@tangle-network/browser-agent-driver 0.33.3 → 0.35.0

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

@@ -0,0 +1,220 @@
+/**
+ * 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 isStringArray = (v) => Array.isArray(v) && v.every(isString);
+/**
+ * Coerce a numeric value, tolerating the numeric STRINGS many models emit
+ * (`"1.25"`, `"16px"`). Same value, just typed — no fabrication. Returns
+ * undefined when there's no leading finite number to read.
+ */
+const coerceNumber = (v) => {
+    if (typeof v === 'number')
+        return Number.isFinite(v) ? v : undefined;
+    if (typeof v === 'string') {
+        const n = Number.parseFloat(v.trim());
+        return Number.isFinite(n) ? n : undefined;
+    }
+    return undefined;
+};
+/** Coerce an array of numbers, accepting numeric strings per element.
+ *  Returns undefined if the input isn't an array or any element won't coerce. */
+const coerceNumberArray = (v) => {
+    if (!Array.isArray(v))
+        return undefined;
+    const out = [];
+    for (const x of v) {
+        const n = coerceNumber(x);
+        if (n === undefined)
+            return undefined;
+        out.push(n);
+    }
+    return out;
+};
+/**
+ * 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. Distinguishes three cases so the caller can report each truthfully:
+ *   - `{ json }`       — an object literal was found;
+ *   - `{ truncated }`  — an object was OPENED (`{`) but never closed (`}`), i.e.
+ *                        the model ran out of output budget mid-object;
+ *   - `null`           — no object literal at all (empty or non-JSON output).
+ */
+function extractJsonObject(raw) {
+    let text = raw.trim();
+    if (text.startsWith('```')) {
+        text = text.replace(/^```(?:json)?\s*/i, '').replace(/```\s*$/i, '').trim();
+    }
+    const first = text.indexOf('{');
+    if (first < 0)
+        return null;
+    const last = text.lastIndexOf('}');
+    if (last <= first)
+        return { truncated: true };
+    return { json: 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[]';
+    const scalePx = coerceNumberArray(raw.scalePx);
+    if (!scalePx || scalePx.length === 0)
+        return 'typeSystem.scalePx must be a non-empty number[]';
+    const ratio = coerceNumber(raw.ratio);
+    if (ratio === undefined)
+        return 'typeSystem.ratio must be a number';
+    if (!isString(raw.rationale))
+        return 'typeSystem.rationale must be a string';
+    return { families: raw.families, scalePx, 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';
+    const durationsMs = coerceNumberArray(raw.durationsMs);
+    if (!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, 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 extracted = extractJsonObject(raw);
+    if (extracted === null) {
+        return fail(raw.trim().length === 0 ? 'model returned empty output' : 'no JSON object found in model output');
+    }
+    if ('truncated' in extracted) {
+        return fail('model output truncated — incomplete JSON object (raise the generation token budget for reasoning models)');
+    }
+    const json = extracted.json;
+    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;AAsJD;;;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,CAsBlC"}

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

@@ -0,0 +1,172 @@
+/**
+ * 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 senior product designer improving a REAL page so its actual users',
+    'accomplish their tasks faster and more easily. A named world-class reference',
+    'is provided ONLY as a source of visual craft — type, colour, spacing rhythm,',
+    'and motion. It is NOT a template: never copy its structure, layout archetype,',
+    'or content into the page. Judge your own work by the page\'s JOB, not by how',
+    'decorative it looks.',
+    '',
+    'Hard rules, in PRIORITY ORDER (a lower rule never justifies breaking a higher one):',
+    '- TASK FIRST. Design for the page\'s primary users and the job in its INTENT',
+    '  below. Every change must make that job easier. Aesthetics serve the task —',
+    '  never sacrifice the task to look more like the reference.',
+    '- PRESERVE FUNCTIONAL AFFORDANCES. Keep every way users find and move through',
+    '  the page: navigation, table of contents, menus, breadcrumbs, search,',
+    '  filters, pagination, tabs. Offer equivalent-or-better wayfinding — NEVER',
+    '  delete navigation to look cleaner.',
+    '- PRESERVE DENSITY WHERE IT IS THE VALUE. For information-dense or reference',
+    '  pages (docs, dashboards, status/console, data tables, lists, feeds,',
+    '  aggregators) density and scannability ARE the craft. Keep at least as many',
+    '  items / rows / sections visible as the original; do not trade content for',
+    '  whitespace, hero banners, or marketing-style cards. The reference informs',
+    '  polish WITHIN that density, never a reduction of it.',
+    '- RIGHT-SIZE THE INTERVENTION. If the page already serves its job well, the',
+    '  best redesign is surgical: refine type, colour, spacing, and hierarchy while',
+    '  keeping the structure and affordances. NEVER turn one kind of page into',
+    '  another — a docs page or a dashboard must not become a landing page.',
+    '- Ground the VISUAL CRAFT in the named REFERENCE EXEMPLAR and echo its id in',
+    '  `groundedInExemplarIds`. NEVER invent, guess, or cite an exemplar id you were',
+    '  not given. Borrow its craft, never its content or structure.',
+    '- Use only the page\'s OWN content. NEVER fabricate content it does not have —',
+    '  no invented metrics, counts, dates, statuses, activity feeds, or sections.',
+    '  You are given the page\'s design DNA + intent, NOT its full text or data, so',
+    '  do not assert specific values (numbers, percentages, dates, names) you were',
+    '  not given; refer to such content by its role. If the page is genuinely',
+    '  sparse, keep the redesign proportionally restrained rather than manufacturing',
+    '  content to fill a denser layout.',
+    '- Specify concrete DESIGN values: hex colours, px type sizes, ms durations.',
+    '  Revised copy may restyle the page\'s existing wording but must never invent',
+    '  facts or use placeholders like "TODO" or "lorem ipsum".',
+    '- The ASCII layout must be a real box-drawing diagram of the proposed structure,',
+    '  top to bottom, and must show the preserved navigation / affordances.',
+    '- Preserve or improve the page\'s measured accessibility (contrast, a11y); never',
+    '  propose a change that would regress it.',
+    '- 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 (borrow its VISUAL CRAFT only — type, colour, spacing,',
+        'motion. Do NOT copy its structure, information architecture, or content.)',
+        `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');
+}
+/**
+ * The per-page FUNCTIONAL CONTRACT — what the redesign must preserve, derived
+ * from the page's own measured DNA (not a hardcoded page-type table). Navigation
+ * affordances and information density are user value on functional pages; the
+ * generator must keep them. Density gating is data-driven off the measured
+ * `layout.density`, so a genuinely sparse page is never forced to stay dense.
+ */
+function renderFunctionalContract(ctx) {
+    const dna = ctx.dna;
+    const nav = dna.components?.nav ?? 0;
+    const density = dna.layout?.density ?? 'balanced';
+    const archetype = dna.layout?.archetype ?? 'unknown';
+    const lines = [
+        'FUNCTIONAL CONTRACT (preserve — the redesign must not regress these):',
+        `page type: ${ctx.classification.type}; measured layout density: ${density}; archetype: ${archetype}; navigation affordances detected: ${nav}.`,
+    ];
+    if (nav > 0)
+        lines.push(`- Keep all ${nav} navigation / wayfinding affordance(s) (menus, table of contents, breadcrumbs, search, tabs). Provide equivalent-or-better navigation; do not drop any.`);
+    if (density === 'dense')
+        lines.push('- This page is DENSE: its information density is the value. Keep at least as many items / rows / sections visible as today. Do not trade content for whitespace or hero sections.');
+    lines.push('- Improve craft within this structure. Do not convert this page into a different kind of page.');
+    return lines.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),
+        renderFunctionalContract(ctx),
+        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":"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"}

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"}