@12ui/design 0.2.36 → 0.2.38

package/dist/prototype-run-record.d.ts.map

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

package/dist/prototype-run-record.js

@@ -0,0 +1,236 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * The prototype post-step is deliberately recorded separately from the branch
+ * run. A branch can be settled while this optional derived artifact is still
+ * running, failed, or ready to retry.
+ */
+export const PROTOTYPE_STATUS_FILENAME = 'prototype.status.json';
+export const prototypeStatusPath = (branchDir) => (path.join(branchDir, PROTOTYPE_STATUS_FILENAME));
+const invalidRecord = (file) => new Error(`Invalid prototype status record: ${file}`);
+const nonEmptyString = (value) => (typeof value === 'string' && value.trim().length > 0);
+const parsePrototypeRunRecord = (source, file) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch (error) {
+        throw new Error(`Invalid prototype status record: ${file}`, { cause: error });
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw invalidRecord(file);
+    }
+    const value = parsed;
+    if (value.version !== 1
+        || !nonEmptyString(value.runId)
+        || !nonEmptyString(value.inputDigest)
+        || !Number.isSafeInteger(value.attempt)
+        || value.attempt < 1
+        || !nonEmptyString(value.startedAt)
+        || !Number.isFinite(Date.parse(value.startedAt))
+        || !nonEmptyString(value.updatedAt)
+        || !Number.isFinite(Date.parse(value.updatedAt))) {
+        throw invalidRecord(file);
+    }
+    const base = {
+        version: 1,
+        runId: value.runId,
+        inputDigest: value.inputDigest,
+        attempt: value.attempt,
+        startedAt: value.startedAt,
+        updatedAt: value.updatedAt,
+    };
+    switch (value.status) {
+        case 'running':
+            return { ...base, status: 'running' };
+        case 'succeeded':
+            if (!nonEmptyString(value.manifestPath))
+                throw invalidRecord(file);
+            return { ...base, status: 'succeeded', manifestPath: value.manifestPath };
+        case 'failed': {
+            if (value.error === null || typeof value.error !== 'object' || Array.isArray(value.error)) {
+                throw invalidRecord(file);
+            }
+            const error = value.error;
+            if (!nonEmptyString(error.name)
+                || !nonEmptyString(error.message)
+                || (error.stack !== undefined && typeof error.stack !== 'string')) {
+                throw invalidRecord(file);
+            }
+            return {
+                ...base,
+                status: 'failed',
+                error: {
+                    name: error.name,
+                    message: error.message,
+                    ...(typeof error.stack === 'string' ? { stack: error.stack } : {}),
+                },
+            };
+        }
+        case 'skipped':
+            if (!nonEmptyString(value.reason)
+                || (value.detail !== undefined && typeof value.detail !== 'string')) {
+                throw invalidRecord(file);
+            }
+            return {
+                ...base,
+                status: 'skipped',
+                reason: value.reason,
+                ...(typeof value.detail === 'string' ? { detail: value.detail } : {}),
+            };
+        default:
+            throw invalidRecord(file);
+    }
+};
+export const readPrototypeRunRecord = async (branchDir) => {
+    const file = prototypeStatusPath(branchDir);
+    let source;
+    try {
+        source = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    return parsePrototypeRunRecord(source, file);
+};
+/**
+ * A synced temporary inode is renamed over the destination, then the parent
+ * directory is synced. Readers therefore see the previous whole record or the
+ * next whole record, and the rename survives a process or machine interruption.
+ */
+export const writePrototypeRunRecord = async (branchDir, record) => {
+    const file = prototypeStatusPath(branchDir);
+    const parent = path.dirname(file);
+    await mkdir(parent, { recursive: true });
+    const temporary = path.join(parent, `.${PROTOTYPE_STATUS_FILENAME}.${randomUUID()}.tmp`);
+    let temporaryHandle;
+    try {
+        temporaryHandle = await open(temporary, 'wx', 0o600);
+        await temporaryHandle.writeFile(`${JSON.stringify(record, null, 2)}\n`, 'utf8');
+        await temporaryHandle.sync();
+        await temporaryHandle.close();
+        temporaryHandle = undefined;
+        await rename(temporary, file);
+        const directoryHandle = await open(parent, 'r');
+        try {
+            await directoryHandle.sync();
+        }
+        finally {
+            await directoryHandle.close();
+        }
+    }
+    finally {
+        await temporaryHandle?.close();
+        await rm(temporary, { force: true });
+    }
+};
+const timestamp = (now) => (now ?? (() => new Date()))().toISOString();
+export const startPrototypeRunRecord = async (args) => {
+    const previous = await readPrototypeRunRecord(args.branchDir);
+    const startedAt = timestamp(args.now);
+    const record = {
+        version: 1,
+        status: 'running',
+        runId: args.runId,
+        inputDigest: args.inputDigest,
+        attempt: previous?.runId === args.runId && previous.inputDigest === args.inputDigest
+            ? previous.attempt + 1
+            : 1,
+        startedAt,
+        updatedAt: startedAt,
+    };
+    await writePrototypeRunRecord(args.branchDir, record);
+    return record;
+};
+const updatedRecordBase = (running, now) => ({
+    version: 1,
+    runId: running.runId,
+    inputDigest: running.inputDigest,
+    attempt: running.attempt,
+    startedAt: running.startedAt,
+    updatedAt: timestamp(now),
+});
+export const succeedPrototypeRunRecord = async (args) => {
+    const record = {
+        ...updatedRecordBase(args.running, args.now),
+        status: 'succeeded',
+        manifestPath: args.manifestPath,
+    };
+    await writePrototypeRunRecord(args.branchDir, record);
+    return record;
+};
+const durableError = (error) => {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            ...(error.stack ? { stack: error.stack } : {}),
+        };
+    }
+    return { name: 'Error', message: String(error) };
+};
+export const failPrototypeRunRecord = async (args) => {
+    const record = {
+        ...updatedRecordBase(args.running, args.now),
+        status: 'failed',
+        error: durableError(args.error),
+    };
+    await writePrototypeRunRecord(args.branchDir, record);
+    return record;
+};
+export const skipPrototypeRunRecord = async (args) => {
+    const record = {
+        ...updatedRecordBase(args.running, args.now),
+        status: 'skipped',
+        reason: args.reason,
+        ...(args.detail === undefined ? {} : { detail: args.detail }),
+    };
+    await writePrototypeRunRecord(args.branchDir, record);
+    return record;
+};
+const fileExists = async (file) => {
+    try {
+        return (await stat(file)).isFile();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+};
+const fromBranchRoot = (branchDir, file) => (path.isAbsolute(file) ? file : path.join(branchDir, file));
+/**
+ * Decide whether a caller can adopt a settled prototype or must run it again.
+ * A legacy manifest remains adoptable only while no sidecar exists; once a
+ * sidecar exists, its digest and status are authoritative.
+ */
+export const resolvePrototypeRunRecord = async (args) => {
+    const record = await readPrototypeRunRecord(args.branchDir);
+    if (!record) {
+        const manifestPath = fromBranchRoot(args.branchDir, args.legacyManifestPath);
+        return await fileExists(manifestPath)
+            ? { action: 'settled', reason: 'legacy-manifest', adoptable: true, manifestPath }
+            : { action: 'retry', reason: 'missing' };
+    }
+    if (record.inputDigest !== args.inputDigest) {
+        return { action: 'retry', reason: 'input-changed', record };
+    }
+    switch (record.status) {
+        case 'succeeded': {
+            const manifestPath = fromBranchRoot(args.branchDir, record.manifestPath);
+            return await fileExists(manifestPath)
+                ? { action: 'settled', reason: 'succeeded', adoptable: true, manifestPath, record }
+                : { action: 'retry', reason: 'manifest-missing', record };
+        }
+        case 'skipped':
+            return { action: 'settled', reason: 'skipped', adoptable: false, record };
+        case 'running':
+            return { action: 'retry', reason: 'running', record };
+        case 'failed':
+            return { action: 'retry', reason: 'failed', record };
+    }
+};
+//# sourceMappingURL=prototype-run-record.js.map

package/dist/prototype-run-record.js.map

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

package/dist/prototype-runner.d.ts

@@ -1,9 +1,10 @@
 import type { TwelveUiPrototypeLabelClient } from './prototype-label-client.js';
+import { type PrototypeBranchContract } from './prototype-branch-contract.js';
 import { type PrototypeStageResult } from './prototype-process.js';
 export declare const PROTOTYPE_MANIFEST_FILENAME = "proto-manifest.json";
 export declare const PROTOTYPE_DIRECTORY = "prototype";
 export declare const PROTOTYPE_WORK_DIRECTORY = ".prototype-work";
-export declare const PROTOTYPE_PIPELINE_REVISION = "prototype-v2";
+export declare const PROTOTYPE_PIPELINE_REVISION = "prototype-v3";
 export type PrototypeRunResult = {
     branchDir: string;
     outputDir: string;
@@ -14,8 +15,19 @@ export type PrototypeRunResult = {
     labelCostMicros: number;
     warnings: string[];
 };
+export declare class PrototypeNavigationSkippedError extends Error {
+    readonly reason: 'prototype_navigation_unreconciled' | 'prototype_navigation_no_survivors';
+    readonly detail: string;
+    constructor(args: {
+        reason: PrototypeNavigationSkippedError['reason'];
+        detail: string;
+    });
+}
 export declare const runPrototypePipeline: (args: {
     branchDir: string;
+    contract?: Exclude<PrototypeBranchContract, {
+        mode: "skip";
+    }>;
     environment?: NodeJS.ProcessEnv;
     homeDirectory?: string;
     labelClient?: TwelveUiPrototypeLabelClient;

package/dist/prototype-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prototype-runner.d.ts","sourceRoot":"","sources":["../src/prototype-runner.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAIhF,OAAO,EAAqB,KAAK,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAItF,eAAO,MAAM,2BAA2B,wBAAwB,CAAC;AACjE,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAC/C,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAC1D,eAAO,MAAM,2BAA2B,iBAAiB,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAOF,eAAO,MAAM,oBAAoB,GAAU,MAAM;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,4BAA4B,CAAC;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAG,OAAO,CAAC,kBAAkB,CAqK7B,CAAC"}
+{"version":3,"file":"prototype-runner.d.ts","sourceRoot":"","sources":["../src/prototype-runner.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,6BAA6B,CAAC;AAChF,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,gCAAgC,CAAC;AAIxC,OAAO,EAAqB,KAAK,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAUtF,eAAO,MAAM,2BAA2B,wBAAwB,CAAC;AACjE,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAC/C,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAC1D,eAAO,MAAM,2BAA2B,iBAAiB,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAAC;AAEF,qBAAa,+BAAgC,SAAQ,KAAK;IACxD,QAAQ,CAAC,MAAM,EAAE,mCAAmC,GAAG,mCAAmC,CAAC;IAC3F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,IAAI,EAAE;QAChB,MAAM,EAAE,+BAA+B,CAAC,QAAQ,CAAC,CAAC;QAClD,MAAM,EAAE,MAAM,CAAC;KAChB;CAMF;AAOD,eAAO,MAAM,oBAAoB,GAAU,MAAM;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC,uBAAuB,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,4BAA4B,CAAC;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAG,OAAO,CAAC,kBAAkB,CA2N7B,CAAC"}

package/dist/prototype-runner.js

@@ -2,20 +2,47 @@ import { randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { resolvePrototypeBranchContract, } from './prototype-branch-contract.js';
 import { resolvePrototypeBrowserProvisioning } from './prototype-browsers.js';
 import { evaluatePrototypeGates } from './prototype-gates.js';
 import { prototypeLabelRequests } from './prototype-requests.js';
 import { runPrototypeStage } from './prototype-process.js';
+import { failPrototypeRunRecord, skipPrototypeRunRecord, startPrototypeRunRecord, succeedPrototypeRunRecord, } from './prototype-run-record.js';
 import { prototypeSourceDirectory } from './prototype-source.js';
 import { BRANCH_COMPLETION_FILENAME, BRANCH_PLAN_FILENAME } from './branch-run-record.js';
 export const PROTOTYPE_MANIFEST_FILENAME = 'proto-manifest.json';
 export const PROTOTYPE_DIRECTORY = 'prototype';
 export const PROTOTYPE_WORK_DIRECTORY = '.prototype-work';
-export const PROTOTYPE_PIPELINE_REVISION = 'prototype-v2';
+export const PROTOTYPE_PIPELINE_REVISION = 'prototype-v3';
+export class PrototypeNavigationSkippedError extends Error {
+    reason;
+    detail;
+    constructor(args) {
+        super(`Prototype skipped (${args.reason}): ${args.detail}`);
+        this.name = 'PrototypeNavigationSkippedError';
+        this.reason = args.reason;
+        this.detail = args.detail;
+    }
+}
 const kitDirectory = () => path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../prototype-kit');
 export const runPrototypePipeline = async (args) => {
     const branchDir = path.resolve(args.branchDir);
     const sourceDir = await prototypeSourceDirectory(branchDir);
+    const contract = args.contract ?? await resolvePrototypeBranchContract({ branchDir, sourceDir });
+    const running = await startPrototypeRunRecord({
+        branchDir,
+        runId: contract.runId || 'unresolved',
+        inputDigest: contract.inputDigest,
+    });
+    if (contract.mode === 'skip') {
+        await skipPrototypeRunRecord({
+            branchDir,
+            running,
+            reason: contract.reason,
+            detail: contract.detail,
+        });
+        throw new PrototypeNavigationSkippedError(contract);
+    }
     const planPath = path.join(sourceDir, BRANCH_PLAN_FILENAME);
     const completionPath = path.join(branchDir, BRANCH_COMPLETION_FILENAME);
     const completion = JSON.parse(await readFile(completionPath, 'utf8'));
@@ -29,18 +56,22 @@ export const runPrototypePipeline = async (args) => {
     const modelFile = path.join(workDir, 'model.json');
     const runtimeAuditFile = path.join(workDir, 'runtime-audit.json');
     const gateAuditFile = path.join(workDir, 'gate-audit.json');
+    const reviewFile = path.join(workDir, 'review.json');
     const stagingDir = path.join(branchDir, `.prototype-${randomUUID()}.tmp`);
     const outputDir = path.join(branchDir, PROTOTYPE_DIRECTORY);
-    const browserProvisioning = await resolvePrototypeBrowserProvisioning({
-        ...(args.environment ? { environment: args.environment } : {}),
-        ...(args.homeDirectory ? { homeDirectory: args.homeDirectory } : {}),
-        ...(args.platform ? { platform: args.platform } : {}),
-    });
     await rm(workDir, { recursive: true, force: true });
     await mkdir(labelsDir, { recursive: true });
     await mkdir(stagingDir, { recursive: true });
     const stages = [];
     try {
+        const browserProvisioning = await resolvePrototypeBrowserProvisioning({
+            ...(args.environment ? { environment: args.environment } : {}),
+            ...(args.homeDirectory ? { homeDirectory: args.homeDirectory } : {}),
+            ...(args.platform ? { platform: args.platform } : {}),
+        });
+        if (contract.mode === 'review') {
+            await writeFile(reviewFile, `${JSON.stringify(contract.review, null, 2)}\n`);
+        }
         stages.push(await runPrototypeStage({
             stage: 'inventory',
             script: path.join(kit, 'inventory.mjs'),
@@ -52,7 +83,7 @@ export const runPrototypePipeline = async (args) => {
         stages.push(await runPrototypeStage({
             stage: 'analyze',
             script: path.join(kit, 'analyze.mjs'),
-            argv: [inventoryFile, modelFile],
+            argv: [inventoryFile, modelFile, ...(contract.mode === 'review' ? [reviewFile] : [])],
             workDir,
             browserProvisioning,
             ...(args.signal ? { signal: args.signal } : {}),
@@ -89,19 +120,30 @@ export const runPrototypePipeline = async (args) => {
         const kitManifest = JSON.parse(await readFile(manifestPath, 'utf8'));
         const inventory = JSON.parse(await readFile(inventoryFile, 'utf8'));
         const runtimeAudit = JSON.parse(await readFile(runtimeAuditFile, 'utf8'));
+        const viewportWidths = [...new Set(runtimeAudit.pages.flatMap((page) => (page.viewports?.map((viewport) => viewport.width).filter((width) => Number.isFinite(width)) || [])))].sort((left, right) => left - right);
         const evaluation = evaluatePrototypeGates(kitManifest);
-        const planStatus = Array.isArray(inventory.plan?.pages) && Array.isArray(inventory.plan?.screens)
-            ? 'passed'
-            : 'accepted-partial';
+        const planStatus = contract.mode === 'review'
+            ? 'accepted-partial'
+            : Array.isArray(inventory.plan?.pages) && Array.isArray(inventory.plan?.screens)
+                ? 'passed'
+                : 'accepted-partial';
+        const reviewStatus = (failed) => (failed && contract.mode === 'review' ? 'accepted-partial' : failed ? 'failed' : 'passed');
         const gates = {
             exportedHtml: 'passed',
             branchPlan: planStatus,
             semanticViewportSections: 'passed',
             runtime: 'passed',
-            zeroActionRealPages: evaluation.facts.zeroActionRealPages.length > 0 ? 'failed' : 'passed',
-            dropdownValidity: evaluation.facts.invalidDropdowns > 0 ? 'failed' : 'passed',
-            holdingRatio: evaluation.facts.holdingRatio > 0.5 ? 'failed' : 'passed',
+            shellConsistency: runtimeAudit.shellConsistencyFailures.length > 0 ? 'failed' : 'passed',
+            activeNavigation: runtimeAudit.activeNavigationFailures.length > 0 ? 'failed' : 'passed',
+            zeroActionRealPages: reviewStatus(evaluation.facts.zeroActionRealPages.length > 0),
+            dropdownValidity: reviewStatus(evaluation.facts.invalidDropdowns > 0),
+            holdingRatio: reviewStatus(evaluation.facts.holdingRatio > 0.5),
         };
+        const reviewFindings = contract.mode === 'review' ? evaluation.blockers : [];
+        const blockers = contract.mode === 'review' ? [] : evaluation.blockers;
+        const warnings = contract.mode === 'review'
+            ? [...evaluation.warnings, ...reviewFindings]
+            : evaluation.warnings;
         await writeFile(gateAuditFile, `${JSON.stringify({
             version: 1,
             revision: PROTOTYPE_PIPELINE_REVISION,
@@ -112,11 +154,16 @@ export const runPrototypePipeline = async (args) => {
             },
             gates,
             facts: evaluation.facts,
-            warnings: evaluation.warnings,
-            blockers: evaluation.blockers,
+            warnings,
+            blockers,
+            ...(reviewFindings.length > 0 ? { reviewFindings } : {}),
         }, null, 2)}\n`);
-        if (evaluation.blockers.length > 0) {
-            throw new Error(`Prototype product gate failed: ${evaluation.blockers.join(' ')}`);
+        if (blockers.length > 0) {
+            throw new Error(`Prototype product gate failed: ${blockers.join(' ')}`);
+        }
+        if (contract.mode === 'review'
+            && JSON.stringify(kitManifest.review) !== JSON.stringify(contract.review)) {
+            throw new Error('Prototype review contract changed between input reconciliation and build.');
         }
         await writeFile(manifestPath, `${JSON.stringify({
             ...kitManifest,
@@ -143,14 +190,19 @@ export const runPrototypePipeline = async (args) => {
                 duplicateIds: runtimeAudit.duplicateIds,
                 brokenTargets: runtimeAudit.brokenTargets.length,
                 interactionFailures: runtimeAudit.interactionFailures,
+                compositionFailures: runtimeAudit.compositionFailures,
+                shellConsistencyFailures: runtimeAudit.shellConsistencyFailures,
+                activeNavigationFailures: runtimeAudit.activeNavigationFailures,
+                viewportWidths,
                 deepLinkBack: runtimeAudit.deepLinkBack,
             },
             facts: evaluation.facts,
-            warnings: evaluation.warnings,
+            warnings,
+            ...(reviewFindings.length > 0 ? { reviewFindings } : {}),
         }, null, 2)}\n`);
         await rm(outputDir, { recursive: true, force: true });
         await rename(stagingDir, outputDir);
-        return {
+        const result = {
             branchDir,
             outputDir,
             manifestPath: path.join(outputDir, PROTOTYPE_MANIFEST_FILENAME),
@@ -158,11 +210,18 @@ export const runPrototypePipeline = async (args) => {
             screenCount: model.states.length,
             labeledScreenCount,
             labelCostMicros,
-            warnings: evaluation.warnings,
+            warnings,
         };
+        await succeedPrototypeRunRecord({
+            branchDir,
+            running,
+            manifestPath: result.manifestPath,
+        });
+        return result;
     }
     catch (error) {
         await rm(stagingDir, { recursive: true, force: true });
+        await failPrototypeRunRecord({ branchDir, running, error });
         throw error;
     }
 };

package/dist/prototype-runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"prototype-runner.js","sourceRoot":"","sources":["../src/prototype-runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"prototype-runner.js","sourceRoot":"","sources":["../src/prototype-runner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAGzC,OAAO,EACL,8BAA8B,GAE/B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,mCAAmC,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,sBAAsB,EAA4B,MAAM,sBAAsB,CAAC;AACxF,OAAO,EAAE,sBAAsB,EAAuB,MAAM,yBAAyB,CAAC;AACtF,OAAO,EAAE,iBAAiB,EAA6B,MAAM,wBAAwB,CAAC;AACtF,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,0BAA0B,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE1F,MAAM,CAAC,MAAM,2BAA2B,GAAG,qBAAqB,CAAC;AACjE,MAAM,CAAC,MAAM,mBAAmB,GAAG,WAAW,CAAC;AAC/C,MAAM,CAAC,MAAM,wBAAwB,GAAG,iBAAiB,CAAC;AAC1D,MAAM,CAAC,MAAM,2BAA2B,GAAG,cAAc,CAAC;AAa1D,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IAC/C,MAAM,CAA4E;IAClF,MAAM,CAAS;IAExB,YAAY,IAGX;QACC,KAAK,CAAC,sBAAsB,IAAI,CAAC,MAAM,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;QAC9C,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC5B,CAAC;CACF;AAED,MAAM,YAAY,GAAG,GAAW,EAAE,CAAC,IAAI,CAAC,OAAO,CAC7C,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAC5C,kBAAkB,CACnB,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,EAAE,IAQ1C,EAA+B,EAAE;IAChC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,MAAM,wBAAwB,CAAC,SAAS,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,MAAM,8BAA8B,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC;IACjG,MAAM,OAAO,GAAG,MAAM,uBAAuB,CAAC;QAC5C,SAAS;QACT,KAAK,EAAE,QAAQ,CAAC,KAAK,IAAI,YAAY;QACrC,WAAW,EAAE,QAAQ,CAAC,WAAW;KAClC,CAAC,CAAC;IACH,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC7B,MAAM,sBAAsB,CAAC;YAC3B,SAAS;YACT,OAAO;YACP,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,MAAM,EAAE,QAAQ,CAAC,MAAM;SACxB,CAAC,CAAC;QACH,MAAM,IAAI,+BAA+B,CAAC,QAAQ,CAAC,CAAC;IACtD,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC;IAC5D,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,0BAA0B,CAAC,CAAC;IACxE,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,CAAwB,CAAC;IAC7F,IAAI,OAAO,UAAU,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QAC9D,MAAM,IAAI,KAAK,CAAC,0BAA0B,cAAc,wBAAwB,CAAC,CAAC;IACpF,CAAC;IACD,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC;IAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,wBAAwB,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC/C,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IAC3D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IACnD,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;IAClE,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAC5D,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;IACrD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,UAAU,EAAE,MAAM,CAAC,CAAC;IAC1E,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,mBAAmB,CAAC,CAAC;IAC5D,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,mBAAmB,GAAG,MAAM,mCAAmC,CAAC;YACpE,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtD,CAAC,CAAC;QACH,IAAI,QAAQ,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC/B,MAAM,SAAS,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QAC/E,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,MAAM,iBAAiB,CAAC;YAClC,KAAK,EAAE,WAAW;YAClB,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC;YACvC,IAAI,EAAE,CAAC,SAAS,EAAE,aAAa,CAAC;YAChC,OAAO;YACP,mBAAmB;YACnB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC,CAAC,CAAC;QACJ,MAAM,CAAC,IAAI,CAAC,MAAM,iBAAiB,CAAC;YAClC,KAAK,EAAE,SAAS;YAChB,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAC;YACrC,IAAI,EAAE,CAAC,aAAa,EAAE,SAAS,EAAE,GAAG,CAAC,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACrF,OAAO;YACP,mBAAmB;YACnB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC,CAAC,CAAC;QACJ,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,CAAmB,CAAC;QAC9E,MAAM,QAAQ,GAAG,sBAAsB,CAAC,KAAK,CAAC,CAAC;QAC/C,IAAI,eAAe,GAAG,CAAC,CAAC;QACxB,IAAI,kBAAkB,GAAG,CAAC,CAAC;QAC3B,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC/B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC5F,eAAe,IAAI,QAAQ,CAAC,UAAU,CAAC;gBACvC,kBAAkB,IAAI,CAAC,CAAC;gBACxB,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,EACjD,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAC9D,CAAC;YACJ,CAAC;QACH,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,MAAM,iBAAiB,CAAC;YAClC,KAAK,EAAE,OAAO;YACd,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC;YACnC,IAAI,EAAE,CAAC,SAAS,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,CAAC;YAClE,OAAO;YACP,mBAAmB;YACnB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC,CAAC,CAAC;QACJ,MAAM,CAAC,IAAI,CAAC,MAAM,iBAAiB,CAAC;YAClC,KAAK,EAAE,SAAS;YAChB,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,oBAAoB,CAAC;YAC5C,IAAI,EAAE,CAAC,UAAU,EAAE,gBAAgB,CAAC;YACpC,OAAO;YACP,mBAAmB;YACnB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC,CAAC,CAAC;QACJ,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,2BAA2B,CAAC,CAAC;QACxE,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAA4B,CAAC;QAChG,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC,CAGjE,CAAC;QACF,MAAM,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAWvE,CAAC;QACF,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CACtE,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAmB,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CACnH,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC;QACzC,MAAM,UAAU,GAAG,sBAAsB,CAAC,WAAW,CAAC,CAAC;QACvD,MAAM,UAAU,GAAwB,QAAQ,CAAC,IAAI,KAAK,QAAQ;YAChE,CAAC,CAAC,kBAAkB;YACpB,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC;gBAC9E,CAAC,CAAC,QAAQ;gBACV,CAAC,CAAC,kBAAkB,CAAC;QACzB,MAAM,YAAY,GAAG,CAAC,MAAe,EAAuB,EAAE,CAAC,CAC7D,MAAM,IAAI,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CACzF,CAAC;QACF,MAAM,KAAK,GAAG;YACZ,YAAY,EAAE,QAAQ;YACtB,UAAU,EAAE,UAAU;YACtB,wBAAwB,EAAE,QAAQ;YAClC,OAAO,EAAE,QAAQ;YACjB,gBAAgB,EAAE,YAAY,CAAC,wBAAwB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ;YACxF,gBAAgB,EAAE,YAAY,CAAC,wBAAwB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ;YACxF,mBAAmB,EAAE,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,GAAG,CAAC,CAAC;YAClF,gBAAgB,EAAE,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,gBAAgB,GAAG,CAAC,CAAC;YACrE,YAAY,EAAE,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,YAAY,GAAG,GAAG,CAAC;SACvD,CAAC;QACX,MAAM,cAAc,GAAG,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC;QACvE,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,KAAK,QAAQ;YACzC,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,QAAQ,EAAE,GAAG,cAAc,CAAC;YAC7C,CAAC,CAAC,UAAU,CAAC,QAAQ,CAAC;QACxB,MAAM,SAAS,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;YAC/C,OAAO,EAAE,CAAC;YACV,QAAQ,EAAE,2BAA2B;YACrC,KAAK,EAAE;gBACL,iBAAiB,EAAE,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBAC9E,wBAAwB,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM;gBAC7C,UAAU;aACX;YACD,KAAK;YACL,KAAK,EAAE,UAAU,CAAC,KAAK;YACvB,QAAQ;YACR,QAAQ;YACR,GAAG,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACjB,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,kCAAkC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC1E,CAAC;QACD,IAAI,QAAQ,CAAC,IAAI,KAAK,QAAQ;eACzB,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5E,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAC;QAC/F,CAAC;QACD,MAAM,SAAS,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;YAC9C,GAAG,WAAW;YACd,OAAO,EAAE,CAAC;YACV,QAAQ,EAAE,2BAA2B;YACrC,MAAM,EAAE,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE;YACnE,KAAK,EAAE;gBACL,iBAAiB,EAAE,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBAC9E,wBAAwB,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM;gBAC7C,UAAU;aACX;YACD,MAAM,EAAE;gBACN,gBAAgB,EAAE,QAAQ,CAAC,MAAM;gBACjC,cAAc,EAAE,kBAAkB;gBAClC,UAAU,EAAE,eAAe;gBAC3B,UAAU,EAAE,mEAAmE;aAChF;YACD,KAAK;YACL,OAAO,EAAE;gBACP,SAAS,EAAE,gBAAgB;gBAC3B,SAAS,EAAE,YAAY,CAAC,KAAK,CAAC,MAAM;gBACpC,UAAU,EAAE,YAAY,CAAC,UAAU;gBACnC,aAAa,EAAE,YAAY,CAAC,aAAa;gBACzC,YAAY,EAAE,YAAY,CAAC,YAAY;gBACvC,aAAa,EAAE,YAAY,CAAC,aAAa,CAAC,MAAM;gBAChD,mBAAmB,EAAE,YAAY,CAAC,mBAAmB;gBACrD,mBAAmB,EAAE,YAAY,CAAC,mBAAmB;gBACrD,wBAAwB,EAAE,YAAY,CAAC,wBAAwB;gBAC/D,wBAAwB,EAAE,YAAY,CAAC,wBAAwB;gBAC/D,cAAc;gBACd,YAAY,EAAE,YAAY,CAAC,YAAY;aACxC;YACD,KAAK,EAAE,UAAU,CAAC,KAAK;YACvB,QAAQ;YACR,GAAG,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACjB,MAAM,EAAE,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACtD,MAAM,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG;YACb,SAAS;YACT,SAAS;YACT,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,2BAA2B,CAAC;YAC/D,MAAM;YACN,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM;YAChC,kBAAkB;YAClB,eAAe;YACf,QAAQ;SACT,CAAC;QACF,MAAM,yBAAyB,CAAC;YAC9B,SAAS;YACT,OAAO;YACP,YAAY,EAAE,MAAM,CAAC,YAAY;SAClC,CAAC,CAAC;QACH,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,EAAE,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACvD,MAAM,sBAAsB,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC,CAAC"}

package/open-design.json

@@ -3,7 +3,7 @@
   "specVersion": "1.0.0",
   "name": "12ui-design",
   "title": "12UI Design",
-  "version": "0.2.36",
+  "version": "0.2.38",
   "description": "Explore corpus-grounded interface directions, choose one, and convert it into production-ready responsive or native artifacts with 12UI.",
   "author": {
     "name": "Just Every",
@@ -49,7 +49,7 @@
           "command": "npx",
           "args": [
             "-y",
-            "@12ui/design@0.2.36",
+            "@12ui/design@0.2.38",
             "mcp"
           ]
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12ui/design",
-  "version": "0.2.36",
+  "version": "0.2.38",
   "type": "module",
   "description": "The canonical 12ui CLI, SDK, MCP server, and visual interface design skills",
   "main": "dist/index.js",

package/prototype-kit/analyze.mjs

@@ -1,12 +1,14 @@
 // Deterministic analysis of an inventory: states, shared shell, nav items, dropdowns, rows, buttons, link-like texts.
-// Usage: node analyze.mjs <inventory.json> <model.json>
+// Usage: node analyze.mjs <inventory.json> <model.json> [review.json]
 import fs from 'node:fs';
 import { matchPlannedPage } from './lib/navigation.mjs';
+import { canonicalShellRule, selectCanonicalShellPage } from './lib/shell-consistency.mjs';
 import { compareCanonicalShells, isWithinShell, qualifiesShellCandidate, selectOneShellPerRegion } from './lib/shells.mjs';
 import { normalizeText as norm, slugText as slug } from './lib/text.mjs';
 
-const [invFile, outFile] = process.argv.slice(2);
+const [invFile, outFile, reviewFile] = process.argv.slice(2);
 const inv = JSON.parse(fs.readFileSync(invFile, 'utf8'));
+const review = reviewFile ? JSON.parse(fs.readFileSync(reviewFile, 'utf8')) : null;
 const W = 1536, H = 1024;
 const planScreens = Array.isArray(inv.plan?.screens) ? inv.plan.screens : [];
 const chevronDown = (l) => /\b(down|caret down|chevron down|expand)\b/.test(norm(l)) && /chevron|caret|arrow|down/.test(norm(l));
@@ -137,6 +139,23 @@ for (const r of regions) {
   canonical[r] = { stateId: cands[0].stateId, containerId: cands[0].containerId, box: cands[0].box, presentIn: cands.map((c) => c.stateId), ranking: cands.map((c) => `${c.stateId}:${c.matches}m/${c.items}i/${c.share}`) };
 }
 regions = Object.keys(canonical);
+const canonicalShellPage = selectCanonicalShellPage({ pages: inv.pages, states, canonicalShell: canonical });
+if (canonicalShellPage) {
+  for (const region of regions) {
+    const donorCandidates = states.filter((state) => state.pageId === canonicalShellPage.pageId)
+      .flatMap((state) => state.shell.filter((candidate) => candidate.region === region)
+        .map((candidate) => ({ ...candidate, stateId: state.stateId })));
+    if (donorCandidates.length === 0) continue;
+    const donor = donorCandidates[0];
+    canonical[region] = {
+      ...canonical[region],
+      stateId: donor.stateId,
+      containerId: donor.containerId,
+      box: donor.box,
+    };
+  }
+  canonicalShellPage.rule = canonicalShellRule();
+}
 
 // ---- nav items: texts inside a canonical shell container that repeat, font >= 12, excluding long copy
 const nav = [];
@@ -157,10 +176,31 @@ for (const r of regions) {
 function matchPage(text) {
   return matchPlannedPage(text, states.filter((state) => state.ordinal === 1))?.stateId || null;
 }
-for (const n of nav) { n.target = matchPage(n.text); }
-{ const first = nav.find((n) => n.region !== 'footer'); const home = states.find((s) => s.isSource) || states[0];
-  if (first && !first.target && /^(home|overview|dashboard|start)$/.test(norm(first.text))) { first.target = home.stateId; first.fallback = 'home'; } }
-for (const n of nav) n.holding = n.target ? null : 'holding-' + slug(n.text);
+if (review) {
+  const missingRoutes = Array.isArray(review.missingRoutes) ? review.missingRoutes : [];
+  const exactMissingRoute = (text) => missingRoutes.find((route) => (
+    norm(route.title) === norm(text)
+    || norm(String(route.id).replace(/-/g, ' ')) === norm(text)
+  ));
+  for (const n of nav) {
+    const missing = exactMissingRoute(n.text);
+    n.target = missing ? null : matchPage(n.text);
+    n.holding = missing?.holding || (n.target ? null : 'holding-' + slug(n.text));
+    if (missing) n.reviewRoute = missing.id;
+  }
+  const first = nav.find((n) => n.region !== 'footer');
+  const home = states.find((s) => s.isSource);
+  if (first && !first.target && !first.reviewRoute && home && /^(home|overview|dashboard|start)$/.test(norm(first.text))) {
+    first.target = home.stateId;
+    first.holding = null;
+    first.fallback = 'home';
+  }
+} else {
+  for (const n of nav) { n.target = matchPage(n.text); }
+  { const first = nav.find((n) => n.region !== 'footer'); const home = states.find((s) => s.isSource) || states[0];
+    if (first && !first.target && /^(home|overview|dashboard|start)$/.test(norm(first.text))) { first.target = home.stateId; first.fallback = 'home'; } }
+  for (const n of nav) n.holding = n.target ? null : 'holding-' + slug(n.text);
+}
 
 // ---- per-state interactive candidates
 function smallestCommon(s, ids) {
@@ -257,8 +297,10 @@ const tokens = {
 const model = {
   run: inv.runDir,
   plan: { concept: typeof inv.plan?.concept === 'string' ? inv.plan.concept : '', sitePurpose: typeof inv.plan?.sitePurpose === 'string' ? inv.plan.sitePurpose : '', scope: inv.plan?.scope || null },
+  ...(review ? { review } : {}),
   tokens,
   canonicalShell: canonical,
+  canonicalShellPage,
   shellAmbiguities,
   nav,
   states: states.map((s) => ({