my-frontend-observer 0.1.0

package/dist/domain/evidence.js

@@ -0,0 +1,55 @@
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+const EVIDENCE_SOURCES = ['browser', 'computed-browser', 'derived'];
+function isEvidenceSource(value) {
+    return typeof value === 'string' && EVIDENCE_SOURCES.includes(value);
+}
+function isDerivedFrom(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((entry) => typeof entry === '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 function isValidEvidenceField(field) {
+    if (!isPlainObject(field))
+        return false;
+    const state = field.state;
+    if (state === 'available' || state === 'partial') {
+        if (!isEvidenceSource(field.source))
+            return false;
+        if (!('value' in field) || field.value === undefined)
+            return false;
+        if (state === 'partial' && (typeof field.reason !== 'string' || field.reason.length === 0))
+            return false;
+        if (field.source === 'derived') {
+            if (!isDerivedFrom(field.derivedFrom))
+                return false;
+        }
+        else if ('derivedFrom' in field && field.derivedFrom !== undefined) {
+            return false;
+        }
+        return true;
+    }
+    if (state === 'unavailable') {
+        if ('value' in field && field.value !== undefined)
+            return false;
+        if ('source' in field && field.source !== undefined)
+            return false;
+        return typeof field.reason === 'string' && field.reason.length > 0;
+    }
+    if (state === 'not-applicable') {
+        if ('value' in field && field.value !== undefined)
+            return false;
+        if ('source' in field && field.source !== undefined)
+            return false;
+        if ('reason' in field && field.reason !== undefined && typeof field.reason !== 'string')
+            return false;
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=evidence.js.map

package/dist/domain/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../../src/domain/evidence.ts"],"names":[],"mappings":"AAUA,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,gBAAgB,GAAG,CAAC,SAAS,EAAE,kBAAkB,EAAE,SAAS,CAAU,CAAC;AAE7E,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,gBAAsC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC9F,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC;AACvG,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAc,KAAc;IAC9D,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACxC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAE1B,IAAI,KAAK,KAAK,WAAW,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACjD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,MAAM,CAAC;YAAE,OAAO,KAAK,CAAC;QAClD,IAAI,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QACnE,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QACzG,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,WAAW,CAAC;gBAAE,OAAO,KAAK,CAAC;QACtD,CAAC;aAAM,IAAI,aAAa,IAAI,KAAK,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACrE,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;QAC5B,IAAI,OAAO,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAChE,IAAI,QAAQ,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAClE,OAAO,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IACrE,CAAC;IAED,IAAI,KAAK,KAAK,gBAAgB,EAAE,CAAC;QAC/B,IAAI,OAAO,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAChE,IAAI,QAAQ,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAClE,IAAI,QAAQ,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACtG,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/domain/identity.d.ts

@@ -0,0 +1,13 @@
+import type { NormalizedObservationRequest } from '../request/request.js';
+/**
+ * Pure function of {targetUrl, viewport, targets (order preserved -
+ * semantic), readiness.condition} only. timeoutMs, readiness.timeoutMs, and
+ * outputLocation never affect the result - this is the frozen definition of
+ * "same configuration" for this batch.
+ */
+export declare function buildRequestIdentity(request: NormalizedObservationRequest): string;
+/**
+ * Fresh, opaque per-call identity - never derived from capturedAt/Date.now(),
+ * never collides even when called twice within the same millisecond.
+ */
+export declare function buildObservationIdentity(requestIdentity: string): string;

package/dist/domain/identity.js

@@ -0,0 +1,37 @@
+import { createHash, randomBytes } from 'node:crypto';
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, entryValue]) => [key, canonicalize(entryValue)]);
+        return Object.fromEntries(entries);
+    }
+    return value;
+}
+/**
+ * Pure function of {targetUrl, viewport, targets (order preserved -
+ * semantic), readiness.condition} only. timeoutMs, readiness.timeoutMs, and
+ * outputLocation never affect the result - this is the frozen definition of
+ * "same configuration" for this batch.
+ */
+export function buildRequestIdentity(request) {
+    const semanticView = {
+        targetUrl: request.targetUrl,
+        viewport: { width: request.viewport.width, height: request.viewport.height },
+        targets: request.targets.map((target) => ({ name: target.name.toLowerCase(), selector: target.selector })),
+        readinessCondition: request.readiness.condition,
+    };
+    const serialized = JSON.stringify(canonicalize(semanticView));
+    return createHash('sha256').update(serialized).digest('hex');
+}
+/**
+ * Fresh, opaque per-call identity - never derived from capturedAt/Date.now(),
+ * never collides even when called twice within the same millisecond.
+ */
+export function buildObservationIdentity(requestIdentity) {
+    const nonce = randomBytes(16).toString('hex');
+    return `${requestIdentity}-${nonce}`;
+}
+//# sourceMappingURL=identity.js.map

package/dist/domain/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../src/domain/identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC;aAC7D,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;aAChD,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,YAAY,CAAC,UAAU,CAAC,CAAU,CAAC,CAAC;QACxE,OAAO,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAqC;IACxE,MAAM,YAAY,GAAG;QACnB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,QAAQ,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,EAAE;QAC5E,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC1G,kBAAkB,EAAE,OAAO,CAAC,SAAS,CAAC,SAAS;KAChD,CAAC;IACF,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9D,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,eAAuB;IAC9D,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,OAAO,GAAG,eAAe,IAAI,KAAK,EAAE,CAAC;AACvC,CAAC"}

package/dist/domain/schema.d.ts

@@ -0,0 +1,111 @@
+import type { EvidenceField } from './evidence.js';
+import type { Diagnostic } from './diagnostics.js';
+import type { CompletionState } from './completion.js';
+import type { NormalizedObservationRequest } from '../request/request.js';
+export declare const ARTIFACT_KIND: "my-frontend-observer/observation";
+export declare const SCHEMA_VERSION: "1.0.0";
+export declare const PRODUCER_NAME: "my-frontend-observer";
+export interface ArtifactReference {
+    path: string;
+    kind: string;
+}
+export interface TargetGeometry {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    right: number;
+    bottom: number;
+}
+export interface TargetComputedStyle {
+    display: string;
+    position: string;
+    overflowX: string;
+    overflowY: string;
+}
+export interface TargetLayoutMetrics {
+    scrollWidth: number;
+    scrollHeight: number;
+    clientWidth: number;
+    clientHeight: number;
+    scrollTop: number;
+    scrollLeft: number;
+}
+export interface TargetVisibility {
+    visible: boolean;
+}
+export interface TargetSemantics {
+    role?: string;
+    name?: string;
+}
+/**
+ * Batch 1 froze the wrapper (EvidenceField<T>) and the category names
+ * (resolution/geometry/style) but deliberately left geometry/style typed
+ * `unknown`, deferring the concrete rendered-evidence shapes to whichever
+ * batch actually captures them. Batch 3 fills that in and adds the
+ * remaining v0.1 target-evidence categories (tag/layout/visibility/
+ * semantics) additively: nothing in the repository constructs a
+ * TargetEvidenceRecord yet (only `{}` empty records exist in tests), so no
+ * existing caller loses a field.
+ */
+export interface TargetEvidenceRecord {
+    resolution: EvidenceField<{
+        selectionMethod: string;
+        selectionStatus: string;
+    }>;
+    tag: EvidenceField<string>;
+    geometry: EvidenceField<TargetGeometry>;
+    style: EvidenceField<TargetComputedStyle>;
+    layout: EvidenceField<TargetLayoutMetrics>;
+    visibility: EvidenceField<TargetVisibility>;
+    semantics: EvidenceField<TargetSemantics>;
+}
+export interface ObservationArtifact {
+    artifactKind: typeof ARTIFACT_KIND;
+    schemaVersion: typeof SCHEMA_VERSION;
+    observationId: string;
+    requestId: string;
+    producer: {
+        name: typeof PRODUCER_NAME;
+        version: string;
+    };
+    browser: EvidenceField<{
+        engine: string;
+        version: string;
+    }>;
+    requestConfig: NormalizedObservationRequest;
+    provenance: {
+        capturedAt: string;
+        observationMethod: string;
+    };
+    pageEvidence: Record<string, EvidenceField<unknown>>;
+    targetEvidence: Record<string, TargetEvidenceRecord>;
+    screenshot: EvidenceField<{
+        path: string;
+    }>;
+    completion: CompletionState;
+    diagnostics: Diagnostic[];
+    limits: {
+        truncated: boolean;
+        omittedFields: string[];
+        omittedTargets: string[];
+    };
+    artifactReferences: ArtifactReference[];
+}
+export type SchemaValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * producer.version is read independently from package.json; it is never
+ * equal to schemaVersion by construction - the two are different fields with
+ * unrelated value spaces.
+ */
+export declare function getProducerInfo(): {
+    name: typeof PRODUCER_NAME;
+    version: string;
+};
+/** Structural validator for the frozen schema-1.0.0 ObservationArtifact contract. Treats `value` as arbitrary/unknown input. */
+export declare function isValidObservationArtifact(value: unknown): SchemaValidationResult;

package/dist/domain/schema.js

@@ -0,0 +1,126 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { isValidEvidenceField } from './evidence.js';
+import { DIAGNOSTIC_CODES, DIAGNOSTIC_SEVERITY } from './diagnostics.js';
+export const ARTIFACT_KIND = 'my-frontend-observer/observation';
+export const SCHEMA_VERSION = '1.0.0';
+export const PRODUCER_NAME = 'my-frontend-observer';
+function readPackageVersion() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const packageJsonPath = path.join(here, '..', '..', 'package.json');
+    const raw = readFileSync(packageJsonPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.version !== 'string' || parsed.version.length === 0) {
+        throw new Error('package.json is missing a string "version" field');
+    }
+    return parsed.version;
+}
+/**
+ * producer.version is read independently from package.json; it is never
+ * equal to schemaVersion by construction - the two are different fields with
+ * unrelated value spaces.
+ */
+export function getProducerInfo() {
+    return { name: PRODUCER_NAME, version: readPackageVersion() };
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isValidDiagnostic(value) {
+    if (!isPlainObject(value))
+        return false;
+    const code = value.code;
+    if (typeof code !== 'string' || !DIAGNOSTIC_CODES.includes(code))
+        return false;
+    const expectedSeverity = DIAGNOSTIC_SEVERITY[code];
+    if (value.severity !== expectedSeverity)
+        return false;
+    if (typeof value.message !== 'string')
+        return false;
+    if ('targetName' in value && value.targetName !== undefined && typeof value.targetName !== 'string')
+        return false;
+    return true;
+}
+function isValidCompletionState(value) {
+    if (!isPlainObject(value))
+        return false;
+    const state = value.state;
+    if (state === 'complete') {
+        if (!('diagnostics' in value) || value.diagnostics === undefined)
+            return true;
+        return Array.isArray(value.diagnostics) && value.diagnostics.length === 0;
+    }
+    if (state === 'partial' || state === 'warning' || state === 'invalid-request' || state === 'fatal') {
+        return Array.isArray(value.diagnostics) && value.diagnostics.every((d) => isValidDiagnostic(d));
+    }
+    return false;
+}
+/** Structural validator for the frozen schema-1.0.0 ObservationArtifact contract. Treats `value` as arbitrary/unknown input. */
+export function isValidObservationArtifact(value) {
+    if (!isPlainObject(value))
+        return { valid: false, reason: 'artifact must be an object' };
+    if (value.artifactKind !== ARTIFACT_KIND)
+        return { valid: false, reason: 'artifactKind mismatch' };
+    if (value.schemaVersion !== SCHEMA_VERSION)
+        return { valid: false, reason: 'schemaVersion mismatch' };
+    if (typeof value.observationId !== 'string' || value.observationId.length === 0) {
+        return { valid: false, reason: 'observationId must be a non-empty string' };
+    }
+    if (typeof value.requestId !== 'string' || value.requestId.length === 0) {
+        return { valid: false, reason: 'requestId must be a non-empty string' };
+    }
+    if (!isPlainObject(value.producer) ||
+        value.producer.name !== PRODUCER_NAME ||
+        typeof value.producer.version !== 'string' ||
+        value.producer.version.length === 0) {
+        return { valid: false, reason: 'producer must be { name: "my-frontend-observer", version: string }' };
+    }
+    if (!isValidEvidenceField(value.browser))
+        return { valid: false, reason: 'browser evidence field is invalid' };
+    if (!isPlainObject(value.pageEvidence) || !Object.values(value.pageEvidence).every((v) => isValidEvidenceField(v))) {
+        return { valid: false, reason: 'pageEvidence entries must be valid evidence fields' };
+    }
+    if (!isPlainObject(value.targetEvidence))
+        return { valid: false, reason: 'targetEvidence must be an object' };
+    for (const target of Object.values(value.targetEvidence)) {
+        if (!isPlainObject(target) ||
+            !isValidEvidenceField(target.resolution) ||
+            !isValidEvidenceField(target.tag) ||
+            !isValidEvidenceField(target.geometry) ||
+            !isValidEvidenceField(target.style) ||
+            !isValidEvidenceField(target.layout) ||
+            !isValidEvidenceField(target.visibility) ||
+            !isValidEvidenceField(target.semantics)) {
+            return {
+                valid: false,
+                reason: 'targetEvidence entries must have valid resolution/tag/geometry/style/layout/visibility/semantics evidence fields',
+            };
+        }
+    }
+    if (!isValidEvidenceField(value.screenshot))
+        return { valid: false, reason: 'screenshot evidence field is invalid' };
+    if (!isValidCompletionState(value.completion))
+        return { valid: false, reason: 'completion state is invalid' };
+    if (!Array.isArray(value.diagnostics) || !value.diagnostics.every((d) => isValidDiagnostic(d))) {
+        return { valid: false, reason: 'diagnostics must be an array of valid Diagnostic values' };
+    }
+    if (isPlainObject(value.completion) && value.completion.state === 'complete' && value.diagnostics.length > 0) {
+        return { valid: false, reason: 'completion "complete" requires an empty diagnostics array' };
+    }
+    const limits = value.limits;
+    if (!isPlainObject(limits) ||
+        typeof limits.truncated !== 'boolean' ||
+        !Array.isArray(limits.omittedFields) ||
+        !limits.omittedFields.every((f) => typeof f === 'string') ||
+        !Array.isArray(limits.omittedTargets) ||
+        !limits.omittedTargets.every((f) => typeof f === 'string')) {
+        return { valid: false, reason: 'limits must be { truncated: boolean; omittedFields: string[]; omittedTargets: string[] }' };
+    }
+    if (!Array.isArray(value.artifactReferences) ||
+        !value.artifactReferences.every((r) => isPlainObject(r) && typeof r.path === 'string' && typeof r.kind === 'string')) {
+        return { valid: false, reason: 'artifactReferences must be an array of { path: string; kind: string }' };
+    }
+    return { valid: true };
+}
+//# sourceMappingURL=schema.js.map

package/dist/domain/schema.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export type { EvidenceState, EvidenceSource, EvidenceField } from './domain/evidence.js';
+export { isValidEvidenceField } from './domain/evidence.js';
+export type { DiagnosticCode, DiagnosticSeverity, Diagnostic } from './domain/diagnostics.js';
+export { DIAGNOSTIC_CODES, DIAGNOSTIC_SEVERITY, orderDiagnostics } from './domain/diagnostics.js';
+export type { CompletionState, RequestPhase } from './domain/completion.js';
+export { deriveCompletion } from './domain/completion.js';
+export type { ObservationArtifact, ArtifactReference, TargetEvidenceRecord, TargetGeometry, TargetComputedStyle, TargetLayoutMetrics, TargetVisibility, TargetSemantics, SchemaValidationResult, } from './domain/schema.js';
+export { ARTIFACT_KIND, SCHEMA_VERSION, PRODUCER_NAME, getProducerInfo, isValidObservationArtifact } from './domain/schema.js';
+export { buildRequestIdentity, buildObservationIdentity } from './domain/identity.js';
+export type { NamedTarget, Viewport, ReadinessCondition, ReadinessConfig, NormalizedObservationRequest, RawObservationRequest, NormalizeRequestResult, } from './request/request.js';
+export { normalizeRequest } from './request/request.js';
+export type { NormalizeOutputLocationResult } from './request/paths.js';
+export { normalizeOutputLocation } from './request/paths.js';
+export type { SafetyDecision } from './safety/policy.js';
+export { classifyUrl, classifyRedirect, classifySubresource, classifyPopup, classifyDownload } from './safety/policy.js';
+export type { BrowserCaptureResult, BrowserProvenance } from './browser/types.js';
+export { runBrowserCapture } from './application/browserCaptureService.js';
+export type { PersistedObservationResult } from './artifacts/types.js';
+export { MANIFEST_FILENAME, SCREENSHOT_FILENAME } from './artifacts/artifactWriter.js';
+export type { ApplicationObservationResult } from './application/observationPersistence.js';
+export { buildObservationArtifact, persistBrowserCapture, observe } from './application/observationPersistence.js';

package/dist/index.js

@@ -0,0 +1,12 @@
+export { isValidEvidenceField } from './domain/evidence.js';
+export { DIAGNOSTIC_CODES, DIAGNOSTIC_SEVERITY, orderDiagnostics } from './domain/diagnostics.js';
+export { deriveCompletion } from './domain/completion.js';
+export { ARTIFACT_KIND, SCHEMA_VERSION, PRODUCER_NAME, getProducerInfo, isValidObservationArtifact } from './domain/schema.js';
+export { buildRequestIdentity, buildObservationIdentity } from './domain/identity.js';
+export { normalizeRequest } from './request/request.js';
+export { normalizeOutputLocation } from './request/paths.js';
+export { classifyUrl, classifyRedirect, classifySubresource, classifyPopup, classifyDownload } from './safety/policy.js';
+export { runBrowserCapture } from './application/browserCaptureService.js';
+export { MANIFEST_FILENAME, SCREENSHOT_FILENAME } from './artifacts/artifactWriter.js';
+export { buildObservationArtifact, persistBrowserCapture, observe } from './application/observationPersistence.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAG5D,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGlG,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAa1D,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,aAAa,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,oBAAoB,CAAC;AAE/H,OAAO,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAWtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAG7D,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGzH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wCAAwC,CAAC;AAG3E,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AAEvF,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,yCAAyC,CAAC"}

package/dist/request/paths.d.ts

@@ -0,0 +1,14 @@
+import type { Diagnostic } from '../domain/diagnostics.js';
+export type NormalizeOutputLocationResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    diagnostic: Diagnostic;
+};
+/**
+ * Portable, relative, forward-slash logical path only: no drive letter, no
+ * leading "/", no ".." segment. Backslashes are converted to forward slashes
+ * before validation. Never touches the real filesystem.
+ */
+export declare function normalizeOutputLocation(raw: string): NormalizeOutputLocationResult;

package/dist/request/paths.js

@@ -0,0 +1,33 @@
+const DRIVE_LETTER_RE = /^[A-Za-z]:\//;
+/**
+ * Portable, relative, forward-slash logical path only: no drive letter, no
+ * leading "/", no ".." segment. Backslashes are converted to forward slashes
+ * before validation. Never touches the real filesystem.
+ */
+export function normalizeOutputLocation(raw) {
+    const withForwardSlashes = raw.replace(/\\/g, '/');
+    if (withForwardSlashes.startsWith('/') || DRIVE_LETTER_RE.test(withForwardSlashes)) {
+        return {
+            ok: false,
+            diagnostic: {
+                code: 'invalid-request',
+                severity: 'error',
+                message: 'outputLocation must be a relative, portable path (no drive letter or leading "/")',
+            },
+        };
+    }
+    const segments = withForwardSlashes.split('/');
+    if (segments.some((segment) => segment === '..')) {
+        return {
+            ok: false,
+            diagnostic: {
+                code: 'invalid-request',
+                severity: 'error',
+                message: 'outputLocation must not contain ".." segments',
+            },
+        };
+    }
+    const cleaned = segments.filter((segment) => segment.length > 0 && segment !== '.');
+    return { ok: true, value: cleaned.length > 0 ? cleaned.join('/') : '.' };
+}
+//# sourceMappingURL=paths.js.map

package/dist/request/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/request/paths.ts"],"names":[],"mappings":"AAIA,MAAM,eAAe,GAAG,cAAc,CAAC;AAEvC;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAW;IACjD,MAAM,kBAAkB,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAEnD,IAAI,kBAAkB,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,eAAe,CAAC,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC;QACnF,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU,EAAE;gBACV,IAAI,EAAE,iBAAiB;gBACvB,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,mFAAmF;aAC7F;SACF,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,EAAE,CAAC;QACjD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,UAAU,EAAE;gBACV,IAAI,EAAE,iBAAiB;gBACvB,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,+CAA+C;aACzD;SACF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,OAAO,KAAK,GAAG,CAAC,CAAC;IACpF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AAC3E,CAAC"}

package/dist/request/request.d.ts

@@ -0,0 +1,43 @@
+import type { Diagnostic } from '../domain/diagnostics.js';
+export interface NamedTarget {
+    name: string;
+    selector: string;
+}
+export interface Viewport {
+    width: number;
+    height: number;
+}
+export type ReadinessCondition = 'load' | 'domcontentloaded';
+export interface ReadinessConfig {
+    condition: ReadinessCondition;
+    timeoutMs: number;
+}
+export interface NormalizedObservationRequest {
+    targetUrl: string;
+    viewport: Viewport;
+    targets: NamedTarget[];
+    outputLocation: string;
+    timeoutMs: number;
+    readiness: ReadinessConfig;
+}
+export interface RawObservationRequest {
+    targetUrl?: unknown;
+    viewport?: unknown;
+    targets?: unknown;
+    outputLocation?: unknown;
+    timeoutMs?: unknown;
+    readiness?: unknown;
+}
+export type NormalizeRequestResult = {
+    ok: true;
+    request: NormalizedObservationRequest;
+} | {
+    ok: false;
+    diagnostics: Diagnostic[];
+};
+/**
+ * Total, never throws. Collects every applicable diagnostic before returning
+ * (does not short-circuit on the first violation) so callers see every
+ * problem at once, in deterministic order.
+ */
+export declare function normalizeRequest(raw: RawObservationRequest): NormalizeRequestResult;