@12ui/design 0.2.13 → 0.2.15

package/dist/cli-package-command.js

@@ -0,0 +1,128 @@
+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_MANIFEST_TEMPLATE_NOTES, renderPackageManifestTemplate, } from './package-manifest-template.js';
+import { PACKAGE_RESULT_FILENAME, submitConversionPackage, writePackageResultRecord, } from './package-submission.js';
+import { createPackageProgressReporter, 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.');
+};
+/**
+ * `12ui convert package --template` prints the starting manifest and returns
+ * before any config read or network call, so it works with no credentials.
+ * Guidance goes to stderr and only the JSON reaches stdout, which is what makes
+ * `--template > package.json` write a file that parses.
+ *
+ * Returns false when the caller did not ask for the template, so the dispatcher
+ * falls through to the real submission. This lives beside the command rather
+ * than inline in the dispatcher so the argv path is reachable from a test.
+ */
+export const runPackageTemplateCommand = (flags) => {
+    if (!booleanFlag(flags, 'template'))
+        return false;
+    process.stderr.write(`${PACKAGE_MANIFEST_TEMPLATE_NOTES}\n`);
+    process.stdout.write(renderPackageManifestTemplate());
+    return true;
+};
+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 reportProgress = createPackageProgressReporter({
+        write: (line) => { process.stderr.write(`${line}\n`); },
+        elapsed: () => formatDuration((Date.now() - startedAt) / 1000),
+    });
+    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) => { reportProgress(undefined, event); },
+    });
+    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,9 +20,146 @@ 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;
+    /**
+     * The screen-generation phase of a whole run. Viewport chains run in parallel
+     * across pages, so it tracks the depth of ONE page's chain rather than the
+     * screen count: measured median 3m22 over 49 four-page runs.
+     */
+    readonly branchScreenPhase: 202;
+    /** One branch page as one package. Measured median 2m10 over the same runs. */
+    readonly branchPackage: 130;
+    /** Downloads, the sentinel, and the final records. */
+    readonly branchFinalize: 15;
+    /**
+     * Whole runs, derived from the phases above by `branchRunEstimateSeconds` at
+     * the default page concurrency: one page for `--scope page`, four for
+     * `--scope site`. A test holds them to that derivation.
+     */
+    readonly branchPage: 362;
+    readonly branchSite: 492;
+    /** One `12ui convert package` submission, whose page count is not known here. */
+    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;
+};
+/**
+ * Three pages convert at a time. Each holds two or three viewport children on
+ * the server, so three pages sit just under the account's ~10 active
+ * conversions: a brief queue at the admission boundary is visible in the
+ * package's own published progress rather than looking like a stall. It lives
+ * beside the duration hints because the run estimate is a function of it.
+ */
+export declare const BRANCH_PAGE_CONCURRENCY_DEFAULT = 3;
+/**
+ * A whole branch run, decomposed rather than guessed: the claim, the screen
+ * phase, the page conversions — which run `concurrency` at a time and start as
+ * each page's own screens land — and the records at the end.
+ *
+ * The floor is the run whose conversions all overlap generation except the last
+ * one; the ceiling is the run where none of them do. Quoting the pair is what
+ * keeps a caller from reading the slower half of a normal distribution as a
+ * stall.
+ */
+export declare const branchRunEstimateSeconds: (args: {
+    pages: number;
+    concurrency: number;
+    /** A run that stops at downloaded PNGs converts nothing. */
+    convert?: boolean;
+}) => {
+    floor: number;
+    ceiling: number;
+};
+/** What `--scope site` plans in practice, for an estimate made before the plan. */
+export declare const BRANCH_TYPICAL_SITE_PAGES = 4;
+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 PackageStageProgress = {
+    stage: string;
+    percent?: number;
+    completed?: number;
+    total?: number;
+    running?: number;
+    stageSince?: string;
+    pagesAvailable?: number;
+};
+/**
+ * `converting viewports 32% — 1 of 3 viewports, 2 running, 1m 20s in stage`.
+ *
+ * A percent alone is the number that stalls: a phase whose children each take
+ * minutes reports the same figure for minutes, and an agent polling it decides
+ * the run is wedged. The counts and the time in phase are facts that keep
+ * advancing while the percent does not. Every one of them is optional, because
+ * a server that predates them answers without them and a renderer that demanded
+ * them would print nothing at all.
+ */
+export declare const packageProgressLine: (progress: PackageStageProgress, now?: number) => string;
+/**
+ * One writer for every package progress line, deduplicated per page.
+ *
+ * The poll revalidates every few seconds and mostly sees the same facts;
+ * repeating an unchanged line is how a stream stops reading as motion. When the
+ * server publishes its time in phase the line advances on its own, which is the
+ * point — a percent that has not moved is exactly when a caller needs to see
+ * that something still is.
+ */
+export declare const createPackageProgressReporter: (args: {
+    write: (line: string) => void;
+    elapsed: () => string;
+    now?: () => number;
+}) => ((pageId: string | undefined, progress: PackageStageProgress) => void);
 export type ProgressReporter = {
     onProgress: (operation: ConversionOperation) => void;
     /** Final line for a finished operation. */

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;;;;OAIG;;IAEH,+EAA+E;;IAE/E,sDAAsD;;IAEtD;;;;OAIG;;;IAGH,iFAAiF;;IA/CjF,0DAA0D;;IAE1D,8EAA8E;;IAE9E;;;;OAIG;;CAyCK,CAAC;AAEX;;;;;;GAMG;AACH,eAAO,MAAM,+BAA+B,IAAI,CAAC;AAEjD;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,KAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAUnC,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,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;AA0BF,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,MAAsC,CAAC;AAUlF,MAAM,MAAM,oBAAoB,GAAG;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC9B,UAAU,oBAAoB,EAC9B,MAAK,MAAmB,KACvB,MAeF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,GAAI,MAAM;IAClD,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,OAAO,EAAE,MAAM,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,KAAG,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,oBAAoB,KAAK,IAAI,CAQxE,CAAC;AAEF,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,74 @@ 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,
+    /**
+     * The screen-generation phase of a whole run. Viewport chains run in parallel
+     * across pages, so it tracks the depth of ONE page's chain rather than the
+     * screen count: measured median 3m22 over 49 four-page runs.
+     */
+    branchScreenPhase: 202,
+    /** One branch page as one package. Measured median 2m10 over the same runs. */
+    branchPackage: 130,
+    /** Downloads, the sentinel, and the final records. */
+    branchFinalize: 15,
+    /**
+     * Whole runs, derived from the phases above by `branchRunEstimateSeconds` at
+     * the default page concurrency: one page for `--scope page`, four for
+     * `--scope site`. A test holds them to that derivation.
+     */
+    branchPage: 362,
+    branchSite: 492,
+    /** One `12ui convert package` submission, whose page count is not known here. */
+    package: 360,
+};
+/**
+ * Three pages convert at a time. Each holds two or three viewport children on
+ * the server, so three pages sit just under the account's ~10 active
+ * conversions: a brief queue at the admission boundary is visible in the
+ * package's own published progress rather than looking like a stall. It lives
+ * beside the duration hints because the run estimate is a function of it.
+ */
+export const BRANCH_PAGE_CONCURRENCY_DEFAULT = 3;
+/**
+ * A whole branch run, decomposed rather than guessed: the claim, the screen
+ * phase, the page conversions — which run `concurrency` at a time and start as
+ * each page's own screens land — and the records at the end.
+ *
+ * The floor is the run whose conversions all overlap generation except the last
+ * one; the ceiling is the run where none of them do. Quoting the pair is what
+ * keeps a caller from reading the slower half of a normal distribution as a
+ * stall.
+ */
+export const branchRunEstimateSeconds = (args) => {
+    const base = OPERATION_DURATION_HINTS.branchClaim
+        + OPERATION_DURATION_HINTS.branchScreenPhase
+        + OPERATION_DURATION_HINTS.branchFinalize;
+    if (args.convert === false)
+        return { floor: base, ceiling: base };
+    const waves = Math.max(1, Math.ceil(Math.max(1, args.pages) / Math.max(1, args.concurrency)));
+    return {
+        floor: base + OPERATION_DURATION_HINTS.branchPackage,
+        ceiling: base + waves * OPERATION_DURATION_HINTS.branchPackage,
+    };
+};
+/** What `--scope site` plans in practice, for an estimate made before the plan. */
+export const BRANCH_TYPICAL_SITE_PAGES = 4;
 export const formatDuration = (seconds) => {
     const whole = Math.max(0, Math.round(seconds));
     if (whole < 90)
@@ -27,6 +95,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',
@@ -45,8 +143,66 @@ const STAGE_LABELS = {
     static_export: 'rendering export',
     project_export: 'building project',
     publish: 'publishing',
+    // The package coordinator's own phases.
+    convert_viewports: 'converting viewports',
+    compose_pages: 'composing pages',
+    export_pages: 'exporting pages',
 };
 export const stageLabel = (stage) => STAGE_LABELS[stage] ?? stage;
+/** What the current package phase counts. */
+const STAGE_UNITS = {
+    convert_viewports: 'viewport',
+    compose_pages: 'page',
+    export_pages: 'page',
+    publish: 'page',
+};
+/**
+ * `converting viewports 32% — 1 of 3 viewports, 2 running, 1m 20s in stage`.
+ *
+ * A percent alone is the number that stalls: a phase whose children each take
+ * minutes reports the same figure for minutes, and an agent polling it decides
+ * the run is wedged. The counts and the time in phase are facts that keep
+ * advancing while the percent does not. Every one of them is optional, because
+ * a server that predates them answers without them and a renderer that demanded
+ * them would print nothing at all.
+ */
+export const packageProgressLine = (progress, now = Date.now()) => {
+    const head = progress.percent === undefined
+        ? stageLabel(progress.stage)
+        : `${stageLabel(progress.stage)} ${progress.percent}%`;
+    const unit = STAGE_UNITS[progress.stage];
+    const facts = [];
+    if (progress.total !== undefined) {
+        facts.push(`${progress.completed ?? 0} of ${progress.total}${unit ? ` ${unit}${progress.total === 1 ? '' : 's'}` : ''}`);
+    }
+    if (progress.running !== undefined)
+        facts.push(`${progress.running} running`);
+    const inStage = secondsSince(progress.stageSince, now);
+    if (inStage !== undefined)
+        facts.push(`${formatDuration(inStage)} in stage`);
+    if (progress.pagesAvailable)
+        facts.push(`${progress.pagesAvailable} page(s) ready`);
+    return facts.length === 0 ? head : `${head} — ${facts.join(', ')}`;
+};
+/**
+ * One writer for every package progress line, deduplicated per page.
+ *
+ * The poll revalidates every few seconds and mostly sees the same facts;
+ * repeating an unchanged line is how a stream stops reading as motion. When the
+ * server publishes its time in phase the line advances on its own, which is the
+ * point — a percent that has not moved is exactly when a caller needs to see
+ * that something still is.
+ */
+export const createPackageProgressReporter = (args) => {
+    const last = new Map();
+    return (pageId, progress) => {
+        const line = packageProgressLine(progress, (args.now ?? Date.now)());
+        if (last.get(pageId ?? '') === line)
+            return;
+        last.set(pageId ?? '', line);
+        args.write(`[${args.elapsed()}] package${pageId ? ` ${pageId}` : ''}: ${line}`);
+    };
+};
 /**
  * Streams stage progress to stderr, one line per distinct stage/percent.
  *

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":"AAEA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,0DAA0D;IAC1D,OAAO,EAAE,GAAG;IACZ,8EAA8E;IAC9E,MAAM,EAAE,GAAG;IACX;;;;OAIG;IACH,KAAK,EAAE,GAAG;CACF,CAAC;AAIX;;;;GAIG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,GAAG,yBAAyB;IAC5B,6DAA6D;IAC7D,cAAc,EAAE,EAAE;IAClB,6CAA6C;IAC7C,UAAU,EAAE,EAAE;IACd,kEAAkE;IAClE,WAAW,EAAE,EAAE;IACf,oEAAoE;IACpE,YAAY,EAAE,EAAE;IAChB,kBAAkB,EAAE,GAAG;IACvB;;;;OAIG;IACH,iBAAiB,EAAE,GAAG;IACtB,+EAA+E;IAC/E,aAAa,EAAE,GAAG;IAClB,sDAAsD;IACtD,cAAc,EAAE,EAAE;IAClB;;;;OAIG;IACH,UAAU,EAAE,GAAG;IACf,UAAU,EAAE,GAAG;IACf,iFAAiF;IACjF,OAAO,EAAE,GAAG;CACJ,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC;AAEjD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,IAKxC,EAAsC,EAAE;IACvC,MAAM,IAAI,GAAG,wBAAwB,CAAC,WAAW;UAC7C,wBAAwB,CAAC,iBAAiB;UAC1C,wBAAwB,CAAC,cAAc,CAAC;IAC5C,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK;QAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAClE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAC9F,OAAO;QACL,KAAK,EAAE,IAAI,GAAG,wBAAwB,CAAC,aAAa;QACpD,OAAO,EAAE,IAAI,GAAG,KAAK,GAAG,wBAAwB,CAAC,aAAa;KAC/D,CAAC;AACJ,CAAC,CAAC;AAEF,mFAAmF;AACnF,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC;AAI3C,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,OAAe,EAAU,EAAE;IACxD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;IAC/C,IAAI,KAAK,GAAG,EAAE;QAAE,OAAO,GAAG,KAAK,GAAG,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC;IACvC,MAAM,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;IACxB,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,IAAI,GAAG,CAAC;AAC7D,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAgC,EAAU,EAAE,CAAC,CACxE,gBAAgB,cAAc,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,EAAE,CAClE,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,cAAsB,EACtB,cAAsB,EACd,EAAE,CAAC,CACX,GAAG,cAAc,CAAC,cAAc,CAAC,cAAc,cAAc,CAAC,cAAc,CAAC,UAAU,CACxF,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,IAM9B,EAAU,EAAE;IACX,MAAM,UAAU,GAAG,cAAc,CAAC,IAAI,CAAC,iBAAiB,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,cAAc,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/G,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,IAAI,8DAA8D,CAAC;IAC7F,OAAO,GAAG,IAAI,CAAC,IAAI,0BAA0B,cAAc,CAAC,IAAI,CAAC,cAAc,CAAC,GAAG;UAC/E,mBAAmB,UAAU,WAAW,IAAI,CAAC,aAAa,OAAO,IAAI,GAAG,CAAC;AAC/E,CAAC,CAAC;AAEF,oFAAoF;AACpF,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,MAAoE,EAC5D,EAAE,CAAC,MAAM;KAChB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;KAC1F,IAAI,CAAC,IAAI,CAAC,CAAC;AAEd,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,GAAuB,EAAE,GAAW,EAAsB,EAAE;IACvF,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAChC,OAAO,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACpF,CAAC,CAAC;AAEF,oEAAoE;AACpE,MAAM,YAAY,GAA2B;IAC3C,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,WAAW;IACpB,kBAAkB,EAAE,mBAAmB;IACvC,WAAW,EAAE,sBAAsB;IACnC,wEAAwE;IACxE,oEAAoE;IACpE,iBAAiB,EAAE,mBAAmB;IACtC,oBAAoB,EAAE,sBAAsB;IAC5C,YAAY,EAAE,uBAAuB;IACrC,IAAI,EAAE,eAAe;IACrB,oBAAoB,EAAE,kCAAkC;IACxD,kBAAkB,EAAE,+BAA+B;IACnD,kBAAkB,EAAE,eAAe;IACnC,aAAa,EAAE,kBAAkB;IACjC,cAAc,EAAE,kBAAkB;IAClC,OAAO,EAAE,YAAY;IACrB,wCAAwC;IACxC,iBAAiB,EAAE,sBAAsB;IACzC,aAAa,EAAE,iBAAiB;IAChC,YAAY,EAAE,iBAAiB;CAChC,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC;AAElF,6CAA6C;AAC7C,MAAM,WAAW,GAA2B;IAC1C,iBAAiB,EAAE,UAAU;IAC7B,aAAa,EAAE,MAAM;IACrB,YAAY,EAAE,MAAM;IACpB,OAAO,EAAE,MAAM;CAChB,CAAC;AAYF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,QAA8B,EAC9B,MAAc,IAAI,CAAC,GAAG,EAAE,EAChB,EAAE;IACV,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,KAAK,SAAS;QACzC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC;QAC5B,CAAC,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,OAAO,GAAG,CAAC;IACzD,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACjC,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,SAAS,IAAI,CAAC,OAAO,QAAQ,CAAC,KAAK,GACxD,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,QAAQ,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,OAAO,UAAU,CAAC,CAAC;IAC9E,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IACvD,IAAI,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7E,IAAI,QAAQ,CAAC,cAAc;QAAE,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,cAAc,gBAAgB,CAAC,CAAC;IACpF,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;AACrE,CAAC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,IAI7C,EAA0E,EAAE;IAC3E,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE;QAC1B,MAAM,IAAI,GAAG,mBAAmB,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACrE,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,KAAK,IAAI;YAAE,OAAO;QAC5C,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,YAAY,MAAM,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IAClF,CAAC,CAAC;AACJ,CAAC,CAAC;AAQF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,IAKtC,EAAoB,EAAE;IACrB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,IAAY,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACvF,MAAM,SAAS,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IAC3C,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,MAAM,OAAO,GAAG,GAAW,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5F,OAAO;QACL,UAAU,EAAE,CAAC,SAAS,EAAE,EAAE;YACxB,IAAI,IAAI,CAAC,KAAK;gBAAE,OAAO;YACvB,MAAM,KAAK,GAAG,SAAS,CAAC,QAAQ,EAAE,KAAK,IAAI,SAAS,CAAC,MAAM,CAAC;YAC5D,MAAM,OAAO,GAAG,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC;YAC5C,MAAM,IAAI,GAAG,OAAO,KAAK,SAAS;gBAChC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,KAAK,UAAU,CAAC,KAAK,CAAC,EAAE;gBACvC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,KAAK,UAAU,CAAC,KAAK,CAAC,IAAI,OAAO,GAAG,CAAC;YACtD,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO;YAC1B,IAAI,GAAG,IAAI,CAAC;YACZ,KAAK,CAAC,IAAI,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QAClC,CAAC;QACD,IAAI,EAAE,CAAC,SAAS,EAAE,EAAE;YAClB,IAAI,IAAI,CAAC,KAAK;gBAAE,OAAO;YACvB,KAAK,CAAC,IAAI,OAAO,EAAE,KAAK,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;QAC7D,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}

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