@12ui/design 0.2.12 → 0.2.14

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 \
@@ -99,6 +110,15 @@ PNG output, and one stable idempotency key. Per-candidate and batch evidence
 records provider-start and completion times. It never retries a candidate or
 switches providers after dispatch.
 
+Candidates are written into a hidden staging directory and moved into place only
+once the batch is terminal, so a caller listing the output directory can never
+observe a half-written batch. Completion is published as a
+`generation.complete.json` sentinel beside the candidates, carrying each
+candidate's status, sha256, and byte count. `--resume` recovers an interrupted
+batch: it delivers candidates that were already generated and re-requests only
+those the provider provably never billed, so it can never buy a candidate twice,
+and it refuses a batch that already completed.
+
 The single-candidate `image generate` command remains available. Both commands
 resolve authenticated Codex first, then `OPENAI_API_KEY` from the process or
 exactly `<project-root>/.env`. They refuse a Git-tracked `.env`, never store or
@@ -247,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/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"}

package/dist/branch-completion.js

@@ -0,0 +1,137 @@
+import { BRANCH_WORKFLOW_REVISION, branchConceptDigest } from './branch-identity.js';
+import { branchBlockedSlots } from './branch-schedule.js';
+import { branchPlanPath, } 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 const buildCompletion = (args) => {
+    const blocked = new Map(branchBlockedSlots(args.plan.screens.map((screen) => ({
+        slot: screen.slot,
+        status: screen.status,
+        footer: screen.footer,
+        dependsOnSlot: screen.dependsOnSlot,
+    }))).map((entry) => [entry.slot, entry]));
+    const pageIdByIndex = new Map(args.plan.pages.map((page) => [page.index, page.id]));
+    const screens = args.plan.screens.map((screen) => {
+        const downloaded = args.screens.get(screen.slot);
+        const block = blocked.get(screen.slot);
+        const status = screen.status === 'succeeded' && downloaded
+            ? 'succeeded'
+            : block
+                ? 'blocked'
+                : 'failed';
+        return {
+            slot: screen.slot,
+            pageIndex: screen.pageIndex,
+            pageId: pageIdByIndex.get(screen.pageIndex) ?? `p${screen.pageIndex}`,
+            viewportOrdinal: screen.viewportOrdinal,
+            status,
+            direction: screen.direction,
+            ...(downloaded
+                ? {
+                    path: downloaded.path,
+                    sha256: downloaded.sha256,
+                    bytes: downloaded.bytes,
+                    width: downloaded.width,
+                    height: downloaded.height,
+                }
+                : {}),
+            ...(screen.dependsOnSlot ? { dependsOnSlot: screen.dependsOnSlot } : {}),
+            ...(screen.footer === true ? { footer: true } : {}),
+            ...(block ? { blockedBy: block.waitingOn, blockedReason: block.reason } : {}),
+            ...(screen.error ? { error: screen.error } : {}),
+        };
+    });
+    const succeededCount = screens.filter((screen) => screen.status === 'succeeded').length;
+    const blockedCount = screens.filter((screen) => screen.status === 'blocked').length;
+    const failedCount = screens.length - succeededCount - blockedCount;
+    const pages = args.plan.pages.map((page) => ({
+        index: page.index,
+        id: page.id,
+        kind: page.kind,
+        title: page.title,
+        slots: page.slots,
+        startsFromWinner: page.startsFromWinner,
+        ...(args.conversions.has(page.id) ? { conversion: args.conversions.get(page.id) } : {}),
+    }));
+    const notes = [];
+    if (blockedCount > 0) {
+        notes.push(`${blockedCount} screen(s) can never run: their dependency failed, so the run is terminal`
+            + ' rather than still waiting. Redraw the failed screen to unblock them.');
+    }
+    if (args.stopped)
+        notes.push(`Dispatch stopped early: ${args.stopped.code} — ${args.stopped.message}`);
+    const conversionsAttempted = [...args.conversions.values()];
+    const conversionFailed = conversionsAttempted.some((conversion) => conversion?.status === 'failed');
+    const status = succeededCount === 0 && screens.length > 0
+        ? 'failed'
+        : (failedCount > 0 || blockedCount > 0 || args.stopped || conversionFailed)
+            ? 'partial'
+            : 'succeeded';
+    return {
+        version: 1,
+        status,
+        runId: args.plan.runId,
+        runKey: args.runKey,
+        workflowRevision: BRANCH_WORKFLOW_REVISION,
+        scope: args.inputs.scope,
+        concept: args.inputs.concept,
+        conceptSha256: branchConceptDigest(args.inputs.concept),
+        origin: args.origin,
+        outDir: args.outDir,
+        attemptPath: args.attemptFile,
+        planPath: branchPlanPath(args.outDir),
+        startedAt: args.startedAt,
+        completedAt: new Date().toISOString(),
+        screenCount: screens.length,
+        succeededCount,
+        failedCount,
+        blockedCount,
+        ...(args.winner
+            ? {
+                winner: {
+                    path: args.winner.path,
+                    sha256: args.winner.sha256,
+                    bytes: args.winner.bytes,
+                    width: args.winner.width,
+                    height: args.winner.height,
+                    ...(args.inputs.convert?.sourceConversionId
+                        ? { sourceConversionId: args.inputs.convert.sourceConversionId }
+                        : {}),
+                },
+            }
+            : {}),
+        screens,
+        pages,
+        ...(notes.length > 0 ? { notes } : {}),
+    };
+};
+/**
+ * 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 const terminalFailure = (args) => {
+    if (args.stopped) {
+        return new Error(`Branch run ${args.completion.runId} stopped: ${args.stopped.code} — ${args.stopped.message}`
+            + ` Whatever settled is materialized. Evidence: ${args.completionFile}`);
+    }
+    if (args.completion.screenCount > 0 && args.completion.succeededCount === 0) {
+        return new Error(`Branch run ${args.completion.runId} produced no screen. Evidence: ${args.completionFile}`);
+    }
+    if (args.convert) {
+        const attempted = args.completion.pages
+            .map((page) => page.conversion)
+            .filter((conversion) => conversion && conversion.status !== 'skipped');
+        if (attempted.length > 0 && attempted.every((conversion) => conversion.status === 'failed')) {
+            return new Error(`Branch run ${args.completion.runId} generated its screens but converted no page.`
+                + ` The screens are on disk. Evidence: ${args.completionFile}`);
+        }
+    }
+    return null;
+};
+//# sourceMappingURL=branch-completion.js.map

package/dist/branch-completion.js.map

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