@12ui/design 0.2.13 → 0.2.14

package/dist/cli-package-command.js

@@ -0,0 +1,112 @@
+import { stat } from 'node:fs/promises';
+import path from 'node:path';
+import { booleanFlag, stringFlag } from './cli-arguments.js';
+import { readConversionConfig } from './config.js';
+import { conversionPackageKey } from './branch-identity.js';
+import { normalizeOptionalIdempotencyKey } from './idempotency-key.js';
+import { TwelveUiConversionPackageClient } from './package-client.js';
+import { readLocalPackageManifest } from './package-manifest-file.js';
+import { PACKAGE_RESULT_FILENAME, submitConversionPackage, writePackageResultRecord, } from './package-submission.js';
+import { formatDuration, nextActionLine } from './cli-progress.js';
+/**
+ * `12ui convert package` — the ordered-viewport submission that had no CLI at
+ * all. Without it the terminal step of the branch path was the least supported
+ * operation in the product, and an agent that got that far fell back to
+ * per-image conversion, losing page order and stitching.
+ */
+export const PACKAGE_USAGE = 'Usage: 12ui convert package --manifest <package.json>'
+    + ' --out-dir <directory> [--idempotency-key <key>] [--timeout-ms <ms>] [--wait] [--quiet]'
+    + '\n       12ui convert package --template > package.json';
+/** A multi-viewport page converts its viewports in parallel, then composes. */
+export const PACKAGE_DURATION_SECONDS = 360;
+const parseTimeoutMs = (value) => {
+    if (value === undefined)
+        return undefined;
+    const timeoutMs = Number(value);
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 1_000) {
+        throw new Error('--timeout-ms must be a number of at least 1000');
+    }
+    return Math.floor(timeoutMs);
+};
+const refuseExistingResult = async (outDir) => {
+    const existing = path.join(outDir, PACKAGE_RESULT_FILENAME);
+    try {
+        await stat(existing);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    throw new Error(`A package result already exists at ${existing}. It names the package id and every page's`
+        + ' conversion id — read it back rather than submitting the same pages again, or choose a'
+        + ' new --out-dir if you genuinely want another package.');
+};
+export const runPackageCommand = async (flags, dependencies = {}) => {
+    const manifestFlag = stringFlag(flags, 'manifest')?.trim();
+    const outDirFlag = stringFlag(flags, 'out-dir')?.trim();
+    if (!manifestFlag || !outDirFlag)
+        throw new Error(PACKAGE_USAGE);
+    const manifestPath = path.resolve(manifestFlag);
+    const outDir = path.resolve(outDirFlag);
+    const quiet = booleanFlag(flags, 'quiet');
+    await refuseExistingResult(outDir);
+    const manifest = await readLocalPackageManifest(manifestPath);
+    const idempotencyKey = normalizeOptionalIdempotencyKey(stringFlag(flags, 'idempotency-key'), '--idempotency-key') ?? conversionPackageKey({
+        manifestSha256: manifest.manifestSha256,
+        output: manifest.output,
+    });
+    const config = (dependencies.readConfig ?? readConversionConfig)({
+        origin: stringFlag(flags, 'origin'),
+        apiKey: stringFlag(flags, 'api-key'),
+    });
+    const client = (dependencies.createClient ?? ((value) => (new TwelveUiConversionPackageClient(value))))(config);
+    const viewportCount = manifest.pages.reduce((total, page) => total + page.viewports.length, 0);
+    if (!quiet) {
+        process.stderr.write(`12ui convert package — ${manifest.pages.length} page(s), ${viewportCount} viewport(s)`
+            + ` to ${manifest.output}; expect about ${formatDuration(PACKAGE_DURATION_SECONDS)}\n`);
+    }
+    const startedAt = Date.now();
+    const result = await submitConversionPackage({
+        client,
+        outDir,
+        submission: {
+            output: manifest.output,
+            ...(manifest.model ? { model: manifest.model } : {}),
+            ...(manifest.responsiveQuality ? { responsiveQuality: manifest.responsiveQuality } : {}),
+            pages: manifest.pages,
+            idempotencyKey,
+        },
+        ...(parseTimeoutMs(stringFlag(flags, 'timeout-ms')) === undefined
+            ? {}
+            : { timeoutMs: parseTimeoutMs(stringFlag(flags, 'timeout-ms')) }),
+        onSubmitted: quiet
+            ? undefined
+            : (packageId) => {
+                process.stderr.write(`12ui convert package ${packageId} submitted.\n${nextActionLine({
+                    what: 'A multi-viewport page conversion',
+                    typicalSeconds: PACKAGE_DURATION_SECONDS,
+                    statusCommand: `GET /api/v1/convert/package/${packageId}`,
+                    waitHint: 'or leave this command running, which is what --wait already does by default',
+                })}\n`);
+            },
+        onProgress: quiet
+            ? undefined
+            : (event) => {
+                const elapsed = formatDuration((Date.now() - startedAt) / 1000);
+                const percent = event.percent === undefined ? '' : ` ${event.percent}%`;
+                process.stderr.write(`[${elapsed}] package: ${event.stage}${percent}\n`);
+            },
+    });
+    const resultPath = await writePackageResultRecord(outDir, result);
+    const reported = { ...result, resultPath };
+    console.log(JSON.stringify({ manifestPath, outDir, ...reported }, null, 2));
+    const failed = reported.pages.filter((page) => page.status === 'failed');
+    if (failed.length > 0) {
+        throw new Error(`Package ${reported.packageId} converted ${reported.pages.length - failed.length} of`
+            + ` ${reported.pages.length} page(s). Failed: ${failed.map((page) => page.id).join(', ')}.`
+            + ` Evidence: ${resultPath}`);
+    }
+    return reported;
+};
+//# sourceMappingURL=cli-package-command.js.map

package/dist/cli-package-command.js.map

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

package/dist/cli-progress.d.ts

@@ -20,8 +20,69 @@ export declare const CONVERSION_DURATION_HINTS: {
     readonly fused: 300;
 };
 export type ConversionDurationHintKind = keyof typeof CONVERSION_DURATION_HINTS;
+/**
+ * Every long operation's typical wall time, in one place, so a status line, a
+ * skill sentence, and a capability document can never quote three different
+ * numbers for the same wait.
+ */
+export declare const OPERATION_DURATION_HINTS: {
+    /** One generated candidate from the local image provider. */
+    readonly imageCandidate: 90;
+    /** Four candidates, started concurrently. */
+    readonly imageBatch: 90;
+    /** The build claim: the planner runs inline and buys no image. */
+    readonly branchClaim: 15;
+    /** One branch screen. The server's own provider budget is 150 s. */
+    readonly branchScreen: 90;
+    readonly branchScreenBudget: 150;
+    /** A whole `--scope page` run: serial trunk continuations plus one package. */
+    readonly branchPage: 720;
+    /** A whole `--scope site` run: several pages, one package each. */
+    readonly branchSite: 1200;
+    /** One package conversion of a multi-viewport page to responsive HTML. */
+    readonly package: 360;
+    /** image -> LayerDoc. Extraction plus materialization. */
+    readonly convert: 240;
+    /** A responsive HTML export run on its own, after the conversion finished. */
+    readonly export: 240;
+    /**
+     * Fused convert + export. The export's reference and anchor conversions run
+     * alongside the conversion, so the bundle costs about the slower half plus
+     * assembly rather than the sum of both.
+     */
+    readonly fused: 300;
+};
+export type OperationDurationHintKind = keyof typeof OPERATION_DURATION_HINTS;
 export declare const formatDuration: (seconds: number) => string;
 export declare const durationHint: (kind: ConversionDurationHintKind) => string;
+/**
+ * `45s elapsed, ~90s typical`. A bare elapsed time reads as a stall; the pair
+ * is what tells a caller the wait is still inside the expected envelope.
+ */
+export declare const elapsedAgainstTypical: (elapsedSeconds: number, typicalSeconds: number) => string;
+/**
+ * THE mandatory closing line of any output that is not yet terminal.
+ *
+ * A poll surface that answers with bare absence is what makes a model conclude
+ * the process stalled and improvise around it. Every not-yet-done response ends
+ * by naming the typical duration, the exact command that narrates progress, and
+ * the blocking alternative — so the caller can sleep, schedule, or block
+ * according to what it can actually do.
+ */
+export declare const nextActionLine: (args: {
+    what: string;
+    typicalSeconds: number;
+    statusCommand: string;
+    checkAgainSeconds?: number;
+    waitHint?: string;
+}) => string;
+/** `3 complete, 2 generating, 4 waiting, 0 blocked` — zeros included on purpose. */
+export declare const narrateCounts: (counts: readonly {
+    label: string;
+    count: number;
+    detail?: string;
+}[]) => string;
+export declare const secondsSince: (iso: string | undefined, now: number) => number | undefined;
 export declare const stageLabel: (stage: string) => string;
 export type ProgressReporter = {
     onProgress: (operation: ConversionOperation) => void;

package/dist/cli-progress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-progress.d.ts","sourceRoot":"","sources":["../src/cli-progress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB;IACpC,0DAA0D;;IAE1D,8EAA8E;;IAE9E;;;;OAIG;;CAEK,CAAC;AAEX,MAAM,MAAM,0BAA0B,GAAG,MAAM,OAAO,yBAAyB,CAAC;AAEhF,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,KAAG,MAMhD,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,MAAM,0BAA0B,KAAG,MAE/D,CAAC;AAsBF,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,MAAsC,CAAC;AAElF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,CAAC,SAAS,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACrD,2CAA2C;IAC3C,IAAI,EAAE,CAAC,SAAS,EAAE,mBAAmB,KAAK,IAAI,CAAC;CAChD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAI,MAAM;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,KAAG,gBAsBH,CAAC"}
+{"version":3,"file":"cli-progress.d.ts","sourceRoot":"","sources":["../src/cli-progress.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElE;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB;IACpC,0DAA0D;;IAE1D,8EAA8E;;IAE9E;;;;OAIG;;CAEK,CAAC;AAEX,MAAM,MAAM,0BAA0B,GAAG,MAAM,OAAO,yBAAyB,CAAC;AAEhF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB;IAEnC,6DAA6D;;IAE7D,6CAA6C;;IAE7C,kEAAkE;;IAElE,oEAAoE;;;IAGpE,+EAA+E;;IAE/E,mEAAmE;;IAEnE,0EAA0E;;IAlC1E,0DAA0D;;IAE1D,8EAA8E;;IAE9E;;;;OAIG;;CA4BK,CAAC;AAEX,MAAM,MAAM,yBAAyB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AAE9E,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,KAAG,MAMhD,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,MAAM,0BAA0B,KAAG,MAE/D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAChC,gBAAgB,MAAM,EACtB,gBAAgB,MAAM,KACrB,MAEF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,KAAG,MAKH,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,aAAa,GACxB,QAAQ,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,KACnE,MAEU,CAAC;AAEd,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,GAAG,SAAS,EAAE,KAAK,MAAM,KAAG,MAAM,GAAG,SAI5E,CAAC;AAsBF,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,MAAsC,CAAC;AAElF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,EAAE,CAAC,SAAS,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACrD,2CAA2C;IAC3C,IAAI,EAAE,CAAC,SAAS,EAAE,mBAAmB,KAAK,IAAI,CAAC;CAChD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAI,MAAM;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,KAAG,gBAsBH,CAAC"}

package/dist/cli-progress.js

@@ -18,6 +18,29 @@ export const CONVERSION_DURATION_HINTS = {
      */
     fused: 300,
 };
+/**
+ * Every long operation's typical wall time, in one place, so a status line, a
+ * skill sentence, and a capability document can never quote three different
+ * numbers for the same wait.
+ */
+export const OPERATION_DURATION_HINTS = {
+    ...CONVERSION_DURATION_HINTS,
+    /** One generated candidate from the local image provider. */
+    imageCandidate: 90,
+    /** Four candidates, started concurrently. */
+    imageBatch: 90,
+    /** The build claim: the planner runs inline and buys no image. */
+    branchClaim: 15,
+    /** One branch screen. The server's own provider budget is 150 s. */
+    branchScreen: 90,
+    branchScreenBudget: 150,
+    /** A whole `--scope page` run: serial trunk continuations plus one package. */
+    branchPage: 720,
+    /** A whole `--scope site` run: several pages, one package each. */
+    branchSite: 1_200,
+    /** One package conversion of a multi-viewport page to responsive HTML. */
+    package: 360,
+};
 export const formatDuration = (seconds) => {
     const whole = Math.max(0, Math.round(seconds));
     if (whole < 90)
@@ -27,6 +50,36 @@ export const formatDuration = (seconds) => {
     return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`;
 };
 export const durationHint = (kind) => (`expect about ${formatDuration(CONVERSION_DURATION_HINTS[kind])}`);
+/**
+ * `45s elapsed, ~90s typical`. A bare elapsed time reads as a stall; the pair
+ * is what tells a caller the wait is still inside the expected envelope.
+ */
+export const elapsedAgainstTypical = (elapsedSeconds, typicalSeconds) => (`${formatDuration(elapsedSeconds)} elapsed, ~${formatDuration(typicalSeconds)} typical`);
+/**
+ * THE mandatory closing line of any output that is not yet terminal.
+ *
+ * A poll surface that answers with bare absence is what makes a model conclude
+ * the process stalled and improvise around it. Every not-yet-done response ends
+ * by naming the typical duration, the exact command that narrates progress, and
+ * the blocking alternative — so the caller can sleep, schedule, or block
+ * according to what it can actually do.
+ */
+export const nextActionLine = (args) => {
+    const checkAgain = formatDuration(args.checkAgainSeconds ?? Math.max(30, Math.round(args.typicalSeconds / 3)));
+    const wait = args.waitHint ?? 'or re-run the command with --wait to block until it finishes';
+    return `${args.what} typically takes about ${formatDuration(args.typicalSeconds)}.`
+        + ` Check again in ${checkAgain} with \`${args.statusCommand}\`, ${wait}.`;
+};
+/** `3 complete, 2 generating, 4 waiting, 0 blocked` — zeros included on purpose. */
+export const narrateCounts = (counts) => counts
+    .map((entry) => `${entry.count} ${entry.label}${entry.detail ? ` (${entry.detail})` : ''}`)
+    .join(', ');
+export const secondsSince = (iso, now) => {
+    if (!iso)
+        return undefined;
+    const started = Date.parse(iso);
+    return Number.isFinite(started) ? Math.max(0, (now - started) / 1000) : undefined;
+};
 /** Human-readable name for a pipeline stage, for progress lines. */
 const STAGE_LABELS = {
     queued: 'queued',

package/dist/cli-progress.js.map

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

package/dist/cli-select-command.d.ts

@@ -0,0 +1,12 @@
+import { type CliFlags } from './cli-arguments.js';
+/**
+ * `12ui select` — the choice, recorded.
+ *
+ * The judgement stays the model's: it has to look at four images and say which
+ * one and why. Assembling the evidence around that judgement does not, and used
+ * to be a contract the skill asked an agent to fill in from four other files by
+ * hand.
+ */
+export declare const SELECT_USAGE: string;
+export declare const runSelectCommand: (runDirArgument: string | undefined, flags: CliFlags) => Promise<void>;
+//# sourceMappingURL=cli-select-command.d.ts.map

package/dist/cli-select-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-select-command.d.ts","sourceRoot":"","sources":["../src/cli-select-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAQ/D;;;;;;;GAOG;AAEH,eAAO,MAAM,YAAY,QAC4D,CAAC;AAWtF,eAAO,MAAM,gBAAgB,GAC3B,gBAAgB,MAAM,GAAG,SAAS,EAClC,OAAO,QAAQ,KACd,OAAO,CAAC,IAAI,CA8Cd,CAAC"}

package/dist/cli-select-command.js

@@ -0,0 +1,66 @@
+import { stringFlag } from './cli-arguments.js';
+import { draftPaths, readDraftRecord } from './draft-workspace.js';
+import { buildSelectionRecord, readSelectionRecord, writeSelectionRecord, } from './selection-record.js';
+/**
+ * `12ui select` — the choice, recorded.
+ *
+ * The judgement stays the model's: it has to look at four images and say which
+ * one and why. Assembling the evidence around that judgement does not, and used
+ * to be a contract the skill asked an agent to fill in from four other files by
+ * hand.
+ */
+export const SELECT_USAGE = 'Usage: 12ui select <run-dir> --winner <id> --reason <text>'
+    + ' [--recommended <id>] [--recommendation-source <text>] [--reject <id>=<reason>]';
+/** `--reject B=too generic --reject C=illegible headline` */
+const parseRejections = (flags) => {
+    const raw = stringFlag(flags, 'reject');
+    if (!raw)
+        return {};
+    const separator = raw.indexOf('=');
+    if (separator <= 0)
+        throw new Error('--reject must be <candidate-id>=<reason>');
+    return { [raw.slice(0, separator).trim()]: [raw.slice(separator + 1).trim()] };
+};
+export const runSelectCommand = async (runDirArgument, flags) => {
+    if (!runDirArgument)
+        throw new Error(SELECT_USAGE);
+    const winner = stringFlag(flags, 'winner')?.trim();
+    const reason = stringFlag(flags, 'reason')?.trim();
+    if (!winner || !reason)
+        throw new Error(SELECT_USAGE);
+    const paths = draftPaths(runDirArgument);
+    const draft = await readDraftRecord(paths.draftRecord);
+    if (!draft) {
+        throw new Error(`No draft run in ${paths.runDir} — there is nothing to select from, and nothing has failed.`
+            + ' Start one with `12ui draft --query "<product, audience, surface, goal, personality>"`.');
+    }
+    const existing = await readSelectionRecord(paths.selection);
+    if (existing) {
+        throw new Error(`A selection already exists at ${paths.selection}: candidate ${existing.winner}. Read it`
+            + ' rather than choosing again, or start a new draft to explore other directions.');
+    }
+    const recommended = stringFlag(flags, 'recommended')?.trim();
+    const record = await buildSelectionRecord({
+        draft,
+        winner,
+        reason,
+        recommendation: {
+            candidateId: recommended ?? null,
+            source: recommended ? stringFlag(flags, 'recommendation-source')?.trim() ?? 'run' : null,
+        },
+        rejectionReasons: parseRejections(flags),
+    });
+    await writeSelectionRecord(paths.selection, record);
+    console.log(JSON.stringify({
+        runDir: paths.runDir,
+        selection: paths.selection,
+        winner: record.winner,
+        winnerPath: record.candidates.find((candidate) => candidate.id === record.winner)?.path,
+        selectionSource: record.selectionSource,
+        nextAction: `Convert the winner alone with \`12ui convert ${paths.candidatesDir}/${record.winner}.png`
+            + ' --export html`, or grow the whole surface with'
+            + ` \`12ui branch execute ${paths.runDir} --concept "<what the rest must cover>"`
+            + ' --scope page|site --convert html`.',
+    }, null, 2));
+};
+//# sourceMappingURL=cli-select-command.js.map

package/dist/cli-select-command.js.map

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

package/dist/cli.js

@@ -1,19 +1,28 @@
 #!/usr/bin/env node
 import { readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { materializeConversionArtifacts } from './artifact-materializer.js';
 import { booleanFlag, parseCliArguments, stringFlag, } from './cli-arguments.js';
 import { runAuthCommand } from './cli-auth-command.js';
+import { runBranchCommand } from './cli-branch-command.js';
 import { CLI_CAPABILITIES } from './cli-capabilities.js';
 import { runCliCommand } from './cli-cli-command.js';
 import { runCorpusCommand } from './cli-corpus-command.js';
 import { runExportCommand } from './cli-export-command.js';
-import { runImageBatchCommand } from './cli-image-batch-command.js';
+import { runImageBatchCommand, runImageBatchStatusCommand, } from './cli-image-batch-command.js';
 import { runImageCommand } from './cli-image-command.js';
+import { runCreateCommand } from './cli-create-command.js';
+import { runPackageCommand } from './cli-package-command.js';
+import { PACKAGE_MANIFEST_TEMPLATE_NOTES, renderPackageManifestTemplate, } from './package-manifest-template.js';
 import { runSkillCommand } from './cli-skill-command.js';
 import { isConversionModel } from './conversion-models.js';
 import { TwelveUiConversionClient, } from './conversion-client.js';
-import { createProgressReporter, durationHint } from './cli-progress.js';
+import { detachBranchRun, detachImageBatch } from './cli-detach.js';
+import { runDraftCommand, runDraftStatusCommand } from './cli-draft-command.js';
+import { runSelectCommand } from './cli-select-command.js';
+import { resolveBranchDirectory } from './cli-branch-command.js';
+import { CONVERSION_DURATION_HINTS, OPERATION_DURATION_HINTS, createProgressReporter, durationHint, nextActionLine, } from './cli-progress.js';
 import { CONVERSION_OUTPUTS, isConversionOutput } from './conversion-outputs.js';
 import { readConversionConfig } from './config.js';
 import { classifyLocalConversionInput, createInputForLocalFile, defaultConversionOutputPath, } from './local-conversion-input.js';
@@ -37,10 +46,23 @@ const usage = (exitCode = 1) => {
   12ui corpus inspire --query <text>|--query-file <file> --out-dir <directory> [--mode direct|balanced|adventurer] [--count <1-48>] [--reference-image <png|jpeg|webp>] [--idempotency-key <key>] [--origin <url>] [--api-key <key>]
   12ui corpus resume --out-dir <directory> [--origin <url>] [--api-key <key>]
   12ui image generate --prompt <text>|--prompt-file <file> --reference <file> --out <file.png> [--aspect landscape|portrait|square] [--reference-mode inspiration|preserve-structure] [--provider auto|codex|openai] --project-root <directory> --idempotency-key <key>
-  12ui image generate-batch --manifest <batch.json> [--resume]
+  12ui draft --query <text> [--redesign-source <png>] [--mode exploratory|reskin] [--aspect landscape|portrait|square] [--provider auto|codex|openai] [--project-root <directory>] [--wait] [--quiet] [--origin <url>] [--api-key <key>]
+  12ui draft status <run-dir> [--json]
+  12ui select <run-dir> --winner <id> --reason <text> [--recommended <id>] [--recommendation-source <text>] [--reject <id>=<reason>]
+  12ui create claim --concept <text>|--concept-file <file> --candidates <json>|@<file> [--aspect landscape|portrait|square] [--mode inspiration|preserve-structure] [--reference-image <png|jpeg|webp>] [--idempotency-key <key>] [--origin <url>] [--api-key <key>]
+  12ui create dispatch <run-id> [--slot <a,b,...>] [--quiet] [--origin <url>] [--api-key <key>]
+  12ui create status <run-id> [--json] [--origin <url>] [--api-key <key>]
+  12ui create download <run-id> --out-dir <directory> [--slot <a,b,...>] [--origin <url>] [--api-key <key>]
+  12ui image generate-batch --manifest <batch.json> [--resume] [--wait] [--quiet]
+  12ui image batch-status --manifest <batch.json> [--json]
+  12ui branch execute <run-dir> --concept <text>|--concept-file <file> --scope page|site [--convert html] [--convert-model fast|standard|pro] [--convert-quality standard|pro] [--winner-image <file>|--winner-run <crt-id> --winner-slot <slot>] [--source-conversion-id <id>] [--max-screens <n>] [--idempotency-key <key>] [--out-dir <directory>] [--resume] [--dry-run] [--wait] [--quiet] [--origin <url>] [--api-key <key>]
+  12ui branch resume <run-dir> [--quiet] [--origin <url>] [--api-key <key>]
+  12ui branch status <run-dir> [--json] [--origin <url>] [--api-key <key>]
   12ui capabilities [--json]
   12ui convert <image.png|jpg|webp|layerdoc.json> --output ${outputs} [--model fast|standard|pro] [--width <px>] [--export html] [--export-quality standard|pro] [--export-out <file>] [--responsive-quality standard|pro] [--profile <json|file>] [--out <file>] [--detach] [--quiet] [--timeout-ms <ms>] [--idempotency-key <key>] [--origin <url>] [--api-key <key>]
-  12ui export <source-conversion-id> --output <comma-separated-formats> --out-dir <directory> --idempotency-key <key> [--responsive-quality standard|pro] [--web-profile <json|file>] [--app-profile <json|file>] [--timeout-ms <ms>] [--origin <url>] [--api-key <key>]
+  12ui convert package --manifest <package.json> --out-dir <directory> [--idempotency-key <key>] [--timeout-ms <ms>] [--wait] [--quiet] [--origin <url>] [--api-key <key>]
+  12ui convert package --template
+  12ui export <source-conversion-id> --output <comma-separated-formats> --out-dir <directory> [--idempotency-key <key>] [--responsive-quality standard|pro] [--web-profile <json|file>] [--app-profile <json|file>] [--timeout-ms <ms>] [--origin <url>] [--api-key <key>]
   12ui resume <conversion-id> --output ${outputs} --out <file> [--timeout-ms <ms>] [--origin <url>] [--api-key <key>]
   12ui mcp [--origin <url>] [--api-key <key>]
   12ui --version
@@ -50,9 +72,23 @@ export runs alongside the conversion, so the pair finishes in about the time of
 the conversion alone (~5m) instead of ~8m. Progress goes to stderr; --quiet
 silences it.
 
+\`branch execute\`, \`branch resume\` and \`image generate-batch\` START the work and
+return: the run continues in its own process group and survives the shell that
+launched it. Follow it with \`12ui branch status --out-dir <dir>\` or
+\`12ui image batch-status --manifest <file>\`; both always report what is moving
+and what to do next. Add --wait to block in this shell instead. Never list an
+output directory to decide whether work is still running.
+
 Omit --client to discover and target every supported CLI installation.`);
     process.exit(exitCode);
 };
+/** This file, as the worker re-executes it. */
+const CLI_PATH = fileURLToPath(import.meta.url);
+/**
+ * Long dispatches detach by default. `--wait` keeps the work in this shell for
+ * a human at a terminal; `--dry-run` never starts anything to detach from.
+ */
+const detaches = (flags) => (!booleanFlag(flags, 'wait') && !booleanFlag(flags, 'dry-run'));
 const parseTimeoutMs = (value) => {
     if (value === undefined)
         return undefined;
@@ -108,6 +144,21 @@ const printVersion = async () => {
 };
 const runConversionCommand = async (command, flags) => {
     const verb = command[0];
+    // The hosted candidate API as commands: claim, dispatch, status, download.
+    if (verb === 'create') {
+        await runCreateCommand(command, flags);
+        return;
+    }
+    // Ordered viewports of one page are ONE package conversion, not N converts.
+    if (verb === 'convert' && command[1] === 'package') {
+        if (booleanFlag(flags, 'template')) {
+            process.stderr.write(`${PACKAGE_MANIFEST_TEMPLATE_NOTES}\n`);
+            process.stdout.write(renderPackageManifestTemplate());
+            return;
+        }
+        await runPackageCommand(flags);
+        return;
+    }
     const config = readConversionConfig({
         origin: stringFlag(flags, 'origin'),
         apiKey: stringFlag(flags, 'api-key'),
@@ -116,7 +167,11 @@ const runConversionCommand = async (command, flags) => {
         await startMcpServer({ config });
         return;
     }
-    const outputValue = stringFlag(flags, 'output');
+    // `12ui convert <image> --export html` is the whole command for a single
+    // screen. The export is derived from a LayerDoc conversion, so asking for the
+    // output as well is asking the caller to restate the only value it can have.
+    const outputValue = stringFlag(flags, 'output')
+        ?? (stringFlag(flags, 'export') !== undefined ? 'layerdoc' : undefined);
     const output = isConversionOutput(outputValue) ? outputValue : usage();
     const client = new TwelveUiConversionClient(config);
     const timeoutMs = parseTimeoutMs(stringFlag(flags, 'timeout-ms'));
@@ -236,19 +291,34 @@ const runConversionCommand = async (command, flags) => {
         waitSeconds: detach ? 0 : 20,
     });
     if (detach) {
+        const resumeCommand = `12ui resume ${created.id} --output ${output} --out <file>`;
         console.log(JSON.stringify({
             id: created.id,
             status: created.status,
             output: created.output,
             ...(created.export ? { export: created.export } : {}),
             expiresAt: created.expires_at,
+            // A detached operation is the one case with nothing streaming, so the
+            // response has to say how long it takes and how to collect it.
+            nextAction: nextActionLine({
+                what: 'A conversion',
+                typicalSeconds: CONVERSION_DURATION_HINTS[created.export ? 'fused' : 'convert'],
+                statusCommand: resumeCommand,
+                waitHint: 'which blocks until it finishes and writes the result',
+            }),
         }, null, 2));
         return;
     }
     const exportOperationId = created.export?.conversion_id ?? null;
     if (!quiet) {
         process.stderr.write(`12ui convert ${created.id}${exportOperationId ? ` (+ export ${exportOperationId})` : ''}`
-            + ` — ${durationHint(exportOperationId ? 'fused' : 'convert')}\n`);
+            + ` — ${durationHint(exportOperationId ? 'fused' : 'convert')}\n`
+            + `${nextActionLine({
+                what: 'A conversion',
+                typicalSeconds: CONVERSION_DURATION_HINTS[exportOperationId ? 'fused' : 'convert'],
+                statusCommand: `12ui resume ${created.id} --output ${output} --out <file>`,
+                waitHint: 'or leave this command running, which is what --wait already does by default',
+            })}\n`);
     }
     const reporter = createProgressReporter({ label: 'convert', quiet });
     let operation;
@@ -333,12 +403,75 @@ const main = async () => {
         return;
     }
     if (command[0] === 'image') {
-        if (command[1] === 'generate-batch')
+        if (command[1] === 'generate-batch') {
+            if (detaches(flags)) {
+                const manifest = stringFlag(flags, 'manifest')?.trim();
+                if (!manifest)
+                    throw new Error('--manifest is required');
+                console.log(JSON.stringify(await detachImageBatch({
+                    cliPath: CLI_PATH,
+                    argv: process.argv.slice(2),
+                    manifestPath: path.resolve(manifest),
+                    typicalSeconds: OPERATION_DURATION_HINTS.imageBatch,
+                }), null, 2));
+                return;
+            }
             await runImageBatchCommand(flags);
+        }
+        else if (command[1] === 'batch-status')
+            await runImageBatchStatusCommand(flags);
         else
             await runImageCommand(command[1], flags);
         return;
     }
+    if (command[0] === 'draft') {
+        if (command[1] === 'status') {
+            console.log(JSON.stringify(await runDraftStatusCommand(command[2], flags), null, 2));
+            return;
+        }
+        await runDraftCommand(flags, {
+            generate: async ({ manifestPath, detach }) => {
+                if (!detach)
+                    return runImageBatchCommand({ ...flags, manifest: manifestPath });
+                return console.log(JSON.stringify(await detachImageBatch({
+                    cliPath: CLI_PATH,
+                    argv: ['image', 'generate-batch', '--manifest', manifestPath],
+                    manifestPath,
+                    typicalSeconds: OPERATION_DURATION_HINTS.imageBatch,
+                }), null, 2));
+            },
+        });
+        return;
+    }
+    if (command[0] === 'select') {
+        await runSelectCommand(command[1], flags);
+        return;
+    }
+    if (command[0] === 'branch') {
+        // `branch execute <run-dir>` — the directory `12ui draft` printed.
+        const runDirArgument = command[2]?.trim();
+        if ((command[1] === 'execute' || command[1] === 'resume') && detaches(flags)) {
+            const resolved = await resolveBranchDirectory({
+                ...(stringFlag(flags, 'out-dir')?.trim()
+                    ? { outDirFlag: stringFlag(flags, 'out-dir').trim() }
+                    : {}),
+                ...(runDirArgument ? { runDirArgument } : {}),
+            });
+            console.log(JSON.stringify(await detachBranchRun({
+                cliPath: CLI_PATH,
+                argv: process.argv.slice(2),
+                outDir: resolved.branchDir,
+                typicalSeconds: stringFlag(flags, 'scope') === 'site'
+                    ? OPERATION_DURATION_HINTS.branchSite
+                    : OPERATION_DURATION_HINTS.branchPage,
+            }), null, 2));
+            return;
+        }
+        await runBranchCommand(command[1], flags, {
+            ...(runDirArgument ? { runDirArgument } : {}),
+        });
+        return;
+    }
     if (command[0] === 'export') {
         await runExportCommand(command[1], flags);
         return;