@12ui/design 0.2.13 → 0.2.15

package/README.md

@@ -52,24 +52,27 @@ name) to install one skill instead of the complete bundle.
 ## Five visual interface skills
 
 - `design` routes UI, web, and mobile work. Finished screenshots go directly
-  to conversion, tiny edits stay code-only, and rough briefs retrieve exactly
+  to conversion, tiny edits stay code-only, and rough briefs classify the
+  deliverable as one fold, one full page, or a multi-page app, retrieve exactly
   four references, generate four candidates using one different reference per
-  candidate, select one, convert only the winner, integrate it, and verify the
-  real surface.
+  candidate, select one, execute the recorded scope, integrate the result, and
+  verify the real surface.
 - `design-search` returns a ranked, diverse set of real Design Corpus
   references while preserving endpoint order and metrics.
 - `design-draft` drafts candidates from a brief by claiming one
   `/api/v1/create` run, dispatches each candidate slot once, and downloads the
   images without re-buying a settled slot.
-- `design-branch` expands one approved design into the 2-8 screens the server
-  plans, dispatching each screen only once its dependency and footer gates
-  clear.
+- `design-branch` is required whenever the deliverable is more than one
+  viewport. One `12ui branch execute` run expands one approved design into the
+  2-8 screens the server plans, dispatching each only once its dependency and
+  footer gates clear, and converts each page as one ordered package.
 - `design-convert` turns a finished PNG, JPEG, or WebP into LayerDoc and any
-  supported responsive, fixed, project, or document export.
+  supported responsive, fixed, project, or document export, and converts the
+  ordered viewports of one page as a single package.
 
 `design-search`, `design-draft`, and `design-branch` are pipeline stages the
-`design` skill can also run end to end; install one when an agent only needs
-that stage.
+`design` skill also runs end to end as part of its main flow; install one when
+an agent only needs that stage.
 
 The design workflow exists because code-first agents often converge on safe,
 generic visual defaults. Corpus-conditioned image generation expands the
@@ -85,6 +88,14 @@ manual recreation.
   --out-dir ./references \
   --count 4
 12ui image generate-batch --manifest ./generation.json
+12ui image batch-status --manifest ./generation.json
+12ui branch execute \
+  --winner-image ./candidates/A.png \
+  --concept "Editorial architecture studio site" \
+  --scope site \
+  --out-dir ./branch \
+  --convert html
+12ui branch status --out-dir ./branch
 12ui export <base-layerdoc-conversion-id> \
   --output html,pdf,psd,pptx,sketch,web_project \
   --out-dir ./exports \
@@ -256,9 +267,24 @@ export TWELVE_UI_API_KEY=your-key
 12ui convert ./screen.layerdoc.json --output pptx --out ./screen.pptx --idempotency-key screen-pptx-v1
 12ui convert ./screen.layerdoc.json --output web_project --profile ./react-tailwind.json --out ./screen-react.zip
 12ui convert ./screen.layerdoc.json --output app_project --profile '{"version":1,"framework":"swiftui","styling":"native","language":"swift","packaging":"project"}' --out ./screen-ios.zip
+12ui convert package --manifest ./package.json --out-dir ./pages
 12ui resume conversion-id --output layerdoc --out ./screen.layerdoc.json
 ```
 
+`convert package` submits the ordered viewports of one continuous page as ONE
+package conversion per page, which is what preserves page order and stitching;
+converting a stacked page one image at a time loses both. Every viewport of a
+page must share one width, checked locally before anything is bought. A viewport
+may name `sourceConversionId` to reuse an already succeeded conversion of
+exactly those bytes instead of paying for it twice.
+
+Long commands block until they finish, and `--wait` names that default
+explicitly. While one runs, `12ui branch status --out-dir <dir>` and
+`12ui image batch-status --manifest <file>` report forward motion — per-item
+state, elapsed against typical, and what to do next — without touching the run.
+Do not infer progress from a directory listing: staged work is materialized in
+one atomic pass at the end.
+
 Each conversion also writes a verified `<out>.assets/manifest.json` plus every
 signed raster artifact beside the requested result. Set `TWELVE_UI_ORIGIN` to
 override `https://12ui.com`; waits default to the operation expiry and can be

package/dist/bounded-concurrency.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A bounded worker pool expressed as a function: `limiter(task)` starts the
+ * task as soon as fewer than `limit` of them are running, and never more.
+ *
+ * Independent work runs in parallel, but the bound is real rather than
+ * decorative: every concurrent branch page holds two or three viewport children
+ * on the server, admission is measured at the account boundary, and an
+ * unbounded fan-out would spend the run's admission slots queueing instead of
+ * converting.
+ */
+export type ConcurrencyLimiter = <T>(task: () => Promise<T>) => Promise<T>;
+export declare const createConcurrencyLimiter: (limit: number) => ConcurrencyLimiter;
+//# sourceMappingURL=bounded-concurrency.d.ts.map

package/dist/bounded-concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-concurrency.d.ts","sourceRoot":"","sources":["../src/bounded-concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAE3E,eAAO,MAAM,wBAAwB,GAAI,OAAO,MAAM,KAAG,kBAiCxD,CAAC"}

package/dist/bounded-concurrency.js

@@ -0,0 +1,43 @@
+/**
+ * A bounded worker pool expressed as a function: `limiter(task)` starts the
+ * task as soon as fewer than `limit` of them are running, and never more.
+ *
+ * Independent work runs in parallel, but the bound is real rather than
+ * decorative: every concurrent branch page holds two or three viewport children
+ * on the server, admission is measured at the account boundary, and an
+ * unbounded fan-out would spend the run's admission slots queueing instead of
+ * converting.
+ */
+export const createConcurrencyLimiter = (limit) => {
+    const bound = Math.max(1, Math.floor(limit));
+    let running = 0;
+    const waiting = [];
+    const acquire = async () => {
+        if (running < bound) {
+            running += 1;
+            return;
+        }
+        await new Promise((resolve) => { waiting.push(resolve); });
+    };
+    // The finishing task hands its slot straight to the next waiter rather than
+    // decrementing: a released count would let a caller that arrives before the
+    // waiter wakes overtake it and put `bound + 1` tasks in flight.
+    const release = () => {
+        const next = waiting.shift();
+        if (next) {
+            next();
+            return;
+        }
+        running -= 1;
+    };
+    return async (task) => {
+        await acquire();
+        try {
+            return await task();
+        }
+        finally {
+            release();
+        }
+    };
+};
+//# sourceMappingURL=bounded-concurrency.js.map

package/dist/bounded-concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bounded-concurrency.js","sourceRoot":"","sources":["../src/bounded-concurrency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,KAAa,EAAsB,EAAE;IAC5E,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7C,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,OAAO,GAAmB,EAAE,CAAC;IAEnC,MAAM,OAAO,GAAG,KAAK,IAAmB,EAAE;QACxC,IAAI,OAAO,GAAG,KAAK,EAAE,CAAC;YACpB,OAAO,IAAI,CAAC,CAAC;YACb,OAAO;QACT,CAAC;QACD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnE,CAAC,CAAC;IAEF,4EAA4E;IAC5E,4EAA4E;IAC5E,gEAAgE;IAChE,MAAM,OAAO,GAAG,GAAS,EAAE;QACzB,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC;QAC7B,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QACD,OAAO,IAAI,CAAC,CAAC;IACf,CAAC,CAAC;IAEF,OAAO,KAAK,EAAK,IAAsB,EAAc,EAAE;QACrD,MAAM,OAAO,EAAE,CAAC;QAChB,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,EAAE,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC,CAAC;AACJ,CAAC,CAAC"}

package/dist/branch-client.d.ts

@@ -0,0 +1,155 @@
+import type { ConversionConfig } from './config.js';
+/**
+ * The create/build API as the CLI needs it: a port of the web app's
+ * `apps/web/src/pages/create/createApi.ts` with the browser identity, Turnstile,
+ * and object-URL machinery removed and Bearer key auth in their place.
+ *
+ * The wire envelope is deliberately NOT `BranchPlan` verbatim. `plan.pages[]`
+ * carries the ordering (`slots`), while every per-screen fact —
+ * `viewportOrdinal`, `header`, `footer`, `pageEndsHere`, `dependsOnSlot`,
+ * `content` — lives on `candidates[]`. Those are two different places and both
+ * are needed to reconstruct the page grouping.
+ */
+export declare const BRANCH_MAX_CONCEPT_CHARACTERS = 600;
+export type BranchAspect = 'landscape' | 'portrait' | 'square';
+export type BranchPageKind = 'source' | 'additional';
+export type BranchScreenStatus = 'pending' | 'dispatched' | 'succeeded' | 'failed';
+export type BranchPlanPageEnvelope = {
+    index: number;
+    kind: BranchPageKind;
+    title: string;
+    pageType: string;
+    surfaceType: string;
+    purpose: string;
+    /** Source page only: the approved screen already reaches its natural end. */
+    sourceEndsHere?: boolean;
+    /** This page's slots, in viewport order. */
+    slots: string[];
+};
+export type BranchPlanEnvelope = {
+    sitePurpose: string;
+    /** First person, written for the user. Safe to render verbatim. */
+    statusUpdate: string;
+    approvedScreenSummary: string;
+    pages: BranchPlanPageEnvelope[];
+};
+export type BranchCandidateEnvelope = {
+    slot: string;
+    status: BranchScreenStatus;
+    direction: string;
+    width: number;
+    height: number;
+    image?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+    pageIndex?: number;
+    /** 1-based within an additional page; source continuations begin at 2. */
+    viewportOrdinal?: number;
+    /** null means webpage chrome semantics do not apply to this surface. */
+    header?: boolean | null;
+    footer?: boolean | null;
+    pageEndsHere?: boolean;
+    /** The previous viewport of the same page, which must succeed first. */
+    dependsOnSlot?: string | null;
+    content?: string;
+};
+export type BranchRunEnvelope = {
+    id: string;
+    concept: string;
+    aspect: BranchAspect;
+    source?: 'create' | 'build';
+    createdAt?: string;
+    expiresAt?: string;
+    plan?: BranchPlanEnvelope;
+    candidates: BranchCandidateEnvelope[];
+};
+export type BranchStartInput = {
+    concept: string;
+    aspect?: BranchAspect;
+    winner?: {
+        createRunId: string;
+        slot: string;
+    };
+    referenceImage?: {
+        data: string;
+        mediaType: string;
+        sha256: string;
+    };
+};
+/**
+ * The other shape the same endpoint accepts: an explicit candidate list rather
+ * than a planned build. `12ui draft` covers the four-candidate case; this is
+ * the one with per-slot directions and references.
+ */
+export type CreateStartInput = {
+    concept: string;
+    aspect?: BranchAspect;
+    mode?: 'inspiration' | 'preserve-structure';
+    candidates: readonly {
+        slot: string;
+        direction?: string;
+        referenceId?: string;
+        useReferenceImage?: boolean;
+    }[];
+    referenceImage?: {
+        data: string;
+        mediaType: string;
+        sha256: string;
+    };
+};
+export declare class BranchApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly retryAfterSeconds?: number;
+    /** Branch gating only: the slot that must succeed before this one runs. */
+    readonly dependsOn?: string;
+    constructor(message: string, status: number, code: string, options?: {
+        retryAfterSeconds?: number;
+        dependsOn?: string;
+    });
+}
+/**
+ * TWO error shapes live behind one status. The dependency gates answer 409 with
+ * a NESTED object — `{"error":{"code","dependsOn","message"}}` — while every
+ * other refusal, `candidate_in_flight` included, uses the FLAT helper —
+ * `{"error":"candidate_in_flight","message":…}` — where `error.code` is
+ * undefined. Reading only one of the two silently mis-routes the other, which
+ * is exactly the trap the branch skill used to invite.
+ */
+export declare const parseBranchFailure: (status: number, body: unknown, retryAfterHeader?: string | null) => BranchApiError;
+export type BranchClientOptions = ConversionConfig & {
+    fetch?: typeof fetch;
+};
+export declare class TwelveUiBranchClient {
+    #private;
+    readonly origin: string;
+    constructor(options: BranchClientOptions);
+    /**
+     * Claim the build run. The planner runs inline — 10 to 20 seconds — and buys
+     * no image. The key derives the run id, so replaying it returns the same run.
+     */
+    startBuildRun(input: BranchStartInput, idempotencyKey: string, signal?: AbortSignal): Promise<BranchRunEnvelope>;
+    /**
+     * Claim a candidate run. Buys no image; the key derives the run, so replaying
+     * it returns the same run and its stored images rather than a second set.
+     */
+    startCreateRun(input: CreateStartInput, idempotencyKey: string, signal?: AbortSignal): Promise<BranchRunEnvelope>;
+    /**
+     * Dispatch one screen. Unkeyed by default and by design: an unkeyed repeat
+     * replays the settled screen for free, while a NEW key on a settled slot buys
+     * another image. Only an explicit redraw passes one.
+     */
+    dispatchScreen(runId: string, slot: string, options?: {
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+    }): Promise<BranchRunEnvelope>;
+    getRun(runId: string, signal?: AbortSignal): Promise<BranchRunEnvelope>;
+    /** Candidate images are owner-authenticated rather than signed. */
+    downloadScreen(runId: string, slot: string, signal?: AbortSignal): Promise<{
+        bytes: Uint8Array;
+        sha256: string;
+    }>;
+}
+//# sourceMappingURL=branch-client.d.ts.map

package/dist/branch-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-client.d.ts","sourceRoot":"","sources":["../src/branch-client.ts"],"names":[],"mappings":"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"}

package/dist/branch-client.js

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+import { appendClientAuthGuidance } from './client-auth-guidance.js';
+import { normalizeConversionOrigin } from './config.js';
+/**
+ * The create/build API as the CLI needs it: a port of the web app's
+ * `apps/web/src/pages/create/createApi.ts` with the browser identity, Turnstile,
+ * and object-URL machinery removed and Bearer key auth in their place.
+ *
+ * The wire envelope is deliberately NOT `BranchPlan` verbatim. `plan.pages[]`
+ * carries the ordering (`slots`), while every per-screen fact —
+ * `viewportOrdinal`, `header`, `footer`, `pageEndsHere`, `dependsOnSlot`,
+ * `content` — lives on `candidates[]`. Those are two different places and both
+ * are needed to reconstruct the page grouping.
+ */
+export const BRANCH_MAX_CONCEPT_CHARACTERS = 600;
+export class BranchApiError extends Error {
+    status;
+    code;
+    retryAfterSeconds;
+    /** Branch gating only: the slot that must succeed before this one runs. */
+    dependsOn;
+    constructor(message, status, code, options = {}) {
+        super(message);
+        this.name = 'BranchApiError';
+        this.status = status;
+        this.code = code;
+        if (options.retryAfterSeconds !== undefined)
+            this.retryAfterSeconds = options.retryAfterSeconds;
+        if (options.dependsOn !== undefined)
+            this.dependsOn = options.dependsOn;
+    }
+}
+/**
+ * TWO error shapes live behind one status. The dependency gates answer 409 with
+ * a NESTED object — `{"error":{"code","dependsOn","message"}}` — while every
+ * other refusal, `candidate_in_flight` included, uses the FLAT helper —
+ * `{"error":"candidate_in_flight","message":…}` — where `error.code` is
+ * undefined. Reading only one of the two silently mis-routes the other, which
+ * is exactly the trap the branch skill used to invite.
+ */
+export const parseBranchFailure = (status, body, retryAfterHeader) => {
+    const parsed = (body && typeof body === 'object' && !Array.isArray(body)
+        ? body
+        : null);
+    const nested = parsed?.error && typeof parsed.error === 'object' && !Array.isArray(parsed.error)
+        ? parsed.error
+        : null;
+    const flat = typeof parsed?.error === 'string' ? parsed.error : undefined;
+    const code = nested?.code ?? flat ?? 'error';
+    const message = nested?.message
+        ?? parsed?.message
+        ?? (status === 429
+            ? 'The daily generation allowance is used up.'
+            : `The create service failed (${status}).`);
+    const retryAfter = Number(retryAfterHeader ?? '');
+    return new BranchApiError(appendClientAuthGuidance(message, status), status, code, {
+        ...(Number.isFinite(retryAfter) && retryAfter > 0
+            ? { retryAfterSeconds: Math.round(retryAfter) }
+            : {}),
+        ...(typeof nested?.dependsOn === 'string' ? { dependsOn: nested.dependsOn } : {}),
+    });
+};
+const parseEnvelope = (payload) => {
+    const record = payload;
+    if (!record || typeof record.id !== 'string' || !Array.isArray(record.candidates)) {
+        throw new BranchApiError('The create service returned an unexpected response.', 0, 'error');
+    }
+    return record;
+};
+export class TwelveUiBranchClient {
+    origin;
+    #apiKey;
+    #fetch;
+    constructor(options) {
+        this.origin = normalizeConversionOrigin(options.origin);
+        this.#apiKey = options.apiKey.trim();
+        this.#fetch = options.fetch ?? fetch;
+        if (!this.#apiKey)
+            throw new Error('A 12ui API key is required');
+    }
+    /**
+     * Claim the build run. The planner runs inline — 10 to 20 seconds — and buys
+     * no image. The key derives the run id, so replaying it returns the same run.
+     */
+    async startBuildRun(input, idempotencyKey, signal) {
+        const body = {
+            source: 'build',
+            concept: input.concept,
+            ...(input.aspect ? { aspect: input.aspect } : {}),
+            ...(input.winner ? { winner: input.winner } : {}),
+            ...(input.referenceImage ? { referenceImage: input.referenceImage } : {}),
+        };
+        return parseEnvelope(await this.#json('/api/v1/create', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'Idempotency-Key': idempotencyKey },
+            body: JSON.stringify(body),
+            ...(signal ? { signal } : {}),
+        }, [200, 201]));
+    }
+    /**
+     * Claim a candidate run. Buys no image; the key derives the run, so replaying
+     * it returns the same run and its stored images rather than a second set.
+     */
+    async startCreateRun(input, idempotencyKey, signal) {
+        const body = {
+            concept: input.concept,
+            ...(input.aspect ? { aspect: input.aspect } : {}),
+            ...(input.mode ? { mode: input.mode } : {}),
+            candidates: input.candidates.map((candidate) => ({
+                slot: candidate.slot,
+                ...(candidate.direction ? { direction: candidate.direction } : {}),
+                ...(candidate.referenceId ? { referenceId: candidate.referenceId } : {}),
+                ...(candidate.useReferenceImage ? { useReferenceImage: true } : {}),
+            })),
+            ...(input.referenceImage ? { referenceImage: input.referenceImage } : {}),
+        };
+        return parseEnvelope(await this.#json('/api/v1/create', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'Idempotency-Key': idempotencyKey },
+            body: JSON.stringify(body),
+            ...(signal ? { signal } : {}),
+        }, [200, 201]));
+    }
+    /**
+     * Dispatch one screen. Unkeyed by default and by design: an unkeyed repeat
+     * replays the settled screen for free, while a NEW key on a settled slot buys
+     * another image. Only an explicit redraw passes one.
+     */
+    async dispatchScreen(runId, slot, options = {}) {
+        return parseEnvelope(await this.#json(`/api/v1/create/${encodeURIComponent(runId)}/candidates/${encodeURIComponent(slot)}`, {
+            method: 'POST',
+            headers: {
+                'content-length': '0',
+                ...(options.idempotencyKey ? { 'Idempotency-Key': options.idempotencyKey } : {}),
+            },
+            ...(options.signal ? { signal: options.signal } : {}),
+        }));
+    }
+    async getRun(runId, signal) {
+        return parseEnvelope(await this.#json(`/api/v1/create/${encodeURIComponent(runId)}`, { method: 'GET', ...(signal ? { signal } : {}) }));
+    }
+    /** Candidate images are owner-authenticated rather than signed. */
+    async downloadScreen(runId, slot, signal) {
+        const response = await this.#fetch(`${this.origin}/api/v1/create/${encodeURIComponent(runId)}/candidates/${encodeURIComponent(slot)}/image`, {
+            method: 'GET',
+            headers: this.#headers({ accept: 'image/png' }),
+            ...(signal ? { signal } : {}),
+        });
+        if (!response.ok) {
+            throw parseBranchFailure(response.status, await response.json().catch(() => null), response.headers.get('retry-after'));
+        }
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        return { bytes, sha256: createHash('sha256').update(bytes).digest('hex') };
+    }
+    async #json(path, init, okStatuses = [200]) {
+        let response;
+        try {
+            response = await this.#fetch(`${this.origin}${path}`, {
+                ...init,
+                headers: this.#headers({ accept: 'application/json', ...init.headers }),
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'AbortError')
+                throw error;
+            throw new BranchApiError('Could not reach the create service.', 0, 'network');
+        }
+        if (!response.ok && !okStatuses.includes(response.status)) {
+            throw parseBranchFailure(response.status, await response.json().catch(() => null), response.headers.get('retry-after'));
+        }
+        return await response.json().catch(() => null);
+    }
+    #headers(values) {
+        const headers = new Headers(values);
+        headers.set('authorization', `Bearer ${this.#apiKey}`);
+        return headers;
+    }
+}
+//# sourceMappingURL=branch-client.js.map

package/dist/branch-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-client.js","sourceRoot":"","sources":["../src/branch-client.ts"],"names":[],"mappings":"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"}

package/dist/branch-completion.d.ts

@@ -0,0 +1,37 @@
+import type { BranchDispatchStop } from './branch-dispatch-loop.js';
+import type { BranchDownloadedScreen } from './branch-downloads.js';
+import type { BranchExecutionInputs } from './branch-execution-types.js';
+import type { BranchNormalizedPlan } from './branch-plan.js';
+import { type BranchCompletion, type BranchCompletionPage } from './branch-run-record.js';
+/**
+ * The completion sentinel and the exit disposition: the two things that decide
+ * what a caller believes happened. Every screen is accounted for as succeeded,
+ * failed, or blocked-by-a-failure, so a run always reaches a terminal story
+ * rather than leaving a screen that will never move looking merely pending.
+ */
+export declare const buildCompletion: (args: {
+    plan: BranchNormalizedPlan;
+    inputs: BranchExecutionInputs;
+    runKey: string;
+    origin: string;
+    outDir: string;
+    attemptFile: string;
+    startedAt: string;
+    screens: ReadonlyMap<string, BranchDownloadedScreen>;
+    winner?: BranchDownloadedScreen;
+    conversions: ReadonlyMap<string, BranchCompletionPage["conversion"]>;
+    stopped: BranchDispatchStop | null;
+}) => BranchCompletion;
+/**
+ * Park or fail, per CLAUDE.md §5. A run that lost some screens still delivered
+ * the pages that are whole, so it exits 0 with the gaps named. A run that lost
+ * everything, was cut off by quota or funds, or converted nothing it attempted
+ * has no artifact to hand over and says so.
+ */
+export declare const terminalFailure: (args: {
+    completion: BranchCompletion;
+    stopped: BranchDispatchStop | null;
+    completionFile: string;
+    convert: boolean;
+}) => Error | null;
+//# sourceMappingURL=branch-completion.d.ts.map

package/dist/branch-completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-completion.d.ts","sourceRoot":"","sources":["../src/branch-completion.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7D,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EAE1B,MAAM,wBAAwB,CAAC;AAEhC;;;;;GAKG;AAEH,eAAO,MAAM,eAAe,GAAI,MAAM;IACpC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,MAAM,EAAE,qBAAqB,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACrD,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,YAAY,CAAC,CAAC,CAAC;IACrE,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACpC,KAAG,gBA6GH,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM;IACpC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;CAClB,KAAG,KAAK,GAAG,IAwBX,CAAC"}