@michaelmagan/dnumb 0.1.0

package/dist/snapshot/color.d.cts

@@ -0,0 +1,316 @@
+/**
+ * Color, composited and disclosed -- never adjudicated.
+ *
+ * The design of record is `docs/notes/03-color.md`; this file is stage 1 of
+ * it. Three things carry over from that note verbatim, because they are the
+ * whole shape of the module:
+ *
+ * 1. **The backdrop composite runs Node-side, over `ElementRecord[]`, exactly
+ *    like `clip.ts`.** Both capture paths already produce the raw fields this
+ *    needs (`backgroundColor`, `backgroundImage`, `opacity`, the overlap
+ *    inputs); nothing here touches a page or a browser, so both paths agree
+ *    on every derived color fact by construction.
+ * 2. **`ratio` is a number or it is `unmeasured (<reason>)`. Never a verdict.**
+ *    No output token here ever says `pass`, `fail`, `AA`, `AAA`, `low`, or
+ *    `poor`. §5 of the design note draws this line in four rules; this module
+ *    is the code that holds it.
+ * 3. **A gradient, an image, or a non-ancestor overlay makes "the background
+ *    color" not exist**, and printing a number anyway is fabrication, not
+ *    suppression-avoidance (design note §5's rule 4). `blendedBackgroundColors`
+ *    -- CDP's own composite -- gets this wrong on exactly these two shapes
+ *    (verified in the design note's probes, and again in
+ *    `test/browser/color-backdrop.test.ts`), which is why it is a test oracle
+ *    for the alpha-chain case it gets right and never a source at runtime.
+ *
+ * The color-space conversions (`oklch`/`oklab`/`lab`/`lch`/`color(srgb*
+ * )`/`color(display-p3 ...)`) are verified against real Chromium canvas
+ * readback, not derived from memory of the spec math alone --
+ * `test/browser/color-space-conversion.test.ts` paints each one and diffs
+ * channels, per the design note's own §10 experiment 4.
+ */
+import type { DocumentBackground, ElementRecord } from "./types.cjs";
+/** 0-255 per channel, alpha 0-1. */
+export interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export type ParsedColor = {
+    kind: 'resolved';
+    rgba: RGBA;
+} | {
+    kind: 'verbatim';
+    raw: string;
+};
+/**
+ * Parse a computed-style color string to sRGB, or refuse honestly.
+ *
+ * Every space `docs/notes/03-color.md` §3 calls out as a real capture
+ * problem -- `oklch`, `oklab`, `lab`, `lch`, `color(srgb ...)`,
+ * `color(srgb-linear ...)`, `color(display-p3 ...)` -- converts. Anything
+ * else (a future space, a syntax this parser does not recognise) returns the
+ * raw string verbatim rather than guessing: rule 4 of the design note's §5
+ * applies to color parsing exactly as it does to the ratio itself.
+ */
+export declare function parseCssColor(raw: string): ParsedColor;
+/** `#rrggbb`, or `#rrggbbaa` when `alpha` is given and < 1. */
+export declare function toHex(rgb: {
+    r: number;
+    g: number;
+    b: number;
+}, alpha?: number): string;
+/** WCAG 2.x relative luminance. The name of a formula, never a threshold. */
+export declare function relativeLuminance(rgb: {
+    r: number;
+    g: number;
+    b: number;
+}): number;
+/** WCAG 2.x contrast ratio between two opaque sRGB colors. */
+export declare function contrastRatio(a: {
+    r: number;
+    g: number;
+    b: number;
+}, b: {
+    r: number;
+    g: number;
+    b: number;
+}): number;
+export type Backdrop = {
+    kind: 'opaque';
+    color: string;
+    via: string;
+    self: boolean;
+    layers: number;
+} | {
+    kind: 'gradient';
+    from: string;
+    to: string;
+    via: string;
+} | {
+    kind: 'image';
+    via: string;
+    coverage: ImageCoverage;
+} | {
+    kind: 'overlay';
+    reason: 'under' | 'behind';
+    via: string;
+}
+/**
+ * `via`'s own `backgroundImage` is `null` -- this specific capture never
+ * measured it (A3; see `ElementRecord.backgroundImage`'s doc comment and
+ * `bundle.ts#normalizeElement`). Compositing cannot honestly continue past
+ * an element whose background-image is unknown: it might be a gradient or
+ * a photo sitting behind the text, and there is no way to tell from here.
+ * Refuse to guess, the same discipline `detectOverlay` already applies to
+ * a missing `hitStackIds`/`paintOrder`.
+ */
+ | {
+    kind: 'not-captured';
+    via: string;
+}
+/**
+ * The ancestor walk ran off the top of `<body>` with nothing left to
+ * check, and either no `DocumentBackground` was supplied at all (a caller
+ * that has not been updated to pass one -- see this module's header) or
+ * the one supplied cannot honestly resolve to a single color (an
+ * unconvertible `background-color`, or a `color-scheme` that lists both
+ * `light` and `dark` with no way to know which the reader's browser would
+ * pick). See `canvasBackdrop` and A2.
+ */
+ | {
+    kind: 'canvas';
+};
+/** `<html>`'s own background-color/color-scheme -- see `DocumentBackground`
+ * in `snapshot/types.ts`, and this module's header for why a compositing
+ * walk needs it. Re-exported under this name here because `resolveBackdrop`
+ * et al. take it as a plain, optional parameter (never a required one: every
+ * existing caller that does not yet pass one -- see A2's routing note --
+ * must keep compiling and must keep refusing to guess, never regress to
+ * assuming white). */
+export type CanvasBackground = DocumentBackground;
+/**
+ * The `image` backdrop's weakest signal, strengthened: a real-page soak
+ * found `unmeasured (image <id>)` printing identically for a 12x12 decorative
+ * sort-arrow in one corner of a table header and a 1440x600 full-bleed hero
+ * photo -- an agent cannot tell "irrelevant corner decoration" from
+ * "genuinely unmeasurable backdrop" from the token alone, and would spend a
+ * screenshot round-trip finding out something already on the record.
+ *
+ * `box` is the rendered size of the element that actually carries the
+ * `background-image` (already captured, no new measurement); `of` is the
+ * text element's own box, so `image e_th (12x12 of 180x40)` and
+ * `image e_hero (1440x600 of 1440x600)` read as the different sentences they
+ * are. This is a size proxy, not the image's true painted footprint --
+ * `background-size`/`background-position` can still make a small box show a
+ * cropped, dominant image, or a large box show a small tiled icon -- so it
+ * narrows the question rather than closing it, honestly.
+ */
+export interface ImageCoverage {
+    boxWidth: number;
+    boxHeight: number;
+    ofWidth: number;
+    ofHeight: number;
+}
+/** One layer the ancestor walk actually visited: its own color and alpha, and
+ * the element it came from. Diagnostic detail for `q color <id>`'s long form
+ * ("the full composite chain") -- not needed by the grammar line itself,
+ * which only ever shows the final result plus a layer *count*. */
+export interface BackdropLayer {
+    id: string;
+    color: string;
+    alpha: number;
+}
+export interface ResolvedBackdrop {
+    backdrop: Backdrop;
+    /** The final composited, opaque sRGB color -- `null` whenever `backdrop`
+     * is not a single resolved color (gradient, image, overlay, not-captured,
+     * canvas) or its terminating layer's own color could not be converted. */
+    rgb: {
+        r: number;
+        g: number;
+        b: number;
+    } | null;
+    /** Every layer visited, from `el` itself outward, including the
+     * terminating one (opaque, canvas, or the unresolvable/gradient/image/
+     * not-captured layer that ended the walk). */
+    chain: BackdropLayer[];
+}
+/**
+ * Walk up from `el` accumulating translucent `background-color` layers
+ * *and* CSS `opacity` until something fully opaque is reached, then report
+ * the composited result -- an incremental left-to-right fold rather than
+ * "collect layers, then composite once at the end", specifically so
+ * `opacity` folds in correctly (A5): unlike a plain `background-color`
+ * alpha, `opacity` scales *everything already composited so far* as one
+ * group at the exact point it is applied, so each ancestor's own
+ * contribution has to be resolved against what is beneath it before the
+ * next ancestor's `opacity` scales the combined result again. The pure
+ * `background-color`-only case (no `opacity < 1` anywhere in the chain)
+ * reduces to exactly the old flat-stack composite -- *verified* exact
+ * against Chromium's own `blendedBackgroundColors` on an alpha chain
+ * (`test/browser/color-backdrop.test.ts`) -- and the opacity-aware general
+ * case is verified against real Chromium canvas pixel readback for both a
+ * single opacity boundary and nested multi-level opacity (see this
+ * module's header and `test/browser/color-backdrop.test.ts`'s A5 cases).
+ *
+ * Aborts to a `gradient`/`image`/`not-captured` backdrop the instant any
+ * layer's own `backgroundImage` says so (A3), and to `canvas` when the walk
+ * runs off the top of `<body>` with no way to know the real default fill
+ * (A2, see `canvasBackdrop`). A non-ancestor overlay is checked by the
+ * caller before this ever runs (see `colorFactFor`), since an overlay makes
+ * the ancestor chain irrelevant regardless of what it would have found.
+ */
+export declare function resolveBackdrop(el: ElementRecord, byId: Map<string, ElementRecord>, canvas?: CanvasBackground | null): ResolvedBackdrop;
+/**
+ * A non-ancestor element painted `under` (in front of, obscuring the text
+ * itself) or `behind` (between the text and where the ancestor walk would
+ * have looked) this one -- the two `incompleteData` cases
+ * `blendedBackgroundColors` gets silently wrong (design note §3): a
+ * `rgba(255,0,0,0.8)` sibling scrim painted directly over text reads back as
+ * `rgb(255,255,255)`, the page background, as if the overlay were not there.
+ *
+ * Two independent input signals, one per capture path (design note §7):
+ * `el.hitStackIds` (the `walk` path's `elementsFromPoint` result, already
+ * ordered front-to-back) when present, else `paintOrder` plus rect
+ * intersection (the `cdp` path, Node-side, whole-rect rather than
+ * centre-point). Neither present -- a hand-built fixture, a bundle written
+ * before this capability existed -- reports no overlay rather than guessing:
+ * rule 4 of the design note's §5 (refuse rather than fabricate) applies here
+ * exactly as it does to the ratio itself.
+ */
+export declare function detectOverlay(el: ElementRecord, byId: Map<string, ElementRecord>, elements: ElementRecord[]): {
+    reason: 'under' | 'behind';
+    via: string;
+} | null;
+export type RatioReason = 'gradient' | 'image' | 'under' | 'behind' | 'color-space' | 'not-captured' | 'canvas';
+export interface ColorFact {
+    elementId: string;
+    /** The effective ink: computed `color`, composited at effective opacity,
+     * as lowercase hex (with an alpha suffix below full opacity) -- or the raw
+     * CSS string verbatim when the color space could not be converted. */
+    fg: string;
+    backdrop: Backdrop;
+    /** WCAG 2.x contrast ratio, or `null` when it cannot be honestly computed
+     * -- see `ratioReason`. Never a verdict. */
+    ratio: number | null;
+    ratioReason: RatioReason | null;
+    fontSizePx: number;
+    fontWeight: number;
+    /** The CSS `opacity` multiplier, present only when it is below 1 -- "so the
+     * reader can recover the raw value" (design note §4). */
+    effectiveOpacity: number | null;
+    shadowColor: string | null;
+    strokeWidthPx: number | null;
+    strokeColor: string | null;
+}
+/**
+ * The color fact for one element, or `null` when the measurement gate does
+ * not apply: "every visible element with its own text" (design note §4) --
+ * no text, no ink-on-backdrop question to answer.
+ *
+ * A6 note: a closed `<sl-dialog>` (`opacity: 0` on an ancestor) still gets a
+ * fact here for each visible-by-its-own-styling descendant -- `el.visible`
+ * only reflects the element's *own* opacity/display/visibility/size, not an
+ * ancestor's. That fact's `ratio` genuinely does come out `1.00` (ink
+ * composited to exactly equal its own backdrop at zero *effective* opacity)
+ * -- mathematically correct, not fabricated, and never suppressed here:
+ * "facts, with counter-facts, never adjudicate" means this module does not
+ * get to decide the fact is uninteresting and drop it. `effectiveOpacity`
+ * below is the counter-fact that explains it (`opacity ×0`, kept on
+ * `ColorFact` and, via `ColorPair.effectiveOpacity`, on `q color`'s grouped
+ * rows too -- see that field's doc comment) so a reader sees *why* the
+ * ratio is round, rather than the fact disappearing and the explanation
+ * disappearing with it.
+ */
+export declare function colorFactFor(el: ElementRecord, byId: Map<string, ElementRecord>, elements: ElementRecord[], canvas?: CanvasBackground | null): ColorFact | null;
+/** Every color fact the capture supports, in document order -- the gate from
+ * `colorFactFor` applied once per element. */
+export declare function colorFactsForAll(elements: ElementRecord[], canvas?: CanvasBackground | null): ColorFact[];
+/** Just the `<bg>` half of the grammar -- reused by `q color`'s pair table
+ * and the digest header's `lowest` clause, which both need it without the
+ * rest of the line. */
+export declare function backdropLabel(backdrop: Backdrop): string;
+/**
+ * `color <fg> on <bg>; ratio <r>; <size>px/<weight>[; opacity ×<o>][; shadow
+ * <color>][; stroke <w>px <color>]` -- `docs/notes/03-color.md` §4, exactly.
+ */
+export declare function renderColorFact(fact: ColorFact): string;
+export interface ColorPair {
+    fg: string;
+    bgLabel: string;
+    ratio: number | null;
+    ratioReason: RatioReason | null;
+    elementIds: string[];
+    fontSizesPx: number[];
+    weights: number[];
+    /**
+     * The CSS `opacity` multiplier, present only when it is below 1 -- same
+     * meaning and same "present only below 1" convention as
+     * `ColorFact.effectiveOpacity`, taken from the first fact in the group
+     * exactly like `ratio`/`ratioReason` already are (elements sharing one
+     * (ink, backdrop) pair by construction share the composited result, and
+     * in the overwhelming common case share the same ancestor chain too).
+     *
+     * Added for A6: `q color`'s pair table used to have no way to carry this
+     * at all, so even a caller that *wanted* to show `opacity ×0` (or `×0.5`)
+     * next to a row -- the fact that explains a suspiciously round ratio like
+     * `1.00` on an ancestor-hidden element -- had nothing to read it from off
+     * a `ColorPair` directly. `query.ts`'s own fix for the same gap
+     * (`pairOpacities`) instead recovers the full, deduped set of a pair's
+     * member opacities from the ungrouped facts by `elementIds`, which this
+     * single first-fact value cannot replace when a pair's members disagree
+     * (rare, but possible) -- both are kept: this one for a caller that only
+     * needs "does this pair carry a reduced-opacity member" cheaply, without
+     * re-deriving a `factsById` map of its own.
+     */
+    effectiveOpacity: number | null;
+}
+/**
+ * One row per (ink, backdrop) pair, not per element -- "thousands of
+ * elements compress to dozens of rows" (design note §6). `fg` and the
+ * rendered `<bg>` form together are the grouping key: two elements with the
+ * same ink over the same backdrop are, by construction, the same measured
+ * ratio.
+ */
+export declare function groupColorFacts(facts: ColorFact[]): ColorPair[];

package/dist/snapshot/color.d.ts

@@ -0,0 +1,316 @@
+/**
+ * Color, composited and disclosed -- never adjudicated.
+ *
+ * The design of record is `docs/notes/03-color.md`; this file is stage 1 of
+ * it. Three things carry over from that note verbatim, because they are the
+ * whole shape of the module:
+ *
+ * 1. **The backdrop composite runs Node-side, over `ElementRecord[]`, exactly
+ *    like `clip.ts`.** Both capture paths already produce the raw fields this
+ *    needs (`backgroundColor`, `backgroundImage`, `opacity`, the overlap
+ *    inputs); nothing here touches a page or a browser, so both paths agree
+ *    on every derived color fact by construction.
+ * 2. **`ratio` is a number or it is `unmeasured (<reason>)`. Never a verdict.**
+ *    No output token here ever says `pass`, `fail`, `AA`, `AAA`, `low`, or
+ *    `poor`. §5 of the design note draws this line in four rules; this module
+ *    is the code that holds it.
+ * 3. **A gradient, an image, or a non-ancestor overlay makes "the background
+ *    color" not exist**, and printing a number anyway is fabrication, not
+ *    suppression-avoidance (design note §5's rule 4). `blendedBackgroundColors`
+ *    -- CDP's own composite -- gets this wrong on exactly these two shapes
+ *    (verified in the design note's probes, and again in
+ *    `test/browser/color-backdrop.test.ts`), which is why it is a test oracle
+ *    for the alpha-chain case it gets right and never a source at runtime.
+ *
+ * The color-space conversions (`oklch`/`oklab`/`lab`/`lch`/`color(srgb*
+ * )`/`color(display-p3 ...)`) are verified against real Chromium canvas
+ * readback, not derived from memory of the spec math alone --
+ * `test/browser/color-space-conversion.test.ts` paints each one and diffs
+ * channels, per the design note's own §10 experiment 4.
+ */
+import type { DocumentBackground, ElementRecord } from "./types.js";
+/** 0-255 per channel, alpha 0-1. */
+export interface RGBA {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export type ParsedColor = {
+    kind: 'resolved';
+    rgba: RGBA;
+} | {
+    kind: 'verbatim';
+    raw: string;
+};
+/**
+ * Parse a computed-style color string to sRGB, or refuse honestly.
+ *
+ * Every space `docs/notes/03-color.md` §3 calls out as a real capture
+ * problem -- `oklch`, `oklab`, `lab`, `lch`, `color(srgb ...)`,
+ * `color(srgb-linear ...)`, `color(display-p3 ...)` -- converts. Anything
+ * else (a future space, a syntax this parser does not recognise) returns the
+ * raw string verbatim rather than guessing: rule 4 of the design note's §5
+ * applies to color parsing exactly as it does to the ratio itself.
+ */
+export declare function parseCssColor(raw: string): ParsedColor;
+/** `#rrggbb`, or `#rrggbbaa` when `alpha` is given and < 1. */
+export declare function toHex(rgb: {
+    r: number;
+    g: number;
+    b: number;
+}, alpha?: number): string;
+/** WCAG 2.x relative luminance. The name of a formula, never a threshold. */
+export declare function relativeLuminance(rgb: {
+    r: number;
+    g: number;
+    b: number;
+}): number;
+/** WCAG 2.x contrast ratio between two opaque sRGB colors. */
+export declare function contrastRatio(a: {
+    r: number;
+    g: number;
+    b: number;
+}, b: {
+    r: number;
+    g: number;
+    b: number;
+}): number;
+export type Backdrop = {
+    kind: 'opaque';
+    color: string;
+    via: string;
+    self: boolean;
+    layers: number;
+} | {
+    kind: 'gradient';
+    from: string;
+    to: string;
+    via: string;
+} | {
+    kind: 'image';
+    via: string;
+    coverage: ImageCoverage;
+} | {
+    kind: 'overlay';
+    reason: 'under' | 'behind';
+    via: string;
+}
+/**
+ * `via`'s own `backgroundImage` is `null` -- this specific capture never
+ * measured it (A3; see `ElementRecord.backgroundImage`'s doc comment and
+ * `bundle.ts#normalizeElement`). Compositing cannot honestly continue past
+ * an element whose background-image is unknown: it might be a gradient or
+ * a photo sitting behind the text, and there is no way to tell from here.
+ * Refuse to guess, the same discipline `detectOverlay` already applies to
+ * a missing `hitStackIds`/`paintOrder`.
+ */
+ | {
+    kind: 'not-captured';
+    via: string;
+}
+/**
+ * The ancestor walk ran off the top of `<body>` with nothing left to
+ * check, and either no `DocumentBackground` was supplied at all (a caller
+ * that has not been updated to pass one -- see this module's header) or
+ * the one supplied cannot honestly resolve to a single color (an
+ * unconvertible `background-color`, or a `color-scheme` that lists both
+ * `light` and `dark` with no way to know which the reader's browser would
+ * pick). See `canvasBackdrop` and A2.
+ */
+ | {
+    kind: 'canvas';
+};
+/** `<html>`'s own background-color/color-scheme -- see `DocumentBackground`
+ * in `snapshot/types.ts`, and this module's header for why a compositing
+ * walk needs it. Re-exported under this name here because `resolveBackdrop`
+ * et al. take it as a plain, optional parameter (never a required one: every
+ * existing caller that does not yet pass one -- see A2's routing note --
+ * must keep compiling and must keep refusing to guess, never regress to
+ * assuming white). */
+export type CanvasBackground = DocumentBackground;
+/**
+ * The `image` backdrop's weakest signal, strengthened: a real-page soak
+ * found `unmeasured (image <id>)` printing identically for a 12x12 decorative
+ * sort-arrow in one corner of a table header and a 1440x600 full-bleed hero
+ * photo -- an agent cannot tell "irrelevant corner decoration" from
+ * "genuinely unmeasurable backdrop" from the token alone, and would spend a
+ * screenshot round-trip finding out something already on the record.
+ *
+ * `box` is the rendered size of the element that actually carries the
+ * `background-image` (already captured, no new measurement); `of` is the
+ * text element's own box, so `image e_th (12x12 of 180x40)` and
+ * `image e_hero (1440x600 of 1440x600)` read as the different sentences they
+ * are. This is a size proxy, not the image's true painted footprint --
+ * `background-size`/`background-position` can still make a small box show a
+ * cropped, dominant image, or a large box show a small tiled icon -- so it
+ * narrows the question rather than closing it, honestly.
+ */
+export interface ImageCoverage {
+    boxWidth: number;
+    boxHeight: number;
+    ofWidth: number;
+    ofHeight: number;
+}
+/** One layer the ancestor walk actually visited: its own color and alpha, and
+ * the element it came from. Diagnostic detail for `q color <id>`'s long form
+ * ("the full composite chain") -- not needed by the grammar line itself,
+ * which only ever shows the final result plus a layer *count*. */
+export interface BackdropLayer {
+    id: string;
+    color: string;
+    alpha: number;
+}
+export interface ResolvedBackdrop {
+    backdrop: Backdrop;
+    /** The final composited, opaque sRGB color -- `null` whenever `backdrop`
+     * is not a single resolved color (gradient, image, overlay, not-captured,
+     * canvas) or its terminating layer's own color could not be converted. */
+    rgb: {
+        r: number;
+        g: number;
+        b: number;
+    } | null;
+    /** Every layer visited, from `el` itself outward, including the
+     * terminating one (opaque, canvas, or the unresolvable/gradient/image/
+     * not-captured layer that ended the walk). */
+    chain: BackdropLayer[];
+}
+/**
+ * Walk up from `el` accumulating translucent `background-color` layers
+ * *and* CSS `opacity` until something fully opaque is reached, then report
+ * the composited result -- an incremental left-to-right fold rather than
+ * "collect layers, then composite once at the end", specifically so
+ * `opacity` folds in correctly (A5): unlike a plain `background-color`
+ * alpha, `opacity` scales *everything already composited so far* as one
+ * group at the exact point it is applied, so each ancestor's own
+ * contribution has to be resolved against what is beneath it before the
+ * next ancestor's `opacity` scales the combined result again. The pure
+ * `background-color`-only case (no `opacity < 1` anywhere in the chain)
+ * reduces to exactly the old flat-stack composite -- *verified* exact
+ * against Chromium's own `blendedBackgroundColors` on an alpha chain
+ * (`test/browser/color-backdrop.test.ts`) -- and the opacity-aware general
+ * case is verified against real Chromium canvas pixel readback for both a
+ * single opacity boundary and nested multi-level opacity (see this
+ * module's header and `test/browser/color-backdrop.test.ts`'s A5 cases).
+ *
+ * Aborts to a `gradient`/`image`/`not-captured` backdrop the instant any
+ * layer's own `backgroundImage` says so (A3), and to `canvas` when the walk
+ * runs off the top of `<body>` with no way to know the real default fill
+ * (A2, see `canvasBackdrop`). A non-ancestor overlay is checked by the
+ * caller before this ever runs (see `colorFactFor`), since an overlay makes
+ * the ancestor chain irrelevant regardless of what it would have found.
+ */
+export declare function resolveBackdrop(el: ElementRecord, byId: Map<string, ElementRecord>, canvas?: CanvasBackground | null): ResolvedBackdrop;
+/**
+ * A non-ancestor element painted `under` (in front of, obscuring the text
+ * itself) or `behind` (between the text and where the ancestor walk would
+ * have looked) this one -- the two `incompleteData` cases
+ * `blendedBackgroundColors` gets silently wrong (design note §3): a
+ * `rgba(255,0,0,0.8)` sibling scrim painted directly over text reads back as
+ * `rgb(255,255,255)`, the page background, as if the overlay were not there.
+ *
+ * Two independent input signals, one per capture path (design note §7):
+ * `el.hitStackIds` (the `walk` path's `elementsFromPoint` result, already
+ * ordered front-to-back) when present, else `paintOrder` plus rect
+ * intersection (the `cdp` path, Node-side, whole-rect rather than
+ * centre-point). Neither present -- a hand-built fixture, a bundle written
+ * before this capability existed -- reports no overlay rather than guessing:
+ * rule 4 of the design note's §5 (refuse rather than fabricate) applies here
+ * exactly as it does to the ratio itself.
+ */
+export declare function detectOverlay(el: ElementRecord, byId: Map<string, ElementRecord>, elements: ElementRecord[]): {
+    reason: 'under' | 'behind';
+    via: string;
+} | null;
+export type RatioReason = 'gradient' | 'image' | 'under' | 'behind' | 'color-space' | 'not-captured' | 'canvas';
+export interface ColorFact {
+    elementId: string;
+    /** The effective ink: computed `color`, composited at effective opacity,
+     * as lowercase hex (with an alpha suffix below full opacity) -- or the raw
+     * CSS string verbatim when the color space could not be converted. */
+    fg: string;
+    backdrop: Backdrop;
+    /** WCAG 2.x contrast ratio, or `null` when it cannot be honestly computed
+     * -- see `ratioReason`. Never a verdict. */
+    ratio: number | null;
+    ratioReason: RatioReason | null;
+    fontSizePx: number;
+    fontWeight: number;
+    /** The CSS `opacity` multiplier, present only when it is below 1 -- "so the
+     * reader can recover the raw value" (design note §4). */
+    effectiveOpacity: number | null;
+    shadowColor: string | null;
+    strokeWidthPx: number | null;
+    strokeColor: string | null;
+}
+/**
+ * The color fact for one element, or `null` when the measurement gate does
+ * not apply: "every visible element with its own text" (design note §4) --
+ * no text, no ink-on-backdrop question to answer.
+ *
+ * A6 note: a closed `<sl-dialog>` (`opacity: 0` on an ancestor) still gets a
+ * fact here for each visible-by-its-own-styling descendant -- `el.visible`
+ * only reflects the element's *own* opacity/display/visibility/size, not an
+ * ancestor's. That fact's `ratio` genuinely does come out `1.00` (ink
+ * composited to exactly equal its own backdrop at zero *effective* opacity)
+ * -- mathematically correct, not fabricated, and never suppressed here:
+ * "facts, with counter-facts, never adjudicate" means this module does not
+ * get to decide the fact is uninteresting and drop it. `effectiveOpacity`
+ * below is the counter-fact that explains it (`opacity ×0`, kept on
+ * `ColorFact` and, via `ColorPair.effectiveOpacity`, on `q color`'s grouped
+ * rows too -- see that field's doc comment) so a reader sees *why* the
+ * ratio is round, rather than the fact disappearing and the explanation
+ * disappearing with it.
+ */
+export declare function colorFactFor(el: ElementRecord, byId: Map<string, ElementRecord>, elements: ElementRecord[], canvas?: CanvasBackground | null): ColorFact | null;
+/** Every color fact the capture supports, in document order -- the gate from
+ * `colorFactFor` applied once per element. */
+export declare function colorFactsForAll(elements: ElementRecord[], canvas?: CanvasBackground | null): ColorFact[];
+/** Just the `<bg>` half of the grammar -- reused by `q color`'s pair table
+ * and the digest header's `lowest` clause, which both need it without the
+ * rest of the line. */
+export declare function backdropLabel(backdrop: Backdrop): string;
+/**
+ * `color <fg> on <bg>; ratio <r>; <size>px/<weight>[; opacity ×<o>][; shadow
+ * <color>][; stroke <w>px <color>]` -- `docs/notes/03-color.md` §4, exactly.
+ */
+export declare function renderColorFact(fact: ColorFact): string;
+export interface ColorPair {
+    fg: string;
+    bgLabel: string;
+    ratio: number | null;
+    ratioReason: RatioReason | null;
+    elementIds: string[];
+    fontSizesPx: number[];
+    weights: number[];
+    /**
+     * The CSS `opacity` multiplier, present only when it is below 1 -- same
+     * meaning and same "present only below 1" convention as
+     * `ColorFact.effectiveOpacity`, taken from the first fact in the group
+     * exactly like `ratio`/`ratioReason` already are (elements sharing one
+     * (ink, backdrop) pair by construction share the composited result, and
+     * in the overwhelming common case share the same ancestor chain too).
+     *
+     * Added for A6: `q color`'s pair table used to have no way to carry this
+     * at all, so even a caller that *wanted* to show `opacity ×0` (or `×0.5`)
+     * next to a row -- the fact that explains a suspiciously round ratio like
+     * `1.00` on an ancestor-hidden element -- had nothing to read it from off
+     * a `ColorPair` directly. `query.ts`'s own fix for the same gap
+     * (`pairOpacities`) instead recovers the full, deduped set of a pair's
+     * member opacities from the ungrouped facts by `elementIds`, which this
+     * single first-fact value cannot replace when a pair's members disagree
+     * (rare, but possible) -- both are kept: this one for a caller that only
+     * needs "does this pair carry a reduced-opacity member" cheaply, without
+     * re-deriving a `factsById` map of its own.
+     */
+    effectiveOpacity: number | null;
+}
+/**
+ * One row per (ink, backdrop) pair, not per element -- "thousands of
+ * elements compress to dozens of rows" (design note §6). `fg` and the
+ * rendered `<bg>` form together are the grouping key: two elements with the
+ * same ink over the same backdrop are, by construction, the same measured
+ * ratio.
+ */
+export declare function groupColorFacts(facts: ColorFact[]): ColorPair[];