@tileflow/capture 0.0.0-bootstrap.0

package/README.md

@@ -0,0 +1,130 @@
+# @tileflow/capture
+
+Pinned, headless local capture and visual comparison for Tileflow scenes. Most users should invoke
+it through the project-local `tileflow` CLI; this package is the public Node integration surface.
+
+## Capture committed scenes
+
+```ts
+import {captureTileflowScenes} from '@tileflow/capture';
+
+const result = await captureTileflowScenes({
+  scenes: ['madrid-desktop'],
+  allowBrowserInstall: true,
+});
+
+const [{png, receipt, sha256, networkDependent}] = result.captures;
+```
+
+Standalone scenes compile through `@tileflow/dev`, inject the installed MapLibre JS and CSS into a
+pinned Playwright Chromium headless shell, fulfill generated local icon assets in memory, and wait
+for `load`, `idle`, and two animation frames. They never open a visible window or an HTTP listener.
+One call with multiple scenes uses one Browser and a fresh isolated context per scene. Capture
+installs the exact pinned shell automatically when `allowBrowserInstall` is true; the CLI enables
+that normal happy path by default.
+
+For a warm integration, retain and close a session:
+
+```ts
+import {createTileflowCaptureSession} from '@tileflow/capture';
+
+const session = createTileflowCaptureSession({cwd: process.cwd()});
+try {
+  await session.capture(['madrid-desktop']);
+  await session.captureAll();
+} finally {
+  await session.close();
+}
+```
+
+Sessions can also capture caller-provided scene definitions or a prepared `TileflowBuildArtifacts`
+snapshot. Results carry PNG bytes, dimensions, hashes, safe runtime identity, the canonical receipt,
+warnings, and a `networkDependent` flag. They never expose a Playwright page or browser as part of
+the capture result.
+
+Failures use `TileflowCaptureError` with a stable code and optional bounded details. The phase
+distinguishes style validation, browser start, resource loading, MapLibre load/idle, and screenshot
+production. Resource details contain only a classified kind, sanitized origin, optional HTTP
+status, and safe bounded context; raw Playwright stacks, queries, credentials, response bodies, and
+DOM contents are not part of the public diagnostic contract.
+
+## Application capture
+
+Application scenes need only the app's normal loopback server:
+
+```ts
+const result = await captureTileflowScenes({
+  appOrigin: 'http://127.0.0.1:3000',
+  scenes: ['madrid-product'],
+});
+```
+
+Tileflow does not start or discover the server. It accepts only loopback HTTP(S), creates a fresh
+context without reused profile/cookies/storage or service workers, confines redirects to the exact
+approved origin, finds exactly one target, waits for Tileflow's `data-tileflow-state="idle"` marker,
+and captures the element or viewport. The React, Vue, and Svelte wrappers expose the marker plus
+`data-tileflow-map` and optional `data-tileflow-capture-id`. A full one-off `appUrl`, selector, and
+frame can be supplied through the session options. The route and component props own application
+camera state; capture includes that camera in scene identity but does not rewrite it.
+
+## Prepared/offline browser setup
+
+```ts
+import {setupTileflowCaptureBrowser} from '@tileflow/capture';
+
+const renderer = await setupTileflowCaptureBrowser({allowInstall: true});
+```
+
+Playwright provisions its exact platform-specific headless shell in the versioned per-user browser
+cache. Tileflow always launches headlessly, never uses system Chrome, never embeds a browser in the
+npm tarball, and never deletes the shared cache. Set `allowInstall: false` for an offline prepared
+environment. The equivalent CLI command is `tileflow setup capture`; use it to pay installation
+cost in advance or verify prepared CI, not as a prerequisite for normal capture.
+
+## Receipts and visual comparison
+
+`createTileflowCaptureReceipt`, `parseTileflowCaptureReceipt`,
+`validateTileflowCaptureReceipt`, and `serializeTileflowCaptureReceipt` implement the strict,
+bounded schema-version-1 receipt contract. A receipt contains image/scene/style hashes, dimensions,
+renderer/platform identity, required nullable `source.tilesetVersion` evidence, and
+remote-dependency state; it contains no time, user, origin,
+repository, absolute path, config source, environment, or credential.
+
+```ts
+import {compareTileflowCaptureToBaseline} from '@tileflow/capture';
+
+const comparison = await compareTileflowCaptureToBaseline(result.captures[0], {
+  png: baselinePng,
+  receipt: baselineReceiptJson,
+});
+```
+
+Comparison validates PNG CRC, hash, dimensions, pixel bounds, and receipt identity before reading
+pixels. It classifies unchanged, changed, missing, scene-mismatch, and runtime-mismatch results,
+reports exact RGBA changed pixels plus a fixed 0.1 perceptual metric, and returns an optional
+transparent high-contrast diff PNG. Exact RGBA inequality determines `changed`.
+
+For an external design screenshot that has no Tileflow receipt, use the separate exploratory
+primitive:
+
+```ts
+import {analyzeTileflowCaptureReference} from '@tileflow/capture';
+
+const analysis = await analyzeTileflowCaptureReference(result.captures[0], referencePng);
+```
+
+It strictly validates the bounded non-interlaced PNG, reports dimensions and up to 16 deterministic
+quantized palette entries, and—only for equal dimensions—exact/perceptual changed pixels, mean
+absolute RGBA-channel difference, and a high-contrast diff PNG. It does not assert scene/runtime
+compatibility, accept a receipt for the reference, or create a baseline.
+
+## Security and determinism boundary
+
+`tileflow.config.ts` is executable trusted repository code, not a sandbox. Chromium receives a
+small non-secret environment allowlist. Standalone capture fulfills only exact compiled synthetic
+assets and reports external HTTP(S) origins; application capture accepts only loopback URLs and
+does not echo query strings or DOM contents in failures. Remote tiles, glyphs, or sprites can change,
+so a remote-dependent result is evidence but not a globally byte-stable golden image.
+
+See `THIRD_PARTY_NOTICES.md` for runtime license treatment and
+https://tileflow.dev/docs/agent-workflow for the complete CLI workflow.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,35 @@
+# Third-party notices
+
+`@tileflow/capture` depends on the following separately installed open-source packages. Their
+package distributions contain the complete license texts and notices; this file keeps the relevant
+attribution and browser-provisioning boundary visible in the Tileflow package itself.
+
+## Playwright 1.60.0
+
+Copyright (c) Microsoft Corporation. Licensed under the Apache License, Version 2.0. Playwright
+contains code derived from Puppeteer, also available under Apache-2.0. The installed `playwright`
+and `playwright-core` packages include `LICENSE`, `NOTICE`, and `ThirdPartyNotices.txt` files.
+
+## Chromium headless shell revision 1223
+
+Chromium is licensed under the BSD license and includes third-party software under additional open
+source licenses. It is not contained in the `@tileflow/capture` npm tarball. Playwright provisions
+the platform-specific headless shell into its versioned per-user browser cache; the downloaded
+distribution carries Chromium's license and credits. Chromium source and license information are
+available at https://www.chromium.org/chromium-projects/.
+
+## MapLibre GL JS 5.24.0
+
+Copyright (c) 2023 MapLibre contributors. Licensed under BSD-3-Clause. The installed `maplibre-gl`
+package includes `LICENSE.txt`, including notices for code derived from Mapbox GL JS and other
+third-party works.
+
+## Pixelmatch 7.2.0
+
+Copyright (c) 2025 Mapbox. Licensed under the ISC License. The installed `pixelmatch` package
+includes `LICENSE`.
+
+## pngjs 7.0.0
+
+Copyright (c) 2015 Luke Page and original contributors; derived work copyright (c) 2012 Kuba
+Niegowski. Licensed under the MIT License. The installed `pngjs` package includes `LICENSE`.

package/dist/index.d.ts

@@ -0,0 +1,270 @@
+import { Browser } from 'playwright';
+import { 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;
+
+type TileflowBrowserInstallProgress = 'installing' | 'installed';
+type TileflowBrowserLaunchOptions = {
+    allowInstall?: boolean;
+    onInstallProgress?: (progress: TileflowBrowserInstallProgress) => void;
+    signal?: AbortSignal;
+};
+type TileflowCaptureBrowserDependencies = {
+    install(signal?: AbortSignal): Promise<void>;
+    launch(): Promise<Browser>;
+};
+declare function createTileflowCaptureBrowserEnvironment(source?: NodeJS.ProcessEnv): Record<string, string>;
+declare function launchTileflowCaptureBrowser(options?: TileflowBrowserLaunchOptions): Promise<Browser>;
+declare function setupTileflowCaptureBrowser(options?: TileflowBrowserLaunchOptions): Promise<TileflowCaptureRendererIdentity>;
+declare class TileflowCaptureBrowserManager {
+    #private;
+    constructor(options?: TileflowBrowserLaunchOptions, dependencies?: TileflowCaptureBrowserDependencies);
+    getBrowser(signal?: AbortSignal | undefined): Promise<Browser>;
+    close(): Promise<void>;
+}
+
+declare const tileflowCaptureReceiptSchemaVersion: 1;
+declare const tileflowCaptureReceiptLimits: Readonly<{
+    maximumBytes: number;
+}>;
+type TileflowCaptureReceipt = {
+    schemaVersion: 1;
+    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;
+    };
+    source: {
+        tilesetVersion: string | null;
+    };
+    networkDependent: boolean;
+};
+type CreateTileflowCaptureReceiptInput = {
+    dpr: 1 | 2;
+    height: number;
+    map: string;
+    networkDependent: boolean;
+    pngSha256: string;
+    renderer: TileflowCaptureRendererIdentity;
+    scene: string;
+    sceneSha256: string;
+    styleSha256: string;
+    sourceVersion?: 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;
+    appOrigin?: string;
+    appUrl?: string;
+    config?: string;
+    cwd?: string;
+    onBrowserInstallProgress?: (progress: TileflowBrowserInstallProgress) => void;
+    frame?: 'map' | 'viewport';
+    scenes: string[];
+    signal?: AbortSignal;
+    selector?: string;
+    timeoutMs?: number;
+};
+type CreateTileflowCaptureSessionOptions = Omit<TileflowCaptureOptions, 'scenes'>;
+type TileflowCapture = {
+    scene: string;
+    map: string;
+    target: 'map' | 'application';
+    png: Uint8Array;
+    sha256: string;
+    sceneSha256: string;
+    styleSha256: string;
+    width: number;
+    height: number;
+    dpr: 1 | 2;
+    networkDependent: boolean;
+    renderer: TileflowCaptureRendererIdentity;
+    receipt: TileflowCaptureReceipt;
+    warnings: string[];
+};
+type TileflowCaptureResult = {
+    schemaVersion: 1;
+    captures: TileflowCapture[];
+};
+type TileflowCaptureSession = {
+    capture(scenes: string[], signal?: AbortSignal): Promise<TileflowCaptureResult>;
+    captureAll(signal?: AbortSignal): Promise<TileflowCaptureResult>;
+    captureDefinitions(scenes: Record<string, TileflowCaptureScene>, signal?: AbortSignal): Promise<TileflowCaptureResult>;
+    captureArtifacts(artifacts: TileflowBuildArtifacts, requestedScenes: string[], signal?: AbortSignal): Promise<TileflowCaptureResult>;
+    close(): Promise<void>;
+};
+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 TileflowCapturePhase = 'style-validation' | 'browser-start' | 'resource-load' | 'map-load' | 'map-idle' | 'screenshot';
+type TileflowCaptureDiagnostic = {
+    message: string;
+    path: string;
+};
+type TileflowCaptureResourceKind = 'glyph' | 'other-http' | 'sprite-image' | 'sprite-json' | 'tilejson' | 'vector-tile';
+type TileflowCaptureResourceDiagnostic = {
+    context?: string;
+    kind: TileflowCaptureResourceKind;
+    origin: string;
+    status?: number;
+};
+type TileflowCaptureErrorDetails = {
+    diagnostics?: TileflowCaptureDiagnostic[];
+    phase?: TileflowCapturePhase;
+    resources?: TileflowCaptureResourceDiagnostic[];
+};
+type TileflowCaptureErrorOptions = ErrorOptions & {
+    details?: TileflowCaptureErrorDetails;
+};
+declare class TileflowCaptureError extends Error {
+    readonly code: TileflowCaptureErrorCode;
+    readonly details?: TileflowCaptureErrorDetails;
+    constructor(code: TileflowCaptureErrorCode, message: string, options?: TileflowCaptureErrorOptions);
+}
+declare function captureErrorMessage(error: unknown, fallback: string): string;
+
+declare const tileflowSyntheticAssetOrigin = "https://tileflow.local.invalid";
+
+declare function resolveTileflowApplicationUrl(input: {
+    appOrigin?: string;
+    appUrl?: string;
+    path: string;
+}): {
+    origin: string;
+    url: string;
+};
+
+declare const tileflowVisualComparisonSchemaVersion: 1;
+declare const tileflowVisualPerceptualThreshold = 0.1;
+declare const tileflowVisualArtifactLimits: Readonly<{
+    maximumPngBytes: number;
+    maximumPaletteColors: 16;
+}>;
+type TileflowVisualComparisonStatus = 'unchanged' | 'changed' | 'missing-baseline' | 'scene-mismatch' | 'runtime-mismatch';
+type TileflowVisualPixelMetric = {
+    changedPixels: number;
+    totalPixels: number;
+    ratio: number;
+};
+type TileflowVisualImageIdentity = {
+    sha256: string;
+    cssWidth: number;
+    cssHeight: number;
+    physicalWidth: number;
+    physicalHeight: number;
+    dpr: 1 | 2;
+    networkDependent: boolean;
+};
+type TileflowVisualSceneIdentity = TileflowCaptureReceipt['scene'];
+type TileflowVisualRuntimeIdentity = Pick<TileflowCaptureReceipt, 'renderer' | 'platform'>;
+type TileflowVisualComparison = {
+    schemaVersion: 1;
+    scene: string;
+    map: string;
+    target: 'map' | 'application';
+    status: TileflowVisualComparisonStatus;
+    changeKind: 'pixels' | 'dimensions' | null;
+    baselineScene: TileflowVisualSceneIdentity | null;
+    actualScene: TileflowVisualSceneIdentity;
+    baselineRuntime: TileflowVisualRuntimeIdentity | null;
+    actualRuntime: TileflowVisualRuntimeIdentity;
+    baseline: TileflowVisualImageIdentity | null;
+    actual: TileflowVisualImageIdentity;
+    dimensionsMatch: boolean | null;
+    exact: TileflowVisualPixelMetric | null;
+    perceptual: (TileflowVisualPixelMetric & {
+        threshold: number;
+    }) | null;
+    rendererMatch: boolean | null;
+    sceneMatch: boolean | null;
+    diffPng?: Uint8Array;
+    warnings: string[];
+};
+type TileflowVisualComparisonDocument = Omit<TileflowVisualComparison, 'diffPng'>;
+type TileflowVisualPaletteColor = {
+    color: string;
+    count: number;
+    ratio: number;
+};
+type TileflowVisualReferenceAnalysis = {
+    schemaVersion: 1;
+    scene: string;
+    map: string;
+    target: 'map' | 'application';
+    dimensionsMatch: boolean;
+    reference: {
+        sha256: string;
+        physicalWidth: number;
+        physicalHeight: number;
+        palette: TileflowVisualPaletteColor[];
+    };
+    actual: {
+        sha256: string;
+        physicalWidth: number;
+        physicalHeight: number;
+        palette: TileflowVisualPaletteColor[];
+    };
+    exact: TileflowVisualPixelMetric | null;
+    perceptual: (TileflowVisualPixelMetric & {
+        threshold: number;
+    }) | null;
+    meanAbsoluteChannelDifference: number | null;
+    diffPng?: Uint8Array;
+    warnings: string[];
+};
+type TileflowVisualReferenceAnalysisDocument = Omit<TileflowVisualReferenceAnalysis, 'diffPng'>;
+type TileflowVisualBaseline = {
+    png: Uint8Array;
+    receipt: string | Uint8Array | TileflowCaptureReceipt;
+};
+declare function validateTileflowVisualReferencePng(png: Uint8Array): {
+    width: number;
+    height: number;
+};
+declare function analyzeTileflowCaptureReference(actualCapture: TileflowCapture, referencePng: Uint8Array): 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 };