@tileflow/dev 0.1.0-alpha.4 → 0.1.0-alpha.41

package/dist/icons-BIHpw5Zy.d.ts

@@ -0,0 +1,417 @@
+import { TileflowIconAppearance, TileflowIconLayoutMetadata, TileflowIconSetPin, TileflowLandmarkRegion, TileflowLandmarkFootprint, TileflowModelDirectory, TileflowTreeModel, TileflowIconSpriteIndex, TileflowIconSource, TileflowIconsLockfileV1, TileflowIconCompositionV1, TileflowIconPackageFileName, TileflowIconPackageManifest, TileflowIconDirectory } from '@tileflow/core';
+import { TileflowEffectiveModelSourceIdentity, TileflowEffectiveIconSourceIdentity, TileflowBuildCatalog, TileflowPreparedMapAssets } from '@tileflow/core/build';
+
+type TileflowRenderedIconCell = {
+    height: number;
+    width: number;
+    rgba: Uint8Array;
+};
+type TileflowRenderedIcon = {
+    id: string;
+    appearance?: TileflowIconAppearance;
+    layout?: TileflowIconLayoutMetadata;
+    oneX: TileflowRenderedIconCell;
+    twoX: TileflowRenderedIconCell;
+};
+/** Pack independently rendered densities without scaling or re-rasterizing either input. */
+declare function packTileflowRenderedIcons(input: readonly TileflowRenderedIcon[]): Promise<CompiledTileflowIconPackage>;
+
+type VerifiedTileflowIconArtifact = {
+    package: CompiledTileflowIconPackage;
+    icons: TileflowRenderedIcon[];
+};
+/** Verify exact compressed bytes and independently decode/hash every cell at both densities. */
+declare function verifyTileflowIconArtifact(input: CompiledTileflowIconPackage): Promise<VerifiedTileflowIconArtifact>;
+
+type TileflowIconCacheOptions = {
+    /** Parent of the versioned tileflow/icons/v1 cache, not a serialized lock setting. */
+    cacheRoot?: string;
+    offline?: boolean;
+    /** Trusted application configuration. A lock cannot extend this allowlist. */
+    deliveryOrigins?: readonly string[];
+    fetch?: typeof globalThis.fetch;
+    signal?: AbortSignal;
+};
+declare function getTileflowIconCacheDirectory(options?: Pick<TileflowIconCacheOptions, 'cacheRoot'>): string;
+/** Read and verify an exact pin; a cache miss never resolves a newer version. */
+declare function loadTileflowIconSetArtifact(input: TileflowIconSetPin, options?: TileflowIconCacheOptions): Promise<VerifiedTileflowIconArtifact>;
+/** Seed or repair a disposable cache using verified generated bytes, never original artwork. */
+declare function storeTileflowIconSetArtifact(input: TileflowIconSetPin, artifact: CompiledTileflowIconPackage, options?: Pick<TileflowIconCacheOptions, 'cacheRoot'>): Promise<VerifiedTileflowIconArtifact>;
+
+/** A building model file, prepared for the build to write beside the style. */
+type PreparedTileflowBuildingModel = {
+    /** Its file name, content-addressed: `<id>-<first 16 hex of its SHA-256>.glb`. */
+    fileName: string;
+    bytes: Uint8Array;
+    sha256: string;
+    /** The glTF binaries it was prepared from, nearest level first. */
+    sources: readonly Readonly<{
+        level: 'near' | 'mid' | 'far';
+        sha256: string;
+        byteLength: number;
+    }>[];
+};
+/** A building model's glTF binaries, nearest level first. */
+type TileflowBuildingModelLevels = Readonly<{
+    near: Uint8Array;
+    mid?: Uint8Array;
+    far?: Uint8Array;
+}>;
+/**
+ * Prepares one building model from its glTF binaries into the file a build writes beside the
+ * style: a glTF binary compressed with meshoptimizer. Its footprint is the near level's `footprint`
+ * mesh, or else its outline on the ground. Throws `TileflowGltfError` or `RangeError` with words an
+ * author can act on.
+ */
+declare function prepareTileflowBuildingModel(id: string, levels: TileflowBuildingModelLevels): Promise<{
+    bytes: Uint8Array;
+    sha256: string;
+}>;
+/** A landmark to package: a building model and where it stands. */
+type TileflowLandmarkSource = Readonly<{
+    id: string;
+    /** Longitude and latitude of its origin. */
+    at: readonly [number, number];
+    /** Degrees clockwise from north its own north is turned to, from 0 to 360. */
+    heading: number;
+    levels: TileflowBuildingModelLevels;
+}>;
+/**
+ * Packages the landmarks standing in one tile of a landmarks tileset into that tile's prepared
+ * model file, the landmarks in the order of their ids. Every landmark's origin must fall in the
+ * same zoom-14 tile. It also returns each landmark's place and footprint, as the region's index
+ * names them. The result depends only on its input.
+ */
+declare function packageTileflowLandmarkTile(landmarks: readonly TileflowLandmarkSource[]): Promise<{
+    x: number;
+    y: number;
+    bytes: Uint8Array;
+    sha256: string;
+    landmarks: readonly TileflowLandmarkFootprint[];
+}>;
+/**
+ * Writes the index of one region of a landmarks tileset, `{region: [x, y], tiles: [[x, y, sha256,
+ * landmarks], ...]}`, as the bytes the tileset serves, with their SHA-256. A tile's `landmarks` are
+ * the ones `packageTileflowLandmarkTile` returned for it, or `readTileflowLandmarkTileFootprints`
+ * reads back from its bytes.
+ */
+declare function encodeTileflowLandmarkRegion(region: TileflowLandmarkRegion): {
+    bytes: Uint8Array;
+    sha256: string;
+};
+type PreparedTileflowTreeModels = {
+    /** The prepared tree models by id. */
+    models: Record<string, TileflowTreeModel>;
+    /** The prepared building models by id. */
+    buildings: Record<string, PreparedTileflowBuildingModel>;
+    identities: TileflowEffectiveModelSourceIdentity[];
+    /** Directories to watch for changes. */
+    watchPaths: string[];
+};
+/** Reads, checks and prepares one map's model directories. */
+declare function prepareTileflowMapTreeModels(directories: readonly TileflowModelDirectory[], options: {
+    baseDirectory: string;
+    configPath: string;
+    cwd: string;
+    target: 'hosted' | 'local';
+}): Promise<PreparedTileflowTreeModels>;
+
+/** Render a report image without changing the immutable generated sprite. */
+declare function renderTileflowIconAtlasPreview(source: Uint8Array, index: TileflowIconSpriteIndex): Promise<Uint8Array>;
+
+/**
+ * Read the exact current lock bytes for a compare-and-swap update.
+ *
+ * `null` means no lock exists yet. The returned text is the only valid `expectedContents` for a
+ * later `writeTileflowIconsLockfile` call, so a concurrent writer can never be silently lost.
+ */
+declare function readTileflowIconsLockfileText(baseDirectory: string): Promise<string | null>;
+declare function readTileflowIconsLockfile(baseDirectory: string, sources?: readonly TileflowIconSource[]): Promise<TileflowIconsLockfileV1>;
+/** Compare-and-swap the whole lock. Never rewrite executable config or lose another writer's pin. */
+declare function writeTileflowIconsLockfile(baseDirectory: string, input: TileflowIconsLockfileV1, expectedContents: string | null): Promise<void>;
+
+type ComposeTileflowIconSourcesOptions = TileflowIconCacheOptions & {
+    cwd: string;
+    baseDirectory?: string;
+    /** Trusted caller-owned diagnostic prefix, such as `maps.main.icons`. */
+    configPath?: string;
+    lock?: unknown;
+    target?: TileflowIconCompilationTarget;
+};
+/** One declared contributor, retained even when later contributors shadow all of its exports. */
+type TileflowComposedIconContributor = {
+    /** Ordered declared entries, before later contributors replace any of them. */
+    entries: readonly TileflowIconDirectoryEntry[];
+    iconIds: readonly string[];
+    insideWorkingTree: boolean;
+    kind: 'local' | 'package';
+    label: string;
+} | {
+    iconIds: readonly string[];
+    kind: 'icon-set';
+    /** Canonical `@team/set` reference; the exact revision lives in the receipt. */
+    label: string;
+    packageId: string;
+    reference: string;
+    setId: string;
+    version: number;
+    versionId: string;
+};
+/** One effective icon after ordered last-wins replacement has completed. */
+type TileflowComposedIconWinner = {
+    contributor: number;
+    id: string;
+    identity: TileflowEffectiveIconSourceIdentity;
+    /** Present only for filesystem-backed winners; verified shared cells expose no original. */
+    source: TileflowIconDirectorySourceFile | null;
+};
+type TileflowComposedIconSources = {
+    package: CompiledTileflowIconPackage | null;
+    composition: TileflowIconCompositionV1 | null;
+    contributors: TileflowComposedIconContributor[];
+    sourceIdentities: TileflowEffectiveIconSourceIdentity[];
+    replacements: Array<{
+        id: string;
+        replaced: number;
+        winner: number;
+    }>;
+    /** Exact files whose contents select this composition, such as the icon lock. */
+    watchFiles: string[];
+    /** Local directories whose children can change the composition without a config edit. */
+    watchPaths: string[];
+    winners: TileflowComposedIconWinner[];
+};
+/** The single normal icon-preparation path for declared local, package and shared contributors. */
+declare function composeTileflowIconSources(input: readonly TileflowIconSource[], options: ComposeTileflowIconSourcesOptions): Promise<TileflowComposedIconSources>;
+
+type TileflowBuildAsset = {
+    contentType: string;
+    fileName: string;
+    source: string | Uint8Array;
+};
+/** Executable authoring input before local sources have been resolved into runtime URLs. */
+type TileflowSourceCatalog = TileflowBuildCatalog;
+declare const preparedTileflowBuildCatalog: unique symbol;
+/** A validated catalog paired with build-owned portable assets. */
+type PreparedTileflowBuildCatalog = TileflowBuildCatalog & {
+    readonly [preparedTileflowBuildCatalog]: true;
+};
+type PreparedTileflowCatalog = {
+    assets: TileflowBuildAsset[];
+    baseDirectory: string;
+    cwd: string;
+    mapAssets: Record<string, TileflowPreparedMapAssets>;
+    /** Ordered shared dependency receipts, present only for maps that declare an Icon Set. */
+    mapIconCompositions: Record<string, TileflowIconCompositionV1>;
+    mapIconSources: Record<string, readonly TileflowEffectiveIconSourceIdentity[]>;
+    /** The files of each map's own 3D models, for its revision. */
+    mapModelSources?: Record<string, readonly TileflowEffectiveModelSourceIdentity[]>;
+    project: PreparedTileflowBuildCatalog;
+    sourceProject: TileflowSourceCatalog;
+    /** Exact files whose contents select the composition, such as the icon lock. */
+    watchFiles: string[];
+    watchPaths: string[];
+};
+/**
+ * Explicit, trusted resolution settings for declared shared Icon Sets.
+ *
+ * These are supplied by the calling command or adapter. A lock file can never widen them, and no
+ * ambient process state selects a cache, an origin, or a transport.
+ */
+type TileflowIconResolutionOptions = TileflowIconCacheOptions;
+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 = {
+    appearances?: Record<string, TileflowIconAppearance>;
+    iconIds: readonly string[];
+    label: string;
+    mapName: string;
+    packageHash: string;
+};
+type CompileTileflowIconPackagesOptions = {
+    baseDirectory?: string;
+    cwd: string;
+    /** Trusted shared-set resolution settings; omitted means the default verified cache. */
+    icons?: TileflowIconResolutionOptions;
+    target: TileflowIconCompilationTarget;
+};
+type CompileTileflowIconPackagesResult = {
+    bindings: TileflowMapIconPackageBinding[];
+    /** Exact ordered dependency receipts, keyed by map, for maps that declare an Icon Set. */
+    compositions: Record<string, TileflowIconCompositionV1>;
+    packages: CompiledTileflowIconPackage[];
+    sourceIdentities: Record<string, readonly TileflowEffectiveIconSourceIdentity[]>;
+    /** Exact files whose contents select the composition, such as the icon lock. */
+    watchFiles: string[];
+    watchPaths: string[];
+};
+type InspectTileflowIconCatalogsOptions = {
+    baseDirectory?: string;
+    cwd: string;
+    icons?: TileflowIconResolutionOptions;
+    mapNames?: readonly string[];
+};
+type TileflowIconCatalogSourceFormat = 'jpeg' | 'png' | 'svg' | 'webp';
+type TileflowIconCatalogAtlasRectangle = {
+    height: number;
+    width: number;
+    x: number;
+    y: number;
+};
+type TileflowIconCatalogRenderedDensity = {
+    atlas: TileflowIconCatalogAtlasRectangle;
+    height: number;
+    pixelRatio: 1 | 2;
+    pixelSha256: string;
+    width: number;
+};
+/** One winning icon's origin: a repository/package original, or an exact shared revision cell. */
+type TileflowIconCatalogIconSource = {
+    byteLength: number;
+    contributor: number;
+    dimensions: {
+        height: number;
+        width: number;
+    } | null;
+    format: TileflowIconCatalogSourceFormat;
+    kind: 'file';
+    path: string;
+} | {
+    contributor: number;
+    kind: 'icon-set';
+    reference: string;
+    version: number;
+};
+type TileflowIconCatalogIcon = {
+    appearance?: TileflowIconAppearance;
+    layout?: TileflowIconLayoutMetadata;
+    id: string;
+    rendered: {
+        oneX: TileflowIconCatalogRenderedDensity;
+        twoX: TileflowIconCatalogRenderedDensity;
+    };
+    source: TileflowIconCatalogIconSource;
+};
+/** One declared contributor in authoring order, retained even when fully shadowed. */
+type TileflowIconCatalogContributor = {
+    iconIds: string[];
+    insideWorkingTree: boolean;
+    kind: 'local' | 'package';
+    label: string;
+} | {
+    iconIds: string[];
+    kind: 'icon-set';
+    label: string;
+    reference: string;
+    version: number;
+};
+type TileflowIconCatalog = {
+    compiledPackage: CompiledTileflowIconPackage;
+    composition: TileflowIconCompositionV1 | null;
+    contributors: TileflowIconCatalogContributor[];
+    icons: TileflowIconCatalogIcon[];
+    insideWorkingTree: boolean;
+    replacements: TileflowIconReplacement[];
+};
+type TileflowIconReplacement = {
+    id: string;
+    replaced: string;
+    winner: string;
+};
+type TileflowIconCatalogMap = {
+    name: string;
+    icons: {
+        composition: TileflowIconCompositionV1 | null;
+        contributors: TileflowIconCatalogContributor[];
+        iconIds: string[];
+        kind: 'sources';
+        label: string;
+        packageHash: string;
+    } | {
+        kind: 'none';
+    };
+};
+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[]);
+}
+type DecodedIconDimensions = {
+    height: number;
+    width: number;
+};
+declare const iconFileExtensions: Set<string>;
+declare function compileTileflowIconPackages(project: TileflowBuildCatalog, options: CompileTileflowIconPackagesOptions): Promise<CompileTileflowIconPackagesResult>;
+declare function inspectTileflowIconCatalogs(project: TileflowBuildCatalog, options: InspectTileflowIconCatalogsOptions): Promise<TileflowIconCatalogInspection>;
+declare function prepareTileflowCatalogIcons(project: TileflowBuildCatalog, options: {
+    assetBaseUrl: string;
+    baseDirectory?: string;
+    cwd: string;
+    icons?: TileflowIconResolutionOptions;
+}): Promise<PreparedTileflowCatalog>;
+/**
+ * Report the exact filesystem inputs that can change the composed sprite.
+ *
+ * The lock beside the selected config is one of them; a lock edit rebuilds from its new exact
+ * pins. Catalog heads are never polled, so a newly published revision changes nothing here.
+ */
+declare function getTileflowIconWatchPaths(project: TileflowBuildCatalog, cwd: string, baseDirectory?: string): Promise<string[]>;
+
+/** One declared icon file, including entries a later contributor eventually replaces. */
+type TileflowIconDirectoryEntry = {
+    byteLength: number;
+    format: TileflowIconCatalogSourceFormat;
+    id: string;
+    kind: 'icon' | 'pattern';
+    /** Authoring-relative display path. Absolute filesystem paths never leave this module. */
+    path: string;
+};
+/** The decoded original behind one effective local winner. */
+type TileflowIconDirectorySourceFile = TileflowIconDirectoryEntry & {
+    dimensions: DecodedIconDimensions;
+};
+type ReadTileflowIconDirectoryResult = {
+    containmentRoot: string;
+    entries: TileflowIconDirectoryEntry[];
+    iconIds: string[];
+    /** Authoring label: a config-relative directory or a safe `npm:<package>/<path>` descriptor. */
+    label: string;
+    realPath: string;
+    render: (ids: readonly string[]) => Promise<Array<{
+        icon: TileflowRenderedIcon;
+        identity: TileflowEffectiveIconSourceIdentity;
+        source: TileflowIconDirectorySourceFile;
+        sourceBytes: number;
+    }>>;
+    watchPath?: string;
+};
+/** A bounded local source snapshot used by the explicit shared-composition build port. */
+declare function readTileflowIconDirectory(source: TileflowIconDirectory, options: {
+    baseDirectory: string;
+    /** Trusted caller-owned diagnostic prefix, such as `maps.main.icons`. */
+    configPath?: string;
+    cwd: string;
+    /** Ordinal of this directory inside the declared contributor sequence. */
+    ordinal?: number;
+    target: TileflowIconCompilationTarget;
+}): Promise<ReadTileflowIconDirectoryResult>;
+
+export { readTileflowIconsLockfileText as $, TileflowIconCompilationError as A, type TileflowIconCompilationIssue as B, type CompileTileflowIconPackagesOptions as C, type TileflowIconCompilationTarget as D, type TileflowIconDirectoryEntry as E, type TileflowIconDirectorySourceFile as F, type TileflowIconReplacement as G, type TileflowMapIconPackageBinding as H, type InspectTileflowIconCatalogsOptions as I, type TileflowRenderedIcon as J, type TileflowRenderedIconCell as K, compileTileflowIconPackages as L, composeTileflowIconSources as M, getTileflowIconCacheDirectory as N, getTileflowIconWatchPaths as O, type PreparedTileflowBuildCatalog as P, iconFileExtensions as Q, type ReadTileflowIconDirectoryResult as R, inspectTileflowIconCatalogs as S, type TileflowBuildAsset as T, loadTileflowIconSetArtifact as U, type VerifiedTileflowIconArtifact as V, packTileflowRenderedIcons as W, prepareTileflowCatalogIcons as X, prepareTileflowMapTreeModels as Y, readTileflowIconDirectory as Z, readTileflowIconsLockfile as _, type TileflowIconResolutionOptions as a, renderTileflowIconAtlasPreview as a0, storeTileflowIconSetArtifact as a1, verifyTileflowIconArtifact as a2, writeTileflowIconsLockfile as a3, type TileflowSourceCatalog as b, type PreparedTileflowCatalog as c, type TileflowBuildingModelLevels as d, type TileflowLandmarkSource as e, encodeTileflowLandmarkRegion as f, prepareTileflowBuildingModel as g, type CompileTileflowIconPackagesResult as h, type CompiledTileflowIconPackage as i, type CompiledTileflowIconPackageFile as j, type ComposeTileflowIconSourcesOptions as k, type PreparedTileflowBuildingModel as l, type TileflowComposedIconContributor as m, type TileflowComposedIconSources as n, type TileflowComposedIconWinner as o, packageTileflowLandmarkTile as p, type TileflowIconCacheOptions as q, type TileflowIconCatalog as r, type TileflowIconCatalogAtlasRectangle as s, type TileflowIconCatalogContributor as t, type TileflowIconCatalogIcon as u, type TileflowIconCatalogIconSource as v, type TileflowIconCatalogInspection as w, type TileflowIconCatalogMap as x, type TileflowIconCatalogRenderedDensity as y, type TileflowIconCatalogSourceFormat as z };

package/dist/icons.d.ts

@@ -0,0 +1,3 @@
+import '@tileflow/core';
+import '@tileflow/core/build';
+export { C as CompileTileflowIconPackagesOptions, h as CompileTileflowIconPackagesResult, i as CompiledTileflowIconPackage, j as CompiledTileflowIconPackageFile, k as ComposeTileflowIconSourcesOptions, I as InspectTileflowIconCatalogsOptions, P as PreparedTileflowBuildCatalog, l as PreparedTileflowBuildingModel, c as PreparedTileflowCatalog, R as ReadTileflowIconDirectoryResult, T as TileflowBuildAsset, m as TileflowComposedIconContributor, n as TileflowComposedIconSources, o as TileflowComposedIconWinner, q as TileflowIconCacheOptions, r as TileflowIconCatalog, s as TileflowIconCatalogAtlasRectangle, t as TileflowIconCatalogContributor, u as TileflowIconCatalogIcon, v as TileflowIconCatalogIconSource, w as TileflowIconCatalogInspection, x as TileflowIconCatalogMap, y as TileflowIconCatalogRenderedDensity, z as TileflowIconCatalogSourceFormat, A as TileflowIconCompilationError, B as TileflowIconCompilationIssue, D as TileflowIconCompilationTarget, E as TileflowIconDirectoryEntry, F as TileflowIconDirectorySourceFile, G as TileflowIconReplacement, a as TileflowIconResolutionOptions, H as TileflowMapIconPackageBinding, J as TileflowRenderedIcon, K as TileflowRenderedIconCell, b as TileflowSourceCatalog, V as VerifiedTileflowIconArtifact, L as compileTileflowIconPackages, M as composeTileflowIconSources, N as getTileflowIconCacheDirectory, O as getTileflowIconWatchPaths, Q as iconFileExtensions, S as inspectTileflowIconCatalogs, U as loadTileflowIconSetArtifact, W as packTileflowRenderedIcons, X as prepareTileflowCatalogIcons, Y as prepareTileflowMapTreeModels, Z as readTileflowIconDirectory, _ as readTileflowIconsLockfile, $ as readTileflowIconsLockfileText, a0 as renderTileflowIconAtlasPreview, a1 as storeTileflowIconSetArtifact, a2 as verifyTileflowIconArtifact, a3 as writeTileflowIconsLockfile } from './icons-BIHpw5Zy.js';

package/dist/icons.js

@@ -0,0 +1,41 @@
+import {
+  TileflowIconCompilationError,
+  compileTileflowIconPackages,
+  composeTileflowIconSources,
+  getTileflowIconCacheDirectory,
+  getTileflowIconWatchPaths,
+  iconFileExtensions,
+  inspectTileflowIconCatalogs,
+  loadTileflowIconSetArtifact,
+  packTileflowRenderedIcons,
+  prepareTileflowCatalogIcons,
+  prepareTileflowMapTreeModels,
+  readTileflowIconDirectory,
+  readTileflowIconsLockfile,
+  readTileflowIconsLockfileText,
+  renderTileflowIconAtlasPreview,
+  storeTileflowIconSetArtifact,
+  verifyTileflowIconArtifact,
+  writeTileflowIconsLockfile
+} from "./chunk-C4VPHZ3F.js";
+import "./chunk-RTU7TD4M.js";
+export {
+  TileflowIconCompilationError,
+  compileTileflowIconPackages,
+  composeTileflowIconSources,
+  getTileflowIconCacheDirectory,
+  getTileflowIconWatchPaths,
+  iconFileExtensions,
+  inspectTileflowIconCatalogs,
+  loadTileflowIconSetArtifact,
+  packTileflowRenderedIcons,
+  prepareTileflowCatalogIcons,
+  prepareTileflowMapTreeModels,
+  readTileflowIconDirectory,
+  readTileflowIconsLockfile,
+  readTileflowIconsLockfileText,
+  renderTileflowIconAtlasPreview,
+  storeTileflowIconSetArtifact,
+  verifyTileflowIconArtifact,
+  writeTileflowIconsLockfile
+};

package/dist/inspect.d.ts

@@ -0,0 +1,149 @@
+import { TileflowThemeAuditDiagnostic, TileflowThemeColorScheme } from '@tileflow/core';
+import { LoadTileflowConfigOptions, LoadedTileflowConfig } from './config.js';
+import { TileflowCommandSummary, TileflowStructuredDiagnostic } from './validation.js';
+import { TileflowPreparedMapAssets, TileflowBuildCatalog } from '@tileflow/core/build';
+
+type TileflowFeatureInspectionOptions = {
+    apiBaseUrl?: string;
+    center: readonly [number, number];
+    fetch?: typeof fetch;
+    height?: number;
+    limit?: number;
+    properties?: readonly string[];
+    /** Build-owned assets required to compile the selected map exactly. */
+    preparedAssets?: TileflowPreparedMapAssets;
+    signal?: AbortSignal;
+    sourceLayers: readonly 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: TileflowBuildCatalog, mapName: string, input: TileflowFeatureInspectionOptions): Promise<TileflowFeatureInspection>;
+
+type TileflowConfigInspectionOptions = LoadTileflowConfigOptions & {
+    config?: string;
+    map?: string;
+};
+type TileflowMapLineageInspection = {
+    depth: number;
+    declaredPaths: string[];
+    id: string;
+    version: number;
+};
+type TileflowMapMergeProvenance = {
+    declared: boolean;
+    inherited: boolean;
+    operation: 'defined' | 'overridden';
+    path: string;
+    /** Stable root-to-leaf lineage depth; disambiguates repeated map ids. */
+    sourceDepth: number;
+    sourceMap: string;
+};
+type TileflowResolvedMapInspection = {
+    id: string;
+    lineage: TileflowMapLineageInspection[];
+    provenance: TileflowMapMergeProvenance[];
+    resolved: Record<string, unknown>;
+    themeContract: TileflowThemeContractInspection;
+};
+type TileflowThemeDifferenceInspection = {
+    from: unknown;
+    path: string;
+    to: unknown;
+};
+type TileflowThemeInspection = {
+    colorScheme: TileflowThemeColorScheme;
+    differencesFromDefault: TileflowThemeDifferenceInspection[];
+    id: string;
+    isDefault: boolean;
+    lighting: Record<string, unknown>;
+    name: string;
+    systemFor: TileflowThemeColorScheme[];
+    tokens: {
+        color: Record<string, string>;
+        font: Record<string, string>;
+        image: Record<string, string>;
+        number: Record<string, number>;
+    };
+    typography: Record<string, unknown>;
+    version: number;
+};
+type TileflowThemeContractInspection = {
+    audit: TileflowThemeAuditDiagnostic[];
+    defaultTheme: string;
+    systemThemes?: {
+        dark: string;
+        light: string;
+    };
+    themes: Record<string, TileflowThemeInspection>;
+    tokenSchema: {
+        color: string[];
+        font: string[];
+        image: string[];
+        number: string[];
+    };
+};
+type TileflowConfigInspection = TileflowCommandSummary & {
+    command: 'inspect';
+    ok: true;
+    maps: TileflowResolvedMapInspection[];
+    diagnostics: TileflowStructuredDiagnostic[];
+};
+/** Resolve a config once and expose only deterministic, secret-free authoring information. */
+declare function inspectTileflowConfig(options?: TileflowConfigInspectionOptions): Promise<TileflowConfigInspection>;
+declare function inspectLoadedTileflowConfig(loaded: LoadedTileflowConfig, options: {
+    cwd: string;
+    map?: string;
+}): TileflowConfigInspection;
+declare class TileflowConfigInspectionError extends Error {
+    readonly code: string;
+    readonly phase: "config-inspection";
+    readonly issues: Array<{
+        code: string;
+        message: string;
+        path: string;
+        phase: string;
+    }>;
+    constructor(code: string, message: string, path: string);
+}
+/** Sanitize a deterministic JSON-like authoring value for machine-facing CLI output. */
+declare function sanitizeTileflowInspectableValue(value: unknown, cwd: string): unknown;
+
+export { type TileflowConfigInspection, TileflowConfigInspectionError, type TileflowConfigInspectionOptions, type TileflowFeatureInspection, type TileflowFeatureInspectionOptions, type TileflowInspectedFeature, type TileflowInspectedProperty, type TileflowMapLineageInspection, type TileflowMapMergeProvenance, type TileflowResolvedMapInspection, type TileflowThemeContractInspection, type TileflowThemeDifferenceInspection, type TileflowThemeInspection, inspectLoadedTileflowConfig, inspectTileflowConfig, inspectTileflowFeatures, sanitizeTileflowInspectableValue };