@12ui/design 0.2.47 → 0.2.49

package/dist/spend-client.d.ts

@@ -0,0 +1,97 @@
+import { type ConversionConfig } from './config.js';
+/**
+ * The account spend contract, as the CLI reads it.
+ *
+ * The service answers `GET /api/v1/spend` with rollups it computed; the CLI
+ * never re-derives a total from the run list, because the run list is capped
+ * and the rollups are not. Fields the service may withhold — settled provider
+ * cost, which is an operator figure — arrive as null, and the CLI reports them
+ * as withheld rather than as zero.
+ */
+export type SpendFundingSource = 'wallet' | 'sponsored' | 'admin' | 'unattributed';
+export type SpendFunctionality = 'convert' | 'draft' | 'branch' | 'search';
+export type SpendCostEvidence = 'provider_reported' | 'estimated' | 'zero_cost_reuse' | 'legacy_unknown';
+export type SpendAmounts = {
+    chargedMicros: number;
+    listPriceMicros: number;
+    providerCostMicros: number | null;
+};
+export type SpendRun = SpendAmounts & {
+    runId: string;
+    functionality: SpendFunctionality;
+    fundingSource: SpendFundingSource;
+    sponsorshipGrantId: string | null;
+    costEvidence: SpendCostEvidence;
+    providerCostEvents: number;
+    firstEventAt: string;
+    lastEventAt: string;
+};
+export type SpendDay = SpendAmounts & {
+    day: string;
+    runs: number;
+};
+export type SpendFundingTotal = SpendAmounts & {
+    fundingSource: SpendFundingSource;
+    sponsorshipGrantId: string | null;
+    runs: number;
+};
+export type SpendWallet = {
+    status: 'ok';
+    accountStatus: string;
+    availableMicros: number;
+    reservedMicros: number;
+    debtMicros: number;
+    lifetimeFundedMicros: number;
+    lifetimeCapturedMicros: number;
+    lifetimeReversedMicros: number;
+} | {
+    status: 'unavailable';
+};
+export type SpendQuotaBucket = {
+    limit: number;
+    used: number;
+    remaining: number;
+    available: boolean;
+};
+export type SpendQuota = {
+    tier: string;
+    windowStart: string;
+    resetsAt: string;
+    buckets: Record<string, SpendQuotaBucket>;
+} | null;
+export type SpendReport = {
+    account: {
+        accountId: string;
+        kind: 'user' | 'organization';
+        operator: boolean;
+    };
+    window: {
+        days: number;
+        start: string;
+        end: string;
+        unit: string;
+    };
+    currency: string;
+    providerCostVisibility: 'operator' | 'restricted';
+    totals: SpendAmounts & {
+        runs: number;
+    };
+    funding: SpendFundingTotal[];
+    days: SpendDay[];
+    runs: SpendRun[];
+    truncated: boolean;
+    wallet: SpendWallet;
+    quota: SpendQuota;
+};
+export type SpendRequest = {
+    days?: number;
+    limit?: number;
+    signal?: AbortSignal;
+};
+type Fetch = typeof fetch;
+export declare const fetchAccountSpend: (request?: SpendRequest, options?: {
+    config?: ConversionConfig;
+    fetch?: Fetch;
+}) => Promise<SpendReport>;
+export {};
+//# sourceMappingURL=spend-client.d.ts.map

package/dist/spend-client.d.ts.map

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

package/dist/spend-client.js

@@ -0,0 +1,31 @@
+import { declareClientVersion } from './client-version.js';
+import { appendClientAuthGuidance } from './client-auth-guidance.js';
+import { readConversionConfig } from './config.js';
+export const fetchAccountSpend = async (request = {}, options = {}) => {
+    const config = options.config ?? readConversionConfig();
+    const fetchImpl = options.fetch ?? fetch;
+    const query = new URLSearchParams();
+    if (request.days !== undefined)
+        query.set('days', String(request.days));
+    if (request.limit !== undefined)
+        query.set('limit', String(request.limit));
+    const suffix = query.size > 0 ? `?${query.toString()}` : '';
+    const headers = declareClientVersion(new Headers({
+        accept: 'application/json',
+        authorization: `Bearer ${config.apiKey}`,
+    }));
+    const response = await fetchImpl(`${config.origin}/api/v1/spend${suffix}`, {
+        headers,
+        ...(request.signal ? { signal: request.signal } : {}),
+    });
+    if (!response.ok) {
+        const detail = await response.text().catch(() => '');
+        throw new Error(appendClientAuthGuidance(`12ui spend request failed (${response.status}): ${detail.slice(0, 500)}`, response.status));
+    }
+    const body = await response.json().catch(() => null);
+    if (!body || typeof body !== 'object' || !body.account || !Array.isArray(body.runs)) {
+        throw new Error('12ui returned an unreadable spend report');
+    }
+    return body;
+};
+//# sourceMappingURL=spend-client.js.map

package/dist/spend-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-client.js","sourceRoot":"","sources":["../src/spend-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,EAAE,oBAAoB,EAAyB,MAAM,aAAa,CAAC;AA6F1E,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,EACpC,UAAwB,EAAE,EAC1B,UAAwD,EAAE,EACpC,EAAE;IACxB,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,oBAAoB,EAAE,CAAC;IACxD,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;IACzC,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;IACpC,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS;QAAE,KAAK,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IACxE,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS;QAAE,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3E,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,OAAO,CAAC;QAC/C,MAAM,EAAE,kBAAkB;QAC1B,aAAa,EAAE,UAAU,MAAM,CAAC,MAAM,EAAE;KACzC,CAAC,CAAC,CAAC;IACJ,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,MAAM,CAAC,MAAM,gBAAgB,MAAM,EAAE,EAAE;QACzE,OAAO;QACP,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtD,CAAC,CAAC;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,wBAAwB,CACtC,8BAA8B,QAAQ,CAAC,MAAM,MAAM,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,EACzE,QAAQ,CAAC,MAAM,CAChB,CAAC,CAAC;IACL,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAuB,CAAC;IAC3E,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpF,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC"}

package/dist/spend-report-lines.d.ts

@@ -0,0 +1,4 @@
+import type { SpendReport } from './spend-client.js';
+export declare const formatUsdMicros: (micros: number | null) => string;
+export declare const spendReportLines: (report: SpendReport) => string[];
+//# sourceMappingURL=spend-report-lines.d.ts.map

package/dist/spend-report-lines.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend-report-lines.d.ts","sourceRoot":"","sources":["../src/spend-report-lines.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,WAAW,EAEZ,MAAM,mBAAmB,CAAC;AAe3B,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,GAAG,IAAI,KAAG,MAKvD,CAAC;AAmFF,eAAO,MAAM,gBAAgB,GAAI,QAAQ,WAAW,KAAG,MAAM,EAyD5D,CAAC"}

package/dist/spend-report-lines.js

@@ -0,0 +1,131 @@
+/**
+ * The human rendering of a spend report, as pure functions over the payload.
+ *
+ * Formatting lives here rather than in the command so the exact lines an
+ * operator reads can be asserted without a network, and so one rule decides how
+ * money is written: money is never rounded to a figure that reads as zero when
+ * it is not. A $0.0004 embedding call prints as $0.0004, because a ledger that
+ * silently rounds spend to $0.00 is the instrument that caused the doubt this
+ * command exists to settle.
+ */
+const MICROS_PER_DOLLAR = 1_000_000;
+export const formatUsdMicros = (micros) => {
+    if (micros === null)
+        return '—';
+    const dollars = micros / MICROS_PER_DOLLAR;
+    if (micros !== 0 && Math.abs(dollars) < 0.01)
+        return `$${dollars.toFixed(4)}`;
+    return `$${dollars.toFixed(2)}`;
+};
+/**
+ * Labels for the vocabularies the service owns.
+ *
+ * Both maps are read through {@link labelled}, which falls back to the raw
+ * value: the service coins ledger labels as its evidence vocabulary changes,
+ * and a report that crashes — or silently blanks a column — on a label this
+ * build has not heard of is worse than one that prints the new label as-is.
+ */
+const FUNDING_LABELS = {
+    wallet: 'wallet',
+    sponsored: 'sponsored',
+    admin: 'operator',
+    unattributed: 'unattributed',
+};
+const EVIDENCE_LABELS = {
+    provider_reported: 'settled',
+    estimated: 'estimated',
+    zero_cost_reuse: 'reused',
+    legacy_unknown: 'unknown',
+};
+const labelled = (labels, value) => (labels[value] ?? value);
+const day = (timestamp) => timestamp.slice(0, 10);
+const padded = (value, width) => value.padEnd(width, ' ');
+const rightPadded = (value, width) => value.padStart(width, ' ');
+/** Money columns are right-aligned so magnitudes line up; labels stay left. */
+const table = (headings, rows, rightAligned) => {
+    const widths = headings.map((heading, column) => Math.max(heading.length, ...rows.map((row) => (row[column] ?? '').length)));
+    const line = (cells) => cells
+        .map((cell, column) => (rightAligned.has(column)
+        ? rightPadded(cell ?? '', widths[column] ?? 0)
+        : padded(cell ?? '', widths[column] ?? 0)))
+        .join('  ')
+        .trimEnd();
+    return [line(headings), ...rows.map(line)];
+};
+const fundingSummary = (report) => {
+    if (report.funding.length === 0)
+        return 'Funding: nothing settled in this window.';
+    const parts = report.funding.map((entry) => {
+        const grant = entry.sponsorshipGrantId ? `, grant ${entry.sponsorshipGrantId}` : '';
+        return `${labelled(FUNDING_LABELS, entry.fundingSource)} ${formatUsdMicros(entry.chargedMicros)}`
+            + ` (${entry.runs} ${entry.runs === 1 ? 'run' : 'runs'}${grant})`;
+    });
+    return `Funding: ${parts.join(' · ')}`;
+};
+const walletLine = (report) => {
+    const { wallet } = report;
+    if (wallet.status !== 'ok') {
+        return 'Wallet: unavailable — billing did not answer; ledger figures above are unaffected.';
+    }
+    return `Wallet: ${formatUsdMicros(wallet.availableMicros)} available,`
+        + ` ${formatUsdMicros(wallet.reservedMicros)} reserved,`
+        + ` lifetime ${formatUsdMicros(wallet.lifetimeFundedMicros)} funded`
+        + ` / ${formatUsdMicros(wallet.lifetimeCapturedMicros)} charged`
+        + (wallet.accountStatus === 'active' ? '' : ` (account ${wallet.accountStatus})`);
+};
+const quotaLine = (report) => {
+    const { quota } = report;
+    if (!quota)
+        return 'Quota: unavailable.';
+    const buckets = Object.entries(quota.buckets)
+        .map(([bucket, value]) => `${bucket} ${value.used}/${value.limit}`)
+        .join(' · ');
+    return `Quota (${quota.tier}): ${buckets} — resets ${quota.resetsAt}`;
+};
+export const spendReportLines = (report) => {
+    const restricted = report.providerCostVisibility !== 'operator';
+    const lines = [
+        `Spend for ${report.account.accountId} · last ${report.window.days}`
+            + ` ${report.window.days === 1 ? 'day' : 'days'}`
+            + ` (${day(report.window.start)} to ${day(report.window.end)}, UTC)`,
+        `Settled: ${formatUsdMicros(report.totals.chargedMicros)} charged`
+            + ` · ${formatUsdMicros(report.totals.listPriceMicros)} at list price`
+            + (restricted
+                ? ' · provider cost withheld (operator figure)'
+                : ` · ${formatUsdMicros(report.totals.providerCostMicros)} provider cost`)
+            + ` · ${report.totals.runs} ${report.totals.runs === 1 ? 'run' : 'runs'}`,
+        fundingSummary(report),
+        walletLine(report),
+        quotaLine(report),
+    ];
+    if (report.days.length > 0) {
+        lines.push('', ...table(['Day', 'Runs', 'Charged', ...(restricted ? [] : ['Provider'])], report.days.map((entry) => [
+            entry.day,
+            String(entry.runs),
+            formatUsdMicros(entry.chargedMicros),
+            ...(restricted ? [] : [formatUsdMicros(entry.providerCostMicros)]),
+        ]), new Set(restricted ? [1, 2] : [1, 2, 3])));
+    }
+    if (report.runs.length > 0) {
+        lines.push('', ...table(['Run', 'Work', 'Funding', 'Charged', ...(restricted ? [] : ['Provider']), 'Evidence', 'Last event'], report.runs.map((run) => [
+            run.runId,
+            run.functionality,
+            run.sponsorshipGrantId
+                ? `${labelled(FUNDING_LABELS, run.fundingSource)} ${run.sponsorshipGrantId}`
+                : labelled(FUNDING_LABELS, run.fundingSource),
+            formatUsdMicros(run.chargedMicros),
+            ...(restricted ? [] : [formatUsdMicros(run.providerCostMicros)]),
+            labelled(EVIDENCE_LABELS, run.costEvidence),
+            run.lastEventAt,
+        ]), new Set(restricted ? [3] : [3, 4])));
+        if (report.truncated) {
+            lines.push(`Showing ${report.runs.length} of ${report.totals.runs} runs; totals above cover the`
+                + ' whole window. Raise --limit to list more.');
+        }
+    }
+    else {
+        lines.push('', 'No settled work in this window.');
+    }
+    return lines;
+};
+//# sourceMappingURL=spend-report-lines.js.map

package/dist/spend-report-lines.js.map

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

package/open-design.json

@@ -3,7 +3,7 @@
   "specVersion": "1.0.0",
   "name": "12ui-design",
   "title": "12UI Design",
-  "version": "0.2.47",
+  "version": "0.2.49",
   "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.47",
+            "@12ui/design@0.2.49",
             "mcp"
           ]
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12ui/design",
-  "version": "0.2.47",
+  "version": "0.2.49",
   "type": "module",
   "description": "The canonical 12ui CLI, SDK, MCP server, and visual interface design skills",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "start": "node dist/cli.js",
     "test": "vitest",
     "test:run": "vitest run",
-    "test:prototype": "node prototype-kit/polish/tests/rules-check.mjs && node prototype-kit/polish/tests/harm-check.mjs && node prototype-kit/polish/tests/breathing-check.mjs && node prototype-kit/polish/tests/report-check.mjs && node prototype-kit/tests/rules-check.mjs && node prototype-kit/tests/offline-check.mjs && node prototype-kit/tests/shell-stitching-runtime.mjs && node prototype-kit/tests/adversarial-runtime.mjs --assert",
+    "test:prototype": "node prototype-kit/polish/tests/rules-check.mjs && node prototype-kit/polish/tests/harm-check.mjs && node prototype-kit/polish/tests/breathing-check.mjs && node prototype-kit/polish/tests/report-check.mjs && node prototype-kit/tests/rules-check.mjs && node prototype-kit/tests/offline-check.mjs && node prototype-kit/tests/shell-stitching-runtime.mjs && node prototype-kit/tests/shell-stitching-runtime.mjs --reintroduce-defect && node prototype-kit/tests/adversarial-runtime.mjs --assert",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.type-tests.json",
     "prepublishOnly": "npm run build"
   },

package/prototype-kit/build.mjs

@@ -4,7 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseHTML } from 'linkedom';
 import { resolveDropdownAction } from './lib/actions.mjs';
-import { restoreActionPointerReachability } from './lib/action-target.mjs';
+import { restoreActionPointerReachability, selectUniqueActionOwners } from './lib/action-target.mjs';
 import {
   HOLDING_SHELL_ATTRIBUTE,
   holdingBlockGeometry,
@@ -13,6 +13,7 @@ import {
   shellPlacementCss,
 } from './lib/holding-composition.mjs';
 import { injectReviewFraming } from './lib/review-framing.mjs';
+import { removeRemoteHeadLinks } from './lib/local-document.mjs';
 import {
   isolateTransplantedShell,
   rulesFor,
@@ -156,6 +157,7 @@ const report = {
   unbound: [],
   invalidDropdowns: [],
   actionDemotions: [],
+  duplicateActionOwners: [],
   shellSizeDelta: [],
   shellAmbiguities: model.shellAmbiguities || [],
   suppressedShellOverlaps: [],
@@ -234,7 +236,9 @@ function actionsFor(s) {
     if (a) acts.set(c.id, a);
     else report.counts.none++;
   }
-  return acts;
+  const normalized = selectUniqueActionOwners(loadDoc(s.file).document, acts);
+  report.duplicateActionOwners.push(...normalized.removed.map((removal) => ({ state: s.stateId, ...removal })));
+  return normalized.actions;
 }
 
 function bindAction(el, action) {
@@ -410,6 +414,7 @@ for (const u of units) {
   const cfg = { unit: u.id, states: u.states.map((s) => s.stateId), tokens: model.tokens, contentFile: `${u.id}.json`, activeNav: activeNav?.text || null };
   document.body.insertAdjacentHTML('beforeend', `<script id="proto-state" type="application/json">${JSON.stringify(cfg).replace(/</g, '\\u003c')}</script><script src="proto.js"></script>`);
   if (review) injectReviewFraming(document, review);
+  removeRemoteHeadLinks(document);
   fs.writeFileSync(path.join(outDir, outputFileOfUnit(u)), '<!doctype html>\n' + document.documentElement.outerHTML);
   fs.writeFileSync(path.join(outDir, 'content', u.id + '.json'), JSON.stringify(content, null, 1));
   report.units.push({
@@ -612,6 +617,7 @@ for (const u of units) {
     const cfg = { unit: hslug, holding: true, holdingBands: bandDeclarations, tokens: model.tokens, contentFile: null, activeNav: navMatch?.text || null };
     document.body.insertAdjacentHTML('beforeend', `<script id="proto-state" type="application/json">${JSON.stringify(cfg)}</script><script src="proto.js"></script>`);
     if (review) injectReviewFraming(document, review);
+    removeRemoteHeadLinks(document);
     fs.writeFileSync(path.join(outDir, outputFile), '<!doctype html>\n' + document.documentElement.outerHTML);
   }
   console.error(`holding pages: ${usedHoldings.size}`);
@@ -623,5 +629,5 @@ fs.writeFileSync(path.join(outDir, 'index.html'), `<!doctype html><meta http-equ
 const manifestHoldings = review
   ? [...usedHoldings.entries()].map(([holding, title]) => [holding.replace(/\.html$/, ''), title])
   : [...usedHoldings.entries()];
-fs.writeFileSync(path.join(outDir, 'proto-manifest.json'), JSON.stringify({ units: report.units, nav: navRows.map((n) => ({ text: n.text, target: n.target, holding: n.holding, rowId: n.rowId })), holdings: manifestHoldings, counts: report.counts, unbound: report.unbound, invalidDropdowns: report.invalidDropdowns, ...(report.actionDemotions.length > 0 ? { actionDemotions: report.actionDemotions } : {}), shellSizeDelta: report.shellSizeDelta, shellAmbiguities: report.shellAmbiguities, suppressedShellOverlaps: report.suppressedShellOverlaps, skippedShellTransplants: report.skippedShellTransplants, replacedShellActions: report.replacedShellActions, shellActionRemaps: report.shellActionRemaps, scriptDirections: states.map(({ stateId, scriptDirection, writingMode }) => ({ stateId, scriptDirection, writingMode })), canonicalShell: model.canonicalShell, canonicalShellPage: report.canonicalShellPage, shellConsistency: report.shellConsistency, ...(review ? { review } : {}) }, null, 1));
+fs.writeFileSync(path.join(outDir, 'proto-manifest.json'), JSON.stringify({ units: report.units, nav: navRows.map((n) => ({ text: n.text, target: n.target, holding: n.holding, rowId: n.rowId })), holdings: manifestHoldings, counts: report.counts, unbound: report.unbound, invalidDropdowns: report.invalidDropdowns, ...(report.actionDemotions.length > 0 ? { actionDemotions: report.actionDemotions } : {}), ...(report.duplicateActionOwners.length > 0 ? { duplicateActionOwners: report.duplicateActionOwners } : {}), shellSizeDelta: report.shellSizeDelta, shellAmbiguities: report.shellAmbiguities, suppressedShellOverlaps: report.suppressedShellOverlaps, skippedShellTransplants: report.skippedShellTransplants, replacedShellActions: report.replacedShellActions, shellActionRemaps: report.shellActionRemaps, scriptDirections: states.map(({ stateId, scriptDirection, writingMode }) => ({ stateId, scriptDirection, writingMode })), canonicalShell: model.canonicalShell, canonicalShellPage: report.canonicalShellPage, shellConsistency: report.shellConsistency, ...(review ? { review } : {}) }, null, 1));
 console.error('counts', JSON.stringify(report.counts), 'unbound', report.unbound.length);

package/prototype-kit/lib/action-target.mjs

@@ -8,3 +8,29 @@ export function restoreActionPointerReachability(element) {
   element.setAttribute('data-proto-pointer-restored', 'true');
   return true;
 }
+
+/**
+ * Give one semantic action to one rendered owner. A label response can name
+ * both a layout wrapper and one or more controls inside it. When descendants
+ * carry the same action kind, only the terminal-most elements are real action
+ * targets; retaining the wrapper adds a duplicate listener and an impossible
+ * hit-test identity. Different nested action kinds remain independent.
+ */
+export function selectUniqueActionOwners(document, actions) {
+  const selected = new Map(actions);
+  const removed = [];
+  for (const [wrapperId, wrapperAction] of actions) {
+    const wrapper = document.getElementById(wrapperId);
+    if (!wrapper) continue;
+    const descendants = [...wrapper.querySelectorAll('[id]')].filter((candidate) => (
+      actions.get(candidate.id)?.action === wrapperAction.action
+    ));
+    if (descendants.length === 0) continue;
+    const ownerIds = descendants.filter((candidate) => ![...candidate.querySelectorAll('[id]')].some((nested) => (
+      actions.get(nested.id)?.action === wrapperAction.action
+    ))).map((candidate) => candidate.id);
+    selected.delete(wrapperId);
+    removed.push({ wrapperId, ownerIds, action: wrapperAction.action });
+  }
+  return { actions: selected, removed };
+}

package/prototype-kit/lib/local-document.mjs

@@ -0,0 +1,16 @@
+const REMOTE_HREF = /^(?:https?:)?\/\//iu;
+
+/**
+ * Prototype files are owner-review artifacts that must open directly from
+ * disk. Remote head links turn an otherwise self-contained page into a noisy
+ * runtime failure when the review browser correctly blocks the network.
+ */
+export function removeRemoteHeadLinks(document) {
+  let removed = 0;
+  for (const link of document.querySelectorAll('head link[href]')) {
+    if (!REMOTE_HREF.test(link.getAttribute('href')?.trim() ?? '')) continue;
+    link.remove();
+    removed += 1;
+  }
+  return removed;
+}

package/prototype-kit/lib/runtime-check.mjs

@@ -1,6 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import {
+  compareCanonicalShellSamples,
+  SHELL_RUNTIME_GEOMETRY_EPSILON_PX,
+} from './shell-runtime-equivalence.mjs';
+
 function errorText(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -21,7 +26,23 @@ function configuredWidths(protoDir, file) {
 async function smokeInteraction(page, selector, assertion) {
   const locator = page.locator(selector).first();
   if (!await locator.count()) return { present: false, ok: true };
+  let reviewClearanceAdded = false;
   try {
+    reviewClearanceAdded = await locator.evaluate((element) => {
+      const framing = document.getElementById('proto-review-framing');
+      if (!framing) return false;
+      const box = framing.getBoundingClientRect();
+      const target = element.getBoundingClientRect();
+      const overlaps = Math.min(box.right, target.right) - Math.max(box.left, target.left) > 0
+        && Math.min(box.bottom, target.bottom) - Math.max(box.top, target.top) > 0;
+      if (!overlaps) return false;
+      const clearance = document.createElement('div');
+      clearance.setAttribute('data-proto-runtime-clearance', 'true');
+      clearance.setAttribute('aria-hidden', 'true');
+      clearance.style.cssText = `display:block;position:relative;flex:none;width:1px;height:${box.height + 36}px;pointer-events:none`;
+      document.body.appendChild(clearance);
+      return true;
+    });
     await locator.scrollIntoViewIfNeeded();
     // Playwright considers an element "in view" even when a fixed review
     // panel covers every point in its box. Center it before hit-testing so
@@ -55,6 +76,10 @@ async function smokeInteraction(page, selector, assertion) {
     return { present: true, ok, point, opened };
   } catch (error) {
     return { present: true, ok: false, error: errorText(error) };
+  } finally {
+    if (reviewClearanceAdded) {
+      await page.locator('[data-proto-runtime-clearance="true"]').evaluateAll((nodes) => nodes.forEach((node) => node.remove())).catch(() => null);
+    }
   }
 }
 
@@ -286,7 +311,12 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
           const host = screen?.querySelector('.ly-anchor-canvas') || screen;
           const hostZoom = host ? parseFloat(getComputedStyle(host).zoom) || 1 : 1;
           const round = (value) => Math.round(value * 10) / 10;
-          const visualSignature = async (shell, declaration) => {
+          const digestJson = async (value) => {
+            const bytes = new TextEncoder().encode(JSON.stringify(value));
+            const digest = await crypto.subtle.digest('SHA-256', bytes);
+            return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+          };
+          const visualSample = async (shell, declaration) => {
             const rootBox = shell.getBoundingClientRect();
             const markerIds = new Set(declaration.activeMarkerIds || []);
             const visualNodes = [shell, ...shell.querySelectorAll('*')]
@@ -306,10 +336,10 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
                   label: node.getAttribute('alt') || node.getAttribute('aria-label') || '',
                   source: node.getAttribute('src') || '',
                   box: [
-                    round((box.left - rootBox.left) / hostZoom),
-                    round((box.top - rootBox.top) / hostZoom),
-                    round(box.width / hostZoom),
-                    round(box.height / hostZoom),
+                    (box.left - rootBox.left) / hostZoom,
+                    (box.top - rootBox.top) / hostZoom,
+                    box.width / hostZoom,
+                    box.height / hostZoom,
                   ],
                   style: [
                     style.display, node === shell ? 'shell-root' : style.position,
@@ -319,9 +349,13 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
                   ],
                 };
               }).filter((node) => node.box[2] > 0 && node.box[3] > 0);
-            const bytes = new TextEncoder().encode(JSON.stringify({ region: declaration.region, visualNodes }));
-            const digest = await crypto.subtle.digest('SHA-256', bytes);
-            return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+            const appearanceNodes = visualNodes.map(({ box, ...appearance }) => appearance);
+            const diagnosticNodes = visualNodes.map((node) => ({ ...node, box: node.box.map(round) }));
+            return {
+              appearanceSignature: await digestJson({ region: declaration.region, visualNodes: appearanceNodes }),
+              diagnosticSignature: await digestJson({ region: declaration.region, visualNodes: diagnosticNodes }),
+              geometry: visualNodes.map((node) => node.box),
+            };
           };
           for (const declaration of declared.regions || []) {
             const shell = document.getElementById(declaration.shellId);
@@ -329,15 +363,16 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
               failures.push({ kind: 'shell-consistency', region: declaration.region, reason: 'missing-declared-shell' });
               continue;
             }
-            const actualSignature = await visualSignature(shell, declaration);
+            const sample = await visualSample(shell, declaration);
             const shellBox = shell.getBoundingClientRect();
             const hostBox = host?.getBoundingClientRect() || { left: 0, top: 0 };
-            const actualGeometry = [
-              round((shellBox.left - hostBox.left) / hostZoom),
-              round((shellBox.top - hostBox.top) / hostZoom),
-              round(shellBox.width / hostZoom),
-              round(shellBox.height / hostZoom),
+            const comparisonGeometry = [
+              (shellBox.left - hostBox.left) / hostZoom,
+              (shellBox.top - hostBox.top) / hostZoom,
+              shellBox.width / hostZoom,
+              shellBox.height / hostZoom,
             ];
+            const actualGeometry = comparisonGeometry.map(round);
             let activeMatches = true;
             if (declaration.active?.status === 'linked') {
               const marker = document.getElementById(declaration.active.markerId);
@@ -364,8 +399,11 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
             regions.push({
               region: declaration.region,
               shellId: declaration.shellId,
-              actualSignature,
+              actualSignature: sample.diagnosticSignature,
               actualGeometry,
+              appearanceSignature: sample.appearanceSignature,
+              visualGeometry: sample.geometry,
+              comparisonGeometry,
               inventorySampleSignature: declaration.canonicalSignature,
               consistencyStatus: declaration.consistencyStatus || 'canonical',
               activeStatus: declaration.active?.status || 'silent',
@@ -427,23 +465,48 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
       .map((failure) => ({ file: page.file, width: viewport.width, ...failure })) || []
   )));
   const shellRuntimeGroups = new Map();
+  const shellConsistencyTolerances = [];
   for (const page of pages) for (const viewport of page.viewports) {
     if (!unitByFile.has(page.file)) continue;
     for (const region of viewport.shellState?.regions || []) {
       if (region.consistencyStatus !== 'canonical') continue;
       const key = `${viewport.width}:${viewport.shellState.activeBand}:${region.region}`;
       if (!shellRuntimeGroups.has(key)) shellRuntimeGroups.set(key, []);
-      shellRuntimeGroups.get(key).push({ file: page.file, signature: region.actualSignature, geometry: region.actualGeometry });
+      shellRuntimeGroups.get(key).push({
+        file: page.file,
+        signature: region.actualSignature,
+        geometry: region.actualGeometry,
+        appearanceSignature: region.appearanceSignature,
+        visualGeometry: region.visualGeometry,
+        shellGeometry: region.comparisonGeometry,
+      });
     }
   }
   for (const [key, entries] of shellRuntimeGroups) {
-    const fingerprints = new Set(entries.map((entry) => JSON.stringify([entry.signature, entry.geometry])));
-    if (fingerprints.size > 1) shellConsistencyFailures.push({
+    const reference = entries[0];
+    const comparisons = entries.slice(1).map((entry) => compareCanonicalShellSamples(reference, entry));
+    const equivalent = comparisons.every((comparison) => comparison.equivalent);
+    const pagesInGroup = entries.map(({ file, signature, geometry }) => ({ file, signature, geometry }));
+    if (!equivalent) shellConsistencyFailures.push({
       kind: 'shell-consistency',
       reason: 'prototype-shell-signature-mismatch',
       group: key,
-      pages: entries,
+      pages: pagesInGroup,
     });
+    else {
+      const diagnosticFingerprints = new Set(entries.map((entry) => JSON.stringify([entry.signature, entry.geometry])));
+      if (diagnosticFingerprints.size > 1) shellConsistencyTolerances.push({
+        group: key,
+        epsilonPx: SHELL_RUNTIME_GEOMETRY_EPSILON_PX,
+        maxGeometryDelta: Math.max(0, ...comparisons.map((comparison) => comparison.maxGeometryDelta || 0)),
+        pages: pagesInGroup,
+      });
+    }
+  }
+  for (const page of pages) for (const viewport of page.viewports) for (const region of viewport.shellState?.regions || []) {
+    delete region.appearanceSignature;
+    delete region.visualGeometry;
+    delete region.comparisonGeometry;
   }
   const activeNavigationFailures = pages.flatMap((page) => page.viewports.flatMap((viewport) => (
     viewport.shellState?.failures?.filter((failure) => failure.kind === 'active-navigation')
@@ -458,6 +521,7 @@ export async function checkRuntime({ browser, baseUrl, relativeProtoPath, protoD
     interactionFailures: pages.filter((page) => page.dropdown?.ok === false || page.modal?.ok === false).map((page) => page.file),
     compositionFailures,
     shellConsistencyFailures,
+    shellConsistencyTolerances,
     activeNavigationFailures,
     deepLinkBack,
   };