@bridge-ds/core 0.18.0 → 0.20.0

package/dist/component-spec.d.ts

@@ -8,7 +8,9 @@ export declare const DEFAULT_COMPONENT_SPECS_FILE = "packages/react/component-sp
  * (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' | 'counterAxisSpacing' | 'width' | 'height' | 'minWidth' | 'minHeight' | 'opacity' | 'textFill' | 'fontFamily' | 'fontSize' | 'fontWeight' | 'lineHeight' | 'letterSpacing' | 'textDecoration';
+export type SpecField = 'fill' | 'stroke' | 'strokeWeight' | 'strokeTopWeight' | 'strokeRightWeight' | 'strokeBottomWeight' | 'strokeLeftWeight' | 'cornerRadius' | 'paddingTop' | 'paddingRight' | 'paddingBottom' | 'paddingLeft' | 'itemSpacing' | 'counterAxisSpacing' | 'width' | 'height' | 'minWidth' | 'minHeight' | 'opacity'
+/** A CSS box-shadow list (drop and inner shadows), as the page computes it. */
+ | 'shadow' | '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>;

package/dist/config.d.ts

@@ -17,6 +17,16 @@ export interface StorybookConfig {
     /** Root URL (where index.json and iframe.html are served), https only, no trailing slash. */
     url: string;
 }
+/**
+ * A public demo's persona (Bridge's own demo repositories only): who a visitor without an account stands in for,
+ * so the demo home greets them as that person ("Good morning, Dana.") and names their role. Ignored elsewhere.
+ */
+export interface DemoConfig {
+    /** The persona's first name: "Dana". */
+    viewer: string;
+    /** What they do: "DS lead". */
+    role?: string;
+}
 /** The team's hosted Library (/library/<owner>/<repo>/). */
 export interface LibraryConfig {
     /** True lets search engines index the hosted Library of a public repository. Default false: noindex. */
@@ -131,6 +141,11 @@ export interface GovernanceConfig {
      * person's approval counts for design and tech. Default false: one person never covers both approvals alone.
      */
     soloOwnerCanApproveBoth?: boolean | undefined;
+    /**
+     * Team admins and the reviewers of the matching domain publish a Tier 1 change without review (docs/GOVERNANCE.md,
+     * "Tier 1 publish by leads"). Absent counts as on (leadsPublishTier1On); false turns it off.
+     */
+    leadsPublishTier1?: boolean | undefined;
 }
 /** `bridge audit` settings: how product code that consumes the design system is measured. */
 export interface AuditConfig {
@@ -144,6 +159,8 @@ export interface AuditConfig {
     exclude?: string[] | undefined;
 }
 export interface BridgeConfig {
+    /** The team's display name ("Bridge", "Acme Design"), 1 to 60 characters. Undefined: Bridge names the team after its repository. */
+    name?: string | undefined;
     /** GitHub repository. Undefined only for a detected config of a repo with no known remote. */
     repo: RepoRef | undefined;
     tokens: TokenConfig;
@@ -190,6 +207,8 @@ export interface BridgeConfig {
     storybook?: StorybookConfig | undefined;
     /** The hosted Library. Read it through libraryIsPublic(). */
     library?: LibraryConfig | undefined;
+    /** A public demo's persona (see DemoConfig). */
+    demo?: DemoConfig | undefined;
 }
 type Partialish<T> = {
     [K in keyof T]?: T[K] | undefined;
@@ -198,6 +217,8 @@ type Partialish<T> = {
 export interface BridgeConfigInput {
     $schema?: string;
     version?: number;
+    /** The team's display name, shown on invites instead of owner/repo. */
+    name?: string;
     repo?: (Partial<RepoRef> & {
         owner: string;
         name: string;
@@ -256,7 +277,12 @@ export interface BridgeConfigInput {
         url: string;
     };
     library?: LibraryConfig;
+    demo?: DemoConfig;
 }
+/** Longest team display name bridge.config.json accepts. */
+export declare const TEAM_NAME_MAX = 60;
+/** The team's display name from a config value: trimmed, 1 to 60 characters; undefined for anything else. */
+export declare function teamName(value: unknown): string | undefined;
 export declare const DEFAULT_TOKEN_PATHS: TokenPaths;
 export declare const DEFAULT_GOVERNANCE: GovernanceConfig;
 export declare class ConfigError extends Error {

package/dist/css-color.d.ts

@@ -0,0 +1,25 @@
+/** One CSS color function (`oklch(0.205 0 0)`, `color(display-p3 1 0 0 / 0.5)`) as `rgb(r, g, b)` / `rgba(...)`. */
+export declare function cssColorToRgb(fn: string, inner: string): string | undefined;
+/** Every oklch/oklab/lab/lch/color() in a CSS value (a color, a shadow, SVG markup) as sRGB; the rest unchanged. */
+export declare function cssColorsToRgb(text: string): string;
+/** The same on every string inside a value (a measure result, a token harvest). */
+export declare function withSrgbColors<T>(value: T): T;
+export interface CssShadow {
+    inset: boolean;
+    x: number;
+    y: number;
+    blur: number;
+    spread: number;
+    /** 0..1 sRGB and alpha. */
+    color: {
+        r: number;
+        g: number;
+        b: number;
+        a: number;
+    };
+}
+/**
+ * A computed `box-shadow` (`rgba(0, 0, 0, 0.1) 0px 1px 3px 0px, inset ...`) as shadows, transparent ones left out (the
+ * zero rings utility CSS stacks under every shadow). Colors in any notation the page kept are read as sRGB.
+ */
+export declare function parseBoxShadow(css: string | undefined): CssShadow[];

package/dist/docs-proposal.d.ts

@@ -21,6 +21,7 @@ export interface DocsOrigin {
 }
 export declare const DOCS_EDITOR_ORIGIN: DocsOrigin;
 export declare const DOCS_MCP_ORIGIN: DocsOrigin;
+export declare const DOCS_CLI_ORIGIN: DocsOrigin;
 export interface DocsIssue {
     field: string;
     message: string;

package/dist/explorations.d.ts

@@ -162,6 +162,7 @@ export declare function explorationShareMessage(input: {
         label: string;
         url: string;
     }[] | undefined;
+    local?: string | undefined;
 }): string;
 /**
  * The rules Claude follows on an exploration branch (request briefs, docs drafts, token edits with a target branch):

package/dist/fidelity-references.d.ts

@@ -31,6 +31,18 @@ export interface ReferenceRender {
      * elements with their props, icons by name. Replaces `text` and `parts`.
      */
     children?: (string | SpecExample)[] | undefined;
+    /**
+     * Export name of the compound component this set is a part of (AccordionItem in Accordion, Radio in RadioGroup,
+     * MenuItem in Menu): the part needs its parent around it to render, and the image shows the part alone.
+     */
+    within?: string | undefined;
+    /**
+     * A popup drawn open (Dialog/Popup): the root renders open (`defaultOpen`), and the image is the popup Base UI
+     * portals, found by the class of the spec's root part ("popup", "tooltip"), not the trigger.
+     */
+    popup?: {
+        className: string;
+    } | undefined;
 }
 export type ReferencePlan = {
     ok: true;

package/dist/fidelity.d.ts

@@ -132,7 +132,18 @@ export declare function buildFidelityReport(input: {
     file?: string;
     now?: Date;
 }): FidelityReport;
-/** One variant's verdict: "Matches the code" or "Differs from the code: 12% of pixels, size 120x40 vs 118x40". */
+/**
+ * A size difference past the tolerance, in designer words: "height 89 in Figma vs 48 in code". It says more than the
+ * share of pixels when the two images do not have the same size (a 1% pixel score can hide a set twice as tall).
+ */
+export declare function sizeGap(s: {
+    figma: Size;
+    code: Size;
+}, tolerance?: number): string | undefined;
+/**
+ * One variant's verdict: "Matches the code", "Differs from the code: 12% of pixels", or the size first when the size
+ * differs: "Differs from the code: height 89 in Figma vs 48 in code, 1.4% of pixels".
+ */
 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;

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-fix-run.d.ts

@@ -0,0 +1,103 @@
+import { type BridgeConfig } from './config';
+import { type FixAttempt, type FixVerdict, type GapCaseForInput, type TriedVariant } from './figma-fix-loop';
+import type { FigmaFix } from './figma-fixes';
+import type { GapCase } from './gap-case';
+/** Where `bridge specs --measure` writes, from the repo root. */
+export declare const DEFAULT_MEASURED_SPECS_FILE = "measured-specs.json";
+/** The label every figma-fixes.json change carries, next to drafted-by-claude. */
+export declare const FIGMA_FIXES_LABEL = "figma-fixes";
+/** Asks Claude one prompt, returns the reply text. Runners pass the team's key; tests pass a fake. */
+export type FixAsk = (prompt: string) => Promise<string>;
+/** Where a loop stands between rounds: plain JSON, so a server can keep it between requests. */
+export interface FixLoopState {
+    component: string;
+    /** Rounds done. */
+    round: number;
+    attempts: FixAttempt[];
+    /** The closest fixes so far (verdict closer), with their score and the referee's summary. */
+    best?: {
+        fixes: unknown[];
+        score: number;
+        summary: string;
+    } | undefined;
+    /** No round left, or every difference resolved. */
+    done: boolean;
+}
+export interface FixLoopRound {
+    round: number;
+    fixes: unknown[];
+    /** invalid: the fixes broke the schema; undefined: no fixes could be read from the reply. */
+    verdict?: FixVerdict | 'invalid' | undefined;
+    summary: string;
+}
+export declare const startFixLoop: (component: string) => FixLoopState;
+/**
+ * One round: Claude proposes fixes from the gap case and what the earlier rounds gave, the values referee tries them,
+ * and the state keeps the closest. `ask` may throw (the network, the key): the state is then unchanged.
+ */
+export declare function fixLoopRound(input: GapCaseForInput, state: FixLoopState, ask: FixAsk, gap?: GapCase): Promise<{
+    state: FixLoopState;
+    round: FixLoopRound;
+}>;
+/** What the loop proposes once done: the closest fixes, or a status fix (Differs, with the reason) when none came closer. */
+export declare function fixLoopOutcome(gap: GapCase, state: FixLoopState, existingIds?: string[]): {
+    kind: 'fixes' | 'status';
+    fixes: unknown[];
+    summary: string;
+};
+/** The branch a component's fixes go on (a number is added when it is taken): bridge/figma-fixes-text-input. */
+export declare const figmaFixesBranchStem: (config: BridgeConfig, component: string) => string;
+export interface FigmaFixesProposalInput extends GapCaseForInput {
+    /** The fixes to propose (fix objects; the repo's fixes with the same ids are replaced). */
+    proposed: unknown[];
+    /** One or two sentences a reviewer reads first. */
+    summary: string;
+    config: BridgeConfig;
+    /** figma-fixes.json path in the repo. */
+    fixesPath: string;
+    /** Who drafted it, for the body and the commit: "Bridge MCP (source: mcp)". */
+    tool: string;
+    /** The `source:` label: mcp, cli, studio. */
+    source: string;
+}
+export interface FigmaFixesReport {
+    component: string;
+    verdict: FixVerdict;
+    summary: string;
+    variants: TriedVariant[];
+    fixes: string[];
+    tier: number;
+    prTitle: string;
+}
+export type FigmaFixesProposal = {
+    status: 'blocked';
+    verdict: FixVerdict;
+    why: string;
+    detail: string;
+    component: string;
+} | {
+    status: 'ready';
+    report: FigmaFixesReport;
+    /** The accepted fixes as validated. */
+    fixes: FigmaFix[];
+    labels: string[];
+    prBody: string;
+    fileContents: {
+        path: string;
+        content: string;
+    }[];
+    title: string;
+    message: string;
+    /** Tier 2 and above open as a draft. */
+    draft: boolean;
+    /** The default branch it targets. */
+    base: string;
+    branchStem: string;
+};
+/**
+ * The change for review of proposed fixes. The values referee runs again first: a fix that moves the component further
+ * from the code is refused, and part or story fixes that move nothing are refused (propose a status fix), unless they
+ * size, place or lay out a part: the values referee can't judge layout, Check fidelity decides. Throws a sentence when
+ * the fixes are invalid or the summary is not one.
+ */
+export declare function figmaFixesProposal(input: FigmaFixesProposalInput): FigmaFixesProposal;

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>>;