@12ui/design 0.2.13 → 0.2.15

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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"}

package/dist/branch-dispatch-loop.d.ts

@@ -0,0 +1,84 @@
+import { type TwelveUiBranchClient } from './branch-client.js';
+import { type BranchNormalizedPlan } from './branch-plan.js';
+/**
+ * The dispatch driver: the scheduler decides WHICH screens may run, this decides
+ * WHEN to ask again. It is `apps/web/src/pages/branch/useBranchRun.ts` with the
+ * React state machine removed and its three intervals kept as the same
+ * constants, because they are the cadence the server was tuned against.
+ *
+ * Spending rules, unchanged from the board:
+ *   - automatic dispatch sends NO idempotency key, so any replay is free;
+ *   - a settled slot is never re-offered; a redraw is an explicit action;
+ *   - a gate refusal is not an error — the slot is held and offered again.
+ */
+export declare const BRANCH_POLL_INTERVAL_MS = 4000;
+export declare const BRANCH_PUMP_INTERVAL_MS = 2000;
+export declare const BRANCH_GATE_BACKOFF_MS = 4000;
+/** A screen's own server budget is 150 s; a whole run is bounded far above it. */
+export declare const BRANCH_RUN_TIMEOUT_MS: number;
+export type BranchDispatchEvent = {
+    kind: 'dispatched';
+    slot: string;
+} | {
+    kind: 'succeeded';
+    slot: string;
+} | {
+    kind: 'failed';
+    slot: string;
+    code: string;
+    message: string;
+} | {
+    kind: 'held';
+    slot: string;
+    code: string;
+    waitingOn?: string;
+} | {
+    kind: 'in-flight';
+    slot: string;
+} | {
+    kind: 'blocked';
+    slot: string;
+    waitingOn: string;
+    reason: string;
+} | {
+    kind: 'stopped';
+    code: string;
+    message: string;
+};
+export type BranchDispatchStop = {
+    code: string;
+    message: string;
+};
+export type BranchDispatchResult = {
+    plan: BranchNormalizedPlan;
+    stopped: BranchDispatchStop | null;
+};
+/** Everything a status surface needs to narrate motion, taken at one instant. */
+export type BranchDispatchSnapshot = {
+    plan: BranchNormalizedPlan;
+    dispatchedAt: Readonly<Record<string, string>>;
+};
+/** Cadence and clock overrides. Tests drive these; the CLI never sets them. */
+export type BranchDispatchTuning = {
+    now?: () => number;
+    sleep?: (milliseconds: number) => Promise<void>;
+    pollIntervalMs?: number;
+    pumpIntervalMs?: number;
+    gateBackoffMs?: number;
+    timeoutMs?: number;
+};
+export declare const runBranchDispatch: (args: {
+    client: TwelveUiBranchClient;
+    plan: BranchNormalizedPlan;
+    onEvent?: (event: BranchDispatchEvent) => void;
+    /** Called on every loop turn, changed or not, so a poller always sees motion. */
+    onSnapshot?: (snapshot: BranchDispatchSnapshot) => void;
+    now?: () => number;
+    sleep?: (milliseconds: number) => Promise<void>;
+    pollIntervalMs?: number;
+    pumpIntervalMs?: number;
+    gateBackoffMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}) => Promise<BranchDispatchResult>;
+//# sourceMappingURL=branch-dispatch-loop.d.ts.map

package/dist/branch-dispatch-loop.d.ts.map

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

package/dist/branch-dispatch-loop.js

@@ -0,0 +1,206 @@
+import { BranchApiError } from './branch-client.js';
+import { branchBlockedSlots, branchDispatchableSlots, branchRunSettled, } from './branch-schedule.js';
+import { applyBranchEnvelope } from './branch-plan.js';
+/**
+ * The dispatch driver: the scheduler decides WHICH screens may run, this decides
+ * WHEN to ask again. It is `apps/web/src/pages/branch/useBranchRun.ts` with the
+ * React state machine removed and its three intervals kept as the same
+ * constants, because they are the cadence the server was tuned against.
+ *
+ * Spending rules, unchanged from the board:
+ *   - automatic dispatch sends NO idempotency key, so any replay is free;
+ *   - a settled slot is never re-offered; a redraw is an explicit action;
+ *   - a gate refusal is not an error — the slot is held and offered again.
+ */
+export const BRANCH_POLL_INTERVAL_MS = 4_000;
+export const BRANCH_PUMP_INTERVAL_MS = 2_000;
+export const BRANCH_GATE_BACKOFF_MS = 4_000;
+/** A screen's own server budget is 150 s; a whole run is bounded far above it. */
+export const BRANCH_RUN_TIMEOUT_MS = 60 * 60_000;
+/** Refusals that end the run rather than holding one screen back. */
+const TERMINAL_CODES = new Set([
+    'quota_exhausted',
+    'insufficient_funds',
+    'expired',
+    'rate_limited',
+    'not_found',
+    'unauthorized',
+    'forbidden',
+]);
+const scheduleView = (plan) => (plan.screens.map((screen) => ({
+    slot: screen.slot,
+    status: screen.status,
+    footer: screen.footer,
+    dependsOnSlot: screen.dependsOnSlot,
+})));
+const defaultSleep = async (milliseconds) => (new Promise((resolve) => { setTimeout(resolve, milliseconds); }));
+export const runBranchDispatch = async (args) => {
+    const now = args.now ?? Date.now;
+    const sleep = args.sleep ?? defaultSleep;
+    const pollIntervalMs = args.pollIntervalMs ?? BRANCH_POLL_INTERVAL_MS;
+    const pumpIntervalMs = args.pumpIntervalMs ?? BRANCH_PUMP_INTERVAL_MS;
+    const gateBackoffMs = args.gateBackoffMs ?? BRANCH_GATE_BACKOFF_MS;
+    const emit = args.onEvent ?? (() => undefined);
+    const deadline = now() + (args.timeoutMs ?? BRANCH_RUN_TIMEOUT_MS);
+    let plan = args.plan;
+    let stopped = null;
+    const inFlight = new Set();
+    const heldUntil = {};
+    const active = new Set();
+    const announcedBlocked = new Set();
+    const dispatchedAt = {};
+    const snapshot = () => args.onSnapshot?.({ plan, dispatchedAt });
+    const markDispatched = (slot) => {
+        plan = {
+            ...plan,
+            screens: plan.screens.map((screen) => (screen.slot === slot && screen.status === 'pending'
+                ? { ...screen, status: 'dispatched' }
+                : screen)),
+        };
+    };
+    const markPending = (slot) => {
+        plan = {
+            ...plan,
+            screens: plan.screens.map((screen) => (screen.slot === slot ? { ...screen, status: 'pending' } : screen)),
+        };
+    };
+    const markFailed = (slot, code, message) => {
+        plan = {
+            ...plan,
+            screens: plan.screens.map((screen) => (screen.slot === slot
+                ? { ...screen, status: 'failed', error: { code, message } }
+                : screen)),
+        };
+    };
+    const announceBlocked = () => {
+        for (const blocked of branchBlockedSlots(scheduleView(plan))) {
+            if (announcedBlocked.has(blocked.slot))
+                continue;
+            announcedBlocked.add(blocked.slot);
+            emit({
+                kind: 'blocked',
+                slot: blocked.slot,
+                waitingOn: blocked.waitingOn,
+                reason: blocked.reason,
+            });
+        }
+    };
+    const dispatch = async (slot) => {
+        inFlight.add(slot);
+        markDispatched(slot);
+        dispatchedAt[slot] = new Date(now()).toISOString();
+        emit({ kind: 'dispatched', slot });
+        snapshot();
+        try {
+            // No idempotency key: an unkeyed repeat replays the settled screen free,
+            // while a new key would buy another image.
+            const envelope = await args.client.dispatchScreen(plan.runId, slot, {
+                ...(args.signal ? { signal: args.signal } : {}),
+            });
+            plan = applyBranchEnvelope(plan, envelope);
+            const resolved = plan.screens.find((screen) => screen.slot === slot);
+            if (resolved?.status === 'succeeded')
+                emit({ kind: 'succeeded', slot });
+            if (resolved?.status === 'failed') {
+                emit({
+                    kind: 'failed',
+                    slot,
+                    code: resolved.error?.code ?? 'failed',
+                    message: resolved.error?.message ?? 'This screen could not be generated.',
+                });
+            }
+        }
+        catch (error) {
+            const code = error instanceof BranchApiError ? error.code : 'error';
+            const message = error instanceof Error ? error.message : String(error);
+            if (code === 'dependency_pending' || code === 'footer_reference_pending') {
+                // The worker knows more than this client did. Hold the slot and let the
+                // scheduler offer it again once its reference lands.
+                heldUntil[slot] = now() + gateBackoffMs;
+                markPending(slot);
+                emit({
+                    kind: 'held',
+                    slot,
+                    code,
+                    ...(error instanceof BranchApiError && error.dependsOn
+                        ? { waitingOn: error.dependsOn }
+                        : {}),
+                });
+            }
+            else if (code === 'candidate_in_flight') {
+                // Another caller owns the paid call. Leave the slot dispatched; the run
+                // poll reports its result. Note the FLAT error shape here.
+                emit({ kind: 'in-flight', slot });
+            }
+            else if (TERMINAL_CODES.has(code) || (error instanceof BranchApiError && error.status >= 500)) {
+                markPending(slot);
+                stopped ??= { code, message };
+            }
+            else {
+                markFailed(slot, code, message);
+                emit({ kind: 'failed', slot, code, message });
+            }
+        }
+        finally {
+            inFlight.delete(slot);
+            snapshot();
+        }
+    };
+    const poll = async () => {
+        try {
+            plan = applyBranchEnvelope(plan, await args.client.getRun(plan.runId, args.signal));
+        }
+        catch (error) {
+            const code = error instanceof BranchApiError ? error.code : 'error';
+            if (TERMINAL_CODES.has(code))
+                stopped ??= { code, message: error.message };
+        }
+    };
+    const track = (promise) => {
+        const tracked = promise.finally(() => { active.delete(tracked); });
+        active.add(tracked);
+    };
+    while (plan.screens.length > 0 && !branchRunSettled(scheduleView(plan))) {
+        if (stopped)
+            break;
+        if (now() >= deadline) {
+            stopped = {
+                code: 'run_timeout',
+                message: `Branch run ${plan.runId} did not settle within the run budget.`,
+            };
+            break;
+        }
+        announceBlocked();
+        for (const slot of branchDispatchableSlots(scheduleView(plan), {
+            inFlight,
+            heldUntil,
+            now: now(),
+        })) {
+            track(dispatch(slot));
+        }
+        // Every turn publishes a snapshot, changed or not: a poller that sees only
+        // "nothing yet" is the one that gives up and improvises.
+        snapshot();
+        if (active.size > 0) {
+            await Promise.race([...active, sleep(pumpIntervalMs)]);
+            continue;
+        }
+        // Nothing of ours is running. Either a sibling caller owns a slot, or every
+        // remaining screen is inside its gate backoff; both resolve by waiting and
+        // re-reading rather than by dispatching again.
+        await poll();
+        if (stopped || branchRunSettled(scheduleView(plan)))
+            break;
+        const nextOffer = Math.min(...Object.values(heldUntil).filter((until) => until > now()), now() + pollIntervalMs);
+        await sleep(Math.max(pumpIntervalMs, Math.min(pollIntervalMs, nextOffer - now())));
+    }
+    // Whatever ended the loop, in-flight work still owns paid calls; let it land
+    // so its result reaches the sentinel instead of being lost.
+    await Promise.allSettled([...active]);
+    announceBlocked();
+    snapshot();
+    if (stopped)
+        emit({ kind: 'stopped', ...stopped });
+    return { plan, stopped };
+};
+//# sourceMappingURL=branch-dispatch-loop.js.map

package/dist/branch-dispatch-loop.js.map

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

package/dist/branch-downloads.d.ts

@@ -0,0 +1,53 @@
+import type { TwelveUiBranchClient } from './branch-client.js';
+/**
+ * Screens are written into a hidden staging directory and moved into
+ * `screens/` in one pass once the run is terminal, exactly as
+ * `image generate-batch` materializes its candidates. A caller listing
+ * `screens/` therefore never sees a half-written run and mistake it for
+ * failure; the directory goes from empty to complete.
+ *
+ * The staging directory is a child of the destination on purpose: a
+ * same-directory rename is same-filesystem, so materialization is atomic and
+ * can never fail with EXDEV.
+ */
+export declare const BRANCH_STAGING_DIRECTORY_NAME = ".12ui-branch-staging";
+export type BranchDownloadedScreen = {
+    slot: string;
+    path: string;
+    sha256: string;
+    bytes: number;
+    width: number;
+    height: number;
+    /** Where the bytes live until the run materializes them. */
+    stagedPath?: string;
+};
+export declare const branchScreenPath: (screensDirectory: string, slot: string) => string;
+/** Bytes already on disk are already paid for; a resume never re-downloads. */
+export declare const readMaterializedScreen: (screensDirectory: string, slot: string) => Promise<BranchDownloadedScreen | null>;
+export declare const stageBranchScreenBytes: (args: {
+    screensDirectory: string;
+    slot: string;
+    bytes: Uint8Array;
+}) => Promise<BranchDownloadedScreen>;
+/**
+ * A screen is delivered in two phases — staged while the run is still going,
+ * moved into `screens/` in one atomic pass at the end — and a page conversion
+ * that starts as soon as its own screens land reads across that move. Both
+ * names address the same delivered bytes, so a reader tries the staged name and
+ * falls through to the final one when the move has already happened.
+ */
+export declare const readBranchScreenBytes: (screen: BranchDownloadedScreen) => Promise<Uint8Array>;
+export declare const stageBranchScreen: (args: {
+    client: TwelveUiBranchClient;
+    runId: string;
+    slot: string;
+    screensDirectory: string;
+    signal?: AbortSignal;
+}) => Promise<BranchDownloadedScreen>;
+/**
+ * Deliver every staged screen at once. Anything already materialized — a
+ * resumed run's earlier screens — stays where it is rather than being
+ * overwritten with bytes that would have to be proved identical first.
+ */
+export declare const materializeBranchScreens: (screensDirectory: string, slots: readonly string[]) => Promise<void>;
+//# sourceMappingURL=branch-downloads.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"branch-downloads.d.ts","sourceRoot":"","sources":["../src/branch-downloads.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG/D;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,6BAA6B,yBAAyB,CAAC;AAEpE,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,kBAAkB,MAAM,EAAE,MAAM,MAAM,KAAG,MAEzE,CAAC;AAgBF,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,GACjC,kBAAkB,MAAM,EACxB,MAAM,MAAM,KACX,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAiBvC,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAU,MAAM;IACjD,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;CACnB,KAAG,OAAO,CAAC,sBAAsB,CAcjC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,GAChC,QAAQ,sBAAsB,KAC7B,OAAO,CAAC,UAAU,CASpB,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAU,MAAM;IAC5C,MAAM,EAAE,oBAAoB,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAG,OAAO,CAAC,sBAAsB,CAOjC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GACnC,kBAAkB,MAAM,EACxB,OAAO,SAAS,MAAM,EAAE,KACvB,OAAO,CAAC,IAAI,CAgBd,CAAC"}

package/dist/branch-downloads.js

@@ -0,0 +1,114 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { readImageDimensions } from './image-dimensions.js';
+/**
+ * Screens are written into a hidden staging directory and moved into
+ * `screens/` in one pass once the run is terminal, exactly as
+ * `image generate-batch` materializes its candidates. A caller listing
+ * `screens/` therefore never sees a half-written run and mistake it for
+ * failure; the directory goes from empty to complete.
+ *
+ * The staging directory is a child of the destination on purpose: a
+ * same-directory rename is same-filesystem, so materialization is atomic and
+ * can never fail with EXDEV.
+ */
+export const BRANCH_STAGING_DIRECTORY_NAME = '.12ui-branch-staging';
+export const branchScreenPath = (screensDirectory, slot) => (path.join(screensDirectory, `${slot}.png`));
+const stagedScreenPath = (screensDirectory, slot) => (path.join(screensDirectory, BRANCH_STAGING_DIRECTORY_NAME, `${slot}.png.part`));
+const pathExists = async (target) => {
+    try {
+        await readFile(target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+};
+/** Bytes already on disk are already paid for; a resume never re-downloads. */
+export const readMaterializedScreen = async (screensDirectory, slot) => {
+    const file = branchScreenPath(screensDirectory, slot);
+    let bytes;
+    try {
+        bytes = await readFile(file);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    const dimensions = await readImageDimensions(bytes);
+    return {
+        slot,
+        path: file,
+        sha256: createHash('sha256').update(bytes).digest('hex'),
+        bytes: bytes.byteLength,
+        ...dimensions,
+    };
+};
+export const stageBranchScreenBytes = async (args) => {
+    const staged = stagedScreenPath(args.screensDirectory, args.slot);
+    await mkdir(path.dirname(staged), { recursive: true });
+    await rm(staged, { force: true });
+    await writeFile(staged, args.bytes, { flag: 'wx', mode: 0o600 });
+    const dimensions = await readImageDimensions(args.bytes);
+    return {
+        slot: args.slot,
+        path: branchScreenPath(args.screensDirectory, args.slot),
+        stagedPath: staged,
+        sha256: createHash('sha256').update(args.bytes).digest('hex'),
+        bytes: args.bytes.byteLength,
+        ...dimensions,
+    };
+};
+/**
+ * A screen is delivered in two phases — staged while the run is still going,
+ * moved into `screens/` in one atomic pass at the end — and a page conversion
+ * that starts as soon as its own screens land reads across that move. Both
+ * names address the same delivered bytes, so a reader tries the staged name and
+ * falls through to the final one when the move has already happened.
+ */
+export const readBranchScreenBytes = async (screen) => {
+    if (screen.stagedPath) {
+        try {
+            return new Uint8Array(await readFile(screen.stagedPath));
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return new Uint8Array(await readFile(screen.path));
+};
+export const stageBranchScreen = async (args) => {
+    const downloaded = await args.client.downloadScreen(args.runId, args.slot, args.signal);
+    return stageBranchScreenBytes({
+        screensDirectory: args.screensDirectory,
+        slot: args.slot,
+        bytes: downloaded.bytes,
+    });
+};
+/**
+ * Deliver every staged screen at once. Anything already materialized — a
+ * resumed run's earlier screens — stays where it is rather than being
+ * overwritten with bytes that would have to be proved identical first.
+ */
+export const materializeBranchScreens = async (screensDirectory, slots) => {
+    await Promise.all(slots.map(async (slot) => {
+        const staged = stagedScreenPath(screensDirectory, slot);
+        if (!(await pathExists(staged)))
+            return;
+        const destination = branchScreenPath(screensDirectory, slot);
+        if (await pathExists(destination)) {
+            throw new Error(`Refusing to overwrite an existing screen at ${destination} with staged bytes from`
+                + ` ${staged}; inspect both before continuing.`);
+        }
+        await rename(staged, destination);
+    }));
+    // rmdir refuses a non-empty directory, so this both cleans up and proves
+    // nothing was left undelivered.
+    await rmdir(path.join(screensDirectory, BRANCH_STAGING_DIRECTORY_NAME)).catch(() => undefined);
+};
+//# sourceMappingURL=branch-downloads.js.map

package/dist/branch-downloads.js.map

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