@12ui/design 0.2.70 → 0.2.72

package/README.md

@@ -99,6 +99,11 @@ keep their backend; external requires the separate key before inference starts.
 Native does not imply zero cost or a known image model.
 The CLI owns runtime setup; the skill contains workflow guidance.
 
+The skill's `scene.md` guide rebuilds a design image as a live Three.js scene
+with the local `12ui scene` tools (`12ui scene --help`): camera solve, placement,
+a starter harness with a bundled three.js, capture with the managed Chromium,
+and review sheets. It needs no account and makes no network request.
+
 `improve --apply` captures the URL and edits the actual repository. Without a
 target it drafts candidates, stops for an explicit choice, then applies that
 choice locally. Without `--apply`, the existing hosted implementation-kit behavior

package/SKILL.md

@@ -28,7 +28,7 @@ dispatch paid work when it is absent, rejected, or times out.
 Use `12ui` when it is available on `PATH`. Otherwise invoke the pinned CLI that
 the plugin's `open-design.json` MCP entry uses:
 
-    npx -y @12ui/design@0.2.70 <command> ...
+    npx -y @12ui/design@0.2.72 <command> ...
 
 Run `12ui auth status --json` (or its pinned `npx` equivalent) before the paid
 preflight. A desktop user can authenticate with `12ui auth login`; a headless

package/dist/cli-capabilities.d.ts

@@ -24,6 +24,15 @@ export declare const CLI_CAPABILITIES: {
         readonly withoutTarget: "Draft candidates, require an explicit pick, then edit the actual project locally.";
         readonly withoutApply: "Hosted implementation kit; does not edit project source.";
     };
+    /** Local helpers for rebuilding a design image as a live Three.js scene (the 12ui-design skill's scene.md). */
+    readonly localScene: {
+        readonly command: "12ui scene <verb>";
+        readonly verbs: readonly ["init", "solve", "ray", "project", "rect", "serve", "capture", "sheet", "blend", "colors", "rectify"];
+        readonly network: "none";
+        readonly browser: "managed Chromium for capture";
+        readonly skill: "12ui-design";
+        readonly guide: "scene.md";
+    };
     readonly localExport: {
         readonly command: "12ui export <run-dir|output-dir> --output <format> --out-dir <directory>";
         readonly outputs: readonly ["assets", "png", "jpg", "webp", "pdf", "react"];

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

@@ -1 +1 @@
-{"version":3,"file":"cli-capabilities.d.ts","sourceRoot":"","sources":["../src/cli-capabilities.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAuE3B;;;;;OAKG;;;;;;;;;;;IAeH;;;;;;OAMG;;;;;;;QAUD,iFAAiF;;;IAGnF;;;;;;OAMG;;;QAGD,yEAAyE;;;;;QASzE,6EAA6E;;QAE7E,6EAA6E;;;;;;;IAO/E,uEAAuE;;;;;;;;;;;;QAYrE;;;WAGG;;;;;;;;;;;;;;;;;;CAkBG,CAAC"}
+{"version":3,"file":"cli-capabilities.d.ts","sourceRoot":"","sources":["../src/cli-capabilities.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;IA8B3B,+GAA+G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAkD/G;;;;;OAKG;;;;;;;;;;;IAeH;;;;;;OAMG;;;;;;;QAUD,iFAAiF;;;IAGnF;;;;;;OAMG;;;QAGD,yEAAyE;;;;;QASzE,6EAA6E;;QAE7E,6EAA6E;;;;;;;IAO/E,uEAAuE;;;;;;;;;;;;QAYrE;;;WAGG;;;;;;;;;;;;;;;;;;CAkBG,CAAC"}

package/dist/cli-capabilities.js

@@ -5,6 +5,7 @@ import { CLI_CONVERSION_OUTPUTS, CONVERSION_OUTPUT_MEDIA_TYPES, } from './conver
 import { MAX_IMAGE_OUTPUT_WIDTH } from './image-output-width.js';
 import { RESPONSIVE_CONVERSION_QUALITIES } from './responsive-quality.js';
 import { RUN_JOURNAL_FILENAME, RUN_JOURNAL_VERSION } from './run-journal.js';
+import { SCENE_VERBS } from './scene/scene-verbs.js';
 export const CLI_CAPABILITIES = {
     inputs: [
         'image/png',
@@ -34,6 +35,15 @@ export const CLI_CAPABILITIES = {
         withoutTarget: 'Draft candidates, require an explicit pick, then edit the actual project locally.',
         withoutApply: 'Hosted implementation kit; does not edit project source.',
     },
+    /** Local helpers for rebuilding a design image as a live Three.js scene (the 12ui-design skill's scene.md). */
+    localScene: {
+        command: '12ui scene <verb>',
+        verbs: SCENE_VERBS,
+        network: 'none',
+        browser: 'managed Chromium for capture',
+        skill: '12ui-design',
+        guide: 'scene.md',
+    },
     localExport: {
         command: '12ui export <run-dir|output-dir> --output <format> --out-dir <directory>',
         outputs: ['assets', 'png', 'jpg', 'webp', 'pdf', 'react'],

package/dist/cli-capabilities.js.map

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

package/dist/cli-conversion-recovery-advice.d.ts

@@ -0,0 +1,35 @@
+import { type ConversionOperation, type TwelveUiConversionClient, type TerminalConversionStatus } from './conversion-client.js';
+import type { TerminalArtifactReport } from './cli-progress.js';
+import { type ObservedConversionStatus } from './conversion-status-contract.js';
+export declare const terminalConversionOperation: (error: unknown) => (ConversionOperation & {
+    status: TerminalConversionStatus;
+}) | null;
+export declare const terminalConversionStatus: (error: unknown) => TerminalConversionStatus | null;
+export declare const conversionRecoveryAdvice: (args: {
+    conversionId: string;
+    terminalStatus: TerminalConversionStatus | null;
+    resumeCommand: string;
+}) => string;
+export type LinkedExportRecoveryState = {
+    id: string;
+    status: ObservedConversionStatus;
+    readError?: string;
+};
+export declare const describeTerminalRecovery: (args: {
+    client: Pick<TwelveUiConversionClient, "getConversion">;
+    error: unknown;
+    conversionId: string;
+    fallbackExportId?: string;
+    resumeCommand: string;
+    parentArtifact?: Pick<TerminalArtifactReport, "name" | "path">;
+    linkedArtifact?: Pick<TerminalArtifactReport, "name" | "path">;
+}) => Promise<{
+    terminalOperation: (ConversionOperation & {
+        status: TerminalConversionStatus;
+    }) | null;
+    terminalStatus: TerminalConversionStatus | null;
+    linkedExport?: LinkedExportRecoveryState;
+    artifacts?: TerminalArtifactReport[];
+    next: string;
+}>;
+//# sourceMappingURL=cli-conversion-recovery-advice.d.ts.map

package/dist/cli-conversion-recovery-advice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-conversion-recovery-advice.d.ts","sourceRoot":"","sources":["../src/cli-conversion-recovery-advice.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC9B,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,iCAAiC,CAAC;AAEzC,eAAO,MAAM,2BAA2B,GACtC,OAAO,OAAO,KACb,CAAC,mBAAmB,GAAG;IAAE,MAAM,EAAE,wBAAwB,CAAA;CAAE,CAAC,GAAG,IAEjE,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAI,OAAO,OAAO,KAAG,wBAAwB,GAAG,IAEpF,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAI,MAAM;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAChD,aAAa,EAAE,MAAM,CAAC;CACvB,KAAG,MASH,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,wBAAwB,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,eAAO,MAAM,wBAAwB,GAAU,MAAM;IACnD,MAAM,EAAE,IAAI,CAAC,wBAAwB,EAAE,eAAe,CAAC,CAAC;IACxD,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;IAC/D,cAAc,CAAC,EAAE,IAAI,CAAC,sBAAsB,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC;CAChE,KAAG,OAAO,CAAC;IACV,iBAAiB,EAAE,CAAC,mBAAmB,GAAG;QAAE,MAAM,EAAE,wBAAwB,CAAA;KAAE,CAAC,GAAG,IAAI,CAAC;IACvF,cAAc,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAChD,YAAY,CAAC,EAAE,yBAAyB,CAAC;IACzC,SAAS,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;CACd,CAwDA,CAAC"}

package/dist/cli-conversion-recovery-advice.js

@@ -0,0 +1,72 @@
+import { ConversionTerminalError, } from './conversion-client.js';
+import { readConversionStatusObservation, } from './conversion-status-contract.js';
+export const terminalConversionOperation = (error) => (error instanceof ConversionTerminalError ? error.operation : null);
+export const terminalConversionStatus = (error) => (terminalConversionOperation(error)?.status ?? null);
+export const conversionRecoveryAdvice = (args) => {
+    if (args.terminalStatus === 'failed') {
+        return `contact 12ui support with conversion ID ${args.conversionId};`
+            + ' resume only collects a purchase and cannot restart a terminal failure';
+    }
+    if (args.terminalStatus === 'expired') {
+        return `conversion ${args.conversionId} has expired; start a new conversion if you still need the result`;
+    }
+    return `${args.resumeCommand}; collection is free until the purchase expires`;
+};
+export const describeTerminalRecovery = async (args) => {
+    const terminalOperation = terminalConversionOperation(args.error);
+    const terminalStatus = terminalOperation?.status ?? null;
+    let linkedExport;
+    if (terminalOperation && terminalOperation.id === args.conversionId) {
+        const exportId = terminalOperation.export?.conversion_id ?? args.fallbackExportId;
+        if (exportId) {
+            const observation = await readConversionStatusObservation(args.client, exportId);
+            linkedExport = {
+                id: exportId,
+                status: observation.status,
+                ...(observation.readError ? { readError: observation.readError.message } : {}),
+            };
+        }
+    }
+    let next = conversionRecoveryAdvice({
+        conversionId: terminalOperation?.id ?? args.conversionId,
+        terminalStatus,
+        resumeCommand: args.resumeCommand,
+    });
+    if (linkedExport) {
+        if (linkedExport.status === 'succeeded' || linkedExport.status === 'queued' || linkedExport.status === 'running') {
+            next += `; linked responsive export ${linkedExport.id} is ${linkedExport.status}`
+                + `; collect it with 12ui resume ${linkedExport.id} --output html --out ${args.linkedArtifact?.path ?? '<file>'}`;
+        }
+        else if (linkedExport.status === 'unknown') {
+            next += `; linked responsive export ${linkedExport.id} could not be read, so its state is unknown`;
+        }
+        else {
+            next += `; linked responsive export ${linkedExport.id} is ${linkedExport.status}`;
+        }
+    }
+    const artifacts = terminalOperation && terminalOperation.id === args.conversionId && args.parentArtifact
+        ? [
+            { ...args.parentArtifact, state: terminalOperation.status },
+            ...(args.linkedArtifact
+                ? [{
+                        ...args.linkedArtifact,
+                        name: args.linkedArtifact.name ?? 'responsive html',
+                        state: !linkedExport || linkedExport.status === 'unknown'
+                            ? 'unknown — linked export was not read'
+                            : ['succeeded', 'queued', 'running'].includes(linkedExport.status)
+                                ? `${linkedExport.status} — not collected`
+                                : linkedExport.status,
+                        ...(linkedExport?.readError ? { note: linkedExport.readError } : {}),
+                    }]
+                : []),
+        ]
+        : undefined;
+    return {
+        terminalOperation,
+        terminalStatus,
+        ...(linkedExport ? { linkedExport } : {}),
+        ...(artifacts ? { artifacts } : {}),
+        next,
+    };
+};
+//# sourceMappingURL=cli-conversion-recovery-advice.js.map

package/dist/cli-conversion-recovery-advice.js.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"cli-convert-command.d.ts","sourceRoot":"","sources":["../src/cli-convert-command.ts"],"names":[],"mappings":"AAKA,OAAO,EAA2B,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AA8B5E,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,iCAAiC,CAAC;AAgBzC,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD;;;;GAIG;AAEH,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,MAAM,GAAG,SAOxD,CAAC;AAqHF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG,MAIpD,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,MAAM;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE;QACb,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,wBAAwB,CAAC;QACjC,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH,KAAG,MAYH,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,sBAAsB,GAAI,MAAM;IAC3C,MAAM,EAAE,wBAAwB,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;CACnB,KAAG,MAMH,CAAC;AAsLF,eAAO,MAAM,oBAAoB,GAC/B,SAAS,SAAS,MAAM,EAAE,EAC1B,OAAO,QAAQ,EACf,SAAS,eAAe,EACxB,eAAc;IACZ,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,CAAC;CACpB,KACL,OAAO,CAAC,IAAI,CA8qBd,CAAC"}
+{"version":3,"file":"cli-convert-command.d.ts","sourceRoot":"","sources":["../src/cli-convert-command.ts"],"names":[],"mappings":"AAKA,OAAO,EAA2B,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAmC5E,OAAO,EAIL,KAAK,wBAAwB,EAC9B,MAAM,iCAAiC,CAAC;AAgBzC,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD;;;;GAIG;AAEH,eAAO,MAAM,cAAc,GAAI,QAAQ,MAAM,KAAG,MAAM,GAAG,SAOxD,CAAC;AAqHF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG,MAIpD,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,MAAM;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE;QACb,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,wBAAwB,CAAC;QACjC,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH,KAAG,MAYH,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,sBAAsB,GAAI,MAAM;IAC3C,MAAM,EAAE,wBAAwB,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;CACnB,KAAG,MAMH,CAAC;AAyLF,eAAO,MAAM,oBAAoB,GAC/B,SAAS,SAAS,MAAM,EAAE,EAC1B,OAAO,QAAQ,EACf,SAAS,eAAe,EACxB,eAAc;IACZ,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,CAAC;CACpB,KACL,OAAO,CAAC,IAAI,CA2xBd,CAAC"}

package/dist/cli-convert-command.js

@@ -8,7 +8,8 @@ import { runConversionDerivation } from './cli-conversion-derivation.js';
 import { CONVERSION_DURATION_HINTS, createLongRunningProgress, } from './cli-progress.js';
 import { refuseUsage, usage, usageRefusal } from './cli-usage.js';
 import { readConversionConfig } from './config.js';
-import { TwelveUiConversionClient, } from './conversion-client.js';
+import { TwelveUiConversionClient, ConversionTerminalError, } from './conversion-client.js';
+import { conversionRecoveryAdvice, describeTerminalRecovery, } from './cli-conversion-recovery-advice.js';
 import { isConversionModel } from './conversion-models.js';
 import { isCliConversionOutput, } from './conversion-outputs.js';
 import { recordConvertedImageReceipt } from './conversion-receipt.js';
@@ -201,10 +202,13 @@ const outputPathForRecovery = async (artifact, overrideDirectory) => prepareOutp
     : artifact.outFile);
 const completedOperation = async (args) => {
     const current = await args.client.getConversion(args.id);
-    if (current.status === 'succeeded') {
+    if (current.status === 'succeeded' || current.responsive_alternative) {
         args.onProgress?.(current);
         return current;
     }
+    if (current.status === 'failed' || current.status === 'expired') {
+        throw new ConversionTerminalError({ ...current, status: current.status });
+    }
     return await args.client.waitForConversion(current.id, {
         expiresAt: current.expires_at,
         ...(args.timeoutMs === undefined ? {} : { timeoutMs: args.timeoutMs }),
@@ -431,9 +435,19 @@ export const runConversionCommand = async (command, flags, journal, dependencies
                 });
             }
             catch (error) {
-                progress.finish('stopped', {
+                const recoveryReport = await describeTerminalRecovery({
+                    client, error, conversionId,
+                    resumeCommand: `re-run 12ui resume ${conversionId}`,
+                    parentArtifact: { name: recovery.conversion.output, path: shownPath(recovery.conversion.outFile) },
+                    ...(recovery.linkedExport ? {
+                        fallbackExportId: recovery.linkedExport.conversionId,
+                        linkedArtifact: { name: 'responsive html', path: shownPath(recovery.linkedExport.outFile) },
+                    } : {}),
+                });
+                progress.finish(recoveryReport.terminalStatus ? 'failed' : 'stopped', {
                     detail: error instanceof Error ? error.message : String(error),
-                    next: `re-run 12ui resume ${conversionId}; collection is free until the purchase expires`,
+                    artifacts: recoveryReport.artifacts,
+                    next: recoveryReport.next,
                 });
                 throw error;
             }
@@ -475,6 +489,11 @@ export const runConversionCommand = async (command, flags, journal, dependencies
         const current = await client.getConversion(conversionId).catch((error) => {
             progress.finish('stopped', {
                 detail: error instanceof Error ? error.message : String(error),
+                next: conversionRecoveryAdvice({
+                    conversionId,
+                    terminalStatus: null,
+                    resumeCommand: `re-run 12ui resume ${conversionId} --output ${requestedOutput} --out ${resolvedOutFile}`,
+                }),
             });
             throw error;
         });
@@ -492,10 +511,13 @@ export const runConversionCommand = async (command, flags, journal, dependencies
         }
         let completed;
         try {
-            if (current.status === 'succeeded') {
+            if (current.status === 'succeeded' || current.responsive_alternative) {
                 reportConversion(progress, current, `collecting ${requestedOutput}`);
                 completed = current;
             }
+            else if (current.status === 'failed' || current.status === 'expired') {
+                throw new ConversionTerminalError({ ...current, status: current.status });
+            }
             else {
                 completed = await client.waitForConversion(current.id, {
                     expiresAt: current.expires_at,
@@ -504,20 +526,47 @@ export const runConversionCommand = async (command, flags, journal, dependencies
                 });
             }
         }
+        catch (error) {
+            const savedLinkedExport = current.export
+                ? (await readConversionRecovery(conversionId))?.linkedExport
+                : undefined;
+            const recoveryReport = await describeTerminalRecovery({
+                client, error, conversionId,
+                resumeCommand: `re-run 12ui resume ${conversionId} --output ${requestedOutput} --out ${resolvedOutFile}`,
+                parentArtifact: { name: current.output, path: resolvedOutFile },
+                ...(current.export ? {
+                    fallbackExportId: current.export.conversion_id,
+                    linkedArtifact: { name: 'responsive html', ...(savedLinkedExport ? { path: savedLinkedExport.outFile } : {}) },
+                } : {}),
+            });
+            progress.finish(recoveryReport.terminalStatus ? 'failed' : 'stopped', {
+                detail: error instanceof Error ? error.message : String(error),
+                artifacts: recoveryReport.artifacts,
+                next: recoveryReport.next,
+            });
+            throw error;
+        }
+        let downloaded;
+        try {
+            downloaded = await downloadCompletedConversion({
+                client,
+                operation: completed,
+                output: requestedOutput,
+                outFile: resolvedOutFile,
+            });
+        }
         catch (error) {
             progress.finish('stopped', {
                 detail: error instanceof Error ? error.message : String(error),
-                next: `re-run 12ui resume ${conversionId} --output ${requestedOutput} --out ${resolvedOutFile};`
-                    + ' collection is free until the purchase expires',
+                artifacts: [{ name: requestedOutput, state: 'succeeded — not collected', path: resolvedOutFile }],
+                next: conversionRecoveryAdvice({
+                    conversionId,
+                    terminalStatus: null,
+                    resumeCommand: `re-run 12ui resume ${conversionId} --output ${requestedOutput} --out ${resolvedOutFile}`,
+                }),
             });
             throw error;
         }
-        const downloaded = await downloadCompletedConversion({
-            client,
-            operation: completed,
-            output: requestedOutput,
-            outFile: resolvedOutFile,
-        });
         journal.note({ runId: completed.id, artifacts: [resolvedOutFile] });
         let linkedExport;
         if (completed.output === 'layerdoc' && completed.export?.conversion_id) {
@@ -749,10 +798,14 @@ export const runConversionCommand = async (command, flags, journal, dependencies
         : ''}`);
     let operation;
     try {
-        if (created.status === 'succeeded') {
+        if (created.status === 'succeeded' || created.responsive_alternative) {
             reportConversion(progress, created);
             operation = created;
         }
+        else if (created.status === 'failed' || created.status === 'expired') {
+            reportConversion(progress, created);
+            throw new ConversionTerminalError({ ...created, status: created.status });
+        }
         else {
             operation = await client.waitForConversion(created.id, {
                 expiresAt: created.expires_at,
@@ -763,17 +816,23 @@ export const runConversionCommand = async (command, flags, journal, dependencies
     }
     catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
-        progress.finish('stopped', {
-            detail: `conversion ${created.id} did not settle: ${detail}`,
-            ...(exportOperationId && exportOutFile
-                ? {
-                    artifacts: [
-                        { name: output, state: 'not collected' },
-                        { name: 'responsive html', state: 'unknown — the linked export was not read' },
-                    ],
-                    next: `12ui resume ${created.id} recovers both halves without re-buying`,
-                }
-                : { next: `12ui resume ${created.id} recovers the purchase without re-buying` }),
+        const recoveryReport = await describeTerminalRecovery({
+            client, error, conversionId: created.id,
+            resumeCommand: exportOperationId
+                ? `12ui resume ${created.id} recovers both halves without re-buying`
+                : `12ui resume ${created.id} recovers the purchase without re-buying`,
+            parentArtifact: { name: output, path: outFile },
+            ...(exportOperationId && exportOutFile ? {
+                fallbackExportId: exportOperationId,
+                linkedArtifact: { name: 'responsive html', path: exportOutFile },
+            } : {}),
+        });
+        progress.finish(recoveryReport.terminalStatus ? 'failed' : 'stopped', {
+            detail: recoveryReport.terminalStatus
+                ? `conversion ${created.id} is ${recoveryReport.terminalStatus}: ${detail}`
+                : `conversion ${created.id} did not settle: ${detail}`,
+            artifacts: recoveryReport.artifacts,
+            next: recoveryReport.next,
         });
         throw new Error(`Conversion ${created.id} failed: ${detail}`, { cause: error });
     }
@@ -791,7 +850,22 @@ export const runConversionCommand = async (command, flags, journal, dependencies
             ...(quiet ? {} : { warn: (message) => process.stderr.write(`${message}\n`) }),
         });
     }
-    const result = await downloadCompletedConversion({ client, operation, output, outFile });
+    let result;
+    try {
+        result = await downloadCompletedConversion({ client, operation, output, outFile });
+    }
+    catch (error) {
+        progress.finish('stopped', {
+            detail: error instanceof Error ? error.message : String(error),
+            artifacts: [{ name: output, state: 'succeeded — not collected', path: outFile }],
+            next: conversionRecoveryAdvice({
+                conversionId: created.id,
+                terminalStatus: null,
+                resumeCommand: `12ui resume ${created.id}`,
+            }),
+        });
+        throw error;
+    }
     journal.note({ artifacts: [outFile] });
     if (!exportOperationId || !exportOutFile) {
         const disposition = responsiveAlternativeDisposition(result);
@@ -879,16 +953,35 @@ export const runConversionCommand = async (command, flags, journal, dependencies
         : undefined;
     const pending = isPendingConversionStatus(exportStatus);
     const collect = `12ui resume ${exportOperationId} --output html --out <file>`;
-    const report = {
-        ...result,
-        nextAction: layerDocStateAction({
+    const collectToOutput = `12ui resume ${exportOperationId} --output html --out ${exportOutFile}`;
+    const terminalExportStatus = !exportResult
+        && (exportStatus === 'failed' || exportStatus === 'expired')
+        ? exportStatus
+        : null;
+    const nextAction = exportResult
+        ? layerDocStateAction({
             outFile,
             linkedExport: {
                 id: exportOperationId,
                 status: exportStatus,
-                ...(exportResult ? { outFile: exportOutFile } : {}),
+                outFile: exportOutFile,
             },
-        }),
+        })
+        : terminalExportStatus
+            ? conversionRecoveryAdvice({
+                conversionId: exportOperationId,
+                terminalStatus: terminalExportStatus,
+                resumeCommand: collectToOutput,
+            })
+            : exportStatus === 'succeeded' || exportStatus === 'unknown'
+                ? `Responsive export ${exportOperationId} is ${exportStatus}; collect the existing export with ${collectToOutput}`
+                : layerDocStateAction({
+                    outFile,
+                    linkedExport: { id: exportOperationId, status: exportStatus },
+                });
+    const report = {
+        ...result,
+        nextAction,
         export: exportResult
             ? { ...exportResult, status: exportStatus }
             : {
@@ -955,7 +1048,32 @@ export const runConversionCommand = async (command, flags, journal, dependencies
             next: `the purchase stays collectable until ${created.expires_at}`,
         });
     }
+    else if (exportStatus === 'succeeded' || exportStatus === 'unknown') {
+        progress.finish('stopped', {
+            detail: exportStatus === 'succeeded'
+                ? `the linked responsive export succeeded but collection did not complete: ${exportError}`
+                : `the linked responsive export state could not be read: ${exportReadDetail ?? exportError}`,
+            artifacts: [
+                layerdocRow,
+                {
+                    name: 'responsive html',
+                    state: exportStatus === 'succeeded' ? 'succeeded — not collected' : 'unknown — not collected',
+                    path: exportOutFile,
+                    ...((exportObservation?.readError?.message || exportError)
+                        ? { note: exportObservation?.readError?.message || exportError || undefined }
+                        : {}),
+                },
+            ],
+            spend: spendLine,
+            next: `${collectToOutput}; collection is free until the purchase expires`,
+        });
+    }
     else {
+        const next = conversionRecoveryAdvice({
+            conversionId: exportOperationId,
+            terminalStatus: terminalExportStatus,
+            resumeCommand: collectToOutput,
+        });
         progress.finish('failed', {
             detail: `the linked responsive export ${exportOperationId} ${exportStatus}`,
             artifacts: [
@@ -967,7 +1085,7 @@ export const runConversionCommand = async (command, flags, journal, dependencies
                 },
             ],
             spend: spendLine,
-            next: `render a fixed page free from the document: 12ui convert ${outFile} --output html_fixed`,
+            next,
         });
     }
     writeResultWithSummary(report, writeResult);
@@ -980,10 +1098,10 @@ export const runConversionCommand = async (command, flags, journal, dependencies
                 ? `Conversion ${created.id} succeeded and was written to ${outFile}, but responsive export`
                     + ` ${exportOperationId} failed with ${responsiveAlternativeLabel(exportDisposition)};`
                     + ` coverage is recorded in ${exportResult.artifactManifest.manifestFile}.`
-                : exportStatus === 'unknown'
-                    ? `Conversion ${created.id} succeeded and was written to ${outFile}. Responsive HTML export ${exportOperationId} has an unknown state. ${exportReadDetail ?? exportError}. Keep this purchase and collect the same export when the read issue is resolved: ${collect}.`
+                : exportStatus === 'succeeded' || exportStatus === 'unknown'
+                    ? `Conversion ${created.id} succeeded and was written to ${outFile}. Responsive HTML export ${exportOperationId} is ${exportStatus} and was not collected. Use ${collectToOutput}; this collects the existing purchase.`
                     : `Conversion ${created.id} succeeded and was written to ${outFile}, but its responsive HTML`
-                        + ` export ${exportOperationId} did not: ${exportError}`);
+                        + ` export ${exportOperationId} is ${exportStatus}: ${exportError}. ${nextAction}`);
     }
 };
 //# sourceMappingURL=cli-convert-command.js.map