@bridge-ds/core 0.17.0 → 0.19.0

package/dist/figma-fix-loop.d.ts

@@ -0,0 +1,153 @@
+import { type ComponentSpec, type SpecValue } from './component-spec';
+import type { FidelityComponentResult, FidelityReport } from './fidelity';
+import { type AppliedFix, type FigmaFix, type FigmaFixesFile, type FixedMeasuredSpecsFile } from './figma-fixes';
+import { type GapBuiltVariant, type GapCase, type GapDifference } from './gap-case';
+import type { MeasuredSpecsFile } from './measured-spec';
+/** Where the plugin's Check fidelity run lives in the team's repo (or on the requests branch), next to measured-specs.json. */
+export declare const DEFAULT_FIDELITY_RUN_FILE = "figma-fidelity.json";
+/** Rounds of try per component before the loop gives up and proposes an honest status instead. */
+export declare const FIX_LOOP_MAX_ROUNDS = 3;
+/** The model the CLI loop runner asks when the team's API key is set and no model is named. */
+export declare const FIX_LOOP_MODEL = "claude-sonnet-5-5";
+/**
+ * One Check fidelity run, as the plugin saves it: the report (the shot referee), and per set what the layers read back
+ * (values, hidden parts, boxes: they let the gap say where space is missing) and a reference to each Figma render.
+ */
+export interface FigmaFidelityRun {
+    version: 1;
+    report: FidelityReport;
+    /** Set name -> variant key -> what the plugin read back from the layers. */
+    built?: Record<string, Record<string, GapBuiltVariant>> | undefined;
+    /** Set name -> variant key -> node id or exported PNG. */
+    figmaRenders?: Record<string, Record<string, string>> | undefined;
+    /** measuredAt of the measured-specs.json the pull drew from. */
+    measuredAt?: string | undefined;
+}
+/**
+ * Reads a fidelity run: the plugin's run file, a bare FidelityReport ("Copy the report"), or one component's result.
+ * Throws a sentence that says what is wrong.
+ */
+export declare function parseFidelityRun(input: string | unknown): FigmaFidelityRun;
+export interface FigmaGapRow {
+    component: string;
+    /** Differs: the shots (or the measure) say so. Can't check: nothing to compare, or a status fix says so. */
+    status: 'differs' | 'cant-check';
+    /** One sentence for a designer. */
+    summary: string;
+    /** What said it: the plugin's Check fidelity (shots), the measure's --check (values), or a status fix. */
+    source: 'fidelity' | 'measure' | 'figma-fixes';
+    checked?: number | undefined;
+    differing?: number | undefined;
+    /** Fix ids figma-fixes.json already applies to it. */
+    fixes?: string[] | undefined;
+}
+/**
+ * The components whose Figma build differs from their story, or that cannot be checked: from the fidelity run when
+ * there is one (the shots are the referee), else from the measure's statuses (`bridge specs --measure --check`). A
+ * status fix in figma-fixes.json shows with its reason. Matching components are left out.
+ */
+export declare function figmaGaps(measured: FixedMeasuredSpecsFile | MeasuredSpecsFile, run?: FigmaFidelityRun): FigmaGapRow[];
+export interface GapCaseForInput {
+    component: string;
+    /** measured-specs.json as measured (the team's fixes are applied here). */
+    measured: MeasuredSpecsFile;
+    /** figma-fixes.json, when the repo has one. */
+    fixes?: FigmaFixesFile | undefined;
+    run?: FigmaFidelityRun | undefined;
+}
+export interface GapCaseFor {
+    gap: GapCase;
+    /** The measure with the team's fixes on (what the pull reads). */
+    measured: FixedMeasuredSpecsFile;
+    /** The set the pull draws from it (specsFromMeasure), when the measure gives one. */
+    spec?: ComponentSpec | undefined;
+    fidelity?: FidelityComponentResult | undefined;
+    shots: Record<string, {
+        file: string;
+    }>;
+}
+/** The gap case of one component, built the way the plugin pulls it: fixes applied, set rebuilt, the run's verdicts. */
+export declare function gapCaseFor(input: GapCaseForInput): GapCaseFor;
+export declare const FIX_SCHEMA_SUMMARY = "figma-fixes.json fixes (version 1). Each fix is one JSON object:\n- Every fix: \"id\" (lower case, digits, dashes, unique), \"kind\", \"component\" (the Figma set, e.g. \"TextInput\"), \"reason\" (one plain sentence, no em dash), optional \"by\": \"claude\", optional \"where\": { \"args\": { \"<arg>\": value }, \"state\": \"rest\" | \"hover\" | \"active\" | \"focus-visible\" | \"disabled\" } (absent: every variant).\n- kind \"part\": \"part\" is a part id from the gap case (\"root\", \"cds--text-input-label-wrapper\") or \".class\". At least one of: \"set\" { field: token path | px number | null (colors only) | \"full\" (cornerRadius only) }, \"width\" / \"height\": \"fixed\" (the measured size) | px number | \"hug\" | \"fill\", \"direction\": \"HORIZONTAL\" | \"VERTICAL\", \"align\": { \"primary\": MIN|CENTER|MAX|SPACE_BETWEEN, \"counter\": MIN|CENTER|MAX|STRETCH }, \"overlay\": true | false | { \"top\": 3, \"left\": 3 }, \"hide\": true (alone; never the root). Fields: 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.\n- kind \"axis\": \"action\" \"map\" (\"arg\", \"property\" and/or \"values\" { code value: Figma value }), \"ignore\" (\"arg\"), or \"prune\" (\"where\" names the variants to drop).\n- kind \"story\": \"where\" names the variant, \"use\": { \"story\": \"<story id>\", \"args\"?, \"state\"? } is the measured render to draw it from.\n- kind \"status\": \"status\": \"differs\" | \"cant-check\" with the reason; never \"matches\" (only the shots say a component matches). Without \"status\": a note.\nRules: fix only the component you were given; prefer the smallest fix that explains the differences (a part's size \"fixed\" when Figma hugs what code fixes, a missing padding, a hidden part); never invent a part id or a token: use the ones in the gap case.";
+export type FixDiffResult = 'resolved' | 'closer' | 'same' | 'worse' | 'unknown';
+export type FixVerdict = 'closer' | 'same' | 'worse';
+export interface TriedDifference {
+    text: string;
+    part: string;
+    property: GapDifference['property'];
+    /** Code (the measure). */
+    expected: SpecValue | boolean;
+    /** Figma now (the gap case), and what the rebuilt set draws with the fixes. */
+    before: SpecValue | boolean;
+    after: SpecValue | boolean | undefined;
+    deltaBefore?: number | undefined;
+    deltaAfter?: number | undefined;
+    result: FixDiffResult;
+    /** The size after is worked out from the layer boxes and the changed paddings, gaps and fixed sizes. */
+    estimated?: boolean | undefined;
+}
+export interface TriedVariant {
+    key: string;
+    story?: string | undefined;
+    /** gone: the fixes drop this variant (prune, ignore). */
+    verdict: FixVerdict | 'gone';
+    differences: TriedDifference[];
+    /** Differences the fixes add: the rebuilt set now disagrees with the code where it agreed. */
+    regressions: GapDifference[];
+}
+export interface TryFixesResult {
+    status: 'invalid' | 'checked';
+    component: string;
+    /** Validation problems (status invalid): fix them and try again. */
+    problems: string[];
+    /** One record per proposed fix: applied, not-found (its part or story is not in this measure), already. */
+    applied: AppliedFix[];
+    /** The values referee's verdict on the whole: closer, same or worse. */
+    verdict: FixVerdict;
+    referee: 'values';
+    variants: TriedVariant[];
+    /** One sentence. */
+    summary: string;
+    /** Lines for Claude: per variant, each difference before and after. */
+    detail: string;
+    /** The figma-fixes.json the fixes make (the repo's fixes, with these added or replacing the same ids). */
+    file?: FigmaFixesFile | undefined;
+}
+export interface TryFixesInput extends GapCaseForInput {
+    /** The fixes to try, added to the repo's (a fix with the id of one already there replaces it). */
+    proposed: unknown[];
+}
+/** The repo's fixes with the proposed ones: a proposed fix replaces one with the same id, the others are appended. */
+export declare function mergeFigmaFixes(existing: FigmaFixesFile | undefined, proposed: FigmaFix[]): FigmaFixesFile;
+/**
+ * The values referee: validates the proposed fixes, lays them on the measure, rebuilds the set the way the plugin pulls
+ * it, and compares each variant the gap case lists with what the code renders, before and after. A difference is
+ * resolved, closer, the same or worse; a difference the fixes add elsewhere is a regression. The verdict is closer when
+ * more moved closer than got worse. Offline: no Figma, no shots. The pixel check runs in the plugin after the pull.
+ */
+export declare function tryFigmaFixes(input: TryFixesInput): TryFixesResult;
+/** Plain words for one fix, for the pull request body. */
+export declare function fixWords(f: FigmaFix): string;
+/** A part fix that sizes, places or lays out a part: the values referee can't judge it, Check fidelity does. */
+export declare function touchesLayout(f: FigmaFix): boolean;
+/** The pull request body of a figma-fixes.json change: the gap, each fix with its reason, before and after. */
+export declare function figmaFixesPrBody(input: {
+    component: string;
+    summary: string;
+    gap: GapCase;
+    tried: TryFixesResult;
+    fixes: FigmaFix[];
+    tool: string;
+}): string;
+export interface FixAttempt {
+    fixes: unknown[];
+    /** Validation problems, or the try's detail. */
+    feedback: string;
+    verdict?: FixVerdict | undefined;
+}
+/** The prompt for one round: the gap case, the schema, and what the earlier rounds gave. Asks for fix objects only. */
+export declare function fixPrompt(gap: GapCase, attempts?: FixAttempt[]): string;
+/** The fix objects in a reply: a JSON array (or { "fixes": [...] }), in a code fence or not. Throws a sentence otherwise. */
+export declare function parseFixReply(text: string): unknown[];
+/** A status fix for a component that did not converge: what the loop proposes after its last round. */
+export declare function statusFixFor(gap: GapCase, existingIds?: string[]): FigmaFix;

package/dist/figma-fixes.d.ts

@@ -0,0 +1,169 @@
+import { type SpecField, type SpecLayout, type SpecValue } from './component-spec';
+import type { MeasuredSpecsComponent, MeasuredSpecsFile, MeasuredSpecsStory } from './measured-spec';
+import { type GapState } from './gap-case';
+export declare const FIGMA_FIXES_VERSION = 1;
+/** Where the fixes live in the team's repo when nothing else is said. */
+export declare const DEFAULT_FIGMA_FIXES_FILE = "figma-fixes.json";
+export type FixArgValue = string | number | boolean;
+/** Which variants a fix applies to: stories whose props (args over defaults, plus overrides) include `args`, in `state`. */
+export interface FixWhere {
+    args?: Record<string, FixArgValue> | undefined;
+    state?: GapState | undefined;
+}
+interface FixBase {
+    /** Stable and unique in the file: lower case, digits and dashes ("toggle-knob-radius"). Provenance names it. */
+    id: string;
+    /** The Figma set: the last segment of the stories' title ("Toggle"), case ignored. */
+    component: string;
+    /** Why, in plain words: read in review and shown where the fix applies. */
+    reason: string;
+    /** Who wrote it: "claude" or a GitHub login. */
+    by?: string | undefined;
+    /** Only these variants. Absent: every story of the component. */
+    where?: FixWhere | undefined;
+}
+export type FixSize = 'hug' | 'fill' | 'fixed' | number;
+export type FixPrimary = SpecLayout['primary'];
+export type FixCounter = SpecLayout['counter'];
+export type FixPin = {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+};
+/** (a) A spec patch on one part of the measured render. */
+export interface PartFix extends FixBase {
+    kind: 'part';
+    /** Part id ("cds--toggle-switch", "root"), or a CSS class with a dot (".cds--toggle__switch"): every part with it. */
+    part: string;
+    /** Field values: a token path, a px number, null (no paint, colors only), or "full" for a corner radius (pill). */
+    set?: Partial<Record<SpecField, SpecValue | 'full'>> | undefined;
+    /** fixed: the measured size (or this number, px), hug: its content, fill: its container. */
+    width?: FixSize | undefined;
+    height?: FixSize | undefined;
+    /** Auto layout of a frame part. */
+    direction?: SpecLayout['direction'] | undefined;
+    align?: {
+        primary?: FixPrimary | undefined;
+        counter?: FixCounter | undefined;
+    } | undefined;
+    /** true: over its parent, filling it (out of auto layout). An object: pinned at these offsets (px). false: back in the flow. */
+    overlay?: boolean | FixPin | undefined;
+    /** Not drawn (with everything inside it). */
+    hide?: boolean | undefined;
+}
+/** (b) How a story arg becomes a Figma property. */
+export interface AxisFix extends FixBase {
+    kind: 'axis';
+    /**
+     * map: name the property (`property`) and its values (`values`: code value -> Figma value).
+     * ignore: the arg is not a property; only stories at its default value are drawn.
+     * prune: drop the variants `where` names (a combination code allows that the library never shows).
+     */
+    action: 'map' | 'ignore' | 'prune';
+    arg?: string | undefined;
+    property?: string | undefined;
+    values?: Record<string, string> | undefined;
+}
+/** (c) The story a variant is drawn from. */
+export interface StoryFix extends FixBase {
+    kind: 'story';
+    /** The story to use, as measured: its id, and the args and state of the measured entry when there are several. */
+    use: {
+        story: string;
+        args?: Record<string, FixArgValue> | undefined;
+        state?: GapState | undefined;
+    };
+}
+/** (d) A note, or the status to show with its reason, when a variant will not converge. Never "matches". */
+export interface StatusFix extends FixBase {
+    kind: 'status';
+    /** Absent: a note only. */
+    status?: 'differs' | 'cant-check' | undefined;
+}
+export type FigmaFix = PartFix | AxisFix | StoryFix | StatusFix;
+export interface FigmaFixesFile {
+    $schema?: string | undefined;
+    version: typeof FIGMA_FIXES_VERSION;
+    fixes: FigmaFix[];
+}
+export declare class FigmaFixesError extends Error {
+    readonly problems: string[];
+    constructor(problems: string[]);
+}
+/**
+ * Every problem in a fixes file, in plain words (empty when it is valid): version, unique ids, a component and a reason
+ * on every fix, known kinds and keys, and each kind's fields.
+ */
+export declare function validateFigmaFixes(data: unknown): string[];
+/** Reads figma-fixes.json (text or parsed JSON); throws FigmaFixesError with every problem. */
+export declare function parseFigmaFixes(input: string | unknown): FigmaFixesFile;
+/** What applyFixes writes on a component entry for the pull: Figma names, dropped args and combinations, status. */
+export interface FigmaHints {
+    /** Arg -> Figma property name. */
+    properties?: Record<string, string> | undefined;
+    /** Arg -> code value -> Figma value. */
+    values?: Record<string, Record<string, string>> | undefined;
+    /** Args that are not Figma properties. */
+    ignored?: string[] | undefined;
+    /** Variant combinations dropped. */
+    pruned?: FixWhere[] | undefined;
+    /** Status to show for the component, or for some variants (`where`), with the reason. */
+    status?: {
+        status: 'differs' | 'cant-check';
+        reason: string;
+        fix: string;
+        where?: FixWhere | undefined;
+    }[] | undefined;
+    notes?: {
+        text: string;
+        fix: string;
+        where?: FixWhere | undefined;
+    }[] | undefined;
+    /** Ids of the fixes applied to this component, in file order. */
+    fixes?: string[] | undefined;
+}
+export type FixedComponent = MeasuredSpecsComponent & {
+    figma?: FigmaHints | undefined;
+};
+/** A measured story a fix changed: the ids of those fixes. */
+export type FixedStory = MeasuredSpecsStory & {
+    fixes?: string[] | undefined;
+};
+export interface AppliedFix {
+    id: string;
+    kind: FigmaFix['kind'];
+    component: string;
+    /** applied: it changed what the pull draws. not-found: nothing matched (the code or the measure moved: re-check it). already: the input had it. */
+    result: 'applied' | 'not-found' | 'already';
+    /** Story entries it changed. */
+    stories: number;
+    /** Plain words: what it did, or what it did not find. */
+    detail: string;
+}
+/** The pull's input with the fixes laid on, and where they came from. */
+export type FixedMeasuredSpecsFile = Omit<MeasuredSpecsFile, 'stories' | 'components'> & {
+    stories: FixedStory[];
+    components?: FixedComponent[] | undefined;
+    /** The fixes run that made this file. */
+    figmaFixes?: {
+        applied: AppliedFix[];
+    } | undefined;
+};
+/** A story is one of `where`'s variants: every arg it names, at that value, and the state. */
+export declare function storyMatchesWhere(s: MeasuredSpecsStory, where: FixWhere | undefined): boolean;
+/**
+ * The measured specs the pull reads, with the fixes laid on, and one provenance record per fix. Pure: the input is not
+ * changed. Fixes run in file order; a fix whose component, part or story is not in this measure is reported
+ * `not-found` (the code or the measure moved: re-check it) and changes nothing. A file that already carries a fix run
+ * (`figmaFixes`) keeps those fixes and only runs the new ones.
+ */
+export declare function applyFixes(measured: MeasuredSpecsFile | FixedMeasuredSpecsFile, fixes: FigmaFixesFile | FigmaFix[]): {
+    file: FixedMeasuredSpecsFile;
+    applied: AppliedFix[];
+};
+/** A part fix in a few words, for provenance and review: "toggle switch: cornerRadius full, width fixed". */
+export declare function describePartFix(f: PartFix): string;
+/** One line per fix result, for the CLI and the plugin's pull report. */
+export declare function appliedFixLines(applied: AppliedFix[]): string[];
+export {};

package/dist/figma-push-github.d.ts

@@ -117,6 +117,7 @@ export declare function figmaChangeOnGitHub(gh: GitHubClient, n: number, opts?:
         body: string;
         mergeable: boolean | null;
         requestedReviewers: string[];
+        autoMerge: boolean;
     };
     origin: FigmaOrigin;
     status: FigmaPushStatus;
@@ -127,6 +128,7 @@ export declare function figmaChangeOnGitHub(gh: GitHubClient, n: number, opts?:
         body: string;
         mergeable: boolean | null;
         requestedReviewers: string[];
+        autoMerge: boolean;
     };
     origin: FigmaOrigin;
     status: FigmaPushStatus;
@@ -137,12 +139,15 @@ export declare function figmaChangeOnGitHub(gh: GitHubClient, n: number, opts?:
     brief: string;
 }>;
 /**
- * Claude wrote the code: the branch is labelled drafted by Claude AI (no longer waiting) and its description says so.
- * Refused while the branch only carries the spec, so the label never claims code that is not there.
+ * Claude wrote the code: the pull request is marked ready for review, then the branch is labelled drafted-by-claude
+ * (no longer waiting) and its description says so. Refused while the branch only carries the spec, so the label never
+ * claims code that is not there. Ready goes first: when GitHub refuses it, nothing else changed, so the label never
+ * says "drafted" on a branch reviewers cannot see yet. Running it again after a partial failure finishes the job.
  */
 export declare function markFigmaChangeDraftedOnGitHub(gh: GitHubClient, n: number): Promise<{
     status: FigmaPushStatus;
     files: string[];
+    ready: boolean;
 }>;
 /** Where each pushed Figma component's library branch stands (by pull request number), for the plugin's Pull. */
 export declare function figmaPushStatusesOnGitHub(gh: GitHubClient, numbers: number[]): Promise<Map<number, FigmaPushStatus>>;

package/dist/figma-push.d.ts

@@ -14,11 +14,24 @@ export interface Rebind {
     allVariants: boolean;
     before: string[];
     after: string[];
+    /** Values set by hand where a variable went (the property was unbound), with the variables that hold each. */
+    raw?: UnboundValue[] | undefined;
+}
+/** A value set by hand in Figma ("#FF00AA", "12") and the Figma variables whose value equals it ("radius/control"). */
+export interface UnboundValue {
+    value: string;
+    matches?: string[] | undefined;
 }
 /** An edit the scan cannot read with confidence, and what the designer does about it. */
 export interface PushIssue {
     what: string;
     todo: string;
+    /** A property set by hand: where, and its values, so the designer sees them and can bind a variable that holds one. */
+    raw?: {
+        kind: string;
+        variants: string[];
+        values: UnboundValue[];
+    } | undefined;
 }
 /**
  * A component change from Figma, structured: what the designer sees in the Push tab, and what the library branch
@@ -111,7 +124,7 @@ export interface ComponentPushPlan {
 /**
  * How a component change from Figma goes back to the library. A token swap is exact when the property was painted by a
  * component token (one variable before, one after), that token paints nothing else, and the new variable is a token
- * the library has: the token then points to the new variable. Anything else that needs code is drafted by Claude AI;
+ * the library has: the token then points to the new variable. Anything else that needs code is built by a developer with Claude;
  * what cannot be read with confidence is listed with what to do.
  */
 export declare function planComponentPush(d: ComponentPushDiff, ctx: PushTokenContext): ComponentPushPlan;
@@ -194,7 +207,7 @@ export declare const figmaBranchTitle: (d: Pick<ComponentPushDiff, "component" |
 export type FigmaPushStatusKey = 'waiting-for-claude' | 'drafted' | 'in-review' | 'shipped' | 'closed';
 export interface FigmaPushStatus {
     key: FigmaPushStatusKey;
-    /** "Waiting for Claude AI", "Shipped". */
+    /** "Waiting for a developer", "Shipped". */
     label: string;
     /** One sentence for the designer. */
     sentence: string;

package/dist/gap-case.d.ts

@@ -0,0 +1,144 @@
+import { type ComponentSpec, type SpecField, type SpecPart, type SpecValue, type SpecVariant } from './component-spec';
+import type { FidelityComponentResult, Size } from './fidelity';
+import { type MeasuredBox, type MeasuredSpec, type MeasuredSpecsFile, type MeasuredSpecsStory, type MeasuredState } from './measured-spec';
+export declare const GAP_CASE_VERSION = 1;
+/** How a story reaches a variant: at rest, a forced pseudo state, or disabled (an arg). */
+export type GapState = 'rest' | MeasuredState | 'disabled';
+/**
+ * What a difference is about. A Figma field (fill, paddingTop, cornerRadius, height...), or: `presence` (a part one side
+ * draws and the other does not), `sizing` (fixed in code, hugging in Figma), `direction` (auto layout direction).
+ */
+export type GapProperty = SpecField | 'presence' | 'sizing' | 'direction';
+/** One concrete difference. `expected` is the code (the measure), `actual` is Figma (what was drawn). */
+export interface GapDifference {
+    /** Plain words: "Height 72 in Figma vs 84 in code: 12 px missing below the label wrapper". */
+    text: string;
+    /** Part id, as the measure and the built set name it ("root", "cds--toggle-switch"). */
+    part: string;
+    /** The part in words ("toggle switch"). */
+    partName: string;
+    property: GapProperty;
+    /** Code: token path, px number, null (no paint), `present`, `fixed`, `HORIZONTAL`... */
+    expected: SpecValue | boolean;
+    /** Figma: the same kinds, `missing`, `hidden`, `hug`... */
+    actual: SpecValue | boolean;
+    /** Numbers: actual minus expected, px (negative: Figma is smaller). */
+    delta?: number | undefined;
+}
+export interface GapStoryRef {
+    /** Storybook story id. */
+    id: string;
+    name?: string | undefined;
+    /** Story URL the measure opened (args in it). */
+    url?: string | undefined;
+    /** The props it rendered with (args over the component defaults), and the args Bridge passed to reach the variant. */
+    props: Record<string, string | number | boolean>;
+    overrides?: Record<string, string | number | boolean> | undefined;
+    state: GapState;
+}
+export interface GapVariant {
+    /** Figma variant key (variantKeyOf: "Size=md, State=Default"). */
+    key: string;
+    /** Figma props of the variant. */
+    props: Record<string, string>;
+    /** The referee's verdict for this variant: the plugin's Check fidelity (`unchecked` without one). */
+    verdict: 'differs' | 'unchecked';
+    /** Different pixels in percent, and both sizes, when the shot was compared. */
+    percent?: number | undefined;
+    size?: {
+        figma: Size;
+        code: Size;
+    } | undefined;
+    story?: GapStoryRef | undefined;
+    /** The story's screenshot, relative to measured-specs.json (the referee image). */
+    shot?: string | undefined;
+    /** What Figma drew for this variant: a node id or an exported PNG, when the plugin passes one. */
+    figmaRender?: string | undefined;
+    differences: GapDifference[];
+    /** Why the list is empty when the shots differ: no story, or the measure agrees and only the images tell. */
+    unexplained?: string | undefined;
+}
+export interface GapCase {
+    version: typeof GAP_CASE_VERSION;
+    component: string;
+    storybook: string;
+    /** `shots`: the variants come from the fidelity check. `values`: no check was passed, variants with differences. */
+    referee: 'shots' | 'values';
+    /** Variants compared, and how many differ. */
+    checked: number;
+    differing: number;
+    /** One sentence for a designer. */
+    summary: string;
+    /** Lines for a developer (or Claude): story, args, state, shot and every delta per variant. */
+    detail: string;
+    variants: GapVariant[];
+    /** Fixes from figma-fixes.json already applied to this component (the patched measure says so). */
+    fixes?: string[] | undefined;
+}
+/** What the plugin reads back from one drawn variant, laid over the spec it drew from. All optional. */
+export interface GapBuiltVariant {
+    /** Field values the layers hold (part id -> field -> value), when they differ from the spec's. */
+    values?: SpecVariant['values'] | undefined;
+    /** Parts hidden in this variant. */
+    hidden?: string[] | undefined;
+    /** Part id -> its box relative to the variant's top-left, px: lets the gap say where space is missing. */
+    boxes?: Record<string, MeasuredBox> | undefined;
+}
+export interface GapCaseInput {
+    /** Set name ("Toggle"): the last segment of the stories' title. */
+    component: string;
+    measured: MeasuredSpecsFile;
+    /** What the pull drew the set from (specsFromMeasure's spec, or the overlaid static spec). */
+    spec?: ComponentSpec | undefined;
+    /** The plugin's Check fidelity result for this set: the referee. */
+    fidelity?: FidelityComponentResult | undefined;
+    /** Variant key -> what the layers read back. */
+    built?: Record<string, GapBuiltVariant> | undefined;
+    /** Variant key -> the story shot the set was compared with (MeasuredShots[set]). */
+    shots?: Record<string, {
+        file: string;
+    }> | undefined;
+    /** Variant key -> a reference to what Figma drew (node id, PNG path). */
+    figmaRenders?: Record<string, string> | undefined;
+    /** Token path -> its value in the measured page. Default: the measure's resolved values and token harvest. */
+    resolve?: ((tokenPath: string) => string | number | undefined) | undefined;
+}
+/** The stories of a set: the last title segment, case and punctuation ignored. */
+export declare function storiesOfComponent(file: Pick<MeasuredSpecsFile, 'stories'>, component: string): MeasuredSpecsStory[];
+/** A story's state: its forced pseudo state, else disabled when the arg says so, else at rest. */
+export declare function storyState(s: Pick<MeasuredSpecsStory, 'state' | 'props' | 'overrides'>): GapState;
+/**
+ * The story a Figma variant was drawn from: the one whose shot it was compared with, else the first (single instance
+ * before galleries) whose props, overrides and state give the variant's axis values.
+ */
+export declare function storyForVariant(spec: Pick<ComponentSpec, 'axes'>, props: Record<string, string>, stories: MeasuredSpecsStory[], shot?: {
+    file: string;
+}): MeasuredSpecsStory | undefined;
+/** A part in words: the measure's ids are class names ("cds--toggle__switch" -> "toggle switch"). */
+export declare function partWords(part: Pick<SpecPart, 'id' | 'name'> | undefined, id?: string): string;
+/** Token path -> value, from the measure: components[].resolved, then the token harvest (by CSS name). */
+export declare function measuredResolver(file: Pick<MeasuredSpecsFile, 'components' | 'tokens'>): (path: string) => string | number | undefined;
+export interface VariantGapInput {
+    /** The parts the set was drawn with, and this variant's values and hidden parts. */
+    parts: SpecPart[];
+    variant: Pick<SpecVariant, 'values' | 'hidden' | 'layout'>;
+    properties?: ComponentSpec['properties'] | undefined;
+    built?: GapBuiltVariant | undefined;
+    measured: MeasuredSpec;
+    /** The fidelity check's sizes (CSS px), when the shot was compared. */
+    size?: {
+        figma: Size;
+        code: Size;
+    } | undefined;
+    resolve?: ((tokenPath: string) => string | number | undefined) | undefined;
+}
+/**
+ * The differences between what Figma drew for one variant and what the code renders (its measured story): the size and
+ * where it comes from, parts one side lacks, fixed sizes Figma hugs, auto layout direction, then field values.
+ */
+export declare function variantDifferences(input: VariantGapInput): GapDifference[];
+/**
+ * The gap case of one component: the variants the referee says differ (the fidelity check; without one, every variant
+ * with a difference), each with its story, args, state, shot, Figma render and the differences in words and deltas.
+ */
+export declare function buildGapCase(input: GapCaseInput): GapCase;

package/dist/github-client.d.ts

@@ -15,6 +15,8 @@ export interface GitHubErrorInfo {
     auth?: GitHubAuthState | undefined;
     /** The permission the call needed, when GitHub or the endpoint tells (only with auth "missing-permission"). */
     permission?: GitHubPermission | undefined;
+    /** For a rate limit (status 429): when the limit resets, when GitHub or Bridge said. */
+    resetsAt?: Date | undefined;
 }
 export declare class GitHubError extends Error {
     readonly status: number;
@@ -23,6 +25,8 @@ export declare class GitHubError extends Error {
     readonly auth: GitHubAuthState | undefined;
     /** With auth "missing-permission": the permission the call needed, when known. */
     readonly permission: GitHubPermission | undefined;
+    /** For a rate limit (status 429): when the limit resets, when known. */
+    readonly resetsAt: Date | undefined;
     constructor(status: number, message: string, detail?: string | undefined, info?: GitHubErrorInfo);
 }
 /** True when `err` says GitHub refused the token itself (revoked, regenerated or expired). */
@@ -96,6 +100,8 @@ export interface Review {
     state: string;
     body: string;
     submittedAt?: string | undefined;
+    /** The commit the review was given on (GitHub `commit_id`). */
+    commitId?: string | undefined;
 }
 export interface PullRequestSummary {
     number: number;
@@ -112,6 +118,11 @@ export interface PullRequestSummary {
     updatedAt: string;
     /** Description, when the list endpoint returns it (component change requests read "Closes #n" from it). */
     body?: string | undefined;
+    /** ISO dates, when GitHub returns them (build requests: in progress since, shipped on). */
+    createdAt?: string | undefined;
+    mergedAt?: string | undefined;
+    /** Who is assigned (logins), when any. */
+    assignees?: string[] | undefined;
 }
 export interface ClientOptions {
     /** API base, for GitHub Enterprise or tests. */
@@ -340,8 +351,23 @@ export declare class GitHubClient {
      */
     private paged;
     getRepo(): Promise<RepoInfo>;
+    /**
+     * What the token may write here, found without writing anything: each probe is invalid on purpose (a zero sha, a
+     * missing head branch, an empty title), so GitHub answers 422 when the token has the permission and 403 or 404 when
+     * it does not. repo.permissions.push says what the user may do, not what a fine-grained token may do.
+     */
+    writeAccess(base: string): Promise<{
+        contents: boolean;
+        pullRequests: boolean;
+        issues: boolean;
+    }>;
     /** Commit sha a branch points to, or undefined when the branch does not exist. */
     getBranchSha(branch: string): Promise<string | undefined>;
+    /**
+     * Whether a branch exists, through the matching-refs list: it answers 200 with an empty list when the branch is
+     * missing, so asking never leaves a 404 in the browser console (an optional branch like bridge-data).
+     */
+    hasBranch(branch: string): Promise<boolean>;
     getCommitTree(commitSha: string): Promise<string>;
     getTree(treeSha: string, recursive?: boolean): Promise<{
         entries: TreeEntry[];
@@ -609,6 +635,7 @@ export declare class GitHubClient {
         body: string;
         mergeable: boolean | null;
         requestedReviewers: string[];
+        autoMerge: boolean;
     }>;
     listPullRequestFiles(n: number): Promise<PullRequestFile[]>;
     updatePullRequest(n: number, patch: {
@@ -782,4 +809,8 @@ export interface IssueSummary {
     author: string;
     createdAt: string;
     updatedAt: string;
+    /** Who is assigned (logins), when any (build requests: "Ana is on it"). */
+    assignees?: string[] | undefined;
+    /** ISO date it was closed, when closed. */
+    closedAt?: string | undefined;
 }

package/dist/id-map.d.ts

@@ -17,6 +17,16 @@ export interface ReconcileResult {
 export declare function levenshtein(a: string, b: string): number;
 export declare function pathSimilarity(a: string, b: string): number;
 export declare const SIMILARITY_THRESHOLD = 0.5;
+/**
+ * Tokens the code renamed between two commits: removed and added between `base` and `head` with the same type, tier
+ * and values and a similar path. One pair per token; a token that matches more than one counterpart equally is left
+ * as a removal and an addition (no guess). Lets a pull rename the Figma variable instead of orphaning it and adding a
+ * new one, so everything bound to it keeps its binding.
+ */
+export declare function remoteRenames(base: Map<string, LogicalToken>, head: Map<string, LogicalToken>): {
+    from: LogicalToken;
+    to: LogicalToken;
+}[];
 /**
  * Align Figma token ids with Git ids. `git` is every token known on the Git side (base and head).
  * Heuristic candidates are restricted to Git tokens that no Figma variable claims.