@invarn/cibuild 2.9.6 → 2.9.8

package/dist/src/yaml/steps/structural-facts.d.ts

@@ -1,992 +0,0 @@
-/**
- * Structural-facts deriver — Signal A of the UI-fidelity structural pass.
- *
- * Pure and platform-agnostic: it takes a per-node layout dump (clipped +
- * unclipped bounds in px, parent) emitted alongside the render and derives
- * intent-agnostic geometric facts the fidelity judge should check instead of
- * discovering them by eye:
- *
- *   - `overflow`          — a node extends past its parent's box (parent does
- *                           NOT clip, so the excess is visibly sticking out).
- *   - `clipped_by_parent` — a node extends past a CLIPPING parent's box, so the
- *                           excess is cut away (the motivating euro-coin case).
- *   - `off_screen`        — a node extends past the root canvas.
- *   - `overlap`           — two siblings overlap by a significant area.
- *
- * The deriver does NOT judge or score; it reports facts. The verdict stays the
- * agent's. This is the brain of Signal A; the render-side emission + facts
- * artifact wiring live in the render step (a separate slice).
- */
-export interface LayoutBounds {
-    left: number;
-    top: number;
-    right: number;
-    bottom: number;
-}
-export interface LayoutNode {
-    /** Stable id/label for the node within one dump. */
-    id: string;
-    /** Clipped root-space bounds in px (boundsInRoot — the visible region,
-     *  clamped by any clipping ancestor). */
-    bounds: LayoutBounds;
-    /** Unclipped root-space bounds in px (positionInRoot + size — the true layout
-     *  extent). Absent in legacy dumps emitted before the structural pass tracked
-     *  it; when present, overflow/clip is derived from this so it survives a
-     *  clamping parent (which would otherwise hide the excess in `bounds`). */
-    unclippedBounds?: LayoutBounds;
-    /** Parent node id, or null for a root node. */
-    parentId: string | null;
-    /** Legacy clip hint (parent clips its children). The current emitter writes a
-     *  constant false; used only for the legacy (no-`unclippedBounds`) fallback. */
-    clipsChildren: boolean;
-    /** Accessible text content. */
-    text?: string;
-    /** Fill (background) color, hex. */
-    fillColor?: string;
-    /** Text (foreground) color, hex. */
-    textColor?: string;
-    /** Fill alpha 0..1 (issue 14b), present only when the render painted the fill
-     *  TRANSLUCENT — omitted at full opacity, exactly like the design side, so
-     *  absence means opaque on both sides. Older harnesses omit it always. */
-    fillAlpha?: number;
-    /** Text alpha 0..1 (issue 14b), same convention as `fillAlpha`. */
-    textAlpha?: number;
-    /** Border (ring) colour, hex — the design's `stroke` (property-recognizer 01),
-     *  read from the layout node's `Modifier.border(...)` element. Absent when the
-     *  node has no border OR has one this read cannot measure (a gradient brush),
-     *  so absence alone is not "no border" — that is what `styleChannels` on the
-     *  dump is for. */
-    borderColor?: string;
-    /** Border thickness in DP (the harness reads `Dp.value`), so unlike `bounds`
-     *  it is NOT divided by density. Emitted together with `borderColor` or not at
-     *  all: half a measurement compared against a whole design value is how a
-     *  wrong number ships. */
-    borderWidth?: number;
-    /** AnnotatedString background-span extents (issue 16): each range of the
-     *  node's text drawn with a specified span background — the highlighted
-     *  substrings. Offsets index into `text`. Absent in dumps from packages
-     *  generated before the emitter tracked spans, and on spanless text — no
-     *  signal, never a divergence. */
-    textSpans?: TextSpan[];
-    /** Laid-out line extents (issue 18): where the node's text ACTUALLY wrapped,
-     *  read from the render's TextLayoutResult — one entry per laid-out line,
-     *  with a VISIBLE end (trailing whitespace and the newline excluded).
-     *  Offsets index into `text`. Absent in dumps from packages generated
-     *  before the emitter tracked lines, and on nodes that lay out no text —
-     *  no signal, never a divergence. */
-    textLines?: TextLine[];
-    /** The RESOLVED typeface (typeface facts, issue 03): the font that ACTUALLY
-     *  painted this node's text, post-fallback — NOT the requested
-     *  TextStyle.fontFamily, which still reads "correct" during a runtime
-     *  fallback (the incident class the typeface fact exists to catch). Captured
-     *  via per-glyph shaping (TextRunShaper, API 31+). Absent in dumps from
-     *  packages generated before the emitter tracked it, on non-text nodes, and
-     *  whenever the capture could not resolve — no signal, never a divergence. */
-    resolvedTypeface?: TypefaceSpec;
-    /** The TYPE METRICS this node's text was laid out with (typography facts 01),
-     *  in sp: the layout input's own style, which is the style that produced the
-     *  layout. A separate field from `resolvedTypeface` on purpose — that capture
-     *  needs per-glyph shaping (API 31+) and is frequently absent, while these are
-     *  read straight off a style, so coupling them would make a size uncomparable
-     *  on every proof that renders below the shaping seam.
-     *
-     *  Absent on non-text nodes, in dumps from packages generated before the
-     *  emitter tracked it, and PER METRIC when the style declares one in anything
-     *  but sp — no signal, never a divergence. */
-    typeMetrics?: TypeMetrics;
-    /** What the node PAINTS, as distinct from the box it occupies. `Icon(N.dp)`
-     *  paints `N × (path bounds ÷ viewport)` — 62.5% for a typical close glyph —
-     *  while a design reference's key for an icon is its vector PATH box, which is
-     *  pure ink. Without this the two are compared as if they measured the same
-     *  thing. In the drawable's own viewport units: converting to dp needs the
-     *  rendered box, which the consumer holds. Absent in dumps from packages
-     *  generated before the emitter tracked it, and on nodes that paint no painter
-     *  — their layout box IS the measurement. */
-    paintedInk?: PaintedInk;
-}
-/** A node's painted extent, in its drawable's viewport units.
- *
- *  `unmeasurable` is a distinct claim from absence: it says the node paints
- *  SOMETHING whose extent could not be derived (a bitmap painter, a transformed
- *  or clipped vector group), so a consumer knows it is comparing a container
- *  against ink rather than assuming it is not. */
-export type PaintedInk = {
-    kind: 'vector';
-    viewport: {
-        w: number;
-        h: number;
-    };
-    /** The ink's extent AND, since icon-ink-ratio 02 Half B, its ORIGIN in the
-     *  same viewport units. `x`/`y` are optional because every dump written
-     *  before the origin was captured carries the extent alone — a consumer that
-     *  needs placement must treat their absence as "unknown", never as (0,0) or
-     *  as centred. */
-    ink: {
-        w: number;
-        h: number;
-        x?: number;
-        y?: number;
-    };
-} | {
-    kind: 'unmeasurable';
-    why: string;
-};
-/** One styled extent of a text node (an AnnotatedString span style with a
- *  specified background and/or a specified foreground color). */
-export interface TextSpan {
-    start: number;
-    end: number;
-    text: string;
-    /** Span background color, hex. */
-    background?: string;
-    /** Span foreground (text) color, hex — partial-color emphasis. */
-    color?: string;
-}
-/** One laid-out line of a text node (issue 18). */
-export interface TextLine {
-    start: number;
-    end: number;
-    text: string;
-}
-export interface LayoutDump {
-    /** The captured canvas / root bounds in px. */
-    canvas: LayoutBounds;
-    nodes: LayoutNode[];
-    /** The Android SDK the proof rendered at (Robolectric testOptions.targetSdk),
-     *  declared by the emitter. The typeface capture seam (TextRunShaper) is API
-     *  31+, so a dump from an older render SDK cannot carry `resolvedTypeface` —
-     *  consumers use this to advise "typeface not checked" instead of silently
-     *  passing. Absent in dumps emitted before the field existed. */
-    renderSdk?: number;
-    /** The span channels this dump's emitter can report ("background",
-     *  "color"). Absent in dumps emitted before foreground-color spans
-     *  existed — their silence on the color channel is "cannot see", never
-     *  "no color span rendered", so the span compare only derives color-span
-     *  facts when the marker includes "color". */
-    spanChannels?: string[];
-    /** The STYLE channels this dump's emitter can report ("border").
-     *  Absent in dumps emitted before border capture existed, and load-bearing in
-     *  that case: their silence means "cannot see a border", NOT "the render has no
-     *  border". The border compare therefore withholds the ABSENCE case entirely
-     *  without this marker and the caller advises "not checked" — reading it the
-     *  other way would put a finding on every stroked design in the catalogue
-     *  (property-recognizer 01). */
-    styleChannels?: string[];
-}
-export type Edge = 'left' | 'top' | 'right' | 'bottom';
-export type StructuralFact = {
-    kind: 'overflow';
-    nodeId: string;
-    parentId: string;
-    edges: Edge[];
-    overflowPx: Partial<Record<Edge, number>>;
-} | {
-    kind: 'clipped_by_parent';
-    nodeId: string;
-    clipperId: string;
-    edges: Edge[];
-    clippedPx: Partial<Record<Edge, number>>;
-} | {
-    kind: 'off_screen';
-    nodeId: string;
-    edges: Edge[];
-    offscreenPx: Partial<Record<Edge, number>>;
-} | {
-    kind: 'overlap';
-    nodeIds: [string, string];
-    overlapPx: {
-        width: number;
-        height: number;
-    };
-    ratio: number;
-} | {
-    /** Composition runs only (design-frame anchor): the captured wrapper
-     *  root's dp size differs from the declared design frame — an authoring
-     *  problem with the wrapper, never a defect of the screen. While this
-     *  fact is present, placement facts are withheld for the State
-     *  (`StructuralBlock.placement`), so a mis-sized root can never
-     *  masquerade as placement drift. */
-    kind: 'frame_mismatch';
-    declared: {
-        w: number;
-        h: number;
-    };
-    captured: {
-        w: number;
-        h: number;
-    };
-    deltas: Array<{
-        dimension: 'w' | 'h';
-        delta: number;
-    }>;
-} | {
-    /** One testTag shared by `instanceCount` nodes in the dump — an authoring
-     *  problem with the wrapper, never a defect of the screen. Every id
-     *  lookup (parent pairing, geometry, placement) is last-wins for a
-     *  duplicated tag, so facts derived through it would compare arbitrary
-     *  instances; they are WITHHELD rather than guessed while this fact is
-     *  present, mirroring the `frame_mismatch` withhold pattern. */
-    kind: 'duplicate_tag';
-    tag: string;
-    instanceCount: number;
-};
-/** The declared design frame for one screen (design px, treated 1:1 with dp —
- *  same convention as `ReferenceGeometry`). Composition runs declare one per
- *  State via `params.reference_frame`; component runs never pass it. */
-export interface ReferenceFrame {
-    w: number;
-    h: number;
-}
-/** One member root whose position on the surface diverges from the design
- *  frame beyond tolerance (composition runs only): `expected` is the declared
- *  design x/y (design px, 1:1 dp), `actual` the rendered root-space dp —
- *  directly comparable because the root is frame-sized (asserted). Only the
- *  out-of-tolerance dimensions appear in `deltas`. */
-export interface PlacementFact {
-    elementId: string;
-    expected: {
-        x: number;
-        y: number;
-    };
-    actual: {
-        x: number;
-        y: number;
-    };
-    deltas: Array<{
-        dimension: 'x' | 'y';
-        delta: number;
-    }>;
-}
-/** Placement drift at or below this many dp is sub-pixel/rounding noise, not
- *  a misplacement — same reasoning as the size-delta floor. */
-export declare const DEFAULT_PLACEMENT_TOLERANCE_DP = 2;
-/** Placement-fact gate for one State (composition runs only): present when a
- *  design frame was declared and asserted against the captured root. When the
- *  root mis-matches the frame, placement facts are WITHHELD (`withheld: true`,
- *  with the reason, no `facts`) — the placement deriver must not compute drift
- *  against a wrongly-sized canvas. When the root matches, `facts` carries the
- *  tolerance-banded member-root x/y divergences (empty = placement holds). */
-export interface StructuralPlacement {
-    withheld: boolean;
-    reason?: 'frame_mismatch';
-    facts?: PlacementFact[];
-}
-/** Captured-root vs declared-frame tolerance (dp): sub-pixel rounding must not
- *  read as a mis-sized wrapper root. */
-export declare const DEFAULT_FRAME_TOLERANCE_DP = 1;
-export interface DeriveStructuralFactsOptions {
-    /** Edge excesses / overlaps at or below this many px are ignored, so that
-     *  exact-touching layout edges don't read as overflow or overlap. */
-    tolerancePx?: number;
-    /** Minimum (intersection area / smaller node area) for an overlap to be
-     *  reported as significant. */
-    overlapMinRatio?: number;
-}
-/**
- * Node ids that appear on MORE THAN ONE node of the dump (testTag collisions),
- * mapped to their instance count. Every id-keyed lookup (parent pairing,
- * geometry, placement) is last-wins for such an id, so facts derived through it
- * would compare arbitrary instances — consumers withhold them and report the
- * collision as a `duplicate_tag` fact instead.
- */
-export declare function duplicatedNodeIds(nodes: readonly LayoutNode[]): Map<string, number>;
-export declare function deriveStructuralFacts(dump: LayoutDump, options?: DeriveStructuralFactsOptions): StructuralFact[];
-/** One element's geometry; x/y optional (position is advisory, see ADR-0004). */
-export interface ElementGeometry {
-    width: number;
-    height: number;
-    x?: number;
-    y?: number;
-}
-export type GeometrySource = Record<string, ElementGeometry>;
-export interface DimensionDelta {
-    dimension: 'width' | 'height' | 'x' | 'y';
-    generated: number;
-    reference: number;
-    delta: number;
-}
-export interface GeometryDelta {
-    elementId: string;
-    deltas: DimensionDelta[];
-}
-/**
- * Per-element dimensional deltas between a GENERATED geometry (render layout) and
- * a REFERENCE geometry (design numbers), both in the same unit. Only elements
- * present on both sides, and only dimensions supplied on both, are compared.
- * Port of `packages/cli/lib/fidelity-geometry-diff.mjs`.
- */
-export declare function diffKeyGeometry(generated: GeometrySource, reference: GeometrySource | null | undefined, options?: {
-    tolerancePx?: number;
-}): GeometryDelta[];
-/** `params.reference_geometry["<Screen>"]` — design px, treated 1:1 with dp. */
-export type ReferenceGeometry = Record<string, {
-    w?: number;
-    h?: number;
-    x?: number;
-    y?: number;
-}>;
-/**
- * Per-edge overhang of an element that overflows its frame (Signal B v2). For a
- * clipping element the load-bearing invariant is its overhang per edge (= the
- * clip), NOT its raw w/h: width can match and the clip still be wrong. Frame-
- * relative edge overhang is the real clip, so it IS flagged — unlike absolute
- * canvas x/y, which stays suppressed as a canvas-width artifact.
- *
- *   rendered[edge] = element's unclipped edge − frame's edge (dp)
- *   design[edge]   = design element edge − design frame edge (from reference_geometry)
- *   deltas         = edges where |rendered − design| > overhangTolerance
- *   clipFlag       = any delta present
- */
-export interface StructuralOverhang {
-    unit: 'dp';
-    rendered: Partial<Record<Edge, number>>;
-    design: Partial<Record<Edge, number>>;
-    deltas: Array<{
-        edge: Edge;
-        delta: number;
-    }>;
-    clipFlag: boolean;
-    /** The clip delta is explained by the element's OWN size being wrong on the
-     *  clip axis (a size delta, not the design's intended clip). */
-    sizeDriven: boolean;
-    /** …and that wrong size matches the frame's size — the parent-relative
-     *  (`fillMaxHeight`/`matchParentSize`) signature. The fix is a fixed size. */
-    frameRelative: boolean;
-    /** The clip delta is explained by the element's frame-relative POSITION on the
-     *  clip axis being wrong (an offset, not a size). Frame-relative position is NOT
-     *  the suppressed absolute-x/y canvas artifact — it changes the real clip. */
-    positionDriven: boolean;
-}
-export interface StructuralGeometryElement {
-    id: string;
-    rendered?: {
-        w: number;
-        h: number;
-        x: number;
-        y: number;
-    };
-    design?: {
-        w: number | undefined;
-        h: number | undefined;
-        x?: number;
-        y?: number;
-    };
-    deltas?: Array<{
-        dimension: 'w' | 'h' | 'x' | 'y';
-        delta: number;
-    }>;
-    sizeFlag?: boolean;
-    /** Present only when the element overflows its (declared) frame. */
-    overhang?: StructuralOverhang;
-    /** What the element PAINTS (see `LayoutNode.paintedInk`), passed through from
-     *  the dump so the judge can compare ink to ink instead of a container to
-     *  ink. Absent for anything that paints no painter, and for every render made
-     *  before the emitter tracked it. */
-    paintedInk?: PaintedInk;
-    /**
-     * The element's render ancestry: every ancestor node id from its IMMEDIATE
-     * parent up to the root (icon-ink-ratio 05). The dump's `parentId` links are
-     * consumed here for sibling grouping and were dropped, so the judge could not
-     * see the render's tree at all — and an element the wrapper nested in the wrong
-     * container had no finding of its own.
-     *
-     * The CHAIN rather than the parent link, because Compose's semantics tree omits
-     * untagged layout nodes: a declared key routinely sits several levels below the
-     * container it should be compared against, and an immediate parent alone cannot
-     * see past the gap. Measured over three gated screens, the parent link produces
-     * 21 false rows where the chain produces 2.
-     *
-     * An EMPTY array is a root node — a measurement, distinguishable from the
-     * ABSENT field of every render made before this shipped.
-     */
-    ancestors?: string[];
-}
-export interface StructuralGeometry {
-    unit: 'dp';
-    density: number;
-    elements: StructuralGeometryElement[];
-}
-export interface StructuralSummary {
-    clean: boolean;
-    factCount: number;
-    maxSizeDeltaDp: number | null;
-    /** Largest |overhang delta| in dp, or null when there is no geometry. */
-    maxClipDeltaDp: number | null;
-}
-export interface StructuralBlock {
-    summary: StructuralSummary;
-    facts: StructuralFact[];
-    geometry?: StructuralGeometry;
-    appearance?: StructuralAppearance;
-    /** Composition runs only — see `StructuralPlacement`. */
-    placement?: StructuralPlacement;
-}
-/** Which reference the appearance facts were diffed against. `previous_render`
- *  facts are regressions/drift, NOT design divergences (the no-Figma path). */
-export type AppearanceBaseline = 'figma' | 'previous_render';
-export type AppearanceFact = {
-    kind: 'color';
-    elementId: string;
-    channel: 'fill' | 'text';
-    rendered: string;
-    reference: string;
-    /** CIEDE2000 perceptual distance — measurement only, no significance. */
-    deltaE: number;
-} | {
-    /** The channel's OPACITY differs from the design's (issue 14b). Its own
-     *  kind, not a `color` one: the hex can match exactly while the design
-     *  paints the element at 30% (disabled) and the render at 100% (enabled),
-     *  and a matching hex gives deltaE 0, which would never flag. */
-    kind: 'color_alpha';
-    elementId: string;
-    channel: 'fill' | 'text';
-    rendered: number;
-    reference: number;
-}
-/** The design declares a STROKE the render drew no border for at all
- *  (property-recognizer 01). The motivating case: an 18dp badge with a 4dp
- *  white ring inside it, rendered as a plain green blob, about which the gate
- *  said nothing because no harness captured a border. Emitted ONLY from a dump
- *  that declares border capability (`styleChannels`) — an older emitter's
- *  silence is "cannot see a border", never "no border was drawn". */
- | {
-    kind: 'border_missing';
-    elementId: string;
-    reference: string;
-    referenceWidth?: number;
-}
-/** A drawn border whose COLOUR differs from the design's stroke. */
- | {
-    kind: 'border';
-    elementId: string;
-    rendered: string;
-    reference: string;
-}
-/** A drawn border of the right colour and the wrong THICKNESS, in dp. Its own
- *  kind so a correctly-coloured ring is never reported as a colour problem. */
- | {
-    kind: 'border_width';
-    elementId: string;
-    rendered: number;
-    reference: number;
-} | {
-    kind: 'text_mismatch';
-    elementId: string;
-    rendered: string;
-    reference: string;
-} | {
-    kind: 'text_missing';
-    elementId: string;
-    reference: string;
-}
-/** The highlighted extent (an AnnotatedString background span) differs from
- *  the declared reference span (issue 16). `rendered` is what the render
- *  actually highlighted (all span extents, comma-joined); `reference` the
- *  substring the design highlights. */
- | {
-    kind: 'span_mismatch';
-    elementId: string;
-    rendered: string;
-    reference: string;
-}
-/** The styled segment's FOREGROUND COLOR differs from the declared span
- *  color (partial-color emphasis): the extent matched, the emphasis painted
- *  the wrong color. `rendered`/`reference` are hex; `extent` names the
- *  segment. Derived only from a dump that DECLARES it can report color
- *  spans (`spanChannels`) — an old emitter's silence is never a fact. */
- | {
-    kind: 'span_color_mismatch';
-    elementId: string;
-    extent?: string;
-    rendered: string;
-    reference: string;
-}
-/** The laid-out line split differs from the declared reference split
- *  (issue 18): the text wrapped on the wrong word, or dropped/added a
- *  break. `rendered`/`reference` carry the newline-joined line texts. */
- | {
-    kind: 'line_break_mismatch';
-    elementId: string;
-    rendered: string;
-    reference: string;
-}
-/** The RESOLVED typeface (what actually painted, post-fallback) diverges from the
- *  design typeface in family or weight. `rendered` is the font that resolved on
- *  the render (e.g. a Roboto fallback); `reference` is the design font. The crux
- *  is "resolved, not requested": a runtime fallback reads correct at the
- *  TextStyle.fontFamily layer, so the requested family can never be the signal. */
- | {
-    kind: 'typeface';
-    elementId: string;
-    channel: 'text';
-    rendered: TypefaceSpec;
-    reference: TypefaceSpec;
-}
-/** ONE type metric — size, tracking or leading — diverges from the design, in
- *  sp (typography facts 01).
- *
- *  One fact PER METRIC rather than one carrying all three: downstream finding
- *  identity is `screen + element + category`, so two metrics folded into a
- *  single fact would collapse into one finding and silently drop the other —
- *  and the motivating case diverged in TWO of them at once (18sp against 16sp,
- *  with −0.6 tracking). A separate fact per metric is what keeps both
- *  reportable.
- *
- *  Emitted only when BOTH sides declare the metric: a design that says nothing
- *  about tracking is not asserting 0. */
- | {
-    kind: 'type_metric';
-    elementId: string;
-    channel: 'text';
-    metric: TypeMetricKey;
-    rendered: number;
-    reference: number;
-}
-/** In the reference, not rendered. */
- | {
-    kind: 'element_missing';
-    elementId: string;
-}
-/** Rendered, not in the reference. */
- | {
-    kind: 'element_extra';
-    elementId: string;
-};
-/** A resolved or design typeface: a font `family` plus a numeric `weight`
- *  (100–900, CSS/OpenType scale). `weight` is optional because a design
- *  annotation may name only a family (the weight is then derived from a
- *  weight-suffix token on the family, or defaults to 400 Regular). */
-export interface TypefaceSpec {
-    family: string;
-    weight?: number;
-    /** Design-side type metrics in sp (typography facts 01), carried on the same
-     *  reference entry as the family because they arrive on the same channel and
-     *  describe the same thing: the type. The RENDERED side keeps them in its own
-     *  map (`DumpNode.typeMetrics`), because its family capture has an API floor
-     *  these do not. Each is absent when the design declares no value for it. */
-    fontSize?: number;
-    letterSpacing?: number;
-    lineHeight?: number;
-}
-/** The metrics a text node was laid out with, in sp. Every field optional: a
- *  style may declare a size and no tracking, and a metric declared in Em or left
- *  Unspecified is omitted rather than converted — it is not comparable against a
- *  design that declares absolute sp. */
-export interface TypeMetrics {
-    fontSize?: number;
-    letterSpacing?: number;
-    lineHeight?: number;
-}
-/** The metrics a `type_metric` fact can report, in the order a finding reads
- *  them: the size first (it explains the others), then tracking, then leading. */
-export declare const TYPE_METRIC_KEYS: readonly ["fontSize", "letterSpacing", "lineHeight"];
-export type TypeMetricKey = (typeof TYPE_METRIC_KEYS)[number];
-/**
- * A reference-shaped snapshot of the render's OWN appearance — the element-id
- * set plus per-element text/colors it produced. Persisted in the structural
- * block so a later no-Figma render can use it as the `previous_render` baseline
- * (the colors/text/ids to diff against), mirroring how Signal B's geometry
- * baseline reuses the previous render's persisted `geometry`. text/color are
- * present only for the elements that exposed them.
- */
-export interface AppearanceRendered {
-    elementIds: string[];
-    text?: TextSource;
-    color?: ColorSource;
-    /** The resolved typeface per element (issue 03) — what actually painted,
-     *  post-fallback. Persisted so it serves as the previous-render typeface
-     *  drift baseline. */
-    typeface?: TypefaceSource;
-}
-export interface StructuralAppearance {
-    baseline: AppearanceBaseline;
-    facts: AppearanceFact[];
-    /** The render's own appearance, persisted as the baseline source for the next
-     *  no-Figma render. Present whenever Signal C ran. */
-    rendered?: AppearanceRendered;
-    /** Signals a check that could NOT run (never a silent pass): e.g. a typeface
-     *  reference was supplied but the proof rendered below SDK 31, where the
-     *  resolved-typeface capture seam does not exist. Standard CI vocabulary
-     *  (LLM-facing). Absent when every requested check ran. */
-    advisories?: string[];
-}
-/**
- * The reference side of the appearance diff, passed into `buildStructuralBlock`.
- * `elementIds` is the reference element-id set (Figma node ids on the `figma`
- * baseline; the previous render's element ids on `previous_render`). This slice
- * derives presence only; the copy/color slices extend this with reference text /
- * colors keyed by element id.
- */
-export interface AppearanceReference {
-    baseline: AppearanceBaseline;
-    elementIds: string[];
-    /** Reference text per element id (Figma `characters` on the figma baseline; the
-     *  previous render's text on `previous_render`). When supplied, copy facts are
-     *  derived against the render's per-node text. Absent → presence facts only. */
-    text?: TextSource;
-    /** Reference fill/text color per element id (Figma `fills` on the figma
-     *  baseline; the previous render's colors on `previous_render`). When supplied,
-     *  color facts are derived against the render's per-node colors. */
-    color?: ColorSource;
-    /** Declared highlight extents per element id (issue 16): the substring the
-     *  design highlights on that text element (and optionally its background).
-     *  When supplied, span facts are derived against the render's per-node
-     *  `textSpans`. */
-    spans?: SpanSource;
-    /** Declared line splits per element id (issue 18): the exact line texts
-     *  the design breaks that text element into. When supplied, line facts
-     *  are derived against the render's per-node `textLines`. */
-    lines?: LineSource;
-    /** Reference typeface per element id (the DESIGN font from Figma node
-     *  metadata on the figma baseline; the previous render's resolved font on
-     *  `previous_render`). When supplied, typeface facts are derived against the
-     *  render's per-node `resolvedTypeface`. */
-    typeface?: TypefaceSource;
-}
-/** The per-screen reference params the runner assembles an `AppearanceReference`
- *  from (the slices of `params.reference_*` for one screen). */
-export interface AppearanceReferenceParams {
-    /** Per-screen `reference_geometry` (design/baseline geometry). Its keys seed
-     *  the element-id set. */
-    refGeom?: ReferenceGeometry | null;
-    /** Per-screen `reference_text` (text per element id). */
-    refText?: TextSource | null;
-    /** Per-screen `reference_color` (fill/text color per element id). */
-    refColor?: ColorSource | null;
-    /** Per-screen `reference_spans` (declared highlight extents per element id). */
-    refSpans?: SpanSource | null;
-    /** Per-screen `reference_lines` (declared line split per element id). */
-    refLines?: LineSource | null;
-    /** Per-screen `reference_typeface` (the DESIGN font per element id, built by
-     *  the caller from Figma node metadata — typeface issue 04). */
-    refTypeface?: TypefaceSource | null;
-    baseline: AppearanceBaseline;
-}
-/**
- * Assemble the `AppearanceReference` from a screen's reference params. Issue 05
- * decouples the appearance container from `reference_geometry`: the reference is
- * built when ANY of geometry / text / color is present, with `elementIds` = the
- * UNION of their keys (geometry first, then text, then color — deduped, order
- * preserved). So a run carrying `reference_color` but no `reference_geometry` now
- * yields a reference (→ color facts), while a geometry-only run is byte-identical
- * to before (color/text keys are a subset). `text`/`color` are attached only when
- * present. No reference of any kind → null (no appearance container).
- */
-export declare function buildAppearanceReferenceFromParams(params: AppearanceReferenceParams): AppearanceReference | null;
-/**
- * Map a previous catalog render's persisted appearance snapshot
- * (`StructuralAppearance.rendered` — element ids + per-element colors) into the
- * `previous_render` AppearanceReference the next render diffs against. The
- * no-Figma drift path: the colors/ids the next render compares itself to are the
- * LAST render's, so a diverging fill surfaces as a regression (drift), marked
- * `baseline: 'previous_render'`, distinct from a design divergence.
- *
- * Pure (no I/O) — the testable core the thin catalog-fetch adapter wraps,
- * mirroring how the geometry baseline reuses the previous render's persisted
- * `geometry`. `color` is carried only when the previous render exposed colors;
- * a previous render with no extractable color yields a presence-only reference
- * (element ids, no color). A genuinely absent previous render (no snapshot) →
- * null, so the next render carries no appearance container, exactly as before.
- * `color` (issue 01/02) and `text` (issue 03) are each carried only when the
- * previous render exposed them; an empty map is no signal on that axis.
- */
-export declare function appearanceReferenceFromPreviousRender(previous: AppearanceRendered | null | undefined): AppearanceReference | null;
-/**
- * Element-presence facts from the set difference of the rendered element-id set
- * and the reference element-id set, keyed on the stable element id shared with
- * Signal B. An id present in the reference but not rendered is `element_missing`;
- * an id rendered but not in the reference is `element_extra`.
- *
- * Pure and platform-agnostic: it takes two id collections and is order-
- * independent — the result depends only on the two SETS, not on input order or
- * duplicates. Output is sorted (missing before extra, each by id) so callers get
- * a deterministic list. The deriver reports facts only; significance is a later,
- * separately-wired concern.
- */
-export declare function derivePresenceFacts(renderedIds: Iterable<string>, referenceIds: Iterable<string>): AppearanceFact[];
-/** Per-element text content, keyed on the stable element id (rendered text from
- *  the layout dump's per-node `text`; reference text from the Figma node tree's
- *  `characters`). A missing or empty string means "no text signal for that
- *  element," which the deriver treats as absence, never a divergence. */
-export type TextSource = Record<string, string | undefined>;
-/**
- * Copy/text facts from the per-element comparison of rendered text vs reference
- * text, keyed on the stable element id shared with Signal B. For each element the
- * REFERENCE declares text for: identical text → no fact; a different rendered
- * string → `text_mismatch` (both strings attached); empty/absent rendered text →
- * `text_missing`. An element with no reference text signal produces no fact —
- * absence of a signal is never reported as a divergence, so a rendered string the
- * reference never declared is silent.
- *
- * Pure and platform-agnostic; order-independent and deterministic (output sorted
- * by element id). The deriver reports facts only; significance is a later,
- * separately-wired concern.
- */
-export declare function deriveCopyFacts(rendered: TextSource, reference: TextSource): AppearanceFact[];
-/** Declared highlight extent per element id: the substring the design
- *  highlights on that text element (an AnnotatedString background span),
- *  optionally with its background color. A missing/empty `text` is "no span
- *  signal for that element" — never a divergence. */
-export type SpanSource = Record<string, {
-    text?: string;
-    background?: string;
-    color?: string;
-} | undefined>;
-/** The rendered highlight extents per element id — each node's `textSpans`
- *  from the layout dump. `undefined` for a node that emitted no spans (an
- *  old package, or a spanless text): no signal, never a divergence. */
-export type RenderedSpans = Record<string, TextSpan[] | undefined>;
-/**
- * Span facts (issue 16 + color spans) from the per-element comparison of
- * rendered styled extents vs the declared reference span, keyed on the stable
- * element id. Channel-scoped: a `background` declaration (highlight chip)
- * compares against background-carrying rendered spans; a `color` declaration
- * (partial foreground emphasis) against color-carrying ones — a color-only
- * rendered span never satisfies a chip declaration. A channel-less
- * declaration ({text} only) keeps its legacy semantics (any extent matches).
- *
- * Capability gate: the COLOR channel compares only when `colorCapable` is
- * true (the dump's `spanChannels` marker includes "color") — an old
- * emitter's silence is "cannot see", never "no color span rendered". Within
- * a capable dump, an ABSENT `textSpans` is a real absence for a color
- * declaration (the segment rendered unstyled); background/legacy
- * declarations keep the old-package tolerance (no spans array → no fact).
- * A wrong extent on either channel is one `span_mismatch`; a matching extent
- * whose color diverges is a `span_color_mismatch` carrying both hex values.
- *
- * Pure and platform-agnostic; order-independent and deterministic (output
- * sorted by element id). The deriver reports facts only; significance is a
- * later, separately-wired concern.
- */
-export declare function deriveSpanFacts(rendered: RenderedSpans, reference: SpanSource, colorCapable?: boolean): AppearanceFact[];
-/** Declared line split per element id (issue 18): the exact line texts the
- *  design breaks that text element into, in order. A missing/empty array (or
- *  one with no usable line text) is "no line signal for that element" —
- *  never a divergence. */
-export type LineSource = Record<string, string[] | undefined>;
-/** The rendered laid-out lines per element id — each node's `textLines` from
- *  the layout dump. `undefined` for a node that emitted no lines (an old
- *  package, or a node that lays out no text): no signal, never a divergence. */
-export type RenderedLines = Record<string, TextLine[] | undefined>;
-/**
- * Line facts (issue 18) from the per-element comparison of the rendered
- * laid-out lines vs the declared reference split, keyed on the stable element
- * id. For each element the REFERENCE declares a split for: rendered line
- * texts equal to the declared line texts (same count, same order) → no fact;
- * anything else — the break on a different word, a dropped break (fewer
- * lines), an extra break — is ONE `line_break_mismatch` carrying both splits
- * newline-joined. An element whose node emitted NO lines produces no fact —
- * old committed packages don't emit `textLines`, and absence of a signal is
- * never reported as a divergence (regenerating the package picks it up).
- *
- * Pure and platform-agnostic; order-independent and deterministic (output
- * sorted by element id). The deriver reports facts only; significance is a
- * later, separately-wired concern.
- */
-export declare function deriveLineFacts(rendered: RenderedLines, reference: LineSource): AppearanceFact[];
-/** CIELAB triple [L, a, b]. */
-export type Lab = [number, number, number];
-/** One element's rendered/reference colors, by channel. A missing channel is
- *  "no color signal" for that element/channel — never a divergence. */
-export interface ElementColors {
-    fill?: string;
-    text?: string;
-    /** Per-channel alpha 0..1 (issue 14b), present only when translucent. */
-    fillAlpha?: number;
-    textAlpha?: number;
-    /** The BORDER colour (property-recognizer 01) — the design calls this a
-     *  `stroke`, and both sides use that name so they line up. On the reference
-     *  side it comes from `colors[key].stroke`; on the rendered side from the
-     *  dump's `borderColor`. */
-    stroke?: string;
-    /** Border thickness in DP on both sides — the harness reads `Dp.value` and the
-     *  design's `strokeWeight` is in design units, so unlike bounds this is never
-     *  divided by density. */
-    strokeWeight?: number;
-}
-export type ColorSource = Record<string, ElementColors>;
-/**
- * Convert an sRGB hex string to CIELAB (D65). White → ~[100,0,0], black → L 0.
- * Returns [0,0,0] for an unparseable string so a malformed color never throws
- * (the deriver guards on signal presence separately).
- */
-export declare function hexToLab(hex: string): Lab;
-/**
- * CIEDE2000 colour-difference ΔE00 between two CIELAB colours (kL=kC=kH=1).
- * Implements Sharma, Wu & Dalal (2005); validated against their supplementary
- * test data. Pure and symmetric; identical colours give 0.
- */
-export declare function ciede2000(lab1: Lab, lab2: Lab): number;
-/**
- * Border facts (property-recognizer 01) — the design's `stroke` against the
- * render's captured border. THE case this exists for: an 18dp badge with a 4dp
- * white ring inside it rendered as a plain green blob, about which the gate said
- * nothing at all, because the design's stroke lived in an authoring hint and the
- * dump captured no border. Nothing compared, so an unmeasured property read as a
- * pass.
- *
- * The DESIGN is the only side that raises the question, exactly as with alpha: an
- * entry with no declared `stroke` is skipped, so a wrapper adding a ring the
- * design never asked for is not something this calls wrong.
- *
- * Three kinds, because they are three different fixes — absent / wrong colour /
- * wrong thickness. Folding width into `border` would report "the ring is the
- * wrong colour" about a ring whose colour is exactly right.
- *
- * `capable` gates the ABSENCE case only, and both directions of that gate are
- * wrong in a way worth naming: without it, a border-blind dump would fire
- * `border_missing` on every stroked design in the catalogue; with it applied too
- * broadly, a real divergence on a capable dump would go unreported. A colour or
- * width difference is a genuine measurement either way — only "I saw no border"
- * depends on being able to see borders at all.
- *
- * Pure and platform-agnostic; deterministic (sorted by element id). Mirrors the
- * CLI preview twin in `packages/cli/lib/fidelity-structural.mjs`.
- */
-export declare function deriveBorderFacts(rendered: ColorSource, reference: ColorSource, capable: boolean): AppearanceFact[];
-/**
- * Color facts from the per-element, per-channel comparison of rendered vs
- * reference color, keyed on the stable element id shared with Signal B. For each
- * element/channel the REFERENCE declares a color for and the render also exposes
- * one: identical color → no fact; any divergence → a `color` fact carrying the
- * channel (fill vs text), both hex values, and the CIEDE2000 ΔE as the metric.
- * Fill and text are distinct channels, so a correct background with a wrong text
- * color and the reverse are separate facts, never collapsed. A missing rendered
- * or reference color for a channel is no signal → no fact.
- *
- * Pure and platform-agnostic; order-independent and deterministic (output sorted
- * by element id then channel, fill before text). Measurement only — significance
- * is a later, separately-wired concern.
- */
-export declare function deriveColorFacts(rendered: ColorSource, reference: ColorSource): AppearanceFact[];
-/** One element's resolved/design typeface, by the (single) text channel. */
-export type TypefaceSource = Record<string, TypefaceSpec | undefined>;
-/**
- * Typeface facts from the per-element comparison of the RESOLVED render font vs the
- * DESIGN reference font, keyed on the stable element id shared with Signal B. For
- * each element the reference declares a typeface for and the render also resolved
- * one: normalize both (family-name + weight-encoding) and emit a `typeface` fact
- * when the normalized family OR weight differs. A normalization-equivalent pair
- * ("Poppins-SemiBold" vs "Poppins" + 600) yields no fact. A missing rendered or
- * reference font for an element is no signal → no fact (graceful, no false
- * positive). The fact carries the raw `rendered`/`reference` specs as given, so the
- * finding names the actual fonts.
- *
- * Pure and platform-agnostic; order-independent and deterministic (output sorted by
- * element id). Measurement only — significance is a later, separately-wired concern.
- */
-export declare function deriveTypefaceFacts(rendered: TypefaceSource, reference: TypefaceSource): AppearanceFact[];
-/** Per-element type metrics, keyed like every other appearance source. */
-export type TypeMetricSource = Record<string, TypeMetrics | undefined>;
-/**
- * Type-metric facts from the per-element comparison of the LAID-OUT metrics
- * against the design's, keyed on the stable element id shared with Signal B.
- *
- * For each element the reference declares and the render measured, each of the
- * three metrics is compared independently and emits its own fact when the two
- * differ by more than the sub-unit tolerance. A metric missing on EITHER side is
- * no signal and yields no fact — a design that declares no tracking is not
- * asserting zero, and a style that leaves leading Unspecified has not chosen a
- * value to be wrong about.
- *
- * Pure and platform-agnostic; deterministic (sorted by element id, then by the
- * metric order a finding reads them in). Measurement only — significance and
- * wording live downstream.
- */
-export declare function deriveTypeMetricFacts(rendered: TypeMetricSource, reference: TypefaceSource): AppearanceFact[];
-/**
- * Assemble the inline `structural` block (ADR-0004): Signal-A facts always, plus
- * the Signal-B geometry block when `referenceGeometry` is supplied. Size (w/h)
- * deltas drive `sizeFlag`/`summary.clean`; x/y position deltas are reported but
- * never flagged (canvas-width artifact). Mirrors Invarn's `buildStructuralBlock`.
- */
-export declare function buildStructuralBlock(dump: LayoutDump, referenceGeometry?: ReferenceGeometry | null, density?: number, options?: {
-    sizeTolerancePx?: number;
-    overhangTolerancePx?: number;
-}, appearanceReference?: AppearanceReference | null, referenceFrame?: ReferenceFrame | null, anchorFrame?: ReferenceFrame | null): StructuralBlock;
-export interface ReviewRow {
-    element: string;
-    rendered: string | null;
-    design: string | null;
-    fact: string;
-    verdict: null;
-}
-export interface ReviewScaffold {
-    verdict: null;
-    mustExplain: string[];
-    rows: ReviewRow[];
-}
-/**
- * Build the run-only `review` scaffold from an assembled structural block:
- * size-flagged geometry elements first (load-bearing), then every structural
- * fact, each as a row with a null `verdict` the agent must replace.
- */
-export declare function buildReviewScaffold(structural: {
-    facts?: StructuralFact[];
-    geometry?: StructuralGeometry | null;
-}): ReviewScaffold;
-/**
- * Render-side embedded form of the deriver.
- *
- * The Android render runs as a single self-contained generated script (see
- * `generateAndroidRenderScript`), so render-side pure logic is embedded as a
- * JS-source string and concatenated in — exactly like `RENDER_SCRIPT_TRIM_STAGE`.
- * The typed `deriveStructuralFacts` above stays the canonical, tested spec; the
- * `parity` test asserts this embedded port produces identical facts on shared
- * fixtures so the two cannot drift.
- *
- * `deriveStructuralFacts` here is pure; `deriveAndWriteFacts` references runtime
- * globals (`fs`, `path`, `artifactsDir`, `log`) defined in the main script and
- * is only invoked from there — harmless to define in the eval sandbox.
- */
-export declare const RENDER_SCRIPT_FACTS_STAGE: string;
-/**
- * Evaluates the embedded facts stage and returns its pure `deriveStructuralFacts`,
- * so the parity test exercises exactly the code that ships in the runtime script
- * (mirrors `getPostProcessorInternals`). `deriveAndWriteFacts` references runtime
- * globals only when called, so defining it in the sandbox is harmless.
- */
-export declare function getStructuralFactsStageInternals(): {
-    deriveStructuralFacts: (dump: LayoutDump, options?: DeriveStructuralFactsOptions) => StructuralFact[];
-};
-/**
- * Render-side embedded form of the Signal-B differ + structural-block assembler.
- *
- * Concatenated into the generated render script alongside `RENDER_SCRIPT_FACTS_STAGE`
- * (function declarations hoist, so order does not matter — `buildStructuralBlock`
- * calls the facts stage's `deriveStructuralFacts`). `assembleStructural` references
- * runtime globals (`fs`, `path`, `log`) defined in the main script and is only
- * invoked from there. Kept byte-equivalent to the typed `buildStructuralBlock` /
- * `diffKeyGeometry` above by the parity test, so run-side and preview-side (Invarn)
- * structural blocks cannot drift.
- */
-export declare const RENDER_SCRIPT_GEOMETRY_STAGE: string;
-/**
- * Evaluates the embedded facts + geometry stages together (mirroring how the
- * render script concatenates them) and returns the pure `diffKeyGeometry` +
- * `buildStructuralBlock`, so the parity test exercises exactly the shipped code.
- */
-export declare function getGeometryStageInternals(): {
-    diffKeyGeometry: (generated: GeometrySource, reference: GeometrySource | null | undefined, options?: {
-        tolerancePx?: number;
-    }) => GeometryDelta[];
-    buildStructuralBlock: (dump: LayoutDump, referenceGeometry?: ReferenceGeometry | null, density?: number, options?: {
-        sizeTolerancePx?: number;
-        overhangTolerancePx?: number;
-    }, appearanceReference?: AppearanceReference | null, referenceFrame?: ReferenceFrame | null, anchorFrame?: ReferenceFrame | null) => StructuralBlock;
-    buildReviewScaffold: (structural: {
-        facts?: StructuralFact[];
-        geometry?: StructuralGeometry | null;
-    }) => ReviewScaffold;
-    derivePresenceFacts: (renderedIds: Iterable<string>, referenceIds: Iterable<string>) => AppearanceFact[];
-    deriveCopyFacts: (rendered: TextSource, reference: TextSource) => AppearanceFact[];
-    deriveSpanFacts: (rendered: RenderedSpans, reference: SpanSource) => AppearanceFact[];
-    deriveLineFacts: (rendered: RenderedLines, reference: LineSource) => AppearanceFact[];
-    deriveColorFacts: (rendered: ColorSource, reference: ColorSource) => AppearanceFact[];
-    deriveTypefaceFacts: (rendered: TypefaceSource, reference: TypefaceSource) => AppearanceFact[];
-    deriveTypeMetricFacts: (rendered: TypeMetricSource, reference: TypefaceSource) => AppearanceFact[];
-    buildAppearanceReferenceFromParams: (params: AppearanceReferenceParams) => AppearanceReference | null;
-    ciede2000: (lab1: Lab, lab2: Lab) => number;
-    hexToLab: (hex: string) => Lab;
-};
-//# sourceMappingURL=structural-facts.d.ts.map