@bridge-ds/core 0.9.0 → 0.10.0

package/README.md

@@ -36,7 +36,8 @@ also exported as `@bridge-ds/core/bridge.config.schema.json`) for the plugin, th
 server. Canonical form: `repo`, `tokens` (`root`, `include`, `exclude`, `tiers`, ordered `layers` with `{mode}`
 placeholders and `optional`), `modes` (name -> `{ values, default, parity }`), `contrast` (`path`, `modes`),
 `components`, `docs`, `changesets`, `cssVar`, `governance` (`protectedBranches`, `branchPrefix`, `labels`,
-`guardrails`, `owners: { design, tech }`). The older flat form (`tokens.primitives`, `modes.brands`...) still loads.
+`guardrails`, `owners: { design, tech }`), `changes` (`"suggest"`, the default, or `"direct"`) and `storybook`
+(`{ url }`, https). The older flat form (`tokens.primitives`, `modes.brands`...) still loads.
 
 ```ts
 const CONFIG_FILE = 'bridge.config.json';
@@ -50,10 +51,13 @@ interface BridgeConfig {
   docs; changesets: { dir; package } | undefined; changeset?: { package };
   cssVar: { prefix; separator };
   governance: { protectedBranches; branchPrefix; labels; guardrails; owners: { design: string[]; tech: string[] } };
+  changes: 'suggest' | 'direct';                          // how changes reach the code (default 'suggest')
+  storybook?: { url: string };
 }
 function defineConfig(input): BridgeConfig;   function loadConfig(source): BridgeConfig;   // ConfigError { problems }
 function toConfigJson(config): object;        // canonical JSON (what `bridge init` writes)
 function protectedBranchesOf(config); function baseBranchOf(config); function tokensPath(config, rel?);
+function changesMode(config): 'suggest' | 'direct';   function storybookUrl(config): string | undefined; // storybook.url, else previews.production.storybook
 ```
 
 ## governance
@@ -257,6 +261,28 @@ loadRepoFiles(client, commitSha, fallbackTokensPath): Promise<{ files; contrastC
 Reads and content-addressed writes retry on network errors, 5xx and secondary rate limits; errors
 become `GitHubError { status, message, detail }` with plain-language messages.
 
+## suggestions (suggestions.ts, suggestion-review.ts, suggestions-github.ts)
+
+A change filed as a GitHub issue instead of a branch, so an owner needs only Issues write. Readable Markdown, then a
+collapsed JSON payload (`bridge.suggestion/1`) with the sha256 of its canonical form in a marker; token changes are
+edits (paths and values), other files whole contents with git blob shas before and after. Contents that do not fit
+the body (65,536 characters) go to continuation comments, 8 at most. Reviews are comments bound to the payload sha
+and counted only from the configured owners.
+
+```ts
+composeSuggestionIssue(payload, { labels?, assignees?, state?, details? }): { title; body; labels; assignees; parts: string[]; sha };
+parseSuggestionIssue(body, { comments?, author? }): { ok: true; payload; sha; markedSha; edited; parts } | { ok: false; reason; message };
+suggestionPayloadSha(payload); canonicalJson(value); sha256Hex(text); gitBlobSha(text);
+suggestionLabels(payload, { state?, labels? }); suggestionIssueTitle(payload); suggestionStatus({ state, stateReason?, linkedPrs?, review?, applied?, outdated? });
+suggestionPathProblems(payload, config): string[];    unsafePathProblem(path): string | null;
+summarizeSuggestionApprovals(comments, { owners, rights?, teams? }, { payloadSha, author? }); suggestionReviewState(tier, approvals);
+composeSuggestionReviewComment(record); parseSuggestionReviewComment(body); composeSuggestionAppliedComment(record); parseSuggestionAppliedComment(body);
+// GitHub (Issues read and write only)
+createSuggestionOnGitHub(gh, payload, opts); listSuggestionsOnGitHub(gh, { state? }); getSuggestionOnGitHub(gh, n, gov, { outdated? });
+reviewSuggestionOnGitHub(gh, n, { event, role?, message?, payloadSha? }, gov); linkSuggestionPrOnGitHub(gh, n, { pr?, branch?, commit?, payloadSha });
+declineSuggestionOnGitHub(gh, n, reason, by?); syncSuggestionStateLabel(gh, n, labels, status);
+```
+
 ## history (history.ts, history-github.ts, history-demo.ts)
 
 What changed in the tokens, when, who changed it and why, and how to undo it safely.

package/bridge.config.schema.json

@@ -650,6 +650,29 @@
         }
       }
     },
+    "changes": {
+      "enum": [
+        "suggest",
+        "direct"
+      ],
+      "default": "suggest",
+      "description": "How Bridge sends a change to the code. suggest (default): Bridge files a GitHub issue that holds the exact change (a suggestion); owners approve it and a developer applies it with their own access. direct: Bridge opens branches and pull requests itself, which needs Contents and Pull requests write. This file is a guardrail, so switching modes is a Tier 3 change."
+    },
+    "storybook": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "url"
+      ],
+      "description": "The deployed Storybook Bridge reads the component list and previews from. Absent: previews.production.storybook when it is set.",
+      "properties": {
+        "url": {
+          "type": "string",
+          "pattern": "^https://",
+          "description": "Root URL of the deployed Storybook (where index.json and iframe.html are served), https only."
+        }
+      }
+    },
     "visualImpact": {
       "type": "object",
       "additionalProperties": false,

package/dist/audit/index.js

@@ -1,6 +1,6 @@
-import { i as isAuditable, a as auditFile } from "../report-DY_peRy4.js";
-import { A, b, c, C, D, d, F, I, L, e, M, N, f, g, h, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, B, E, G, H, J, K, O, P, Q, R, S, T, U, V, W, X, Y, Z } from "../report-DY_peRy4.js";
-import { p as pieceId, a as proposedTokenPath, t as tokenLabel } from "../prod-branch-D5Tl87Wf.js";
+import { i as isAuditable, a as auditFile } from "../report-DOnKUw8G.js";
+import { A, b, c, C, D, d, F, I, L, e, M, N, f, g, h, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, B, E, G, H, J, K, O, P, Q, R, S, T, U, V, W, X, Y, Z } from "../report-DOnKUw8G.js";
+import { p as pieceId, a as proposedTokenPath, t as tokenLabel } from "../prod-branch-BdMPKffE.js";
 const lines = (text) => text.split(/\r?\n/);
 function lineBag(text) {
   const bag = /* @__PURE__ */ new Map();

package/dist/config.d.ts

@@ -4,6 +4,19 @@ 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";
+/**
+ * How Bridge sends a change to the code. "suggest": a GitHub issue that holds the exact change (suggestions.ts);
+ * owners approve it and a developer applies it with their own access. "direct": Bridge opens branches and pull
+ * requests itself. Absent from the file: "suggest".
+ */
+export type ChangesMode = 'suggest' | 'direct';
+export declare const CHANGES_MODES: readonly ChangesMode[];
+export declare const DEFAULT_CHANGES_MODE: ChangesMode;
+/** The deployed Storybook Bridge reads the component list and previews from. */
+export interface StorybookConfig {
+    /** Root URL (where index.json and iframe.html are served), https only, no trailing slash. */
+    url: string;
+}
 export interface RepoRef {
     owner: string;
     name: string;
@@ -154,6 +167,10 @@ export interface BridgeConfig {
     visualImpact?: VisualImpactConfig | undefined;
     /** Apps that consume the design system, the default one being the library (see products.ts). Default DEFAULT_PRODUCTS. */
     products: ProductConfig[];
+    /** How changes reach the code: suggestions (default) or branches and pull requests. See changesMode(). */
+    changes: ChangesMode;
+    /** The Storybook set in the file. Read it through storybookUrl(), which falls back to previews.production.storybook. */
+    storybook?: StorybookConfig | undefined;
 }
 type Partialish<T> = {
     [K in keyof T]?: T[K] | undefined;
@@ -214,6 +231,10 @@ export interface BridgeConfigInput {
     integrations?: IntegrationsConfig;
     visualImpact?: Partial<VisualImpactConfig>;
     products?: ProductConfig[];
+    changes?: ChangesMode;
+    storybook?: {
+        url: string;
+    };
 }
 export declare const DEFAULT_TOKEN_PATHS: TokenPaths;
 export declare const DEFAULT_GOVERNANCE: GovernanceConfig;
@@ -231,6 +252,13 @@ export declare const tokensPath: (config: BridgeConfig, rel?: string) => string;
 export declare const protectedBranchesOf: (config: BridgeConfig) => string[];
 /** The base branch proposals target. */
 export declare const baseBranchOf: (config: BridgeConfig) => string;
+/** How changes reach the code for this repo: the config's mode ("suggest" when the file does not say). */
+export declare const changesMode: (config: Pick<BridgeConfig, "changes"> | null | undefined) => ChangesMode;
+/**
+ * The Storybook to read: `storybook.url`, else the production Storybook of `previews` when it is https. Undefined
+ * when neither is set. No trailing slash.
+ */
+export declare function storybookUrl(config: Pick<BridgeConfig, 'storybook' | 'previews'> | null | undefined): string | undefined;
 /** Plain-JSON form of a config, in the canonical shape (what `bridge init` writes). */
 export declare function toConfigJson(config: BridgeConfig, schema?: string): Record<string, unknown>;
 export {};

package/dist/docs-proposal.d.ts

@@ -1,6 +1,9 @@
+import type { ChangesMode } from './config';
 import { type ComponentDocsJson } from './docs-draft';
 import type { GitHubClient, PullRequestSummary } from './github-client';
+import type { RequestSource } from './requests';
 import { type RiskResult } from './risk';
+import { type SuggestionPayloadV1 } from './suggestions';
 /** One component's docs.json, before (null: a new file) and after, at its repo path. */
 export interface DocsFileEdit {
     path: string;
@@ -114,13 +117,7 @@ export declare function docsProposal(edits: DocsFileEdit[], opts: {
     origin?: DocsOrigin | undefined;
     authorLine?: string | 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.
- * One open proposal per component: when the component already has one, the edit goes there as a new commit
- * (`continued`; `unchanged` when it already says this) instead of a second pull request.
- */
-export declare function proposeDocsOnGitHub(gh: GitHubClient, edits: DocsFileEdit[], opts: {
+export interface ProposeDocsOptions {
     base: string;
     title?: string | undefined;
     notes?: string | undefined;
@@ -131,16 +128,67 @@ export declare function proposeDocsOnGitHub(gh: GitHubClient, edits: DocsFileEdi
     commitNote?: string | undefined;
     /** Who wrote the text (docsAuthorLine). Without it, the origin's footer, never "no AI" over a Claude draft. */
     authorLine?: string | undefined;
-    /** Default true: continue the component's open proposal. False always opens a new one. */
+    /** Default true: continue the component's open proposal. False always opens a new one. Direct mode only. */
     continueOpen?: boolean | undefined;
-}): Promise<{
+    /**
+     * "direct" (default here, so existing callers keep their behaviour): a branch and a pull request. "suggest": a
+     * suggestion issue with the cleaned docs, no branch. Callers pass changesMode(config).
+     */
+    mode?: ChangesMode | undefined;
+    /** Suggest mode: where it was sent from (default from the origin: Studio, or MCP) and who sent it. */
+    source?: RequestSource | undefined;
+    suggestedBy?: string | undefined;
+    /** Suggest mode: commit sha of `base`, when the caller already read it. */
+    baseSha?: string | undefined;
+}
+export interface ProposedDocs {
+    status: 'opened' | 'continued';
     number: number;
     url: string;
     branch: string;
     title: string;
     continued: boolean;
     unchanged: boolean;
-}>;
+}
+export interface SuggestedDocs {
+    status: 'suggested';
+    /** The suggestion issue. */
+    number: number;
+    url: string;
+    title: string;
+    /** sha256 of the payload: what approvals bind to. */
+    sha: string;
+    warnings: string[];
+}
+/**
+ * The suggestion payload (bridge.suggestion/1, kind docs) of a set of docs edits: the cleaned docs object of each
+ * component (re-written at apply time as a minimal diff of the current file) and the patch changeset. Pure.
+ */
+export declare function docsSuggestionPayload(edits: DocsFileEdit[], opts: {
+    base: {
+        ref: string;
+        sha: string;
+    };
+    title?: string | undefined;
+    notes?: string | undefined;
+    date?: Date | undefined;
+    origin?: DocsOrigin | undefined;
+    source?: RequestSource | undefined;
+    suggestedBy?: string | undefined;
+    packageName?: string | undefined;
+    changesetDir?: string | undefined;
+}): SuggestionPayloadV1;
+/**
+ * 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.
+ * One open proposal per component: when the component already has one, the edit goes there as a new commit
+ * (`continued`; `unchanged` when it already says this) instead of a second pull request.
+ * In suggest mode (`mode: 'suggest'`) it files a suggestion instead: no branch, no pull request (`status: 'suggested'`).
+ */
+export declare function proposeDocsOnGitHub(gh: GitHubClient, edits: DocsFileEdit[], opts: ProposeDocsOptions & {
+    mode?: 'direct' | undefined;
+}): Promise<ProposedDocs>;
+export declare function proposeDocsOnGitHub(gh: GitHubClient, edits: DocsFileEdit[], opts: ProposeDocsOptions): Promise<ProposedDocs | SuggestedDocs>;
 /**
  * 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.

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

@@ -0,0 +1,143 @@
+import type { ChangesMode } from './config';
+import { type GitHubClient } from './github-client';
+import { type SuggestionPayloadV1 } from './suggestions';
+import type { TokenEdit } from './token-edits';
+import { type ComponentPushDiff, type ComponentPushPlan, type FigmaOrigin, type FigmaPushStatus, type PushTokenContext } from './figma-push';
+/**
+ * Opens the token change of an exact push: the caller plans it on the library's token files (planTokenProposal). In
+ * suggest mode (`mode`), it files a suggestion instead (suggestTokenProposalOnGitHub with `links: { figma }`) and
+ * returns its result: a result with `status: 'suggested'` is reported as a suggestion.
+ */
+export type FigmaTokenWriter = (input: {
+    edits: TokenEdit[];
+    title: string;
+    summary: string;
+    bodyExtra: string[];
+    mode: ChangesMode;
+    /** The Figma component, for the suggestion's links. */
+    figma: {
+        fileKey?: string | undefined;
+        nodeId?: string | undefined;
+        url?: string | undefined;
+    };
+}) => Promise<{
+    number: number;
+    url: string;
+    branch: string;
+    status?: undefined;
+} | {
+    status: 'suggested';
+    number: number;
+    url: string;
+}>;
+export interface OpenComponentPushInput {
+    diff: ComponentPushDiff;
+    /** Token facts to route it (planComponentPush), or the route already planned with every component of the file. */
+    tokens?: PushTokenContext | undefined;
+    plan?: ComponentPushPlan | undefined;
+    /** Branch library work starts from (the default branch). */
+    base: string;
+    /** governance.branchPrefix ("bridge/"). */
+    branchPrefix: string;
+    /** Labels the repo adds to every Bridge branch (governance.labels), before the Figma ones. */
+    labels?: string[] | undefined;
+    /** The token change of an exact push (planTokenProposal + writeTokenProposalOnGitHub where the token files are read). */
+    writeTokens?: FigmaTokenWriter | undefined;
+    /** "the DS Bridge Figma plugin", "Bridge MCP". */
+    tool?: string | undefined;
+    dryRun?: boolean | undefined;
+    /**
+     * "direct" (default here, so existing callers keep their behaviour): a branch and a pull request. "suggest": a
+     * suggestion issue (a token change, or a component spec for Claude), no branch. Callers pass changesMode(config).
+     */
+    mode?: ChangesMode | undefined;
+    /** Who sends it (a GitHub login), recorded on a suggestion. Defaults to the diff's requestedBy. */
+    suggestedBy?: string | undefined;
+    /** Commit sha of `base`, when the caller already read it (a component spec suggestion records it). */
+    baseSha?: string | undefined;
+}
+export interface OpenedComponentPush {
+    status: 'opened' | 'suggested' | 'dry-run' | 'not-sent';
+    plan: ComponentPushPlan;
+    /** The library branch: a token change or a Claude draft branch (a draft pull request). Null when suggested. */
+    link: {
+        route: 'token-change' | 'claude-draft';
+        number: number;
+        url: string;
+        branch: string;
+    } | null;
+    /** The suggestion issue (status 'suggested'): a token change, or a component spec Claude drafts the code from. */
+    suggestion?: {
+        route: 'token-change' | 'claude-draft';
+        number: number;
+        url: string;
+    } | undefined;
+}
+/** The suggestion payload (bridge.suggestion/1, kind component-spec) of a push that needs code. Pure. */
+export declare function componentSpecSuggestionPayload(d: ComponentPushDiff, plan: Pick<ComponentPushPlan, 'edits' | 'reasons' | 'issues'>, ctx: {
+    base: {
+        ref: string;
+        sha: string;
+    };
+    suggestedBy?: string | undefined;
+    createdAt?: string | undefined;
+    componentsDir?: string | undefined;
+}): SuggestionPayloadV1;
+/**
+ * Opens the library branch of a component change from Figma, linked to its origin (the Figma component): an exact token
+ * swap opens a token change (the shared proposal write: contrast gate, tier, changeset); anything that needs code opens
+ * a draft pull request carrying the spec (`.bridge/figma/<slug>.json`), labelled waiting for Claude. A manual change
+ * opens nothing: its issues say what to do in Figma.
+ * In suggest mode: the token swap is a token suggestion (through `writeTokens`), the code change a component spec
+ * suggestion (the spec inside the payload, labelled from Figma and waiting for Claude). Issues write only.
+ */
+export declare function openComponentPushOnGitHub(gh: GitHubClient, input: OpenComponentPushInput): Promise<OpenedComponentPush>;
+export interface FigmaChangeRow {
+    number: number;
+    title: string;
+    url: string;
+    branch: string;
+    origin: FigmaOrigin;
+    status: FigmaPushStatus;
+}
+/** Library branches opened from Figma components (label from-figma), newest first, with where each stands. */
+export declare function listFigmaChangesOnGitHub(gh: GitHubClient, opts?: {
+    state?: 'open' | 'closed' | 'all';
+}): Promise<FigmaChangeRow[]>;
+/** One library branch from Figma, its spec and Claude's brief to draft the code. */
+export declare function figmaChangeOnGitHub(gh: GitHubClient, n: number, opts?: {
+    componentsDir?: string | undefined;
+}): Promise<{
+    pull: import("./github-client").PullRequest & import("./github-client").PullRequestSummary & {
+        body: string;
+        mergeable: boolean | null;
+        requestedReviewers: string[];
+    };
+    origin: FigmaOrigin;
+    status: FigmaPushStatus;
+    spec: undefined;
+    brief: undefined;
+} | {
+    pull: import("./github-client").PullRequest & import("./github-client").PullRequestSummary & {
+        body: string;
+        mergeable: boolean | null;
+        requestedReviewers: string[];
+    };
+    origin: FigmaOrigin;
+    status: FigmaPushStatus;
+    spec: ComponentPushDiff & {
+        tokenEdits?: TokenEdit[];
+        reasons?: string[];
+    };
+    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.
+ */
+export declare function markFigmaChangeDraftedOnGitHub(gh: GitHubClient, n: number): Promise<{
+    status: FigmaPushStatus;
+    files: string[];
+}>;
+/** 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

@@ -0,0 +1,204 @@
+import { type ComponentSpecsFile } from './component-spec';
+import { type RequestChange, type RequestKind, type RequestSource } from './requests';
+import type { TokenEdit } from './token-edits';
+import type { ContrastPair } from './wcag';
+/** Where a component change goes: a token change (exact), a library branch Claude drafts, or nowhere yet (manual). */
+export type PushRoute = 'token-change' | 'claude-draft' | 'manual';
+/** A token swap seen in Figma: in these variants, one property moved from one variable to another (token paths). */
+export interface Rebind {
+    /** Property family, as the scan names it: fill, stroke, radius, padding, gap, size, typography... */
+    kind: string;
+    /** Variant names ("Size=md, Tone=primary") where it moved. */
+    variants: string[];
+    /** Every variant of the component moved the same way. */
+    allVariants: boolean;
+    before: string[];
+    after: string[];
+}
+/** An edit the scan cannot read with confidence, and what the designer does about it. */
+export interface PushIssue {
+    what: string;
+    todo: string;
+}
+/**
+ * A component change from Figma, structured: what the designer sees in the Push tab, and what the library branch
+ * carries as its spec (the JSON Claude reads to write the code).
+ */
+export interface ComponentPushDiff {
+    v: 1;
+    /** Coded name ("Button"), or the proposed name of a new component ("DatePicker"). */
+    component: string;
+    /** Name of the set in Figma ("Forms / Date picker"). */
+    figmaName: string;
+    /** The component has a folder in code. */
+    coded: boolean;
+    kind: RequestKind;
+    /** One line, sentence case: "Add a lg size". */
+    title: string;
+    summary: string;
+    /** What changes, in one sentence. */
+    line?: string | undefined;
+    /** The rows of the change, as the Push tab lists them. */
+    changes: RequestChange[];
+    /** Token swaps, for the exact route. */
+    rebinds: Rebind[];
+    /** Something only code can carry: a variant, a property, layers, a swapped instance, a new component. */
+    needsCode: boolean;
+    /** Edits the scan cannot read with confidence: listed with what to do, never sent. */
+    unknown: PushIssue[];
+    figma?: {
+        fileKey?: string | undefined;
+        nodeId?: string | undefined;
+        nodeName?: string | undefined;
+        url?: string | undefined;
+    } | undefined;
+    /** The component as Figma has it now: variant axes, properties, bound variables (token paths) per variant. */
+    variantAxes: Record<string, string[]>;
+    properties: {
+        name: string;
+        type: string;
+        default: string;
+    }[];
+    bindings: Record<string, Record<string, string[]>>;
+    /** Layers of each variant, in order, as words ("instance Icon/Pencil, \"Icon\""). */
+    anatomy: Record<string, string[]>;
+    /** What code gave Figma at the last pull, when known. */
+    before?: {
+        variantAxes: Record<string, string[]>;
+        properties: {
+            name: string;
+            type: string;
+            default: string;
+        }[];
+    } | undefined;
+    /** Screenshot URLs (Figma exports on the requests branch). */
+    images?: string[] | undefined;
+    source: RequestSource;
+    requestedBy?: string | undefined;
+}
+/** What the plan needs to know about tokens, from wherever the caller reads them (the plugin, the MCP server). */
+export interface PushTokenContext {
+    /** Tier of a token path ("component", "semantic"...), undefined when the library has no such token. */
+    tierOf(path: string): string | undefined;
+    /**
+     * Where else this token paints: variants of the same component outside the swap ("Size=sm, Variant=primary"), and
+     * other components ("IconButton"). Empty lists: nowhere else.
+     */
+    usedElsewhere(path: string, rebind: Rebind): {
+        variants: string[];
+        components: string[];
+    };
+}
+export interface ComponentPushPlan {
+    route: PushRoute;
+    /** One sentence in designer words: what happens when it is sent. */
+    said: string;
+    /** Exact token edits: the whole change (token-change), or the part Claude makes too (claude-draft). */
+    edits: TokenEdit[];
+    /** Why a token swap needs Claude rather than a token change, one sentence each. */
+    reasons: string[];
+    /** Listed with what to do, never sent. */
+    issues: PushIssue[];
+    /** Other components an exact token change also repaints (they share the component token): said, for review. */
+    alsoChanges: string[];
+}
+/**
+ * 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;
+ * what cannot be read with confidence is listed with what to do.
+ */
+export declare function planComponentPush(d: ComponentPushDiff, ctx: PushTokenContext): ComponentPushPlan;
+/**
+ * Where else a token paints, from component-specs.json (what code gives each component): the variants of `component`
+ * outside the swap, and the other components. For tools that read the code, not a Figma file (the MCP server, the CLI).
+ */
+export declare function specsUsage(specs: Pick<ComponentSpecsFile, 'components'>, component: string): PushTokenContext['usedElsewhere'];
+/**
+ * The contrast gate for component token swaps. contrast.checks.json lists semantic pairs (action text on action bg);
+ * a component token that aliases one side of a pair is checked in its place, against the component token that aliases
+ * the other side (button.primary.text on button.primary.bg), else against that other side itself. So pointing
+ * button.primary.bg to a pale variable fails the same way the semantic pair would.
+ */
+export declare function componentContrastPairs(edits: readonly Pick<TokenEdit, 'path'>[], pairs: readonly ContrastPair[], tokens: {
+    aliasOf(path: string): string | undefined;
+    paths: readonly string[];
+}): ContrastPair[];
+/** Every library branch opened from a Figma component carries this label. */
+export declare const FROM_FIGMA_LABEL = "from-figma";
+/** A Claude draft branch that carries the spec only: no code yet. */
+export declare const WAITING_FOR_CLAUDE_LABEL = "waiting-for-claude";
+/** A Claude draft branch once Claude wrote the code: a person reviews it. */
+export declare const DRAFTED_BY_CLAUDE_LABEL = "drafted-by-claude";
+/** Where a Claude draft branch keeps the spec it was opened with. */
+export declare const FIGMA_SPEC_DIR = ".bridge/figma";
+export type FigmaOriginStatus = 'spec' | 'drafted';
+/** What the library branch remembers about where it came from: the Figma component and how it was routed. */
+export interface FigmaOrigin {
+    component: string;
+    figmaName: string;
+    route: Exclude<PushRoute, 'manual'>;
+    kind: RequestKind;
+    nodeId?: string | undefined;
+    fileKey?: string | undefined;
+    url?: string | undefined;
+    /** Claude draft branches: the spec file, and whether Claude wrote the code yet. */
+    spec?: string | undefined;
+    status?: FigmaOriginStatus | undefined;
+    requestedBy?: string | undefined;
+}
+export declare function parseFigmaOrigin(body: string | null | undefined): FigmaOrigin | undefined;
+/** The "From Figma" lines people read on GitHub, then the hidden block tools read. */
+export declare function figmaOriginSection(o: FigmaOrigin): string;
+/** The body with the "From Figma" section first (replacing an earlier one). */
+export declare function withFigmaOrigin(body: string | null | undefined, o: FigmaOrigin): string;
+export declare const figmaSpecSlug: (d: Pick<ComponentPushDiff, "component" | "title">) => string;
+/** The spec file of a Claude draft branch. */
+export declare const figmaSpecPath: (d: Pick<ComponentPushDiff, "component" | "title">) => string;
+/** The structured diff as the spec file stores it (stable key order, two-space JSON). */
+export declare function formatFigmaSpec(d: ComponentPushDiff, plan: Pick<ComponentPushPlan, 'edits' | 'reasons' | 'issues'>): string;
+/** Reads a spec file back; undefined when it is not one. */
+export declare function parseFigmaSpec(text: string | null | undefined): (ComponentPushDiff & {
+    tokenEdits?: TokenEdit[];
+    reasons?: string[];
+}) | undefined;
+/**
+ * What Claude gets to draft the code on the branch (MCP `bridge_get_figma_change`, CLI `bridge figma show`): the change,
+ * the spec, the exact token swaps to make too, the rules, and how to say it is drafted.
+ */
+export declare function figmaDraftBrief(d: ComponentPushDiff & {
+    tokenEdits?: TokenEdit[] | undefined;
+    reasons?: string[] | undefined;
+}, ctx: {
+    pr: number;
+    branch: string;
+    specPath: string;
+    componentsDir?: string | undefined;
+    agentsFile?: string | undefined;
+} | {
+    suggestion: true;
+    specPath: string;
+    componentsDir?: string | undefined;
+    agentsFile?: string | undefined;
+}): string;
+/** The pull request body of a Claude draft branch: the origin, the change, the rows and the spec. */
+export declare function figmaDraftBody(d: ComponentPushDiff, plan: Pick<ComponentPushPlan, 'edits' | 'reasons' | 'issues'>, o: FigmaOrigin): string;
+/** The title of a library branch opened from Figma: "Button: add a lg size". */
+export declare const figmaBranchTitle: (d: Pick<ComponentPushDiff, "component" | "title">) => string;
+export type FigmaPushStatusKey = 'waiting-for-claude' | 'drafted' | 'in-review' | 'shipped' | 'closed';
+export interface FigmaPushStatus {
+    key: FigmaPushStatusKey;
+    /** "Waiting for Claude AI", "Shipped". */
+    label: string;
+    /** One sentence for the designer. */
+    sentence: string;
+    /** The Figma component should be rebuilt from code (the branch shipped or was closed). */
+    rebuild: boolean;
+}
+/** Where a library branch opened from Figma stands, from its state and labels. */
+export declare function figmaPushStatus(x: {
+    state: string;
+    draft?: boolean | undefined;
+    labels?: readonly string[] | undefined;
+    route?: PushRoute | undefined;
+}): FigmaPushStatus;

package/dist/github-client.d.ts

@@ -302,12 +302,17 @@ export declare class GitHubClient {
     /** Best effort: labels need the repo to allow it; failure is not fatal. */
     addLabels(issueNumber: number, labels: string[]): Promise<boolean>;
     addComment(issueNumber: number, body: string): Promise<void>;
-    /** Comments on an issue or pull request, oldest first (first 100: the sticky preview comment is posted early). */
+    /**
+     * Comments on an issue or pull request, oldest first (first 100: the sticky preview comment is posted early).
+     * `authorAssociation` is GitHub's OWNER, MEMBER, COLLABORATOR, CONTRIBUTOR, NONE... (suggestion approvals read it).
+     */
     listIssueComments(issueNumber: number): Promise<{
         id: number;
         body: string;
         author: string;
         updatedAt: string;
+        createdAt: string;
+        authorAssociation: string;
     }[]>;
     createIssue(input: {
         title: string;

package/dist/index.d.ts

@@ -57,3 +57,9 @@ export * from './products';
 export * from './prod-branch';
 export * from './prod-branch-github';
 export * from './token-proposal';
+export * from './figma-push';
+export * from './figma-push-github';
+export * from './suggestions';
+export * from './suggestion-review';
+export * from './suggestions-github';
+export * from './suggestion-apply';