@bridge-ds/core 0.20.0 → 0.21.0

package/dist/exploration-done-github.d.ts

@@ -0,0 +1,50 @@
+import { type DoneExploringPlan, type ExplorationChecks, type ExplorationStatus } from './explorations';
+import { type GitHubClient } from './github-client';
+import { type ProposedPieces } from './prod-branch-github';
+import type { ProductConfig } from './products';
+import type { RequestSource } from './requests';
+export interface DoneExploringInput {
+    /** Piece ids the designer ticked: each becomes a request for the DS lead. Unticked ones are not proposed. */
+    pieces?: readonly string[] | undefined;
+    /** bridge.config.json products, to name the product the pieces are needed by. */
+    products?: readonly ProductConfig[] | undefined;
+    /** The exploration's preview, linked from each request so the DS lead sees the piece in context. */
+    previewUrl?: string | null | undefined;
+    /** Who said it, and the AI agent behind it ("claude"). */
+    openedBy?: string | undefined;
+    agent?: string | undefined;
+    source?: RequestSource | undefined;
+    date?: Date | undefined;
+    dryRun?: boolean | undefined;
+    /**
+     * The design system repository, when the exploration lives in a product's own repository (`gh` reads that one): the
+     * requests for the ticked pieces are filed there, where the DS lead works, linking back to the product pull request.
+     */
+    library?: GitHubClient | undefined;
+}
+export interface DoneExploring {
+    number: number;
+    url: string;
+    branch: string;
+    /** Where it stands after: ready (waiting for code), or what it already was when said again. */
+    status: ExplorationStatus;
+    /** False when it was already done exploring: only the newly ticked pieces were sent. */
+    handedOff: boolean;
+    plan: DoneExploringPlan | null;
+    pieces: ProposedPieces;
+    /** The two commands a developer runs to take it. */
+    take: [string, string];
+    /** The branch checks at the head developers start from, when GitHub said; null when it could not be read. */
+    checks: ExplorationChecks | null;
+    /** What developers read next to the commands, true to those checks. */
+    note: string;
+    /** Steps that did not go through, with what to do on GitHub instead. */
+    warnings: string[];
+}
+/**
+ * Says "Done exploring" on an exploration: requests for the ticked pieces first, then the note removed, the labels
+ * swapped and the body rewritten for developers (with the head they start from, so their pushes read "Being built").
+ * Said again on an exploration already handed off, it only sends the newly ticked pieces. Refused on a closed or
+ * shipped one. Never closes, merges or marks the draft ready.
+ */
+export declare function doneExploringOnGitHub(gh: GitHubClient, ref: string | number, input?: DoneExploringInput): Promise<DoneExploring>;

package/dist/exploration-resume.d.ts

@@ -0,0 +1,136 @@
+import { type ExplorationStatus } from './explorations';
+/** The phrase Claude recognizes to resume an exploration ("Continue Bridge exploration #12"). */
+export declare const CONTINUE_PHRASE = "Continue Bridge exploration";
+/** True when every changed file is a Bridge note (.bridge/): nothing the product is built from changed yet. */
+export declare const onlyNotes: (files: readonly string[] | null | undefined) => boolean;
+/**
+ * Where a running exploration stands: not started (nothing beyond the Bridge notes), exploring (something changed),
+ * or handed on (done exploring, being built, shipped, closed, archived: the pages keep their own layout). Files
+ * unknown (null): exploring, so a failed read never hides work behind "Nothing built yet".
+ */
+export declare function explorationStage(x: {
+    status: ExplorationStatus;
+    archived?: boolean | null | undefined;
+    files: readonly string[] | null | undefined;
+}): 'not-started' | 'exploring' | 'handed';
+export interface ContinueRef {
+    number: number;
+    name: string;
+    /** The product's display name ("Admin demo"). */
+    productName: string;
+    /** Set when the exploration lives in a product's own repository: its key ("shop") and that repository. */
+    product?: string | null | undefined;
+    repo?: string | null | undefined;
+}
+/** The ref Claude resolves: "#12", or "shop#12" in a product's own repository. */
+export declare const continueRef: (x: Pick<ContinueRef, "number" | "product" | "repo">) => string;
+/**
+ * The two lines a designer pastes to continue: in the Claude app, a sentence; in a terminal, the claude command.
+ * No em dash: the line is copied as is.
+ */
+export declare function continueLines(x: ContinueRef): {
+    app: string;
+    terminal: string;
+};
+/** Reads "Continue Bridge exploration #12" or "... shop#12" back into a ref ("#12", "shop#12"); null otherwise. */
+export declare function parseContinueLine(text: string): string | null;
+/** "BulkActionsBar" -> "Bulk actions bar", "DSBridgePanel" -> "DS bridge panel". */
+export declare function wordsOf(name: string): string;
+/**
+ * What one file is, for a designer: a component ("Bulk actions bar"), a screen ("Orders screen"), the tokens
+ * ("Tokens"), or null when it says nothing to them (helpers, config, tests, notes).
+ */
+export declare function thingOf(path: string): string | null;
+/** The distinct things the files are, in file order. */
+export declare function changedThings(files: readonly string[]): string[];
+/** "A", "A and B", "A, B and 3 more". */
+export declare function listThings(things: readonly string[], max?: number): string;
+/** A commit on the branch, as GitHub lists them (GET /pulls/{n}/commits). */
+export interface BranchCommitLike {
+    sha: string;
+    commit: {
+        message: string;
+        author?: {
+            name?: string | null;
+            date?: string | null;
+        } | null;
+        committer?: {
+            date?: string | null;
+        } | null;
+    };
+    author?: {
+        login?: string | null;
+    } | null;
+}
+export interface ActivityEvent {
+    /** "claude" for Claude's work, else the person's login (or git name). */
+    who: string;
+    /** Claude alone: a Claude account, or Claude's trailer with no person as the author (a bot or none). */
+    claude: boolean;
+    /** A person's commit Claude co-wrote (its co-author trailer or footer): shown as "Florian with Claude". */
+    withClaude?: boolean;
+    /** After the actor: "added row selection to the Orders table". */
+    text: string;
+    at: string;
+    sha?: string;
+}
+/** True when the commit carries Claude's co-author trailer or the Claude Code footer. */
+export declare function isClaudeAssisted(c: BranchCommitLike): boolean;
+/** The person who authored the commit (GitHub login, else git name), or null for a bot, Claude or nobody. */
+export declare function humanAuthorOf(c: BranchCommitLike): string | null;
+/**
+ * True when Claude alone wrote the commit: a Claude account, or Claude's trailer on a commit no person authored (a
+ * bot, or no author). A person's commit with Claude's trailer is theirs, made with Claude (isClaudeAssisted).
+ */
+export declare function isClaudeCommit(c: BranchCommitLike): boolean;
+/** True for the commit Bridge writes when it starts an exploration (only the note file). */
+export declare const isStartCommit: (c: BranchCommitLike) => boolean;
+/**
+ * A commit subject in words after the actor: "feat(orders): add row selection" -> "added row selection". Conventional
+ * prefixes go, an imperative first verb turns past, em dashes become commas. Other subjects: "changed things: <subject>".
+ */
+export declare function subjectWords(subject: string): string;
+/**
+ * The branch's activity, newest first: one event per commit (Bridge's start commit left out), then "started the
+ * exploration". `limit` keeps the newest ones, the start event included when it fits.
+ */
+export declare function explorationActivity(input: {
+    commits: readonly BranchCommitLike[];
+    author: string;
+    startedAt?: string | null | undefined;
+    limit?: number;
+}): ActivityEvent[];
+/**
+ * The line under the title once something changed: who changed what, from the branch files when they name screens
+ * or components ("changed Orders table and Bulk actions bar"), else the latest commit in words. Null before any change.
+ */
+export declare function lastActivity(input: {
+    commits: readonly BranchCommitLike[];
+    files: readonly string[] | null | undefined;
+    author: string;
+}): {
+    who: string;
+    claude: boolean;
+    withClaude?: boolean;
+    text: string;
+    at: string;
+} | null;
+/** "just now", "5 min ago", "2 h ago", "Yesterday", "3 days ago", then the date ("Oct 12"). */
+export declare function shortAgo(iso: string, now?: Date): string;
+/** "today", "yesterday", "3 days ago", "Oct 12": when it was started, after "Started by Ann · Admin demo ·". */
+export declare function startedWhen(iso: string, now?: Date): string;
+/** The actor in words: "Claude", "Florian", or "Florian with Claude" when Claude co-wrote a person's change. */
+export declare function actorName(e: Pick<ActivityEvent, 'who' | 'claude' | 'withClaude'>, names?: Record<string, string>): string;
+/**
+ * Where it stands, in one or two plain sentences, for Claude to say first when the designer continues it. No
+ * technical words: no branch, commit or pull request.
+ */
+export declare function whereItStands(input: {
+    name: string;
+    stage: 'not-started' | 'exploring' | 'handed';
+    statusLabel?: string;
+    events: readonly ActivityEvent[];
+    files: readonly string[] | null | undefined;
+    names?: Record<string, string>;
+    now?: Date;
+}): string;

package/dist/explorations-github.d.ts

@@ -1,7 +1,8 @@
 import type { BridgeConfig } from './config';
-import { type Exploration, type ExplorationSource, type ExplorationStatus, type ExplorationTryIt, type PromotionPlan } from './explorations';
+import { type Exploration, type ExplorationSource, type ExplorationStatus, type ExplorationPrContext, type ExplorationTryIt, type PromotionPlan } from './explorations';
 import { type GitHubClient, type PullRequestSummary } from './github-client';
 import { type BranchPreview, type PreviewApps } from './previews';
+import { type ProductConfig } from './products';
 export interface ExplorationSettings {
     /** Branch explorations start from and pull requests target (the default branch). */
     base: string;
@@ -16,7 +17,11 @@ export interface ExplorationSettings {
     }[] | undefined;
     /** More labels for the draft pull request, such as the product ones (productMarks). */
     labels?: string[] | undefined;
+    /** Started in a product's own repository (productRepoOf): what its draft pull request body says instead of the library's. */
+    inProduct?: ExplorationPrContext['inProduct'];
 }
+/** The first commit message of an exploration branch: the purpose only when one was given. */
+export declare const explorationStartMessage: (e: Pick<Exploration, "name" | "purpose">) => string;
 export interface ExplorationSummary {
     number: number;
     url: string;
@@ -26,6 +31,8 @@ export interface ExplorationSummary {
     purpose: string;
     useCase?: string | undefined;
     status: ExplorationStatus;
+    /** Archived (the `archived` label): hidden from the default lists, its pull request and preview still open. */
+    archived: boolean;
     draft: boolean;
     author: string;
     /** Where it was started and the AI agent that started it, when the exploration block says so. */
@@ -43,13 +50,49 @@ export interface ExplorationSummary {
         label: string;
         url: string;
     }[];
+    /**
+     * Set when the exploration lives in a product's own repository (productRepoOf): that repository ("owner/name") and
+     * the product key. Tools name it "<product>#<number>" (explorationRefLabel); absent in the design system repository.
+     */
+    repo?: string | undefined;
+    product?: string | undefined;
 }
 /** One exploration from a pull request summary. */
 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. */
+/**
+ * Explorations of the repo, newest activity first. `state: 'open'` lists the running ones and the open ones handed to
+ * developers. Archived ones are left out unless `archived` is 'include' (all) or 'only' (the Archived filter).
+ */
 export declare function listExplorationsOnGitHub(gh: GitHubClient, s: Pick<ExplorationSettings, 'packages' | 'apps'>, opts?: {
     state?: 'open' | 'closed' | 'all';
+    archived?: 'exclude' | 'include' | 'only';
 }): Promise<ExplorationSummary[]>;
+/** A product repository Bridge could not read while listing: left out of the lists, said only where connections live. */
+export interface UnreachableProductRepo {
+    product: string;
+    name: string;
+    repo: string;
+    /** not-connected: GitHub hides it (Bridge not installed there, or the token does not reach it); unavailable: any other failure. */
+    reason: 'not-connected' | 'unavailable';
+}
+/** GitHub hides the repository from this token, or Bridge's proxy says its app is not there. */
+export declare const isHiddenRepoError: (err: unknown) => boolean;
+/**
+ * The explorations of every product that has its own repository (bridge.config.json products[].repo): one read of
+ * the open (or `state`) pull requests per repository, all in parallel. Each one carries its `repo` and `product`, and
+ * the product's preview template as its preview. A repository Bridge cannot read is skipped and reported in
+ * `unreachable`, never thrown: designers never see it in a list, Settings says it. `clientFor` gives a client for
+ * "owner/name" with the same token (or proxy) as the design system repository.
+ */
+export declare function listProductExplorationsOnGitHub(clientFor: (repo: string) => GitHubClient, products: readonly ProductConfig[], designSystemRepo: string | null | undefined, opts?: {
+    state?: 'open' | 'closed' | 'all';
+    archived?: 'exclude' | 'include' | 'only';
+}): Promise<{
+    explorations: ExplorationSummary[];
+    unreachable: UnreachableProductRepo[];
+}>;
+/** An exploration read in a product's own repository: its repository, its product and the product's preview. */
+export declare function inProductRepo(x: ExplorationSummary, product: ProductConfig, repo: string): ExplorationSummary;
 export interface StartedExploration {
     branch: string;
     slug: string;
@@ -70,6 +113,20 @@ export interface StartedExploration {
  * install command. Refuses an exploration whose branch already exists.
  */
 export declare function startExplorationOnGitHub(gh: GitHubClient, e: Exploration, s: ExplorationSettings): Promise<StartedExploration>;
+/** Whether Bridge can open an exploration in a product's own repository with this token, and from which branch. */
+export type ProductRepoAccess = {
+    ok: true;
+    base: string;
+} | {
+    ok: false;
+    reason: 'not-connected' | 'read-only';
+};
+/**
+ * One read of a product's own repository before an exploration starts there: its default branch when the token may
+ * push to it; `not-connected` when GitHub hides it (Bridge is not installed on it, or the token does not reach it);
+ * `read-only` when the person may only read it. A rejected token or a GitHub outage still throws.
+ */
+export declare function productRepoAccess(gh: GitHubClient): Promise<ProductRepoAccess>;
 /**
  * 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.
@@ -116,7 +173,22 @@ export declare function promoteExplorationOnGitHub(gh: GitHubClient, ref: string
     date?: Date | undefined;
     dryRun?: boolean | undefined;
 }): Promise<PromotedExploration>;
-/** Closes an exploration without merging. The branch stays for reference; the workflow removes the prerelease. */
+/**
+ * Archives an exploration (the `archived` label), or brings it back with `archived: false`. The pull request stays
+ * open, so its preview link keeps working: archiving only hides it from the default lists.
+ */
+export declare function archiveExplorationOnGitHub(gh: GitHubClient, ref: string | number, opts?: {
+    archived?: boolean;
+}): Promise<{
+    number: number;
+    url: string;
+    branch: string;
+    archived: boolean;
+}>;
+/**
+ * Closes an exploration without merging. The branch stays for reference, but the workflows remove its preview
+ * prerelease and visual images: archiving (archiveExplorationOnGitHub) keeps the link alive instead.
+ */
 export declare function closeExplorationOnGitHub(gh: GitHubClient, ref: string | number): Promise<{
     number: number;
     url: string;

package/dist/explorations.d.ts

@@ -11,8 +11,17 @@ export declare const EXPLORATION_NOTES_DIR = ".bridge/explorations";
 export declare const EXPLORATION_TIER_LABEL = "Exploration (not mergeable)";
 /** Name of the CI job that fails while the label is on. */
 export declare const EXPLORATION_CHECK = "Exploration not merged as is";
+/** Done exploring: the exploration label gives way to this one. Developers take the branch from there. */
+export declare const EXPLORATION_READY_LABEL = "ready-for-devs";
+/** An archived exploration: hidden from the default lists, its pull request and preview still open. */
+export declare const EXPLORATION_ARCHIVED_LABEL = "archived";
 export type ExplorationUseCase = 'user-test' | 'stakeholder-demo' | 'ab-idea' | 'terminal' | 'other';
-export type ExplorationStatus = 'active' | 'promoted' | 'closed';
+/**
+ * active: running (the exploration label is on). ready: done exploring, waiting for developers to take it. building:
+ * developers pushed to it (or marked it ready for review) since. shipped: merged after done exploring. promoted: sent
+ * to review the older way (label removed without done exploring), open or merged. closed: closed without merging.
+ */
+export type ExplorationStatus = 'active' | 'ready' | 'building' | 'shipped' | '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: {
@@ -24,7 +33,10 @@ export declare const EXPLORATION_STATUS_LABEL: Record<ExplorationStatus, string>
 export interface Exploration {
     /** Display name, sentence case: "Denser data tables". */
     name: string;
-    /** What the team wants to learn, in one or two sentences. */
+    /**
+     * What the team wants to learn, in one or two sentences, or empty: designers explore freely and nobody is asked
+     * for a brief (Claude passes the designer's first sentence when it has one).
+     */
     purpose: string;
     /** Branch slug: `explore/<slug>`. Derived from the name when missing. */
     slug?: string | undefined;
@@ -41,8 +53,14 @@ export interface Exploration {
     agent?: string | undefined;
     /** A Jira ticket key ("DS-42"), first in the pull request title so Jira's GitHub integration links it. */
     jira?: string | undefined;
+    /** ISO date someone said "Done exploring". */
+    doneAt?: string | undefined;
+    /** The branch head at that moment: a newer head means developers are building on it. */
+    doneSha?: string | undefined;
 }
-/** "Denser data tables!" -> "denser-data-tables". Up to 40 characters, cut at a word boundary. Empty when nothing is left. */
+/** Longest slug: a name is under 60 characters (explorationProblems), so a valid name is never cut mid-phrase. */
+export declare const EXPLORATION_SLUG_MAX = 60;
+/** "Denser data tables!" -> "denser-data-tables". Up to 60 characters, cut at a word boundary. Empty when nothing is left. */
 export declare function explorationSlug(name: string): string;
 /** `explore/<slug>` for a name, a slug or a branch name. */
 export declare function explorationBranch(nameOrBranch: string): string;
@@ -50,10 +68,35 @@ export declare function explorationBranch(nameOrBranch: string): string;
 export declare function isExplorationBranch(ref: string | null | undefined): boolean;
 /** The slug of an exploration branch, or null. */
 export declare function explorationSlugFromBranch(ref: string): string | null;
+/**
+ * Which exploration a person or a tool means, wherever it lives. In the design system repository: its number ("12",
+ * "#12") or its name ("pill-buttons", "explore/pill-buttons"). In a product's own repository, the product key or the
+ * repository goes first: "shop#12", "peterbono/bridge-demo-shop#12", "shop:checkout-flow", or the pull request link.
+ */
+export interface ExplorationRef {
+    /** A product key ("shop"), when the reference names one. */
+    product?: string | undefined;
+    /** "owner/name", when the reference names the repository (a link or owner/name#12). */
+    repo?: string | undefined;
+    /** The pull request number, or the exploration's name or branch. */
+    ref: number | string;
+}
+/** Reads an exploration reference (ExplorationRef). Anything else is taken as a name in the design system repository. */
+export declare function parseExplorationRef(input: string | number): ExplorationRef;
+/** How tools name an exploration back: "#12" in the design system repository, "shop#12" in a product's own one. */
+export declare const explorationRefLabel: (x: {
+    number: number;
+    product?: string | null | undefined;
+    repo?: string | null | undefined;
+}) => string;
 /** Path of the note that starts an exploration branch. */
 export declare const explorationNotePath: (slug: string) => string;
-/** Problems with a new exploration, as sentences that say how to fix them. Empty when it can start. */
-export declare function explorationProblems(e: Pick<Exploration, 'name' | 'purpose'> & {
+/**
+ * Problems with a new exploration, as sentences that say how to fix them. Empty when it can start. Only the name is
+ * needed: the purpose is optional, nobody has to write a brief to explore.
+ */
+export declare function explorationProblems(e: Pick<Exploration, 'name'> & {
+    purpose?: string | undefined;
     slug?: string | undefined;
 }): string[];
 /** The note committed as the first commit of the branch (`.bridge/explorations/<slug>.md`). */
@@ -70,12 +113,26 @@ export interface ExplorationPrContext {
         number: number;
         title: string;
     }[] | undefined;
+    /**
+     * Set when the exploration lives in a product's own repository (productRepoOf): the body says to check the branch
+     * out there and to get the library from npm (`library`: the design system repository), with the product's preview
+     * template instead of the library's apps.
+     */
+    inProduct?: {
+        name: string;
+        library: string;
+        preview?: string | undefined;
+    } | undefined;
 }
-/** Draft pull request title: "Exploration: denser data tables". */
+/**
+ * Draft pull request title: "Exploration: Denser data tables". The name keeps its casing as typed; a name that already
+ * starts with "Exploration:" is not prefixed twice, and a colon inside the name becomes a comma so the title has one
+ * ("Exploration page: pick up" -> "Exploration: Exploration page, pick up").
+ */
 export declare function explorationPrTitle(e: Pick<Exploration, 'name'>): string;
 /**
  * The draft pull request body: purpose, what is experimental, how a product staging branch installs it, the
- * previews, and how to promote or close it. Markdown for people plus one hidden JSON block for tools.
+ * previews, and how it ends (Done exploring, Archive). Markdown for people plus one hidden JSON block for tools.
  */
 export declare function explorationPrBody(e: Exploration, ctx: ExplorationPrContext): string;
 /** The exploration inside a pull request body, or undefined when it has no valid Bridge block. */
@@ -89,16 +146,88 @@ export interface ExplorationPullLike {
     })[];
     headRef?: string | undefined;
     body?: string | null | undefined;
+    /** Head commit and draft flag: after "Done exploring", a newer head or a ready pull request reads "Being built". */
+    headSha?: string | undefined;
+    draft?: boolean | undefined;
 }
 /** True for a pull request that is or was an exploration: an `explore/*` branch, the label, or the Bridge block. */
 export declare function isExplorationPull(p: ExplorationPullLike): boolean;
+/** "Done exploring" was said: the `ready-for-devs` label, or the date in the exploration block. */
+export declare function isHandedOff(p: Pick<ExplorationPullLike, 'labels' | 'body'>): boolean;
 /**
  * Where an exploration stands: closed without merging = closed; open with the `exploration` label = active
- * (running); otherwise promoted (the label was removed, so it is a normal pull request now, open or merged).
+ * (running). After "Done exploring": merged = shipped; marked ready for review, or a head newer than the one done
+ * exploring left = building (developers work on it); otherwise ready (waiting for code). The label removed without
+ * done exploring is the older promotion: promoted, open or merged.
  */
 export declare function explorationStatus(p: ExplorationPullLike): ExplorationStatus;
 /** True while the label is on: the pull request must not merge (the CI check fails, Studio blocks the merge). */
 export declare const isActiveExploration: (labels: ExplorationPullLike["labels"]) => boolean;
+/** True for an archived exploration: hidden from the default lists, reachable from the Archived filter. */
+export declare const isArchivedExploration: (labels: readonly (string | {
+    name?: string;
+})[] | null | undefined) => boolean;
+/**
+ * Open explorations that stay out of the review queue: running, archived, or handed to developers while still a
+ * draft. Once developers mark it ready for review it is a change like any other.
+ */
+export declare function isHeldExploration(p: {
+    state?: string | undefined;
+    draft?: boolean | undefined;
+    labels?: readonly (string | {
+        name?: string;
+    })[] | null | undefined;
+}): boolean;
+/** How a developer takes an exploration: fetch, then check out its branch. */
+export declare const explorationTakeCommands: (branch: string) => [string, string];
+/** What developers read next to those commands, when nothing is known about the branch checks: a starting point. */
+export declare const EXPLORATION_STARTING_POINT = "A starting point, not ready to ship: nobody has reviewed Claude's prototype code yet. Continue on this branch: its pull request already exists, so Bridge follows your pushes, and the merge reads as shipped.";
+/** The branch checks at its head, folded into one state (GitHubClient.getChecks). */
+export type ExplorationChecks = 'success' | 'failure' | 'pending' | 'none';
+/**
+ * The starting point note, true to the branch checks: passing checks are said as such (the code is still not
+ * reviewed), failing or missing checks too. Without a state it is EXPLORATION_STARTING_POINT.
+ */
+export declare function explorationStartingPoint(checks?: ExplorationChecks | null | undefined): string;
+export interface DoneExploringPlan {
+    /** Labels to remove (the exploration label) and to add (ready-for-devs). */
+    removeLabels: string[];
+    addLabels: string[];
+    /** Files to delete on the branch first: the exploration note, so main never gets it. */
+    removeFiles: string[];
+    /** The body once done: the developer section in place of the sandbox note and the "When it is done" part. */
+    body: string;
+    /** The two commands a developer runs to take it. */
+    take: [string, string];
+    /** Done exploring never merges, closes or marks the draft ready. */
+    markReady: false;
+}
+/**
+ * What "Done exploring" does to the pull request: the exploration label gives way to `ready-for-devs` (the merge
+ * guard stops failing, so developers can ship it once the code is theirs), the exploration note leaves the branch, and
+ * the body says how developers take it. The draft stays a draft and the pull request stays open, so its preview lives
+ * on. The caller records the head once the note is gone (withDoneExploring with `doneSha`).
+ */
+export declare function doneExploringPlan(input: {
+    body: string | null | undefined;
+    branch: string;
+    files: {
+        path: string;
+        status?: string | undefined;
+    }[];
+    date?: Date | undefined;
+}): DoneExploringPlan;
+/**
+ * The body after "Done exploring": the sandbox warning and the "When it is done" part give way to the developer
+ * section (the two commands and the starting point note), and the hidden block records when, and on which head once
+ * known. Calling it again replaces the section and the block.
+ */
+export declare function withDoneExploring(body: string | null | undefined, done: {
+    branch: string;
+    doneAt: string;
+    doneSha?: string | undefined;
+    checks?: ExplorationChecks | null | undefined;
+}): string;
 export interface PromotionPlan {
     tier: RiskTier;
     reasons: string[];

package/dist/figma-fix-loop.d.ts

@@ -68,7 +68,7 @@ export interface GapCaseFor {
 }
 /** The gap case of one component, built the way the plugin pulls it: fixes applied, set rebuilt, the run's verdicts. */
 export declare function gapCaseFor(input: GapCaseForInput): GapCaseFor;
-export declare const FIX_SCHEMA_SUMMARY = "figma-fixes.json fixes (version 1). Each fix is one JSON object:\n- Every fix: \"id\" (lower case, digits, dashes, unique), \"kind\", \"component\" (the Figma set, e.g. \"TextInput\"), \"reason\" (one plain sentence, no em dash), optional \"by\": \"claude\", optional \"where\": { \"args\": { \"<arg>\": value }, \"state\": \"rest\" | \"hover\" | \"active\" | \"focus-visible\" | \"disabled\" } (absent: every variant).\n- kind \"part\": \"part\" is a part id from the gap case (\"root\", \"cds--text-input-label-wrapper\") or \".class\". At least one of: \"set\" { field: token path | px number | null (colors only) | \"full\" (cornerRadius only) }, \"width\" / \"height\": \"fixed\" (the measured size) | px number | \"hug\" | \"fill\", \"direction\": \"HORIZONTAL\" | \"VERTICAL\", \"align\": { \"primary\": MIN|CENTER|MAX|SPACE_BETWEEN, \"counter\": MIN|CENTER|MAX|STRETCH }, \"overlay\": true | false | { \"top\": 3, \"left\": 3 }, \"hide\": true (alone; never the root). Fields: fill, stroke, strokeWeight, strokeTopWeight, strokeRightWeight, strokeBottomWeight, strokeLeftWeight, cornerRadius, paddingTop, paddingRight, paddingBottom, paddingLeft, itemSpacing, counterAxisSpacing, width, height, minWidth, minHeight, opacity, textFill, fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, textDecoration.\n- kind \"axis\": \"action\" \"map\" (\"arg\", \"property\" and/or \"values\" { code value: Figma value }), \"ignore\" (\"arg\"), or \"prune\" (\"where\" names the variants to drop).\n- kind \"story\": \"where\" names the variant, \"use\": { \"story\": \"<story id>\", \"args\"?, \"state\"? } is the measured render to draw it from.\n- kind \"status\": \"status\": \"differs\" | \"cant-check\" with the reason; never \"matches\" (only the shots say a component matches). Without \"status\": a note.\nRules: fix only the component you were given; prefer the smallest fix that explains the differences (a part's size \"fixed\" when Figma hugs what code fixes, a missing padding, a hidden part); never invent a part id or a token: use the ones in the gap case.";
+export declare const FIX_SCHEMA_SUMMARY = "figma-fixes.json fixes (version 1). Each fix is one JSON object:\n- Every fix: \"id\" (lower case, digits, dashes, unique), \"kind\", \"component\" (the Figma set, e.g. \"TextInput\"), \"reason\" (one plain sentence, no em dash), optional \"by\": \"claude\", optional \"where\": { \"args\": { \"<arg>\": value }, \"state\": \"rest\" | \"hover\" | \"active\" | \"focus-visible\" | \"disabled\" } (absent: every variant).\n- kind \"part\": \"part\" is a part id from the gap case (\"root\", \"cds--text-input-label-wrapper\") or \".class\". At least one of: \"set\" { field: token path | px number | null (colors only) | \"full\" (cornerRadius only) }, \"width\" / \"height\": \"fixed\" (each story's own measured size; a width that only hugs text in code is skipped, since it is the story's words) | px number | \"hug\" | \"fill\", \"direction\": \"HORIZONTAL\" | \"VERTICAL\", \"align\": { \"primary\": MIN|CENTER|MAX|SPACE_BETWEEN, \"counter\": MIN|CENTER|MAX|STRETCH }, \"overlay\": true | false | { \"top\": 3, \"left\": 3 }, \"hide\": true (alone; never the root). Fields: fill, stroke, strokeWeight, strokeTopWeight, strokeRightWeight, strokeBottomWeight, strokeLeftWeight, cornerRadius, paddingTop, paddingRight, paddingBottom, paddingLeft, itemSpacing, counterAxisSpacing, width, height, minWidth, minHeight, opacity, textFill, fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, textDecoration.\n- kind \"axis\": \"action\" \"map\" (\"arg\", \"property\" and/or \"values\" { code value: Figma value }), \"ignore\" (\"arg\"), or \"prune\" (\"where\" names the variants to drop).\n- kind \"story\": \"where\" names the variant, \"use\": { \"story\": \"<story id>\", \"args\"?, \"state\"? } is the measured render to draw it from.\n- kind \"status\": \"status\": \"differs\" | \"cant-check\" with the reason; never \"matches\" (only the shots say a component matches). Without \"status\": a note.\nRules: fix only the component you were given; prefer the smallest fix that explains the differences (a part's size \"fixed\" when Figma hugs what code fixes, a missing padding, a hidden part); never invent a part id or a token: use the ones in the gap case.";
 export type FixDiffResult = 'resolved' | 'closer' | 'same' | 'worse' | 'unknown';
 export type FixVerdict = 'closer' | 'same' | 'worse';
 export interface TriedDifference {

package/dist/figma-fixes.d.ts

@@ -134,8 +134,12 @@ export interface AppliedFix {
     id: string;
     kind: FigmaFix['kind'];
     component: string;
-    /** applied: it changed what the pull draws. not-found: nothing matched (the code or the measure moved: re-check it). already: the input had it. */
-    result: 'applied' | 'not-found' | 'already';
+    /**
+     * applied: it changed what the pull draws. not-found: nothing matched (the code or the measure moved: re-check it).
+     * skipped: it matched, but the measure has no size of the part's own to pin there (the detail says why). already:
+     * the input had it.
+     */
+    result: 'applied' | 'not-found' | 'skipped' | 'already';
     /** Story entries it changed. */
     stories: number;
     /** Plain words: what it did, or what it did not find. */
@@ -152,6 +156,14 @@ export type FixedMeasuredSpecsFile = Omit<MeasuredSpecsFile, 'stories' | 'compon
 };
 /** A story is one of `where`'s variants: every arg it names, at that value, and the state. */
 export declare function storyMatchesWhere(s: MeasuredSpecsStory, where: FixWhere | undefined): boolean;
+/** Why a `fixed` size was not laid on one part of one story: the measure has no size of the part's own there. */
+export interface SkippedSize {
+    part: string;
+    side: 'width' | 'height';
+    why: 'words' | 'fills' | 'unmeasured';
+    /** The measured px it did not pin (words, fills). */
+    measured?: number | undefined;
+}
 /**
  * The measured specs the pull reads, with the fixes laid on, and one provenance record per fix. Pure: the input is not
  * changed. Fixes run in file order; a fix whose component, part or story is not in this measure is reported

package/dist/github-client.d.ts

@@ -638,6 +638,23 @@ export declare class GitHubClient {
         autoMerge: boolean;
     }>;
     listPullRequestFiles(n: number): Promise<PullRequestFile[]>;
+    /** The commits of a pull request, oldest first, as GitHub lists them (one read, up to 100). */
+    listPullRequestCommits(n: number): Promise<{
+        sha: string;
+        commit: {
+            message: string;
+            author?: {
+                name?: string | null;
+                date?: string | null;
+            } | null;
+            committer?: {
+                date?: string | null;
+            } | null;
+        };
+        author?: {
+            login?: string | null;
+        } | null;
+    }[]>;
     updatePullRequest(n: number, patch: {
         title?: string;
         body?: string;

package/dist/index.d.ts

@@ -41,6 +41,8 @@ export * from './change-drafts';
 export * from './draft-exchange';
 export * from './explorations';
 export * from './explorations-github';
+export * from './exploration-done-github';
+export * from './exploration-resume';
 export * from './requests-github';
 export * from './component-spec';
 export * from './measured-spec';