@bridge-ds/core 0.18.0 → 0.20.0

package/dist/requester.d.ts

@@ -0,0 +1,14 @@
+export interface Requester {
+    /** The display name, when the line gives one. */
+    name: string | null;
+    /** The GitHub login, without "@", when the line gives one. */
+    login: string | null;
+}
+/** The neutral author of a change whose requester deleted their Bridge account (api/account rewrites the line). */
+export declare const FORMER_MEMBER = "A former member";
+/** How a sentence names a requester by first name ("Waiting for Priya"): the former member stays whole. */
+export declare const requesterFirstName: (name: string) => string;
+/** The requester a body names, null when it names none (or names it in a form Bridge does not write). */
+export declare function requesterOf(body: string | null | undefined): Requester | null;
+/** The line Bridge writes for a requester: "Requested by Ann Leroy (@annleroy)." */
+export declare function requesterLine(r: Requester): string;

package/dist/requests.d.ts

@@ -45,6 +45,8 @@ export interface ComponentChangeRequest {
      * `exploration` label and the brief says to work on that branch (docs/EXPLORATIONS.md).
      */
     exploration?: string | undefined;
+    /** Build request details (before and after images, props needed, spec path): build-requests.ts. */
+    build?: import('./build-requests').BuildRequestExtra | undefined;
 }
 export interface RequestIssue {
     title: string;

package/dist/review-gate.d.ts

@@ -1,3 +1,4 @@
+import type { FigmaPush } from './build-requests';
 import type { OverridePolicy } from './config';
 import { type ShipPolicy } from './rights';
 import { type RiskTier } from './risk';
@@ -12,8 +13,22 @@ export interface PullStateLike {
     draft?: boolean;
     merged?: boolean;
     merged_at?: string | null;
+    /** GitHub labels (objects or names): `drafted-by-claude` makes a draft ready for review (isDraft). */
+    labels?: readonly ({
+        name?: string;
+    } | string)[] | null | undefined;
 }
 export type PullState = 'merged' | 'closed' | 'draft' | 'open';
+/**
+ * Where Claude stands on a library branch opened from Figma (figma-push labels): `waiting` while it carries the spec
+ * only (a developer builds it with Claude), `drafted` once the code is written. Null on any other branch.
+ */
+export declare function claudeStage(labels: PullStateLike['labels']): 'waiting' | 'drafted' | null;
+/**
+ * A draft on GitHub that still reads as one. Decision RT-1: once Claude drafted the code (`drafted-by-claude`), the
+ * branch is ready for review even while GitHub still calls it a draft; the merge marks it ready first (branch-actions).
+ */
+export declare const isDraft: (p: Pick<PullStateLike, "draft" | "labels">) => boolean;
 /** Merged wins over closed (GitHub reports merged pull requests as closed), closed over draft, draft over open. */
 export declare function pullState(p: PullStateLike): PullState;
 /** Label and pill tone of each state, for list and detail views. */
@@ -33,7 +48,13 @@ export interface CiStatusLike {
     context: string;
     state: 'success' | 'failure' | 'error' | 'pending' | string;
     target_url?: string | null;
+    description?: string | null;
 }
+/**
+ * A status the hosting platform posts when it refused to run at all (Vercel "Deployment rate limited"): it says nothing
+ * about the change, and GitHub does not require it, so it never counts as a failed check.
+ */
+export declare function isPlatformRefusal(s: Pick<CiStatusLike, 'state' | 'description'>): boolean;
 export type CiState = 'pass' | 'fail' | 'pending' | 'none';
 export interface CiSummary {
     state: CiState;
@@ -56,13 +77,29 @@ export interface ReviewLike {
     } | null;
     state: 'APPROVED' | 'CHANGES_REQUESTED' | 'COMMENTED' | 'DISMISSED' | 'PENDING' | string;
     submitted_at?: string | null;
+    /** The commit the review was given on (GitHub `commit_id`): tells whether the branch moved on since. */
+    commit_id?: string | null;
 }
 export interface ApprovalSummary {
     approvers: string[];
     changesRequested: string[];
     design: boolean;
     tech: boolean;
+    /**
+     * One owner approved (design or tech list, teams expanded): the Tier 1 rule of docs/GOVERNANCE.md, "1 code owner",
+     * the same as Settings says ("one owner"). With no owner configured, any approval counts. Absent (a summary built by
+     * hand): any approval counts.
+     */
+    owner?: boolean;
+    /**
+     * A token value change (withTokenValueApprovals, decision TV-1 in docs/BUILD-REQUESTS.md): token values changed or
+     * tokens added, nothing renamed or removed, no code. The design approval is all it needs: once it is in, `tech` counts
+     * as given and the change ships after the automatic checks. mergeGate never asks for the tech approval then.
+     */
+    valuesOnly?: boolean;
 }
+/** Whether the Tier 1 approval is in: one owner approved (GOVERNANCE.md "1 code owner"), else any approval without owners. */
+export declare const hasOwnerApproval: (a: ApprovalSummary) => boolean;
 export interface ApprovalRules {
     /**
      * `governance.soloOwnerCanApproveBoth`: when the owners resolve to one person holding both roles, that person's
@@ -75,6 +112,41 @@ export declare function summarizeApprovals(reviews: ReviewLike[], owners: {
     design: string[];
     tech: string[];
 }, author?: string, rules?: ApprovalRules): ApprovalSummary;
+/**
+ * The reviewers to look again: the author updated the branch after every changes request that still counts (the
+ * latest decisive review of each of those reviewers was given on a commit other than `headSha`). Then it is the
+ * reviewers' turn, not the author's, like GitHub's re-request but read from what happened (an email member cannot
+ * request reviewers). Empty while one request was given on the current head, or a review does not say its commit.
+ * The merge gate is unchanged: the changes request still blocks until that reviewer approves.
+ */
+export declare function lookAgainReviewers(reviews: ReviewLike[], headSha: string | null | undefined, author?: string): string[];
+/**
+ * The approvals a pull request carries from the Bridge suggestion it applies (its body says "Closes #n"): the owners
+ * approved that exact change on the suggestion, so the pull request that applies it is not gated a second time for the
+ * same approval (docs/GOVERNANCE.md, Suggestions). Only when the suggestion is approved (every approval its tier needs,
+ * no changes requested) and the pull request's tier is not higher than the tier it was approved at. Changes requested
+ * on the pull request itself still block, and CI, conflicts and the ship right gate the merge as before.
+ */
+export declare function withSuggestionApprovals(pr: ApprovalSummary, suggestion: {
+    approvals: ApprovalSummary;
+    tier: RiskTier;
+} | null | undefined, prTier: RiskTier | null | undefined): ApprovalSummary;
+/**
+ * The approvals a push from the Figma plugin carries (docs/BUILD-REQUESTS.md): a push counts as design-approved, since
+ * keeping unvalidated work out of Figma main is the team's discipline. Token values only (scope `token-values`) also
+ * count as tech-approved: they ship after the automatic checks. A rename or removal, code, or unread token changes still
+ * need the tech approval. A guardrail file (`outside`) gets no credit. Changes requested on the pull request, CI, a
+ * conflict and the ship right gate the merge as before.
+ */
+export declare function withFigmaPushApprovals(pr: ApprovalSummary, push: FigmaPush | null | undefined): ApprovalSummary;
+/**
+ * Decision TV-1 (docs/BUILD-REQUESTS.md, "Token values from Studio"): a token value change follows the rule of a push
+ * from Figma, whoever opened it (Studio, the CLI, the MCP server, an agent). Once the design approval is given, it
+ * ships after the automatic checks with no developer code OK: the tech approval counts as given. A rename or removal,
+ * unread token changes, code or a guardrail file is not a value change (isTokenValueChange) and still needs it. Changes
+ * requested, CI, a conflict and the ship right gate the merge as before.
+ */
+export declare function withTokenValueApprovals(pr: ApprovalSummary, valuesOnly: boolean | null | undefined): ApprovalSummary;
 export type MissingApproval = 'design approval' | 'tech approval' | 'approval';
 export interface MergeGate {
     allowed: boolean;
@@ -88,6 +160,21 @@ export interface MergeGate {
 }
 /** Whether `login` may use the owner override. Case-insensitive, a leading @ is ignored. */
 export declare function canOverride(login: string | null | undefined, policy: OverridePolicy | null | undefined): boolean;
+/**
+ * Who may use the owner override: the logins `governance.override.allowed` names that are also owners (design or
+ * tech lists, teams expanded). docs/GOVERNANCE.md: "A listed owner may merge past missing approvals only". Settings,
+ * the Home and the branch page read this one list, so the override is never offered to someone who is not an owner.
+ * When an owner entry is a team whose members are not known (a "/" entry), the allowed list stands as it is.
+ */
+export declare function overrideHolders(policy: OverridePolicy | null | undefined, owners: {
+    design: string[];
+    tech: string[];
+}): string[];
+/** The override policy limited to its holders (overrideHolders): what the gate and the who-acts rules read. */
+export declare const ownerOverridePolicy: (policy: OverridePolicy | null | undefined, owners: {
+    design: string[];
+    tech: string[];
+}) => OverridePolicy | null;
 /**
  * Whether the Merge button is enabled, and why not. Mirrors docs/GOVERNANCE.md.
  * The owner override only ever covers missing approvals: CI failing or running, changes requested, a draft,
@@ -110,8 +197,96 @@ export declare function mergeGate(input: {
     ship?: ShipPolicy | null;
 }): MergeGate;
 /** The gate reason of a conflict, in the words a designer reads. Detected by identity, never by regex. */
+/**
+ * The verdict on one pull request, assembled once for every surface: Studio's branch page and row status, the MCP
+ * tools (bridge_branch_status, bridge_merge_branch, bridge_what_needs_me) and the CLI (`bridge branch status`,
+ * `bridge branch merge`). One composition of the rules of docs/GOVERNANCE.md, so a branch never reads ready in one
+ * place and blocked in another:
+ * - the pull request that applies an approved suggestion ("Closes #n") carries its approvals (withSuggestionApprovals);
+ * - the owner override is limited to the owners `governance.override.allowed` names (ownerOverridePolicy);
+ * - Tier 1 needs one owner approval (hasOwnerApproval, inside mergeGate and reviewStatusKind).
+ * `gate` is null while the tests or the reviews could not be read: an unknown read never reads as mergeable.
+ */
+export interface BranchVerdictInput {
+    tier: RiskTier | null;
+    ci: CiSummary | null;
+    /** The pull request's own approvals (summarizeApprovals); null when its reviews could not be read. */
+    approvals: ApprovalSummary | null;
+    /** The approved Bridge suggestion the pull request applies (approvedSuggestionOnGitHub), or null. */
+    suggestion?: {
+        approvals: ApprovalSummary;
+        tier: RiskTier;
+    } | null | undefined;
+    /** The approver lists (approverLists: rights applied, teams expanded). */
+    owners: {
+        design: string[];
+        tech: string[];
+    };
+    /** `governance.override` as configured; the verdict limits it to its owner holders. */
+    override?: OverridePolicy | null | undefined;
+    draft?: boolean | undefined;
+    /** The pull request's labels: `drafted-by-claude` reads a draft as ready for review (isDraft). */
+    labels?: PullStateLike['labels'];
+    mergeable?: boolean | null | undefined;
+    state?: string | undefined;
+    merged_at?: string | null | undefined;
+    /** Login of the viewer; null or absent leaves out who may ship and the override (signed out, no token). */
+    viewer?: string | null | undefined;
+    exploration?: boolean | undefined;
+    ship?: ShipPolicy | null | undefined;
+    /** Pushed from the Figma plugin (figmaPushOf): design approved by the push, tech too for token values only. */
+    figmaPush?: FigmaPush | null | undefined;
+    /**
+     * The pull request only changes token values (isTokenValueChange over its real files and token changes), whoever
+     * opened it: the design approval is all it needs (withTokenValueApprovals, decision TV-1). Absent: not known, the
+     * tech approval is still asked.
+     */
+    tokenValues?: boolean | null | undefined;
+    /**
+     * Auto-merge is armed on the pull request (GitHub `auto_merge` set): Bridge armed a token value change once its design
+     * approval was in (/api/ship, decision TV-1). With `tokenValues` and the design approval, it reads `autoShip`.
+     */
+    autoMerge?: boolean | null | undefined;
+    /**
+     * A lead published this Tier 1 change without review (the app's review starts with TIER1_PUBLISH_HEADING, on the
+     * head commit; docs/GOVERNANCE.md "Tier 1 publish by leads"). With `autoMerge` and the checks not failing, it reads
+     * `autoShip`. A failing check drops it back to review: the status reads as any other change waiting for an approval.
+     */
+    tier1Published?: boolean | null | undefined;
+    /**
+     * The reviewers to look again (lookAgainReviewers over the reviews and the head sha): the author updated the branch
+     * after every changes request. The status stays `changes-requested` and the merge stays blocked; only its words say
+     * "Updated, look again".
+     */
+    lookAgain?: readonly string[] | null | undefined;
+}
+export interface BranchVerdict {
+    /** The approvals the gate counts: the pull request's own plus the ones carried from its approved suggestion. */
+    approvals: ApprovalSummary | null;
+    /** The owner override as the gate reads it: its holders only. Null when none is configured. */
+    override: OverridePolicy | null;
+    gate: MergeGate | null;
+    status: ReviewStatusKind;
+    /** The words of the status, the same in Studio, the MCP server and the CLI (reviewStatusLabel). */
+    label: string;
+    /** Reviewers to look again (the input's lookAgain while changes are requested), else empty. */
+    lookAgain: string[];
+    /**
+     * A token push from Figma with values only, still open: Bridge merges it once the automatic checks pass, nobody
+     * reviews it. Also a token value change whose design approval is in and whose merge Bridge armed (`autoMerge`,
+     * decision TV-1). Review queues and "Needs you" leave it out; Studio shows "On its way to the library".
+     */
+    autoShip: boolean;
+}
+export declare function branchVerdict(input: BranchVerdictInput): BranchVerdict;
 export declare const CONFLICT_REASON = "It conflicts with main: resolve it with Update from main on the branch.";
 export declare const OVERRIDE_HEADING = "**Bridge owner override**";
+/**
+ * The shortest override reason accepted. docs/GOVERNANCE.md: the reason is always required, at least
+ * `minReasonLength` characters (20 by default). `requireReason: false` no longer waives it: an override without a
+ * reason would leave the audit trail empty.
+ */
+export declare function overrideReasonMin(policy: Pick<OverridePolicy, 'minReasonLength'>): number;
 /** Problem with an override reason, or null when it is accepted. */
 export declare function overrideReasonProblem(reason: string, policy: OverridePolicy): string | null;
 /**
@@ -163,6 +338,7 @@ export declare const REVIEW_STATUS_ORDER: Record<ReviewStatusKind, number>;
 export declare function reviewStatusKind(input: {
     state?: string;
     draft?: boolean;
+    labels?: PullStateLike['labels'];
     merged_at?: string | null;
     ci: CiSummary | null;
     approvals: ApprovalSummary | null;
@@ -174,6 +350,14 @@ export declare function reviewStatusKind(input: {
  * working out whether an approved branch merges cleanly; it never stands for missing tests.
  */
 export declare const REVIEW_STATUS_LABEL: Record<ReviewStatusKind, string>;
+/** The words of a branch the author updated after every changes request: the reviewers who asked look again. */
+export declare const LOOK_AGAIN_STATUS_LABEL = "Updated, look again";
+/**
+ * The words of a status. Changes requested on a branch the author updated since (lookAgainReviewers not empty) reads
+ * "Updated, look again", never the stale "Changes requested": the merge gate is the same, the next step is the
+ * reviewers'.
+ */
+export declare function reviewStatusLabel(kind: ReviewStatusKind, lookAgain?: readonly string[] | null): string;
 /** The words of a CI summary. A repo without automated checks reads as that, calmly, never as pending or unknown. */
 export declare const CI_STATE_LABEL: Record<CiState, string>;
 export interface QueuePull extends PullStateLike {
@@ -233,8 +417,11 @@ export declare function reopenEligibility(x: {
     branch: 'exists' | 'gone' | 'unknown';
 }): ReopenEligibility;
 export type ApprovalRole = 'design' | 'tech' | 'approval';
-/** The approvals a tier needs, as mergeGate counts them (Tier 2 and 3: design and tech; Tier 1: one approval). */
-export declare function requiredApprovals(tier: RiskTier | null): ApprovalRole[];
+/**
+ * The approvals a tier needs, as mergeGate counts them (Tier 2 and 3: design and tech; Tier 1: one approval). A token
+ * value change (`valuesOnly`, withTokenValueApprovals) needs the design approval only.
+ */
+export declare function requiredApprovals(tier: RiskTier | null, valuesOnly?: boolean | null): ApprovalRole[];
 /** The approvals still missing on a branch, from its tier and the reviews read (empty when either is unknown). */
 export declare function pendingApprovals(tier: RiskTier | null | undefined, approvals: ApprovalSummary | null | undefined): ApprovalRole[];
 /**

package/dist/risk.d.ts

@@ -32,6 +32,18 @@ export interface RiskResult {
     bump?: SemverBump | undefined;
 }
 export declare const RISK_LABELS: Record<RiskTier, string>;
+/**
+ * The tier line of a token change pushed from the Figma plugin (docs/BUILD-REQUESTS.md): a push is design-approved, so
+ * the approvals part of RISK_LABELS would mislead. Token values ship once the checks pass; a rename or a removal waits for
+ * a developer OK. Keeps "Tier N" first so parseTier reads it. Same rule as branchVerdict `autoShip`.
+ */
+export declare function figmaPushTierLabel(tier: RiskTier, changes: readonly {
+    kind: TokenChangeKind | string;
+}[]): string;
+/** The sentence after it: what happens next to a token change pushed from Figma. */
+export declare const figmaPushNextLine: (changes: readonly {
+    kind: TokenChangeKind | string;
+}[]) => string;
 /** Kind and description-only flag of any token change. */
 export declare function summarizeTokenChange(c: AcceptedChange | TokenChangeSummary): TokenChangeSummary;
 /** Semver bump of a set of token changes: renames and removals major, other changes minor, descriptions patch. */

package/dist/share-branch.d.ts

@@ -1,5 +1,5 @@
 /** The dialog's explanation, in designer words. */
-export declare const SHARE_EXPLAIN = "Product teams can install this branch in their app before it is merged, and remove it any time.";
+export declare const SHARE_EXPLAIN = "Product teams can install this change in their app before it is in the library, and remove it any time.";
 export type ChangeLifecycle = 'open' | 'draft' | 'merged' | 'closed';
 type Source = 'pkg.pr.new' | 'release' | 'other';
 export type ShareState = 

package/dist/snapshot.d.ts

@@ -1,6 +1,8 @@
 import type { AuditMetrics, AuditReport } from './audit/types';
+import type { ChangelogReleaseRow } from './changelog-model';
 import type { ContrastPairResult } from './contrast-model';
 import type { SpecCoverage } from './component-spec';
+import { type MotionDocs } from './motion-docs';
 import { type RepoSource } from './repo-source';
 import type { RepoModel } from './repo-model';
 export declare const SNAPSHOT_SCHEMA_VERSION = 1;
@@ -10,6 +12,17 @@ export declare const SNAPSHOT_FILE = "snapshot.json";
 export declare const SNAPSHOT_AUDITS_DIR = "audits";
 /** Above this, a snapshot is refused (a published file the browser downloads whole). */
 export declare const SNAPSHOT_MAX_BYTES = 5000000;
+/** Releases a snapshot keeps, newest first (the pending one counts); older ones stay in the CHANGELOG.md files. */
+export declare const SNAPSHOT_MAX_RELEASES = 60;
+/** A workspace package of the repository, for the Library's Install page. */
+export interface SnapshotPackage {
+    name: string;
+    version: string;
+    /** Not published to npm. */
+    private: boolean;
+    /** Repo-relative folder ("." for the root package). */
+    dir: string;
+}
 /** One adoption audit: the summary lives in snapshot.json, the full report in audits/<id>.json next to it. */
 export interface SnapshotAudit {
     id: string;
@@ -85,6 +98,19 @@ export interface RepoSnapshot {
      * written before Bridge read global stylesheets: a reader then reads those files from the repository.
      */
     styles?: string[];
+    /**
+     * Releases from the packages' CHANGELOG.md files and the pending changesets, newest first, at most
+     * SNAPSHOT_MAX_RELEASES. Dates come from release tags or git history, absent when the clone has neither. Absent from
+     * a snapshot written before Bridge read releases, or when the repository has no changelog.
+     */
+    releases?: ChangelogReleaseRow[];
+    /** Workspace packages (name, version, private, folder). Absent from a snapshot written before Bridge read them. */
+    packages?: SnapshotPackage[];
+    /**
+     * Motion and interaction docs per component (motionDocs), keyed by component name, computed from the specs file the
+     * snapshot does not carry. Absent without a readable specs file or a component scan.
+     */
+    motion?: Record<string, MotionDocs>;
 }
 export declare class SnapshotError extends Error {
 }
@@ -120,7 +146,15 @@ export interface BuildSnapshotInput {
     committedAt?: string;
     generatedAt?: string;
     audits?: SnapshotAudit[];
+    /** collectReleases() of the repository; kept to the newest SNAPSHOT_MAX_RELEASES. */
+    releases?: ChangelogReleaseRow[];
+    packages?: SnapshotPackage[];
 }
+/**
+ * Motion docs of every scanned component, from the parsed specs file: what the Library's motion section shows. Null
+ * without a specs file or a component scan.
+ */
+export declare function snapshotMotion(model: Pick<RepoModel, 'components' | 'specs'>): Record<string, MotionDocs> | null;
 /** Counts of a model for the snapshot summary. */
 export declare function snapshotSummary(model: RepoModel): SnapshotSummary;
 /** Assembles the snapshot from a model and the files it was read from. The specs file becomes the coverage list. */

package/dist/suggestion-review.d.ts

@@ -1,5 +1,5 @@
-import type { Owners } from './config';
-import { type ApprovalRole, type ApprovalSummary } from './review-gate';
+import type { OverridePolicy, Owners } from './config';
+import { type ApprovalRole, type ApprovalSummary, type MissingApproval } from './review-gate';
 import { type Rights } from './rights';
 import type { RiskTier } from './risk';
 import type { TeamStates } from './teams';
@@ -51,13 +51,54 @@ export interface SuggestionGovernance {
     teams?: TeamStates | null | undefined;
     /** `governance.soloOwnerCanApproveBoth`: the only owner's approval covers design and tech (review-gate summarizeApprovals). */
     soloOwnerCanApproveBoth?: boolean | undefined;
+    /**
+     * `governance.override`: an owner it allows, whom nobody else can review, approves their own suggestion as owner with
+     * a written reason (suggestionOverrideOf, docs/GOVERNANCE.md "Owner override"). Absent: no override.
+     */
+    override?: OverridePolicy | null | undefined;
 }
 export interface SuggestionApprovals extends ApprovalSummary {
     /** People whose latest review is on an older payload: it no longer counts. */
     stale: string[];
     /** People whose review does not count because they are not owners (or not collaborators when no owner is set). */
     ignored: string[];
+    /** Approved with the owner override on this version (suggestionOverrideOf): who, why, and what it went without. */
+    override?: SuggestionOverrideRecord | undefined;
 }
+export declare const SUGGESTION_OVERRIDE_MARK = "bridge-suggestion-override";
+export interface SuggestionOverrideRecord {
+    login: string;
+    reason: string;
+    missing: string[];
+    /** The version it was approved on (suggestionPayloadSha). */
+    payloadSha: string;
+}
+/** The override comment: the PR override's audit line ("Approved as owner from Bridge."), the version, the record. */
+export declare function composeSuggestionOverrideComment(r: {
+    login: string;
+    reason: string;
+    missing: MissingApproval[];
+    payloadSha: string;
+}): string;
+/** Reads an override comment on a suggestion back; null for any other comment. */
+export declare function parseSuggestionOverrideComment(body: string | null | undefined): SuggestionOverrideRecord | null;
+/**
+ * Who may approve this suggestion as owner, and why not: an owner `governance.override` allows (overrideHolders), on
+ * their own suggestion, when nobody else in the approver lists can review it. Null when they may.
+ */
+export declare function suggestionOverrideProblem(x: {
+    viewer: string | null | undefined;
+    author: string;
+    gov: SuggestionGovernance;
+}): string | null;
+/**
+ * The owner override in force on this version: the latest override comment for `payloadSha`, posted by the person it
+ * names, who may use it (suggestionOverrideProblem) with a reason long enough. Null otherwise.
+ */
+export declare function suggestionOverrideOf(comments: readonly SuggestionCommentLike[], gov: SuggestionGovernance, opts: {
+    payloadSha: string;
+    author?: string | null | undefined;
+}): SuggestionOverrideRecord | null;
 /**
  * Approvals on a suggestion, as summarizeApprovals counts them on a pull request, from the review comments: only
  * comments by people in the approver lists (governance owners and rights) count; with no owner configured at all, only
@@ -68,6 +109,8 @@ export interface SuggestionApprovals extends ApprovalSummary {
 export declare function summarizeSuggestionApprovals(comments: readonly SuggestionCommentLike[], gov: SuggestionGovernance, opts: {
     payloadSha: string;
     author?: string | null | undefined;
+    /** A token value suggestion (suggestionIsTokenValues): the design approval is all it needs (decision TV-1). */
+    valuesOnly?: boolean | undefined;
 }): SuggestionApprovals;
 /** The review state for the status machine: changes requested beats approved; approved when no approval is missing. */
 export declare function suggestionReviewState(tier: RiskTier, approvals: ApprovalSummary): 'needs-review' | 'changes-requested' | 'approved';

package/dist/suggestions-github.d.ts

@@ -1,7 +1,8 @@
 import { GitHubClient, type IssueSummary, type PullRequestSummary } from './github-client';
+import { type Requester } from './requester';
 import { type SuggestionAppliedRecord, type SuggestionApprovals, type SuggestionCommentLike, type SuggestionGovernance, type SuggestionReviewEvent } from './suggestion-review';
 import { type ComposeSuggestionOptions, type ParsedSuggestion, type SuggestionKind, type SuggestionPayloadV1, type SuggestionStatus } from './suggestions';
-import type { ApprovalRole } from './review-gate';
+import { type ApprovalRole } from './review-gate';
 import { type BridgeConfig } from './config';
 import { type SuggestionApplyOp, type SuggestionApplyPlan, type SuggestionWorkspace } from './suggestion-apply';
 export interface CreatedSuggestion {
@@ -32,6 +33,11 @@ export interface SuggestionListItem {
     title: string;
     url: string;
     author: string;
+    /**
+     * Who asked for it, as Bridge records it in the body ("Requested by Ann Leroy."): the person to show, since the
+     * GitHub author is often a lead or an agent acting for them. Null when the body names nobody.
+     */
+    requester: Requester | null;
     createdAt: string;
     state: 'open' | 'closed';
     stateReason: string | null;
@@ -86,6 +92,21 @@ export declare function getSuggestionOnGitHub(gh: GitHubClient, n: number, gov:
     pulls?: PullRequestSummary[] | undefined;
     outdated?: boolean | undefined;
 }): Promise<SuggestionDetail>;
+/** An approved Bridge suggestion a pull request applies: its number, approvals and the tier they were given at. */
+export interface ApprovedSuggestion {
+    number: number;
+    approvals: SuggestionApprovals;
+    tier: 1 | 2 | 3;
+}
+/**
+ * The approved Bridge suggestion a pull request applies, from the issues its body closes ("Closes #n", the first three):
+ * its approvals and the tier they were given at, for branchVerdict (withSuggestionApprovals). Null when it closes
+ * none, or none is an approved suggestion. Studio, the MCP server and the CLI read it through this one call. A read
+ * that fails counts as no suggestion: the pull request then needs its own approvals, never fewer.
+ */
+export declare function approvedSuggestionOnGitHub(gh: GitHubClient, body: string | null | undefined, gov: SuggestionGovernance): Promise<ApprovedSuggestion | null>;
+/** One issue: the approved suggestion it holds, or null (not a suggestion, not approved). Throws when it cannot be read. */
+export declare function approvedSuggestionNumber(gh: GitHubClient, n: number, gov: SuggestionGovernance): Promise<ApprovedSuggestion | null>;
 /**
  * Keeps exactly one status label on the issue, the one the status calls for (suggestionLabelChanges): an open state
  * label while open, the final label ("suggestion: applied", "suggestion: declined") once closed, the old ones removed.
@@ -153,6 +174,17 @@ export declare function reviewSuggestionOnGitHub(gh: GitHubClient, n: number, in
     by?: string | undefined;
     at?: Date | undefined;
 }, gov: SuggestionGovernance): Promise<SuggestionReviewResult>;
+/**
+ * The owner override on a suggestion (docs/GOVERNANCE.md "Owner override"): the owner it allows, whom nobody else can
+ * review, approves their own suggestion as owner with a written reason. Checks the rule (suggestionOverrideProblem),
+ * the reason (overrideReasonProblem), the version, then posts the audit comment and re-syncs the state label. A
+ * developer then applies it as any approved suggestion; the pull request carries the approvals.
+ */
+export declare function overrideSuggestionOnGitHub(gh: GitHubClient, n: number, input: {
+    reason: string;
+    payloadSha?: string | undefined;
+    by?: string | undefined;
+}, gov: SuggestionGovernance): Promise<SuggestionReviewResult>;
 /**
  * Records that a suggestion is being applied (the applied marker comment) and sets its status label: "suggestion:
  * applying" while the pull request is open, "suggestion: applied" (the old labels removed) once it merged or the issue

package/dist/suggestions.d.ts

@@ -173,6 +173,12 @@ export interface SuggestionStatusInput {
     /** The dry-run apply found a conflict with the current default branch. */
     outdated?: boolean | undefined;
 }
+/**
+ * Decision TV-1 (docs/BUILD-REQUESTS.md, "Token values from Studio"): a token suggestion that only changes values or
+ * adds tokens (every edit a `set` or an `add`, no file beside its changeset) needs the design approval only, the same
+ * rule as a pull request (isTokenValueChange). A rename, a removal or any other kind still needs the tech approval.
+ */
+export declare function suggestionIsTokenValues(p: Pick<SuggestionPayloadV1, 'kind' | 'tokens' | 'files' | 'docs' | 'componentSpec'>): boolean;
 /**
  * Where a suggestion stands. Closed: applied when a linked pull request merged or the issue was closed as completed,
  * declined otherwise. Open: applying when a linked pull request is open or an applied marker exists; outdated when the

package/dist/tier1-publish.d.ts

@@ -0,0 +1,48 @@
+import type { Owners } from './config';
+import type { RiskTier } from './risk';
+/** The setting, absent counting as on. */
+export declare const leadsPublishTier1On: (gov: {
+    leadsPublishTier1?: boolean | undefined;
+} | null | undefined) => boolean;
+/** Which reviewers lead a Tier 1 change: tech when it touches stories or tests (code-only Tier 1), else design. */
+export type Tier1Domain = 'design' | 'tech';
+export declare function tier1Domain(paths: readonly string[]): Tier1Domain;
+export interface Tier1PublishInput {
+    /** Login of the person publishing (the pull request's author). */
+    viewer: string | null | undefined;
+    /** classifyRisk over the change. Only Tier 1 publishes without review. */
+    tier: RiskTier | null | undefined;
+    domain: Tier1Domain;
+    /** The approver lists (approverLists: rights applied, teams expanded). */
+    approvers: Owners;
+    /** The viewer is an admin of the team in Bridge. */
+    admin: boolean;
+    /** governance.leadsPublishTier1 (leadsPublishTier1On). */
+    enabled: boolean;
+}
+/** Whether this person may publish this change without review. */
+export declare function canPublishTier1(x: Tier1PublishInput): boolean;
+/** The button that replaces "Send for review" for someone who may publish. */
+export declare const PUBLISH_LABEL = "Publish";
+/** The first line of the app's review on the pull request: how History and the readers recognise it. */
+export declare const TIER1_PUBLISH_HEADING = "**Bridge: published without review (Tier 1)**";
+/** The record, on the pull request and in History. */
+export declare const publishedWithoutReview: (name: string) => string;
+/** The app's review body: the heading, then the record and why it needed no review. */
+export declare function tier1PublishReviewBody(name: string, login: string): string;
+/** Who published it, read back from the app's review body, or null when the body is not one. */
+export declare function tier1PublishedBy(body: string | null | undefined): string | null;
+/**
+ * Who published this pull request without review, read from its reviews: the app's approving review with the heading,
+ * on the head commit when the head is known (an older one was dismissed by the push after it). Null when none.
+ */
+export declare function tier1PublishOf(reviews: readonly {
+    state: string;
+    body?: string | null | undefined;
+    commit_id?: string | null | undefined;
+}[] | null | undefined, headSha?: string | null | undefined): string | null;
+/**
+ * Who may publish without review, in one sentence, for the CLI, the MCP server and Settings. Admins are a Bridge
+ * team role, so the sentence names the role, not people.
+ */
+export declare function tier1PublishSentence(enabled: boolean): string;

package/dist/token-proposal.d.ts

@@ -52,6 +52,8 @@ export declare function planTokenProposal(input: {
     tool?: string | undefined;
     /** More body paragraphs, after the generated body (the product line, "Needed by"). */
     bodyExtra?: string[] | undefined;
+    /** Pushed from the Figma plugin: the body says design-approved and what happens next (docs/BUILD-REQUESTS.md). */
+    fromFigma?: boolean | undefined;
 }): TokenProposalPlan | null;
 export interface OpenedTokenProposal {
     branch: string;
@@ -74,6 +76,11 @@ export declare function writeTokenProposalOnGitHub(gh: GitHubClient, plan: Token
     labelsAfter?: string[] | undefined;
     /** Who proposes it, in the commit message: "Bridge MCP (source: mcp)". */
     tool?: string | undefined;
+    /**
+     * Open it as a draft or not. Default: a draft from tier 2, until design review. A token push from Figma with values
+     * only opens ready (false): it ships after the automatic checks (docs/BUILD-REQUESTS.md).
+     */
+    draft?: boolean | undefined;
 }): Promise<OpenedTokenProposal>;
 export interface SuggestedTokenProposal {
     status: 'suggested';

package/dist/try-in-product.d.ts

@@ -17,3 +17,12 @@ export declare function productPreview(apps: PreviewApps, ctx: {
  * Only http(s) previews: anything else (a javascript: or data: URL in a hostile comment) gives ''.
  */
 export declare function tryInProductUrl(preview: string, pr: number, screen: ProductScreen | null): string;
+/**
+ * True when nothing reported an online preview of the branch (no Vercel status, deployment or comment, only config
+ * templates): explorations and library branches are not deployed, a developer tries them on their machine.
+ */
+export declare function noOnlinePreview(previews: readonly {
+    source: string | null;
+}[]): boolean;
+/** The command that puts a branch on a developer's machine, quoted when the name has shell characters. */
+export declare function localTryCommand(branch: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bridge-ds/core",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "type": "module",
   "description": "Bridge core: bridge.config.json, DTCG token loading (tiers and layered modes), alias resolution, WCAG contrast, diffs, minimal-diff edits, PR body, the shared risk tier classifier, changesets and a fetch-based GitHub client. No Figma API, no DOM; Node-only helpers (git, reading a product folder) under @bridge-ds/core/node; the adoption audit under @bridge-ds/core/audit.",
   "license": "MIT",