my-frontend-observer 0.1.0

package/dist/browser/evidenceCapture.js

@@ -0,0 +1,201 @@
+import { DIAGNOSTIC_SEVERITY } from '../domain/diagnostics.js';
+function diagnostic(code, message, targetName) {
+    const base = { code, severity: DIAGNOSTIC_SEVERITY[code], message };
+    return targetName === undefined ? base : { ...base, targetName };
+}
+function browserField(value) {
+    return { state: 'available', source: 'browser', value };
+}
+function derivedField(value, derivedFrom) {
+    return { state: 'available', source: 'derived', value, derivedFrom };
+}
+function computedField(value) {
+    return { state: 'available', source: 'computed-browser', value };
+}
+function unavailableField(reason) {
+    return { state: 'unavailable', reason };
+}
+/**
+ * Captures the v0.1 minimum page evidence (docs/PROJECT_MILESTONES.md
+ * "Minimum page evidence") from the already-navigated, already-ready page.
+ * `documentWidth`/`documentHeight` are the one explicitly *derived* pair -
+ * max(scroll, client) in each axis - everything else is a direct browser
+ * read, per the Batch 1 evidence-source model.
+ */
+export async function capturePageEvidence(page, requestedUrl, viewport) {
+    const raw = await page.evaluate(() => ({
+        title: document.title,
+        windowScrollX: window.scrollX,
+        windowScrollY: window.scrollY,
+        documentScrollWidth: document.documentElement.scrollWidth,
+        documentScrollHeight: document.documentElement.scrollHeight,
+        documentClientWidth: document.documentElement.clientWidth,
+        documentClientHeight: document.documentElement.clientHeight,
+    }));
+    const documentWidth = Math.max(raw.documentScrollWidth, raw.documentClientWidth);
+    const documentHeight = Math.max(raw.documentScrollHeight, raw.documentClientHeight);
+    return {
+        requestedUrl: browserField(requestedUrl),
+        finalUrl: browserField(page.url()),
+        title: browserField(raw.title),
+        viewportWidth: browserField(viewport.width),
+        viewportHeight: browserField(viewport.height),
+        devicePixelRatio: browserField(await page.evaluate(() => window.devicePixelRatio)),
+        documentScrollWidth: browserField(raw.documentScrollWidth),
+        documentScrollHeight: browserField(raw.documentScrollHeight),
+        documentClientWidth: browserField(raw.documentClientWidth),
+        documentClientHeight: browserField(raw.documentClientHeight),
+        documentWidth: derivedField(documentWidth, ['documentScrollWidth', 'documentClientWidth']),
+        documentHeight: derivedField(documentHeight, ['documentScrollHeight', 'documentClientHeight']),
+        windowScrollX: browserField(raw.windowScrollX),
+        windowScrollY: browserField(raw.windowScrollY),
+    };
+}
+/**
+ * Extracts only the target element's own role/name from a Playwright
+ * `ariaSnapshot()` string (e.g. `- button "Click me"`), never its
+ * descendants - bounded, target-local semantic evidence, not an
+ * accessibility-tree dump. A generic `- text: ...` line (no distinct ARIA
+ * role) or an empty snapshot both mean "no reliable role/name", not a role
+ * of "text".
+ */
+function parseAriaSnapshotFirstLine(snapshot) {
+    const firstLine = snapshot.split('\n')[0]?.trim();
+    if (!firstLine)
+        return undefined;
+    const match = /^-\s+([A-Za-z][\w-]*)\s*(?:"([^"]*)")?:?$/.exec(firstLine);
+    if (!match)
+        return undefined;
+    const role = match[1];
+    const name = match[2];
+    if (role === undefined || role === 'text')
+        return undefined;
+    return name !== undefined && name.length > 0 ? { role, name } : { role };
+}
+function missingTargetRecord() {
+    const reason = 'target selector matched no element';
+    return {
+        resolution: { state: 'available', source: 'derived', value: { selectionMethod: 'css-selector', selectionStatus: 'not-found' }, derivedFrom: ['selector-query'] },
+        tag: unavailableField(reason),
+        geometry: unavailableField(reason),
+        style: unavailableField(reason),
+        layout: unavailableField(reason),
+        visibility: unavailableField(reason),
+        semantics: unavailableField(reason),
+    };
+}
+function ambiguousTargetRecord(matchCount) {
+    const reason = `target selector matched ${matchCount} elements; expected exactly one`;
+    return {
+        resolution: { state: 'available', source: 'derived', value: { selectionMethod: 'css-selector', selectionStatus: 'ambiguous' }, derivedFrom: ['selector-query'] },
+        tag: unavailableField(reason),
+        geometry: unavailableField(reason),
+        style: unavailableField(reason),
+        layout: unavailableField(reason),
+        visibility: unavailableField(reason),
+        semantics: unavailableField(reason),
+    };
+}
+/**
+ * Captures the v0.1 minimum target evidence for one resolved (single-match)
+ * target element, from the same live page/readiness state as the page
+ * evidence and screenshot. Role/name come from Playwright's real
+ * accessibility tree (`page.accessibility.snapshot`), not a hand-rolled
+ * approximation; when the browser cannot supply them reliably for this
+ * element, they are reported `unavailable` rather than guessed.
+ */
+async function captureResolvedTargetRecord(page, selector) {
+    const handle = await page.$(selector);
+    if (!handle)
+        return missingTargetRecord();
+    try {
+        const raw = await handle.evaluate((el) => {
+            const rect = el.getBoundingClientRect();
+            const computed = getComputedStyle(el);
+            return {
+                tag: el.tagName.toLowerCase(),
+                geometry: { x: rect.x, y: rect.y, width: rect.width, height: rect.height, right: rect.right, bottom: rect.bottom },
+                style: { display: computed.display, position: computed.position, overflowX: computed.overflowX, overflowY: computed.overflowY },
+                layout: {
+                    scrollWidth: el.scrollWidth,
+                    scrollHeight: el.scrollHeight,
+                    clientWidth: el.clientWidth,
+                    clientHeight: el.clientHeight,
+                    scrollTop: el.scrollTop,
+                    scrollLeft: el.scrollLeft,
+                },
+                computedVisibility: computed.visibility,
+            };
+        });
+        const visible = raw.style.display !== 'none' && raw.computedVisibility !== 'hidden' && raw.geometry.width > 0 && raw.geometry.height > 0;
+        let semantics;
+        try {
+            const snapshot = await page.locator(selector).ariaSnapshot();
+            const parsed = parseAriaSnapshotFirstLine(snapshot);
+            semantics = parsed ? computedField(parsed) : unavailableField('no distinct accessible role/name is exposed for this target');
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            semantics = unavailableField(`accessibility snapshot failed: ${message}`);
+        }
+        return {
+            resolution: {
+                state: 'available',
+                source: 'derived',
+                value: { selectionMethod: 'css-selector', selectionStatus: 'matched' },
+                derivedFrom: ['selector-query'],
+            },
+            tag: browserField(raw.tag),
+            geometry: browserField(raw.geometry),
+            style: computedField(raw.style),
+            layout: browserField(raw.layout),
+            visibility: derivedField({ visible }, ['style.display', 'computed-visibility', 'geometry.width', 'geometry.height']),
+            semantics,
+        };
+    }
+    finally {
+        await handle.dispose();
+    }
+}
+/** Observes every explicitly configured Batch 1 target from the same live page, honoring the 0/1/many cardinality contract. */
+export async function captureTargetEvidence(page, targets) {
+    const targetEvidence = {};
+    const diagnostics = [];
+    for (const target of targets) {
+        const matchCount = await page.evaluate((selector) => document.querySelectorAll(selector).length, target.selector);
+        if (matchCount === 0) {
+            targetEvidence[target.name] = missingTargetRecord();
+            diagnostics.push(diagnostic('target-missing', `no element matched selector for target "${target.name}"`, target.name));
+            continue;
+        }
+        if (matchCount > 1) {
+            targetEvidence[target.name] = ambiguousTargetRecord(matchCount);
+            diagnostics.push(diagnostic('target-ambiguous', `${matchCount} elements matched selector for target "${target.name}"`, target.name));
+            continue;
+        }
+        try {
+            targetEvidence[target.name] = await captureResolvedTargetRecord(page, target.selector);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            const reason = `target evaluation failed: ${message}`;
+            targetEvidence[target.name] = {
+                resolution: {
+                    state: 'available',
+                    source: 'derived',
+                    value: { selectionMethod: 'css-selector', selectionStatus: 'matched' },
+                    derivedFrom: ['selector-query'],
+                },
+                tag: unavailableField(reason),
+                geometry: unavailableField(reason),
+                style: unavailableField(reason),
+                layout: unavailableField(reason),
+                visibility: unavailableField(reason),
+                semantics: unavailableField(reason),
+            };
+            diagnostics.push(diagnostic('browser-evidence-unavailable', reason, target.name));
+        }
+    }
+    return { targetEvidence, diagnostics };
+}
+//# sourceMappingURL=evidenceCapture.js.map

package/dist/browser/evidenceCapture.js.map

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

package/dist/browser/types.d.ts

@@ -0,0 +1,22 @@
+import type { Diagnostic } from '../domain/diagnostics.js';
+import type { EvidenceField } from '../domain/evidence.js';
+import type { TargetEvidenceRecord } from '../domain/schema.js';
+export interface BrowserProvenance {
+    engine: string;
+    version: string;
+}
+/**
+ * Observer-owned result of the browser boundary. Contains no Playwright
+ * object anywhere in its shape - only plain, serializable data.
+ */
+export type BrowserCaptureResult = {
+    ok: true;
+    provenance: BrowserProvenance;
+    screenshot: Uint8Array;
+    pageEvidence: Record<string, EvidenceField<unknown>>;
+    targetEvidence: Record<string, TargetEvidenceRecord>;
+    diagnostics: Diagnostic[];
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};

package/dist/browser/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/browser/types.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+export interface CliIO {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+}
+/** Testable CLI entry point: pure function of argv (+ injectable IO), no direct process.exit. */
+export declare function runCli(argv: readonly string[], io?: CliIO): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { normalizeRequest } from './request/request.js';
+import { getProducerInfo } from './domain/schema.js';
+import { observe } from './application/observationPersistence.js';
+const defaultIO = {
+    stdout: (text) => {
+        process.stdout.write(text);
+    },
+    stderr: (text) => {
+        process.stderr.write(text);
+    },
+};
+const TOP_LEVEL_HELP = `my-frontend-observer - local-first browser runtime evidence producer
+
+Usage:
+  my-frontend-observer <command> [options]
+
+Commands:
+  observe    Capture one bounded browser observation and persist it as a
+             portable artifact.
+
+Options:
+  --help     Show this help.
+  --version  Print the package version.
+
+Run "my-frontend-observer observe --help" for observe command options.
+`;
+const OBSERVE_HELP = `Usage:
+  my-frontend-observer observe --url <loopback-url> [options]
+
+Required:
+  --url <url>              Loopback target URL (http/https, localhost/127.x.x.x/::1 only).
+
+Options:
+  --viewport <WIDTHxHEIGHT> Viewport size, e.g. 1280x720.
+  --target <id=selector>    An explicit observation target. Repeatable.
+                            Parsed on the first "=" only, so selectors
+                            containing "=" (e.g. button[data-state="active"])
+                            are preserved intact.
+  --output <directory>      Portable, relative output location for the
+                            observation artifact.
+  --timeout <ms>            Overall request timeout in milliseconds.
+  --help                    Show this help.
+
+On success, prints a concise result and exits 0. On invalid syntax, invalid
+request, unsafe/failed navigation, or a failed artifact write, prints
+structured diagnostics to stderr and exits nonzero. No progress output is
+printed during a normal capture.
+`;
+function parseViewport(raw) {
+    const match = /^(\d+)x(\d+)$/.exec(raw);
+    if (!match)
+        return undefined;
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    return { width, height };
+}
+function parseTarget(raw) {
+    const eq = raw.indexOf('=');
+    if (eq <= 0 || eq === raw.length - 1)
+        return undefined;
+    return { name: raw.slice(0, eq), selector: raw.slice(eq + 1) };
+}
+/** CLI-syntax-only parsing: shape/format errors only. Domain bounds and policy are Batch 1's job, not this function's. */
+function parseObserveArgs(argv) {
+    const errors = [];
+    let targetUrl;
+    let viewport;
+    const targets = [];
+    let outputLocation;
+    let timeoutMs;
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--url':
+                targetUrl = argv[(i += 1)];
+                break;
+            case '--viewport': {
+                const value = argv[(i += 1)];
+                const parsed = value === undefined ? undefined : parseViewport(value);
+                if (parsed === undefined) {
+                    errors.push(`--viewport must be WIDTHxHEIGHT (e.g. 1280x720); got ${JSON.stringify(value)}`);
+                }
+                else {
+                    viewport = parsed;
+                }
+                break;
+            }
+            case '--target': {
+                const value = argv[(i += 1)];
+                const parsed = value === undefined ? undefined : parseTarget(value);
+                if (parsed === undefined) {
+                    errors.push(`--target must be id=css-selector; got ${JSON.stringify(value)}`);
+                }
+                else {
+                    targets.push(parsed);
+                }
+                break;
+            }
+            case '--output':
+                outputLocation = argv[(i += 1)];
+                break;
+            case '--timeout': {
+                const value = argv[(i += 1)];
+                const parsedNumber = value === undefined ? NaN : Number(value);
+                if (!Number.isFinite(parsedNumber)) {
+                    errors.push(`--timeout must be a number of milliseconds; got ${JSON.stringify(value)}`);
+                }
+                else {
+                    timeoutMs = parsedNumber;
+                }
+                break;
+            }
+            default:
+                errors.push(`unrecognized argument: ${arg}`);
+        }
+    }
+    if (targetUrl === undefined)
+        errors.push('--url is required');
+    if (errors.length > 0)
+        return { ok: false, errors };
+    const raw = {
+        targetUrl,
+        ...(viewport === undefined ? {} : { viewport }),
+        ...(targets.length > 0 ? { targets } : {}),
+        ...(outputLocation === undefined ? {} : { outputLocation }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    };
+    return { ok: true, raw };
+}
+function formatDiagnostic(diagnostic) {
+    const target = diagnostic.targetName === undefined ? '' : ` (target: ${diagnostic.targetName})`;
+    return `[${diagnostic.code}] ${diagnostic.message}${target}`;
+}
+/** Completion states that must never be reported as a successful process exit, even though they may still have a persisted artifact. */
+const NON_SUCCESS_COMPLETION_STATES = new Set(['fatal', 'invalid-request']);
+async function runObserveCommand(argv, io) {
+    if (argv.includes('--help')) {
+        io.stdout(OBSERVE_HELP);
+        return 0;
+    }
+    const parsedArgs = parseObserveArgs(argv);
+    if (!parsedArgs.ok) {
+        for (const error of parsedArgs.errors)
+            io.stderr(`error: ${error}\n`);
+        io.stderr(OBSERVE_HELP);
+        return 1;
+    }
+    const normalized = normalizeRequest(parsedArgs.raw);
+    if (!normalized.ok) {
+        for (const diagnostic of normalized.diagnostics)
+            io.stderr(`${formatDiagnostic(diagnostic)}\n`);
+        return 1;
+    }
+    // Exactly one application observation attempt: one browser capture, persisted at most once.
+    const result = await observe(normalized.request);
+    if (!result.ok) {
+        for (const diagnostic of result.diagnostics)
+            io.stderr(`${formatDiagnostic(diagnostic)}\n`);
+        return 1;
+    }
+    io.stdout(`Observation: ${result.observationId}\n`);
+    io.stdout(`State: ${result.completion.state}\n`);
+    io.stdout(`Artifact: ${result.artifactRoot}\n`);
+    io.stdout(`Targets: ${result.targetCount}\n`);
+    io.stdout(`Diagnostics: ${result.diagnostics.length}\n`);
+    return NON_SUCCESS_COMPLETION_STATES.has(result.completion.state) ? 1 : 0;
+}
+/** Testable CLI entry point: pure function of argv (+ injectable IO), no direct process.exit. */
+export async function runCli(argv, io = defaultIO) {
+    const [command, ...rest] = argv;
+    if (command === undefined) {
+        io.stderr(TOP_LEVEL_HELP);
+        return 1;
+    }
+    if (command === '--help' || command === '-h') {
+        io.stdout(TOP_LEVEL_HELP);
+        return 0;
+    }
+    if (command === '--version') {
+        io.stdout(`${getProducerInfo().version}\n`);
+        return 0;
+    }
+    if (command === 'observe') {
+        return runObserveCommand(rest, io);
+    }
+    io.stderr(`error: unrecognized command "${command}"\n`);
+    io.stderr(TOP_LEVEL_HELP);
+    return 1;
+}
+/**
+ * Resolves symlinks on both sides before comparing paths, not just a raw URL string
+ * comparison: on macOS, `os.tmpdir()` (and other paths) live under `/var`, which is
+ * itself a symlink to `/private/var`. A plain `import.meta.url === pathToFileURL(...)`
+ * comparison silently evaluates false in that case (mismatched but equivalent paths),
+ * so the CLI's own entry point never runs - `node dist/cli.js ...` exits 0 having
+ * printed nothing. Real-pathing both sides makes the comparison symlink-safe.
+ */
+function isMainModule() {
+    if (process.argv[1] === undefined)
+        return false;
+    try {
+        return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule()) {
+    runCli(process.argv.slice(2)).then((exitCode) => {
+        process.exitCode = exitCode;
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/domain/completion.d.ts

@@ -0,0 +1,30 @@
+import type { Diagnostic } from './diagnostics.js';
+/**
+ * The "warning" variant is reserved for a future non-blocking diagnostic
+ * class; no DiagnosticCode frozen in v0.1 Batch 1 maps to it (see
+ * deriveCompletion below - every warning-severity diagnostic produces
+ * "partial", never "warning").
+ */
+export type CompletionState = {
+    state: 'complete';
+} | {
+    state: 'partial';
+    diagnostics: Diagnostic[];
+} | {
+    state: 'warning';
+    diagnostics: Diagnostic[];
+} | {
+    state: 'invalid-request';
+    diagnostics: Diagnostic[];
+} | {
+    state: 'fatal';
+    diagnostics: Diagnostic[];
+};
+export type RequestPhase = 'pre-capture' | 'post-capture';
+/**
+ * pre-capture + any diagnostic -> invalid-request (capture never attempted).
+ * post-capture + any error-severity diagnostic -> fatal.
+ * post-capture + only warning-severity diagnostics -> partial (never silently complete).
+ * no diagnostics, either phase -> complete.
+ */
+export declare function deriveCompletion(diagnostics: readonly Diagnostic[], requestPhase: RequestPhase): CompletionState;

package/dist/domain/completion.js

@@ -0,0 +1,22 @@
+import { orderDiagnostics } from './diagnostics.js';
+/**
+ * pre-capture + any diagnostic -> invalid-request (capture never attempted).
+ * post-capture + any error-severity diagnostic -> fatal.
+ * post-capture + only warning-severity diagnostics -> partial (never silently complete).
+ * no diagnostics, either phase -> complete.
+ */
+export function deriveCompletion(diagnostics, requestPhase) {
+    const ordered = orderDiagnostics(diagnostics);
+    if (ordered.length === 0) {
+        return { state: 'complete' };
+    }
+    if (requestPhase === 'pre-capture') {
+        return { state: 'invalid-request', diagnostics: ordered };
+    }
+    const hasError = ordered.some((diagnostic) => diagnostic.severity === 'error');
+    if (hasError) {
+        return { state: 'fatal', diagnostics: ordered };
+    }
+    return { state: 'partial', diagnostics: ordered };
+}
+//# sourceMappingURL=completion.js.map

package/dist/domain/completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion.js","sourceRoot":"","sources":["../../src/domain/completion.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAiBpD;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAkC,EAAE,YAA0B;IAC7F,MAAM,OAAO,GAAG,gBAAgB,CAAC,WAAW,CAAC,CAAC;IAC9C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC;IAC/B,CAAC;IACD,IAAI,YAAY,KAAK,aAAa,EAAE,CAAC;QACnC,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;IAC5D,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IAC/E,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;IAClD,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AACpD,CAAC"}

package/dist/domain/diagnostics.d.ts

@@ -0,0 +1,17 @@
+export declare const DIAGNOSTIC_CODES: readonly ["invalid-request", "unsupported-configuration", "unsafe-url", "prohibited-navigation", "prohibited-redirect", "prohibited-subresource-request", "readiness-timeout", "navigation-failure", "target-missing", "target-ambiguous", "browser-evidence-unavailable", "partial-evidence", "bounded-truncated-evidence", "artifact-write-failure", "browser-runtime-failure"];
+export type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
+export type DiagnosticSeverity = 'error' | 'warning';
+/** Single source of truth for code->severity; ordering/completion logic must consult this, never a duplicated mapping. */
+export declare const DIAGNOSTIC_SEVERITY: Record<DiagnosticCode, DiagnosticSeverity>;
+export interface Diagnostic {
+    code: DiagnosticCode;
+    severity: DiagnosticSeverity;
+    message: string;
+    targetName?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Deterministic ordering: error before warning, then code, then targetName
+ * (absent-first). Pure - returns a new array, never mutates the input.
+ */
+export declare function orderDiagnostics(diagnostics: readonly Diagnostic[]): Diagnostic[];

package/dist/domain/diagnostics.js

@@ -0,0 +1,55 @@
+export const DIAGNOSTIC_CODES = [
+    'invalid-request',
+    'unsupported-configuration',
+    'unsafe-url',
+    'prohibited-navigation',
+    'prohibited-redirect',
+    'prohibited-subresource-request',
+    'readiness-timeout',
+    'navigation-failure',
+    'target-missing',
+    'target-ambiguous',
+    'browser-evidence-unavailable',
+    'partial-evidence',
+    'bounded-truncated-evidence',
+    'artifact-write-failure',
+    'browser-runtime-failure',
+];
+/** Single source of truth for code->severity; ordering/completion logic must consult this, never a duplicated mapping. */
+export const DIAGNOSTIC_SEVERITY = {
+    'invalid-request': 'error',
+    'unsupported-configuration': 'error',
+    'unsafe-url': 'error',
+    'prohibited-navigation': 'error',
+    'prohibited-redirect': 'error',
+    'prohibited-subresource-request': 'error',
+    'readiness-timeout': 'warning',
+    'navigation-failure': 'error',
+    'target-missing': 'warning',
+    'target-ambiguous': 'warning',
+    'browser-evidence-unavailable': 'warning',
+    'partial-evidence': 'warning',
+    'bounded-truncated-evidence': 'warning',
+    'artifact-write-failure': 'error',
+    'browser-runtime-failure': 'error',
+};
+/**
+ * Deterministic ordering: error before warning, then code, then targetName
+ * (absent-first). Pure - returns a new array, never mutates the input.
+ */
+export function orderDiagnostics(diagnostics) {
+    const severityRank = (d) => (d.severity === 'error' ? 0 : 1);
+    return [...diagnostics].sort((a, b) => {
+        const rankDiff = severityRank(a) - severityRank(b);
+        if (rankDiff !== 0)
+            return rankDiff;
+        if (a.code !== b.code)
+            return a.code < b.code ? -1 : 1;
+        const targetA = a.targetName ?? '';
+        const targetB = b.targetName ?? '';
+        if (targetA !== targetB)
+            return targetA < targetB ? -1 : 1;
+        return 0;
+    });
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/domain/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/domain/diagnostics.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,iBAAiB;IACjB,2BAA2B;IAC3B,YAAY;IACZ,uBAAuB;IACvB,qBAAqB;IACrB,gCAAgC;IAChC,mBAAmB;IACnB,oBAAoB;IACpB,gBAAgB;IAChB,kBAAkB;IAClB,8BAA8B;IAC9B,kBAAkB;IAClB,4BAA4B;IAC5B,wBAAwB;IACxB,yBAAyB;CACjB,CAAC;AAMX,0HAA0H;AAC1H,MAAM,CAAC,MAAM,mBAAmB,GAA+C;IAC7E,iBAAiB,EAAE,OAAO;IAC1B,2BAA2B,EAAE,OAAO;IACpC,YAAY,EAAE,OAAO;IACrB,uBAAuB,EAAE,OAAO;IAChC,qBAAqB,EAAE,OAAO;IAC9B,gCAAgC,EAAE,OAAO;IACzC,mBAAmB,EAAE,SAAS;IAC9B,oBAAoB,EAAE,OAAO;IAC7B,gBAAgB,EAAE,SAAS;IAC3B,kBAAkB,EAAE,SAAS;IAC7B,8BAA8B,EAAE,SAAS;IACzC,kBAAkB,EAAE,SAAS;IAC7B,4BAA4B,EAAE,SAAS;IACvC,wBAAwB,EAAE,OAAO;IACjC,yBAAyB,EAAE,OAAO;CACnC,CAAC;AAUF;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAkC;IACjE,MAAM,YAAY,GAAG,CAAC,CAAa,EAAU,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjF,OAAO,CAAC,GAAG,WAAW,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACpC,MAAM,QAAQ,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QACnD,IAAI,QAAQ,KAAK,CAAC;YAAE,OAAO,QAAQ,CAAC;QACpC,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI;YAAE,OAAO,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvD,MAAM,OAAO,GAAG,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,CAAC,CAAC,UAAU,IAAI,EAAE,CAAC;QACnC,IAAI,OAAO,KAAK,OAAO;YAAE,OAAO,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,OAAO,CAAC,CAAC;IACX,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/domain/evidence.d.ts

@@ -0,0 +1,27 @@
+export type EvidenceState = 'available' | 'unavailable' | 'not-applicable' | 'partial';
+export type EvidenceSource = 'browser' | 'computed-browser' | 'derived';
+export type EvidenceField<T> = {
+    state: 'available';
+    source: EvidenceSource;
+    value: T;
+    derivedFrom?: string[];
+} | {
+    state: 'partial';
+    source: EvidenceSource;
+    value: T;
+    reason: string;
+    derivedFrom?: string[];
+} | {
+    state: 'unavailable';
+    reason: string;
+} | {
+    state: 'not-applicable';
+    reason?: string;
+};
+/**
+ * Structural validator for the frozen EvidenceField<T> contract. Enforces the
+ * per-state field-combination invariants (available/partial require
+ * source+value; unavailable/not-applicable forbid both) and the
+ * derivedFrom-iff-derived-source invariant.
+ */
+export declare function isValidEvidenceField<T = unknown>(field: unknown): field is EvidenceField<T>;