@tangle-network/browser-agent-driver 0.33.2 → 0.34.0

package/dist/design/audit/reference/generate/parse.js

@@ -0,0 +1,180 @@
+/**
+ * Redesign-direction parser — a PURE core of the generative layer.
+ *
+ * `parseDirection` turns one raw model response into a typed `RedesignDirection`
+ * or a typed `DirectionParseError`. It is FAIL-CLOSED by construction: malformed
+ * JSON, a missing/ill-typed field, an ungrounded direction, or a hallucinated
+ * exemplar id all yield an explicit error — never a fabricated or half-built
+ * direction. The generator drops errored calls rather than inventing content.
+ *
+ * Hostile-input safe: the response is parsed with `JSON.parse` only (no eval),
+ * and the returned direction is assembled FIELD-BY-FIELD from validated values,
+ * so unexpected keys (including `__proto__`) never leak into the result and no
+ * prototype is mutated.
+ *
+ * No IO, no LLM, no browser — unit-tested on string fixtures alone.
+ */
+const fail = (reason) => ({ ok: false, reason });
+const isRecord = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isString = (v) => typeof v === 'string';
+const isFiniteNumber = (v) => typeof v === 'number' && Number.isFinite(v);
+const isStringArray = (v) => Array.isArray(v) && v.every(isString);
+const isNumberArray = (v) => Array.isArray(v) && v.every(isFiniteNumber);
+/**
+ * Pull the outermost JSON object out of a model response. Tolerates a leading
+ * markdown fence and any prose preamble/suffix the gateway wraps around the
+ * object. Returns null when no object literal is present.
+ */
+function extractJsonObject(raw) {
+    let text = raw.trim();
+    if (text.startsWith('```')) {
+        text = text.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/i, '').trim();
+    }
+    const first = text.indexOf('{');
+    const last = text.lastIndexOf('}');
+    if (first < 0 || last <= first)
+        return null;
+    return text.slice(first, last + 1);
+}
+function parseTypeSystem(raw) {
+    if (!isRecord(raw))
+        return 'typeSystem must be an object';
+    if (!isStringArray(raw.families) || raw.families.length === 0)
+        return 'typeSystem.families must be a non-empty string[]';
+    if (!isNumberArray(raw.scalePx) || raw.scalePx.length === 0)
+        return 'typeSystem.scalePx must be a non-empty number[]';
+    if (!isFiniteNumber(raw.ratio))
+        return 'typeSystem.ratio must be a number';
+    if (!isString(raw.rationale))
+        return 'typeSystem.rationale must be a string';
+    return { families: raw.families, scalePx: raw.scalePx, ratio: raw.ratio, rationale: raw.rationale };
+}
+function parseColorSystem(raw) {
+    if (!isRecord(raw))
+        return 'colorSystem must be an object';
+    if (!isString(raw.primary))
+        return 'colorSystem.primary must be a string';
+    if (!isStringArray(raw.neutrals))
+        return 'colorSystem.neutrals must be a string[]';
+    if (!isString(raw.background))
+        return 'colorSystem.background must be a string';
+    if (!isString(raw.rationale))
+        return 'colorSystem.rationale must be a string';
+    if (raw.accent !== undefined && !isString(raw.accent))
+        return 'colorSystem.accent must be a string when present';
+    const spec = {
+        primary: raw.primary,
+        neutrals: raw.neutrals,
+        background: raw.background,
+        rationale: raw.rationale,
+    };
+    if (isString(raw.accent))
+        spec.accent = raw.accent;
+    return spec;
+}
+function parseMotionSpec(raw) {
+    if (!isRecord(raw))
+        return 'motionSpec must be an object';
+    if (!isNumberArray(raw.durationsMs))
+        return 'motionSpec.durationsMs must be a number[]';
+    if (!isStringArray(raw.easings))
+        return 'motionSpec.easings must be a string[]';
+    if (!isStringArray(raw.cues))
+        return 'motionSpec.cues must be a string[]';
+    return { durationsMs: raw.durationsMs, easings: raw.easings, cues: raw.cues };
+}
+function parseCopy(raw) {
+    if (!Array.isArray(raw))
+        return 'copy must be an array';
+    const out = [];
+    for (const item of raw) {
+        if (!isRecord(item))
+            return 'each copy entry must be an object';
+        if (!isString(item.location))
+            return 'copy[].location must be a string';
+        if (!isString(item.after))
+            return 'copy[].after must be a string';
+        if (item.before !== undefined && !isString(item.before))
+            return 'copy[].before must be a string when present';
+        const rev = { location: item.location, after: item.after };
+        if (isString(item.before))
+            rev.before = item.before;
+        out.push(rev);
+    }
+    return out;
+}
+/**
+ * Ids in `d.groundedInExemplarIds` that are NOT in `allowedIds` (the retrieved
+ * set). Empty ⇒ the direction is grounded only in real, retrieved exemplars.
+ */
+export function validateGrounding(d, allowedIds) {
+    const allowed = new Set(allowedIds);
+    return d.groundedInExemplarIds.filter((id) => !allowed.has(id));
+}
+/**
+ * Parse one model response into a `RedesignDirection`. Fail-closed: any defect
+ * returns a `DirectionParseError`, never a partial or invented direction.
+ */
+export function parseDirection(raw, allowedIds) {
+    const json = extractJsonObject(raw);
+    if (json === null)
+        return fail('no JSON object found in model output');
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (e) {
+        return fail(`invalid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!isRecord(parsed))
+        return fail('parsed value is not an object');
+    if (!isString(parsed.id))
+        return fail('missing or invalid field: id');
+    if (!isString(parsed.name))
+        return fail('missing or invalid field: name');
+    if (!isString(parsed.rationale))
+        return fail('missing or invalid field: rationale');
+    if (!isString(parsed.asciiLayout))
+        return fail('missing or invalid field: asciiLayout');
+    if (!isStringArray(parsed.hierarchy) || parsed.hierarchy.length === 0) {
+        return fail('hierarchy must be a non-empty string[]');
+    }
+    if (!isStringArray(parsed.groundedInExemplarIds)) {
+        return fail('missing or invalid field: groundedInExemplarIds');
+    }
+    const typeSystem = parseTypeSystem(parsed.typeSystem);
+    if (typeof typeSystem === 'string')
+        return fail(typeSystem);
+    const colorSystem = parseColorSystem(parsed.colorSystem);
+    if (typeof colorSystem === 'string')
+        return fail(colorSystem);
+    const motionSpec = parseMotionSpec(parsed.motionSpec);
+    if (typeof motionSpec === 'string')
+        return fail(motionSpec);
+    const copy = parseCopy(parsed.copy);
+    if (typeof copy === 'string')
+        return fail(copy);
+    // Assemble field-by-field — never spread `parsed` — so no unexpected key
+    // (e.g. `__proto__`) survives into the result.
+    const direction = {
+        id: parsed.id,
+        name: parsed.name,
+        rationale: parsed.rationale,
+        asciiLayout: parsed.asciiLayout,
+        typeSystem,
+        colorSystem,
+        motionSpec,
+        hierarchy: parsed.hierarchy,
+        copy,
+        groundedInExemplarIds: parsed.groundedInExemplarIds,
+    };
+    if (direction.groundedInExemplarIds.length === 0) {
+        return fail('direction is ungrounded (empty groundedInExemplarIds)');
+    }
+    const offenders = validateGrounding(direction, allowedIds);
+    if (offenders.length > 0) {
+        return fail(`grounded in unknown exemplar ids: ${offenders.join(', ')}`);
+    }
+    return { ok: true, direction };
+}
+//# sourceMappingURL=parse.js.map

package/dist/design/audit/reference/generate/parse.js.map

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

package/dist/design/audit/reference/generate/prompt.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Redesign-generation prompt builder — a PURE core of the generative layer.
+ *
+ * `buildDirectionPrompt` grounds ONE retrieved world-class exemplar's identity
+ * (id + DNA) into a single-direction generation request for the page under
+ * audit. The generator (`generate/generator.ts`) fans this out — one
+ * `brain.complete` per exemplar — so the N named `RedesignDirection`s emerge
+ * from N independent, individually-grounded calls rather than one mega-prompt.
+ *
+ * It performs NO IO, NO LLM, NO browser work and is byte-stable for fixed
+ * inputs (no clock, no randomness), so it unit-tests on static fixtures and a
+ * fixed-input snapshot pins its determinism.
+ *
+ * Budget discipline: both injected DNA summaries are bounded by `maxRefChars`
+ * (via the deterministic `summarizeDNA`) and any operator rubric is truncated,
+ * so a large reference can never blow the generation token budget.
+ */
+import type { GenerationContext, RetrievalResult } from '../contracts.js';
+/** Tuning knobs for the deterministic prompt. */
+export interface DirectionPromptOptions {
+    /**
+     * Max chars for EACH injected DNA summary (page-under-audit + exemplar). The
+     * single lever that bounds the prompt's reference payload. px/ms values inside
+     * the summary are preserved; only the tail is clipped.
+     */
+    maxRefChars?: number;
+}
+/**
+ * Build the `{ system, user }` pair for a single reference-grounded redesign
+ * direction. Deterministic: identical inputs always yield identical strings.
+ */
+export declare function buildDirectionPrompt(ctx: GenerationContext, exemplar: RetrievalResult, opts?: DirectionPromptOptions): {
+    system: string;
+    user: string;
+};
+//# sourceMappingURL=prompt.d.ts.map

package/dist/design/audit/reference/generate/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/generate/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAGzE,iDAAiD;AACjD,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAgGD;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,iBAAiB,EACtB,QAAQ,EAAE,eAAe,EACzB,IAAI,GAAE,sBAA2B,GAChC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAqBlC"}

package/dist/design/audit/reference/generate/prompt.js

@@ -0,0 +1,124 @@
+/**
+ * Redesign-generation prompt builder — a PURE core of the generative layer.
+ *
+ * `buildDirectionPrompt` grounds ONE retrieved world-class exemplar's identity
+ * (id + DNA) into a single-direction generation request for the page under
+ * audit. The generator (`generate/generator.ts`) fans this out — one
+ * `brain.complete` per exemplar — so the N named `RedesignDirection`s emerge
+ * from N independent, individually-grounded calls rather than one mega-prompt.
+ *
+ * It performs NO IO, NO LLM, NO browser work and is byte-stable for fixed
+ * inputs (no clock, no randomness), so it unit-tests on static fixtures and a
+ * fixed-input snapshot pins its determinism.
+ *
+ * Budget discipline: both injected DNA summaries are bounded by `maxRefChars`
+ * (via the deterministic `summarizeDNA`) and any operator rubric is truncated,
+ * so a large reference can never blow the generation token budget.
+ */
+import { summarizeDNA } from '../dna/derive.js';
+const DEFAULT_MAX_REF_CHARS = 900;
+// The composed rubric body can be arbitrarily long; cap it so scoring criteria
+// never dominate the generation budget. Independent of `maxRefChars` (a
+// different concern: criteria vs reference identity).
+const MAX_RUBRIC_CHARS = 1600;
+const truncate = (s, max) => s.length > max ? `${s.slice(0, max - 1)}…` : s;
+/**
+ * The art-director persona + output contract. A module constant so the system
+ * half of every generation call is byte-identical run-to-run.
+ */
+const GENERATION_SYSTEM_PROMPT = [
+    'You are a world-class art director. You translate ONE concrete, named',
+    'world-class reference into a single coherent, buildable redesign direction for',
+    'the page under audit — not a menu of options, one opinionated direction.',
+    '',
+    'Hard rules:',
+    '- Ground every decision in the named REFERENCE EXEMPLAR below. Echo its id in',
+    '  `groundedInExemplarIds`. NEVER invent, guess, or cite an exemplar id you',
+    '  were not given.',
+    '- Specify concrete values: hex colors, px type sizes, ms durations, and real',
+    '  revised copy strings — never placeholders like "TODO" or "lorem ipsum".',
+    '- The ASCII layout must be a real box-drawing diagram of the proposed page',
+    '  structure, top to bottom.',
+    '- Preserve or improve the page\'s measured accessibility (contrast, a11y).',
+    '  Never propose a change that would regress it.',
+    '- If the REFERENCE EXEMPLAR\'s DNA reports scroll-driven motion (scroll',
+    '  reveals, sticky pinning, or parallax) and the page does not, propose concrete',
+    '  scroll interactions in `motionSpec.cues`, naming the specific reveal, pin, or',
+    '  parallax grounded in that exemplar. NEVER invent scroll motion the exemplar',
+    '  does not show.',
+    '- Output STRICT JSON only: a single object matching the OUTPUT CONTRACT, with',
+    '  no surrounding prose and no markdown code fences.',
+].join('\n');
+function renderPageBlock(ctx, maxRefChars) {
+    const c = ctx.classification;
+    return [
+        'PAGE UNDER REDESIGN',
+        `url: ${ctx.url}`,
+        `type: ${c.type}   domain: ${c.domain}   maturity: ${c.maturity}`,
+        `intent: ${c.intent}`,
+        'current design DNA:',
+        summarizeDNA(ctx.dna, { maxChars: maxRefChars }),
+    ].join('\n');
+}
+function renderExemplarBlock(hit, maxRefChars) {
+    const e = hit.exemplar;
+    const reasons = hit.reasons.length > 0 ? hit.reasons.join('; ') : 'nearest aesthetic neighbour';
+    return [
+        'REFERENCE EXEMPLAR (ground every choice in this one page)',
+        `id: ${e.id}   source: ${e.source}   type: ${e.pageType}`,
+        `url: ${e.url}`,
+        `job-to-be-done: ${e.jobToBeDone}`,
+        `why it was retrieved: ${reasons}`,
+        'its design DNA:',
+        summarizeDNA(e.dna, { maxChars: maxRefChars }),
+    ].join('\n');
+}
+function renderConstraints(ctx) {
+    const m = ctx.measurements;
+    if (!m)
+        return null;
+    const aa = m.contrast.summary.aaPassRate;
+    const blocking = m.a11y.violations.filter((v) => v.impact === 'critical' || v.impact === 'serious').length;
+    return [
+        'GROUND-TRUTH CONSTRAINTS (deterministic — do not regress)',
+        `current AA contrast pass rate: ${aa}; blocking a11y issues: ${blocking}.`,
+        'The redesign must keep contrast at or above this rate and must not introduce',
+        'new blocking accessibility issues.',
+    ].join('\n');
+}
+const OUTPUT_CONTRACT = [
+    'OUTPUT CONTRACT — return STRICT JSON matching this exact shape, nothing else:',
+    '{',
+    '  "id": "short-slug",',
+    '  "name": "evocative direction name",',
+    '  "rationale": "why this direction serves the page\'s job-to-be-done",',
+    '  "asciiLayout": "ASCII / box-drawing diagram of the proposed page structure",',
+    '  "typeSystem": { "families": ["Font A"], "scalePx": [14, 18, 24, 32], "ratio": 1.25, "rationale": "..." },',
+    '  "colorSystem": { "primary": "#2563eb", "accent": "#f59e0b", "neutrals": ["#111827", "#6b7280"], "background": "#ffffff", "rationale": "..." },',
+    '  "motionSpec": { "durationsMs": [160, 240], "easings": ["ease-out"], "cues": ["where motion is applied and why — name scroll reveals / sticky pins / parallax when grounded in a scroll-rich exemplar"] },',
+    '  "hierarchy": ["most prominent element", "...", "least prominent element"],',
+    '  "copy": [{ "location": "h1", "before": "current copy", "after": "revised copy" }],',
+    '  "groundedInExemplarIds": ["<the reference exemplar id above>"]',
+    '}',
+].join('\n');
+/**
+ * Build the `{ system, user }` pair for a single reference-grounded redesign
+ * direction. Deterministic: identical inputs always yield identical strings.
+ */
+export function buildDirectionPrompt(ctx, exemplar, opts = {}) {
+    const maxRefChars = opts.maxRefChars ?? DEFAULT_MAX_REF_CHARS;
+    const sections = [
+        renderPageBlock(ctx, maxRefChars),
+        renderExemplarBlock(exemplar, maxRefChars),
+    ];
+    const constraints = renderConstraints(ctx);
+    if (constraints)
+        sections.push(constraints);
+    if (ctx.rubricBody && ctx.rubricBody.trim().length > 0) {
+        sections.push(['SCORING CRITERIA (optimise the redesign against these)', truncate(ctx.rubricBody.trim(), MAX_RUBRIC_CHARS)].join('\n'));
+    }
+    sections.push(OUTPUT_CONTRACT);
+    sections.push(`Produce exactly ONE redesign direction grounded in exemplar "${exemplar.exemplar.id}". Return ONLY the JSON object.`);
+    return { system: GENERATION_SYSTEM_PROMPT, user: sections.join('\n\n') };
+}
+//# sourceMappingURL=prompt.js.map

package/dist/design/audit/reference/generate/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../../../../src/design/audit/reference/generate/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAY/C,MAAM,qBAAqB,GAAG,GAAG,CAAA;AACjC,+EAA+E;AAC/E,wEAAwE;AACxE,sDAAsD;AACtD,MAAM,gBAAgB,GAAG,IAAI,CAAA;AAE7B,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAE,GAAW,EAAU,EAAE,CAClD,CAAC,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;AAEhD;;;GAGG;AACH,MAAM,wBAAwB,GAAG;IAC/B,uEAAuE;IACvE,gFAAgF;IAChF,0EAA0E;IAC1E,EAAE;IACF,aAAa;IACb,+EAA+E;IAC/E,4EAA4E;IAC5E,mBAAmB;IACnB,8EAA8E;IAC9E,2EAA2E;IAC3E,4EAA4E;IAC5E,6BAA6B;IAC7B,4EAA4E;IAC5E,iDAAiD;IACjD,yEAAyE;IACzE,iFAAiF;IACjF,iFAAiF;IACjF,+EAA+E;IAC/E,kBAAkB;IAClB,+EAA+E;IAC/E,qDAAqD;CACtD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ,SAAS,eAAe,CAAC,GAAsB,EAAE,WAAmB;IAClE,MAAM,CAAC,GAAG,GAAG,CAAC,cAAc,CAAA;IAC5B,OAAO;QACL,qBAAqB;QACrB,QAAQ,GAAG,CAAC,GAAG,EAAE;QACjB,SAAS,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,MAAM,gBAAgB,CAAC,CAAC,QAAQ,EAAE;QACjE,WAAW,CAAC,CAAC,MAAM,EAAE;QACrB,qBAAqB;QACrB,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;KACjD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC;AAED,SAAS,mBAAmB,CAAC,GAAoB,EAAE,WAAmB;IACpE,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAA;IACtB,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,6BAA6B,CAAA;IAC/F,OAAO;QACL,2DAA2D;QAC3D,OAAO,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,MAAM,YAAY,CAAC,CAAC,QAAQ,EAAE;QACzD,QAAQ,CAAC,CAAC,GAAG,EAAE;QACf,mBAAmB,CAAC,CAAC,WAAW,EAAE;QAClC,yBAAyB,OAAO,EAAE;QAClC,iBAAiB;QACjB,YAAY,CAAC,CAAC,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;KAC/C,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC;AAED,SAAS,iBAAiB,CAAC,GAAsB;IAC/C,MAAM,CAAC,GAAG,GAAG,CAAC,YAAY,CAAA;IAC1B,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IACnB,MAAM,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAA;IACxC,MAAM,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CACvC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,CACzD,CAAC,MAAM,CAAA;IACR,OAAO;QACL,2DAA2D;QAC3D,kCAAkC,EAAE,2BAA2B,QAAQ,GAAG;QAC1E,8EAA8E;QAC9E,oCAAoC;KACrC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC;AAED,MAAM,eAAe,GAAG;IACtB,+EAA+E;IAC/E,GAAG;IACH,uBAAuB;IACvB,uCAAuC;IACvC,wEAAwE;IACxE,gFAAgF;IAChF,6GAA6G;IAC7G,kJAAkJ;IAClJ,6MAA6M;IAC7M,8EAA8E;IAC9E,sFAAsF;IACtF,kEAAkE;IAClE,GAAG;CACJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,GAAsB,EACtB,QAAyB,EACzB,OAA+B,EAAE;IAEjC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,qBAAqB,CAAA;IAE7D,MAAM,QAAQ,GAAa;QACzB,eAAe,CAAC,GAAG,EAAE,WAAW,CAAC;QACjC,mBAAmB,CAAC,QAAQ,EAAE,WAAW,CAAC;KAC3C,CAAA;IAED,MAAM,WAAW,GAAG,iBAAiB,CAAC,GAAG,CAAC,CAAA;IAC1C,IAAI,WAAW;QAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;IAE3C,IAAI,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvD,QAAQ,CAAC,IAAI,CAAC,CAAC,wDAAwD,EAAE,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,EAAE,gBAAgB,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IACzI,CAAC;IAED,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;IAC9B,QAAQ,CAAC,IAAI,CACX,gEAAgE,QAAQ,CAAC,QAAQ,CAAC,EAAE,iCAAiC,CACtH,CAAA;IAED,OAAO,EAAE,MAAM,EAAE,wBAAwB,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAA;AAC1E,CAAC"}

package/dist/design/audit/reference/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * L5 barrel — the public surface of the reference-grounded engine.
+ *
+ * Re-exports ONLY the entrypoints, the shared contracts, and the offline
+ * authoring + eval helpers a consumer is meant to call. The L1-L3 internals
+ * (pure cores, adapters, `engine/core`, `engine/wiring`) are deliberately NOT
+ * re-exported here — callers reach the engine through `runReferenceRedesign`
+ * (rich artifact) or `evaluateReferenceGrounded` (pipeline `PageAuditResult`),
+ * not by importing a stage.
+ */
+export * from './contracts.js';
+export { runReferenceRedesign } from './run.js';
+export type { RunReferenceRedesignOptions } from './run.js';
+export { evaluateReferenceGrounded } from './pipeline/evaluate-reference.js';
+export type { EvaluateReferenceInput, ReferenceEvaluation } from './pipeline/evaluate-reference.js';
+export { renderArtifactMarkdown, renderRedesignDirectionsSummary, renderRedesignTarget, artifactSlug } from './artifact/render.js';
+export { resolveReferenceContext } from './reference-context.js';
+export type { ResolveReferenceDeps, ResolveReferenceOptions } from './reference-context.js';
+export { resolveReferenceConfig, DEFAULT_REFERENCE_CONFIG, DEFAULT_RETRIEVE_WEIGHTS, } from './config.js';
+export type { ReferenceConfigOverrides } from './config.js';
+export type { ReferenceBrain } from './engine/wiring.js';
+export { createFileCorpusStore } from './corpus/store.js';
+export { buildExemplar, ingestCorpus } from './corpus/build.js';
+export type { BuildExemplarOptions, ExemplarClassifier, ExemplarClassifyInput, ExemplarClassification, IngestTarget, IngestCorpusOptions, IngestResult, } from './corpus/build.js';
+export { tasteAgreement, tasteMetricsFromVerdicts } from './eval/taste-core.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/design/audit/reference/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/design/audit/reference/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,cAAc,gBAAgB,CAAA;AAG9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAC/C,YAAY,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAA;AAG3D,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAA;AAC5E,YAAY,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAA;AAKnG,OAAO,EAAE,sBAAsB,EAAE,+BAA+B,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAGlI,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAChE,YAAY,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAG3F,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAG3D,YAAY,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAGxD,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAC/D,YAAY,EACV,oBAAoB,EACpB,kBAAkB,EAClB,qBAAqB,EACrB,sBAAsB,EACtB,YAAY,EACZ,mBAAmB,EACnB,YAAY,GACb,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/design/audit/reference/index.js

@@ -0,0 +1,31 @@
+/**
+ * L5 barrel — the public surface of the reference-grounded engine.
+ *
+ * Re-exports ONLY the entrypoints, the shared contracts, and the offline
+ * authoring + eval helpers a consumer is meant to call. The L1-L3 internals
+ * (pure cores, adapters, `engine/core`, `engine/wiring`) are deliberately NOT
+ * re-exported here — callers reach the engine through `runReferenceRedesign`
+ * (rich artifact) or `evaluateReferenceGrounded` (pipeline `PageAuditResult`),
+ * not by importing a stage.
+ */
+// All shared types + boundary interfaces (RedesignArtifact, PageAuditResult,
+// ReferenceGroundedConfig, Exemplar, TasteVerdict, …) flow from the one hub.
+export * from './contracts.js';
+// Rich library/CLI entry → RedesignArtifact.
+export { runReferenceRedesign } from './run.js';
+// Flagged STAGE-6 entry → PageAuditResult (drops into the existing pipeline).
+export { evaluateReferenceGrounded } from './pipeline/evaluate-reference.js';
+// Human-facing renderers for the redesign brief surfaced in the audit report:
+// the full rich brief and a compact report-section projection, plus the shared
+// slug used to name the brief file.
+export { renderArtifactMarkdown, renderRedesignDirectionsSummary, renderRedesignTarget, artifactSlug } from './artifact/render.js';
+// CLI plumbing: resolve `--reference <url|path>` into a ReferenceContext once.
+export { resolveReferenceContext } from './reference-context.js';
+// Config: frozen defaults + the clamped operator-override merge.
+export { resolveReferenceConfig, DEFAULT_REFERENCE_CONFIG, DEFAULT_RETRIEVE_WEIGHTS, } from './config.js';
+// Corpus access: the file-backed store + the offline authoring path.
+export { createFileCorpusStore } from './corpus/store.js';
+export { buildExemplar, ingestCorpus } from './corpus/build.js';
+// Taste eval: corpus-vs-corpus agreement + generated-vs-reference metrics.
+export { tasteAgreement, tasteMetricsFromVerdicts } from './eval/taste-core.js';
+//# sourceMappingURL=index.js.map

package/dist/design/audit/reference/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/design/audit/reference/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,6EAA6E;AAC7E,6EAA6E;AAC7E,cAAc,gBAAgB,CAAA;AAE9B,6CAA6C;AAC7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAG/C,8EAA8E;AAC9E,OAAO,EAAE,yBAAyB,EAAE,MAAM,kCAAkC,CAAA;AAG5E,8EAA8E;AAC9E,+EAA+E;AAC/E,oCAAoC;AACpC,OAAO,EAAE,sBAAsB,EAAE,+BAA+B,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAElI,+EAA+E;AAC/E,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAGhE,iEAAiE;AACjE,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,aAAa,CAAA;AAMpB,qEAAqE;AACrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAW/D,2EAA2E;AAC3E,OAAO,EAAE,cAAc,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAA"}

package/dist/design/audit/reference/judge/image-clamp.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Vision-image clamp — the one pre-flight a screenshot needs before a vision API
+ * call. PURE (Buffer in → Buffer out, no IO): the disk read lives in the
+ * `vision-model` adapter, this only does pixel math, so it unit-tests with
+ * synthesised PNGs and no model.
+ *
+ * Why it exists: corpus exemplars are FULL-PAGE captures (e.g. 1440×14739). The
+ * Anthropic vision API rejects any image whose longest edge exceeds 8000px with a
+ * 400 `invalid_request_error`, and it internally downscales anything past ~1568px
+ * on the long edge regardless — so an un-clamped full-page screenshot either hard-
+ * fails (Anthropic-family providers) or burns tokens encoding detail the model
+ * never sees. Clamping the longest edge to {@link VISION_MAX_EDGE_PX} both clears
+ * the hard limit AND matches the API's own effective resolution, at a fraction of
+ * the base64 size.
+ *
+ * Fail-soft by design: an image already within the limit is returned BYTE-FOR-BYTE
+ * unchanged (no decode/re-encode), and a buffer that is not decodable as PNG is
+ * passed through untouched rather than thrown — the downstream model call is the
+ * place a genuinely bad image surfaces, not this size guard.
+ */
+/**
+ * Longest-edge ceiling, in px. 1568 is the resolution the Anthropic vision API
+ * downscales to internally, and is comfortably under its 8000px hard limit — so
+ * clamping here is lossless relative to what the model would actually see while
+ * cutting the encoded payload by orders of magnitude on tall captures.
+ */
+export declare const VISION_MAX_EDGE_PX = 1568;
+/**
+ * Downscale a PNG so its longest edge is ≤ `maxEdge`, preserving aspect ratio with
+ * an area-average (box) filter. Returns the ORIGINAL buffer unchanged when the
+ * image is already within bounds or cannot be parsed as PNG.
+ */
+export declare function clampPngLongestEdge(buf: Buffer, maxEdge?: number): Buffer;
+//# sourceMappingURL=image-clamp.d.ts.map

package/dist/design/audit/reference/judge/image-clamp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-clamp.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/judge/image-clamp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAA;AAEtC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,MAA2B,GAAG,MAAM,CAsD7F"}

package/dist/design/audit/reference/judge/image-clamp.js

@@ -0,0 +1,88 @@
+/**
+ * Vision-image clamp — the one pre-flight a screenshot needs before a vision API
+ * call. PURE (Buffer in → Buffer out, no IO): the disk read lives in the
+ * `vision-model` adapter, this only does pixel math, so it unit-tests with
+ * synthesised PNGs and no model.
+ *
+ * Why it exists: corpus exemplars are FULL-PAGE captures (e.g. 1440×14739). The
+ * Anthropic vision API rejects any image whose longest edge exceeds 8000px with a
+ * 400 `invalid_request_error`, and it internally downscales anything past ~1568px
+ * on the long edge regardless — so an un-clamped full-page screenshot either hard-
+ * fails (Anthropic-family providers) or burns tokens encoding detail the model
+ * never sees. Clamping the longest edge to {@link VISION_MAX_EDGE_PX} both clears
+ * the hard limit AND matches the API's own effective resolution, at a fraction of
+ * the base64 size.
+ *
+ * Fail-soft by design: an image already within the limit is returned BYTE-FOR-BYTE
+ * unchanged (no decode/re-encode), and a buffer that is not decodable as PNG is
+ * passed through untouched rather than thrown — the downstream model call is the
+ * place a genuinely bad image surfaces, not this size guard.
+ */
+import { PNG } from 'pngjs';
+/**
+ * Longest-edge ceiling, in px. 1568 is the resolution the Anthropic vision API
+ * downscales to internally, and is comfortably under its 8000px hard limit — so
+ * clamping here is lossless relative to what the model would actually see while
+ * cutting the encoded payload by orders of magnitude on tall captures.
+ */
+export const VISION_MAX_EDGE_PX = 1568;
+/**
+ * Downscale a PNG so its longest edge is ≤ `maxEdge`, preserving aspect ratio with
+ * an area-average (box) filter. Returns the ORIGINAL buffer unchanged when the
+ * image is already within bounds or cannot be parsed as PNG.
+ */
+export function clampPngLongestEdge(buf, maxEdge = VISION_MAX_EDGE_PX) {
+    let png;
+    try {
+        png = PNG.sync.read(buf);
+    }
+    catch {
+        // Not a decodable PNG — leave it to the model call to reject; this guard only
+        // shrinks oversized images, it does not validate them.
+        return buf;
+    }
+    const { width, height } = png;
+    const longest = Math.max(width, height);
+    if (longest <= maxEdge)
+        return buf;
+    const scale = maxEdge / longest;
+    const newW = Math.max(1, Math.round(width * scale));
+    const newH = Math.max(1, Math.round(height * scale));
+    const out = new PNG({ width: newW, height: newH });
+    // Each destination pixel averages the source rectangle it maps to. The
+    // rectangles tile the source exactly, so every source pixel is read once —
+    // O(source pixels), independent of the downscale factor.
+    const src = png.data;
+    const dst = out.data;
+    for (let y = 0; y < newH; y++) {
+        const sy0 = Math.floor((y * height) / newH);
+        const sy1 = Math.max(sy0 + 1, Math.floor(((y + 1) * height) / newH));
+        for (let x = 0; x < newW; x++) {
+            const sx0 = Math.floor((x * width) / newW);
+            const sx1 = Math.max(sx0 + 1, Math.floor(((x + 1) * width) / newW));
+            let r = 0;
+            let g = 0;
+            let b = 0;
+            let a = 0;
+            let n = 0;
+            for (let sy = sy0; sy < sy1; sy++) {
+                const rowBase = sy * width;
+                for (let sx = sx0; sx < sx1; sx++) {
+                    const idx = (rowBase + sx) << 2;
+                    r += src[idx];
+                    g += src[idx + 1];
+                    b += src[idx + 2];
+                    a += src[idx + 3];
+                    n++;
+                }
+            }
+            const o = (y * newW + x) << 2;
+            dst[o] = Math.round(r / n);
+            dst[o + 1] = Math.round(g / n);
+            dst[o + 2] = Math.round(b / n);
+            dst[o + 3] = Math.round(a / n);
+        }
+    }
+    return PNG.sync.write(out);
+}
+//# sourceMappingURL=image-clamp.js.map

package/dist/design/audit/reference/judge/image-clamp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-clamp.js","sourceRoot":"","sources":["../../../../../src/design/audit/reference/judge/image-clamp.ts"],"names":[],"mappings":"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"}

package/dist/design/audit/reference/judge/pairwise.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Position-swapped pairwise debias — the core that cancels slot bias.
+ *
+ * A single judge call is contaminated by position bias: models systematically
+ * over-prefer whichever design sits in slot A. `judgePair` neutralises it by
+ * running BOTH slot orders through the INJECTED `TasteJudge` (A-vs-B and
+ * B-vs-A) and reconciling. The model call is the only impure part and it is
+ * injected, so `reconcileVerdicts` — where all the debias logic lives — is fully
+ * pure and unit-tests with stub verdicts and zero live model.
+ *
+ * Reconciliation rule (measures taste, not slot):
+ *  - both orders pick the SAME id  ⇒ that id wins (margin = mean confidence)
+ *  - the preferred id FLIPS with the slot ⇒ pure position bias ⇒ tie
+ *  - only one order separates them ⇒ a low-confidence win (margin halved)
+ *  - both orders tie ⇒ tie
+ *
+ * `swapped` re-labels the subjects (a↔b) while preserving `dimension`,
+ * `reference`, and `rubricBody`, so the judge sees the same comparison from the
+ * other side — the second call is a genuine slot swap, not a different question.
+ */
+import type { JudgePairInput, RawVerdict, TasteJudge, TasteVerdict } from '../contracts.js';
+/**
+ * Reconcile the two slot-order verdicts into a stable, id-keyed `TasteVerdict`.
+ * Pure: no IO, no model. `ab` presented a→SLOT A, b→SLOT B; `ba` presented
+ * b→SLOT A, a→SLOT B.
+ */
+export declare function reconcileVerdicts(ab: RawVerdict, ba: RawVerdict, aId: string, bId: string): TasteVerdict;
+/**
+ * Run a single comparison through both slot orders (× `reps`) and reconcile to a
+ * position-debiased `TasteVerdict`. The `TasteJudge` is injected, so this is the
+ * only impure boundary; all aggregation is deterministic.
+ */
+export declare function judgePair(judge: TasteJudge, input: JudgePairInput, reps?: number): Promise<TasteVerdict>;
+//# sourceMappingURL=pairwise.d.ts.map

package/dist/design/audit/reference/judge/pairwise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairwise.d.ts","sourceRoot":"","sources":["../../../../../src/design/audit/reference/judge/pairwise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAmB3F;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,UAAU,EACd,EAAE,EAAE,UAAU,EACd,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,YAAY,CA+Bd;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,UAAU,EACjB,KAAK,EAAE,cAAc,EACrB,IAAI,SAAI,GACP,OAAO,CAAC,YAAY,CAAC,CAsBvB"}