@tileflow/capture 0.1.0-alpha.17 → 0.1.0-alpha.19

package/dist/index.d.ts

@@ -1,22 +1,8 @@
 import { Browser } from 'playwright';
-import { TileflowDataIdentity, TileflowCaptureScene } from '@tileflow/core';
-import { TileflowBuildArtifacts } from '@tileflow/dev';
-
-type TileflowCaptureRendererIdentity = {
-    tileflow: string;
-    maplibre: string;
-    playwright: string;
-    chromiumRevision: string;
-    chromiumVersion: string;
-};
-declare const tileflowCaptureRuntime: Readonly<{
-    tileflow: string;
-    maplibre: string;
-    playwright: string;
-    chromiumRevision: string;
-    chromiumVersion: string;
-}>;
-declare function createTileflowCaptureRendererIdentity(browser?: Pick<Browser, 'version'>): TileflowCaptureRendererIdentity;
+import { T as TileflowCaptureRendererIdentity, a as TileflowCaptureReceiptV4, b as TileflowCaptureDataInput, c as TileflowCaptureWorldIdentityV3, d as TileflowCaptureReceipt } from './receipt-Q7wQ68tG.js';
+export { C as CreateTileflowCaptureReceiptInput, e as TileflowCaptureDataBindingsV2, f as TileflowCaptureDataCapabilitiesV2, g as TileflowCaptureDataIdentityV2, h as TileflowCaptureDataIdentityV3, i as TileflowCaptureDataSemanticsV2, j as TileflowCaptureDataSourceV2, k as TileflowCaptureReceiptV2, l as TileflowCaptureReceiptV3, m as TileflowCaptureVectorIdentityV3, n as TileflowCaptureVerificationV2, o as createTileflowCaptureReceipt, p as createTileflowCaptureRendererIdentity, q as parseTileflowCaptureReceipt, s as serializeTileflowCaptureReceipt, t as tileflowCaptureReceiptLimits, r as tileflowCaptureReceiptSchemaVersion, u as tileflowCaptureRuntime, v as validateTileflowCaptureReceipt } from './receipt-Q7wQ68tG.js';
+import { TileflowCaptureScene, MapLibreStyle, NormalizedTileflowCaptureScene } from '@tileflow/core';
+import { TileflowBuildArtifacts } from '@tileflow/dev/artifacts';
 
 type TileflowBrowserInstallProgress = 'installing' | 'installed';
 type TileflowBrowserLaunchOptions = {
@@ -38,56 +24,6 @@ declare class TileflowCaptureBrowserManager {
     close(): Promise<void>;
 }
 
-declare const tileflowCaptureReceiptSchemaVersion: 2;
-declare const tileflowCaptureReceiptLimits: Readonly<{
-    maximumBytes: number;
-}>;
-type TileflowCaptureReceipt = {
-    schemaVersion: 2;
-    scene: {
-        name: string;
-        map: string;
-        target: 'map' | 'application';
-        sha256: string;
-    };
-    style: {
-        sha256: string;
-    };
-    image: {
-        sha256: string;
-        cssWidth: number;
-        cssHeight: number;
-        physicalWidth: number;
-        physicalHeight: number;
-        dpr: 1 | 2;
-    };
-    renderer: TileflowCaptureRendererIdentity;
-    platform: {
-        os: string;
-        architecture: string;
-    };
-    data: TileflowDataIdentity;
-    networkDependent: boolean;
-};
-type CreateTileflowCaptureReceiptInput = {
-    dpr: 1 | 2;
-    data: TileflowDataIdentity;
-    height: number;
-    map: string;
-    networkDependent: boolean;
-    pngSha256: string;
-    renderer: TileflowCaptureRendererIdentity;
-    scene: string;
-    sceneSha256: string;
-    styleSha256: string;
-    target: 'map' | 'application';
-    width: number;
-};
-declare function createTileflowCaptureReceipt(input: CreateTileflowCaptureReceiptInput): TileflowCaptureReceipt;
-declare function serializeTileflowCaptureReceipt(receipt: TileflowCaptureReceipt): string;
-declare function parseTileflowCaptureReceipt(source: string | Uint8Array): TileflowCaptureReceipt;
-declare function validateTileflowCaptureReceipt(value: unknown): TileflowCaptureReceipt;
-
 declare const tileflowCaptureResultSchemaVersion: 1;
 type TileflowCaptureOptions = {
     allowBrowserInstall?: boolean;
@@ -106,6 +42,7 @@ type CreateTileflowCaptureSessionOptions = Omit<TileflowCaptureOptions, 'scenes'
 type TileflowCapture = {
     scene: string;
     map: string;
+    theme: string;
     target: 'map' | 'application';
     png: Uint8Array;
     sha256: string;
@@ -116,7 +53,8 @@ type TileflowCapture = {
     dpr: 1 | 2;
     networkDependent: boolean;
     renderer: TileflowCaptureRendererIdentity;
-    receipt: TileflowCaptureReceipt;
+    /** Newly captured evidence is always the concrete-theme receipt contract. */
+    receipt: TileflowCaptureReceiptV4;
     warnings: string[];
 };
 type TileflowCaptureResult = {
@@ -133,7 +71,7 @@ type TileflowCaptureSession = {
 declare function captureTileflowScenes(options: TileflowCaptureOptions): Promise<TileflowCaptureResult>;
 declare function createTileflowCaptureSession(options?: CreateTileflowCaptureSessionOptions): TileflowCaptureSession;
 
-type TileflowCaptureErrorCode = 'ABORTED' | 'APPLICATION_ORIGIN_REQUIRED' | 'APPLICATION_ORIGIN_INVALID' | 'APPLICATION_NAVIGATION_FAILED' | 'APPLICATION_TARGET_NOT_FOUND' | 'APPLICATION_TARGET_AMBIGUOUS' | 'APPLICATION_ERROR' | 'BASELINE_INVALID' | 'BROWSER_INSTALL_FAILED' | 'BROWSER_MISSING' | 'BROWSER_START_FAILED' | 'CAPTURE_TIMEOUT' | 'INVALID_PNG' | 'MAP_LOAD_FAILED' | 'RENDER_FAILED' | 'RESOURCE_FAILED' | 'SCENE_NOT_FOUND' | 'SCREENSHOT_FAILED' | 'STYLE_INVALID' | 'SYNTHETIC_ASSET_NOT_FOUND';
+type TileflowCaptureErrorCode = 'ABORTED' | 'APPLICATION_ORIGIN_REQUIRED' | 'APPLICATION_ORIGIN_INVALID' | 'APPLICATION_NAVIGATION_FAILED' | 'APPLICATION_TARGET_NOT_FOUND' | 'APPLICATION_TARGET_AMBIGUOUS' | 'APPLICATION_ERROR' | 'BASELINE_INVALID' | 'BROWSER_INSTALL_FAILED' | 'BROWSER_MISSING' | 'BROWSER_START_FAILED' | 'CAPTURE_TIMEOUT' | 'INVALID_PNG' | 'MAP_LOAD_FAILED' | 'RENDER_FAILED' | 'RESOURCE_FAILED' | 'SCENE_NOT_FOUND' | 'SCREENSHOT_FAILED' | 'STYLE_INVALID' | 'SYNTHETIC_ASSET_NOT_FOUND' | 'WORLD_RESOLUTION_FAILED';
 type TileflowCapturePhase = 'style-validation' | 'browser-start' | 'resource-load' | 'map-load' | 'map-idle' | 'screenshot';
 type TileflowCaptureDiagnostic = {
     message: string;
@@ -161,6 +99,35 @@ declare class TileflowCaptureError extends Error {
 }
 declare function captureErrorMessage(error: unknown, fallback: string): string;
 
+declare const tileflowWorldCurrentTileJsonUrl: "https://api.tileflow.dev/tiles/world/tiles.json";
+type FetchTileJson = (input: string, init: {
+    cache: 'no-store';
+    redirect: 'error';
+    signal?: AbortSignal;
+}) => Promise<Pick<Response, 'ok' | 'status' | 'text'>>;
+type TileflowCaptureResolvedWorldV1 = Readonly<{
+    identity: Omit<TileflowCaptureWorldIdentityV3, 'kind' | 'schema' | 'schemaVersion' | 'semantics' | 'sourceId'>;
+    tileJsonUrl: string;
+    tiles: readonly [string];
+}>;
+type PreparedTileflowCaptureStyle = Readonly<{
+    data: TileflowCaptureDataInput;
+    style: MapLibreStyle;
+}>;
+/**
+ * Own one exact World resolution for the complete lifetime of a capture session. A failed lookup
+ * is retained too: retrying the same session cannot silently move to a newer `current` release.
+ */
+declare class TileflowCaptureWorldSession {
+    #private;
+    constructor(fetchTileJson?: FetchTileJson);
+    prepare(style: MapLibreStyle, signal?: AbortSignal): Promise<PreparedTileflowCaptureStyle>;
+}
+declare function resolveTileflowCaptureWorldTileJson(tileJsonUrl: string, options?: {
+    fetchTileJson?: FetchTileJson;
+    signal?: AbortSignal;
+}): Promise<TileflowCaptureResolvedWorldV1>;
+
 declare const tileflowSyntheticAssetOrigin = "https://tileflow.local.invalid";
 
 declare function resolveTileflowApplicationUrl(input: {
@@ -174,6 +141,8 @@ declare function resolveTileflowApplicationUrl(input: {
 
 declare const tileflowVisualComparisonSchemaVersion: 1;
 declare const tileflowVisualPerceptualThreshold = 0.1;
+/** Fixed linear-luminance difference used to classify adjacent pixel pairs as edges. */
+declare const tileflowVisualEdgeThreshold = 0.05;
 declare const tileflowVisualArtifactLimits: Readonly<{
     maximumPngBytes: number;
     maximumPaletteColors: 16;
@@ -224,10 +193,58 @@ type TileflowVisualPaletteColor = {
     count: number;
     ratio: number;
 };
+/** One bounded region in physical PNG pixels, relative to the top-left corner. */
+type TileflowVisualRegion = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type TileflowVisualAppearanceStatistics = {
+    mean: number;
+    percentiles: {
+        p10: number;
+        p50: number;
+        p90: number;
+    };
+};
+type TileflowVisualAppearanceProfile = {
+    /** WCAG relative luminance after compositing transparent pixels on white, in [0, 1]. */
+    linearLuminance: TileflowVisualAppearanceStatistics;
+    /** Perceptual OKLab L after compositing transparent pixels on white, in [0, 1]. */
+    oklabLightness: TileflowVisualAppearanceStatistics;
+    /** Perceptual OKLab chroma after compositing transparent pixels on white. */
+    oklabChroma: TileflowVisualAppearanceStatistics;
+    /** Ratio of horizontal/vertical neighbor pairs crossing tileflowVisualEdgeThreshold. */
+    edgeDensity: number;
+    /** Mean absolute linear-luminance difference across horizontal/vertical neighbor pairs. */
+    localContrast: number;
+};
+/** Signed, field-for-field subtraction between two reported appearance profiles. */
+type TileflowVisualAppearanceDelta = TileflowVisualAppearanceProfile;
+type TileflowVisualReferenceAppearance = {
+    region: TileflowVisualRegion;
+    reference: TileflowVisualAppearanceProfile;
+    actual: TileflowVisualAppearanceProfile;
+    /** Every value is actual minus reference; negative values mean the actual is lower. */
+    actualMinusReference: TileflowVisualAppearanceDelta;
+};
+type TileflowVisualReviewAppearance = {
+    region: TileflowVisualRegion;
+    left: TileflowVisualAppearanceProfile;
+    right: TileflowVisualAppearanceProfile;
+    /** Every value is right minus left; negative values mean the right side is lower. */
+    rightMinusLeft: TileflowVisualAppearanceDelta;
+};
+type TileflowVisualReferenceAnalysisOptions = {
+    /** Restrict appearance metrics to one bounded rectangle in physical PNG pixels. */
+    region?: TileflowVisualRegion;
+};
 type TileflowVisualReferenceAnalysis = {
     schemaVersion: 1;
     scene: string;
     map: string;
+    theme: string;
     target: 'map' | 'application';
     dimensionsMatch: boolean;
     reference: {
@@ -247,6 +264,7 @@ type TileflowVisualReferenceAnalysis = {
         threshold: number;
     }) | null;
     meanAbsoluteChannelDifference: number | null;
+    appearance: TileflowVisualReferenceAppearance | null;
     diffPng?: Uint8Array;
     warnings: string[];
 };
@@ -259,10 +277,80 @@ declare function validateTileflowVisualReferencePng(png: Uint8Array): {
     width: number;
     height: number;
 };
-declare function analyzeTileflowCaptureReference(actualCapture: TileflowCapture, referencePng: Uint8Array): Promise<TileflowVisualReferenceAnalysis>;
+declare function analyzeTileflowCaptureReference(actualCapture: TileflowCapture, referencePng: Uint8Array, options?: TileflowVisualReferenceAnalysisOptions): Promise<TileflowVisualReferenceAnalysis>;
 declare function createTileflowVisualReferenceAnalysisDocument(analysis: TileflowVisualReferenceAnalysis): TileflowVisualReferenceAnalysisDocument;
 declare function compareTileflowCaptureToBaseline(actualCapture: TileflowCapture, baseline?: TileflowVisualBaseline): Promise<TileflowVisualComparison>;
 declare function createTileflowVisualComparisonDocument(comparison: TileflowVisualComparison): TileflowVisualComparisonDocument;
 declare function serializeTileflowVisualComparison(comparison: TileflowVisualComparison | TileflowVisualComparisonDocument): string;
 
-export { type CreateTileflowCaptureSessionOptions, type TileflowBrowserInstallProgress, type TileflowBrowserLaunchOptions, type TileflowCapture, TileflowCaptureBrowserManager, type TileflowCaptureDiagnostic, TileflowCaptureError, type TileflowCaptureErrorCode, type TileflowCaptureErrorDetails, type TileflowCaptureOptions, type TileflowCapturePhase, type TileflowCaptureReceipt, type TileflowCaptureRendererIdentity, type TileflowCaptureResourceDiagnostic, type TileflowCaptureResourceKind, type TileflowCaptureResult, type TileflowCaptureSession, type TileflowVisualBaseline, type TileflowVisualComparison, type TileflowVisualComparisonDocument, type TileflowVisualComparisonStatus, type TileflowVisualImageIdentity, type TileflowVisualPaletteColor, type TileflowVisualPixelMetric, type TileflowVisualReferenceAnalysis, type TileflowVisualReferenceAnalysisDocument, type TileflowVisualRuntimeIdentity, type TileflowVisualSceneIdentity, analyzeTileflowCaptureReference, captureErrorMessage, captureTileflowScenes, compareTileflowCaptureToBaseline, createTileflowCaptureBrowserEnvironment, createTileflowCaptureReceipt, createTileflowCaptureRendererIdentity, createTileflowCaptureSession, createTileflowVisualComparisonDocument, createTileflowVisualReferenceAnalysisDocument, launchTileflowCaptureBrowser, parseTileflowCaptureReceipt, resolveTileflowApplicationUrl, serializeTileflowCaptureReceipt, serializeTileflowVisualComparison, setupTileflowCaptureBrowser, tileflowCaptureReceiptLimits, tileflowCaptureReceiptSchemaVersion, tileflowCaptureResultSchemaVersion, tileflowCaptureRuntime, tileflowSyntheticAssetOrigin, tileflowVisualArtifactLimits, tileflowVisualComparisonSchemaVersion, tileflowVisualPerceptualThreshold, validateTileflowCaptureReceipt, validateTileflowVisualReferencePng };
+declare const tileflowVisualReviewSchemaVersion: 1;
+type TileflowVisualReviewStatus = 'comparable' | 'frame-mismatch' | 'dimensions-mismatch' | 'runtime-mismatch' | 'data-mismatch';
+type TileflowVisualReviewDefinition = NormalizedTileflowCaptureScene & {
+    theme: string;
+};
+type TileflowVisualReviewCapture = {
+    capture: TileflowCapture;
+    definition: TileflowVisualReviewDefinition;
+};
+type TileflowVisualReviewOptions = {
+    /** The contextual diff is evidence for review, never an approval or baseline decision. */
+    includeDiff?: boolean;
+    /** Restrict appearance metrics to one bounded rectangle in physical PNG pixels. */
+    region?: TileflowVisualRegion;
+};
+type TileflowVisualReviewFrameIdentity = {
+    camera: TileflowVisualReviewDefinition['camera'];
+    viewport: TileflowVisualReviewDefinition['viewport'];
+    target: {
+        kind: 'map';
+    } | {
+        kind: 'application';
+        frame: 'map' | 'viewport';
+    };
+};
+type TileflowVisualReviewSide = {
+    scene: TileflowCaptureReceiptV4['scene'];
+    style: TileflowCaptureReceiptV4['style'];
+    frame: TileflowVisualReviewFrameIdentity;
+    image: TileflowVisualImageIdentity;
+    runtime: Pick<TileflowCaptureReceiptV4, 'renderer' | 'platform'>;
+    data: TileflowCaptureReceiptV4['data'];
+    verification: TileflowCaptureReceiptV4['verification'];
+    palette: TileflowVisualPaletteColor[];
+};
+type TileflowVisualReviewComparison = {
+    schemaVersion: 1;
+    kind: 'style-review';
+    status: TileflowVisualReviewStatus;
+    left: TileflowVisualReviewSide;
+    right: TileflowVisualReviewSide;
+    frameMatch: boolean;
+    dimensionsMatch: boolean;
+    rendererMatch: boolean;
+    dataMatch: boolean;
+    exact: TileflowVisualPixelMetric | null;
+    perceptual: (TileflowVisualPixelMetric & {
+        threshold: number;
+    }) | null;
+    meanAbsoluteChannelDifference: number | null;
+    appearance: TileflowVisualReviewAppearance | null;
+    diffPng?: Uint8Array;
+    warnings: string[];
+};
+type TileflowVisualReviewDocument = Omit<TileflowVisualReviewComparison, 'diffPng'>;
+declare class TileflowVisualReviewError extends Error {
+    readonly code: "VISUAL_REVIEW_INVALID";
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Compare two deliberate Tileflow renders for human or agent review. Unlike baseline comparison,
+ * map, theme, scene, and style identities may differ. Pixel evidence is produced only after the
+ * two inputs prove that they share the same frame, dimensions, renderer, and exact data identity.
+ */
+declare function compareTileflowCapturesForReview(leftInput: TileflowVisualReviewCapture, rightInput: TileflowVisualReviewCapture, options?: TileflowVisualReviewOptions): Promise<TileflowVisualReviewComparison>;
+declare function createTileflowVisualReviewDocument(comparison: TileflowVisualReviewComparison): TileflowVisualReviewDocument;
+declare const tileflowVisualReviewLimits: Readonly<{
+    maximumAggregatePngBytes: number;
+}>;
+
+export { type CreateTileflowCaptureSessionOptions, type PreparedTileflowCaptureStyle, type TileflowBrowserInstallProgress, type TileflowBrowserLaunchOptions, type TileflowCapture, TileflowCaptureBrowserManager, TileflowCaptureDataInput, type TileflowCaptureDiagnostic, TileflowCaptureError, type TileflowCaptureErrorCode, type TileflowCaptureErrorDetails, type TileflowCaptureOptions, type TileflowCapturePhase, TileflowCaptureReceipt, TileflowCaptureReceiptV4, TileflowCaptureRendererIdentity, type TileflowCaptureResolvedWorldV1, type TileflowCaptureResourceDiagnostic, type TileflowCaptureResourceKind, type TileflowCaptureResult, type TileflowCaptureSession, TileflowCaptureWorldIdentityV3, TileflowCaptureWorldSession, type TileflowVisualAppearanceDelta, type TileflowVisualAppearanceProfile, type TileflowVisualAppearanceStatistics, type TileflowVisualBaseline, type TileflowVisualComparison, type TileflowVisualComparisonDocument, type TileflowVisualComparisonStatus, type TileflowVisualImageIdentity, type TileflowVisualPaletteColor, type TileflowVisualPixelMetric, type TileflowVisualReferenceAnalysis, type TileflowVisualReferenceAnalysisDocument, type TileflowVisualReferenceAnalysisOptions, type TileflowVisualReferenceAppearance, type TileflowVisualRegion, type TileflowVisualReviewAppearance, type TileflowVisualReviewCapture, type TileflowVisualReviewComparison, type TileflowVisualReviewDefinition, type TileflowVisualReviewDocument, TileflowVisualReviewError, type TileflowVisualReviewFrameIdentity, type TileflowVisualReviewOptions, type TileflowVisualReviewSide, type TileflowVisualReviewStatus, type TileflowVisualRuntimeIdentity, type TileflowVisualSceneIdentity, analyzeTileflowCaptureReference, captureErrorMessage, captureTileflowScenes, compareTileflowCaptureToBaseline, compareTileflowCapturesForReview, createTileflowCaptureBrowserEnvironment, createTileflowCaptureSession, createTileflowVisualComparisonDocument, createTileflowVisualReferenceAnalysisDocument, createTileflowVisualReviewDocument, launchTileflowCaptureBrowser, resolveTileflowApplicationUrl, resolveTileflowCaptureWorldTileJson, serializeTileflowVisualComparison, setupTileflowCaptureBrowser, tileflowCaptureResultSchemaVersion, tileflowSyntheticAssetOrigin, tileflowVisualArtifactLimits, tileflowVisualComparisonSchemaVersion, tileflowVisualEdgeThreshold, tileflowVisualPerceptualThreshold, tileflowVisualReviewLimits, tileflowVisualReviewSchemaVersion, tileflowWorldCurrentTileJsonUrl, validateTileflowVisualReferencePng };