@12ui/design 0.2.13 → 0.2.15

package/dist/branch-run-record.js

@@ -0,0 +1,94 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * The two durable records of a branch run.
+ *
+ * `branch.attempt.json` is written BEFORE any spend, exclusively, so a plain
+ * re-run in the same directory refuses instead of buying a second run; only
+ * `--resume` may proceed. `branch.complete.json` is the sentinel: written once,
+ * atomically, only at a terminal state. Its ABSENCE means the run is still
+ * going — never that it failed. It is deliberately not named
+ * `generation.complete.json`, which is `image generate-batch`'s record and a
+ * different thing entirely.
+ */
+export const BRANCH_ATTEMPT_FILENAME = 'branch.attempt.json';
+export const BRANCH_COMPLETION_FILENAME = 'branch.complete.json';
+export const BRANCH_PLAN_FILENAME = 'branch.plan.json';
+export const BRANCH_SCREENS_DIRECTORY = 'screens';
+export const BRANCH_PAGES_DIRECTORY = 'pages';
+export const branchAttemptPath = (outDir) => (path.join(outDir, BRANCH_ATTEMPT_FILENAME));
+export const branchCompletionPath = (outDir) => (path.join(outDir, BRANCH_COMPLETION_FILENAME));
+export const branchPlanPath = (outDir) => (path.join(outDir, BRANCH_PLAN_FILENAME));
+const writeJsonAtomically = async (file, value) => {
+    await mkdir(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+            encoding: 'utf8',
+            flag: 'wx',
+            mode: 0o600,
+        });
+        await rename(temporary, file);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+};
+export const writeBranchAttempt = async (file, attempt, exclusive = false) => {
+    if (!exclusive) {
+        await writeJsonAtomically(file, attempt);
+        return;
+    }
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify(attempt, null, 2)}\n`, {
+        encoding: 'utf8',
+        flag: 'wx',
+        mode: 0o600,
+    });
+};
+export const readBranchAttempt = async (file) => {
+    let source;
+    try {
+        source = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    try {
+        const value = JSON.parse(source);
+        if (typeof value !== 'object' || value === null)
+            return undefined;
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const writeBranchPlanRecord = async (file, plan) => {
+    await rm(file, { force: true });
+    await writeJsonAtomically(file, { version: 1, ...plan });
+};
+export const writeBranchCompletion = async (file, completion) => {
+    await writeJsonAtomically(file, completion);
+};
+export const readBranchCompletion = async (file) => {
+    let source;
+    try {
+        source = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        return undefined;
+    }
+};
+//# sourceMappingURL=branch-run-record.js.map

package/dist/branch-run-record.js.map

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

package/dist/branch-schedule.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The branch scheduler — the one place that decides which screens may be
+ * dispatched right now. It is a near-verbatim port of the web board's
+ * `apps/web/src/pages/branch/branchSchedule.ts`, which in turn mirrors the
+ * worker's dispatch gate (`workers/api/src/create/branchReferences.ts`). One
+ * policy, three surfaces: the worker stays the authority and answers a nested
+ * 409 when any client disagrees.
+ *
+ * Two rules gate a screen:
+ *   1. DEPENDENCY — the previous viewport of the same page must have SUCCEEDED,
+ *      because it is the screen's continuation reference.
+ *   2. FOOTER SEED — the first footer-bearing slot in plan order draws the
+ *      site's footer with no example; every later footer screen waits for it.
+ *      Once the seed has FAILED they proceed without it rather than deadlock.
+ *
+ * Slots are assigned in plan order (page order then viewport order), so slot
+ * order IS plan order and the seed is simply the first footer-bearing slot.
+ *
+ * The one addition over the web copy is `branchBlockedSlots`, which reports the
+ * screens `branchRunSettled` counts as terminal-but-unreachable. It derives
+ * that from `branchSlotGate` rather than re-deciding it, so there is still only
+ * one gate predicate here.
+ */
+export type BranchScheduleStatus = 'pending' | 'dispatched' | 'succeeded' | 'failed';
+export type BranchScheduleCandidate = {
+    slot: string;
+    status: BranchScheduleStatus;
+    /** null on non-webpage surfaces, where footer semantics do not apply. */
+    footer?: boolean | null;
+    dependsOnSlot?: string | null;
+};
+export type BranchSlotGate = {
+    ready: true;
+} | {
+    ready: false;
+    reason: 'dependency' | 'footer-seed';
+    waitingOn: string;
+    /** The awaited slot failed, so waiting can never resolve on its own. */
+    blocked: boolean;
+};
+/** THE footer seed: first footer-bearing slot in plan (= slot) order. */
+export declare const branchFooterSeedSlot: (candidates: readonly BranchScheduleCandidate[]) => string | null;
+/** Whether one screen's references are all in place, and what it waits on. */
+export declare const branchSlotGate: (slot: string, candidates: readonly BranchScheduleCandidate[]) => BranchSlotGate;
+export type BranchScheduleOptions = {
+    /** Slots this client already has a dispatch in flight for. */
+    inFlight?: ReadonlySet<string>;
+    /** Slot -> epoch ms before which a gate-refused slot is not retried. */
+    heldUntil?: Readonly<Record<string, number>>;
+    now?: number;
+};
+/**
+ * Every slot that may be dispatched now: still pending, not already in flight,
+ * not inside a gate-refusal backoff, and with both gates satisfied. Settled
+ * slots are never rescheduled — a regenerate is always an explicit user action.
+ */
+export declare const branchDispatchableSlots: (candidates: readonly BranchScheduleCandidate[], options?: BranchScheduleOptions) => string[];
+/** True while any screen is still expected to move without user action. */
+export declare const branchRunActive: (candidates: readonly BranchScheduleCandidate[]) => boolean;
+/** True once no screen can progress further without a user action. */
+export declare const branchRunSettled: (candidates: readonly BranchScheduleCandidate[]) => boolean;
+export type BranchBlockedSlot = {
+    slot: string;
+    reason: 'dependency' | 'footer-seed';
+    waitingOn: string;
+};
+/**
+ * The screens a failed dependency put permanently out of reach. These are the
+ * slots `branchRunSettled` treats as terminal without them ever running, so a
+ * caller must be able to name them and their cause rather than waiting on a
+ * status that will never change.
+ */
+export declare const branchBlockedSlots: (candidates: readonly BranchScheduleCandidate[]) => BranchBlockedSlot[];
+//# sourceMappingURL=branch-schedule.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"branch-schedule.d.ts","sourceRoot":"","sources":["../src/branch-schedule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,MAAM,oBAAoB,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;AAErF,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,oBAAoB,CAAC;IAC7B,yEAAyE;IACzE,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,cAAc,GACtB;IAAE,KAAK,EAAE,IAAI,CAAA;CAAE,GACf;IACA,KAAK,EAAE,KAAK,CAAC;IACb,MAAM,EAAE,YAAY,GAAG,aAAa,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAIJ,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,GAC/B,YAAY,SAAS,uBAAuB,EAAE,KAC7C,MAAM,GAAG,IAIX,CAAC;AA6EF,8EAA8E;AAC9E,eAAO,MAAM,cAAc,GACzB,MAAM,MAAM,EACZ,YAAY,SAAS,uBAAuB,EAAE,KAC7C,cAKF,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/B,wEAAwE;IACxE,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAClC,YAAY,SAAS,uBAAuB,EAAE,EAC9C,UAAS,qBAA0B,KAClC,MAAM,EAaR,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,eAAe,GAC1B,YAAY,SAAS,uBAAuB,EAAE,KAC7C,OAA4E,CAAC;AAEhF,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,GAC3B,YAAY,SAAS,uBAAuB,EAAE,KAC7C,OAWF,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,YAAY,GAAG,aAAa,CAAC;IACrC,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,YAAY,SAAS,uBAAuB,EAAE,KAC7C,iBAAiB,EAKyC,CAAC"}

package/dist/branch-schedule.js

@@ -0,0 +1,130 @@
+/**
+ * The branch scheduler — the one place that decides which screens may be
+ * dispatched right now. It is a near-verbatim port of the web board's
+ * `apps/web/src/pages/branch/branchSchedule.ts`, which in turn mirrors the
+ * worker's dispatch gate (`workers/api/src/create/branchReferences.ts`). One
+ * policy, three surfaces: the worker stays the authority and answers a nested
+ * 409 when any client disagrees.
+ *
+ * Two rules gate a screen:
+ *   1. DEPENDENCY — the previous viewport of the same page must have SUCCEEDED,
+ *      because it is the screen's continuation reference.
+ *   2. FOOTER SEED — the first footer-bearing slot in plan order draws the
+ *      site's footer with no example; every later footer screen waits for it.
+ *      Once the seed has FAILED they proceed without it rather than deadlock.
+ *
+ * Slots are assigned in plan order (page order then viewport order), so slot
+ * order IS plan order and the seed is simply the first footer-bearing slot.
+ *
+ * The one addition over the web copy is `branchBlockedSlots`, which reports the
+ * screens `branchRunSettled` counts as terminal-but-unreachable. It derives
+ * that from `branchSlotGate` rather than re-deciding it, so there is still only
+ * one gate predicate here.
+ */
+const READY = { ready: true };
+/** THE footer seed: first footer-bearing slot in plan (= slot) order. */
+export const branchFooterSeedSlot = (candidates) => ([...candidates]
+    .sort((left, right) => left.slot.localeCompare(right.slot))
+    .find((candidate) => candidate.footer === true)?.slot ?? null);
+/**
+ * Unreachability is TRANSITIVE. A screen waiting on a screen that itself can
+ * never run is just as terminal as one waiting on a screen that already failed
+ * — and a footer screen waiting on a seed in that state is the case that
+ * deadlocks a run without either of them ever being marked failed.
+ */
+const neverSettles = (slot, candidates, bySlot, seen) => {
+    if (seen.has(slot))
+        return false;
+    const candidate = bySlot.get(slot);
+    if (!candidate || candidate.status !== 'pending')
+        return false;
+    const gate = gateFor(slot, candidates, bySlot, new Set(seen).add(slot));
+    return !gate.ready && gate.blocked;
+};
+const neverSucceeds = (slot, candidates, bySlot, seen) => {
+    const candidate = bySlot.get(slot);
+    if (!candidate)
+        return false;
+    if (candidate.status === 'failed')
+        return true;
+    return neverSettles(slot, candidates, bySlot, seen);
+};
+const gateFor = (slot, candidates, bySlot, seen) => {
+    const candidate = bySlot.get(slot);
+    if (!candidate)
+        return READY;
+    const dependsOn = candidate.dependsOnSlot ?? null;
+    if (dependsOn) {
+        const dependency = bySlot.get(dependsOn);
+        if (!dependency || dependency.status !== 'succeeded') {
+            return {
+                ready: false,
+                reason: 'dependency',
+                waitingOn: dependsOn,
+                blocked: neverSucceeds(dependsOn, candidates, bySlot, seen),
+            };
+        }
+    }
+    if (candidate.footer === true) {
+        const seedSlot = branchFooterSeedSlot(candidates);
+        if (seedSlot && seedSlot !== slot) {
+            const seed = bySlot.get(seedSlot);
+            // A failed seed releases the wave: later footers draw without an example.
+            // A seed that can never settle at all releases nothing, ever.
+            if (seed && seed.status !== 'succeeded' && seed.status !== 'failed') {
+                return {
+                    ready: false,
+                    reason: 'footer-seed',
+                    waitingOn: seedSlot,
+                    blocked: neverSettles(seedSlot, candidates, bySlot, seen),
+                };
+            }
+        }
+    }
+    return READY;
+};
+/** Whether one screen's references are all in place, and what it waits on. */
+export const branchSlotGate = (slot, candidates) => gateFor(slot, candidates, new Map(candidates.map((candidate) => [candidate.slot, candidate])), new Set());
+/**
+ * Every slot that may be dispatched now: still pending, not already in flight,
+ * not inside a gate-refusal backoff, and with both gates satisfied. Settled
+ * slots are never rescheduled — a regenerate is always an explicit user action.
+ */
+export const branchDispatchableSlots = (candidates, options = {}) => {
+    const inFlight = options.inFlight ?? new Set();
+    const heldUntil = options.heldUntil ?? {};
+    const now = options.now ?? Date.now();
+    return candidates
+        .filter((candidate) => (candidate.status === 'pending'
+        && !inFlight.has(candidate.slot)
+        && !((heldUntil[candidate.slot] ?? 0) > now)
+        && branchSlotGate(candidate.slot, candidates).ready))
+        .map((candidate) => candidate.slot)
+        .sort((left, right) => left.localeCompare(right));
+};
+/** True while any screen is still expected to move without user action. */
+export const branchRunActive = (candidates) => candidates.some((candidate) => candidate.status === 'dispatched');
+/** True once no screen can progress further without a user action. */
+export const branchRunSettled = (candidates) => (candidates.length > 0
+    && candidates.every((candidate) => (candidate.status === 'succeeded'
+        || candidate.status === 'failed'
+        // A pending screen whose dependency failed will never run itself.
+        || (candidate.status === 'pending' && (() => {
+            const gate = branchSlotGate(candidate.slot, candidates);
+            return !gate.ready && gate.blocked;
+        })()))));
+/**
+ * The screens a failed dependency put permanently out of reach. These are the
+ * slots `branchRunSettled` treats as terminal without them ever running, so a
+ * caller must be able to name them and their cause rather than waiting on a
+ * status that will never change.
+ */
+export const branchBlockedSlots = (candidates) => candidates.flatMap((candidate) => {
+    if (candidate.status !== 'pending')
+        return [];
+    const gate = branchSlotGate(candidate.slot, candidates);
+    if (gate.ready || !gate.blocked)
+        return [];
+    return [{ slot: candidate.slot, reason: gate.reason, waitingOn: gate.waitingOn }];
+}).sort((left, right) => left.slot.localeCompare(right.slot));
+//# sourceMappingURL=branch-schedule.js.map

package/dist/branch-schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-schedule.js","sourceRoot":"","sources":["../src/branch-schedule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAsBH,MAAM,KAAK,GAAmB,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAE9C,yEAAyE;AACzE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,UAA8C,EAC/B,EAAE,CAAC,CAClB,CAAC,GAAG,UAAU,CAAC;KACZ,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;KAC1D,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,KAAK,IAAI,CAAC,EAAE,IAAI,IAAI,IAAI,CAChE,CAAC;AAIF;;;;;GAKG;AACH,MAAM,YAAY,GAAG,CACnB,IAAY,EACZ,UAA8C,EAC9C,MAAiB,EACjB,IAAyB,EAChB,EAAE;IACX,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACjC,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,SAAS,IAAI,SAAS,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC/D,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACxE,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC;AACrC,CAAC,CAAC;AAEF,MAAM,aAAa,GAAG,CACpB,IAAY,EACZ,UAA8C,EAC9C,MAAiB,EACjB,IAAyB,EAChB,EAAE;IACX,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7B,IAAI,SAAS,CAAC,MAAM,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC/C,OAAO,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;AACtD,CAAC,CAAC;AAEF,MAAM,OAAO,GAAG,CACd,IAAY,EACZ,UAA8C,EAC9C,MAAiB,EACjB,IAAyB,EACT,EAAE;IAClB,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAE7B,MAAM,SAAS,GAAG,SAAS,CAAC,aAAa,IAAI,IAAI,CAAC;IAClD,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACzC,IAAI,CAAC,UAAU,IAAI,UAAU,CAAC,MAAM,KAAK,WAAW,EAAE,CAAC;YACrD,OAAO;gBACL,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,YAAY;gBACpB,SAAS,EAAE,SAAS;gBACpB,OAAO,EAAE,aAAa,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC;aAC5D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,IAAI,SAAS,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QAC9B,MAAM,QAAQ,GAAG,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAClD,IAAI,QAAQ,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAClC,0EAA0E;YAC1E,8DAA8D;YAC9D,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACpE,OAAO;oBACL,KAAK,EAAE,KAAK;oBACZ,MAAM,EAAE,aAAa;oBACrB,SAAS,EAAE,QAAQ;oBACnB,OAAO,EAAE,YAAY,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC;iBAC1D,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF,8EAA8E;AAC9E,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,IAAY,EACZ,UAA8C,EAC9B,EAAE,CAAC,OAAO,CAC1B,IAAI,EACJ,UAAU,EACV,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,EACnE,IAAI,GAAG,EAAU,CAClB,CAAC;AAUF;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,UAA8C,EAC9C,UAAiC,EAAE,EACzB,EAAE;IACZ,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,IAAI,GAAG,EAAU,CAAC;IACvD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC;IAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;IACtC,OAAO,UAAU;SACd,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CACrB,SAAS,CAAC,MAAM,KAAK,SAAS;WAC3B,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC;WAC7B,CAAC,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC;WACzC,cAAc,CAAC,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,KAAK,CACpD,CAAC;SACD,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC;SAClC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;AACtD,CAAC,CAAC;AAEF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,UAA8C,EACrC,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,KAAK,YAAY,CAAC,CAAC;AAEhF,sEAAsE;AACtE,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAC9B,UAA8C,EACrC,EAAE,CAAC,CACZ,UAAU,CAAC,MAAM,GAAG,CAAC;OAClB,UAAU,CAAC,KAAK,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CACjC,SAAS,CAAC,MAAM,KAAK,WAAW;WAC7B,SAAS,CAAC,MAAM,KAAK,QAAQ;QAChC,kEAAkE;WAC/D,CAAC,SAAS,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,GAAG,EAAE;YAC1C,MAAM,IAAI,GAAG,cAAc,CAAC,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YACxD,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC;QACrC,CAAC,CAAC,EAAE,CAAC,CACN,CAAC,CACH,CAAC;AAQF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAChC,UAA8C,EACzB,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE;IACzD,IAAI,SAAS,CAAC,MAAM,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAC9C,MAAM,IAAI,GAAG,cAAc,CAAC,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACxD,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAC3C,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;AACpF,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC"}

package/dist/branch-status.d.ts

@@ -0,0 +1,11 @@
+import type { BranchRunEnvelope } from './branch-client.js';
+import { type BranchProgressScreen, type BranchStatusReport } from './branch-progress.js';
+/** Fold a live run envelope onto the last local snapshot. */
+export declare const mergeLiveBranchScreens: (screens: readonly BranchProgressScreen[], envelope: BranchRunEnvelope) => BranchProgressScreen[];
+export declare const readBranchStatus: (args: {
+    outDir: string;
+    /** Optional live read of the run; omitted or failing falls back to disk. */
+    refresh?: (runId: string) => Promise<BranchRunEnvelope | null>;
+    now?: number;
+}) => Promise<BranchStatusReport>;
+//# sourceMappingURL=branch-status.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"branch-status.d.ts","sourceRoot":"","sources":["../src/branch-status.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,EAKL,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACxB,MAAM,sBAAsB,CAAC;AAmC9B,6DAA6D;AAC7D,eAAO,MAAM,sBAAsB,GACjC,SAAS,SAAS,oBAAoB,EAAE,EACxC,UAAU,iBAAiB,KAC1B,oBAAoB,EAkBtB,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAU,MAAM;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAC/D,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,KAAG,OAAO,CAAC,kBAAkB,CAyE7B,CAAC"}

package/dist/branch-status.js

@@ -0,0 +1,118 @@
+import path from 'node:path';
+import { branchBlockedSlots } from './branch-schedule.js';
+import { branchProgressPath, readBranchProgress, summarizeBranchProgress, } from './branch-progress.js';
+import { branchAttemptPath, branchCompletionPath, branchPlanPath, readBranchAttempt, readBranchCompletion, } from './branch-run-record.js';
+/**
+ * `12ui branch status` — the answer to "is it still going?" that a second
+ * session, or the same agent after a sleep, can ask without touching the run.
+ * It always narrates motion: which screens are complete, which are generating
+ * and for how long against the typical duration, which are waiting on a
+ * dependency, and which are permanently blocked. It never answers with bare
+ * absence, because that is what makes a caller conclude the run died.
+ */
+const phaseFor = (attemptStatus, progressPhase) => {
+    if (progressPhase)
+        return progressPhase;
+    switch (attemptStatus) {
+        case 'downloading': return 'downloading';
+        case 'converting': return 'converting';
+        case 'dispatching': return 'dispatching';
+        case 'succeeded':
+        case 'partial':
+        case 'failed':
+            return 'terminal';
+        default: return 'claiming';
+    }
+};
+/** Fold a live run envelope onto the last local snapshot. */
+export const mergeLiveBranchScreens = (screens, envelope) => {
+    const live = new Map(envelope.candidates.map((candidate) => [candidate.slot, candidate]));
+    const blocked = new Map(branchBlockedSlots(envelope.candidates.map((candidate) => ({
+        slot: candidate.slot,
+        status: candidate.status,
+        footer: candidate.footer ?? null,
+        dependsOnSlot: candidate.dependsOnSlot ?? null,
+    }))).map((entry) => [entry.slot, entry]));
+    return screens.map((screen) => {
+        const candidate = live.get(screen.slot);
+        if (!candidate)
+            return screen;
+        const block = blocked.get(screen.slot);
+        return {
+            ...screen,
+            status: block ? 'blocked' : candidate.status,
+            ...(block ? { waitingOn: block.waitingOn } : {}),
+        };
+    });
+};
+export const readBranchStatus = async (args) => {
+    const outDir = path.resolve(args.outDir);
+    const attempt = await readBranchAttempt(branchAttemptPath(outDir));
+    const completion = await readBranchCompletion(branchCompletionPath(outDir));
+    const progress = await readBranchProgress(branchProgressPath(outDir));
+    if (!attempt && !completion && !progress) {
+        // Never started is not a failure and not a stall. Name the command that
+        // starts it rather than reporting an absence the caller has to interpret.
+        throw new Error(`This branch run has never been started — there is nothing to report, and nothing has`
+            + ` failed. ${outDir} holds no branch attempt, progress, or completion record.`
+            + ' Start one with `12ui branch execute --winner-run <crt-id> --winner-slot <slot>'
+            + ' --concept <text> --scope page|site --out-dir <directory>`, which blocks for the whole'
+            + ' run and streams progress.');
+    }
+    if (completion) {
+        return {
+            ...summarizeBranchProgress({
+                outDir,
+                ...(completion.runId ? { runId: completion.runId } : {}),
+                phase: 'terminal',
+                screens: (progress?.screens ?? []),
+                startedAt: completion.startedAt,
+                updatedAt: completion.completedAt,
+                completion,
+                now: args.now ?? Date.now(),
+            }),
+            completionPath: branchCompletionPath(outDir),
+            planPath: branchPlanPath(outDir),
+        };
+    }
+    const runId = progress?.runId ?? attempt?.runId;
+    let screens = progress?.screens ?? [];
+    if (runId && args.refresh) {
+        try {
+            const envelope = await args.refresh(runId);
+            if (envelope) {
+                screens = screens.length > 0
+                    ? mergeLiveBranchScreens(screens, envelope)
+                    : envelope.candidates.map((candidate) => ({
+                        slot: candidate.slot,
+                        status: candidate.status,
+                        pageIndex: candidate.pageIndex ?? 0,
+                        viewportOrdinal: candidate.viewportOrdinal ?? 0,
+                        ...(candidate.dependsOnSlot ? { waitingOn: candidate.dependsOnSlot } : {}),
+                    }));
+            }
+        }
+        catch {
+            // A status call must never fail because the network did; the local
+            // snapshot is still a truthful account of motion.
+        }
+    }
+    return {
+        ...summarizeBranchProgress({
+            outDir,
+            ...(runId ? { runId } : {}),
+            phase: phaseFor(attempt?.status, progress?.phase),
+            screens,
+            // The half of the run that takes the longest. Without it a poll during
+            // conversion answered with the same sentence every time.
+            ...(progress?.packages ? { packages: progress.packages } : {}),
+            ...(progress?.startedAt ?? attempt?.createdAt
+                ? { startedAt: progress?.startedAt ?? attempt.createdAt }
+                : {}),
+            ...(progress?.updatedAt ? { updatedAt: progress.updatedAt } : {}),
+            now: args.now ?? Date.now(),
+        }),
+        planPath: branchPlanPath(outDir),
+    };
+};
+//# sourceMappingURL=branch-status.js.map

package/dist/branch-status.js.map

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

package/dist/branch-viewport-normalization.d.ts

@@ -0,0 +1,74 @@
+/**
+ * One page stacks into one tall source, so every viewport of it must share one
+ * width. Branch pages mix two origins that cannot agree on their own:
+ *
+ *   - the CONTINUATION screens, drawn by the server on a canvas fixed by the
+ *     run's aspect (`CREATE_ASPECT_SIZES`, 1536x1024 for landscape). The build
+ *     claim accepts `source`, `concept`, `aspect`, `winner` and
+ *     `referenceImage` and nothing else — there is no width parameter — so the
+ *     server side of the page CANNOT be moved to meet the winner.
+ *   - the WINNER, viewport 1 of the source page, which came from a local image
+ *     provider or an upload and is whatever size that produced. Measured across
+ *     the 0.2.14 harness pass: 1672x941, 864x1821, 853x1844, 1024x1536, and in
+ *     one run 1536x1024 — the only run whose page could have converted.
+ *
+ * So the canonical width is the server's, read off the screens it actually
+ * produced, and the local image is the one that moves. That is a declared fact
+ * on both sides rather than a tuned guess: the width is measured from the
+ * delivered pixels the package validator will itself inspect.
+ *
+ * Only the width is reconciled. Heights differ on purpose — a page is a stack
+ * of viewports of different depths — so the resize preserves aspect ratio and
+ * the viewport simply becomes as tall as that width implies.
+ */
+/** The joined page must still fit the LayerDoc canvas and source-pixel limits. */
+export declare const MAX_JOINED_PAGE_SIDE = 10000;
+export declare const MAX_JOINED_PAGE_PIXELS = 8000000;
+export type ViewportImage = {
+    id: string;
+    bytes: Uint8Array;
+    mediaType: 'image/png' | 'image/jpeg' | 'image/webp';
+    width: number;
+    height: number;
+    /** True for a screen the server drew: it defines the page's canonical width. */
+    canonical: boolean;
+};
+export type NormalizedViewportImage = ViewportImage & {
+    sha256: string;
+    normalized: boolean;
+    original?: {
+        width: number;
+        height: number;
+        sha256: string;
+        bytes: number;
+    };
+};
+export declare const digestOf: (bytes: Uint8Array) => string;
+/**
+ * The width every viewport of this page is reconciled to: the width the server
+ * drew its screens at. With no server screen on the page there is nothing to
+ * reconcile and the page keeps the width it already has.
+ */
+export declare const canonicalPageWidth: (viewports: readonly ViewportImage[]) => number | null;
+export type PageNormalization = {
+    canonicalWidth: number | null;
+    /** True when the page was narrowed below the server's canvas to fit a limit. */
+    fitted: boolean;
+    viewports: NormalizedViewportImage[];
+    /** Ids that were resized, for the run record and the report. */
+    normalizedIds: string[];
+};
+/**
+ * The widest the page may be and still join inside both limits.
+ *
+ * Every viewport scales with the page, so the joined height is `width * K`
+ * where K is the sum of the viewports' height/width ratios. That makes the
+ * pixel limit `width² * K <= P` and the side limit `width * K <= S`, both
+ * solvable directly. Shrinking the whole page keeps it convertible and keeps
+ * every viewport in proportion; refusing would hand back nothing, and a tall
+ * approved screen stacked over three continuations is a shape the harness
+ * actually produced (864x1821 over three 1536x1024 screens is 9.7M pixels).
+ */
+export declare const widthThatFits: (requested: number, viewports: readonly ViewportImage[]) => number;
+export declare const normalizePageViewports: (viewports: readonly ViewportImage[]) => Promise<PageNormalization>;
+//# sourceMappingURL=branch-viewport-normalization.d.ts.map

package/dist/branch-viewport-normalization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-viewport-normalization.d.ts","sourceRoot":"","sources":["../src/branch-viewport-normalization.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAC3C,eAAO,MAAM,sBAAsB,UAAY,CAAC;AAEhD,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,WAAW,GAAG,YAAY,GAAG,YAAY,CAAC;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,aAAa,GAAG;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7E,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,OAAO,UAAU,KAAG,MAE5C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,WAAW,SAAS,aAAa,EAAE,KAAG,MAAM,GAAG,IAYjF,CAAC;AAoCF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gFAAgF;IAChF,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,uBAAuB,EAAE,CAAC;IACrC,gEAAgE;IAChE,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,GACxB,WAAW,MAAM,EACjB,WAAW,SAAS,aAAa,EAAE,KAClC,MASF,CAAC;AAEF,eAAO,MAAM,sBAAsB,GACjC,WAAW,SAAS,aAAa,EAAE,KAClC,OAAO,CAAC,iBAAiB,CAuB3B,CAAC"}