@12ui/design 0.2.13 → 0.2.14

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,43 @@
+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;
+};
+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>;
+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;CAChB,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,CAajC,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,94 @@
+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),
+        sha256: createHash('sha256').update(args.bytes).digest('hex'),
+        bytes: args.bytes.byteLength,
+        ...dimensions,
+    };
+};
+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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"}

package/dist/branch-execution-types.d.ts

@@ -0,0 +1,54 @@
+import type { BranchAspect } from './branch-client.js';
+import type { BranchScope } from './branch-identity.js';
+import type { BranchDispatchEvent } from './branch-dispatch-loop.js';
+import type { BranchConversionSettings } from './branch-page-conversion.js';
+import type { BranchProgressPhase, BranchProgressScreen } from './branch-progress.js';
+import type { BranchCompletion } from './branch-run-record.js';
+import type { PackageProgressEvent } from './package-submission.js';
+/**
+ * The inputs and events of one branch run, in their own module so the phases
+ * that consume them — download, completion, the CLI — can import them without
+ * importing the orchestrator that drives them.
+ */
+export type BranchWinnerInput = {
+    kind: 'run';
+    runId: string;
+    slot: string;
+} | {
+    kind: 'image';
+    imagePath: string;
+    bytes: Uint8Array;
+    mediaType: 'image/png' | 'image/jpeg' | 'image/webp';
+    sha256: string;
+};
+export type BranchExecutionInputs = {
+    outDir: string;
+    scope: BranchScope;
+    concept: string;
+    winner: BranchWinnerInput;
+    aspect?: BranchAspect;
+    maxScreens?: number;
+    convert?: BranchConversionSettings;
+    idempotencyKey?: string;
+};
+export type BranchExecutionEvent = BranchDispatchEvent | {
+    kind: 'phase';
+    phase: string;
+    detail?: string;
+} | {
+    /** Published every loop turn so an observer always sees motion, not absence. */
+    kind: 'progress';
+    phase: BranchProgressPhase;
+    screens: BranchProgressScreen[];
+} | {
+    kind: 'package';
+    pageId: string;
+    progress: PackageProgressEvent;
+};
+export type BranchExecutionResult = {
+    completion: BranchCompletion;
+    completionPath: string;
+    /** Non-null when the run must exit non-zero. A parked partial run does not. */
+    failure: Error | null;
+};
+//# sourceMappingURL=branch-execution-types.d.ts.map

package/dist/branch-execution-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-execution-types.d.ts","sourceRoot":"","sources":["../src/branch-execution-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACtF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAEpE;;;;GAIG;AAEH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5C;IACA,IAAI,EAAE,OAAO,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,WAAW,GAAG,YAAY,GAAG,YAAY,CAAC;IACrD,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEJ,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAC5B,mBAAmB,GACnB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACjD;IACA,gFAAgF;IAChF,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,OAAO,EAAE,oBAAoB,EAAE,CAAC;CACjC,GACC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAExE,MAAM,MAAM,qBAAqB,GAAG;IAClC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,cAAc,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,OAAO,EAAE,KAAK,GAAG,IAAI,CAAC;CACvB,CAAC"}

package/dist/branch-execution-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=branch-execution-types.js.map

package/dist/branch-execution-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-execution-types.js","sourceRoot":"","sources":["../src/branch-execution-types.ts"],"names":[],"mappings":""}

package/dist/branch-execution.d.ts

@@ -0,0 +1,18 @@
+import { type TwelveUiBranchClient } from './branch-client.js';
+import { type BranchDispatchTuning } from './branch-dispatch-loop.js';
+import type { TwelveUiConversionPackageClient } from './package-client.js';
+import type { BranchExecutionEvent, BranchExecutionInputs, BranchExecutionResult } from './branch-execution-types.js';
+export type { BranchExecutionEvent, BranchExecutionInputs, BranchExecutionResult, BranchWinnerInput, } from './branch-execution-types.js';
+export declare const deriveBranchRunKey: (inputs: BranchExecutionInputs) => string;
+export declare const executeBranchRun: (args: {
+    branchClient: TwelveUiBranchClient;
+    packageClient?: TwelveUiConversionPackageClient;
+    inputs: BranchExecutionInputs;
+    origin: string;
+    resume?: boolean;
+    onEvent?: (event: BranchExecutionEvent) => void;
+    dispatch?: BranchDispatchTuning;
+    packageTimeoutMs?: number;
+    signal?: AbortSignal;
+}) => Promise<BranchExecutionResult>;
+//# sourceMappingURL=branch-execution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"branch-execution.d.ts","sourceRoot":"","sources":["../src/branch-execution.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AAc5B,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,2BAA2B,CAAC;AAgBnC,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,6BAA6B,CAAC;AAErC,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,6BAA6B,CAAC;AAWrC,eAAO,MAAM,kBAAkB,GAAI,QAAQ,qBAAqB,KAAG,MAQlE,CAAC;AAkCF,eAAO,MAAM,gBAAgB,GAAU,MAAM;IAC3C,YAAY,EAAE,oBAAoB,CAAC;IACnC,aAAa,CAAC,EAAE,+BAA+B,CAAC;IAChD,MAAM,EAAE,qBAAqB,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;IAChD,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAG,OAAO,CAAC,qBAAqB,CAoOhC,CAAC"}