@12ui/design 0.2.13 → 0.2.14

package/dist/package-manifest-file.js

@@ -0,0 +1,119 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isConversionModel } from './conversion-models.js';
+import { isConversionOutput } from './conversion-outputs.js';
+import { classifyLocalConversionInput } from './local-conversion-input.js';
+import { isResponsiveConversionQuality, } from './responsive-quality.js';
+const record = (value, label) => {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${label} must be a JSON object`);
+    }
+    return value;
+};
+const text = (value, label, required = false) => {
+    if (value === undefined) {
+        if (required)
+            throw new Error(`${label} is required`);
+        return undefined;
+    }
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`${label} must be non-empty text`);
+    return value.trim();
+};
+const ordinalOr = (value, fallback, label) => {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || Number(value) < 0) {
+        throw new Error(`${label} must be a non-negative integer`);
+    }
+    return Number(value);
+};
+export const readLocalPackageManifest = async (manifestPath) => {
+    const source = await readFile(manifestPath, 'utf8');
+    const manifestSha256 = createHash('sha256').update(source).digest('hex');
+    const root = record(JSON.parse(source), 'The package manifest');
+    if (root.version !== 1)
+        throw new Error('The package manifest version must be 1');
+    const output = root.output === undefined ? 'html' : root.output;
+    if (!isConversionOutput(output)) {
+        throw new Error('The package manifest output is not a supported conversion output');
+    }
+    if (output === 'web_project' || output === 'app_project') {
+        throw new Error('12ui convert package does not submit project outputs; export them from a conversion instead');
+    }
+    const model = root.model === undefined ? undefined : root.model;
+    if (model !== undefined && !isConversionModel(model)) {
+        throw new Error('The package manifest model must be fast, standard, or pro');
+    }
+    const responsiveQuality = root.responsiveQuality;
+    if (responsiveQuality !== undefined && !isResponsiveConversionQuality(responsiveQuality)) {
+        throw new Error('The package manifest responsiveQuality must be standard or pro');
+    }
+    if (responsiveQuality !== undefined && output !== 'html') {
+        throw new Error('The package manifest responsiveQuality is only valid with output html');
+    }
+    if (!Array.isArray(root.pages) || root.pages.length === 0) {
+        throw new Error('The package manifest must declare at least one page');
+    }
+    const manifestDirectory = path.dirname(path.resolve(manifestPath));
+    const pageIds = new Set();
+    const pages = [];
+    for (const [pageIndex, pageValue] of root.pages.entries()) {
+        const page = record(pageValue, `pages[${pageIndex}]`);
+        const id = text(page.id, `pages[${pageIndex}].id`, true);
+        if (pageIds.has(id))
+            throw new Error(`Page id ${id} is declared twice`);
+        pageIds.add(id);
+        if (page.kind !== undefined && page.kind !== 'source' && page.kind !== 'additional') {
+            throw new Error(`pages[${pageIndex}].kind must be source or additional`);
+        }
+        if (!Array.isArray(page.viewports) || page.viewports.length === 0) {
+            throw new Error(`pages[${pageIndex}].viewports must list at least one screenshot`);
+        }
+        const viewportIds = new Set();
+        const viewports = [];
+        for (const [viewportIndex, viewportValue] of page.viewports.entries()) {
+            const viewport = record(viewportValue, `pages[${pageIndex}].viewports[${viewportIndex}]`);
+            const viewportId = text(viewport.id, `pages[${pageIndex}].viewports[${viewportIndex}].id`, true);
+            if (viewportIds.has(viewportId)) {
+                throw new Error(`Viewport id ${viewportId} is declared twice on page ${id}`);
+            }
+            viewportIds.add(viewportId);
+            const image = text(viewport.image, `pages[${pageIndex}].viewports[${viewportIndex}].image`, true);
+            const imagePath = path.resolve(manifestDirectory, image);
+            const classified = classifyLocalConversionInput(imagePath);
+            if (classified.kind !== 'image') {
+                throw new Error(`Viewport ${viewportId} must name a PNG, JPEG, or WebP screenshot`);
+            }
+            const bytes = new Uint8Array(await readFile(imagePath));
+            const sourceConversionId = text(viewport.sourceConversionId, `pages[${pageIndex}].viewports[${viewportIndex}].sourceConversionId`);
+            viewports.push({
+                id: viewportId,
+                ordinal: ordinalOr(viewport.ordinal, viewportIndex + 1, `pages[${pageIndex}].viewports[${viewportIndex}].ordinal`),
+                imagePath,
+                bytes,
+                mediaType: classified.mediaType,
+                ...(sourceConversionId ? { sourceConversionId } : {}),
+            });
+        }
+        pages.push({
+            id,
+            ordinal: ordinalOr(page.ordinal, pageIndex, `pages[${pageIndex}].ordinal`),
+            ...(page.kind ? { kind: page.kind } : {}),
+            ...(text(page.title, `pages[${pageIndex}].title`) ? { title: text(page.title, '') } : {}),
+            ...(text(page.purpose, `pages[${pageIndex}].purpose`) ? { purpose: text(page.purpose, '') } : {}),
+            ...(text(page.path, `pages[${pageIndex}].path`) ? { path: text(page.path, '') } : {}),
+            viewports,
+        });
+    }
+    return {
+        version: 1,
+        output,
+        ...(model ? { model } : {}),
+        ...(responsiveQuality ? { responsiveQuality } : {}),
+        pages,
+        manifestSha256,
+    };
+};
+//# sourceMappingURL=package-manifest-file.js.map

package/dist/package-manifest-file.js.map

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

package/dist/package-manifest-template.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The starting manifest `12ui convert package --template` prints.
+ *
+ * The manifest shape used to exist only as an example in skill prose, which
+ * made the format a thing an agent had to remember rather than a thing the tool
+ * hands out. This module is the single authored copy, and its test feeds it
+ * straight back through `readLocalPackageManifest` so the template cannot drift
+ * away from the parser that consumes it.
+ *
+ * Guidance goes to stderr in the command, never in here: stdout stays clean
+ * JSON so `12ui convert package --template > package.json` writes a file that
+ * parses.
+ */
+export declare const PACKAGE_MANIFEST_TEMPLATE_IMAGES: readonly ["screens/home-viewport-1.png", "screens/home-viewport-2.png", "screens/pricing-viewport-1.png"];
+export declare const packageManifestTemplate: () => Record<string, unknown>;
+export declare const renderPackageManifestTemplate: () => string;
+/**
+ * Printed to stderr beside the template. Says the things the JSON cannot: what
+ * a viewport is, and which field avoids paying twice for an image that already
+ * has a conversion.
+ */
+export declare const PACKAGE_MANIFEST_TEMPLATE_NOTES: string;
+//# sourceMappingURL=package-manifest-template.d.ts.map

package/dist/package-manifest-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-manifest-template.d.ts","sourceRoot":"","sources":["../src/package-manifest-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,gCAAgC,2GAInC,CAAC;AAEX,eAAO,MAAM,uBAAuB,QAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CA4B/D,CAAC;AAEH,eAAO,MAAM,6BAA6B,QAAO,MAEhD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,QAKhC,CAAC"}

package/dist/package-manifest-template.js

@@ -0,0 +1,60 @@
+/**
+ * The starting manifest `12ui convert package --template` prints.
+ *
+ * The manifest shape used to exist only as an example in skill prose, which
+ * made the format a thing an agent had to remember rather than a thing the tool
+ * hands out. This module is the single authored copy, and its test feeds it
+ * straight back through `readLocalPackageManifest` so the template cannot drift
+ * away from the parser that consumes it.
+ *
+ * Guidance goes to stderr in the command, never in here: stdout stays clean
+ * JSON so `12ui convert package --template > package.json` writes a file that
+ * parses.
+ */
+export const PACKAGE_MANIFEST_TEMPLATE_IMAGES = [
+    'screens/home-viewport-1.png',
+    'screens/home-viewport-2.png',
+    'screens/pricing-viewport-1.png',
+];
+export const packageManifestTemplate = () => ({
+    version: 1,
+    output: 'html',
+    responsiveQuality: 'standard',
+    pages: [
+        {
+            id: 'home',
+            kind: 'source',
+            title: 'Home',
+            path: '/',
+            // Ordered viewports of ONE continuous page. Two entries here means one
+            // page that scrolls, not two pages — that is the whole reason a package
+            // exists rather than two separate conversions.
+            viewports: [
+                { id: 'home-1', image: PACKAGE_MANIFEST_TEMPLATE_IMAGES[0] },
+                { id: 'home-2', image: PACKAGE_MANIFEST_TEMPLATE_IMAGES[1] },
+            ],
+        },
+        {
+            id: 'pricing',
+            kind: 'additional',
+            title: 'Pricing',
+            path: '/pricing',
+            viewports: [
+                { id: 'pricing-1', image: PACKAGE_MANIFEST_TEMPLATE_IMAGES[2] },
+            ],
+        },
+    ],
+});
+export const renderPackageManifestTemplate = () => (`${JSON.stringify(packageManifestTemplate(), null, 2)}\n`);
+/**
+ * Printed to stderr beside the template. Says the things the JSON cannot: what
+ * a viewport is, and which field avoids paying twice for an image that already
+ * has a conversion.
+ */
+export const PACKAGE_MANIFEST_TEMPLATE_NOTES = [
+    'Paths are relative to the manifest file.',
+    'Viewports are the ordered slices of one scrolling page; ordinals are filled in by position.',
+    'Add "sourceConversionId" to a viewport whose image already converted, to reuse it instead of buying it again.',
+    'Supported outputs: html and layerdoc. Export web_project or app_project from a finished conversion instead.',
+].join('\n');
+//# sourceMappingURL=package-manifest-template.js.map

package/dist/package-manifest-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-manifest-template.js","sourceRoot":"","sources":["../src/package-manifest-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC9C,6BAA6B;IAC7B,6BAA6B;IAC7B,gCAAgC;CACxB,CAAC;AAEX,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAA4B,EAAE,CAAC,CAAC;IACrE,OAAO,EAAE,CAAC;IACV,MAAM,EAAE,MAAM;IACd,iBAAiB,EAAE,UAAU;IAC7B,KAAK,EAAE;QACL;YACE,EAAE,EAAE,MAAM;YACV,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,MAAM;YACb,IAAI,EAAE,GAAG;YACT,uEAAuE;YACvE,wEAAwE;YACxE,+CAA+C;YAC/C,SAAS,EAAE;gBACT,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,gCAAgC,CAAC,CAAC,CAAC,EAAE;gBAC5D,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,gCAAgC,CAAC,CAAC,CAAC,EAAE;aAC7D;SACF;QACD;YACE,EAAE,EAAE,SAAS;YACb,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,SAAS;YAChB,IAAI,EAAE,UAAU;YAChB,SAAS,EAAE;gBACT,EAAE,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,gCAAgC,CAAC,CAAC,CAAC,EAAE;aAChE;SACF;KACF;CACF,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,6BAA6B,GAAG,GAAW,EAAE,CAAC,CACzD,GAAG,IAAI,CAAC,SAAS,CAAC,uBAAuB,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAC1D,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG;IAC7C,0CAA0C;IAC1C,6FAA6F;IAC7F,+GAA+G;IAC/G,6GAA6G;CAC9G,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC"}

package/dist/package-submission.d.ts

@@ -0,0 +1,103 @@
+import type { ConversionModel } from './conversion-models.js';
+import { type ConversionOutput } from './conversion-outputs.js';
+import type { ResponsiveConversionQuality } from './responsive-quality.js';
+import { TwelveUiConversionPackageClient, type ConversionPackageFile, type ConversionPackageLegacyManifest, type ConversionPackageOperation } from './package-client.js';
+/**
+ * One page, submitted as ONE package conversion of its ordered viewports.
+ *
+ * Converting a continuous page one screenshot at a time throws away page order
+ * and the stitching between viewports, which is the entire reason to have
+ * branched. This module is the single owner of that submission for both
+ * `12ui convert package` and `12ui branch execute --convert`.
+ */
+export declare const PACKAGE_RESULT_FILENAME = "package.result.json";
+export declare const PACKAGE_POLL_INTERVAL_MS = 4000;
+export declare const PACKAGE_TIMEOUT_MS: number;
+export type PackageImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp';
+export type PackageViewportInput = {
+    id: string;
+    ordinal: number;
+    imagePath: string;
+    bytes: Uint8Array;
+    mediaType: PackageImageMediaType;
+    /**
+     * An already-succeeded conversion of exactly these bytes. Attaching it skips
+     * both the upload and a second paid conversion of the same image — the reuse
+     * path that keeps a base conversion of the winner from being orphaned work.
+     */
+    sourceConversionId?: string;
+};
+export type PackagePageInput = {
+    id: string;
+    ordinal: number;
+    kind?: 'source' | 'additional';
+    title?: string;
+    purpose?: string;
+    path?: string;
+    viewports: PackageViewportInput[];
+};
+export type PackageSubmission = {
+    output: ConversionOutput;
+    model?: ConversionModel;
+    responsiveQuality?: ResponsiveConversionQuality;
+    pages: PackagePageInput[];
+    idempotencyKey: string;
+};
+export type PackagePageResult = {
+    id: string;
+    ordinal: number;
+    title?: string;
+    conversionId?: string;
+    outFile?: string;
+    sha256?: string;
+    bytes?: number;
+    mediaType?: string;
+    status: 'succeeded' | 'failed';
+    error?: string;
+};
+export type PackageSubmissionResult = {
+    packageId: string;
+    status: ConversionPackageOperation['status'];
+    output: ConversionOutput;
+    idempotencyKey: string;
+    pages: PackagePageResult[];
+    resultPath?: string;
+};
+export type PackageProgressEvent = {
+    stage: string;
+    percent?: number;
+    completed?: number;
+    total?: number;
+};
+/**
+ * The stitch precondition, checked HERE rather than at admission. Composition
+ * joins a page's viewports into one tall source, so a width disagreement is
+ * fatal — and the server discovers it only after every viewport is paid for.
+ */
+export declare const assertPackagePageWidths: (pages: readonly PackagePageInput[]) => Promise<Map<string, {
+    width: number;
+    height: number;
+}>>;
+export declare const buildConversionPackageRequest: (submission: PackageSubmission) => Promise<{
+    manifest: ConversionPackageLegacyManifest;
+    screenshots: ConversionPackageFile[];
+}>;
+/**
+ * Submit, wait, and materialize. The package's own operation record is the
+ * durable identity: a retry under the same derived key replays it rather than
+ * buying the pages again.
+ */
+export declare const submitConversionPackage: (args: {
+    client: TwelveUiConversionPackageClient;
+    submission: PackageSubmission;
+    outDir: string;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    /** Fires as soon as the package has an id, before the long wait begins. */
+    onSubmitted?: (packageId: string) => void;
+    onProgress?: (event: PackageProgressEvent) => void;
+    sleep?: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+    signal?: AbortSignal;
+}) => Promise<PackageSubmissionResult>;
+export declare const writePackageResultRecord: (outDir: string, result: PackageSubmissionResult) => Promise<string>;
+//# sourceMappingURL=package-submission.d.ts.map

package/dist/package-submission.d.ts.map

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

package/dist/package-submission.js

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { CONVERSION_OUTPUT_EXTENSIONS, } from './conversion-outputs.js';
+import { readImageDimensions } from './image-dimensions.js';
+/**
+ * One page, submitted as ONE package conversion of its ordered viewports.
+ *
+ * Converting a continuous page one screenshot at a time throws away page order
+ * and the stitching between viewports, which is the entire reason to have
+ * branched. This module is the single owner of that submission for both
+ * `12ui convert package` and `12ui branch execute --convert`.
+ */
+export const PACKAGE_RESULT_FILENAME = 'package.result.json';
+export const PACKAGE_POLL_INTERVAL_MS = 4_000;
+export const PACKAGE_TIMEOUT_MS = 30 * 60_000;
+/**
+ * The stitch precondition, checked HERE rather than at admission. Composition
+ * joins a page's viewports into one tall source, so a width disagreement is
+ * fatal — and the server discovers it only after every viewport is paid for.
+ */
+export const assertPackagePageWidths = async (pages) => {
+    const dimensions = new Map();
+    for (const page of pages) {
+        if (page.viewports.length === 0) {
+            throw new Error(`Page ${page.id} has no viewports to convert.`);
+        }
+        for (const viewport of page.viewports) {
+            dimensions.set(`${page.id}/${viewport.id}`, await readImageDimensions(viewport.bytes));
+        }
+        const first = dimensions.get(`${page.id}/${page.viewports[0].id}`);
+        const mismatched = page.viewports.find((viewport) => (dimensions.get(`${page.id}/${viewport.id}`).width !== first.width));
+        if (mismatched) {
+            const actual = dimensions.get(`${page.id}/${mismatched.id}`);
+            throw new Error(`Page ${page.id} screen ${mismatched.id} (${mismatched.imagePath}) is ${actual.width}px`
+                + ` wide but the page is ${first.width}px wide; every viewport of a page must share one`
+                + ' width. Re-render or crop the odd screen before submitting the page.');
+        }
+    }
+    return dimensions;
+};
+export const buildConversionPackageRequest = async (submission) => {
+    const dimensions = await assertPackagePageWidths(submission.pages);
+    const screenshots = [];
+    const manifest = {
+        version: 1,
+        output: submission.output,
+        ...(submission.model ? { model: submission.model } : {}),
+        ...(submission.responsiveQuality && submission.output === 'html'
+            ? { responsive_quality: submission.responsiveQuality }
+            : {}),
+        pages: submission.pages.map((page) => ({
+            id: page.id,
+            ordinal: page.ordinal,
+            ...(page.kind ? { kind: page.kind } : {}),
+            ...(page.title ? { title: page.title } : {}),
+            ...(page.purpose ? { purpose: page.purpose } : {}),
+            ...(page.path ? { path: page.path } : {}),
+            viewports: page.viewports.map((viewport) => {
+                const size = dimensions.get(`${page.id}/${viewport.id}`);
+                if (viewport.sourceConversionId) {
+                    return {
+                        id: viewport.id,
+                        ordinal: viewport.ordinal,
+                        source_conversion_id: viewport.sourceConversionId,
+                        screenshot: {
+                            sha256: createHash('sha256').update(viewport.bytes).digest('hex'),
+                            media_type: viewport.mediaType,
+                            size_bytes: viewport.bytes.byteLength,
+                            width: size.width,
+                            height: size.height,
+                        },
+                    };
+                }
+                const partId = `${page.id}--${viewport.id}`;
+                screenshots.push({ partId, bytes: viewport.bytes, mediaType: viewport.mediaType });
+                return { id: viewport.id, ordinal: viewport.ordinal, screenshot_part: partId };
+            }),
+        })),
+    };
+    return { manifest, screenshots };
+};
+const delay = async (milliseconds, signal) => (new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, milliseconds);
+    signal?.addEventListener('abort', () => {
+        clearTimeout(timer);
+        reject(signal.reason ?? new Error('Package wait aborted'));
+    }, { once: true });
+}));
+/**
+ * Submit, wait, and materialize. The package's own operation record is the
+ * durable identity: a retry under the same derived key replays it rather than
+ * buying the pages again.
+ */
+export const submitConversionPackage = async (args) => {
+    const { manifest, screenshots } = await buildConversionPackageRequest(args.submission);
+    const sleep = args.sleep ?? delay;
+    const created = await args.client.createPackage({
+        manifest,
+        screenshots,
+        idempotencyKey: args.submission.idempotencyKey,
+        ...(args.signal ? { signal: args.signal } : {}),
+    });
+    args.onSubmitted?.(created.id);
+    const deadline = Date.now() + (args.timeoutMs ?? PACKAGE_TIMEOUT_MS);
+    let operation = created;
+    while (operation.status === 'queued' || operation.status === 'running') {
+        if (Date.now() >= deadline) {
+            throw new Error(`Timed out waiting for package ${created.id}. It is still running server-side; read it`
+                + ` back with GET /api/v1/convert/package/${created.id} rather than submitting again.`);
+        }
+        args.onProgress?.({
+            stage: operation.progress?.stage ?? operation.status,
+            ...(operation.progress?.percent === undefined ? {} : { percent: operation.progress.percent }),
+            ...(operation.progress?.completed === undefined
+                ? {}
+                : { completed: operation.progress.completed, total: operation.progress.total }),
+        });
+        await sleep(args.pollIntervalMs ?? PACKAGE_POLL_INTERVAL_MS, args.signal);
+        operation = await args.client.getPackage(created.id, args.signal);
+    }
+    args.onProgress?.({ stage: operation.status });
+    await mkdir(args.outDir, { recursive: true });
+    const extension = CONVERSION_OUTPUT_EXTENSIONS[args.submission.output];
+    const pages = [];
+    for (const page of operation.pages) {
+        if (page.status !== 'succeeded' || !page.href) {
+            pages.push({
+                id: page.id,
+                ordinal: page.ordinal,
+                ...(page.title ? { title: page.title } : {}),
+                status: 'failed',
+                error: operation.error?.detail ?? `Page ${page.id} finished ${page.status}.`,
+            });
+            continue;
+        }
+        const downloaded = await args.client.downloadPage(operation, page.id, args.signal);
+        const outFile = path.join(args.outDir, `${page.id}.${extension}`);
+        await writeFile(outFile, downloaded.bytes);
+        pages.push({
+            id: page.id,
+            ordinal: page.ordinal,
+            ...(page.title ? { title: page.title } : {}),
+            ...(page.conversion_id ? { conversionId: page.conversion_id } : {}),
+            outFile,
+            sha256: createHash('sha256').update(downloaded.bytes).digest('hex'),
+            bytes: downloaded.bytes.byteLength,
+            mediaType: downloaded.mediaType,
+            status: 'succeeded',
+        });
+    }
+    if (operation.status !== 'succeeded' && pages.every((page) => page.status === 'failed')) {
+        throw new Error(operation.error?.detail
+            ?? `Package ${operation.id} finished ${operation.status} with no converted page.`);
+    }
+    return {
+        packageId: operation.id,
+        status: operation.status,
+        output: args.submission.output,
+        idempotencyKey: args.submission.idempotencyKey,
+        pages,
+    };
+};
+export const writePackageResultRecord = async (outDir, result) => {
+    const file = path.join(outDir, PACKAGE_RESULT_FILENAME);
+    await mkdir(outDir, { recursive: true });
+    await writeFile(file, `${JSON.stringify({ version: 1, ...result }, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    return file;
+};
+//# sourceMappingURL=package-submission.js.map

package/dist/package-submission.js.map

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

package/dist/selection-record.d.ts

@@ -0,0 +1,95 @@
+import type { DraftRecord } from './draft-workspace.js';
+/**
+ * `selection.json`, version 6 — the same contract the skill used to ask an
+ * agent to hand-assemble from four other files. Every field here is copied
+ * from durable evidence the run already wrote, which is the point: a record
+ * assembled by hand can disagree with the run it describes, and this one
+ * cannot.
+ *
+ * The recommendation protocol is preserved exactly: `recommended` when the
+ * winner is the recommended candidate, `override` when it is not (and then a
+ * specific reason is required), `no-recommendation` when the run indicated
+ * none.
+ */
+export declare const SELECTION_RECORD_VERSION = 6;
+export type SelectionRecord = {
+    version: 6;
+    createdAt: string;
+    requestSummary: string;
+    viewportMode: 'first-viewport';
+    designMode: DraftRecord['mode'];
+    redesignSource: {
+        originalPath: string | null;
+        originalSha256: string | null;
+        preparedPath: string | null;
+        preparedSha256: string | null;
+        preparation: 'none' | 'first-viewport-crop';
+    };
+    contract: {
+        preserve: string[];
+        change: string[];
+    };
+    referencePolicy: {
+        retrieval: 'text-only' | 'text-and-redesign-source';
+        generation: 'one-corpus-image-per-candidate' | 'redesign-source-only';
+        imagesPerGeneration: 1;
+    };
+    corpus: {
+        query: string;
+        mode: string;
+        fallback: null;
+        idempotencyKey: string;
+        setId: string;
+        references: {
+            id: string;
+            path: string;
+            sha256: string;
+            aspect: string;
+        }[];
+    };
+    generation: {
+        referenceMode: 'inspiration' | 'preserve-structure';
+        manifestPath: string;
+        manifestSha256: string;
+        batchAttemptPath: string;
+    };
+    candidates: {
+        id: string;
+        path: string;
+        sha256: string | null;
+        prompt: string;
+        promptSha256: string;
+        directionReferenceId: string | null;
+        direction: string;
+        generationReferencePath: string;
+        generationReferenceSha256: string;
+        referenceMode: 'inspiration' | 'preserve-structure';
+        provider: string | null;
+        idempotencyKey: string;
+        providerIdempotencyEnforced: boolean;
+        attemptEvidencePath: string;
+        rejectionReasons: string[];
+    }[];
+    recommendation: {
+        candidateId: string | null;
+        source: string | null;
+    };
+    winner: string;
+    selectionSource: 'recommended' | 'override' | 'no-recommendation';
+    selectionOverrideReason: string | null;
+    rationale: string;
+};
+export declare const buildSelectionRecord: (args: {
+    draft: DraftRecord;
+    winner: string;
+    reason: string;
+    recommendation?: {
+        candidateId: string | null;
+        source: string | null;
+    };
+    rejectionReasons?: Record<string, string[]>;
+    now?: () => Date;
+}) => Promise<SelectionRecord>;
+export declare const writeSelectionRecord: (file: string, record: SelectionRecord) => Promise<void>;
+export declare const readSelectionRecord: (file: string) => Promise<SelectionRecord | undefined>;
+//# sourceMappingURL=selection-record.d.ts.map

package/dist/selection-record.d.ts.map

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