@bridge-ds/core 0.5.1 → 0.7.0

package/dist/component-spec.d.ts

@@ -5,30 +5,37 @@ export declare const DEFAULT_COMPONENT_SPECS_FILE = "packages/react/component-sp
 /**
  * A Figma-side property a CSS declaration maps to.
  * Frames: fill (background-color), stroke and stroke weights (border), cornerRadius (border-radius), paddings, itemSpacing
- * (gap), sizes. Text: textFill (color), font family, size, weight, line height, letter spacing.
+ * (gap), sizes. Text: textFill (color), font family, size, weight, line height, letter spacing, and textDecoration (a
+ * keyword, "UNDERLINE" or "STRIKETHROUGH", not a token).
  */
-export type SpecField = 'fill' | 'stroke' | 'strokeWeight' | 'strokeTopWeight' | 'strokeRightWeight' | 'strokeBottomWeight' | 'strokeLeftWeight' | 'cornerRadius' | 'paddingTop' | 'paddingRight' | 'paddingBottom' | 'paddingLeft' | 'itemSpacing' | 'width' | 'height' | 'minWidth' | 'minHeight' | 'textFill' | 'fontFamily' | 'fontSize' | 'fontWeight' | 'lineHeight' | 'letterSpacing';
+export type SpecField = 'fill' | 'stroke' | 'strokeWeight' | 'strokeTopWeight' | 'strokeRightWeight' | 'strokeBottomWeight' | 'strokeLeftWeight' | 'cornerRadius' | 'paddingTop' | 'paddingRight' | 'paddingBottom' | 'paddingLeft' | 'itemSpacing' | 'counterAxisSpacing' | 'width' | 'height' | 'minWidth' | 'minHeight' | 'opacity' | 'textFill' | 'fontFamily' | 'fontSize' | 'fontWeight' | 'lineHeight' | 'letterSpacing' | 'textDecoration';
 export declare const SPEC_FIELDS: readonly SpecField[];
 /** Fields whose token must be a color. */
 export declare const COLOR_FIELDS: ReadonlySet<SpecField>;
 /**
- * A token path ("button.primary.bg"), a literal zero (`padding: 0`), null: no paint (`transparent`), or a calc() of token
- * paths ("calc(space.2 + space.0-5)", operators + - * / and px numbers): resolved to a number, set but not bound.
+ * A token path ("button.primary.bg"), a literal number (`padding: 0`, a unitless `stroke-width: 3` or `opacity: 0.5`),
+ * null: no paint (`transparent`), or a calc() of token paths ("calc(space.2 + space.0-5)", operators + - * / and px
+ * numbers): resolved to a number, set but not bound.
  */
-export type SpecValue = string | 0 | null;
+export type SpecValue = string | number | null;
 export interface SpecLayout {
     direction: 'HORIZONTAL' | 'VERTICAL';
     /** justify-content. */
     primary: 'MIN' | 'CENTER' | 'MAX' | 'SPACE_BETWEEN';
     /** align-items. STRETCH: children fill the cross axis. */
     counter: 'MIN' | 'CENTER' | 'MAX' | 'STRETCH';
+    /** `flex-direction: row-reverse | column-reverse`: children are drawn in reverse order. */
+    reverse?: boolean | undefined;
+    /** `flex-wrap: wrap` on a row: items wrap to new lines (Figma auto layout wrap). */
+    wrap?: boolean | undefined;
 }
 export interface SpecPart {
     /** Stable id inside the component ("root", "label", "icon-start"). Figma layers keep it in plugin data. */
     id: string;
     /** Layer name in Figma. */
     name: string;
-    kind: 'frame' | 'text' | 'icon';
+    /** vector: an inline SVG drawn from the variant's `vectors` markup (a spinner arc, a progress ring). */
+    kind: 'frame' | 'text' | 'icon' | 'vector';
     /** Parent part id; undefined for the root (the variant itself). */
     parent?: string | undefined;
     /** CSS module class the part is styled by ("Button.module.css .label"), for people reading the spec. */
@@ -42,11 +49,44 @@ export interface SpecPart {
     clip?: boolean | undefined;
     /** Root only: block-level in code (display block, flex or grid, or width 100%), so it fills its container. Figma draws it at a fixed width. */
     fill?: boolean | undefined;
+    /** Text parts with no TEXT property (content written in code, like a group's option labels): the characters drawn. */
+    characters?: string | undefined;
+    /**
+     * Positioned over its parent instead of flowing in its auto layout (an avatar photo over its initials): `position:
+     * absolute` with `inset: 0`, or `width` and `height` 100%. Drawn as an absolute child that fills its parent.
+     */
+    cover?: boolean | undefined;
+    /**
+     * `position: absolute` with token offsets (a dialog's close button): out of the auto layout, pinned to the parent's
+     * edges by these offsets (top, right, bottom, left).
+     */
+    pin?: {
+        top?: SpecValue;
+        right?: SpecValue;
+        bottom?: SpecValue;
+        left?: SpecValue;
+    } | undefined;
+    /** `width: 100%` or `height: 100%` in a parent of that size: Fill container on that axis. */
+    stretch?: {
+        width?: boolean;
+        height?: boolean;
+    } | undefined;
+    /** A value indicator (a progress fill): this share of its parent's width, from the component's value. */
+    fraction?: number | undefined;
+    /**
+     * A thumb placed at the component's value (a slider's): out of the auto layout, its center at this share of its
+     * parent's width, centered on the parent's height.
+     */
+    at?: number | undefined;
+    /** `flex: 1` in code: takes the free space along its parent's auto layout direction (Figma "Fill container"). */
+    grow?: boolean | undefined;
     /**
      * A swappable part: drawn as an instance of a generated component ("Icon/Plus", "Slot/Media") and swapped through an
      * INSTANCE_SWAP property. Icon parts swap between every icon of `icons`; content slots between `options`.
      */
     swap?: SpecSwap | undefined;
+    /** Icon parts whose icon is written in code (a checkbox's check mark): an instance of this icon, with no property. */
+    icon?: string | undefined;
 }
 export interface SpecSwap {
     /** INSTANCE_SWAP property name ("Icon", "Icon start", "Body"). */
@@ -117,6 +157,72 @@ export interface SpecVariant {
     values: Record<string, Partial<Record<SpecField, SpecValue>>>;
     /** Swappable part id -> the component this variant shows by default ("Icon/Plus", "Slot/Media"). */
     slots?: Record<string, string> | undefined;
+    /** Parts this variant does not show (`display: none`, `opacity: 0` or `scale(0)` in this state): hidden layers. */
+    hidden?: string[] | undefined;
+    /** Parts whose auto layout differs from the part's own in this variant (a switch thumb at the end when on). */
+    layout?: Record<string, SpecLayout> | undefined;
+    /** Vector parts: the SVG this variant draws and the stroke token of each shape, in order. */
+    vectors?: Record<string, SpecVector> | undefined;
+    /** Absolute parts placed differently in this variant (offsets from the parent's edges, like SpecPart.pin). */
+    pins?: Record<string, NonNullable<SpecPart['pin']>> | undefined;
+}
+/** An inline SVG part: markup with literal geometry (strokes painted #000000) and the token bound to each shape's stroke. */
+export interface SpecVector {
+    svg: string;
+    strokes: SpecValue[];
+}
+/**
+ * A prototype trigger, Figma's names. ON_HOVER "While hovering" and ON_PRESS "While pressing" go back when the pointer
+ * leaves or lets go; ON_CLICK "On click" stays. A set with a Checked axis uses MOUSE_ENTER / MOUSE_LEAVE for hover, so a
+ * click that changes Checked is not undone when the pointer leaves.
+ */
+export type SpecTrigger = 'ON_HOVER' | 'ON_PRESS' | 'ON_CLICK' | 'MOUSE_ENTER' | 'MOUSE_LEAVE';
+/** Designer names of the triggers, as Figma's prototype panel shows them. */
+export declare const TRIGGER_LABELS: Record<SpecTrigger, string>;
+/** An easing Figma can play: linear, or a cubic bezier with the exact points of the code's curve. */
+export interface SpecEasing {
+    type: 'LINEAR' | 'CUSTOM_CUBIC_BEZIER';
+    /** CUSTOM_CUBIC_BEZIER: x1, y1, x2, y2. */
+    bezier?: [number, number, number, number] | undefined;
+}
+/** The code's CSS transition for one change, resolved from the motion tokens. Played with Smart animate. */
+export interface SpecTransition {
+    /** Milliseconds. */
+    duration: number;
+    /** Token behind the duration ("motion.duration.instant"), when it is one. */
+    durationToken?: string | undefined;
+    easing: SpecEasing;
+    /** Token behind the easing ("motion.easing.standard"), when it is one. */
+    easingToken?: string | undefined;
+    /** CSS properties the code animates in this change ("background-color"). */
+    properties: string[];
+    /** Why Figma plays it slightly differently from the code (one speed for parts that move at several), when it does. */
+    approximated?: string | undefined;
+}
+/**
+ * A prototype interaction between variants of the set, read from the CSS: on `trigger`, every variant whose `axis` is
+ * `from` changes to the variant with `to` instead (other axes kept). `variants` narrows it to those variant keys
+ * (variantKeyOf) when it does not apply to all of them. `transition` null: the code changes it instantly.
+ */
+export interface SpecInteraction {
+    trigger: SpecTrigger;
+    axis: string;
+    from: string;
+    to: string;
+    variants?: string[] | undefined;
+    transition: SpecTransition | null;
+}
+/** Motion the code has that a Figma prototype cannot play (a looping spinner, keyboard focus, a popup opening). */
+export interface SpecMotionNote {
+    /** What moves, in plain words ("Looping animation spin, 700 ms"). */
+    what: string;
+    /** Why Figma does not play it. */
+    reason: string;
+    /** A keyframe animation: the token behind its duration ("motion.duration.spin"), when it is one. */
+    durationToken?: string | undefined;
+    /** Opening and closing: the code's transition when it opens (enter) and when it closes (exit), when it has one. */
+    enter?: SpecTransition | undefined;
+    exit?: SpecTransition | undefined;
 }
 /** A declaration, prop or part that has no Figma equivalent in this version, with the reason. */
 export interface SpecUnmapped {
@@ -127,6 +233,26 @@ export interface SpecUnmapped {
 }
 export interface ComponentSpec {
     name: string;
+    /** Component folder the set comes from, when it is not the set's name (Radio comes from RadioGroup). */
+    component?: string | undefined;
+    /** Props pinned for this set (`{ variant: 'circular' }` for Progress/Circular, a set per layer tree). */
+    fixed?: Record<string, string> | undefined;
+    /** A popup drawn open (`popup`), or the component without its popup (`without-popup`). */
+    view?: 'popup' | 'without-popup' | undefined;
+    /**
+     * Drafted with Claude, not generated: the generator cannot read this component, so its spec was written by hand from
+     * the code (packages/react/component-spec-overrides/<Name>.json, `"source": "drafted"`) and validated like a generated
+     * one. Shown in the plugin as "Drafted, check it". `stale`: the code it was drafted from changed since.
+     */
+    drafted?: {
+        reason: string;
+        stale?: boolean | undefined;
+    } | undefined;
+    /**
+     * The code example the set's content comes from (the docs preview or a component sandbox example): the element, its
+     * props and children, so the fidelity check renders the same thing. Not in the hash: it does not change the drawing.
+     */
+    example?: SpecExample | undefined;
     /** FNV-1a of everything else in the spec: unchanged hash, nothing to rebuild. */
     hash: string;
     /** Files it was read from, repo-relative. */
@@ -136,6 +262,16 @@ export interface ComponentSpec {
     parts: SpecPart[];
     variants: SpecVariant[];
     unmapped: SpecUnmapped[];
+    /** Prototype interactions between the variants (hover, press, click to check), with the code's motion. */
+    interactions?: SpecInteraction[] | undefined;
+    /** Motion of the code a Figma prototype cannot play. */
+    motion?: SpecMotionNote[] | undefined;
+}
+/** An element of a code example: component export name, literal props, children (texts or elements). */
+export interface SpecExample {
+    c: string;
+    p?: Record<string, unknown> | undefined;
+    children?: (string | SpecExample)[] | undefined;
 }
 export interface ComponentSpecsFile {
     version: number;
@@ -147,18 +283,113 @@ export interface ComponentSpecsFile {
     iconStyle?: SpecIconStyle | undefined;
     /** Content components slots swap to. */
     slots?: SpecSlot[] | undefined;
+    /**
+     * Every component of the design system and whether it is in Figma: generated (its sets are in `components`),
+     * unsupported (with the generator's reason) or layout (no visual of its own: a layout helper, use auto layout).
+     * Undefined in files written before coverage was recorded.
+     */
+    coverage?: SpecCoverage[] | undefined;
+}
+export type CoverageStatus = 'generated' | 'drafted' | 'unsupported' | 'layout';
+export interface SpecCoverage {
+    /** Component folder name ("RadioGroup"). */
+    name: string;
+    status: CoverageStatus;
+    /** Plain reason, for unsupported, drafted and layout components ("opens a popup", "uses CSS grid"). */
+    reason?: string | undefined;
+    /** Sets generated from it, when they are not just its own name ("RadioGroup", "Radio"). */
+    sets?: string[] | undefined;
 }
+/**
+ * Coverage counts from a specs file: visual components (generated, drafted with Claude, unsupported), in Figma
+ * (generated + drafted), and layout helpers.
+ */
+export declare function coverageSummary(file: Pick<ComponentSpecsFile, 'coverage' | 'components'>): {
+    generated: number;
+    drafted: number;
+    inFigma: number;
+    visual: number;
+    layout: number;
+    total: number;
+    missing: SpecCoverage[];
+};
+/**
+ * Checks a component spec against the format (the schema every set follows, generated or drafted): axes and their
+ * variants (one per combination, no extra), properties, parts (one root, known parents in order, text and visibility
+ * properties that exist), each value's field and type, and, given `tokenTypes` (token path -> $type), that every token
+ * path exists and has a type the field takes. Returns the problems in plain language, none when the spec is valid.
+ */
+export declare function validateComponentSpec(spec: Omit<ComponentSpec, 'hash'> & {
+    hash?: string;
+}, tokenTypes?: Map<string, string>): string[];
 /** Figma component name of an icon: "Icon/Plus". */
 export declare const iconComponentName: (name: string) => string;
 /** FNV-1a, 32 bits, 8 hex digits. */
 export declare function specHash(text: string): string;
-/** Hash of a spec without its own hash field. */
+/** Hash of a spec without its own hash field (and without its code example, which does not change the drawing). */
 export declare function hashSpec(spec: Omit<ComponentSpec, 'hash'> | ComponentSpec): string;
 /** Figma variant name for a variant's props: "Variant=primary, Size=md, State=Default" (axis order). */
 export declare const variantName: (props: Record<string, string>) => string;
 /** Variant key independent of axis order (same as the plugin's signature keys): sorted "Size=md, Variant=primary". */
 export declare const variantKeyOf: (props: Record<string, string>) => string;
+/** What a set's description says about reduced motion: tokens set every duration to 0 under prefers-reduced-motion. */
+export declare const REDUCED_MOTION_NOTE = "In code, reduced motion turns this off.";
+/** One prototype reaction: on `trigger`, the variant `fromKey` changes to `toKey`, with the code's transition. */
+export interface MotionReaction {
+    trigger: SpecTrigger;
+    /** Figma's name for the trigger ("While hovering"). */
+    label: string;
+    from: Record<string, string>;
+    to: Record<string, string>;
+    /** variantKeyOf(from) and variantKeyOf(to). */
+    fromKey: string;
+    toKey: string;
+    transition: SpecTransition | null;
+}
+/** A component set's motion and interactions, read from its spec: for Figma prototypes, docs and reviews. */
+export interface ComponentMotion {
+    name: string;
+    /** Every reaction between variants, one per variant it starts from. */
+    reactions: MotionReaction[];
+    /** The interactions as the spec lists them (one per trigger and change), with the number of variants each covers. */
+    triggers: (SpecInteraction & {
+        label: string;
+        count: number;
+    })[];
+    /** Motion tokens the transitions use ("motion.duration.instant", "motion.easing.standard"), sorted. */
+    tokens: string[];
+    /** CSS properties that animate ("background-color"), sorted. */
+    properties: string[];
+    /** Where Figma plays the motion differently from the code. */
+    approximations: string[];
+    /** Motion of the code a Figma prototype cannot play. */
+    cannotPlay: SpecMotionNote[];
+    /** Opening and closing (a popup, a panel): the code's enter and exit transitions, when it has them. */
+    opening: {
+        enter: SpecTransition | null;
+        exit: SpecTransition | null;
+    } | undefined;
+    /** REDUCED_MOTION_NOTE when the component animates in code, else undefined. */
+    reducedMotion: string | undefined;
+}
+/**
+ * The motion of a component set from its spec: every reaction between its variants (trigger, from and to variants, the
+ * transition with duration and easing resolved from the motion tokens), the tokens and properties involved, what Figma
+ * approximates or cannot play, and the reduced motion note. Pure: works in the plugin, the browser and Node.
+ */
+export declare function componentMotion(spec: Pick<ComponentSpec, 'name' | 'variants' | 'interactions' | 'motion'>): ComponentMotion;
+/**
+ * Sets whose interactions use a motion token, directly or through an alias: `chainOf(path)` gives the tokens a path
+ * resolves through (resolve(...).chain), so a change to a primitive ("duration.75") finds the sets using
+ * "motion.duration.instant". Without it, only direct uses count. Sorted set names.
+ */
+export declare function componentsUsingMotionToken(specs: Pick<ComponentSpecsFile, 'components'>, tokenPath: string, chainOf?: (path: string) => string[]): string[];
 /** Parses component-specs.json; throws with a readable message when it is not a specs file of a known version. */
 export declare function parseComponentSpecs(text: string): ComponentSpecsFile;
 /** CSS custom property of a token path, with the repo convention (`cssVar` in bridge.config.json): "--" + path joined by "-". */
 export declare const tokenCssVar: (path: string, prefix?: string, separator?: string) => string;
+/** How a component stands in Figma, in Studio's words (the "In Figma" column): a short word and, for the ones not in Figma, the reason as a tooltip. Undefined: no data. */
+export declare function figmaCell(entry: SpecCoverage | undefined): {
+    label: string;
+    title?: string;
+} | undefined;

package/dist/config.d.ts

@@ -1,6 +1,7 @@
 import type { IntegrationsConfig } from './requests';
 import { type PreviewApps, type PreviewsConfig } from './previews';
 import { type Rights, type VisualImpactConfig } from './rights';
+import { type ProductConfig } from './products';
 /** File name Bridge looks for at the repository root. */
 export declare const CONFIG_FILE = "bridge.config.json";
 export interface RepoRef {
@@ -151,6 +152,8 @@ export interface BridgeConfig {
     integrations?: IntegrationsConfig | undefined;
     /** Visual before and after on pull requests: automatic (default) or on demand (label `visual-check`). */
     visualImpact?: VisualImpactConfig | undefined;
+    /** Apps that consume the design system, the default one being the library (see products.ts). Default DEFAULT_PRODUCTS. */
+    products: ProductConfig[];
 }
 type Partialish<T> = {
     [K in keyof T]?: T[K] | undefined;
@@ -210,6 +213,7 @@ export interface BridgeConfigInput {
     };
     integrations?: IntegrationsConfig;
     visualImpact?: Partial<VisualImpactConfig>;
+    products?: ProductConfig[];
 }
 export declare const DEFAULT_TOKEN_PATHS: TokenPaths;
 export declare const DEFAULT_GOVERNANCE: GovernanceConfig;

package/dist/docs-proposal.d.ts

@@ -0,0 +1,82 @@
+import { type ComponentDocsJson } from './docs-draft';
+import type { GitHubClient } from './github-client';
+import { type RiskResult } from './risk';
+/** One component's docs.json, before (null: a new file) and after, at its repo path. */
+export interface DocsFileEdit {
+    path: string;
+    component: string;
+    slug: string;
+    before: string | null;
+    after: string;
+}
+/** Who wrote the docs, for the pull request body and its source label. */
+export interface DocsOrigin {
+    /** "in the Bridge docs editor". */
+    where: string;
+    footer: string;
+    label: string;
+}
+export declare const DOCS_EDITOR_ORIGIN: DocsOrigin;
+export declare const DOCS_MCP_ORIGIN: DocsOrigin;
+export interface DocsIssue {
+    field: string;
+    message: string;
+}
+/** What blocks proposing a docs.json: a summary, no empty list items, no em dash (Bridge voice). */
+export declare function validateDocs(d: ComponentDocsJson): DocsIssue[];
+/** Drops empty list items and trims text, the way the editor saves. */
+export declare function cleanDocs(d: ComponentDocsJson): ComponentDocsJson;
+/** docs.json in the editor's canonical form: cleaned, in the Button.docs.json key order. Used to compare. */
+export declare const docsText: (d: ComponentDocsJson) => string;
+/** docs.json text the editor writes: cleaned, as a minimal diff of the file on main (or the branch) when there is one. */
+export declare const docsFileText: (d: ComponentDocsJson, original: string | null) => string;
+export interface DocsProposal {
+    branch: string;
+    title: string;
+    body: string;
+    files: {
+        path: string;
+        content: string;
+    }[];
+    risk: RiskResult;
+    bump: 'patch';
+    labels: string[];
+}
+/** One pull request for the docs edits of a draft: branch, title, body, files with a patch changeset, the tier. */
+export declare function docsProposal(edits: DocsFileEdit[], opts: {
+    title?: string | undefined;
+    notes?: string | undefined;
+    date: Date;
+    packageName?: string | undefined;
+    changesetDir?: string | undefined;
+    origin?: DocsOrigin | undefined;
+}): DocsProposal;
+/**
+ * Opens one pull request with the docs edits from the default branch, the Jira key first in the title and the branch
+ * name (Jira's GitHub integration links them). Returns its number, link and branch. Labels are best effort.
+ */
+export declare function proposeDocsOnGitHub(gh: GitHubClient, edits: DocsFileEdit[], opts: {
+    base: string;
+    title?: string | undefined;
+    notes?: string | undefined;
+    jira?: string | null | undefined;
+    date?: Date | undefined;
+    origin?: DocsOrigin | undefined;
+    extraLabels?: string[] | undefined;
+    commitNote?: string | undefined;
+}): Promise<{
+    number: number;
+    url: string;
+    branch: string;
+    title: string;
+}>;
+/**
+ * Rewrites one file on an open branch in one commit (`next` gets the current text). Returns the commit sha, or ''
+ * when nothing changed. The Library editor saves an edited docs.json and accepts a Claude draft this way.
+ */
+export declare function commitFileOnGitHub(gh: GitHubClient, input: {
+    path: string;
+    branch: string;
+    message: string;
+    next: (text: string) => string;
+}): Promise<string>;

package/dist/explorations.d.ts

@@ -39,6 +39,8 @@ export interface Exploration {
     source?: ExplorationSource | undefined;
     /** The AI agent that started it ("claude"), when one did: the GitHub account alone cannot tell. */
     agent?: string | undefined;
+    /** A Jira ticket key ("DS-42"), first in the pull request title so Jira's GitHub integration links it. */
+    jira?: string | undefined;
 }
 /** "Denser data tables!" -> "denser-data-tables". Up to 40 characters, cut at a word boundary. Empty when nothing is left. */
 export declare function explorationSlug(name: string): string;

package/dist/fidelity-references.d.ts

@@ -0,0 +1,78 @@
+import { type ComponentSpec, type ComponentSpecsFile, type SpecExample, type SpecVariant } from './component-spec';
+export declare const FIGMA_REFERENCES_BRANCH = "bridge-visual";
+export declare const FIGMA_REFERENCES_DIR = "figma-references";
+export declare const FIGMA_REFERENCES_MANIFEST = "figma-references/manifest.json";
+/** Story id of packages/react/src/stories/FigmaReference.stories.tsx. */
+export declare const FIGMA_REFERENCE_STORY = "internal-figma-reference--variant";
+/** Width token of a block-level root in Figma (the plugin draws fill roots at this width: FILL_WIDTH_TOKEN). */
+export declare const FIGMA_FILL_WIDTH_TOKEN = "size.80";
+export type ReferencePseudo = 'hover' | 'active' | 'focus-visible';
+/** What the reference story renders for one variant. JSON, passed to the story as a string arg. */
+export interface ReferenceRender {
+    /** Export name of the component ("Button", "Card"). */
+    component: string;
+    /** Props from the variant axes and the default property values ("variant": "primary", "disabled": true). */
+    props: Record<string, unknown>;
+    /** Text children (the Label property) of a simple component. */
+    text?: string | undefined;
+    /** Compound parts, in order: export name and text ("CardHeader", "Header"). */
+    parts?: {
+        component: string;
+        text: string;
+    }[] | undefined;
+    /** Icon props -> Lucide icon name ("icon": "Pencil"). */
+    icons?: Record<string, string> | undefined;
+    /** Hover, pressed or focus, forced with the pseudo-states addon classes. */
+    pseudo?: ReferencePseudo | undefined;
+    /** Width token path of the frame the component sits in, for roots that fill their container. */
+    width?: string | undefined;
+    /**
+     * Children from the code example the set was drawn with (a table's rows, a form's fields): texts and design system
+     * elements with their props, icons by name. Replaces `text` and `parts`.
+     */
+    children?: (string | SpecExample)[] | undefined;
+}
+export type ReferencePlan = {
+    ok: true;
+    render: ReferenceRender;
+} | {
+    ok: false;
+    reason: string;
+};
+/** How to render one generated variant from code, or why it cannot be compared. */
+export declare function planReference(spec: ComponentSpec, variant: SpecVariant, file?: Pick<ComponentSpecsFile, 'slots'>): ReferencePlan;
+/** File name of a variant's image, stable and file safe: "button/size-md__state-default__variant-primary.png". */
+export declare function referenceImagePath(component: string, key: string): string;
+export type FigmaReferenceEntry = {
+    file: string;
+    width: number;
+    height: number;
+} | {
+    skipped: string;
+};
+export interface FigmaReferenceManifest {
+    version: 1;
+    tool: '@bridge-ds/visual';
+    createdAt: string;
+    /** Commit of the code the images were made from. */
+    sha: string;
+    /** Device pixels per CSS pixel, the scale the plugin exports Figma variants at. */
+    scale: number;
+    mode: {
+        brand: string;
+        theme: string;
+        density: string;
+    };
+    storyId: string;
+    components: Record<string, {
+        specHash: string;
+        variants: Record<string, FigmaReferenceEntry>;
+    }>;
+}
+/** Every variant of every spec with its render plan (the capture's to-do list). */
+export declare function planReferences(file: ComponentSpecsFile): {
+    component: string;
+    specHash: string;
+    key: string;
+    plan: ReferencePlan;
+}[];

package/dist/fidelity.d.ts

@@ -0,0 +1,138 @@
+/** An RGBA image, 4 bytes per pixel, row by row (ImageData, pngjs and canvas all use this layout). */
+export interface RgbaImage {
+    width: number;
+    height: number;
+    data: Uint8Array | Uint8ClampedArray;
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface CompareOptions {
+    /** Export scale of both images (device pixels per CSS pixel). Sizes are reported in CSS pixels. Default 2. */
+    scale?: number;
+    /**
+     * Color distance under which two pixels are the same, 0 to 1 (YIQ, as pixelmatch). Default 0.1: absorbs gamma
+     * and antialiasing ramps, catches a token swap (a gray one step away is about 0.12).
+     */
+    threshold?: number;
+    /**
+     * Neighborhood, in device pixels, searched for a matching pixel before one counts as different. Figma and Chrome
+     * rasterize text and curves differently (glyph hinting, subpixel positions, corner antialiasing): a pixel that has
+     * its twin within this distance is the same shape drawn half a pixel away. Default: one CSS pixel (= scale).
+     */
+    radius?: number;
+    /** Largest share of different pixels, in percent, that still matches. Default 3. */
+    maxPercent?: number;
+    /** Largest size difference per side, in CSS pixels, that still matches. Default 1. */
+    sizeTolerance?: number;
+    /** Also return the diff overlay. Default true. */
+    diffImage?: boolean;
+}
+export interface ImageCompareResult {
+    matches: boolean;
+    /** Different pixels in percent of the larger canvas, two decimals. */
+    percent: number;
+    differentPixels: number;
+    totalPixels: number;
+    /** CSS pixel sizes (image size divided by the scale, rounded). */
+    size: {
+        figma: Size;
+        code: Size;
+    };
+    sizeMatches: boolean;
+    /** The code image faded to gray with different pixels in red, on the larger canvas. */
+    diff?: RgbaImage | undefined;
+}
+export declare const FIDELITY_DEFAULTS: {
+    readonly scale: 2;
+    readonly threshold: 0.1;
+    readonly maxPercent: 3;
+    readonly sizeTolerance: 1;
+};
+/** YIQ squared distance between two opaque colors (pixelmatch's perceptual metric). */
+export declare function colorDelta(a: [number, number, number], b: [number, number, number]): number;
+/**
+ * Compares a Figma export with the code reference of the same variant. A pixel differs when its color is not found
+ * near the same place in the other image, in either direction: a shape drawn half a pixel away, or text rasterized
+ * a little differently, matches; a missing border, another color, other padding or a different size does not.
+ * Pixels outside the smaller image count as transparent: there, any visible color differs (a missing footer is a
+ * difference even when its gray is light).
+ */
+export declare function compareImages(figma: RgbaImage, code: RgbaImage, options?: CompareOptions): ImageCompareResult;
+export type FidelityVariantStatus = 'matches' | 'differs' | 'skipped';
+export interface FidelityVariantResult {
+    /** Variant key, as the plugin stores it ("Size=md, State=Default, Variant=primary"). */
+    key: string;
+    status: FidelityVariantStatus;
+    percent?: number | undefined;
+    size?: {
+        figma: Size;
+        code: Size;
+    } | undefined;
+    /** Skipped variants: why there is nothing to compare, in designer words. */
+    reason?: string | undefined;
+}
+export type FidelityComponentStatus = 'matches' | 'differs' | 'not-checked';
+export interface FidelityComponentResult {
+    component: string;
+    status: FidelityComponentStatus;
+    checked: number;
+    differing: number;
+    skipped: number;
+    /** The variant that differs most (or matches least well). */
+    worst?: {
+        key: string;
+        percent: number;
+        size: {
+            figma: Size;
+            code: Size;
+        };
+    } | undefined;
+    /** Not checked at all: why. */
+    reason?: string | undefined;
+    variants: FidelityVariantResult[];
+}
+export interface FidelityReport {
+    version: 1;
+    checkedAt: string;
+    /** Figma file the sets were exported from. */
+    file?: string | undefined;
+    /** Commit the code images were made from. */
+    reference: {
+        sha: string;
+        createdAt: string;
+    };
+    options: {
+        scale: number;
+        threshold: number;
+        radius: number;
+        maxPercent: number;
+        sizeTolerance: number;
+    };
+    components: FidelityComponentResult[];
+    summary: {
+        components: number;
+        matches: number;
+        differs: number;
+        notChecked: number;
+        variantsChecked: number;
+        variantsSkipped: number;
+    };
+}
+/** Rolls variant results up into one component result. */
+export declare function summarizeComponent(component: string, variants: FidelityVariantResult[], reason?: string): FidelityComponentResult;
+export declare function buildFidelityReport(input: {
+    components: FidelityComponentResult[];
+    reference: {
+        sha: string;
+        createdAt: string;
+    };
+    options?: CompareOptions;
+    file?: string;
+    now?: Date;
+}): FidelityReport;
+/** One variant's verdict: "Matches the code" or "Differs from the code: 12% of pixels, size 120x40 vs 118x40". */
+export declare function fidelityVerdict(v: Pick<FidelityVariantResult, 'status' | 'percent' | 'size' | 'reason'>): string;
+/** One component's line, from its worst variant. */
+export declare function fidelityComponentLine(c: FidelityComponentResult): string;