@tileflow/dev 0.1.0-alpha.14 → 0.1.0-alpha.17

package/README.md

@@ -14,10 +14,131 @@ const artifacts = await createTileflowBuildArtifacts({
 });
 ```
 
+`createTileflowStyle`, `createTileflowStyles`, and artifact construction all enforce the same
+recursive JSON-value invariant and MapLibre style-spec semantics without fetching remote resources.
+Invalid output throws `TileflowStyleValidationError` with at most 32 deterministic
+`map`/`path`/`message` issues; layer indexes are projected to stable layer IDs.
+
+For a watched, last-known-good integration, use one artifact session rather than recompiling each
+request independently:
+
+```ts
+import {createTileflowArtifactSession} from '@tileflow/dev';
+
+const session = await createTileflowArtifactSession({
+  config: 'tileflow.config.ts',
+  watch: true,
+});
+
+const unsubscribe = session.subscribe((state) => {
+  // building -> ready, or invalid while getLastGoodArtifacts() remains available
+  console.log(state.status, state.generation);
+});
+
+unsubscribe();
+await session.close();
+```
+
+The bounded watcher follows the config, transitive local TypeScript/JavaScript/JSON imports, and
+effective icon inputs. Generations are monotonic, overlapping refreshes are latest-wins, invalid
+edits retain the last good snapshot, and caller-supplied output directories can be ignored to avoid
+feedback loops. `tileflow dev`, `capture --watch`, and framework adapters use this shared status
+vocabulary.
+
+Custom preview servers can select the same map or standalone scene semantics as the CLI:
+
+```ts
+import {createTileflowDevRequestHandler} from '@tileflow/dev';
+
+const fetch = createTileflowDevRequestHandler({
+  session,
+  scene: 'madrid-mobile',
+});
+```
+
+`map` and `scene` are mutually exclusive. Map preview uses the configured `view`; scene preview
+uses its committed camera and CSS viewport. `resolveTileflowPreview()` exposes the validated
+selection for custom integrations. Application-target scenes remain the responsibility of the
+application's development server.
+
 If a map uses `icons: './icons/brand'`, build artifacts include the generated
 MapLibre `sprite.json`, `sprite.png`, `sprite@2x.json`, and `sprite@2x.png`
 assets alongside the styles.
 
+## Bounded vector-feature inspection
+
+Custom Node tooling can inspect only the features visible near a configured camera without opening
+a browser:
+
+```ts
+import {inspectTileflowFeatures} from '@tileflow/dev';
+
+const inspection = await inspectTileflowFeatures(project, 'madrid', {
+  center: [-3.6927512, 40.4086555],
+  zoom: 16,
+  sourceLayers: ['poi'],
+  properties: ['name', 'class', 'subclass', 'rank'],
+  width: 512,
+  height: 512,
+  limit: 100,
+});
+```
+
+The inspector supports ordinary HTTP(S) vector sources and TileJSON. It bounds viewport, tile
+count, individual/total bytes, scanned and returned features, property count/string lengths, and
+request time; results are deduplicated and sorted deterministically. Output contains projected
+properties, geometry summaries, safe origin/path metadata, and the configured source revision or
+`null`. It never emits URL queries, credentials, hidden properties, response bodies, or absolute
+paths. PMTiles and authenticated provider adapters are not currently supported by this primitive.
+
+Deployment adapters can compile the same sources without writing them to disk:
+
+```ts
+import {compileTileflowIconPackages} from '@tileflow/dev';
+
+const result = await compileTileflowIconPackages(project, {
+  cwd: process.cwd(),
+  target: 'hosted',
+});
+```
+
+The hosted target enforces repository containment, portable icon IDs, safe SVG
+references, deterministic ordering, and the public package limits. It returns
+deduplicated generated files plus a canonical manifest/content hash. Upload only
+those generated files: source icons and absolute paths remain local. External
+sprite URLs are preserved as references and are not downloaded.
+
+The version-1 manifest includes `renderedIcons` in the exact sorted `iconNames` order. Each entry
+contains SHA-256 digests for the normalized 1x and 2x RGBA cell. The digest framing includes its
+density and dimensions, zeroes RGB only where alpha is zero, and excludes filenames/source bytes.
+The package content hash still covers the complete canonical manifest, including all four encoded
+file hashes. Consumers can therefore distinguish a visible per-icon change from an atlas-layout or
+encoding-only package change without receiving the original SVG/raster file.
+
+`compileTileflowIconPackages` retains the exact RGBA cells used to assemble each atlas, so its
+pixel digests describe delivered pixels rather than a second render. Hosted upload services must
+decode the submitted PNGs and reconstruct those digests independently; client-authored manifest
+analysis is not authoritative.
+
+Custom Node tooling can inspect the same local pipeline without walking or decoding source files a
+second time:
+
+```ts
+import {inspectTileflowIconCatalogs} from '@tileflow/dev';
+
+const inspection = await inspectTileflowIconCatalogs(project, {
+  cwd: process.cwd(),
+  mapNames: ['madrid'],
+});
+```
+
+The result keeps one catalog per resolved source directory, map-specific resolved mappings,
+cwd-relative source metadata, exact atlas rectangles, both manifest pixel digests, and the shared
+compiled package. It classifies remote and absent catalogs without fetching them. This is a
+local-authoring integration surface: use the hosted compilation target separately for deployment
+compatibility, and project only the metadata needed by an external protocol rather than serializing
+generated byte arrays accidentally.
+
 This package is public, but it is an integration layer. Map styling primitives live in
 `@tileflow/core`; React rendering lives in `@tileflow/react`.
 

package/dist/index.d.ts

@@ -1,11 +1,232 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { TileflowManifest, MapLibreStyle, ValidationMessage, TileflowProjectConfig, TileflowStyleOptions } from '@tileflow/core';
+import { TileflowIconPackageFileName, TileflowIconPackageManifest, TileflowProjectConfig, MapLibreStyle, NormalizedTileflowCaptureScene, TileflowManifest, ValidationMessage, TileflowStyleOptions } from '@tileflow/core';
+
+declare const tileflowArtifactSessionSchemaVersion: 1;
+type TileflowArtifactDiagnostic = {
+    code?: string;
+    message: string;
+    path: string;
+    phase?: string;
+};
+type TileflowArtifactSessionState = {
+    status: 'building';
+    generation: number;
+    lastGoodGeneration?: number;
+} | {
+    status: 'ready';
+    generation: number;
+    artifacts: TileflowBuildArtifacts;
+    lastGoodGeneration: number;
+} | {
+    status: 'invalid';
+    generation: number;
+    diagnostics: TileflowArtifactDiagnostic[];
+    lastGoodGeneration?: number;
+};
+type TileflowArtifactSessionOptions = TileflowBuildArtifactsOptions & {
+    debounceMs?: number;
+    ignoredPaths?: string[];
+    watch?: boolean;
+};
+type TileflowArtifactSession = {
+    close(): Promise<void>;
+    getLastGoodArtifacts(): TileflowBuildArtifacts | undefined;
+    getState(): TileflowArtifactSessionState;
+    refresh(reason?: string): Promise<void>;
+    subscribe(listener: (state: TileflowArtifactSessionState) => void): () => void;
+};
+declare function createTileflowArtifactDiagnostics(error: unknown, cwd: string): TileflowArtifactDiagnostic[];
 
 type TileflowBuildAsset = {
     contentType: string;
     fileName: string;
     source: string | Uint8Array;
 };
+type PreparedTileflowProject = {
+    assets: TileflowBuildAsset[];
+    project: TileflowProjectConfig;
+    watchPaths: string[];
+};
+type TileflowIconCompilationTarget = 'hosted' | 'local';
+type TileflowIconCompilationIssue = {
+    message: string;
+    path: string;
+};
+type CompiledTileflowIconPackageFile = {
+    contentType: 'application/json' | 'image/png';
+    fileName: TileflowIconPackageFileName;
+    source: Uint8Array;
+};
+type CompiledTileflowIconPackage = {
+    contentHash: string;
+    files: CompiledTileflowIconPackageFile[];
+    manifest: TileflowIconPackageManifest;
+};
+type TileflowMapIconPackageBinding = {
+    label: string;
+    mapName: string;
+    mapping?: Record<string, string>;
+    packageHash: string;
+};
+type CompileTileflowIconPackagesResult = {
+    bindings: TileflowMapIconPackageBinding[];
+    packages: CompiledTileflowIconPackage[];
+    watchPaths: string[];
+};
+type InspectTileflowIconCatalogsOptions = {
+    cwd: string;
+    mapNames?: readonly string[];
+};
+type TileflowIconCatalogSourceFormat = 'jpeg' | 'png' | 'svg' | 'webp';
+type TileflowIconCatalogMapping = {
+    iconId: string;
+    semantic: string;
+    targetStatus: 'missing' | 'present' | 'unknown';
+};
+type TileflowIconCatalogMappedFrom = {
+    map: string;
+    semantic: string;
+};
+type TileflowIconCatalogAtlasRectangle = {
+    height: number;
+    width: number;
+    x: number;
+    y: number;
+};
+type TileflowIconCatalogRenderedDensity = {
+    atlas: TileflowIconCatalogAtlasRectangle;
+    height: number;
+    pixelRatio: 1 | 2;
+    pixelSha256: string;
+    width: number;
+};
+type TileflowIconCatalogIcon = {
+    id: string;
+    mappedFrom: TileflowIconCatalogMappedFrom[];
+    rendered: {
+        oneX: TileflowIconCatalogRenderedDensity;
+        twoX: TileflowIconCatalogRenderedDensity;
+    };
+    source: {
+        byteLength: number;
+        dimensions: {
+            height: number;
+            width: number;
+        } | null;
+        format: TileflowIconCatalogSourceFormat;
+        path: string;
+    };
+};
+type TileflowIconCatalog = {
+    compiledPackage: CompiledTileflowIconPackage;
+    icons: TileflowIconCatalogIcon[];
+    insideWorkingTree: boolean;
+    sourcePath: string;
+};
+type TileflowIconCatalogMap = {
+    name: string;
+    icons: {
+        catalogSourcePath: string;
+        kind: 'local';
+        label: string;
+        mappings: TileflowIconCatalogMapping[];
+        packageHash: string;
+    } | {
+        inspectable: false;
+        kind: 'external';
+        mappings: TileflowIconCatalogMapping[];
+    } | {
+        inspectable: false;
+        kind: 'none';
+        mappings: TileflowIconCatalogMapping[];
+    };
+};
+type TileflowIconCatalogInspection = {
+    catalogs: TileflowIconCatalog[];
+    maps: TileflowIconCatalogMap[];
+};
+declare class TileflowIconCompilationError extends Error {
+    readonly code: "ICON_INVALID";
+    readonly issues: TileflowIconCompilationIssue[];
+    readonly phase: "icon-compilation";
+    constructor(issues: TileflowIconCompilationIssue[]);
+}
+declare const iconFileExtensions: Set<string>;
+declare function compileTileflowIconPackages(project: TileflowProjectConfig, options: {
+    cwd: string;
+    target: TileflowIconCompilationTarget;
+}): Promise<CompileTileflowIconPackagesResult>;
+declare function inspectTileflowIconCatalogs(project: TileflowProjectConfig, options: InspectTileflowIconCatalogsOptions): Promise<TileflowIconCatalogInspection>;
+declare function prepareTileflowProjectIcons(project: TileflowProjectConfig, options: {
+    assetBaseUrl: string;
+    cwd: string;
+}): Promise<PreparedTileflowProject>;
+
+type TileflowFeatureInspectionOptions = {
+    center: readonly [number, number];
+    fetch?: typeof fetch;
+    height?: number;
+    limit?: number;
+    properties?: readonly string[];
+    signal?: AbortSignal;
+    sourceLayers: readonly string[];
+    tileBaseUrl?: string;
+    timeoutMs?: number;
+    width?: number;
+    zoom: number;
+};
+type TileflowInspectedProperty = boolean | number | string;
+type TileflowInspectedFeature = {
+    sourceLayer: string;
+    id: number | null;
+    geometry: {
+        type: string;
+        center: [number, number];
+        bounds: [number, number, number, number];
+    };
+    properties: Record<string, TileflowInspectedProperty>;
+};
+type TileflowFeatureInspection = {
+    schemaVersion: 1;
+    map: string;
+    camera: {
+        center: [number, number];
+        zoom: number;
+        viewport: {
+            width: number;
+            height: number;
+        };
+    };
+    source: {
+        id: string;
+        origin: string;
+        tileJsonPath: string | null;
+        tileOrigins: string[];
+        version: string | null;
+    };
+    sourceLayers: string[];
+    properties: string[];
+    tileZoom: number;
+    tilesRead: number;
+    scannedFeatures: number;
+    truncated: boolean;
+    features: TileflowInspectedFeature[];
+};
+declare function inspectTileflowFeatures(project: TileflowProjectConfig, mapName: string, input: TileflowFeatureInspectionOptions): Promise<TileflowFeatureInspection>;
+
+type TileflowStyleValidationIssue = {
+    map: string;
+    message: string;
+    path: string;
+};
+declare class TileflowStyleValidationError extends Error {
+    readonly code: "STYLE_INVALID";
+    readonly issues: TileflowStyleValidationIssue[];
+    readonly phase: "style-validation";
+    constructor(issues: readonly TileflowStyleValidationIssue[]);
+}
+declare function assertValidTileflowStyle(style: MapLibreStyle, map: string): void;
+declare function validateTileflowStyle(style: MapLibreStyle, map: string): TileflowStyleValidationIssue[];
 
 declare const defaultTileflowApiUrl = "https://api.tileflow.dev";
 declare const defaultTileflowConfigPath = "tileflow.config.ts";
@@ -23,10 +244,27 @@ type TileflowDevRequestHandlerOptions = {
     basePath?: string;
     config?: string;
     cwd?: string;
+    map?: string;
     onError?: (error: unknown) => void;
+    scene?: string;
+    session?: TileflowArtifactSession;
     styleBaseUrl?: string;
     tileBaseUrl?: string;
 };
+type TileflowPreviewSelection = {
+    map?: string;
+    scene?: string;
+};
+type ResolvedTileflowPreview = {
+    camera: NormalizedTileflowCaptureScene['camera'];
+    label: string;
+    mapName: string;
+    viewport?: NormalizedTileflowCaptureScene['viewport'];
+};
+declare class TileflowPreviewSelectionError extends Error {
+    readonly code: "PREVIEW_SELECTION_INVALID";
+    constructor(message: string);
+}
 type TileflowBuildArtifactsOptions = {
     assetBaseUrl?: string;
     config?: string;
@@ -37,6 +275,7 @@ type TileflowBuildArtifactsOptions = {
 type TileflowBuildArtifacts = {
     assets: TileflowBuildAsset[];
     manifest: TileflowManifest;
+    project: TileflowProjectConfig;
     styles: Record<string, MapLibreStyle>;
     watchPaths: string[];
 };
@@ -44,7 +283,9 @@ type WriteTileflowBuildArtifactsOptions = TileflowBuildArtifactsOptions & {
     outDir: string;
 };
 declare class TileflowValidationError extends Error {
+    readonly code: "CONFIG_INVALID";
     readonly messages: ValidationMessage[];
+    readonly phase: "config-validation";
     constructor(messages: ValidationMessage[]);
 }
 declare function loadTileflowConfig(configPath?: string, options?: LoadTileflowConfigOptions): Promise<TileflowProjectConfig>;
@@ -53,10 +294,13 @@ declare function assertValidTileflowConfig(project: TileflowProjectConfig): void
 declare function asTileflowProjectConfig(input: unknown): TileflowProjectConfig;
 declare function getTileflowMapNames(project: TileflowProjectConfig): string[];
 declare function getFirstTileflowMapName(project: TileflowProjectConfig): string;
+declare function resolveTileflowPreview(project: TileflowProjectConfig, selection?: TileflowPreviewSelection): ResolvedTileflowPreview;
 declare function getTileflowStyleMapName(path: string): string;
 declare function createTileflowManifest(project: TileflowProjectConfig, options?: TileflowManifestOptions): TileflowManifest;
 declare function createTileflowStyle(project: TileflowProjectConfig, mapName: string, options?: TileflowStyleOptions): MapLibreStyle;
+declare function createTileflowStyles(project: TileflowProjectConfig, options?: TileflowStyleOptions): Record<string, MapLibreStyle>;
 declare function createTileflowBuildArtifacts(options?: TileflowBuildArtifactsOptions): Promise<TileflowBuildArtifacts>;
+declare function createTileflowArtifactSession(options?: TileflowArtifactSessionOptions): Promise<TileflowArtifactSession>;
 declare function getTileflowWatchPaths(options?: Pick<TileflowBuildArtifactsOptions, 'config' | 'cwd'>): Promise<string[]>;
 declare function writeTileflowBuildArtifacts(options: WriteTileflowBuildArtifactsOptions): Promise<TileflowBuildArtifacts>;
 declare function isTileflowRequestUrl(url: string | undefined, basePath: string): boolean;
@@ -66,6 +310,13 @@ declare function joinTileflowPublicUrl(publicBase: string, basePath: string): st
 declare function getTileflowAssetBasePath(basePath: string): string;
 declare function getTileflowAssetFileName(basePath: string, fileName: string): string;
 declare function createTileflowDevRequestHandler(options?: TileflowDevRequestHandlerOptions): (request: Request) => Promise<Response>;
+declare function createTileflowArtifactStatus(state: TileflowArtifactSessionState): {
+    diagnostics?: TileflowArtifactDiagnostic[] | undefined;
+    lastGoodGeneration?: number | undefined;
+    schemaVersion: 1;
+    generation: number;
+    status: "building" | "ready" | "invalid";
+};
 declare function normalizeTileflowBasePath(value?: string): string;
 
-export { type LoadTileflowConfigOptions, type TileflowBuildArtifacts, type TileflowBuildArtifactsOptions, type TileflowDevRequestHandlerOptions, type TileflowManifestOptions, TileflowValidationError, type WriteTileflowBuildArtifactsOptions, asTileflowProjectConfig, assertValidTileflowConfig, createTileflowBuildArtifacts, createTileflowDevRequestHandler, createTileflowManifest, createTileflowNodeRequest, createTileflowStyle, defaultTileflowApiUrl, defaultTileflowConfigPath, defaultTileflowManifestPath, defaultTileflowTileset, getFirstTileflowMapName, getTileflowAssetBasePath, getTileflowAssetFileName, getTileflowMapNames, getTileflowStyleMapName, getTileflowWatchPaths, isTileflowRequestUrl, joinTileflowPublicUrl, loadTileflowConfig, loadValidTileflowConfig, normalizeTileflowBasePath, writeTileflowBuildArtifacts, writeTileflowNodeResponse };
+export { type CompileTileflowIconPackagesResult, type CompiledTileflowIconPackage, type CompiledTileflowIconPackageFile, type InspectTileflowIconCatalogsOptions, type LoadTileflowConfigOptions, type PreparedTileflowProject, type ResolvedTileflowPreview, type TileflowArtifactDiagnostic, type TileflowArtifactSession, type TileflowArtifactSessionOptions, type TileflowArtifactSessionState, type TileflowBuildArtifacts, type TileflowBuildArtifactsOptions, type TileflowBuildAsset, type TileflowDevRequestHandlerOptions, type TileflowFeatureInspection, type TileflowFeatureInspectionOptions, type TileflowIconCatalog, type TileflowIconCatalogAtlasRectangle, type TileflowIconCatalogIcon, type TileflowIconCatalogInspection, type TileflowIconCatalogMap, type TileflowIconCatalogMappedFrom, type TileflowIconCatalogMapping, type TileflowIconCatalogRenderedDensity, type TileflowIconCatalogSourceFormat, TileflowIconCompilationError, type TileflowIconCompilationIssue, type TileflowIconCompilationTarget, type TileflowInspectedFeature, type TileflowInspectedProperty, type TileflowManifestOptions, type TileflowMapIconPackageBinding, type TileflowPreviewSelection, TileflowPreviewSelectionError, TileflowStyleValidationError, type TileflowStyleValidationIssue, TileflowValidationError, type WriteTileflowBuildArtifactsOptions, asTileflowProjectConfig, assertValidTileflowConfig, assertValidTileflowStyle, compileTileflowIconPackages, createTileflowArtifactDiagnostics, createTileflowArtifactSession, createTileflowArtifactStatus, createTileflowBuildArtifacts, createTileflowDevRequestHandler, createTileflowManifest, createTileflowNodeRequest, createTileflowStyle, createTileflowStyles, defaultTileflowApiUrl, defaultTileflowConfigPath, defaultTileflowManifestPath, defaultTileflowTileset, getFirstTileflowMapName, getTileflowAssetBasePath, getTileflowAssetFileName, getTileflowMapNames, getTileflowStyleMapName, getTileflowWatchPaths, iconFileExtensions, inspectTileflowFeatures, inspectTileflowIconCatalogs, isTileflowRequestUrl, joinTileflowPublicUrl, loadTileflowConfig, loadValidTileflowConfig, normalizeTileflowBasePath, prepareTileflowProjectIcons, resolveTileflowPreview, tileflowArtifactSessionSchemaVersion, validateTileflowStyle, writeTileflowBuildArtifacts, writeTileflowNodeResponse };