@tileflow/dev 0.1.0-alpha.3 → 0.1.0-alpha.30

package/dist/tilesets.d.ts

@@ -0,0 +1,89 @@
+declare const inspectionLimits: Readonly<{
+    maxBytes: 24000000;
+    maxDistinctValuesPerField: 256;
+    maxFeatures: 20000;
+    maxIncludedValueFields: 32;
+    maxTiles: 8;
+    maxValueLength: 256;
+    maxValuesPerField: 16;
+}>;
+type TileCoordinate = Readonly<{
+    x: number;
+    y: number;
+    z: number;
+}>;
+type FieldType = 'Boolean' | 'Number' | 'String';
+type FieldValue = boolean | number | string;
+type TileflowTilesetInspectionWarning = Readonly<{
+    code: string;
+    message: string;
+    path: string;
+}>;
+type TileflowTilesetInspectionV1 = Readonly<{
+    schemaVersion: 1;
+    contract: Readonly<{
+        authority: 'pmtiles-header-and-tilejson-v1';
+        attribution?: string;
+        bounds: readonly [number, number, number, number];
+        center: readonly [number, number, number];
+        counts: Readonly<{
+            addressedTiles: number;
+            declaredTileContents: number | null;
+            tileEntries: number;
+        }>;
+        maxzoom: number;
+        minzoom: number;
+        sourceLayersDeclared: boolean;
+        sourceLayers: readonly Readonly<{
+            fieldsDeclared: boolean;
+            fields: readonly Readonly<{
+                name: string;
+                type?: FieldType;
+            }>[];
+            id: string;
+            maxzoom?: number;
+            minzoom?: number;
+        }>[];
+        tileType: 'avif' | 'jpeg' | 'mlt' | 'mvt' | 'png' | 'webp';
+    }>;
+    observation?: Readonly<{
+        authority: 'bounded-mvt-sample-v1';
+        featuresRead: number;
+        includedValueFields: readonly string[];
+        limits: typeof inspectionLimits;
+        sourceLayers: readonly Readonly<{
+            featuresRead: number;
+            fields: readonly Readonly<{
+                distinctValuesObserved: number;
+                distinctValuesTruncated: boolean;
+                featuresMissing: number;
+                featuresPresent: number;
+                name: string;
+                numericRange?: Readonly<{
+                    max: number;
+                    min: number;
+                }>;
+                observedValues?: readonly Readonly<{
+                    count: number;
+                    value: FieldValue;
+                }>[];
+                observedValuesTruncated?: boolean;
+                types: readonly FieldType[];
+            }>[];
+            geometryTypes: readonly string[];
+            id: string;
+        }>[];
+        tiles: readonly TileCoordinate[];
+        tilesRead: number;
+        truncated: boolean;
+    }>;
+    warnings: readonly TileflowTilesetInspectionWarning[];
+}>;
+declare function inspectTileflowPmtiles(archivePath: string, options?: {
+    includeValues?: readonly string[];
+    maximumDirectoryDepth?: number;
+    sample?: boolean;
+    signal?: AbortSignal;
+}): Promise<TileflowTilesetInspectionV1>;
+
+export { type TileflowTilesetInspectionV1, type TileflowTilesetInspectionWarning, inspectTileflowPmtiles };

package/dist/tilesets.js

@@ -0,0 +1,6 @@
+import {
+  inspectTileflowPmtiles
+} from "./chunk-ONYQNLNA.js";
+export {
+  inspectTileflowPmtiles
+};

package/dist/validation.d.ts

@@ -0,0 +1,65 @@
+import { MapLibreStyle } from '@tileflow/core';
+
+declare function sanitizeDiagnosticSecrets(value: string): string;
+
+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 tileflowCommandDocumentSchemaVersion: 1;
+type TileflowDiagnosticSeverity = 'error' | 'info' | 'warning';
+/** Stable, bounded diagnostic contract intended for tools and coding agents. */
+type TileflowStructuredDiagnostic = {
+    phase: string;
+    code: string;
+    /** Semantic compiler domain; a Core diagnostic's owning-module `owner` is reported here. */
+    domain?: string;
+    path: string;
+    /** Semantic compiler target, when the diagnostic applies to one render contribution. */
+    target?: string;
+    severity: TileflowDiagnosticSeverity;
+    message: string;
+    suggestion: string;
+    renderer?: 'native';
+    profile?: 'native-v1';
+};
+type TileflowCommandSummary = TileflowStructuredDiagnostic & {
+    schemaVersion: typeof tileflowCommandDocumentSchemaVersion;
+    command: string;
+    ok: boolean;
+};
+type TileflowCommandFailureDocument = TileflowCommandSummary & {
+    ok: false;
+    diagnostics: TileflowStructuredDiagnostic[];
+};
+type TileflowDiagnosticDefaults = {
+    code: string;
+    phase: string;
+    severity?: TileflowDiagnosticSeverity;
+};
+declare function createTileflowCommandSummary(input: {
+    code: string;
+    command: string;
+    message: string;
+    ok: boolean;
+    path?: string;
+    phase: string;
+    severity: TileflowDiagnosticSeverity;
+    suggestion: string;
+}): TileflowCommandSummary;
+/** Convert arbitrary SDK failures to sorted diagnostics without leaking paths, URLs, or secrets. */
+declare function createTileflowStructuredDiagnostics(error: unknown, cwd: string, defaults: TileflowDiagnosticDefaults): TileflowStructuredDiagnostic[];
+declare function createTileflowCommandFailureDocument(command: string, error: unknown, cwd: string, defaults: TileflowDiagnosticDefaults): TileflowCommandFailureDocument;
+declare function serializeTileflowCommandDocument(value: unknown): string;
+
+export { type TileflowCommandFailureDocument, type TileflowCommandSummary, type TileflowDiagnosticSeverity, type TileflowStructuredDiagnostic, TileflowStyleValidationError, type TileflowStyleValidationIssue, assertValidTileflowStyle, createTileflowCommandFailureDocument, createTileflowCommandSummary, createTileflowStructuredDiagnostics, sanitizeDiagnosticSecrets, serializeTileflowCommandDocument, tileflowCommandDocumentSchemaVersion, validateTileflowStyle };

package/dist/validation.js

@@ -0,0 +1,24 @@
+import {
+  createTileflowCommandFailureDocument,
+  createTileflowCommandSummary,
+  createTileflowStructuredDiagnostics,
+  serializeTileflowCommandDocument,
+  tileflowCommandDocumentSchemaVersion
+} from "./chunk-XHJBCVBB.js";
+import {
+  TileflowStyleValidationError,
+  assertValidTileflowStyle,
+  sanitizeDiagnosticSecrets,
+  validateTileflowStyle
+} from "./chunk-KDFTE4Q5.js";
+export {
+  TileflowStyleValidationError,
+  assertValidTileflowStyle,
+  createTileflowCommandFailureDocument,
+  createTileflowCommandSummary,
+  createTileflowStructuredDiagnostics,
+  sanitizeDiagnosticSecrets,
+  serializeTileflowCommandDocument,
+  tileflowCommandDocumentSchemaVersion,
+  validateTileflowStyle
+};

package/docs/artifact-lifecycle.md

@@ -0,0 +1,152 @@
+# Artifact lifecycle
+
+Start with the [@tileflow/dev guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/README.md) for installation and a complete first example.
+
+Node utilities used by the Tileflow CLI and build integrations.
+
+Most apps should use `tileflow`, `@tileflow/vite`, or `@tileflow/next` directly. Use this
+package when you are building a custom dev server, bundler plugin, or deployment adapter that needs
+to load and compile the single map exported by `tileflow.config.ts`.
+
+```ts
+import {createTileflowBuildArtifacts} from '@tileflow/dev/artifacts';
+
+const artifacts = await createTileflowBuildArtifacts({
+  config: 'tileflow.config.ts',
+});
+
+try {
+  // Serve, capture, or write this exact generation.
+} finally {
+  await artifacts.dispose?.();
+}
+```
+
+The integration surfaces are deliberately split: use `@tileflow/dev/artifacts` for source
+preparation and production outputs, `@tileflow/dev/server` for HTTP development handling,
+`@tileflow/dev/icons` for icon compilation, `@tileflow/dev/inspect` for safe resolved-config and
+bounded feature inspection, `@tileflow/dev/validation` for structured diagnostics, and
+`@tileflow/dev/preview` only for the local preview contract. The package has no root entry point.
+
+Artifact construction is an explicit `source map → resolved map → prepared map → ArtifactPlan`
+pipeline. Map inheritance resolves before its ordered local/package icon and font directories are
+prepared, and before the result reaches the core style compiler. The Node layer may normalize
+the map into an internal build catalog, but that catalog is orchestration state rather than another
+public authoring model. The plan exposes its complete files and observed input graph, so build
+adapters emit and watch the same generation instead of reconstructing either list themselves. Production manifests
+point to content-addressed `generations/<sha256>/...` theme styles and sprites; those immutable files are
+installed before the manifest pointer changes. Stable style paths are
+`styles/<map>/<theme>.json`; every manifest lookup resolves a concrete theme. The disk writer also stages the complete plan,
+records a managed-file inventory, rolls back caught filesystem failures, and removes only stale
+files named by its previous valid inventory. Stable `styles/` and `icons/` paths remain available,
+but generation-consistent consumers resolve maps through `manifest.json`.
+
+A local `hostedTileset()` path remains user-owned input. Dev performs bounded header, root-directory,
+and metadata checks, then creates an opaque immutable snapshot under
+`.tileflow/cache/pmtiles-snapshots/v1/`, using copy-on-write cloning when available and a safe copy
+otherwise. It does not hash the complete archive or traverse every leaf directory. Dev and Capture
+read only that snapshot. The current generation and already-started acquisitions retain references;
+a replaced generation accepts no new acquisitions and is collected after its last acquisition.
+The Style-facing path remains `tilesets/<logical-id>.pmtiles` across generations; physical snapshot
+identity stays out of Style JSON. Standalone Capture retains one generation for the complete render.
+Application Capture delegates PMTiles reads to the application's development server, where each
+range request retains its generation until that response is prepared; it does not lease one
+generation for the complete capture. Strong generation ETags make a cached PMTiles read restart if
+current changes between its ranges. Invalid edits keep the prior valid generation.
+
+Production writers reject unresolved local PMTiles instead of copying, content-addressing,
+deduplicating, retaining, or publishing them. Production data therefore requires an explicit
+`tileset publish` operation or an application-owned PMTiles location. Managed publication owns its
+separate exhaustive validation and version lifecycle. Startup removes snapshot generations owned
+by dead processes, and symlinked snapshot-store boundaries are rejected.
+
+Every plan also emits canonical `build-manifest.json` (schema version 1). For each map it records
+the leaf `mapVersion`, resolved lineage, effective icon/font source identities, semantic compiler ABI, and
+one entry per concrete theme with `colorScheme`, identity, inferred legacy `dataRequirements`,
+multi-source `sourceRequirements`, and `styleSha256`. The multi-source contract records each
+referenced vector source independently and records raster DEM source ID, encoding, and tile size;
+it therefore distinguishes Bathymetry vector bands from optional relief without inventing vector
+fields. `mapRevisionSha256` identifies the effective cartographic definition after `extends`;
+`assetSetSha256` for that map's generated runtime resources. Data requirements are derived from the
+final Style layers and fields rather than copied from a manually maintained allowlist, so disabled
+or overridden modules do not claim data they no longer use. Maps use the single implicit semantic
+compiler; its ABI remains a separate `semanticCompiler: {name, version}` build-manifest axis.
+
+The map revision is versioned and domain-separated. It contains the resolved cartographic design,
+semantic language version, effective public module/render-stack design, and effective icon/font
+identities. Map `id`, `name`, editorial `mapVersion`, default `view`, capture `scenes`, package
+SemVer, compiler ABI, local paths, timestamps, generated sprite/font output, and a
+concrete resolution of a floating World selector are deliberately outside it. Changing a shadowed
+ancestor does not change the revision; changing an effective cartographic override or source asset
+does. Lineage and the leaf `mapVersion` remain beside the hash for traceability, and Style JSON owns
+its compiled-output identity. Hosted browser policy is managed outside repository artifacts. The
+top-level `provenance` block records the exact participating Tileflow package versions and the
+nearest package-manager lockfile's format and content hash, without embedding its local path;
+provenance remains outside every map revision. The same portable block is available to Hosted
+adapters through
+`createTileflowBuildProvenance(cwd)`. The dev server exposes the complete document at
+`/build-manifest.json`.
+
+`createTileflowStyle`, `createTileflowStyles`, and artifact construction all enforce the same
+recursive JSON-value invariant and MapLibre style-spec semantics without fetching remote resources.
+The family API returns `styles[map][theme]`; it never flattens a default theme into a map alias.
+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/artifacts';
+
+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();
+```
+
+`getState()` and `getLastGoodArtifacts()` are borrowed synchronous views. Before starting async
+work, call `session.acquireArtifacts(generation?)` and release the returned acquisition in `finally`.
+A replacement stops new acquisitions of the old generation and deletes its snapshot after the last
+release. `close()` waits for outstanding acquisitions.
+
+The bounded watcher follows the config, transitive local TypeScript/JavaScript/JSON imports, and
+effective local icon/font directory 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 preview`, `capture --watch`, and
+framework adapters use this shared status
+vocabulary. The built-in preview reloads after its live event stream reconnects following a server
+restart, even when the replacement process begins again at generation 1.
+
+Custom preview servers use the exported map or one of its standalone scenes:
+
+```ts
+import {createTileflowDevRequestHandler} from '@tileflow/dev/server';
+
+const fetch = createTileflowDevRequestHandler({
+  config: 'tileflow.config.ts',
+  scene: 'madrid-mobile',
+});
+
+// On server shutdown:
+await fetch.close();
+```
+
+The handler does not close a caller-owned session.
+
+Map preview uses the exported map's `view` and accepts one concrete `theme`; scene preview uses its
+committed concrete theme, camera, and CSS viewport metadata from that same map. A scene does not
+repeat the map ID because its owner is implicit.
+`resolveTileflowPreview()` exposes the validated selection for custom integrations.
+Application-target scenes remain the responsibility of the application's development server. The
+built-in preview records longitude, latitude, zoom, bearing, and pitch in the current URL, so browser
+refreshes and config-triggered reloads return to the same view. Removing those query parameters
+restores the configured camera.

package/docs/bounded-pmtiles-resource-inspection.md

@@ -0,0 +1,21 @@
+# Bounded PMTiles resource inspection
+
+Start with the [@tileflow/dev guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/README.md) for installation and a complete first example.
+
+Node tooling can inspect one local PMTiles archive without reading it completely:
+
+```ts
+import {inspectTileflowPmtiles} from '@tileflow/dev/tilesets';
+
+const inspection = await inspectTileflowPmtiles('./data/stores.pmtiles', {
+  includeValues: ['category', 'status'],
+});
+```
+
+Inspection schema 1 separates the authoritative PMTiles header and TileJSON `vector_layers` metadata
+from deterministic bounded MVT observations. Each sampled field reports present/missing feature
+counts, observed primitive types, capped distinct-value cardinality, numeric min/max, and explicit
+truncation. Values are returned only for requested portable field names, with at most 32 requested
+fields, 16 values per field, and 256 characters per string. Sampling reads at most eight tiles,
+20,000 features, or 24 MB of tile data; `sample: false` returns only authoritative metadata and does
+not accept `includeValues`.

package/docs/bounded-vector-feature-inspection.md

@@ -0,0 +1,100 @@
+# Bounded vector-feature inspection
+
+Start with the [@tileflow/dev guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/README.md) for installation and a complete first example.
+
+Custom Node tooling can inspect only the features visible near a configured camera without opening
+a browser:
+
+```ts
+import {inspectTileflowFeatures} from '@tileflow/dev/inspect';
+
+const internalCatalog = artifacts.project;
+const inspection = await inspectTileflowFeatures(internalCatalog, 'madrid', {
+  center: [-3.6927512, 40.4086555],
+  zoom: 16,
+  sourceLayers: ['poi'],
+  properties: ['name', 'category', 'type', 'icon', 'filter_rank', 'size_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/icons';
+
+const internalCatalog = artifacts.project;
+const result = await compileTileflowIconPackages(internalCatalog, {
+  cwd: process.cwd(),
+  target: 'hosted',
+});
+```
+
+Streets declares `[streetsIcons]` and keeps light/dark image-token targets in that one closure.
+Baedeker, Cívica, Ferraris, Härad, Siegfried, Soundings, and Blueprint declare only
+`[baedekerIcons]`, `[civicaIcons]`, `[ferrarisIcons]`, `[haradIcons]`, `[siegfriedIcons]`,
+`[soundingsIcons]`, and `[blueprintIcons]`, respectively. No official root composes another map's assets even though all
+use the semantic compiler ABI. Baedeker's directory contains eight original travel-atlas patterns;
+its browser-derived Mapterhorn contours use runtime terrain tiles and are not part of the icon
+package. Härad's directory contains nine original Tileflow patterns inspired by Lantmäteriet's CC0
+Häradsekonomiska kartan series from 1859–1934. Soundings owns ten original nautical symbols and
+patterns. Blueprint owns four technical blueprint patterns and one schematic POI node; its
+unbundled Mapterhorn contours remain runtime terrain, and its text uses the canonical Noto Sans
+glyph provider. An application map may inherit a root's exact array, replace it, clear it with `[]`,
+or compose it explicitly with a spread.
+`modules.poi.icons: false` or a disabled POI module suppresses POI icon layers without moving asset
+ownership into dev. POI density is the numeric producer threshold 1–5; it is not an asset-provider
+preset.
+
+The hosted target enforces repository containment, portable icon IDs, safe SVG
+references, deterministic ordering, and the public package limits. Package-owned directories are
+trusted only inside their declared owning package and are exempt from config working-tree
+containment. It returns deduplicated generated files plus a canonical manifest/content hash. Upload
+only those generated files: source icons and absolute paths remain local.
+
+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/icons';
+
+const internalCatalog = artifacts.project;
+const inspection = await inspectTileflowIconCatalogs(internalCatalog, {
+  cwd: process.cwd(),
+  mapNames: ['madrid'],
+});
+```
+
+The result keeps one catalog per distinct ordered directory composition, the exact winning source
+for every final ID, explicit same-ID replacements, config-relative source metadata, exact atlas rectangles,
+both manifest pixel digests, and the shared compiled package. `icons: []` is represented as an
+absent catalog. 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. Styling primitives live in
+`@tileflow/core`, official maps and their source assets live in `@tileflow/maps`, and React
+rendering lives in `@tileflow/react`.
+
+Docs: https://tileflow.dev/docs