@12ui/design 0.2.13 → 0.2.14

package/dist/branch-execution.js

@@ -0,0 +1,261 @@
+import path from 'node:path';
+import { BranchApiError, } from './branch-client.js';
+import { branchConceptDigest, branchRunKey } from './branch-identity.js';
+import { buildCompletion, terminalFailure } from './branch-completion.js';
+import { materializeRun } from './branch-materialize.js';
+import { convertBranchPages } from './branch-page-conversion.js';
+import { applyBranchEnvelope, normalizeBranchPlan } from './branch-plan.js';
+import { branchProgressPath, branchProgressScreens, writeBranchProgress, } from './branch-progress.js';
+import { runBranchDispatch, } from './branch-dispatch-loop.js';
+import { BRANCH_ATTEMPT_FILENAME, BRANCH_PAGES_DIRECTORY, BRANCH_SCREENS_DIRECTORY, branchAttemptPath, branchCompletionPath, branchPlanPath, readBranchAttempt, readBranchCompletion, writeBranchAttempt, writeBranchCompletion, writeBranchPlanRecord, } from './branch-run-record.js';
+/**
+ * The whole branch choreography as one deterministic sequence: claim, plan,
+ * dependency-ordered dispatch, ordered download, per-page package conversion,
+ * sentinel. Everything mechanical lives here so the model's job collapses to
+ * choosing the winner, writing the concept, and picking the scope.
+ */
+const BUILD_PLAN_RETRIES = 3;
+export const deriveBranchRunKey = (inputs) => (inputs.idempotencyKey ?? branchRunKey({
+    winner: inputs.winner.kind === 'run'
+        ? { runId: inputs.winner.runId, slot: inputs.winner.slot }
+        : { imageSha256: inputs.winner.sha256 },
+    concept: inputs.concept,
+    scope: inputs.scope,
+}));
+const claimBuildRun = async (args) => {
+    let lastError;
+    for (let attempt = 1; attempt <= BUILD_PLAN_RETRIES; attempt += 1) {
+        try {
+            return await args.client.startBuildRun({
+                concept: args.inputs.concept,
+                ...(args.inputs.aspect ? { aspect: args.inputs.aspect } : {}),
+                ...(args.inputs.winner.kind === 'run'
+                    ? { winner: { createRunId: args.inputs.winner.runId, slot: args.inputs.winner.slot } }
+                    : {
+                        referenceImage: {
+                            data: Buffer.from(args.inputs.winner.bytes).toString('base64'),
+                            mediaType: args.inputs.winner.mediaType,
+                            sha256: args.inputs.winner.sha256,
+                        },
+                    }),
+            }, args.runKey, args.signal);
+        }
+        catch (error) {
+            lastError = error;
+            // Planning failed before any image spend, so the same key may replay.
+            const retryable = error instanceof BranchApiError && error.code === 'build_plan_failed';
+            if (!retryable || attempt === BUILD_PLAN_RETRIES)
+                throw error;
+        }
+    }
+    throw lastError;
+};
+export const executeBranchRun = async (args) => {
+    const emit = args.onEvent ?? (() => undefined);
+    const { inputs } = args;
+    const outDir = path.resolve(inputs.outDir);
+    const attemptFile = branchAttemptPath(outDir);
+    const completionFile = branchCompletionPath(outDir);
+    const screensDirectory = path.join(outDir, BRANCH_SCREENS_DIRECTORY);
+    const pagesDirectory = path.join(outDir, BRANCH_PAGES_DIRECTORY);
+    const runKey = deriveBranchRunKey(inputs);
+    const startedAt = new Date().toISOString();
+    const progressFile = branchProgressPath(outDir);
+    // Progress writes are serialized AND coalesced: the file is the one thing
+    // another session polls, so it must never be observed half-written, and a
+    // fast loop must not queue an unbounded backlog of stale snapshots. Only the
+    // newest pending snapshot is ever written.
+    let pendingProgress = null;
+    let progressWrites = Promise.resolve();
+    let progressWriting = false;
+    const drainProgress = () => {
+        if (progressWriting || !pendingProgress)
+            return;
+        progressWriting = true;
+        const record = pendingProgress;
+        pendingProgress = null;
+        progressWrites = writeBranchProgress(progressFile, record)
+            .catch(() => undefined)
+            .finally(() => {
+            progressWriting = false;
+            drainProgress();
+        });
+    };
+    const publishProgress = (phase, runId, screens) => {
+        emit({ kind: 'progress', phase, screens });
+        pendingProgress = {
+            version: 1,
+            runId,
+            phase,
+            startedAt,
+            updatedAt: new Date().toISOString(),
+            screens,
+        };
+        drainProgress();
+    };
+    const finished = await readBranchCompletion(completionFile);
+    if (finished) {
+        throw new Error(`This branch run already completed: ${completionFile} names run ${finished.runId},`
+            + ` ${finished.succeededCount} succeeded screen(s), and every page's conversion. Read it`
+            + ' rather than running the branch again, or choose a new --out-dir to start a new run.');
+    }
+    const existing = await readBranchAttempt(attemptFile);
+    if (existing && !args.resume) {
+        throw new Error(`Branch attempt evidence already exists at ${attemptFile} for run`
+            + ` ${existing.runId ?? '(unclaimed)'}. Re-run the identical command with --resume to`
+            + ' continue it: a resume replays every settled screen for free and re-dispatches only'
+            + ' what is still pending. It can never buy a screen twice.');
+    }
+    if (!existing && args.resume) {
+        // Never started, so nothing failed. This answers in a different register
+        // from a recovery report on purpose: a caller told "0 recovered" about work
+        // it never asked for concludes the service is broken and gives up.
+        throw new Error(`This branch run has never been started — there is nothing to resume, and nothing has`
+            + ` failed. There is no ${BRANCH_ATTEMPT_FILENAME} in ${outDir}. Run the same command`
+            + ' without --resume to start it; it blocks for the whole run and streams progress.');
+    }
+    if (existing && existing.runKey !== runKey) {
+        throw new Error(`Refusing to resume: ${outDir} holds run key ${existing.runKey} but these inputs derive`
+            + ` ${runKey}. A resume must replay the same winner, concept, and scope.`);
+    }
+    const attempt = existing ?? {
+        version: 1,
+        status: 'claiming',
+        runKey,
+        origin: args.origin,
+        scope: inputs.scope,
+        concept: inputs.concept,
+        conceptSha256: branchConceptDigest(inputs.concept),
+        winner: inputs.winner.kind === 'run'
+            ? { kind: 'run', runId: inputs.winner.runId, slot: inputs.winner.slot }
+            : {
+                kind: 'image',
+                imagePath: inputs.winner.imagePath,
+                sha256: inputs.winner.sha256,
+                mediaType: inputs.winner.mediaType,
+            },
+        ...(inputs.aspect ? { aspect: inputs.aspect } : {}),
+        ...(inputs.maxScreens === undefined ? {} : { maxScreens: inputs.maxScreens }),
+        ...(inputs.convert
+            ? {
+                convert: {
+                    output: inputs.convert.output,
+                    model: inputs.convert.model ?? 'standard',
+                    ...(inputs.convert.responsiveQuality
+                        ? { responsiveQuality: inputs.convert.responsiveQuality }
+                        : {}),
+                },
+            }
+            : {}),
+        ...(inputs.convert?.sourceConversionId
+            ? { sourceConversionId: inputs.convert.sourceConversionId }
+            : {}),
+        createdAt: startedAt,
+    };
+    if (existing) {
+        attempt.resumedAt = [...(attempt.resumedAt ?? []), startedAt];
+        await writeBranchAttempt(attemptFile, attempt);
+    }
+    else {
+        await writeBranchAttempt(attemptFile, attempt, true);
+    }
+    emit({ kind: 'phase', phase: 'claim', detail: 'planning the screens (10-20s, buys no image)' });
+    const envelope = attempt.runId
+        ? await args.branchClient.getRun(attempt.runId, args.signal)
+        : await claimBuildRun({
+            client: args.branchClient,
+            inputs,
+            runKey,
+            ...(args.signal ? { signal: args.signal } : {}),
+        });
+    attempt.runId = envelope.id;
+    attempt.status = 'dispatching';
+    await writeBranchAttempt(attemptFile, attempt);
+    let plan = normalizeBranchPlan(envelope, {
+        scope: inputs.scope,
+        ...(inputs.maxScreens === undefined ? {} : { maxScreens: inputs.maxScreens }),
+    });
+    await writeBranchPlanRecord(branchPlanPath(outDir), plan);
+    emit({
+        kind: 'phase',
+        phase: 'plan',
+        detail: `${plan.pages.length} page(s), ${plan.screens.length} screen(s) to generate`,
+    });
+    let stopped = null;
+    publishProgress('dispatching', envelope.id, branchProgressScreens(plan, {}));
+    if (plan.screens.length > 0) {
+        const dispatched = await runBranchDispatch({
+            client: args.branchClient,
+            plan,
+            onEvent: emit,
+            onSnapshot: (snapshot) => publishProgress('dispatching', envelope.id, branchProgressScreens(snapshot.plan, snapshot.dispatchedAt)),
+            ...(args.signal ? { signal: args.signal } : {}),
+            ...(args.dispatch ?? {}),
+        });
+        plan = dispatched.plan;
+        stopped = dispatched.stopped;
+    }
+    else {
+        plan = applyBranchEnvelope(plan, envelope);
+    }
+    attempt.status = 'downloading';
+    publishProgress('downloading', envelope.id, branchProgressScreens(plan, {}));
+    await writeBranchAttempt(attemptFile, attempt);
+    const { screens, winner } = await materializeRun({
+        client: args.branchClient,
+        plan,
+        inputs,
+        screensDirectory,
+        needsWinner: Boolean(inputs.convert) && plan.pages.some((page) => page.startsFromWinner),
+        ...(args.signal ? { signal: args.signal } : {}),
+    });
+    emit({ kind: 'phase', phase: 'download', detail: `${screens.size} screen(s) on disk` });
+    const conversions = new Map();
+    if (inputs.convert && !stopped) {
+        attempt.status = 'converting';
+        publishProgress('converting', envelope.id, branchProgressScreens(plan, {}));
+        await writeBranchAttempt(attemptFile, attempt);
+        if (!args.packageClient)
+            throw new Error('A conversion package client is required for --convert');
+        emit({ kind: 'phase', phase: 'convert', detail: 'one package conversion per whole page' });
+        const converted = await convertBranchPages({
+            client: args.packageClient,
+            plan,
+            screens,
+            settings: inputs.convert,
+            pagesDirectory,
+            ...(winner ? { winner } : {}),
+            ...(args.packageTimeoutMs === undefined ? {} : { timeoutMs: args.packageTimeoutMs }),
+            onProgress: (pageId, progress) => emit({ kind: 'package', pageId, progress }),
+            ...(args.signal ? { signal: args.signal } : {}),
+        });
+        for (const [pageId, conversion] of converted)
+            conversions.set(pageId, conversion);
+    }
+    const completion = buildCompletion({
+        plan,
+        inputs,
+        runKey,
+        origin: args.origin,
+        outDir,
+        attemptFile,
+        startedAt,
+        screens,
+        ...(winner ? { winner } : {}),
+        conversions,
+        stopped,
+    });
+    publishProgress('terminal', envelope.id, branchProgressScreens(plan, {}));
+    await progressWrites;
+    await writeBranchCompletion(completionFile, completion);
+    attempt.status = completion.status;
+    attempt.completedAt = completion.completedAt;
+    attempt.completionPath = completionFile;
+    await writeBranchAttempt(attemptFile, attempt);
+    return {
+        completion,
+        completionPath: completionFile,
+        failure: terminalFailure({ completion, stopped, completionFile, convert: Boolean(inputs.convert) }),
+    };
+};
+//# sourceMappingURL=branch-execution.js.map

package/dist/branch-execution.js.map

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

package/dist/branch-identity.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Every identity a branch run needs, derived from its inputs rather than
+ * authored. Free-text keys are load-bearing in both directions here: the same
+ * key with a changed body wedges the claim with `409 idempotency_conflict`, and
+ * a NEW key on a settled slot buys another image. Deriving them removes both
+ * failure modes from the agent's hands.
+ *
+ * Digests are truncated because `Idempotency-Key` is capped at 128 printable
+ * characters and a run id alone is 44 of them. 16 hex characters is 64 bits of
+ * collision resistance over inputs that are already scoped by run id, which is
+ * far more than the number of runs any account will ever hold.
+ */
+export declare const BRANCH_WORKFLOW_REVISION = "branch-execute-v1";
+export type BranchScope = 'page' | 'site';
+export declare const branchConceptDigest: (concept: string) => string;
+/**
+ * Same inputs -> same run, so an interrupted claim replays instead of starting
+ * a second one. A changed concept is a different design problem and therefore a
+ * different run, so it derives a new key rather than wedging the old one.
+ */
+export declare const branchRunKey: (args: {
+    winner: {
+        runId: string;
+        slot: string;
+    } | {
+        imageSha256: string;
+    };
+    concept: string;
+    scope: BranchScope;
+}) => string;
+/**
+ * The ONLY keyed dispatch. Automatic dispatch is unkeyed so every replay is
+ * free; a redraw is an explicit request for one further paid attempt and needs
+ * a key the settled slot has never seen.
+ */
+export declare const branchRedrawKey: (args: {
+    runId: string;
+    slot: string;
+    attempt: number;
+}) => string;
+/**
+ * Stable under retry and distinct per page. Keying on the ordered viewport
+ * hashes means a resumed run that downloaded the same bytes replays the same
+ * package rather than buying a second one, while a redrawn screen produces a
+ * genuinely different page and therefore a genuinely different key.
+ */
+export declare const branchPackageKey: (args: {
+    runId: string;
+    pageIndex: number;
+    viewportSha256s: readonly string[];
+    output: string;
+    model?: string;
+    responsiveQuality?: string;
+}) => string;
+/** Standalone `convert package` runs derive from the manifest they were given. */
+export declare const conversionPackageKey: (args: {
+    manifestSha256: string;
+    output: string;
+}) => string;
+/**
+ * Standalone `export` runs derive from the conversion they re-render. The
+ * export command appends the output and a digest of the request body to this
+ * base, so the base only has to pin the source: exporting the same conversion
+ * to the same format twice is the same paid work and must replay rather than
+ * buy it again, while a different format or profile lands on a different key
+ * through the suffix.
+ */
+export declare const conversionExportKey: (args: {
+    sourceConversionId: string;
+}) => string;
+//# sourceMappingURL=branch-identity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"branch-identity.d.ts","sourceRoot":"","sources":["../src/branch-identity.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,wBAAwB,sBAAsB,CAAC;AAE5D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAM1C,eAAO,MAAM,mBAAmB,GAAI,SAAS,MAAM,KAAG,MAErD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM;IACjC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,WAAW,CAAC;CACpB,KAAG,MAYH,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,KAAG,MAAoE,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,KAAG,MAaO,CAAC;AAEZ,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,GAAI,MAAM;IACzC,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB,KAAG,MAAiF,CAAC;AAEtF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM;IACxC,kBAAkB,EAAE,MAAM,CAAC;CAC5B,KAAG,MAAwD,CAAC"}

package/dist/branch-identity.js

@@ -0,0 +1,72 @@
+import { createHash } from 'node:crypto';
+/**
+ * Every identity a branch run needs, derived from its inputs rather than
+ * authored. Free-text keys are load-bearing in both directions here: the same
+ * key with a changed body wedges the claim with `409 idempotency_conflict`, and
+ * a NEW key on a settled slot buys another image. Deriving them removes both
+ * failure modes from the agent's hands.
+ *
+ * Digests are truncated because `Idempotency-Key` is capped at 128 printable
+ * characters and a run id alone is 44 of them. 16 hex characters is 64 bits of
+ * collision resistance over inputs that are already scoped by run id, which is
+ * far more than the number of runs any account will ever hold.
+ */
+export const BRANCH_WORKFLOW_REVISION = 'branch-execute-v1';
+const shortDigest = (value, characters = 16) => (createHash('sha256').update(value).digest('hex').slice(0, characters));
+export const branchConceptDigest = (concept) => (createHash('sha256').update(concept).digest('hex'));
+/**
+ * Same inputs -> same run, so an interrupted claim replays instead of starting
+ * a second one. A changed concept is a different design problem and therefore a
+ * different run, so it derives a new key rather than wedging the old one.
+ */
+export const branchRunKey = (args) => {
+    const origin = 'runId' in args.winner
+        ? `${args.winner.runId}:${args.winner.slot}`
+        : `img-${args.winner.imageSha256.slice(0, 32)}:-`;
+    return [
+        'branch',
+        'v1',
+        origin,
+        shortDigest(args.concept),
+        args.scope,
+        BRANCH_WORKFLOW_REVISION,
+    ].join(':');
+};
+/**
+ * The ONLY keyed dispatch. Automatic dispatch is unkeyed so every replay is
+ * free; a redraw is an explicit request for one further paid attempt and needs
+ * a key the settled slot has never seen.
+ */
+export const branchRedrawKey = (args) => `branch-screen:${args.runId}:${args.slot}:${args.attempt}`;
+/**
+ * Stable under retry and distinct per page. Keying on the ordered viewport
+ * hashes means a resumed run that downloaded the same bytes replays the same
+ * package rather than buying a second one, while a redrawn screen produces a
+ * genuinely different page and therefore a genuinely different key.
+ */
+export const branchPackageKey = (args) => [
+    'branch-package',
+    'v1',
+    args.runId,
+    String(args.pageIndex),
+    shortDigest(args.viewportSha256s.join('.'), 32),
+    args.output,
+    // Everything that changes the request body has to be in the key. Model and
+    // quality are body fields, so leaving them out turns a deliberate change of
+    // model into `409 idempotency_conflict` on a page that was never bought —
+    // measured against production while smoke-testing this command.
+    args.model ?? 'standard',
+    args.responsiveQuality ?? 'default',
+].join(':');
+/** Standalone `convert package` runs derive from the manifest they were given. */
+export const conversionPackageKey = (args) => `convert-package:v1:${args.manifestSha256.slice(0, 32)}:${args.output}`;
+/**
+ * Standalone `export` runs derive from the conversion they re-render. The
+ * export command appends the output and a digest of the request body to this
+ * base, so the base only has to pin the source: exporting the same conversion
+ * to the same format twice is the same paid work and must replay rather than
+ * buy it again, while a different format or profile lands on a different key
+ * through the suffix.
+ */
+export const conversionExportKey = (args) => `convert-export:v1:${args.sourceConversionId}`;
+//# sourceMappingURL=branch-identity.js.map

package/dist/branch-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-identity.js","sourceRoot":"","sources":["../src/branch-identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,wBAAwB,GAAG,mBAAmB,CAAC;AAI5D,MAAM,WAAW,GAAG,CAAC,KAAa,EAAE,UAAU,GAAG,EAAE,EAAU,EAAE,CAAC,CAC9D,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,CACtE,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,OAAe,EAAU,EAAE,CAAC,CAC9D,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACnD,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAI5B,EAAU,EAAE;IACX,MAAM,MAAM,GAAG,OAAO,IAAI,IAAI,CAAC,MAAM;QACnC,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;QAC5C,CAAC,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;IACpD,OAAO;QACL,QAAQ;QACR,IAAI;QACJ,MAAM;QACN,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC;QACzB,IAAI,CAAC,KAAK;QACV,wBAAwB;KACzB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACd,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAI/B,EAAU,EAAE,CAAC,iBAAiB,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,IAOhC,EAAU,EAAE,CAAC;IACZ,gBAAgB;IAChB,IAAI;IACJ,IAAI,CAAC,KAAK;IACV,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC;IACtB,WAAW,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;IAC/C,IAAI,CAAC,MAAM;IACX,2EAA2E;IAC3E,4EAA4E;IAC5E,0EAA0E;IAC1E,gEAAgE;IAChE,IAAI,CAAC,KAAK,IAAI,UAAU;IACxB,IAAI,CAAC,iBAAiB,IAAI,SAAS;CACpC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEZ,kFAAkF;AAClF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,IAGpC,EAAU,EAAE,CAAC,sBAAsB,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;AAEtF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,IAEnC,EAAU,EAAE,CAAC,qBAAqB,IAAI,CAAC,kBAAkB,EAAE,CAAC"}

package/dist/branch-materialize.d.ts

@@ -0,0 +1,22 @@
+import type { TwelveUiBranchClient } from './branch-client.js';
+import { type BranchDownloadedScreen } from './branch-downloads.js';
+import type { BranchExecutionInputs } from './branch-execution-types.js';
+import type { BranchNormalizedPlan } from './branch-plan.js';
+/**
+ * Delivery. Every screen the run bought is staged first and moved into place in
+ * ONE atomic pass, so `screens/` goes from empty to complete and a caller can
+ * never mistake a half-written run for a failed one. Bytes already on disk were
+ * already paid for, which is what makes a resume free.
+ */
+export declare const materializeRun: (args: {
+    client: TwelveUiBranchClient;
+    plan: BranchNormalizedPlan;
+    inputs: BranchExecutionInputs;
+    screensDirectory: string;
+    needsWinner: boolean;
+    signal?: AbortSignal;
+}) => Promise<{
+    screens: Map<string, BranchDownloadedScreen>;
+    winner?: BranchDownloadedScreen;
+}>;
+//# sourceMappingURL=branch-materialize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"branch-materialize.d.ts","sourceRoot":"","sources":["../src/branch-materialize.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAKL,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7D;;;;;GAKG;AAEH,eAAO,MAAM,cAAc,GAAU,MAAM;IACzC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,IAAI,EAAE,oBAAoB,CAAC;IAC3B,MAAM,EAAE,qBAAqB,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAG,OAAO,CAAC;IAAE,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAAC,MAAM,CAAC,EAAE,sBAAsB,CAAA;CAAE,CA4C5F,CAAC"}

package/dist/branch-materialize.js

@@ -0,0 +1,47 @@
+import { materializeBranchScreens, readMaterializedScreen, stageBranchScreen, stageBranchScreenBytes, } from './branch-downloads.js';
+/**
+ * Delivery. Every screen the run bought is staged first and moved into place in
+ * ONE atomic pass, so `screens/` goes from empty to complete and a caller can
+ * never mistake a half-written run for a failed one. Bytes already on disk were
+ * already paid for, which is what makes a resume free.
+ */
+export const materializeRun = async (args) => {
+    const screens = new Map();
+    const staged = [];
+    const succeeded = args.plan.screens.filter((screen) => screen.status === 'succeeded');
+    for (const screen of succeeded) {
+        // Bytes already on disk were already paid for and already delivered.
+        const materialized = await readMaterializedScreen(args.screensDirectory, screen.slot);
+        if (materialized) {
+            screens.set(screen.slot, materialized);
+            continue;
+        }
+        screens.set(screen.slot, await stageBranchScreen({
+            client: args.client,
+            runId: args.plan.runId,
+            slot: screen.slot,
+            screensDirectory: args.screensDirectory,
+            ...(args.signal ? { signal: args.signal } : {}),
+        }));
+        staged.push(screen.slot);
+    }
+    let winner;
+    if (args.needsWinner) {
+        winner = await readMaterializedScreen(args.screensDirectory, 'winner') ?? undefined;
+        if (!winner) {
+            const bytes = args.inputs.winner.kind === 'image'
+                ? args.inputs.winner.bytes
+                : (await args.client.downloadScreen(args.inputs.winner.runId, args.inputs.winner.slot, args.signal)).bytes;
+            winner = await stageBranchScreenBytes({
+                screensDirectory: args.screensDirectory,
+                slot: 'winner',
+                bytes,
+            });
+            staged.push('winner');
+        }
+    }
+    // One atomic pass: the screens directory goes from empty to complete.
+    await materializeBranchScreens(args.screensDirectory, staged);
+    return { screens, ...(winner ? { winner } : {}) };
+};
+//# sourceMappingURL=branch-materialize.js.map

package/dist/branch-materialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-materialize.js","sourceRoot":"","sources":["../src/branch-materialize.ts"],"names":[],"mappings":"AACA,OAAO,EACL,wBAAwB,EACxB,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,GAEvB,MAAM,uBAAuB,CAAC;AAI/B;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,EAAE,IAOpC,EAA8F,EAAE;IAC/F,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkC,CAAC;IAC1D,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,KAAK,WAAW,CAAC,CAAC;IACtF,KAAK,MAAM,MAAM,IAAI,SAAS,EAAE,CAAC;QAC/B,qEAAqE;QACrE,MAAM,YAAY,GAAG,MAAM,sBAAsB,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QACtF,IAAI,YAAY,EAAE,CAAC;YACjB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;YACvC,SAAS;QACX,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,iBAAiB,CAAC;YAC/C,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK;YACtB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC,CAAC,CAAC;QACJ,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,IAAI,MAA0C,CAAC;IAC/C,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,MAAM,GAAG,MAAM,sBAAsB,CAAC,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAC,IAAI,SAAS,CAAC;QACpF,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,OAAO;gBAC/C,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK;gBAC1B,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CACjC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EACxB,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EACvB,IAAI,CAAC,MAAM,CACZ,CAAC,CAAC,KAAK,CAAC;YACX,MAAM,GAAG,MAAM,sBAAsB,CAAC;gBACpC,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;gBACvC,IAAI,EAAE,QAAQ;gBACd,KAAK;aACN,CAAC,CAAC;YACH,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxB,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,MAAM,wBAAwB,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IAC9D,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACpD,CAAC,CAAC"}

package/dist/branch-page-conversion.d.ts

@@ -0,0 +1,39 @@
+import type { ConversionModel } from './conversion-models.js';
+import type { ResponsiveConversionQuality } from './responsive-quality.js';
+import type { BranchDownloadedScreen } from './branch-downloads.js';
+import type { BranchNormalizedPlan } from './branch-plan.js';
+import type { BranchCompletionPage } from './branch-run-record.js';
+import type { TwelveUiConversionPackageClient } from './package-client.js';
+import { type PackageProgressEvent } from './package-submission.js';
+/**
+ * The terminal step: ordered viewports of ONE page become ONE package
+ * conversion. Viewport 1 of the source page is the approved winner — the
+ * server never generates it — so the package is what makes the winner and its
+ * continuations one document instead of a pile of separately converted images.
+ *
+ * A page with a hole in it is parked, not converted: stitching an incomplete
+ * page would silently ship a page that is missing a section. Its siblings still
+ * convert, because one failed screen must not cost the pages that are whole.
+ */
+export type BranchConversionSettings = {
+    output: 'html';
+    model?: ConversionModel;
+    responsiveQuality?: ResponsiveConversionQuality;
+    /** Reuse of an existing succeeded conversion of the winner's exact bytes. */
+    sourceConversionId?: string;
+};
+export declare const WINNER_VIEWPORT_ID = "winner";
+type PageConversion = NonNullable<BranchCompletionPage['conversion']>;
+export declare const convertBranchPages: (args: {
+    client: TwelveUiConversionPackageClient;
+    plan: BranchNormalizedPlan;
+    screens: ReadonlyMap<string, BranchDownloadedScreen>;
+    winner?: BranchDownloadedScreen;
+    settings: BranchConversionSettings;
+    pagesDirectory: string;
+    timeoutMs?: number;
+    onProgress?: (pageId: string, event: PackageProgressEvent) => void;
+    signal?: AbortSignal;
+}) => Promise<Map<string, PageConversion>>;
+export {};
+//# sourceMappingURL=branch-page-conversion.d.ts.map

package/dist/branch-page-conversion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-page-conversion.d.ts","sourceRoot":"","sources":["../src/branch-page-conversion.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAE3E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,qBAAqB,CAAC;AAM3E,OAAO,EAGL,KAAK,oBAAoB,EAE1B,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;GASG;AAEH,MAAM,MAAM,wBAAwB,GAAG;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,iBAAiB,CAAC,EAAE,2BAA2B,CAAC;IAChD,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAE3C,KAAK,cAAc,GAAG,WAAW,CAAC,oBAAoB,CAAC,YAAY,CAAC,CAAC,CAAC;AActE,eAAO,MAAM,kBAAkB,GAAU,MAAM;IAC7C,MAAM,EAAE,+BAA+B,CAAC;IACxC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IACrD,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,QAAQ,EAAE,wBAAwB,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAC;IACnE,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAkMtC,CAAC"}