@bridge-ds/core 0.17.0 → 0.19.0

package/dist/build-requests.d.ts

@@ -0,0 +1,403 @@
+import { type BridgeConfig } from './config';
+import { type ComponentChangeRequest, type RequestIssue, type RequestKind } from './requests';
+import { type ChangedFile, type TokenChangeKind, type TokenChangeSummary } from './risk';
+import { type CiSummary } from './review-gate';
+/** Every build request issue carries this label (with component-change, which the Jira Action mirrors). */
+export declare const BUILD_REQUEST_LABEL = "bridge-build";
+/** The label the plugin puts on what it pushes (token pull requests, suggestions and requests). */
+export declare const SOURCE_FIGMA_LABEL = "source: figma";
+/** A build request waits this many days before it reads as stale. */
+export declare const BUILD_STALE_DAYS = 7;
+/**
+ * What the two images of a build request are called on designer screens (Studio): the component as it is in code
+ * now, and the design in Figma. The data keeps its field names, `before` and `after`; the GitHub issue table, read by
+ * developers, keeps Before and After.
+ */
+export declare const BUILD_IMAGE_LABEL: {
+    readonly before: "In code now";
+    readonly after: "In Figma";
+};
+/**
+ * Whether a pull request (or issue) was pushed from the Figma plugin: the `source: figma` or `from-figma` label, or the
+ * hidden "From Figma" origin block of a component branch.
+ */
+export declare function isFigmaPush(p: {
+    labels?: readonly ({
+        name?: string;
+    } | string)[] | null | undefined;
+    body?: string | null | undefined;
+}): boolean;
+/**
+ * What a push from Figma changes, from the pull request's real files and token changes (never from what its body says):
+ * - `token-values`: token files only (values changed or tokens added), plus changesets, docs and Bridge's own files;
+ * - `token-structure`: a token renamed or removed;
+ * - `token-unknown`: token files changed but the token changes were not read (counts like token-structure);
+ * - `component`: component or other source code (a Claude draft branch, the pull request of a build request);
+ * - `outside`: a guardrail file (CI, AGENTS.md, bridge.config.json, contrast checks): no Figma credit at all.
+ */
+export type FigmaPushScope = 'token-values' | 'token-structure' | 'token-unknown' | 'component' | 'outside';
+/** A token file: `*.tokens.json`, or a JSON file under `tokens.root`. */
+export declare function isTokenPath(path: string, config?: BridgeConfig | undefined): boolean;
+export declare function figmaPushScope(input: {
+    files: readonly ChangedFile[];
+    tokenChanges: readonly {
+        kind: TokenChangeKind | string;
+    }[] | null | undefined;
+    config?: BridgeConfig | undefined;
+}): FigmaPushScope;
+/**
+ * Whether the token files of a pull request are worth reading to tell a token value change (isTokenValueChange): it
+ * changes token files, and nothing beside them but changesets, docs and Bridge's own files. Every other pull request
+ * (code, a guardrail file, no token file) is not one, with no read.
+ */
+export declare function mayBeTokenValueChange(files: readonly ChangedFile[], config?: BridgeConfig | undefined): boolean;
+/**
+ * Decision TV-1 (docs/BUILD-REQUESTS.md, "Token values from Studio"): a pull request that only changes token values
+ * (values changed or tokens added, from its real files and token changes, never from its body), whoever opened it.
+ * Once the design approval is given it ships after the automatic checks, with no developer code OK (review-gate
+ * withTokenValueApprovals, branchVerdict `tokenValues`). A rename or removal, unread token changes (null), code, a
+ * guardrail file or a running exploration is not one: those still need the tech approval.
+ */
+export declare function isTokenValueChange(input: {
+    files: readonly ChangedFile[];
+    tokenChanges: readonly {
+        kind: TokenChangeKind | string;
+    }[] | null | undefined;
+    config?: BridgeConfig | undefined;
+    labels?: readonly ({
+        name?: string;
+    } | string)[] | null | undefined;
+}): boolean;
+/**
+ * The token changes between two versions of token files, by kind, from their text alone (DTCG: a node with `$value` is a
+ * token, its path the keys joined by "."). For callers that only have the files of a pull request (the server arming a
+ * merge, Studio's branch page): a path gone is `removed` (a rename reads as removed plus added, which gates the same),
+ * a new path `added`, a different `$value`, `$type` or extension `changed`, a different `$description` only
+ * `changed` with descriptionOnly. Unreadable JSON throws, so the caller treats the changes as unknown.
+ */
+export declare function tokenFileChanges(files: readonly {
+    before: string | null | undefined;
+    after: string | null | undefined;
+}[]): TokenChangeSummary[];
+/** The Figma push facts the gate reads (branchVerdict `figmaPush`). Null when the pull request is not one. */
+export interface FigmaPush {
+    scope: FigmaPushScope;
+}
+/**
+ * The Figma push facts of a pull request: pushed from the plugin (isFigmaPush), or the pull request of a build request
+ * sent from Figma (`closesFigmaBuildRequest`: its body closes one). Null otherwise, and for a running exploration.
+ */
+export declare function figmaPushOf(pr: {
+    labels?: readonly ({
+        name?: string;
+    } | string)[] | null | undefined;
+    body?: string | null | undefined;
+}, facts: {
+    files: readonly ChangedFile[];
+    tokenChanges: readonly {
+        kind: TokenChangeKind | string;
+    }[] | null | undefined;
+    config?: BridgeConfig | undefined;
+    closesFigmaBuildRequest?: boolean | undefined;
+}): FigmaPush | null;
+/** Whether a scope ships with no person in the loop: design approved by the push, tech approved by being values only. */
+export declare const shipsByItself: (scope: FigmaPushScope | null | undefined) => boolean;
+/**
+ * Where one published thing went:
+ * - `shipped`: a token pull request with values only. Bridge merges it once the automatic checks pass (auto-merge
+ *   armed); poll libraryArrival until it reads "In the library".
+ * - `waiting-for-developer`: a pull request a developer approves first (a token renamed or removed).
+ * - `build-request`: an issue developers build from (a structure change).
+ */
+export type PublishRoute = 'shipped' | 'waiting-for-developer' | 'build-request';
+export interface PublishOutcome {
+    /** What was published: a token path, or a component name. */
+    subject: {
+        type: 'token' | 'component';
+        name: string;
+    };
+    route: PublishRoute;
+    /** The pull request (shipped, waiting-for-developer) or the issue (build-request). */
+    ref: {
+        kind: 'pull' | 'issue';
+        number: number;
+        url: string;
+    };
+    /**
+     * `shipped` only: whether Bridge armed the merge (auto-merge on GitHub, or the Bridge app merging on green checks).
+     * False when it could not (no Bridge app on the repository, auto-merge off): the route is then reported as
+     * `waiting-for-developer` instead, so this is true on every `shipped` outcome.
+     */
+    armed?: boolean | undefined;
+}
+export interface PublishResult {
+    outcomes: PublishOutcome[];
+}
+export declare const PUBLISH_ROUTE_COPY: Record<PublishRoute, {
+    label: string;
+    sentence: string;
+}>;
+/**
+ * The route of a token push, from its token changes: values changed or tokens added ship; a rename or a removal waits
+ * for a developer. `armed` false (Bridge could not arm the merge) also waits for a developer.
+ */
+export declare function tokenPublishRoute(changes: readonly {
+    kind: TokenChangeKind | string;
+}[], armed?: boolean): Exclude<PublishRoute, 'build-request'>;
+/** One sentence for the end of a publish: "2 on their way to the library, 1 waiting for a developer, 1 build request sent." */
+export declare function publishSummary(r: PublishResult): string;
+export type LibraryArrivalKey = 'on-its-way' | 'in-the-library' | 'held' | 'not-shipped';
+export interface LibraryArrival {
+    key: LibraryArrivalKey;
+    label: string;
+    sentence: string;
+    /** Stop polling: it is in the library, or it will not get there by itself. */
+    final: boolean;
+}
+/**
+ * Where a published pull request stands, for the plugin to poll after `shipped` (every 20 to 30 seconds is plenty)
+ * and for Studio. Never names a technical blocker: a failing check, a conflict or a change request all read "Held for a
+ * developer". `held` is final for polling on a conflict or a change request (a person picks it up from there), not on a
+ * failed check, which a re-run can clear.
+ */
+export declare function libraryArrival(p: {
+    state: string;
+    merged_at?: string | null | undefined;
+    merged?: boolean | undefined;
+    mergeable?: boolean | null | undefined;
+    ci?: CiSummary | null | undefined;
+    changesRequested?: number | undefined;
+}): LibraryArrival;
+/** The review Bridge's app leaves on a token push it ships (the merge rule's record on GitHub). */
+export declare const FIGMA_SHIP_HEADING = "**Bridge: shipped from Figma**";
+export declare function figmaShipReviewBody(by?: string | null): string;
+/** A prop (option) the build needs. */
+export interface BuildProp {
+    name: string;
+    /** "variant", "boolean", "text", "instance swap", or a TypeScript type. */
+    type?: string | undefined;
+    values?: string[] | undefined;
+    default?: string | undefined;
+    /** "new", "changed" or "removed"; default new. */
+    change?: 'new' | 'changed' | 'removed' | undefined;
+    note?: string | undefined;
+}
+/** What a build request adds to a component change request (kept in the request's hidden block, under `build`). */
+export interface BuildRequestExtra {
+    v: 1;
+    /** Image URLs of the design before and after the change. */
+    before?: string[] | undefined;
+    after?: string[] | undefined;
+    props?: BuildProp[] | undefined;
+    /** Where the full spec lives, when it is not in the issue (too large): a path on a branch, or a URL. */
+    specPath?: string | undefined;
+}
+/** The input of the build request issue builder (the Figma plugin, Studio, the CLI and the MCP server). */
+export interface BuildRequestInput {
+    /** Coded name ("Button"), or the proposed name of a new component. */
+    component: string;
+    kind: RequestKind;
+    /** One line, sentence case: "Add a lg size". */
+    title: string;
+    /** What and why, in the designer's words. */
+    summary: string;
+    /** What changes for developers in one sentence. */
+    line?: string | undefined;
+    changes?: ComponentChangeRequest['changes'] | undefined;
+    figma: {
+        fileKey?: string | undefined;
+        nodeId?: string | undefined;
+        nodeName?: string | undefined;
+        url?: string | undefined;
+    };
+    images?: {
+        before?: string[] | undefined;
+        after?: string[] | undefined;
+    } | undefined;
+    props?: BuildProp[] | undefined;
+    /** The structured spec (the plugin's ComponentPushDiff, with its token edits), shown collapsed. Omitted when too large. */
+    spec?: unknown;
+    specPath?: string | undefined;
+    /** A brief for Claude written by the caller; default buildRequestBrief. */
+    brief?: string | undefined;
+    source: ComponentChangeRequest['source'];
+    /** GitHub login of who pushed, when known (the "Requested by" record). */
+    requestedBy?: string | undefined;
+}
+/** Kinds that are structure changes, so a push from Figma becomes a build request. */
+export declare const BUILD_KINDS: readonly RequestKind[];
+/** The largest spec JSON kept in the issue body (GitHub caps a body at 65,536 characters). */
+export declare const BUILD_SPEC_MAX = 30000;
+/** The request a build request input stands for (what parseRequestIssue reads back, with `build`). */
+export declare function buildRequestOf(input: BuildRequestInput): ComponentChangeRequest & {
+    build: BuildRequestExtra;
+};
+/**
+ * The brief Claude gets to build it ("Copy brief for Claude" in Studio, `bridge build show` in the CLI,
+ * `bridge_get_build_request` in the MCP server). Without an issue number (inside the issue body), it says "this issue".
+ */
+export declare function buildRequestBrief(r: ComponentChangeRequest & {
+    build?: BuildRequestExtra | undefined;
+}, ctx?: {
+    issue?: number | undefined;
+    issueUrl?: string | undefined;
+    componentsDir?: string | undefined;
+    agentsFile?: string | undefined;
+    files?: string[] | undefined;
+}): string;
+/**
+ * The GitHub issue of a build request: a component change request issue (component-change, so the bridge-jira Action
+ * mirrors it to Jira) with the bridge-build label, before and after images side by side, the props needed, the spec
+ * collapsed and the brief for Claude collapsed. parseBuildRequestIssue reads it back.
+ */
+export declare function composeBuildRequestIssue(input: BuildRequestInput, opts?: {
+    labels?: string[] | undefined;
+    assignees?: string[] | undefined;
+    componentUrl?: string | undefined;
+}): RequestIssue;
+/** The build request in an issue body, or undefined when it has no Bridge request block. `build` is empty for a plain request. */
+export declare function parseBuildRequestIssue(body: string | null | undefined): (ComponentChangeRequest & {
+    build: BuildRequestExtra;
+}) | undefined;
+/** The spec kept collapsed in a build request issue, or undefined. */
+export declare function parseBuildSpec(body: string | null | undefined): unknown;
+/** Whether an issue is a build request: every component change request is one (bridge-build marks the new ones). Explorations are not. */
+export declare function isBuildRequestIssue(labels: readonly ({
+    name?: string;
+} | string)[] | null | undefined): boolean;
+/**
+ * Requested (nobody assigned) -> Picked up (assigned: "Ana is on it") -> In progress (a linked draft pull request, or a
+ * linked branch with commits) -> In review (a linked pull request ready for review) -> Shipped (merged, or the issue
+ * closed as completed). `not-planned`: closed as not planned.
+ */
+export type BuildStatus = 'requested' | 'picked-up' | 'in-progress' | 'in-review' | 'shipped' | 'not-planned';
+export declare const BUILD_STATUS_LABEL: Record<BuildStatus, string>;
+/** Steps of the status timeline, in order (not-planned is off the line). */
+export declare const BUILD_STEPS: readonly BuildStatus[];
+/** A pull request linked to a build request (closes it, or the build request is that branch). */
+export interface BuildPullLike {
+    number: number;
+    url?: string | undefined;
+    /** "open", "closed" or "merged" (PullRequestSummary), or GitHub's open/closed with merged_at. */
+    state: string;
+    draft?: boolean | undefined;
+    mergedAt?: string | null | undefined;
+    merged_at?: string | null | undefined;
+    labels?: readonly ({
+        name?: string;
+    } | string)[] | undefined;
+    author?: string | undefined;
+    assignees?: string[] | undefined;
+    createdAt?: string | undefined;
+    updatedAt?: string | undefined;
+    body?: string | undefined;
+    /** Commits on the branch, when known (a branch with only the spec commit is not work in progress). */
+    commits?: number | null | undefined;
+    headRef?: string | undefined;
+    title?: string | undefined;
+}
+export interface BuildIssueLike {
+    number: number;
+    url: string;
+    title: string;
+    body: string;
+    state: 'open' | 'closed';
+    stateReason?: string | null | undefined;
+    labels: readonly ({
+        name?: string;
+    } | string)[];
+    author?: string | undefined;
+    assignees?: string[] | undefined;
+    createdAt: string;
+    closedAt?: string | null | undefined;
+}
+export interface BuildStatusEvent {
+    status: BuildStatus;
+    /** ISO date, when GitHub says. */
+    at?: string | undefined;
+    /** Who, when it is a person ("ana"). */
+    who?: string | undefined;
+}
+export interface BuildRequestView {
+    /** "issue-12" or "pull-34". */
+    id: string;
+    /** Where it lives: an issue, or (direct mode, no issue) the library branch from Figma waiting for a developer. */
+    kind: 'issue' | 'pull';
+    number: number;
+    url: string;
+    component: string;
+    /** "Add a lg size": the request's title, without the component prefix. */
+    title: string;
+    requestKind: RequestKind | null;
+    status: BuildStatus;
+    label: string;
+    /** One designer sentence: "Ana is on it.", "Waiting for a developer for 9 days." */
+    sentence: string;
+    /** Who works on it: the assignees, else the author of the linked pull request in progress. */
+    builders: string[];
+    requestedBy: string | null;
+    createdAt: string;
+    ageDays: number;
+    /** Requested for more than BUILD_STALE_DAYS days. */
+    stale: boolean;
+    shippedAt: string | null;
+    /** The linked pull request that moves it furthest. */
+    pull: {
+        number: number;
+        url?: string | undefined;
+        state: string;
+    } | null;
+    /** Jira key from the bridge-jira Action's `jira: DS-12` label. */
+    jira: string | null;
+    figmaUrl: string | null;
+    /** The status timeline: each step reached, with when and who when GitHub says. */
+    timeline: BuildStatusEvent[];
+}
+/** The issue numbers a pull request links: "Closes #n" in its body, plus GitHub's linked issues when the caller read them. */
+export declare function linkedIssueNumbers(p: Pick<BuildPullLike, 'body'>, extra?: readonly number[]): number[];
+/** The Jira key the bridge-jira Action labelled an issue with ("jira: DS-12"), or null. */
+export declare function jiraKeyOfLabels(labels: readonly ({
+    name?: string;
+} | string)[] | null | undefined): string | null;
+/**
+ * The status of one build request, from GitHub only: the issue (state, reason, assignees) and the pull requests linked
+ * to it. `nameOf` turns a login into the name a designer knows (team members), default the login.
+ */
+export declare function buildRequestStatus(x: {
+    issue?: BuildIssueLike | null | undefined;
+    pull?: BuildPullLike | null | undefined;
+    linked?: readonly BuildPullLike[] | undefined;
+}, now?: Date | number, nameOf?: (login: string) => string): Pick<BuildRequestView, 'status' | 'label' | 'sentence' | 'builders' | 'ageDays' | 'stale' | 'shippedAt' | 'pull' | 'timeline' | 'createdAt'>;
+/**
+ * Every build request, from the issues and pull requests read on GitHub: issues that are build requests
+ * (isBuildRequestIssue) with the pull requests that close them, plus library branches from Figma waiting for a
+ * developer that no issue covers (direct mode). `linkedByIssue`: GitHub's linked pull requests per issue number, when the
+ * caller read the timeline (Development links), on top of "Closes #n".
+ */
+export declare function assembleBuildRequests(input: {
+    issues: readonly BuildIssueLike[];
+    pulls: readonly BuildPullLike[];
+    now?: Date | number | undefined;
+    nameOf?: ((login: string) => string) | undefined;
+    linkedByIssue?: ReadonlyMap<number, readonly number[]> | undefined;
+}): BuildRequestView[];
+/** The filters of the Being built page. */
+export type BuildFilter = 'all' | 'waiting' | 'in-progress' | 'shipped-this-week';
+export declare const BUILD_FILTER_LABEL: Record<BuildFilter, string>;
+/** Whether a build request shows under a filter. "All" leaves out what was closed as not planned more than a week ago. */
+export declare function matchesBuildFilter(v: Pick<BuildRequestView, 'status' | 'shippedAt' | 'timeline'>, f: BuildFilter, now?: Date | number): boolean;
+/** Build requests still open (not shipped, not closed). */
+export declare const openBuildRequests: <V extends Pick<BuildRequestView, "status">>(views: readonly V[]) => V[];
+/** The calm summary line of the home: "3 being built, 1 waiting to be picked up." Null when nothing is open. */
+export declare function buildSummaryLine(views: readonly Pick<BuildRequestView, 'status' | 'stale'>[]): string | null;
+/**
+ * The Library component page line while build requests for a component are open: "Figma is ahead: 2 changes being
+ * built (Ana)." Null when none is open (it disappears once shipped).
+ */
+export declare function figmaAheadLine(views: readonly Pick<BuildRequestView, 'component' | 'status' | 'builders'>[], component: string, nameOf?: (login: string) => string): {
+    count: number;
+    builders: string[];
+    sentence: string;
+} | null;
+/** "Button: add a lg size", the issue title of a build request (same rule as every request). */
+export declare const buildRequestTitle: (r: Pick<BuildRequestInput, "component" | "title">) => string;

package/dist/changelog-model.d.ts

@@ -0,0 +1,102 @@
+export type ChangelogBump = 'major' | 'minor' | 'patch';
+export interface ChangelogEntry {
+    source: 'changeset' | 'release';
+    /** First sentence of the note, the row title. */
+    title: string;
+    /** Rest of the note's first paragraph, may be empty. */
+    detail: string;
+    kind: string;
+    bump: ChangelogBump | null;
+    packages: string[];
+    forYou: string;
+    /** The author wrote the "For you:" line (forYou is not the default for the bump). */
+    forYouAuthored?: boolean;
+    date?: string;
+    /** Changeset id: the commit sha prefix in a CHANGELOG.md, or the .changeset file path for pending ones. */
+    ref?: string;
+}
+export interface ChangelogReleasePackage {
+    name: string;
+    version: string;
+    /** Published to npm (not a private app). */
+    published: boolean;
+}
+export interface ChangelogRelease {
+    /** "v1.1.0" (the Library version, from @bridge-ds/react) or "core 0.3.1" when react is not in the release. */
+    name: string;
+    date?: string;
+    pending: boolean;
+    packages: ChangelogReleasePackage[];
+    entries: ChangelogEntry[];
+    announcement: string;
+}
+/** One "## x.y.z" section of a package CHANGELOG.md. */
+export interface ChangelogSection {
+    pkg: string;
+    version: string;
+    published: boolean;
+    notes: {
+        id: string;
+        bump: ChangelogBump;
+        text: string;
+    }[];
+}
+export declare const shortPackage: (name: string) => string;
+/** Splits a paragraph into sentences: ". ", "! " or "? " before a capital, a quote or a backtick, never inside `code`. */
+export declare function noteSentences(para: string): string[];
+/** Longest second sentence shown under a title; a longer one stays in the full notes rather than being cut. */
+export declare const CHANGELOG_DETAIL_MAX = 240;
+/**
+ * A note as a row: its first sentence is the title (no trailing period), the second one the description when it is
+ * short enough to read in a list, and the author's "For you:" line when there is one.
+ */
+export declare function splitNote(text: string): {
+    title: string;
+    detail: string;
+    forYou?: string;
+};
+/** Parses a package CHANGELOG.md into its version sections. "Updated dependencies" lines are not changes. */
+export declare function parseChangelogSections(md: string, pkg: string, published: boolean): ChangelogSection[];
+/** One pending .changeset/*.md file, or null when it is not a changeset. */
+export declare function parseChangeset(src: string, ref: string): ChangelogEntry | null;
+/**
+ * Groups version sections into releases. Sections released together share a date, or, when no date is known
+ * (shallow clone, no tags), share a changeset: the release action writes one changeset into every package it
+ * bumps. Each changeset shows once per release, with every package it touched. Newest first.
+ * `dateOf(pkg, version)` returns the release date (YYYY-MM-DD) or undefined; it never guesses.
+ */
+export declare function groupReleases(sections: ChangelogSection[], dateOf: (pkg: string, version: string) => string | undefined, libraryPackage?: string): Omit<ChangelogRelease, 'announcement'>[];
+/** Breaking first, then New, Fix, Internal; the notes' own order inside a kind. */
+export declare function sortChangelogEntries<T extends {
+    kind: string;
+}>(entries: T[]): T[];
+export declare function releaseAnnouncement(r: Omit<ChangelogRelease, 'announcement'>): string;
+/** Meta line of an entry: the bump in words, then the packages (short names). Over `max`, only a count. */
+export declare function releasePackagesLabel(packages: string[], max?: number): {
+    tags: string[];
+    count: string | null;
+};
+/** A release as the snapshot carries it: the announcement is left out (releaseAnnouncement(r) rebuilds it). */
+export type ChangelogReleaseRow = Omit<ChangelogRelease, 'announcement'>;
+export interface CollectReleasesInput {
+    /** Each package's CHANGELOG.md text, with its npm name and whether it is published (not private). */
+    changelogs: {
+        pkg: string;
+        published: boolean;
+        text: string;
+    }[];
+    /** Pending .changeset/*.md files: `ref` is the file path. README.md is not a changeset and is skipped by the caller. */
+    changesets?: {
+        ref: string;
+        text: string;
+    }[];
+    /** Release date (YYYY-MM-DD) of a package version, or undefined; never guessed. */
+    dateOf?: (pkg: string, version: string) => string | undefined;
+    /** Package whose version names a release ("v1.1.0"). */
+    libraryPackage?: string;
+}
+/**
+ * Every release of a repository, newest first: the pending changesets as "Coming in the next release" when there are
+ * any, then the published versions grouped by groupReleases. What the Changelog shows and the team snapshot carries.
+ */
+export declare function collectReleases(input: CollectReleasesInput): ChangelogReleaseRow[];

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. */
@@ -144,6 +154,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 +202,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 +212,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 +272,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;