@tangle-network/browser-agent-driver 0.30.0 → 0.31.0

package/dist/jobs/store.js

@@ -0,0 +1,92 @@
+/**
+ * Job store — whole-file JSON per job + an append-only index for listing.
+ *
+ * Layout:
+ *   ~/.bad/jobs/<jobId>.json      — Job record (atomic write via tmp + rename)
+ *   ~/.bad/jobs/index.jsonl       — append-only one line per job ({jobId, status, createdAt, label})
+ *
+ * Whole-file rewrite is intentional: a job is a single coherent record with
+ * monotonically-extending `results[]`. Append-only at the entry level would
+ * duplicate target rows; append-only at the file level would force readers
+ * to fold N updates into one logical record. Atomic rename gives us crash
+ * safety without that complexity.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+const DEFAULT_DIR = path.join(os.homedir(), '.bad', 'jobs');
+export function jobsDir(override) {
+    return override ?? DEFAULT_DIR;
+}
+function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+export function jobPath(jobId, dir) {
+    return path.join(jobsDir(dir), `${jobId}.json`);
+}
+function indexPath(dir) {
+    return path.join(jobsDir(dir), 'index.jsonl');
+}
+export function newJobId(now = new Date()) {
+    const stamp = now.toISOString().replace(/[-:.]/g, '').slice(0, 15); // YYYYMMDDTHHMMSS
+    const rand = Math.random().toString(36).slice(2, 8);
+    return `job_${stamp}_${rand}`;
+}
+export function saveJob(job, dir) {
+    const target = jobPath(job.jobId, dir);
+    ensureDir(path.dirname(target));
+    const tmp = `${target}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(job, null, 2));
+    fs.renameSync(tmp, target);
+}
+export function loadJob(jobId, dir) {
+    const target = jobPath(jobId, dir);
+    if (!fs.existsSync(target))
+        return null;
+    return JSON.parse(fs.readFileSync(target, 'utf-8'));
+}
+export function appendIndexEntry(job, dir) {
+    const file = indexPath(dir);
+    ensureDir(path.dirname(file));
+    const line = JSON.stringify({
+        jobId: job.jobId,
+        status: job.status,
+        createdAt: job.createdAt,
+        label: job.spec.label ?? null,
+        targetCount: job.targets.length,
+    });
+    fs.appendFileSync(file, line + '\n');
+}
+/** Reads the index file. Later entries for the same jobId override earlier ones. */
+export function listJobs(dir) {
+    const file = indexPath(dir);
+    if (!fs.existsSync(file))
+        return [];
+    const lines = fs.readFileSync(file, 'utf-8').split('\n').filter(Boolean);
+    const map = new Map();
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            map.set(entry.jobId, entry);
+        }
+        catch {
+            // Skip malformed lines — index is best-effort.
+        }
+    }
+    return Array.from(map.values()).sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+export function updateJobStatus(jobId, status, dir) {
+    const job = loadJob(jobId, dir);
+    if (!job)
+        return null;
+    job.status = status;
+    if (status === 'running' && !job.startedAt)
+        job.startedAt = new Date().toISOString();
+    if (status === 'completed' || status === 'failed' || status === 'cancelled' || status === 'partial') {
+        job.completedAt = new Date().toISOString();
+    }
+    saveJob(job, dir);
+    appendIndexEntry(job, dir);
+    return job;
+}
+//# sourceMappingURL=store.js.map

package/dist/jobs/store.js.map

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

package/dist/jobs/types.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Job orchestration types — RFC-003: comparative-audit jobs.
+ *
+ * A job is a declarative spec ("audit these N URLs, optionally with M historical
+ * snapshots each") that fans out to the existing design-audit pipeline and
+ * persists the aggregate result so report generation can run later.
+ *
+ * Persistence: append-only JSONL at `~/.bad/jobs/<jobId>.json` (whole-file
+ * rewrites are fine — jobs are small) plus a one-line index entry at
+ * `~/.bad/jobs/index.jsonl` for fast listing.
+ */
+import type { AudienceTag, ModalityTag, RegulatoryContextTag, AudienceVulnerabilityTag } from '../design/audit/v2/types.js';
+export type JobKind = 'comparative-audit';
+export type JobStatus = 'queued' | 'running' | 'partial' | 'completed' | 'failed' | 'cancelled';
+export type DiscoverSource = 'list' | 'wayback';
+/** What targets to audit. `list` = explicit URLs; `wayback` = expand each URL into historical snapshots. */
+export interface DiscoverSpec {
+    source: DiscoverSource;
+    /** Explicit list of URLs (always required — it's the seed even for wayback). */
+    urls: string[];
+    /** wayback only: how many evenly-spaced snapshots to fetch per URL. Default 5. */
+    snapshotsPerUrl?: number;
+    /** wayback only: ISO date lower bound (e.g. "2010-01-01"). */
+    since?: string;
+    /** wayback only: ISO date upper bound (e.g. "2026-01-01"). */
+    until?: string;
+}
+/** Pass-through audit options — mirrors the design-audit CLI flags. */
+export interface AuditOptions {
+    pages?: number;
+    modality?: 'html' | 'ios' | 'android';
+    audience?: AudienceTag[];
+    audienceVulnerability?: AudienceVulnerabilityTag[];
+    modalityTag?: ModalityTag[];
+    regulatoryContext?: RegulatoryContextTag[];
+    headless?: boolean;
+    skipEthics?: boolean;
+    /**
+     * Layer 8 add-on: also run the deterministic brand/design-token extractor at
+     * every target. Adds ~10s/target (no LLM). Output lands at
+     * `<resultPath dir>/tokens.json` and is surfaced via `JobResultEntry.tokensPath`.
+     */
+    extractTokens?: boolean;
+}
+export interface JobSpec {
+    kind: JobKind;
+    discover: DiscoverSpec;
+    audit?: AuditOptions;
+    /** Bounded concurrency for the audit fan-out. Default 2 — Playwright + LLM rate limits cap real-world throughput. */
+    concurrency?: number;
+    /** Hard cost cap. The job aborts pre-flight if estimated cost exceeds this. */
+    maxCostUSD?: number;
+    /** Free-form label for humans (shows up in `bad jobs list`). */
+    label?: string;
+}
+/** One target = one (url, optional snapshot) pair the auditor will run on. */
+export interface JobTarget {
+    /** The original seed URL. For non-wayback discovery, this is also the audit URL. */
+    url: string;
+    /** For wayback targets: the actual snapshot URL passed to the audit. */
+    snapshotUrl?: string;
+    /** For wayback targets: ISO datetime when the snapshot was captured. */
+    capturedAt?: string;
+}
+export type JobResultStatus = 'ok' | 'failed' | 'skipped';
+export interface JobResultEntry extends JobTarget {
+    status: JobResultStatus;
+    /** runId of the design-audit run when status === 'ok'. */
+    runId?: string;
+    /** Path to the run's report.json (relative to cwd or absolute). */
+    resultPath?: string;
+    /** Failure reason when status === 'failed' or 'skipped'. */
+    error?: string;
+    /** Estimated USD cost of this audit (if available from telemetry). */
+    costUSD?: number;
+    /** Roll-up score copied out of the report for fast aggregation queries. */
+    rollupScore?: number;
+    /** Page-type classification. */
+    pageType?: string;
+    /** Path to the tokens.json from the brand-kit extractor (when extractTokens=true). */
+    tokensPath?: string;
+}
+export interface Job {
+    jobId: string;
+    spec: JobSpec;
+    status: JobStatus;
+    createdAt: string;
+    startedAt?: string;
+    completedAt?: string;
+    /** All discovered targets (length = number of audits the job will / did run). */
+    targets: JobTarget[];
+    /** Per-target outcome. Length matches `targets` once the job has progressed past discovery. */
+    results: JobResultEntry[];
+    /** Sum of `results[*].costUSD` for completed entries. */
+    totalCostUSD: number;
+    /** Free-form notes (errors, warnings, telemetry summary). */
+    notes?: string[];
+}
+export interface CostEstimate {
+    targetCount: number;
+    estimatedTotalUSD: number;
+    perAuditUSD: number;
+    /** Whether the estimate is above `spec.maxCostUSD`. */
+    exceedsCap: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/jobs/types.d.ts.map

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

package/dist/jobs/types.js

@@ -0,0 +1,13 @@
+/**
+ * Job orchestration types — RFC-003: comparative-audit jobs.
+ *
+ * A job is a declarative spec ("audit these N URLs, optionally with M historical
+ * snapshots each") that fans out to the existing design-audit pipeline and
+ * persists the aggregate result so report generation can run later.
+ *
+ * Persistence: append-only JSONL at `~/.bad/jobs/<jobId>.json` (whole-file
+ * rewrites are fine — jobs are small) plus a one-line index entry at
+ * `~/.bad/jobs/index.jsonl` for fast listing.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/jobs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/jobs/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/reports/aggregate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Deterministic aggregation over a job's per-target audit results.
+ *
+ * Every number that shows up in a report flows through here — never through
+ * an LLM. The narration layer can describe / contextualize / dramatize, but
+ * counts, scores, deltas, and rankings are all computed here. Same pattern
+ * we use for the audit patches contract: agent narrates, code computes.
+ */
+import type { Job } from '../jobs/types.js';
+import type { AggregateRow, CompareRunsResult, LongitudinalRow } from './types.js';
+/**
+ * Read each ok result's `report.json` from disk and project to AggregateRow.
+ * Skipped/failed entries become rows with `rollupScore: NaN` so callers can
+ * filter them — keeping them in the list preserves index alignment with
+ * `job.results` for tools that want to drill in.
+ */
+export declare function aggregateJob(job: Job): AggregateRow[];
+export interface LeaderboardOptions {
+    /** Filter by page type (e.g. only saas-app rows). */
+    byType?: string;
+    /** Top N entries. Default = no cap. */
+    topN?: number;
+    /** Sort direction. Default 'desc' (highest first). */
+    direction?: 'asc' | 'desc';
+}
+export declare function leaderboard(rows: AggregateRow[], opts?: LeaderboardOptions): AggregateRow[];
+/** Longitudinal view: all snapshots for one URL, sorted by capture time. */
+export declare function longitudinalFor(rows: AggregateRow[], url: string): LongitudinalRow[];
+export declare function compareRuns(a: AggregateRow, b: AggregateRow): CompareRunsResult;
+/** Group rows into tier buckets for "top 10 vs 100-200" style reports. */
+export interface TierBucket {
+    label: string;
+    rows: AggregateRow[];
+    meanScore: number;
+    medianScore: number;
+}
+export declare function tierBuckets(rows: AggregateRow[], boundaries: number[]): TierBucket[];
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/reports/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../../src/reports/aggregate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAkB,MAAM,kBAAkB,CAAA;AAE3D,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAkB,eAAe,EAAE,MAAM,YAAY,CAAA;AAkBlG;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,GAAG,YAAY,EAAE,CAMrD;AAwCD,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sDAAsD;IACtD,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;CAC3B;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,IAAI,GAAE,kBAAuB,GAAG,YAAY,EAAE,CAQ/F;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,eAAe,EAAE,CAUpF;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,iBAAiB,CAkB/E;AAED,0EAA0E;AAC1E,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,YAAY,EAAE,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAoBpF"}

package/dist/reports/aggregate.js

@@ -0,0 +1,145 @@
+/**
+ * Deterministic aggregation over a job's per-target audit results.
+ *
+ * Every number that shows up in a report flows through here — never through
+ * an LLM. The narration layer can describe / contextualize / dramatize, but
+ * counts, scores, deltas, and rankings are all computed here. Same pattern
+ * we use for the audit patches contract: agent narrates, code computes.
+ */
+import * as fs from 'node:fs';
+/**
+ * Read each ok result's `report.json` from disk and project to AggregateRow.
+ * Skipped/failed entries become rows with `rollupScore: NaN` so callers can
+ * filter them — keeping them in the list preserves index alignment with
+ * `job.results` for tools that want to drill in.
+ */
+export function aggregateJob(job) {
+    const out = [];
+    for (const r of job.results) {
+        out.push(toRow(r));
+    }
+    return out;
+}
+function toRow(r) {
+    const base = {
+        url: r.url,
+        snapshotUrl: r.snapshotUrl,
+        capturedAt: r.capturedAt,
+        runId: r.runId ?? '',
+        rollupScore: typeof r.rollupScore === 'number' ? r.rollupScore : NaN,
+        dimensions: {},
+        ethicsViolations: 0,
+        resultPath: r.resultPath,
+        pageType: r.pageType,
+    };
+    if (r.status !== 'ok' || !r.resultPath || !fs.existsSync(r.resultPath)) {
+        return base;
+    }
+    try {
+        const json = JSON.parse(fs.readFileSync(r.resultPath, 'utf-8'));
+        const page = json.pages?.[0];
+        if (!page)
+            return base;
+        const v2 = page.auditResultV2;
+        const cls = v2?.classification ?? page.classification ?? {};
+        base.pageType = base.pageType ?? cls.type;
+        base.domain = cls.domain;
+        if (v2?.rollup?.score !== undefined)
+            base.rollupScore = v2.rollup.score;
+        else if (page.rollup?.score !== undefined)
+            base.rollupScore = page.rollup.score;
+        else if (typeof page.score === 'number')
+            base.rollupScore = page.score;
+        if (v2?.scores) {
+            for (const [dim, ds] of Object.entries(v2.scores)) {
+                if (ds && typeof ds.score === 'number')
+                    base.dimensions[dim] = ds.score;
+            }
+        }
+        base.ethicsViolations = Array.isArray(page.ethicsViolations) ? page.ethicsViolations.length : 0;
+    }
+    catch {
+        // Corrupt or partial report.json — leave as-is. Don't pretend we have data we don't.
+    }
+    return base;
+}
+export function leaderboard(rows, opts = {}) {
+    const dir = opts.direction ?? 'desc';
+    const filtered = rows
+        .filter(r => Number.isFinite(r.rollupScore))
+        .filter(r => !opts.byType || r.pageType === opts.byType);
+    filtered.sort((a, b) => (dir === 'desc' ? b.rollupScore - a.rollupScore : a.rollupScore - b.rollupScore));
+    if (opts.topN && opts.topN > 0)
+        return filtered.slice(0, opts.topN);
+    return filtered;
+}
+/** Longitudinal view: all snapshots for one URL, sorted by capture time. */
+export function longitudinalFor(rows, url) {
+    return rows
+        .filter(r => r.url === url && r.capturedAt && Number.isFinite(r.rollupScore))
+        .map(r => ({
+        url: r.url,
+        capturedAt: r.capturedAt,
+        rollupScore: r.rollupScore,
+        pageType: r.pageType,
+    }))
+        .sort((a, b) => a.capturedAt.localeCompare(b.capturedAt));
+}
+export function compareRuns(a, b) {
+    const dims = new Set([
+        ...Object.keys(a.dimensions),
+        ...Object.keys(b.dimensions),
+    ]);
+    const perDimension = [];
+    for (const dim of dims) {
+        const ax = a.dimensions[dim];
+        const bx = b.dimensions[dim];
+        if (typeof ax !== 'number' || typeof bx !== 'number')
+            continue;
+        perDimension.push({ dim, beforeScore: bx, afterScore: ax, delta: round2(ax - bx) });
+    }
+    return {
+        a,
+        b,
+        rollupDelta: round2(a.rollupScore - b.rollupScore),
+        perDimension,
+    };
+}
+export function tierBuckets(rows, boundaries) {
+    const ranked = leaderboard(rows);
+    const buckets = [];
+    const sorted = [...new Set(boundaries)].sort((a, b) => a - b);
+    let prev = 0;
+    for (const upper of sorted) {
+        const slice = ranked.slice(prev, upper);
+        if (slice.length === 0) {
+            prev = upper;
+            continue;
+        }
+        const label = prev === 0 ? `top ${upper}` : `${prev + 1}–${upper}`;
+        buckets.push({ label, rows: slice, ...stats(slice) });
+        prev = upper;
+    }
+    if (prev < ranked.length) {
+        const slice = ranked.slice(prev);
+        buckets.push({ label: `${prev + 1}+`, rows: slice, ...stats(slice) });
+    }
+    return buckets;
+}
+function stats(rows) {
+    if (rows.length === 0)
+        return { meanScore: NaN, medianScore: NaN };
+    const scores = rows.map(r => r.rollupScore).filter(Number.isFinite);
+    const sum = scores.reduce((a, b) => a + b, 0);
+    const sorted = [...scores].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    const median = sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+    return {
+        meanScore: round2(sum / scores.length),
+        medianScore: round2(median),
+    };
+}
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+//# sourceMappingURL=aggregate.js.map

package/dist/reports/aggregate.js.map

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

package/dist/reports/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Reports — turn a job's audit results into shareable artifacts.
+ *
+ * Two surfaces:
+ *   1. Static templates (deterministic markdown rendering — see templates.ts)
+ *   2. AI SDK tools (agentic chat over the same data — see tools.ts)
+ *
+ * Both flow through the same aggregate.ts functions, so numbers are consistent.
+ */
+export type { AggregateRow, CompareRunsResult, DimensionDelta, LongitudinalRow, ReportTemplate } from './types.js';
+export { aggregateJob, leaderboard, longitudinalFor, compareRuns, tierBuckets } from './aggregate.js';
+export type { LeaderboardOptions, TierBucket } from './aggregate.js';
+export { renderLeaderboard, renderLongitudinal, renderBatchComparison, renderBrandEvolution, renderJobHeader, } from './templates.js';
+export type { LeaderboardRenderOpts, LongitudinalRenderOpts, BatchComparisonRenderOpts, BrandEvolutionRenderOpts, } from './templates.js';
+export { aggregateTokens, diffTokens, groupByUrl } from './tokens.js';
+export type { TokenSummary, TokenDiff, TokenSeries } from './tokens.js';
+export { buildReportTools } from './tools.js';
+export type { ReportToolsContext, ReportToolSet } from './tools.js';
+export { narrateReport } from './narrate.js';
+export type { NarrateOptions } from './narrate.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/reports/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/reports/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAClH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACrG,YAAY,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AACpE,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,GAChB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACrE,YAAY,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAC7C,YAAY,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA"}

package/dist/reports/index.js

@@ -0,0 +1,15 @@
+/**
+ * Reports — turn a job's audit results into shareable artifacts.
+ *
+ * Two surfaces:
+ *   1. Static templates (deterministic markdown rendering — see templates.ts)
+ *   2. AI SDK tools (agentic chat over the same data — see tools.ts)
+ *
+ * Both flow through the same aggregate.ts functions, so numbers are consistent.
+ */
+export { aggregateJob, leaderboard, longitudinalFor, compareRuns, tierBuckets } from './aggregate.js';
+export { renderLeaderboard, renderLongitudinal, renderBatchComparison, renderBrandEvolution, renderJobHeader, } from './templates.js';
+export { aggregateTokens, diffTokens, groupByUrl } from './tokens.js';
+export { buildReportTools } from './tools.js';
+export { narrateReport } from './narrate.js';
+//# sourceMappingURL=index.js.map

package/dist/reports/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/reports/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAErG,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,GAChB,MAAM,gBAAgB,CAAA;AAOvB,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAErE,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAE7C,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA"}

package/dist/reports/narrate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * LLM narration around deterministic data.
+ *
+ * The contract: numbers come from the templates (which call the aggregate
+ * functions). The LLM only writes prose context — top-line takeaways, an
+ * angle on what's surprising. Same pattern as the patches contract.
+ *
+ * If a Brain isn't supplied, the deterministic markdown is returned as-is.
+ * That's the safe default — never silently fabricate prose.
+ */
+import type { Brain } from '../brain/index.js';
+export interface NarrateOptions {
+    /** When supplied, prepends an LLM-written executive summary above the deterministic body. */
+    brain?: Brain;
+    /** Free-form context passed to the LLM (e.g. "this is the YC W25 cohort"). */
+    context?: string;
+}
+export declare function narrateReport(deterministicMarkdown: string, opts?: NarrateOptions): Promise<string>;
+//# sourceMappingURL=narrate.d.ts.map

package/dist/reports/narrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"narrate.d.ts","sourceRoot":"","sources":["../../src/reports/narrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAA;AAU9C,MAAM,WAAW,cAAc;IAC7B,6FAA6F;IAC7F,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,wBAAsB,aAAa,CAAC,qBAAqB,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAkB7G"}

package/dist/reports/narrate.js

@@ -0,0 +1,40 @@
+/**
+ * LLM narration around deterministic data.
+ *
+ * The contract: numbers come from the templates (which call the aggregate
+ * functions). The LLM only writes prose context — top-line takeaways, an
+ * angle on what's surprising. Same pattern as the patches contract.
+ *
+ * If a Brain isn't supplied, the deterministic markdown is returned as-is.
+ * That's the safe default — never silently fabricate prose.
+ */
+const SYSTEM = `You are an analyst writing a one-paragraph executive summary at the top of a design-audit report.
+
+Rules:
+- Use ONLY the numbers and facts in the provided markdown report. Do not invent rankings, scores, or claims.
+- Surface the most surprising or load-bearing finding (e.g. a tier-vs-tier gap, a dramatic longitudinal swing, an outlier).
+- Two to four sentences. No bullet lists.
+- Do not preface with "Here is your summary" or similar.`;
+export async function narrateReport(deterministicMarkdown, opts = {}) {
+    if (!opts.brain)
+        return deterministicMarkdown;
+    const user = [
+        opts.context ? `Context: ${opts.context}` : undefined,
+        'REPORT:',
+        deterministicMarkdown,
+        '',
+        'Write the executive summary now.',
+    ].filter(Boolean).join('\n\n');
+    try {
+        const { text } = await opts.brain.complete(SYSTEM, user, { maxOutputTokens: 320 });
+        const summary = text.trim();
+        if (!summary)
+            return deterministicMarkdown;
+        return `## Executive summary\n\n${summary}\n\n${deterministicMarkdown}`;
+    }
+    catch {
+        // Don't let narration failures block the artifact. Ship the data.
+        return deterministicMarkdown;
+    }
+}
+//# sourceMappingURL=narrate.js.map

package/dist/reports/narrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"narrate.js","sourceRoot":"","sources":["../../src/reports/narrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,MAAM,GAAG;;;;;;yDAM0C,CAAA;AASzD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,qBAA6B,EAAE,OAAuB,EAAE;IAC1F,IAAI,CAAC,IAAI,CAAC,KAAK;QAAE,OAAO,qBAAqB,CAAA;IAC7C,MAAM,IAAI,GAAG;QACX,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS;QACrD,SAAS;QACT,qBAAqB;QACrB,EAAE;QACF,kCAAkC;KACnC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC9B,IAAI,CAAC;QACH,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,EAAE,eAAe,EAAE,GAAG,EAAE,CAAC,CAAA;QAClF,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;QAC3B,IAAI,CAAC,OAAO;YAAE,OAAO,qBAAqB,CAAA;QAC1C,OAAO,2BAA2B,OAAO,OAAO,qBAAqB,EAAE,CAAA;IACzE,CAAC;IAAC,MAAM,CAAC;QACP,kEAAkE;QAClE,OAAO,qBAAqB,CAAA;IAC9B,CAAC;AACH,CAAC"}

package/dist/reports/templates.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Static report templates — markdown rendering of pre-aggregated data.
+ *
+ * No LLM. The narration layer (narrate.ts) wraps these with prose; the
+ * templates themselves are pure functions of data so they're snapshot-testable
+ * and deterministic.
+ */
+import type { Job } from '../jobs/types.js';
+import type { AggregateRow } from './types.js';
+export interface LeaderboardRenderOpts {
+    title?: string;
+    topN?: number;
+    byType?: string;
+    /** Tier bucket boundaries — e.g. [10, 100, 200] → "top 10", "11–100", "101–200", "201+". */
+    buckets?: number[];
+}
+export declare function renderLeaderboard(rows: AggregateRow[], opts?: LeaderboardRenderOpts): string;
+export interface LongitudinalRenderOpts {
+    title?: string;
+    /** If multiple URLs are in scope, render one section per URL. */
+    urls?: string[];
+}
+export declare function renderLongitudinal(rows: AggregateRow[], opts?: LongitudinalRenderOpts): string;
+export interface BatchComparisonRenderOpts {
+    title?: string;
+    /** Pairs of (a, b) URLs to diff. If omitted, the first two URLs encountered are paired. */
+    pairs?: Array<[string, string]>;
+}
+export declare function renderBatchComparison(rows: AggregateRow[], opts?: BatchComparisonRenderOpts): string;
+export interface BrandEvolutionRenderOpts {
+    title?: string;
+    /** Max colors to render per snapshot (top by usage count). Default 6. */
+    topColors?: number;
+}
+/**
+ * Render a per-URL brand-kit evolution: for each URL, list the snapshots in
+ * chronological order with their distinct color palette, font families, and
+ * detected libraries. Between consecutive snapshots, surface the delta
+ * (colors added/removed, families added/removed, brand-meta changes).
+ */
+export declare function renderBrandEvolution(job: Job, opts?: BrandEvolutionRenderOpts): string;
+export declare function renderJobHeader(job: Job): string;
+//# sourceMappingURL=templates.d.ts.map

package/dist/reports/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/reports/templates.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAmB,MAAM,YAAY,CAAA;AAI/D,MAAM,WAAW,qBAAqB;IACpC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,IAAI,GAAE,qBAA0B,GAAG,MAAM,CAwChG;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,IAAI,GAAE,sBAA2B,GAAG,MAAM,CA6BlG;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,2FAA2F;IAC3F,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAChC;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,IAAI,GAAE,yBAA8B,GAAG,MAAM,CA+BxG;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,GAAE,wBAA6B,GAAG,MAAM,CAqD1F;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAWhD"}