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

package/README.md

@@ -45,6 +45,22 @@ edits retain the last good snapshot, and caller-supplied output directories can
 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.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { IncomingMessage, ServerResponse } from 'node:http';
-import { TileflowIconPackageFileName, TileflowIconPackageManifest, TileflowProjectConfig, MapLibreStyle, TileflowManifest, ValidationMessage, TileflowStyleOptions } from '@tileflow/core';
+import { TileflowIconPackageFileName, TileflowIconPackageManifest, TileflowProjectConfig, MapLibreStyle, NormalizedTileflowCaptureScene, TileflowManifest, ValidationMessage, TileflowStyleOptions } from '@tileflow/core';
 
 declare const tileflowArtifactSessionSchemaVersion: 1;
 type TileflowArtifactDiagnostic = {
@@ -244,11 +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;
@@ -278,6 +294,7 @@ 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;
@@ -302,4 +319,4 @@ declare function createTileflowArtifactStatus(state: TileflowArtifactSessionStat
 };
 declare function normalizeTileflowBasePath(value?: string): string;
 
-export { type CompileTileflowIconPackagesResult, type CompiledTileflowIconPackage, type CompiledTileflowIconPackageFile, type InspectTileflowIconCatalogsOptions, type LoadTileflowConfigOptions, type PreparedTileflowProject, 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, 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, tileflowArtifactSessionSchemaVersion, validateTileflowStyle, 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 };

package/dist/index.js

@@ -8,6 +8,7 @@ import {
   compareCodeUnits as compareCodeUnits3,
   createManifest,
   createStyleFromProject as createStyleFromProject2,
+  normalizeTileflowCaptureScene,
   validateConfig
 } from "@tileflow/core";
 
@@ -1840,6 +1841,13 @@ var defaultTileflowApiUrl = "https://api.tileflow.dev";
 var defaultTileflowConfigPath = "tileflow.config.ts";
 var defaultTileflowManifestPath = "public/tileflow/manifest.json";
 var defaultTileflowTileset = "world";
+var TileflowPreviewSelectionError = class extends Error {
+  code = "PREVIEW_SELECTION_INVALID";
+  constructor(message) {
+    super(message);
+    this.name = "TileflowPreviewSelectionError";
+  }
+};
 var TileflowValidationError = class extends Error {
   code = "CONFIG_INVALID";
   messages;
@@ -1903,6 +1911,52 @@ function getFirstTileflowMapName(project) {
   }
   return mapName;
 }
+function resolveTileflowPreview(project, selection = {}) {
+  if (selection.map !== void 0 && selection.scene !== void 0) {
+    throw new TileflowPreviewSelectionError(
+      "Choose either a Tileflow preview map or scene, not both."
+    );
+  }
+  if (selection.scene !== void 0) {
+    const scene = Object.hasOwn(project.scenes ?? {}, selection.scene) ? project.scenes?.[selection.scene] : void 0;
+    if (!scene) {
+      throw new TileflowPreviewSelectionError(`Unknown Tileflow scene: ${selection.scene}`);
+    }
+    const normalized = normalizeTileflowCaptureScene(scene);
+    if (normalized.target.kind === "application") {
+      throw new TileflowPreviewSelectionError(
+        `Tileflow scene "${selection.scene}" targets an application. Preview it through the application's development server.`
+      );
+    }
+    if (!Object.hasOwn(project.maps, normalized.map)) {
+      throw new TileflowPreviewSelectionError(
+        `Tileflow scene "${selection.scene}" references an unknown map: ${normalized.map}`
+      );
+    }
+    return {
+      camera: normalized.camera,
+      label: `${normalized.map} / ${selection.scene} \xB7 ${normalized.viewport.width}\xD7${normalized.viewport.height}`,
+      mapName: normalized.map,
+      viewport: normalized.viewport
+    };
+  }
+  const mapName = selection.map ?? getFirstTileflowMapName(project);
+  const map = Object.hasOwn(project.maps, mapName) ? project.maps[mapName] : void 0;
+  if (!map) {
+    throw new TileflowPreviewSelectionError(`Unknown Tileflow map: ${mapName}`);
+  }
+  return {
+    camera: {
+      type: "center",
+      center: map.view?.center ? [map.view.center[0], map.view.center[1]] : [0, 0],
+      zoom: map.view?.zoom ?? 0,
+      bearing: map.view?.bearing ?? 0,
+      pitch: 0
+    },
+    label: mapName,
+    mapName
+  };
+}
 function getTileflowStyleMapName(path) {
   const fileName = path.split("/").pop() ?? "";
   return fileName.replace(/\.json$/, "");
@@ -2092,8 +2146,8 @@ function createTileflowDevRequestHandler(options = {}) {
         return jsonResponse(createTileflowArtifactStatus(state));
       }
       if (path === "/" || path === "") {
-        const mapName = artifacts ? getFirstTileflowMapName(artifacts.project) : void 0;
-        return htmlResponse(previewHtml(mapName, basePath, state));
+        const preview = artifacts ? resolveTileflowPreview(artifacts.project, { map: options.map, scene: options.scene }) : void 0;
+        return htmlResponse(previewHtml(preview, basePath, state));
       }
       if (!artifacts) return unavailableArtifactsResponse(state);
       if (path === "/manifest.json") {
@@ -2199,6 +2253,9 @@ function stripTileflowBasePath(pathname, basePath) {
   return null;
 }
 function tileflowErrorResponse(error) {
+  if (error instanceof TileflowPreviewSelectionError) {
+    return jsonResponse({ error: error.message }, 400);
+  }
   if (error instanceof TileflowStyleValidationError) {
     return jsonResponse(
       {
@@ -2263,9 +2320,23 @@ function resolveAssetBaseUrl(options) {
 function isRelativePublicUrl(value) {
   return !(value.startsWith("http://") || value.startsWith("https://") || value.startsWith("/") || value.startsWith("data:"));
 }
-function previewHtml(mapName, basePath, state) {
-  const styleUrl = mapName ? `${basePath}/styles/${mapName}.json` : void 0;
+function previewHtml(preview, basePath, state) {
+  const styleUrl = preview ? `${basePath}/styles/${preview.mapName}.json` : void 0;
   const initialStatus = createTileflowArtifactStatus(state);
+  const mapOptions = preview ? previewMapOptions(preview) : void 0;
+  const viewportCss = preview?.viewport ? `
+      html, body { min-height: 100%; margin: 0; }
+      body {
+        display: grid;
+        place-items: center;
+        overflow: auto;
+        background: #E8E5DE;
+      }
+      #map {
+        width: ${preview.viewport.width}px;
+        height: ${preview.viewport.height}px;
+        box-shadow: 0 24px 80px rgba(37, 34, 29, 0.18);
+      }` : "html, body, #map { height: 100%; margin: 0; }";
   return `<!doctype html>
 <html lang="en">
   <head>
@@ -2274,7 +2345,7 @@ function previewHtml(mapName, basePath, state) {
     <title>Tileflow Preview</title>
     <link rel="stylesheet" href="${basePath}/__runtime/maplibre-gl.css" />
     <style>
-      html, body, #map { height: 100%; margin: 0; }
+      ${viewportCss}
       body { font-family: ui-sans-serif, system-ui, sans-serif; }
       .badge {
         position: fixed;
@@ -2315,20 +2386,21 @@ function previewHtml(mapName, basePath, state) {
       const initialGeneration = initialStatus.generation;
       const badge = document.getElementById("badge");
       const status = document.getElementById("status");
+      const previewLabel = ${JSON.stringify(preview?.label)};
       const styleUrl = ${JSON.stringify(styleUrl)};
+      const previewMapOptions = ${JSON.stringify(mapOptions)};
 
       if (styleUrl) {
         const map = new maplibregl.Map({
           container: "map",
           style: styleUrl,
-          center: [-3.7038, 40.4168],
-          zoom: 12
+          ...previewMapOptions
         });
         map.addControl(new maplibregl.NavigationControl(), "top-right");
       }
 
       function applyStatus(next) {
-        badge.textContent = "Tileflow preview \xB7 " + next.status;
+        badge.textContent = ["Tileflow preview", previewLabel, next.status].filter(Boolean).join(" \xB7 ");
         if (next.status === "invalid") {
           const diagnostics = next.diagnostics || [];
           status.textContent = diagnostics.map((item) =>
@@ -2352,6 +2424,26 @@ function previewHtml(mapName, basePath, state) {
   </body>
 </html>`;
 }
+function previewMapOptions(preview) {
+  if (preview.camera.type === "center") {
+    return {
+      bearing: preview.camera.bearing,
+      center: preview.camera.center,
+      pitch: preview.camera.pitch,
+      zoom: preview.camera.zoom
+    };
+  }
+  const [west, south, east, north] = preview.camera.bounds;
+  return {
+    bearing: preview.camera.bearing,
+    bounds: [
+      [west, south],
+      [east, north]
+    ],
+    fitBoundsOptions: { padding: preview.camera.padding },
+    pitch: preview.camera.pitch
+  };
+}
 var localRequire = createRequire(import.meta.url);
 var localMapLibreJavaScript;
 var localMapLibreStylesheet;
@@ -2398,6 +2490,7 @@ function isPathWithin(root, candidate) {
 }
 export {
   TileflowIconCompilationError,
+  TileflowPreviewSelectionError,
   TileflowStyleValidationError,
   TileflowValidationError,
   asTileflowProjectConfig,
@@ -2432,6 +2525,7 @@ export {
   loadValidTileflowConfig,
   normalizeTileflowBasePath,
   prepareTileflowProjectIcons,
+  resolveTileflowPreview,
   tileflowArtifactSessionSchemaVersion,
   validateTileflowStyle,
   writeTileflowBuildArtifacts,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/dev",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.17",
   "description": "Node development utilities for Tileflow configs and builds.",
   "type": "module",
   "sideEffects": false,
@@ -38,12 +38,12 @@
   "dependencies": {
     "@mapbox/vector-tile": "2.0.5",
     "@maplibre/maplibre-gl-style-spec": "24.8.5",
+    "@tileflow/core": ">=0.1.0-alpha.17 <0.1.0-beta.0",
     "chokidar": "4.0.3",
     "jiti": "^2.7.0",
     "maplibre-gl": "5.24.0",
     "pbf": "4.0.2",
-    "saxes": "6.0.0",
-    "@tileflow/core": "0.1.0-alpha.16"
+    "saxes": "6.0.0"
   },
   "optionalDependencies": {
     "sharp": "0.35.3"