@12ui/design 0.2.55 → 0.2.56

package/dist/improve-kit-readme.js

@@ -1,32 +1,198 @@
 import { writeFile } from 'node:fs/promises';
 import path from 'node:path';
-export const writeImproveReadme = async (record) => {
-    const readme = path.join(record.runDir, 'README.md');
+import { IMPROVE_ASSET_ROLE_COPY, IMPROVE_SCRIM_MAX_OPACITY_PCT, improveFrameMappingLine, readImproveKitAssets, } from './improve-kit-assets.js';
+import { IMPROVE_NO_APPROXIMATION_RULE, improveRecoveryLine, improveStageStatusLine, readImproveKitStatus, } from './improve-kit-status.js';
+import { improveAbandonedLines } from './improve-reset.js';
+import { improvePaths } from './improve-workspace.js';
+/**
+ * The kit's front door.
+ *
+ * It used to open with the directory anatomy, which answers a question nobody
+ * had. What two lanes actually needed, and did not get, was: did this run
+ * finish, what are these PNGs, and which of them must never be thrown away.
+ * Those three answers now come first, and the anatomy comes last.
+ */
+/** The file-name shape a reader sees, per role, in the order the glossary reads best. */
+const ROLE_GLOSSARY = [
+    { role: 'clean-plate', pattern: 'clean-N' },
+    { role: 'cutout', pattern: 'cutout-N' },
+    { role: 'upscaled-plate', pattern: 'upscaled-plate-N' },
+    { role: 'upscaled-region', pattern: 'upscaled-region-N' },
+    { role: 'source-crop', pattern: 'crop-N' },
+];
+const statusSection = (args) => {
+    const lines = ['## Status', ''];
+    lines.push(...args.status.stages.map((stage) => `- ${improveStageStatusLine(stage)}`));
+    lines.push(`- Target: ${args.status.targetMode}`);
+    lines.push(...improveAbandonedLines(args.record));
+    if (args.status.complete) {
+        lines.push('', ...(args.status.gateBlocked
+            ? ['The coverage gate blocked the anchored plan: `plan/GATE.md` replaced `plan-annotated.md`'
+                    + ' and `token-patch.css`. Read `plan/GATE.md` before touching code; the target, its assets'
+                    + ' and the raster layers it names are all still here.']
+            : args.record.convert?.layout === 'fixed'
+                ? ['Convert fell back: the target HTML is fixed-layout, not responsive.'
+                        + ' The LayerDoc and its assets are the full-quality source of truth.']
+                : ['Every requested stage settled. The kit is complete.']), '');
+        return lines;
+    }
+    lines.push('', `This kit is INCOMPLETE: ${args.status.missing.join(', ')}.`, ...(args.status.present.stall ? ['', 'See `plan/STALL.md` for what the run was waiting on.'] : []), '', 'Recovery, in order — the first resumes and replays every settled stage:', '', ...args.status.recovery.map(improveRecoveryLine), '', IMPROVE_NO_APPROXIMATION_RULE, '');
+    return lines;
+};
+const startHere = (args) => {
+    const design = path.relative(args.record.runDir, args.status.designImage);
+    const hasAssets = args.index.assets.length > 0;
+    // A gate block deletes the two files steps 3 and 4 name. Sending a reader to
+    // them is how a kit gets abandoned with its assets unread.
+    const planSteps = args.status.gateBlocked
+        ? ['3. Read `plan/GATE.md`. It says why no selector-anchored plan was emitted, and what to'
+                + ' re-capture; the raster layers it lists are still the design.']
+        : [
+            '3. Apply `plan/token-patch.css` once, at the token layer, not per element.',
+            '4. Work `plan/plan-annotated.md` in its own order: raster layers, then matched changes,'
+                + ' then added elements.',
+        ];
+    const frame = args.record.capture
+        ? { width: args.record.capture.width, height: args.record.capture.height }
+        : args.record.viewport;
+    return [
+        '## Start here',
+        '',
+        ...(args.status.complete
+            ? []
+            : [args.status.gateBlocked
+                    ? 'Run the recovery above first: the steps below assume a target this kit has not finished.'
+                    : hasAssets
+                        ? 'Run the recovery above first: steps 3 and 4 need a plan this kit does not have yet.'
+                        : 'Run the recovery above first: steps 2 to 4 need a target this kit does not have yet.', '']),
+        // The frame a bound belongs to, before the first step that places anything:
+        // a lane read these percentages as `winner.png` pixels and placed short.
+        improveFrameMappingLine({
+            ...(frame ? { frame } : {}),
+            ...(args.index.canvas ? { design: args.index.canvas } : {}),
+        }),
+        '',
+        args.status.designKind === 'layerdoc'
+            ? `1. Open \`${design}\`. The supplied target document is the design.`
+            : `1. Open \`${design}\`. It is the design.`,
+        '2. Copy the files the assets table below marks ship into the repository;'
+            + ' the rest are references and alternates.',
+        ...planSteps,
+        `${args.status.gateBlocked ? '4' : '5'}. Before committing, screenshot the page and put it`
+            + ` beside \`${design}\`.`,
+        '',
+    ];
+};
+const assetRow = (asset) => {
+    const role = `${asset.roleLabel}${asset.hero ? ' — hero imagery' : ''}`;
+    const layer = asset.layer ? `${asset.layer.kind} — ${asset.layer.name}` : 'whole design';
+    const bounds = asset.bounds
+        ? `${asset.bounds.width.toFixed(1)}% × ${asset.bounds.height.toFixed(1)}%`
+            + ` at ${asset.bounds.x.toFixed(1)}%, ${asset.bounds.y.toFixed(1)}%`
+        : 'full canvas';
+    const instruction = asset.present
+        ? asset.instruction
+        : `${asset.instruction} (declared by the manifest but missing from this kit)`;
+    return `| \`${asset.file}\` | ${asset.ship} | ${role} | ${layer} | ${bounds} | ${instruction} |`;
+};
+const assetsSection = (args) => {
+    const design = path.relative(args.record.runDir, args.status.designImage);
     const lines = [
-        '# 12ui improve kit', '',
-        `Input: ${record.input.kind} \`${record.input.value}\``,
-        `Picked candidate: ${record.pick?.slot ?? (record.target ? 'bring-your-own target' : 'not yet picked')}`, '',
-        '## Anatomy', '',
-        '- `improve.json` is the durable stage, purchase, price-ceiling, and replay record.',
-        `- ${record.input.kind === 'url' ? '`capture/` and `current.domdoc.json` hold the screenshot and selector-verified DOM extraction.' : '`source.png` is the normalized source screenshot.'}`,
-        '- `candidates/` keeps every generated option and its draft record; `winner.png` is the explicit image target.',
-        '- `target/` holds the target LayerDoc, responsive HTML when generated, and extracted assets.',
-        '- `plan/` holds the diff, implementation plan, token patch, added-element assets, or `GATE.md` when anchoring was unsafe.', '',
-        ...(record.convert?.layout === 'fixed' ? [
-            '## Fixed-layout target', '',
-            `- Warning: ${record.convert.responsiveWarning ?? 'Responsive HTML was unavailable.'}`,
-            '- The target HTML is a fixed-layout fallback derived free from the successful LayerDoc conversion. It is not a responsive deliverable; the LayerDoc remains valid for planning.', '',
-        ] : []),
-        '## Next', '',
-        '- Treat the target HTML when present and `target/winner.layerdoc.json` as the visual source of truth.',
-        '- Apply the plan in the owning repository, then verify behavior and screenshots there. This kit never applies code.',
-        '- Re-run from `pick` with another `--pick` slot to reuse capture and candidates; settled paid stages replay.', '',
-        '## Guardrails', '',
-        '- Preserve all real content, data, and controls; invent nothing.',
-        '- Do not describe emptiness or thin content as a defect: that phrasing can invite fabricated UI.',
-        '- Verify Tailwind v4 arbitrary custom-property syntax, quote CSS `url(...)` values, and update CSP before introducing data URIs.', '',
+        '## Assets: what each file is',
+        '',
+        ...ROLE_GLOSSARY.map(({ role, pattern }) => `- ${IMPROVE_ASSET_ROLE_COPY[role].label}`
+            + ` (\`${pattern}\`): ${IMPROVE_ASSET_ROLE_COPY[role].instruction}`),
+        `- \`${design}\`: ${IMPROVE_ASSET_ROLE_COPY.design.instruction}`,
+        '',
     ];
-    await writeFile(readme, lines.join('\n'), 'utf8');
-    return readme;
+    if (args.index.assets.length === 0) {
+        lines.push(args.status.present.layerDoc
+            ? 'This kit has a LayerDoc but no extracted assets yet. Resume before coding.'
+            : 'This kit has no extracted assets yet. Resume before coding.', '');
+    }
+    else {
+        lines.push('Ordered by how much of the canvas the layer covers.', '', 'Ship means copy this file into the repository. An alternate resolution is the same layer at'
+            + ' another size — pick one. An alternate backdrop is the same plate with a further layer'
+            + ' removed as well — it is the background only if you omit that layer. A reference is read,'
+            + ' never shipped.', '', 'Plates and cutouts come out at full resolution and run over a megabyte. Pick one resolution'
+            + ' per layer and optimise the PNG — or convert it to WebP where the repository already uses'
+            + ' one — before committing. Keep the filename stem so the plan still matches.', '', '| File | Ship | Role | Layer | Bounds | What to do with it |', '| --- | --- | --- | --- | --- | --- |', `| \`${design}\` | reference only | winner.png — hero imagery | whole design |`
+            + ` 100.0% × 100.0% at 0.0%, 0.0% | ${IMPROVE_ASSET_ROLE_COPY.design.instruction} |`, ...args.index.assets.map(assetRow), '');
+    }
+    // Only the carrier a layer actually ships is a must-keep; the upscaled twin is
+    // an alternative resolution, and naming it here would contradict "ship one".
+    const heroes = args.index.rasterLayers
+        .filter((layer) => layer.hero && layer.asset)
+        .map((layer) => layer.asset);
+    lines.push('### Never discard', '', `- \`${design}\`.`, args.index.assets.length > 0
+        ? '- Every cutout and plate this table names.'
+        : '- Every cutout and plate the kit extracts once the run completes.', ...heroes.map((asset) => `  - Hero imagery: \`${asset.file}\` (${asset.roleLabel}).`), '- All real content, data, controls, routes, and tests.', '', `Scrims over a plate stay light (at most ${IMPROVE_SCRIM_MAX_OPACITY_PCT}% opacity), and the plan`
+        + ' must say why one is used.', '');
+    return lines;
+};
+const guardrails = () => [
+    '## Guardrails',
+    '',
+    '- Preserve all real content, data, and controls; invent nothing.',
+    '- Do not describe emptiness or thin content as a defect: that phrasing can invite fabricated UI.',
+    '- Verify Tailwind v4 arbitrary custom-property syntax, quote CSS `url(...)` values, and update CSP before introducing data URIs.',
+    '- Never use the raw candidate PNG as a shipped asset; ship the extracted cutouts and plates.',
+    '- Never scrim imagery away. A heavy overlay is a fidelity defect, not a readability fix.',
+    '- Do not add decoration the design does not contain.',
+    '',
+];
+const anatomy = (record) => [
+    '## Anatomy',
+    '',
+    '- `improve.json` is the durable stage, purchase, price-ceiling, and replay record.',
+    `- ${record.input.kind === 'url'
+        ? '`capture/` and `current.domdoc.json` hold the screenshot and selector-verified DOM extraction.'
+        : '`source.png` is the normalized source screenshot.'}`,
+    '- `candidates/` keeps every generated option and its draft record; `winner.png` is the explicit image target.',
+    '- `target/` holds the target LayerDoc, responsive HTML when generated, and extracted assets.',
+    '- `plan/` holds the diff, implementation plan, token patch, added-element assets, `GATE.md` when anchoring was unsafe, or `STALL.md` when a stage did not settle.',
+    '',
+    '## Replay',
+    '',
+    '- Apply the plan in the owning repository, then verify behavior and screenshots there. This kit never applies code.',
+    '- Re-run from `pick` with another `--pick` slot to reuse capture and candidates; settled paid stages replay.',
+    '',
+];
+const fixedLayoutSection = (record) => (record.convert?.layout === 'fixed'
+    ? [
+        '## Fixed-layout target',
+        '',
+        `- Warning: ${record.convert.responsiveWarning ?? 'Responsive HTML was unavailable.'}`,
+        '- The target HTML is a fixed-layout fallback derived free from the successful LayerDoc conversion. It is not a responsive deliverable; the LayerDoc remains valid for planning.',
+        '',
+    ]
+    : []);
+export const renderImproveReadme = (args) => [
+    '# 12ui improve kit',
+    '',
+    `Input: ${args.record.input.kind} \`${args.record.input.value}\``,
+    // Which candidate this kit was built from, and why that one: it is only
+    // ever an explicit --pick now, or a supplied target. Nothing is guessed.
+    `Picked candidate: ${args.record.pick
+        ? `${args.record.pick.slot} — chosen with --pick, and the target was converted from it`
+        : args.record.target
+            ? 'bring-your-own target'
+            : 'not yet picked — nothing has been converted'}`,
+    '',
+    ...statusSection(args),
+    ...startHere(args),
+    ...assetsSection(args),
+    ...guardrails(),
+    ...fixedLayoutSection(args.record),
+    ...anatomy(args.record),
+].join('\n');
+export const writeImproveReadme = async (record, context = {}) => {
+    const paths = improvePaths(record.runDir);
+    const [status, index] = await Promise.all([
+        readImproveKitStatus({ record, ...(context.requestedTo ? { requestedTo: context.requestedTo } : {}) }),
+        readImproveKitAssets({ runDir: record.runDir, layerDocPath: paths.targetLayerDoc }),
+    ]);
+    await writeFile(paths.readme, renderImproveReadme({ record, status, index }), 'utf8');
+    return paths.readme;
 };
 //# sourceMappingURL=improve-kit-readme.js.map

package/dist/improve-kit-readme.js.map

@@ -1 +1 @@
-{"version":3,"file":"improve-kit-readme.js","sourceRoot":"","sources":["../src/improve-kit-readme.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,IAAI,MAAM,WAAW,CAAC;AAI7B,MAAM,CAAC,MAAM,kBAAkB,GAAG,KAAK,EAAE,MAAqB,EAAmB,EAAE;IACjF,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG;QACZ,oBAAoB,EAAE,EAAE;QACxB,UAAU,MAAM,CAAC,KAAK,CAAC,IAAI,MAAM,MAAM,CAAC,KAAK,CAAC,KAAK,IAAI;QACvD,qBAAqB,MAAM,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,gBAAgB,CAAC,EAAE,EAAE,EAAE;QAC5G,YAAY,EAAE,EAAE;QAChB,oFAAoF;QACpF,KAAK,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,gGAAgG,CAAC,CAAC,CAAC,mDAAmD,EAAE;QAC3L,+GAA+G;QAC/G,8FAA8F;QAC9F,2HAA2H,EAAE,EAAE;QAC/H,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC;YACvC,wBAAwB,EAAE,EAAE;YAC5B,cAAc,MAAM,CAAC,OAAO,CAAC,iBAAiB,IAAI,kCAAkC,EAAE;YACtF,iLAAiL,EAAE,EAAE;SACtL,CAAC,CAAC,CAAC,EAAE,CAAC;QACP,SAAS,EAAE,EAAE;QACb,uGAAuG;QACvG,qHAAqH;QACrH,8GAA8G,EAAE,EAAE;QAClH,eAAe,EAAE,EAAE;QACnB,kEAAkE;QAClE,kGAAkG;QAClG,kIAAkI,EAAE,EAAE;KACvI,CAAC;IACF,MAAM,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,CAAC;IAClD,OAAO,MAAM,CAAC;AAChB,CAAC,CAAC"}
+{"version":3,"file":"improve-kit-readme.js","sourceRoot":"","sources":["../src/improve-kit-readme.ts"],"names":[],"mappings":"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"}

package/dist/improve-kit-stall.d.ts

@@ -0,0 +1,67 @@
+import { type ImproveKitAssetIndex } from './improve-kit-assets.js';
+import { type ImproveKitStatus } from './improve-kit-status.js';
+import { type ImproveResumeConversion } from './improve-convert-resilience.js';
+import { type RunJournalEntry } from './run-journal.js';
+import { type ImproveRecord, type ImproveStage } from './improve-workspace.js';
+/** A run that ran out of patience and a run somebody killed read differently. */
+export type ImproveStallKind = 'stalled' | 'stopped';
+export type ImproveStallFacts = {
+    stage: ImproveStage;
+    kind: ImproveStallKind;
+    hostedRunId?: string;
+    waitedSeconds?: number;
+    typicalSeconds?: number;
+    serviceStage?: string;
+    /** The conversion the first recovery command will attach to, if the kit knows one. */
+    resume?: ImproveResumeConversion;
+    reason: string;
+};
+/**
+ * What the run was waiting on, from the journal it kept writing plus the error
+ * that ended the local process. The journal is authoritative for elapsed time
+ * because the error text carries none.
+ */
+export declare const collectImproveStallFacts: (args: {
+    record: ImproveRecord;
+    stage: ImproveStage;
+    error: unknown;
+    kind?: ImproveStallKind;
+    /**
+     * A journal the caller has already read. The terminal-event path runs on a
+     * signal that may be followed by SIGKILL after a short grace, so it reads the
+     * journal exactly once and shares it rather than reading it twice before the
+     * end line is on disk.
+     */
+    entries?: readonly RunJournalEntry[];
+    /**
+     * This invocation still had a stage in flight when it ended, so the record's
+     * `convert` block is about an EARLIER conversion — `--fresh` clears convert
+     * from the DURABLE record inside the stage, and the in-memory copy a stop
+     * handler holds is only reassigned when that stage RETURNS. The journal is
+     * then the only truthful source for the hosted run: its newest paid line is
+     * this process's own heartbeat, and no end line for this invocation exists
+     * yet. Reading the record instead put an abandoned conversion's id and its
+     * 216s age on the pipedrive kit's end line while the live one was 75s old.
+     */
+    inFlight?: boolean;
+}) => Promise<ImproveStallFacts>;
+export declare const renderImproveStall: (args: {
+    record: ImproveRecord;
+    facts: ImproveStallFacts;
+    status: ImproveKitStatus;
+    index: ImproveKitAssetIndex;
+}) => string;
+/**
+ * Write `plan/STALL.md`, creating `plan/` when the plan stage never ran.
+ * Returns the file so the caller can journal it as an artifact.
+ */
+export declare const writeImproveStallReport: (args: {
+    record: ImproveRecord;
+    stage: ImproveStage;
+    error: unknown;
+    requestedTo?: ImproveStage;
+    kind?: ImproveStallKind;
+    /** See `collectImproveStallFacts`: the hosted run then comes from the journal. */
+    inFlight?: boolean;
+}) => Promise<string>;
+//# sourceMappingURL=improve-kit-stall.d.ts.map

package/dist/improve-kit-stall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"improve-kit-stall.d.ts","sourceRoot":"","sources":["../src/improve-kit-stall.ts"],"names":[],"mappings":"AAIA,OAAO,EAAwB,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC1F,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAIL,KAAK,uBAAuB,EAC7B,MAAM,iCAAiC,CAAC;AAGzC,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAgB,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAe7F,iFAAiF;AACjF,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,CAAC;AAErD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,gBAAgB,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GAAU,MAAM;IACnD,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,KAAG,OAAO,CAAC,iBAAiB,CAgC5B,CAAC;AAgDF,eAAO,MAAM,kBAAkB,GAAI,MAAM;IACvC,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,EAAE,oBAAoB,CAAC;CAC7B,KAAG,MAoCH,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAAU,MAAM;IAClD,MAAM,EAAE,aAAa,CAAC;IACtB,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,KAAG,OAAO,CAAC,MAAM,CAoBjB,CAAC"}

package/dist/improve-kit-stall.js

@@ -0,0 +1,159 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { formatDuration } from './cli-progress.js';
+import { readImproveKitAssets } from './improve-kit-assets.js';
+import { IMPROVE_NO_APPROXIMATION_RULE, improveRecoveryLine, readImproveKitStatus, } from './improve-kit-status.js';
+import { improveConversionIdFromText, improveErrorText, improveResumeConversion, } from './improve-convert-resilience.js';
+import { renderImproveRasterLayers } from './improve-raster-layers-section.js';
+import { improveAbandonedLines } from './improve-reset.js';
+import { readRunJournal } from './run-journal.js';
+import { improvePaths } from './improve-workspace.js';
+/**
+ * A stalled run still writes a plan directory.
+ *
+ * Pipedrive's conversion sat in `materializing_assets` for sixteen minutes and
+ * never journalled a terminal event, so the kit had an empty `target/`, no
+ * `plan/`, and nothing at all telling the lane what to do. It hand-authored the
+ * hero in CSS. This file is what should have been there instead: which stage,
+ * how long it waited, the hosted run id, what exists, and the three commands
+ * that recover — plus the raster layers, whenever a LayerDoc survived.
+ */
+const UUID = /[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}/iu;
+/**
+ * What the run was waiting on, from the journal it kept writing plus the error
+ * that ended the local process. The journal is authoritative for elapsed time
+ * because the error text carries none.
+ */
+export const collectImproveStallFacts = async (args) => {
+    const text = improveErrorText(args.error);
+    const entries = args.entries
+        ?? (await readRunJournal({ workspace: args.record.runDir }).catch(() => ({ entries: [] }))).entries;
+    const progress = [...entries].reverse().find((entry) => (entry.event === 'progress' && entry.paid && entry.elapsed_seconds !== undefined));
+    const journalled = [...entries].reverse().find((entry) => (entry.paid && typeof entry.run_id === 'string' && UUID.test(entry.run_id)))?.run_id;
+    const recorded = args.record.convert?.sourceConversionId;
+    const hostedRunId = args.inFlight
+        ? journalled ?? improveConversionIdFromText(text) ?? recorded
+        : recorded ?? improveConversionIdFromText(text) ?? journalled;
+    const resume = improveResumeConversion(args.record);
+    // An attempt whose id never reached the record, named from the journal
+    // instead. It is the same conversion: the open attempt is what THIS
+    // invocation dispatched, and `inFlight` is what makes the journal's newest
+    // paid line this invocation's own heartbeat rather than an earlier run's.
+    const named = resume && !resume.id && args.inFlight && hostedRunId
+        ? { ...resume, id: hostedRunId }
+        : resume;
+    return {
+        stage: args.stage,
+        kind: args.kind ?? 'stalled',
+        ...(hostedRunId ? { hostedRunId } : {}),
+        ...(named ? { resume: named } : {}),
+        ...(progress?.elapsed_seconds === undefined ? {} : { waitedSeconds: progress.elapsed_seconds }),
+        ...(progress?.typical_seconds === undefined ? {} : { typicalSeconds: progress.typical_seconds }),
+        ...(progress?.stage ? { serviceStage: progress.stage } : {}),
+        reason: text.split('\n')[0]?.trim() || 'The stage ended without settling.',
+    };
+};
+const targetContents = (status) => {
+    if (!status.present.layerDoc)
+        return 'nothing';
+    if (!status.present.assets)
+        return 'the LayerDoc only';
+    return status.present.targetHtml
+        ? 'the LayerDoc, its assets, and target HTML'
+        : 'the LayerDoc and its assets';
+};
+/**
+ * Which conversion the recovery command below actually reaches, and — when this
+ * run was watching a different one — that the one it was watching is gone.
+ *
+ * A `--fresh` or retry conversion is recorded by its exact key before it is
+ * dispatched (`improve-conversion-attempts.ts`), so a run stopped inside one
+ * resumes onto the conversion it was actually watching. The "cannot be
+ * resumed" line survives for kits written before that ledger: they hold two
+ * conversions, the base-key one `--fresh` rotated away from, which the resume
+ * lands back on, and the fresh one dispatched under a one-off nonce nothing
+ * recorded. Naming only the second reads as "resume and you get this back",
+ * which is false and costs a conversion when the reader buys another instead.
+ */
+const resumeLines = (facts) => {
+    if (!facts.resume)
+        return [];
+    const reaches = facts.resume.reason === 'settled'
+        ? 'the first command below replays it and buys nothing'
+        : 'the first command below rebuilds this kit\'s conversion key and re-attaches to it,'
+            + ' rather than buying another';
+    const lines = [
+        facts.resume.id
+            ? `- Resume attaches to: \`${facts.resume.id}\` — ${reaches}`
+            : '- Resume attaches to: the conversion this kit dispatched under its recorded key —'
+                + ' it never reported an id, but the key is on the record, so'
+                + ` ${reaches}`,
+    ];
+    if (facts.resume.reason === 'fresh-rotated-away'
+        && facts.hostedRunId
+        && facts.hostedRunId !== facts.resume.id) {
+        lines.push(`- Cannot be resumed: \`${facts.hostedRunId}\` — this run dispatched it under a one-off`
+            + ' `--fresh` key that nothing durable records, so no later command can re-attach to it.'
+            + ' It keeps running and keeps billing.');
+    }
+    return lines;
+};
+export const renderImproveStall = (args) => {
+    const waited = args.facts.waitedSeconds === undefined
+        ? 'unrecorded'
+        : `${formatDuration(args.facts.waitedSeconds)}`
+            + `${args.facts.typicalSeconds === undefined
+                ? ''
+                : ` against a typical ${formatDuration(args.facts.typicalSeconds)}`}`;
+    const lines = [
+        `# INCOMPLETE — this run ${args.facts.kind === 'stopped' ? 'was stopped' : 'stalled'}`,
+        '',
+        `- Stage: ${args.facts.stage}`
+            + `${args.facts.serviceStage ? ` (service stage \`${args.facts.serviceStage}\`)` : ''}`,
+        `- Waited: ${waited}`,
+        `- Hosted run: ${args.facts.hostedRunId ? `\`${args.facts.hostedRunId}\`` : 'not recorded'}`,
+        ...resumeLines(args.facts),
+        `- In \`target/\`: ${targetContents(args.status)}`,
+        `- Reason: ${args.facts.reason}`,
+        ...improveAbandonedLines(args.record),
+        '',
+        '## Recovery',
+        '',
+        'Run the first command; it resumes and replays every settled stage rather than buying them again.',
+        '',
+        ...args.status.recovery.map(improveRecoveryLine),
+        '',
+        IMPROVE_NO_APPROXIMATION_RULE,
+        '',
+    ];
+    if (args.status.present.layerDoc) {
+        lines.push('A LayerDoc survived this run, so the design\'s raster layers are usable without a plan.', '', ...renderImproveRasterLayers({ layers: args.index.rasterLayers }));
+    }
+    return lines.join('\n');
+};
+/**
+ * Write `plan/STALL.md`, creating `plan/` when the plan stage never ran.
+ * Returns the file so the caller can journal it as an artifact.
+ */
+export const writeImproveStallReport = async (args) => {
+    const paths = improvePaths(args.record.runDir);
+    const [facts, status, index] = await Promise.all([
+        collectImproveStallFacts({
+            record: args.record,
+            stage: args.stage,
+            error: args.error,
+            ...(args.kind ? { kind: args.kind } : {}),
+            ...(args.inFlight === undefined ? {} : { inFlight: args.inFlight }),
+        }),
+        readImproveKitStatus({
+            record: args.record,
+            ...(args.requestedTo ? { requestedTo: args.requestedTo } : {}),
+        }),
+        readImproveKitAssets({ runDir: args.record.runDir, layerDocPath: paths.targetLayerDoc }),
+    ]);
+    await mkdir(paths.planDir, { recursive: true });
+    const file = path.join(paths.planDir, 'STALL.md');
+    await writeFile(file, renderImproveStall({ record: args.record, facts, status, index }), 'utf8');
+    return file;
+};
+//# sourceMappingURL=improve-kit-stall.js.map

package/dist/improve-kit-stall.js.map

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

package/dist/improve-kit-status.d.ts

@@ -0,0 +1,69 @@
+import { type ImproveRecord, type ImproveStage } from './improve-workspace.js';
+/**
+ * One honest reading of "how far did this kit actually get".
+ *
+ * Read from the durable record AND the filesystem, because the record only
+ * ever describes stages that settled: a run killed inside `materializing_assets`
+ * leaves a record that says capture, draft and pick are fine and says nothing
+ * at all about the empty `target/` the reader is looking at.
+ */
+export type ImproveStageState = 'settled' | 'replayed' | 'skipped' | 'fallback' | 'blocked' | 'incomplete' | 'not-requested';
+export type ImproveStageStatus = {
+    stage: ImproveStage;
+    state: ImproveStageState;
+    detail?: string;
+};
+export type ImproveTargetMode = 'responsive HTML' | 'fixed-layout fallback' | 'LayerDoc only' | 'none';
+/** One recovery command and what running it costs. */
+export type ImproveRecoveryCommand = {
+    command: string;
+    spends: string;
+};
+export type ImproveKitStatus = {
+    stages: ImproveStageStatus[];
+    /** Every requested stage settled and the artifacts it promises are on disk. */
+    complete: boolean;
+    /**
+     * The coverage gate blocked the anchored plan, so `plan/GATE.md` replaced
+     * `plan-annotated.md` and `token-patch.css`. Nothing is missing and nothing
+     * stalled: it is a third outcome, and a reader sent to files the gate deleted
+     * is a reader who gives up on the kit.
+     */
+    gateBlocked: boolean;
+    /** What a reader will not find, in the words the recovery commands answer. */
+    missing: string[];
+    targetMode: ImproveTargetMode;
+    present: {
+        design: boolean;
+        layerDoc: boolean;
+        assets: boolean;
+        targetHtml: boolean;
+        plan: boolean;
+        gate: boolean;
+        stall: boolean;
+    };
+    /** The file a reader should look at and a conversion can be re-run from. */
+    designImage: string;
+    /** A supplied `*.layerdoc.json` target kit has a document, not a picture. */
+    designKind: 'image' | 'layerdoc';
+    recovery: ImproveRecoveryCommand[];
+};
+export declare const IMPROVE_NO_APPROXIMATION_RULE: string;
+/**
+ * A recovery command is presented as copy-and-run, so it has to survive being
+ * pasted. Capture URLs carry query strings and `--out-dir` paths carry spaces;
+ * either one unquoted breaks the line or backgrounds it at the `&`.
+ */
+export declare const shellArg: (value: string) => string;
+export declare const improveRecoveryCommands: (args: {
+    record: ImproveRecord;
+    designImage: string;
+}) => ImproveRecoveryCommand[];
+/** One indented, copy-pasteable line; the cost rides along as a shell comment. */
+export declare const improveRecoveryLine: (entry: ImproveRecoveryCommand) => string;
+export declare const readImproveKitStatus: (args: {
+    record: ImproveRecord;
+    requestedTo?: ImproveStage;
+}) => Promise<ImproveKitStatus>;
+export declare const improveStageStatusLine: (status: ImproveStageStatus) => string;
+//# sourceMappingURL=improve-kit-status.d.ts.map

package/dist/improve-kit-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"improve-kit-status.d.ts","sourceRoot":"","sources":["../src/improve-kit-status.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgC,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE7G;;;;;;;GAOG;AAEH,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,UAAU,GACV,SAAS,GACT,UAAU,GACV,SAAS,GACT,YAAY,GACZ,eAAe,CAAC;AAEpB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,iBAAiB,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GACzB,iBAAiB,GACjB,uBAAuB,GACvB,eAAe,GACf,MAAM,CAAC;AAEX,sDAAsD;AACtD,MAAM,MAAM,sBAAsB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,WAAW,EAAE,OAAO,CAAC;IACrB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,OAAO,EAAE;QACP,MAAM,EAAE,OAAO,CAAC;QAChB,QAAQ,EAAE,OAAO,CAAC;QAClB,MAAM,EAAE,OAAO,CAAC;QAChB,UAAU,EAAE,OAAO,CAAC;QACpB,IAAI,EAAE,OAAO,CAAC;QACd,IAAI,EAAE,OAAO,CAAC;QACd,KAAK,EAAE,OAAO,CAAC;KAChB,CAAC;IACF,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,UAAU,EAAE,OAAO,GAAG,UAAU,CAAC;IACjC,QAAQ,EAAE,sBAAsB,EAAE,CAAC;CACpC,CAAC;AAgDF,eAAO,MAAM,6BAA6B,QACkB,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAI,OAAO,MAAM,KAAG,MAExC,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAAI,MAAM;IAC5C,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,KAAG,sBAAsB,EAmBzB,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,GAAI,OAAO,sBAAsB,KAAG,MAEnE,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAU,MAAM;IAC/C,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B,KAAG,OAAO,CAAC,gBAAgB,CA8E3B,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,QAAQ,kBAAkB,KAAG,MAGnE,CAAC"}