@bridge-ds/core 0.2.0 → 0.4.0

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import type { IntegrationsConfig } from './requests';
 import { type PreviewApps, type PreviewsConfig } from './previews';
+import { type Rights, type VisualImpactConfig } from './rights';
 /** File name Bridge looks for at the repository root. */
 export declare const CONFIG_FILE = "bridge.config.json";
 export interface RepoRef {
@@ -63,6 +64,10 @@ export interface ComponentsConfig {
     /** Generated component specs the Figma plugin pulls (default packages/react/component-specs.json). */
     specs?: string | undefined;
 }
+/**
+ * Design and tech owners. Each entry is a person ("peterbono" or "@peterbono") or a GitHub team ("@acme/design"),
+ * whose members GitHub manages (teams.ts expands them).
+ */
 export interface Owners {
     design: string[];
     tech: string[];
@@ -86,10 +91,15 @@ export interface GovernanceConfig {
     labels: string[];
     /** Files whose change is Tier 3 on its own, repo-relative; a trailing "/" matches a directory. */
     guardrails: string[];
-    /** GitHub logins that count as design and tech owners. Empty: two distinct approvers stand in. */
+    /** People and teams that count as design and tech owners. Empty: two distinct approvers stand in. */
     owners: Owners;
     /** Owner override for missing approvals only (never CI, changes requested or drafts). Absent: no override. */
     override?: OverridePolicy | undefined;
+    /**
+     * Which owner group may approve design, approve tech and ship (see rights.ts). Absent: approvals follow `owners`
+     * and anyone with write access may ship, as before the field existed.
+     */
+    rights?: Rights | undefined;
 }
 /** `bridge audit` settings: how product code that consumes the design system is measured. */
 export interface AuditConfig {
@@ -139,6 +149,8 @@ export interface BridgeConfig {
     previews?: PreviewsConfig | undefined;
     /** Where component change requests go besides the GitHub issue (see requests.ts). */
     integrations?: IntegrationsConfig | undefined;
+    /** Visual before and after on pull requests: automatic (default) or on demand (label `visual-check`). */
+    visualImpact?: VisualImpactConfig | undefined;
 }
 type Partialish<T> = {
     [K in keyof T]?: T[K] | undefined;
@@ -185,9 +197,10 @@ export interface BridgeConfigInput {
         package: string;
     };
     cssVar?: Partial<BridgeConfig['cssVar']>;
-    governance?: Partial<Omit<GovernanceConfig, 'owners' | 'override'>> & {
+    governance?: Partial<Omit<GovernanceConfig, 'owners' | 'override' | 'rights'>> & {
         owners?: Partial<Owners>;
         override?: Partial<OverridePolicy>;
+        rights?: Partial<Rights>;
     };
     audit?: AuditConfig;
     previews?: {
@@ -196,6 +209,7 @@ export interface BridgeConfigInput {
         production?: PreviewApps;
     };
     integrations?: IntegrationsConfig;
+    visualImpact?: Partial<VisualImpactConfig>;
 }
 export declare const DEFAULT_TOKEN_PATHS: TokenPaths;
 export declare const DEFAULT_GOVERNANCE: GovernanceConfig;

package/dist/css-overrides.d.ts

@@ -0,0 +1,11 @@
+import { type ResolveContext } from './resolver';
+import type { TokenSet } from './token-set';
+/** CSS value of a resolved DTCG value, the way tokens.css writes it. */
+export declare function cssOf(type: string, value: unknown): string | undefined;
+export declare const cssVarOf: (path: string) => string;
+/**
+ * CSS custom properties to set on a scope so it renders `proposed` instead of `head`: every token whose resolved value
+ * differs in that context. Setting resolved values (not var() references) keeps chains correct even when the original
+ * variable is declared on an ancestor.
+ */
+export declare function previewOverrides(head: TokenSet, proposed: TokenSet, ctx: ResolveContext): Record<string, string>;

package/dist/docs-ai.d.ts

@@ -0,0 +1,116 @@
+import { type ComponentDocsJson, type DocsConventions, type DocsPrefill, type ProseKey } from './docs-draft';
+export declare const DOCS_DRAFT_MODEL = "claude-sonnet-5-5";
+export declare const ANTHROPIC_MESSAGES_URL = "https://api.anthropic.com/v1/messages";
+/** How a selected passage is rewritten. */
+export type DocsSelectionMode = 'clearer' | 'shorter' | 'voice';
+export declare const DOCS_SELECTION_MODES: Record<DocsSelectionMode, string>;
+export declare const isDocsSelectionMode: (m: unknown) => m is DocsSelectionMode;
+export declare const isProseKey: (k: unknown) => k is ProseKey;
+/**
+ * One drafting job on a component's docs. "sections": write these prose sections (rewrite: even when they hold text;
+ * check: written sections older than the code, returned only when no longer true for it, so an absent one is still
+ * accurate). "selection": rewrite one passage of a section, nothing else.
+ */
+export type DocsDraftTask = {
+    kind: 'sections';
+    keys: ProseKey[];
+    rewrite?: boolean | undefined;
+    check?: ProseKey[] | undefined;
+} | {
+    kind: 'selection';
+    key: ProseKey;
+    text: string;
+    mode: DocsSelectionMode;
+};
+/** Problems in a task, as sentences. Empty when valid. */
+export declare function validateDocsTask(x: unknown): string[];
+/** The keys a task writes. */
+export declare const docsTaskKeys: (t: DocsDraftTask) => ProseKey[];
+/** The prompt to rewrite a selected passage of a section: the facts and the conventions, the passage, one rule. */
+export declare function docsSelectionPrompt(prefill: DocsPrefill, conventions: DocsConventions, sel: {
+    key: ProseKey;
+    text: string;
+    mode: DocsSelectionMode;
+}): string;
+/** The prompt of a task: docsPrompt for sections (only those keys), docsSelectionPrompt for a selection. */
+export declare function docsTaskPrompt(prefill: DocsPrefill, conventions: DocsConventions, task: DocsDraftTask): string;
+/** The first JSON object in a model reply (plain, or inside a ```json fence). Throws when there is none. */
+export declare function parseDocsReply(text: string): Record<string, unknown>;
+/** One line of docs prose: em dashes out, whitespace folded, trimmed. */
+export declare const cleanDocsText: (s: string) => string;
+export type DocsSections = Partial<Pick<ComponentDocsJson, ProseKey>>;
+/**
+ * The prose sections of an answer, kept to the docs.json shapes: only `keys`, summary one cleaned paragraph, lists of
+ * non-empty cleaned strings, dos and donts as {title, text} (an example only when `examples` and well formed). Em
+ * dashes removed everywhere. Sections that come back empty or in the wrong shape are left out.
+ */
+export declare function sanitizeDocsSections(raw: unknown, keys?: readonly ProseKey[], opts?: {
+    examples?: boolean;
+}): DocsSections;
+/** A rewritten passage: one cleaned paragraph without wrapping quotes, or '' when there is none. */
+export declare function sanitizeDocsReplacement(raw: unknown): string;
+/**
+ * A task's answer. Sections tasks: `sections` drafted or fixed, and `checked`, the checked sections Claude verified and
+ * left unchanged (still accurate). Selection: `replacement` only.
+ */
+export type DocsTaskAnswer = {
+    sections: DocsSections;
+    checked: ProseKey[];
+    replacement?: undefined;
+} | {
+    sections: DocsSections;
+    checked?: undefined;
+    replacement: string;
+};
+/**
+ * A task's answer from Claude's reply text. Sections: the requested keys, sanitized; throws when none came back.
+ * Selection: `replacement` only (sections stay empty); a reply that is plain text counts as the passage.
+ */
+export declare function parseDocsTaskAnswer(task: DocsDraftTask, text: string): DocsTaskAnswer;
+/**
+ * Sections and checked of a sections task from an answer object: absent checked keys are still accurate. Throws only
+ * when the task checks nothing and none of its keys came back.
+ */
+export declare function docsSectionsAnswer(task: Extract<DocsDraftTask, {
+    kind: 'sections';
+}>, raw: unknown): {
+    sections: DocsSections;
+    checked: ProseKey[];
+};
+/** The sections of a task from an answer object (API reply or the exchange). Throws when none of the keys came back. */
+export declare function docsSectionsResult(task: Extract<DocsDraftTask, {
+    kind: 'sections';
+}>, raw: unknown): DocsSections;
+/**
+ * Drafted sections applied to a docs.json, marked for review: the sections replace the ones there, the rest stays as
+ * is (anatomy and preview are code-decided and never come from a draft), and draftedSections lists what waits.
+ */
+export declare function applyDocsSections<T extends Partial<ComponentDocsJson>>(docs: T, sections: DocsSections): T;
+/**
+ * The docs-draft Action's merge: Claude's prose on top of the pre-fill draft, only where the pre-fill is empty (a
+ * written section is never overwritten), anatomy kept from the code, the drafted sections marked for review.
+ */
+export declare function mergeDocsDraft(prefillDraft: Partial<ComponentDocsJson>, reply: Record<string, unknown>): Partial<ComponentDocsJson>;
+export interface AnthropicHttpRequest {
+    url: string;
+    init: {
+        method: 'POST';
+        headers: Record<string, string>;
+        body: string;
+    };
+}
+export interface AnthropicRequestInput {
+    apiKey: string;
+    prompt: string;
+    model?: string | undefined;
+    system?: string | undefined;
+    maxTokens?: number | undefined;
+    /** A direct call from a browser page (the user's own key): adds the header the API asks for. */
+    browser?: boolean | undefined;
+    /** Re-run a declined request on a fallback model inside the same call (server-side fallback beta). */
+    fallback?: boolean | undefined;
+}
+/** The Messages API request for one prompt. The key goes in x-api-key, to api.anthropic.com only. */
+export declare function anthropicRequest(input: AnthropicRequestInput): AnthropicHttpRequest;
+/** The text of a Messages API reply. Throws when Claude declined or the reply was cut off. */
+export declare function anthropicReplyText(msg: unknown): string;

package/dist/docs-draft.d.ts

@@ -23,6 +23,11 @@ export interface ComponentDocsJson {
     anatomy?: Record<string, string>;
     /** Who wrote the prose when it was not a person in the editor. Only "claude" today. */
     draftedBy?: string;
+    /**
+     * The prose sections Claude drafted that wait for review, when a draft covered only some of them (in-place drafting
+     * on the Library page, the docs-draft Action). Missing means the whole file. Accepting removes it.
+     */
+    draftedSections?: ProseKey[];
     /** True while drafted prose waits for a reviewer. Accepting sets it to false. */
     needsReview?: boolean;
 }
@@ -100,15 +105,36 @@ export interface DocsConventions {
     example?: string;
     /** The component source, so the prose stays true to the code. */
     source?: string;
+    /** The component's CSS module: its states and parts, so the prose stays true to the look. */
+    styles?: string;
 }
+/** What docsPrompt asks for. Without `keys`, the missing prose as a full docs.json (the docs-draft Action, bridge_draft_docs). */
+export interface DocsPromptOptions {
+    /** Only these sections, answered as an object holding only them. */
+    keys?: readonly ProseKey[];
+    /** Rewrite the sections even when they hold text. */
+    rewrite?: boolean;
+    /**
+     * Written sections older than the component code, to check (among `keys`): Claude returns one only when something
+     * in it is no longer true for the code, keeping the writer's wording elsewhere; an accurate one is left out.
+     */
+    check?: readonly ProseKey[];
+}
+/** The JSON shape of these sections, for a prompt: {"summary": "...", "dos": [{ "title", "text" }]}. */
+export declare const docsSectionShapes: (keys: readonly ProseKey[]) => string;
 /**
  * The prompt a model gets to write the prose of a docs.json: the pre-fill as facts, the conventions, and strict
  * rules (no invention, JSON only). Used by the GitHub Action and returned by bridge_draft_docs for the user's own
  * Claude.
  */
-export declare function docsPrompt(prefill: DocsPrefill, conventions?: DocsConventions): string;
-/** Marks prose as drafted by Claude and waiting for review. */
-export declare function markClaudeDraft(d: ComponentDocsJson): ComponentDocsJson;
+export declare function docsPrompt(prefill: DocsPrefill, conventions?: DocsConventions, options?: DocsPromptOptions): string;
+/**
+ * Marks prose as drafted by Claude and waiting for review. With `sections`, only those sections were drafted: they
+ * join the ones already waiting (draftedSections, in the PROSE_KEYS order). Without, the whole file was.
+ */
+export declare function markClaudeDraft<T extends Partial<ComponentDocsJson>>(d: T, sections?: readonly ProseKey[]): T;
+/** Prose sections that wait for review: draftedSections, every prose key for a whole-file draft, none once accepted. */
+export declare function sectionsNeedingReview(d: Partial<ComponentDocsJson> | null | undefined): ProseKey[];
 /** True when the docs hold AI-drafted prose nobody has reviewed yet. */
 export declare const needsDocsReview: (d: Partial<ComponentDocsJson> | null | undefined) => boolean;
 /** A reviewer accepts drafted prose: needsReview goes false, draftedBy stays as the record of who wrote it. */
@@ -121,7 +147,7 @@ export declare function formatDocsJson(d: Partial<ComponentDocsJson>): string;
  * original (or with one that is not valid JSON) it falls back to formatDocsJson.
  */
 export declare function patchDocsJson(original: string | null | undefined, next: Partial<ComponentDocsJson>): string;
-/** Accepts the drafted prose inside a docs.json text: only the needsReview line changes. Throws on invalid JSON. */
+/** Accepts the drafted prose inside a docs.json text: only the review lines change. Throws on invalid JSON. */
 export declare function acceptDocsText(text: string): string;
 /** Tier and bump of a docs-only change: Tier 1 under the shared classifier, and a patch. */
 export declare const DOCS_CHANGE_BUMP: "patch";

package/dist/draft-exchange.d.ts

@@ -1,4 +1,6 @@
-import { type DraftText } from './change-drafts';
+import { DRAFT_LINE_MAX, type DraftText } from './change-drafts';
+import { type DocsDraftTask, type DocsSections } from './docs-ai';
+import type { ProseKey } from './docs-draft';
 import { type GitHubClient } from './github-client';
 import { type RequestChange, type RequestKind } from './requests';
 export declare const DRAFT_EXCHANGE_VERSION = 1;
@@ -8,7 +10,10 @@ export declare const DRAFTS_DIR = ".bridge/drafts";
 export declare const DRAFT_PHRASE = "Draft my Bridge changes";
 export declare const DRAFT_TITLE_MAX = 70;
 export declare const DRAFT_SUMMARY_SENTENCES = 3;
-export type DraftScope = 'request' | 'push';
+export { DRAFT_LINE_MAX };
+export type DraftScope = 'request' | 'push' | 'docs';
+/** Who wrote the session: the DS Bridge Figma plugin, or Bridge Studio (component docs on the Library page). */
+export type DraftSource = 'figma' | 'studio';
 export type DraftSessionStatus = 'pending' | 'drafted';
 export interface DraftImage {
     label: 'before' | 'after';
@@ -16,6 +21,23 @@ export interface DraftImage {
     url: string;
     /** Repo path on the requests branch, so tools can read it with the token. */
     path?: string | undefined;
+    /** The change line (DraftLine id) this image shows, when an item has several components (a push). */
+    line?: string | undefined;
+}
+/**
+ * One detected component change to describe in one sentence (its "change line"): the main line of its row in the
+ * plugin and the first line of its request. A request item has one, a push item one per component it requests.
+ */
+export interface DraftLine {
+    /** Stable id to answer with (the plugin uses the component's node id). */
+    id: string;
+    component?: string | undefined;
+    kind?: RequestKind | undefined;
+    changes: RequestChange[];
+    /** The deterministic line, from the changes only, as a starting point. */
+    line: string;
+    /** The deterministic request title of this component change, as a starting point. Missing from older plugins. */
+    title?: string | undefined;
 }
 export interface DraftVariableRow {
     path: string;
@@ -38,20 +60,52 @@ export interface DraftItem {
     images?: DraftImage[] | undefined;
     /** The deterministic draft (from the detected changes only), as a starting point. */
     draft: DraftText;
+    /** Component changes to write one line each for. Missing in sessions from older plugins. */
+    lines?: DraftLine[] | undefined;
+    /** Docs only: the component docs to write. */
+    docs?: DraftDocsItem | undefined;
+}
+/** A docs item: prose sections of one component's docs.json (or one selected passage), from Bridge Studio. */
+export interface DraftDocsItem {
+    /** Component slug on the Library page (button, icon-button). */
+    slug: string;
+    /** docs.json path in the repo. */
+    path?: string | undefined;
+    task: DocsDraftTask;
+    /** The full prompt: the task, the rules, the facts from the code (props, CSS module classes, JSDoc, tokens), the voice. */
+    prompt: string;
 }
 export interface DraftResult {
     id: string;
     title: string;
     summary: string;
+    /**
+     * One sentence per change line of the item (by DraftLine id), and the title of the request it becomes. Optional:
+     * older writers send none, or lines without a title.
+     */
+    lines?: DraftResultLine[] | undefined;
+    /** Docs items (sections task): the sections Claude wrote, sanitized to the docs.json shapes. */
+    docs?: DocsSections | undefined;
+    /** Docs items (selection task): the rewritten passage. */
+    replacement?: string | undefined;
+    /** Docs items (sections task): checked sections Claude verified and left unchanged (still accurate). */
+    checked?: ProseKey[] | undefined;
     by: 'claude';
     at: string;
 }
+export interface DraftResultLine {
+    id: string;
+    /** May be empty when only the title was written. */
+    line: string;
+    /** The request title of this component change: short, sentence case, at most 70 characters ("Add an icon after the label"). */
+    title?: string | undefined;
+}
 export interface PendingDrafts {
     version: 1;
     sessionId: string;
     createdAt: string;
     status: DraftSessionStatus;
-    source: 'figma';
+    source: DraftSource;
     items: DraftItem[];
     results?: DraftResult[] | undefined;
 }
@@ -66,6 +120,7 @@ export declare function draftSessionPath(sessionId: string): string;
 export declare function draftImagePath(sessionId: string, itemId: string, label: DraftImage['label']): string;
 export interface ComposeDraftsInput {
     items: DraftItem[];
+    source?: DraftSource | undefined;
     sessionId?: string | undefined;
     now?: Date | undefined;
     random?: (() => number) | undefined;
@@ -85,15 +140,31 @@ export declare function sanitizeDraftText(raw: {
     title?: unknown;
     summary?: unknown;
 }): DraftText;
+/** What a writer (bridge_write_drafts) sends for one item, before sanitizing. */
+export interface DraftResultInput {
+    id: string;
+    title?: unknown;
+    summary?: unknown;
+    lines?: unknown;
+    /** Docs items: the sections written (sections task). */
+    docs?: unknown;
+    /** Docs items: the rewritten passage (selection task). */
+    replacement?: unknown;
+}
+/** The docs part of a result for a docs item, sanitized to its task. Throws when it holds nothing the task asked for. */
+export declare function sanitizeDocsResult(item: DraftItem, r: DraftResultInput): Pick<DraftResult, 'docs' | 'replacement' | 'checked'>;
+/**
+ * The change lines of a result kept to the contract: known line ids only (throws on an unknown one), one sentence of
+ * at most 120 characters each, empty ones dropped, the last one per id kept.
+ */
+export declare function sanitizeResultLines(item: Pick<DraftItem, 'id' | 'lines'>, raw: unknown): DraftResultLine[];
+/** A request title kept to the contract: one line, no em dash, sentence case, at most 70 characters, no trailing period. */
+export declare function sanitizeDraftTitle(raw: unknown): string;
 /**
  * The session with these results added (a result for the same item replaces the earlier one). Results are sanitized.
  * Throws on an unknown item id or an empty result. Status is "drafted" once every item has a result.
  */
-export declare function mergeDraftResults(p: PendingDrafts, results: {
-    id: string;
-    title?: unknown;
-    summary?: unknown;
-}[], at?: Date): PendingDrafts;
+export declare function mergeDraftResults(p: PendingDrafts, results: DraftResultInput[], at?: Date): PendingDrafts;
 /** The Markdown brief of one item, for Claude: what to write, the facts, the starting draft. */
 export declare function draftItemBrief(i: DraftItem): string;
 type DraftClient = Pick<GitHubClient, 'getFile' | 'putFile' | 'deleteFile' | 'listDirectory'>;
@@ -119,11 +190,7 @@ export declare function updatePendingDrafts(client: DraftClient, sessionId: stri
     message?: string;
 }): Promise<PendingDrafts>;
 /** Writes Claude's results into a session (sanitized, merged, status "drafted" when complete), retrying on 409. */
-export declare function writeDraftResults(client: DraftClient, sessionId: string, results: {
-    id: string;
-    title?: unknown;
-    summary?: unknown;
-}[], opts?: {
+export declare function writeDraftResults(client: DraftClient, sessionId: string, results: DraftResultInput[], opts?: {
     branch?: string;
     now?: Date;
     attempts?: number;
@@ -135,4 +202,58 @@ export declare function writeDraftResults(client: DraftClient, sessionId: string
 export declare function deletePendingDrafts(client: DraftClient, sessionId: string, opts?: {
     branch?: string;
 }): Promise<boolean>;
-export {};
+/** Creates the requests branch from the head of `baseBranch` when it is missing. Never moves an existing branch. */
+export declare function ensureRequestsBranch(client: Pick<GitHubClient, 'getBranchSha' | 'createBranch'>, baseBranch: string): Promise<void>;
+export interface DocsDraftSessionInput {
+    component: string;
+    slug: string;
+    path?: string | undefined;
+    task: DocsDraftTask;
+    prompt: string;
+    /** Branch the requests branch starts from when it does not exist yet. */
+    baseBranch: string;
+    now?: Date | undefined;
+    random?: (() => number) | undefined;
+}
+/**
+ * Bridge Studio asks the user's own Claude for component docs: one docs item in a new session (source "studio") on
+ * the requests branch, created from `baseBranch` when missing. Returns the session to poll.
+ */
+export declare function createDocsDraftSession(client: Pick<GitHubClient, 'getBranchSha' | 'createBranch' | 'getFile' | 'putFile' | 'deleteFile' | 'listDirectory'>, input: DocsDraftSessionInput): Promise<PendingDrafts>;
+export declare const DRAFT_POLL_INTERVAL_MS = 5000;
+export declare const DRAFT_POLL_TIMEOUT_MS: number;
+export interface DraftPollerOptions {
+    client: Pick<GitHubClient, 'getFile'>;
+    sessionId: string;
+    intervalMs?: number | undefined;
+    timeoutMs?: number | undefined;
+    now?: (() => number) | undefined;
+    setTimer?: ((fn: () => void, ms: number) => unknown) | undefined;
+    clearTimer?: ((handle: unknown) => void) | undefined;
+    /** Claude answered every item. Polling has stopped. */
+    onResults: (results: DraftResult[], drafts: PendingDrafts) => void;
+    /** No answer within the timeout. Polling has stopped; start() polls again. */
+    onTimeout: () => void;
+    /** The file is gone (sent or cancelled elsewhere). Polling has stopped. */
+    onGone?: (() => void) | undefined;
+    /** A read failed; polling goes on. */
+    onError?: ((message: string) => void) | undefined;
+}
+/** Reads the session every 5 seconds until Claude answers, the file goes away, or 10 minutes pass. */
+export declare class DraftPoller {
+    private readonly o;
+    private handle;
+    private startedAt;
+    private running;
+    private busy;
+    constructor(o: DraftPollerOptions);
+    get active(): boolean;
+    private now;
+    private schedule;
+    /** Starts (or restarts, after a timeout) polling; the timeout counts from now. */
+    start(): void;
+    stop(): void;
+    private tick;
+    /** Reads the file once. True when polling is over (answered or gone). */
+    check(): Promise<boolean>;
+}

package/dist/explorations-github.d.ts

@@ -1,7 +1,7 @@
 import type { BridgeConfig } from './config';
-import { type Exploration, type ExplorationInstall, type ExplorationStatus, type PromotionPlan } from './explorations';
+import { type Exploration, type ExplorationSource, type ExplorationStatus, type ExplorationTryIt, type PromotionPlan } from './explorations';
 import { type GitHubClient, type PullRequestSummary } from './github-client';
-import { type PreviewApps } from './previews';
+import { type BranchPreview, type PreviewApps } from './previews';
 export interface ExplorationSettings {
     /** Branch explorations start from and pull requests target (the default branch). */
     base: string;
@@ -9,6 +9,11 @@ export interface ExplorationSettings {
     packages: string[];
     /** Per-branch preview URL templates (bridge.config.json previews.apps). */
     apps: PreviewApps;
+    /** Requests the exploration answers, listed in its draft pull request body. */
+    requests?: {
+        number: number;
+        title: string;
+    }[] | undefined;
 }
 export interface ExplorationSummary {
     number: number;
@@ -21,16 +26,24 @@ export interface ExplorationSummary {
     status: ExplorationStatus;
     draft: boolean;
     author: string;
+    /** Where it was started and the AI agent that started it, when the exploration block says so. */
+    source?: ExplorationSource | undefined;
+    agent?: string | undefined;
     updatedAt: string;
+    /** Head commit of the branch. */
+    headSha: string;
+    /**
+     * Template previews Vercel cannot have shortened (a host label of 63 characters or less), without a round trip. The
+     * URLs Vercel reports, with their build state, come from `explorationTestBuildOnGitHub`.
+     */
     previews: {
         app: string;
         label: string;
         url: string;
     }[];
-    install: ExplorationInstall;
 }
 /** One exploration from a pull request summary. */
-export declare function explorationSummary(p: PullRequestSummary, owner: string, repo: string, s: Pick<ExplorationSettings, 'packages' | 'apps'>): ExplorationSummary;
+export declare function explorationSummary(p: PullRequestSummary, _owner: string, _repo: string, s: Pick<ExplorationSettings, 'packages' | 'apps'>): ExplorationSummary;
 /** Explorations of the repo, newest activity first. `state: 'open'` lists the running ones and the promoted open ones. */
 export declare function listExplorationsOnGitHub(gh: GitHubClient, s: Pick<ExplorationSettings, 'packages' | 'apps'>, opts?: {
     state?: 'open' | 'closed' | 'all';
@@ -41,7 +54,8 @@ export interface StartedExploration {
     pr: number;
     url: string;
     commit: string;
-    install: ExplorationInstall;
+    /** Just started: the snapshot is not built yet. `explorationTestBuildOnGitHub` reads the command once it is. */
+    tryIt: ExplorationTryIt;
     previews: {
         app: string;
         label: string;
@@ -54,6 +68,30 @@ export interface StartedExploration {
  * install command. Refuses an exploration whose branch already exists.
  */
 export declare function startExplorationOnGitHub(gh: GitHubClient, e: Exploration, s: ExplorationSettings): Promise<StartedExploration>;
+/**
+ * Where the test build of an exploration stands: the install command from its sticky preview comment when it matches
+ * the branch head, "building" while the workflow has not caught up, "failed" when the publish failed. Two reads.
+ */
+export declare function explorationTryItOnGitHub(gh: GitHubClient, e: {
+    number: number;
+    branch: string;
+}): Promise<ExplorationTryIt>;
+export interface ExplorationTestBuild {
+    /** The install command from the sticky preview comment, or building/failed. Never a guessed command. */
+    tryIt: ExplorationTryIt;
+    /** Every configured app with the URL Vercel reports (null while unknown) and its build state. */
+    previews: BranchPreview[];
+    /** True when the command is ready (or the publish failed) and every preview is built: polling can stop. */
+    settled: boolean;
+}
+/**
+ * Everything "Try it" shows for an exploration, read in one go: the command from the preview comment and the real
+ * preview URLs (deployments, Vercel statuses, the Vercel comment). Comments and the branch head are read once.
+ */
+export declare function explorationTestBuildOnGitHub(gh: GitHubClient, e: {
+    number: number;
+    branch: string;
+}, config: Pick<BridgeConfig, 'previews'> | undefined): Promise<ExplorationTestBuild>;
 /** The open exploration pull request of a branch, slug or number. */
 export declare function findExplorationOnGitHub(gh: GitHubClient, ref: string | number): Promise<PullRequestSummary & {
     body: string;

package/dist/explorations.d.ts

@@ -13,6 +13,8 @@ export declare const EXPLORATION_TIER_LABEL = "Exploration (not mergeable)";
 export declare const EXPLORATION_CHECK = "Exploration not merged as is";
 export type ExplorationUseCase = 'user-test' | 'stakeholder-demo' | 'ab-idea' | 'terminal' | 'other';
 export type ExplorationStatus = 'active' | 'promoted' | 'closed';
+/** Where an exploration was started: Bridge Studio, the Figma plugin, the CLI or the MCP server (an AI agent). */
+export type ExplorationSource = 'studio' | 'figma' | 'cli' | 'mcp';
 export declare const EXPLORATION_USE_CASES: {
     value: ExplorationUseCase;
     label: string;
@@ -33,6 +35,10 @@ export interface Exploration {
     author?: string | undefined;
     /** ISO date it started. */
     startedAt?: string | undefined;
+    /** Where it was started, so Studio says "You" only for what the viewer started there. */
+    source?: ExplorationSource | undefined;
+    /** The AI agent that started it ("claude"), when one did: the GitHub account alone cannot tell. */
+    agent?: string | undefined;
 }
 /** "Denser data tables!" -> "denser-data-tables". Up to 40 characters, cut at a word boundary. Empty when nothing is left. */
 export declare function explorationSlug(name: string): string;
@@ -50,34 +56,6 @@ export declare function explorationProblems(e: Pick<Exploration, 'name' | 'purpo
 }): string[];
 /** The note committed as the first commit of the branch (`.bridge/explorations/<slug>.md`). */
 export declare function explorationNote(e: Exploration): string;
-export interface ExplorationInstall {
-    /** One command for every snapshot package, `npm i @bridge-ds/react@<snapshot> ...`, so internal dependencies match. */
-    command: string;
-    packages: {
-        name: string;
-        url: string;
-    }[];
-    /** Tarballs of the `preview-pr-<n>` prerelease, when pkg.pr.new is not set up. Needs the head commit. */
-    fallback?: {
-        command: string;
-        packages: {
-            name: string;
-            url: string;
-        }[];
-        release: string;
-    } | undefined;
-}
-/**
- * How a product staging branch installs an exploration: pkg.pr.new snapshots by pull request number (always the
- * latest commit), as `name@url` so package.json keeps the package name, and the prerelease tarballs as a fallback.
- */
-export declare function explorationInstall(input: {
-    owner: string;
-    repo: string;
-    pr: number;
-    packages: string[];
-    sha?: string | undefined;
-}): ExplorationInstall;
 export interface ExplorationPrContext {
     owner: string;
     repo: string;
@@ -149,6 +127,40 @@ export declare function promotionPlan(input: {
     requests?: number[] | undefined;
     date?: Date | undefined;
 }): PromotionPlan;
+/** Where the test build of an exploration stands, from its sticky preview comment and the branch head. */
+export type ExplorationTryIt = {
+    state: 'ready';
+    command: string;
+    source: 'pkg.pr.new' | 'release' | 'other';
+    sha7: string | null;
+} | {
+    state: 'building';
+} | {
+    state: 'failed';
+};
+/**
+ * The install command a product staging branch can trust, read from the `<!-- bridge-branch-preview -->` comment,
+ * never guessed: no comment yet, or a comment about an older commit than the head, means the snapshot is still
+ * building; a comment without a command means the publish failed.
+ */
+export declare function explorationTryIt(input: {
+    comment?: string | null | undefined;
+    headSha?: string | null | undefined;
+}): ExplorationTryIt;
+/**
+ * The message a designer sends a developer: what the exploration is, the install command for a product staging
+ * branch, the previews and the pull request. Plain text, one paragraph, ready to paste in a chat.
+ */
+export declare function explorationShareMessage(input: {
+    name: string;
+    branch: string;
+    url: string;
+    command?: string | null | undefined;
+    previews?: {
+        label: string;
+        url: string;
+    }[] | undefined;
+}): string;
 /**
  * The rules Claude follows on an exploration branch (request briefs, docs drafts, token edits with a target branch):
  * work there, never on main, and never open a pull request to main: the exploration's draft pull request is the place.