@invarn/cibuild 2.1.0 → 2.1.1

package/dist/src/lib.d.ts

@@ -16,6 +16,8 @@ import './yaml/steps/index.js';
 export { PipelineRunner, StepExecutionError } from './runner.js';
 export { loadConfig } from './config.js';
 export { loadYAMLPipeline, getWorkflowNames, hasWorkflow, YAMLParseError, YAMLValidationError, } from './yaml/parser.js';
+export { loadFidelityManifest, parseFidelityManifest, buildSurfaceDispatchInputs, FidelityManifestError, } from './yaml/fidelity-manifest.js';
+export type { FidelityManifest, FidelitySurface, FidelityState, StateReference, ReferenceProvenance, BaselineEntry, SurfaceDispatchInputs, } from './yaml/fidelity-manifest.js';
 export { convertYAMLToPipelineDef, getAvailableWorkflows, YAMLConversionError, } from './yaml/converter.js';
 export type { ConversionResult } from './yaml/converter.js';
 export { pipeline } from './pipeline.js';

package/dist/src/lib.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../../src/lib.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,uBAAuB,CAAC;AAI/B,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAIjE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAI5D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAIzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,6CAA6C,CAAC;AACrD,YAAY,EAAE,+BAA+B,EAAE,MAAM,6CAA6C,CAAC;AAInG,OAAO,EACL,eAAe,EACf,OAAO,EACP,iBAAiB,EACjB,YAAY,EACZ,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EACV,OAAO,EACP,WAAW,EACX,QAAQ,EACR,eAAe,EACf,eAAe,EACf,YAAY,GACb,MAAM,YAAY,CAAC;AAIpB,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAI9B,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,UAAU,EACV,OAAO,EACP,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,WAAW,GACZ,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../../src/lib.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,uBAAuB,CAAC;AAI/B,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAIjE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,aAAa,EACb,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AAIrC,OAAO,EACL,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAI5D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAIzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,YAAY,EACV,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,6BAA6B,EAC7B,2BAA2B,GAC5B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EACL,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,6CAA6C,CAAC;AACrD,YAAY,EAAE,+BAA+B,EAAE,MAAM,6CAA6C,CAAC;AAInG,OAAO,EACL,eAAe,EACf,OAAO,EACP,iBAAiB,EACjB,YAAY,EACZ,eAAe,GAChB,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EACV,OAAO,EACP,WAAW,EACX,QAAQ,EACR,eAAe,EACf,eAAe,EACf,YAAY,GACb,MAAM,YAAY,CAAC;AAIpB,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAI9B,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,UAAU,EACV,OAAO,EACP,QAAQ,EACR,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,WAAW,GACZ,MAAM,iBAAiB,CAAC;AAIzB,OAAO,EAAE,+BAA+B,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/src/lib.js

@@ -21,6 +21,8 @@ export { PipelineRunner, StepExecutionError } from './runner.js';
 export { loadConfig } from './config.js';
 // ─── YAML parser ────────────────────────────────────────────────────────
 export { loadYAMLPipeline, getWorkflowNames, hasWorkflow, YAMLParseError, YAMLValidationError, } from './yaml/parser.js';
+// ─── UI fidelity manifest ───────────────────────────────────────────────
+export { loadFidelityManifest, parseFidelityManifest, buildSurfaceDispatchInputs, FidelityManifestError, } from './yaml/fidelity-manifest.js';
 // ─── YAML converter (non-interactive) ───────────────────────────────────
 export { convertYAMLToPipelineDef, getAvailableWorkflows, YAMLConversionError, } from './yaml/converter.js';
 // ─── Pipeline DSL factory ───────────────────────────────────────────────

package/dist/src/yaml/fidelity-manifest.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Multi-state UI-fidelity manifest parser/validator.
+ *
+ * The manifest lives at the app-repo root as `.invarn/fidelity.yml` and is the
+ * single seam the android-ui-fidelity skill and any orchestrator share. It
+ * declares each **Surface** (one app screen) and that surface's first-class
+ * **States** (guest vs logged-in; empty vs progress vs complete). Each State is
+ * one named proof composable paired with one **Reference**, and the Reference
+ * carries export-time **provenance** so the gate can assert validity by
+ * metadata rather than by reading pixels.
+ *
+ * This module owns the schema (the TypeScript types below) and a validator that
+ * rejects malformed entries with a clear, distinct message — the shared
+ * contract the reference-provenance (UNVERIFIABLE) and baseline-filter slices
+ * key on.
+ */
+/**
+ * Export-time provenance stamped onto a Reference. The gate checks this
+ * metadata, never the PNG's pixels: a missing/placeholder/wrong-locale
+ * reference is caught here instead of by OCR.
+ */
+export interface ReferenceProvenance {
+    /** The Figma node the reference was exported from (e.g. "12:345"). */
+    figmaNode: string;
+    /** The locale the reference was exported in (must match the render locale). */
+    locale: string;
+    /** False when copy placeholders (`{date}`/`{amount}`) are still unfilled. */
+    resolved: boolean;
+    /** ISO-8601 export timestamp. */
+    exportedAt: string;
+}
+/** A single-state design image plus its provenance. */
+export interface StateReference {
+    /** Reference image path (repo-relative), or a Figma node URL. */
+    path: string;
+    /** Export-time provenance; absence makes the State UNVERIFIABLE. */
+    provenance: ReferenceProvenance;
+}
+/**
+ * One allowlisted, product-owned divergence for a State. Keyed on
+ * structured/normalized fields only; `actual` is the pinned render value, so a
+ * changed value re-flags by construction.
+ */
+export interface BaselineEntry {
+    /** Divergence category (e.g. "copy", "geometry") — drives equality. */
+    category: string;
+    /** Stable element id from layout.json. Unpinnable divergences aren't here. */
+    element: string;
+    /** The reference/design value. */
+    expected: string;
+    /** The pinned actual render value — required. */
+    actual: string;
+}
+/** One addressable visual State of a Surface. */
+export interface FidelityState {
+    /** State name (e.g. "Guest", "LoggedIn"); unique within the surface. */
+    name: string;
+    /** Named proof composable `<Surface><State>Proof`; 1:1 with a screens key. */
+    proof: string;
+    /** The single-state reference this State is paired against. */
+    reference: StateReference;
+    /** Per-state baseline of accepted divergences. */
+    accepted?: BaselineEntry[];
+}
+/** One app screen and its first-class States. One proof module per surface. */
+export interface FidelitySurface {
+    /** Surface name. */
+    name: string;
+    /** Render platform (e.g. "android"). */
+    platform: string;
+    /** Proof module path (one module per surface, N composables inside). */
+    module?: string;
+    /** The real source files this surface proves. */
+    source?: string[];
+    /** Globs whose changes imply a re-gate. */
+    touchedBy?: string[];
+    /** The surface's States. */
+    states: FidelityState[];
+}
+/** The parsed `.invarn/fidelity.yml` manifest. */
+export interface FidelityManifest {
+    version: number;
+    surfaces: FidelitySurface[];
+}
+/** Thrown when a manifest is absent, unparseable, or schema-invalid. */
+export declare class FidelityManifestError extends Error {
+    readonly filePath?: string | undefined;
+    constructor(message: string, filePath?: string | undefined);
+}
+/** Reads and parses a manifest from disk. */
+export declare function loadFidelityManifest(filePath: string): FidelityManifest;
+/** Parses and validates manifest YAML text. */
+export declare function parseFidelityManifest(text: string, filePath?: string): FidelityManifest;
+/**
+ * The per-dispatch inputs for one surface, derived from its manifest entry.
+ * Shapes the `params` sidecar the render runtime and preflight already consume
+ * (`screens` + `render_locale` + `provenance`), the reference files to upload,
+ * and the per-proof `accepted[]` baseline the post-judgment filter reads.
+ */
+export interface SurfaceDispatchInputs {
+    /** params.screens: proof composable name → reference basename. */
+    screens: Record<string, string>;
+    /** params.render_locale: the single locale every reference is checked against. */
+    render_locale: string;
+    /** params.provenance: proof composable name → its reference provenance. */
+    provenance: Record<string, ReferenceProvenance>;
+    /** Reference files to upload, one per state, addressed by repo path. */
+    references: {
+        proof: string;
+        path: string;
+    }[];
+    /** Per-proof accepted[] baseline (only states that declare one). */
+    accepted: Record<string, BaselineEntry[]>;
+}
+/**
+ * Build the per-dispatch inputs for one surface: one run carries all of the
+ * surface's states, each paired with its own reference and provenance. The
+ * render locale defaults to the references' shared locale (they must agree);
+ * pass `renderLocale` to override (a deliberate mismatch then surfaces as
+ * UNVERIFIABLE at the gate). Reference basenames must be unique, since the
+ * upload layer addresses files by basename.
+ */
+export declare function buildSurfaceDispatchInputs(surface: FidelitySurface, opts?: {
+    renderLocale?: string;
+}): SurfaceDispatchInputs;
+//# sourceMappingURL=fidelity-manifest.d.ts.map

package/dist/src/yaml/fidelity-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity-manifest.d.ts","sourceRoot":"","sources":["../../../src/yaml/fidelity-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;IAClB,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,UAAU,EAAE,mBAAmB,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,iDAAiD;AACjD,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,SAAS,EAAE,cAAc,CAAC;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;CAC5B;AAED,+EAA+E;AAC/E,MAAM,WAAW,eAAe;IAC9B,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,4BAA4B;IAC5B,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED,wEAAwE;AACxE,qBAAa,qBAAsB,SAAQ,KAAK;aACD,QAAQ,CAAC,EAAE,MAAM;gBAAlD,OAAO,EAAE,MAAM,EAAkB,QAAQ,CAAC,EAAE,MAAM,YAAA;CAI/D;AAED,6CAA6C;AAC7C,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,CAQvE;AAED,+CAA+C;AAC/C,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,GAChB,gBAAgB,CAoBlB;AAwDD;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAChD,wEAAwE;IACxE,UAAU,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9C,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;CAC3C;AAQD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,eAAe,EACxB,IAAI,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,qBAAqB,CA+BvB"}

package/dist/src/yaml/fidelity-manifest.js

@@ -0,0 +1,134 @@
+/**
+ * Multi-state UI-fidelity manifest parser/validator.
+ *
+ * The manifest lives at the app-repo root as `.invarn/fidelity.yml` and is the
+ * single seam the android-ui-fidelity skill and any orchestrator share. It
+ * declares each **Surface** (one app screen) and that surface's first-class
+ * **States** (guest vs logged-in; empty vs progress vs complete). Each State is
+ * one named proof composable paired with one **Reference**, and the Reference
+ * carries export-time **provenance** so the gate can assert validity by
+ * metadata rather than by reading pixels.
+ *
+ * This module owns the schema (the TypeScript types below) and a validator that
+ * rejects malformed entries with a clear, distinct message — the shared
+ * contract the reference-provenance (UNVERIFIABLE) and baseline-filter slices
+ * key on.
+ */
+import * as yaml from 'js-yaml';
+import { readFileSync, existsSync } from 'fs';
+/** Thrown when a manifest is absent, unparseable, or schema-invalid. */
+export class FidelityManifestError extends Error {
+    filePath;
+    constructor(message, filePath) {
+        super(message);
+        this.filePath = filePath;
+        this.name = 'FidelityManifestError';
+    }
+}
+/** Reads and parses a manifest from disk. */
+export function loadFidelityManifest(filePath) {
+    if (!existsSync(filePath)) {
+        throw new FidelityManifestError(`Fidelity manifest not found: ${filePath}`, filePath);
+    }
+    return parseFidelityManifest(readFileSync(filePath, 'utf-8'), filePath);
+}
+/** Parses and validates manifest YAML text. */
+export function parseFidelityManifest(text, filePath) {
+    let doc;
+    try {
+        doc = yaml.load(text);
+    }
+    catch (err) {
+        throw new FidelityManifestError(`Invalid YAML in fidelity manifest: ${err.message}`, filePath);
+    }
+    const root = doc;
+    const surfaces = root.surfaces ?? [];
+    validateSurfaces(surfaces, filePath);
+    return {
+        version: Number(root.version),
+        surfaces,
+    };
+}
+/** The provenance fields every Reference must carry to be verifiable. */
+const REQUIRED_PROVENANCE_FIELDS = [
+    'figmaNode',
+    'locale',
+    'resolved',
+    'exportedAt',
+];
+function validateSurfaces(surfaces, filePath) {
+    for (const surface of surfaces) {
+        const seenStateNames = new Set();
+        for (const state of surface.states ?? []) {
+            if (seenStateNames.has(state.name)) {
+                throw new FidelityManifestError(`surface "${surface.name}": duplicate state name "${state.name}" — state names must be unique within a surface.`, filePath);
+            }
+            seenStateNames.add(state.name);
+            const where = `surface "${surface.name}" state "${state.name}"`;
+            const provenance = state.reference?.provenance;
+            for (const field of REQUIRED_PROVENANCE_FIELDS) {
+                if (provenance == null || provenance[field] === undefined) {
+                    throw new FidelityManifestError(`${where}: reference provenance is missing required field "${field}".`, filePath);
+                }
+            }
+            for (const entry of state.accepted ?? []) {
+                if (entry.actual === undefined ||
+                    entry.actual === null ||
+                    entry.actual === '') {
+                    throw new FidelityManifestError(`${where}: accepted[] entry for element "${entry.element}" is missing a pinned "actual" value.`, filePath);
+                }
+            }
+        }
+    }
+}
+/** POSIX basename of a repo-relative path (manifest paths are POSIX). */
+function posixBasename(p) {
+    const parts = p.split('/');
+    return parts[parts.length - 1];
+}
+/**
+ * Build the per-dispatch inputs for one surface: one run carries all of the
+ * surface's states, each paired with its own reference and provenance. The
+ * render locale defaults to the references' shared locale (they must agree);
+ * pass `renderLocale` to override (a deliberate mismatch then surfaces as
+ * UNVERIFIABLE at the gate). Reference basenames must be unique, since the
+ * upload layer addresses files by basename.
+ */
+export function buildSurfaceDispatchInputs(surface, opts = {}) {
+    const screens = {};
+    const provenance = {};
+    const references = [];
+    const accepted = {};
+    const basenameToPath = new Map();
+    for (const state of surface.states ?? []) {
+        const path = state.reference.path;
+        const base = posixBasename(path);
+        const existing = basenameToPath.get(base);
+        if (existing !== undefined && existing !== path) {
+            throw new FidelityManifestError(`surface "${surface.name}": states resolve to the same reference basename "${base}" ` +
+                `(${existing} vs ${path}); references are uploaded by basename, so they must be unique.`);
+        }
+        basenameToPath.set(base, path);
+        screens[state.proof] = base;
+        provenance[state.proof] = state.reference.provenance;
+        references.push({ proof: state.proof, path });
+        if (state.accepted && state.accepted.length > 0) {
+            accepted[state.proof] = state.accepted;
+        }
+    }
+    const renderLocale = opts.renderLocale ?? deriveRenderLocale(surface);
+    return { screens, render_locale: renderLocale, provenance, references, accepted };
+}
+/**
+ * The render locale a surface's references share. Throws when they disagree and
+ * no explicit locale was given — a coherent surface renders in one locale.
+ */
+function deriveRenderLocale(surface) {
+    const locales = new Set((surface.states ?? []).map((s) => s.reference.provenance.locale));
+    if (locales.size > 1) {
+        throw new FidelityManifestError(`surface "${surface.name}": references span multiple locales ` +
+            `(${[...locales].join(', ')}); pass an explicit renderLocale to disambiguate.`);
+    }
+    return locales.values().next().value ?? '';
+}
+//# sourceMappingURL=fidelity-manifest.js.map

package/dist/src/yaml/fidelity-manifest.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Unit tests for the multi-state UI-fidelity manifest parser/validator.
+ *
+ * The manifest (`.invarn/fidelity.yml`) declares each Surface's States
+ * first-class: one named proof composable per State, each paired with its own
+ * Reference (carrying export-time provenance), plus a per-State `accepted[]`
+ * baseline of allowlisted divergences. These tests pin the schema and the
+ * validator's distinct rejections; fixtures are written to a temp dir and
+ * loaded by path, mirroring the YAML pipeline parser tests.
+ */
+export {};
+//# sourceMappingURL=fidelity-manifest.test.d.ts.map

package/dist/src/yaml/fidelity-manifest.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity-manifest.test.d.ts","sourceRoot":"","sources":["../../../src/yaml/fidelity-manifest.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/src/yaml/fidelity-manifest.test.js

@@ -0,0 +1,251 @@
+/**
+ * Unit tests for the multi-state UI-fidelity manifest parser/validator.
+ *
+ * The manifest (`.invarn/fidelity.yml`) declares each Surface's States
+ * first-class: one named proof composable per State, each paired with its own
+ * Reference (carrying export-time provenance), plus a per-State `accepted[]`
+ * baseline of allowlisted divergences. These tests pin the schema and the
+ * validator's distinct rejections; fixtures are written to a temp dir and
+ * loaded by path, mirroring the YAML pipeline parser tests.
+ */
+import { describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import { writeFileSync, mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { loadFidelityManifest, parseFidelityManifest, buildSurfaceDispatchInputs, FidelityManifestError, } from './fidelity-manifest.js';
+describe('fidelity manifest — parser/validator', () => {
+    let workDir;
+    beforeEach(() => {
+        workDir = mkdtempSync(join(tmpdir(), 'cibuild-fidelity-manifest-'));
+    });
+    afterEach(() => {
+        rmSync(workDir, { recursive: true, force: true });
+    });
+    function writeManifest(content) {
+        const path = join(workDir, 'fidelity.yml');
+        writeFileSync(path, content, 'utf-8');
+        return path;
+    }
+    // A well-formed two-state surface modelling the canonical promo banner
+    // (guest + logged-in), with provenance on each reference and one accepted
+    // baseline entry on the logged-in state.
+    const TWO_STATE_BANNER = `version: 1
+surfaces:
+  - name: PromoBanner
+    platform: android
+    module: fidelity/promo-banner
+    source:
+      - feature/hub/**/PromoBanner.kt
+    touchedBy:
+      - feature/hub/**/PromoBanner*.kt
+    states:
+      - name: Guest
+        proof: PromoBannerGuestProof
+        reference:
+          path: fidelity/refs/promo_banner_guest.png
+          provenance:
+            figmaNode: "12:345"
+            locale: en
+            resolved: true
+            exportedAt: "2026-06-18T10:00:00Z"
+      - name: LoggedIn
+        proof: PromoBannerLoggedInProof
+        reference:
+          path: fidelity/refs/promo_banner_logged_in.png
+          provenance:
+            figmaNode: "12:346"
+            locale: en
+            resolved: true
+            exportedAt: "2026-06-18T10:00:00Z"
+        accepted:
+          - category: copy
+            element: banner_subtitle
+            expected: "Get 5 off when you spend 20,00"
+            actual: "Get 5 off your first order placed by {date}"
+`;
+    test('parses a well-formed two-state surface into addressable states', () => {
+        const manifest = loadFidelityManifest(writeManifest(TWO_STATE_BANNER));
+        expect(manifest.version).toBe(1);
+        expect(manifest.surfaces).toHaveLength(1);
+        const surface = manifest.surfaces[0];
+        expect(surface.name).toBe('PromoBanner');
+        expect(surface.platform).toBe('android');
+        expect(surface.states.map((s) => s.name)).toEqual(['Guest', 'LoggedIn']);
+        const [guest, loggedIn] = surface.states;
+        expect(guest.proof).toBe('PromoBannerGuestProof');
+        expect(guest.reference.path).toBe('fidelity/refs/promo_banner_guest.png');
+        expect(guest.reference.provenance).toEqual({
+            figmaNode: '12:345',
+            locale: 'en',
+            resolved: true,
+            exportedAt: '2026-06-18T10:00:00Z',
+        });
+        expect(loggedIn.proof).toBe('PromoBannerLoggedInProof');
+        expect(loggedIn.accepted).toEqual([
+            {
+                category: 'copy',
+                element: 'banner_subtitle',
+                expected: 'Get 5 off when you spend 20,00',
+                actual: 'Get 5 off your first order placed by {date}',
+            },
+        ]);
+    });
+    test('rejects a reference missing a provenance field', () => {
+        // `exportedAt` omitted from the guest reference's provenance.
+        const yaml = `version: 1
+surfaces:
+  - name: PromoBanner
+    platform: android
+    states:
+      - name: Guest
+        proof: PromoBannerGuestProof
+        reference:
+          path: fidelity/refs/promo_banner_guest.png
+          provenance:
+            figmaNode: "12:345"
+            locale: en
+            resolved: true
+`;
+        expect(() => loadFidelityManifest(writeManifest(yaml))).toThrow(FidelityManifestError);
+        expect(() => loadFidelityManifest(writeManifest(yaml))).toThrow(/provenance.*exportedAt|exportedAt.*provenance/i);
+    });
+    test('rejects an accepted[] entry with no pinned actual', () => {
+        // The baseline entry omits `actual` — it cannot pin the render value, so a
+        // changed value could never re-flag. Reject loud.
+        const yaml = `version: 1
+surfaces:
+  - name: PromoBanner
+    platform: android
+    states:
+      - name: LoggedIn
+        proof: PromoBannerLoggedInProof
+        reference:
+          path: fidelity/refs/promo_banner_logged_in.png
+          provenance:
+            figmaNode: "12:346"
+            locale: en
+            resolved: true
+            exportedAt: "2026-06-18T10:00:00Z"
+        accepted:
+          - category: copy
+            element: banner_subtitle
+            expected: "Get 5 off when you spend 20,00"
+`;
+        expect(() => loadFidelityManifest(writeManifest(yaml))).toThrow(FidelityManifestError);
+        expect(() => loadFidelityManifest(writeManifest(yaml))).toThrow(/accepted.*actual|actual/i);
+    });
+    test('rejects duplicate state names within a surface', () => {
+        // Two states both named "Guest" — their proofs would collide on one
+        // params.screens key.
+        const yaml = `version: 1
+surfaces:
+  - name: PromoBanner
+    platform: android
+    states:
+      - name: Guest
+        proof: PromoBannerGuestProof
+        reference:
+          path: fidelity/refs/promo_banner_guest.png
+          provenance:
+            figmaNode: "12:345"
+            locale: en
+            resolved: true
+            exportedAt: "2026-06-18T10:00:00Z"
+      - name: Guest
+        proof: PromoBannerGuestAltProof
+        reference:
+          path: fidelity/refs/promo_banner_guest_alt.png
+          provenance:
+            figmaNode: "12:347"
+            locale: en
+            resolved: true
+            exportedAt: "2026-06-18T10:00:00Z"
+`;
+        expect(() => loadFidelityManifest(writeManifest(yaml))).toThrow(FidelityManifestError);
+        expect(() => loadFidelityManifest(writeManifest(yaml))).toThrow(/duplicate state.*Guest|state name "Guest"/i);
+    });
+});
+describe('buildSurfaceDispatchInputs', () => {
+    const BANNER = `version: 1
+surfaces:
+  - name: PromoBanner
+    platform: android
+    module: fidelity/promo-banner
+    states:
+      - name: Guest
+        proof: PromoBannerGuestProof
+        reference:
+          path: fidelity/refs/promo_banner_guest.png
+          provenance:
+            figmaNode: "12:345"
+            locale: en
+            resolved: true
+            exportedAt: "2026-06-18T10:00:00Z"
+      - name: LoggedIn
+        proof: PromoBannerLoggedInProof
+        reference:
+          path: fidelity/refs/promo_banner_logged_in.png
+          provenance:
+            figmaNode: "12:346"
+            locale: en
+            resolved: true
+            exportedAt: "2026-06-18T10:00:00Z"
+        accepted:
+          - category: copy
+            element: banner_subtitle
+            expected: "A"
+            actual: "B"
+`;
+    function bannerSurface(extra = '') {
+        return parseFidelityManifest(BANNER + extra).surfaces[0];
+    }
+    test('maps each state proof to its reference basename in screens', () => {
+        const inputs = buildSurfaceDispatchInputs(bannerSurface());
+        expect(inputs.screens).toEqual({
+            PromoBannerGuestProof: 'promo_banner_guest.png',
+            PromoBannerLoggedInProof: 'promo_banner_logged_in.png',
+        });
+    });
+    test('keys provenance by proof and derives the render locale from the references', () => {
+        const inputs = buildSurfaceDispatchInputs(bannerSurface());
+        expect(inputs.render_locale).toBe('en');
+        expect(inputs.provenance.PromoBannerGuestProof).toEqual({
+            figmaNode: '12:345',
+            locale: 'en',
+            resolved: true,
+            exportedAt: '2026-06-18T10:00:00Z',
+        });
+    });
+    test('lists the reference files to upload, one per state, by repo path', () => {
+        const inputs = buildSurfaceDispatchInputs(bannerSurface());
+        expect(inputs.references).toEqual([
+            { proof: 'PromoBannerGuestProof', path: 'fidelity/refs/promo_banner_guest.png' },
+            { proof: 'PromoBannerLoggedInProof', path: 'fidelity/refs/promo_banner_logged_in.png' },
+        ]);
+    });
+    test('carries each state baseline keyed by proof for the post-judgment filter', () => {
+        const inputs = buildSurfaceDispatchInputs(bannerSurface());
+        expect(inputs.accepted.PromoBannerLoggedInProof).toEqual([
+            { category: 'copy', element: 'banner_subtitle', expected: 'A', actual: 'B' },
+        ]);
+        // States with no accepted[] don't appear.
+        expect(inputs.accepted.PromoBannerGuestProof).toBeUndefined();
+    });
+    test('honours an explicit render locale override', () => {
+        const inputs = buildSurfaceDispatchInputs(bannerSurface(), { renderLocale: 'it' });
+        expect(inputs.render_locale).toBe('it');
+    });
+    test('throws when references disagree on locale and none is given', () => {
+        // Flip the logged-in reference to Italian.
+        const surface = bannerSurface();
+        surface.states[1].reference.provenance.locale = 'it';
+        expect(() => buildSurfaceDispatchInputs(surface)).toThrow(/locale/i);
+    });
+    test('throws when two states resolve to the same reference basename', () => {
+        const surface = bannerSurface();
+        // Same basename, different dirs → upload-layer collision.
+        surface.states[1].reference.path = 'other/promo_banner_guest.png';
+        expect(() => buildSurfaceDispatchInputs(surface)).toThrow(/basename/i);
+    });
+});
+//# sourceMappingURL=fidelity-manifest.test.js.map

package/dist/src/yaml/steps/fidelity-aspect-guard.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Fidelity aspect-ratio guard.
+ *
+ * One named composable per state is the authoring norm; the failure this
+ * catches is the opposite — several states stacked into one composable, which
+ * renders far taller (or wider) than the single-state reference it is paired
+ * against. That shows up as a sharp divergence between the rendered and
+ * reference aspect ratios, well before a human reads the diff.
+ *
+ * The guard is a pure comparison over the dimensions the render already
+ * reports (`rendered_px`, `reference_px`). It emits a WARNING when the
+ * divergence exceeds a documented fold factor — it never fails the render, and
+ * it stays silent when there is no reference to compare against.
+ */
+/** Pixel dimensions as `[width, height]`. */
+export type PixelSize = [number, number];
+/**
+ * Fold factor beyond which a rendered/reference aspect-ratio divergence is
+ * worth a warning. A faithful single-state wrapper sits near 1.0; trim and
+ * reference alignment nudge it a few percent; a re-stacked 2-up wrapper roughly
+ * doubles one dimension and lands near 2.0. 1.5 catches the stack while
+ * tolerating the wobble.
+ */
+export declare const ASPECT_RATIO_WARN_FACTOR = 1.5;
+/** The outcome of comparing a rendered aspect ratio to its reference. */
+export interface AspectRatioCheck {
+    /** True only when both sizes are present and strictly positive. */
+    comparable: boolean;
+    /** Rendered width/height, or null when not comparable. */
+    renderedAspect: number | null;
+    /** Reference width/height, or null when not comparable. */
+    referenceAspect: number | null;
+    /**
+     * Symmetric divergence `max(r/ref, ref/r)` (≥ 1), or null when not
+     * comparable. 1.0 means identical proportions.
+     */
+    divergence: number | null;
+    /** True when comparable and the divergence exceeds the fold factor. */
+    warn: boolean;
+}
+/**
+ * Compares a rendered size against its reference size. Returns a
+ * non-warning, non-comparable result when either size is missing or
+ * non-positive — the guard only speaks when it has two real frames to compare.
+ */
+export declare function evaluateAspectRatio(renderedPx: PixelSize | null, referencePx: PixelSize | null, factor?: number): AspectRatioCheck;
+/**
+ * Human/agent-readable warning line for a divergent screen, or null when the
+ * screen does not warrant one. The caller decides where to surface it (preview
+ * result, preflight output) — it is advisory, never a failure.
+ */
+export declare function formatAspectRatioWarning(screen: string, check: AspectRatioCheck): string | null;
+//# sourceMappingURL=fidelity-aspect-guard.d.ts.map

package/dist/src/yaml/steps/fidelity-aspect-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fidelity-aspect-guard.d.ts","sourceRoot":"","sources":["../../../../src/yaml/steps/fidelity-aspect-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,6CAA6C;AAC7C,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAE5C,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,UAAU,EAAE,OAAO,CAAC;IACpB,0DAA0D;IAC1D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,2DAA2D;IAC3D,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B;;;OAGG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,uEAAuE;IACvE,IAAI,EAAE,OAAO,CAAC;CACf;AAaD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,SAAS,GAAG,IAAI,EAC5B,WAAW,EAAE,SAAS,GAAG,IAAI,EAC7B,MAAM,GAAE,MAAiC,GACxC,gBAAgB,CAyBlB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,gBAAgB,GACtB,MAAM,GAAG,IAAI,CAUf"}