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

package/README.md

@@ -45,6 +45,24 @@ 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. The built-in preview records longitude, latitude, zoom, bearing,
+and pitch in the current URL after the camera moves, so browser refreshes and config-triggered
+reloads return to the same view. Removing those query parameters restores the configured camera.
+
 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.
@@ -86,8 +104,14 @@ const result = await compileTileflowIconPackages(project, {
 });
 ```
 
+When a Streets map does not select a local or external icon set, the pipeline compiles the built-in
+`tileflow-streets` POI catalog and merges any mapping-only overrides on top of its semantic mapping.
+`modules.poi.icons: false`, a disabled POI module, or the `none` POI preset suppresses that implicit
+package. An explicit local source or hosted sprite always replaces it.
+
 The hosted target enforces repository containment, portable icon IDs, safe SVG
-references, deterministic ordering, and the public package limits. It returns
+references, deterministic ordering, and the public package limits. The package-owned Streets
+catalog is trusted input and is the only source exempt from project-root containment. 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.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,11 @@
+# Third-party notices
+
+## Google Places icons
+
+The glyph artwork in `assets/streets-poi` is adapted from Google Places icons published in the
+[Google Places API documentation](https://developers.google.com/maps/documentation/places/web-service/icons).
+Copyright Google LLC. The documentation content is licensed under the
+[Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/).
+
+Tileflow modifies the source artwork by resizing and recoloring the glyphs, then composing them
+inside circular category markers with a white rim and shadow.

package/assets/streets-poi/cafe.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <title>Cafe</title>
+  <circle cx="12" cy="13" r="10.5" fill="#44515E" opacity=".08"/>
+  <circle cx="12" cy="12.5" r="10" fill="#44515E" opacity=".22"/>
+  <circle cx="12" cy="11" r="10" fill="#FFFFFF"/>
+  <circle cx="12" cy="11" r="8.25" fill="#FF9E67"/>
+  <svg x="6.75" y="7" width="10.5" height="7.875" viewBox="0 0 12 9" fill="#FFFFFF">
+    <path transform="translate(-5 -7)" fill-rule="evenodd" d="M13.4656593,7 L15.1589761,7 C15.6924964,7 16.125,7.43246448 16.125,7.96611494 L16.125,9.90201693 C16.125,10.4355875 15.6906762,10.8681319 15.1589761,10.8681319 L13.7074176,10.8681319 L11.8942308,13.043956 L8.0260989,13.043956 L6.09203297,10.8681319 L5.125,7 L13.4656593,7 Z M5.48763736,14.2527473 L15.157967,14.2527473 L15.157967,15.7032967 L5.48763736,15.7032967 Z M13.7074176,7.96703297 L15.157967,7.96703297 L15.157967,9.9010989 L13.7074176,9.9010989 Z"/>
+  </svg>
+</svg>

package/assets/streets-poi/hospital.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <title>Hospital</title>
+  <circle cx="12" cy="13" r="10.5" fill="#44515E" opacity=".08"/>
+  <circle cx="12" cy="12.5" r="10" fill="#44515E" opacity=".22"/>
+  <circle cx="12" cy="11" r="10" fill="#FFFFFF"/>
+  <circle cx="12" cy="11" r="8.25" fill="#F88181"/>
+  <svg x="8.5" y="6" width="7" height="10" viewBox="0 0 7 10" fill="#FFFFFF">
+    <path transform="translate(-7 -5)" fill-rule="evenodd" d="M8.55555556,14.8333333 L7,14.8333333 L7,5.5 L8.55555556,5.5 L8.55555556,9.38888889 L12.4444444,9.38888889 L12.4444444,5.5 L14,5.5 L14,14.8333333 L12.4444444,14.8333333 L12.4444444,10.9444444 L8.55555556,10.9444444 Z"/>
+  </svg>
+</svg>

package/assets/streets-poi/hotel.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <title>Lodging</title>
+  <circle cx="12" cy="13" r="10.5" fill="#44515E" opacity=".08"/>
+  <circle cx="12" cy="12.5" r="10" fill="#44515E" opacity=".22"/>
+  <circle cx="12" cy="11" r="10" fill="#FFFFFF"/>
+  <circle cx="12" cy="11" r="8.25" fill="#909CE1"/>
+  <svg x="6.5" y="7.5" width="11" height="7" viewBox="0 0 11 7" fill="#FFFFFF">
+    <path transform="translate(-5 -7)" fill-rule="evenodd" d="M5.86454849,7 C6.07788926,7 6.25083612,7.16733023 6.25083612,7.38333841 L6.25026087,11.23 L13.8162609,11.23 L13.8162609,11.229 L9.55363082,11.2296026 L9.55363082,7.94186138 C9.55363082,7.94186138 10.4141238,8.05735202 10.7150234,8.05735206 C12.2129784,8.05735203 13.5048382,9.50607239 14.0681491,10.3167693 L14.7461904,7.83035651 L14.7482609,8.617 L14.7491639,8.01836305 C14.7491639,7.83291732 14.8863533,7.67819481 15.0593924,7.64241177 L15.1354515,7.63461538 C15.3487923,7.63461538 15.5217391,7.8115966 15.5217391,8.01836305 L15.5217391,13.7692308 L14.7491639,13.7692308 L14.7482609,12.5 L6.25026087,12.5 L6.25083612,13.7692308 L5.47826087,13.7692308 L5.47826087,7.38333841 C5.47826087,7.19809045 5.61545027,7.04353295 5.78848942,7.00778807 L5.86454849,7 Z M7.98913043,8.05769231 C8.62915273,8.05769231 9.14799331,8.62594628 9.14799331,9.32692308 C9.14799331,10.0278999 8.62915273,10.5961538 7.98913043,10.5961538 C7.34910814,10.5961538 6.83026756,10.0278999 6.83026756,9.32692308 C6.83026756,8.62594628 7.34910814,8.05769231 7.98913043,8.05769231 Z"/>
+  </svg>
+</svg>

package/assets/streets-poi/museum.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <title>Museum</title>
+  <circle cx="12" cy="13" r="10.5" fill="#44515E" opacity=".08"/>
+  <circle cx="12" cy="12.5" r="10" fill="#44515E" opacity=".22"/>
+  <circle cx="12" cy="11" r="10" fill="#FFFFFF"/>
+  <circle cx="12" cy="11" r="8.25" fill="#13B5C7"/>
+  <svg x="7.5" y="5.75" width="9" height="9.82" viewBox="0 0 11 12" fill="#FFFFFF">
+    <path transform="translate(-5 -4)" fill-rule="evenodd" d="M10.5,4.5 L16,8.5 L16,9.5 L15,9.5 L15,15 L16,15 L16,16 L5,16 L5,15 L6,15 L6,9.5 L5,9.5 L5,8.5 L10.5,4.5 Z M14,8.5 L7,8.5 L7,15 L14,15 L14,8.5 Z M8.99948459,9.49839952 L10.5053982,11.6376682 L12,9.512 L12,9.5 L13,9.5 L13,14 L12,14 L12,11.264 L10.5053982,13.6524794 L8.999,11.277 L9,14 L8,14 L8,9.5 L9,9.5 Z"/>
+  </svg>
+</svg>

package/assets/streets-poi/restaurant.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <title>Restaurant</title>
+  <circle cx="12" cy="13" r="10.5" fill="#44515E" opacity=".08"/>
+  <circle cx="12" cy="12.5" r="10" fill="#44515E" opacity=".22"/>
+  <circle cx="12" cy="11" r="10" fill="#FFFFFF"/>
+  <circle cx="12" cy="11" r="8.25" fill="#FF9E67"/>
+  <svg x="8.5" y="6" width="7" height="9.625" viewBox="0 0 8 11" fill="#FFFFFF">
+    <path transform="translate(-6 -6)" fill-rule="evenodd" d="M12.4864865,12.0540541 L12.4864865,16.1621622 L14,16.1621622 L14,6.21621622 L12.4864865,6.21621622 L11.6216216,7.94594595 L11.6216216,10.7567568 L12.4864865,12.0540541 Z M9.02702703,10.7567568 L9.02702703,11.1891892 L10.7567568,10.3243243 L10.7567568,9.89189189 L10.7567568,7.08108108 L9.67567568,6.21621622 L9.67567568,9.45945946 L9.13513514,9.45945946 L8.81081081,9.45945946 L8.81081081,6 L7.94594595,6 L7.94594595,9.45945946 L7.62162162,9.45945946 L7.08108108,9.45945946 L7.08108108,6.21621622 L6,7.08108108 L6,9.89189189 L6,10.3243243 L7.72972973,11.1891892 L7.72972973,10.7567568 L7.72972973,16.1621622 L9.02702703,16.1621622 Z"/>
+  </svg>
+</svg>

package/assets/streets-poi/school.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <title>School</title>
+  <circle cx="12" cy="13" r="10.5" fill="#44515E" opacity=".08"/>
+  <circle cx="12" cy="12.5" r="10" fill="#44515E" opacity=".22"/>
+  <circle cx="12" cy="11" r="10" fill="#FFFFFF"/>
+  <circle cx="12" cy="11" r="8.25" fill="#7B9EB0"/>
+  <svg x="6.75" y="6.5" width="10.5" height="8.9" viewBox="0 0 13 11" fill="#FFFFFF">
+    <path transform="translate(-4 -5)" fill-rule="evenodd" d="M14.0097657,12.019911 L14.0097657,13.8695475 C13.1038778,15.4241579 10.6537375,15.3674047 10.5024279,15.3623802 C10.3511182,15.3674047 7.90097798,15.4241579 6.99509006,13.8695475 L6.99509006,12.019911 C6.99509006,12.019911 9.60423929,13.5859459 10.5024279,13.6268096 C11.4006164,13.5859459 14.0097657,12.019911 14.0097657,12.019911 Z M10.5,5 L17,8.25037977 L17,9.23855252 L16,9.738 L16,14.7579754 L15,14.7579754 L15,10.238 L10.5,12.4889323 L4,9.23855252 L4,8.25037977 L10.5,5 Z"/>
+  </svg>
+</svg>

package/assets/streets-poi/services.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <title>Services</title>
+  <circle cx="12" cy="13" r="10.5" fill="#44515E" opacity=".08"/>
+  <circle cx="12" cy="12.5" r="10" fill="#44515E" opacity=".22"/>
+  <circle cx="12" cy="11" r="10" fill="#FFFFFF"/>
+  <circle cx="12" cy="11" r="8.25" fill="#7B9EB0"/>
+  <svg x="6.75" y="6.25" width="10.5" height="9.55" viewBox="0 0 11 10" fill="#FFFFFF">
+    <path transform="translate(-5 -6)" fill-rule="evenodd" d="M11.015625,7.32533488 C13.2436218,5.65449747 15.9996948,6.04597697 15.9996948,6.04597697 L15.999,7.327 L16,7.32722697 L16,14.327227 L15.9140184,14.3269458 C11.9704111,14.3496822 11.930542,15.8108695 11.930542,15.8108695 L11.0158997,15.8108695 L11.015,14.327 L11,14.327227 L11,7.32722697 L12.123,7.327 Z M5.0078125,6.03795084 C5.0078125,6.03795084 7.7638855,5.65449747 9.99188232,7.32533488 L8.883,7.327 L10.0075073,7.32722697 L10.0075073,14.327227 L9.991,14.327 L9.99160767,15.8108695 L9.07696533,15.8108695 C9.06464946,15.6770402 8.85223435,14.3486164 5.09348894,14.3269458 L5.00750732,14.327227 L5.0078125,6.03795084 Z"/>
+  </svg>
+</svg>

package/assets/streets-poi/shopping.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <title>Shopping</title>
+  <circle cx="12" cy="13" r="10.5" fill="#44515E" opacity=".08"/>
+  <circle cx="12" cy="12.5" r="10" fill="#44515E" opacity=".22"/>
+  <circle cx="12" cy="11" r="10" fill="#FFFFFF"/>
+  <circle cx="12" cy="11" r="8.25" fill="#4B96F3"/>
+  <svg x="7" y="6.25" width="10" height="9.23" viewBox="0 0 13 12" fill="#FFFFFF">
+    <path transform="translate(-4 -3)" fill-rule="evenodd" d="M7.49019231,10.9275 C7.49019231,10.6215865 7.75802885,10.3747356 8.09141827,10.3747356 C8.42242788,10.3747356 8.69286058,10.6215865 8.69286058,10.9275 C8.69286058,11.6896875 9.46045673,12.3811298 10.5012981,12.3852404 C11.5421394,12.3811298 12.3060577,11.6896875 12.3086538,10.9275 C12.311899,10.6215865 12.5777885,10.3747356 12.9107452,10.3747356 C13.2415385,10.3747356 13.5137019,10.6215865 13.5137019,10.9275 C13.503101,12.3852404 12.1208654,13.4855769 10.5012981,13.4864423 C8.88259615,13.4855769 7.49689904,12.3852404 7.49019231,10.9275 Z M9.41415865,5.7046875 C9.77740385,5.03704327 10.2157212,4.76574519 10.5038942,4.78024038 C10.7881731,4.76574519 11.2264904,5.03704327 11.5901683,5.7046875 C11.8982452,6.26675481 12.1091827,7.15074519 12.1665144,8.03971154 L8.83608173,8.03971154 C8.89341346,7.15074519 9.10478365,6.26675481 9.41415865,5.7046875 M15.5291827,8.18855769 C15.4253365,8.09293269 15.2786538,8.03971154 15.130024,8.03971154 L13.2858894,8.03971154 C13.1439663,5.85439904 12.2803125,3.879375 10.5038942,3.75 C8.72314904,3.879375 7.85819712,5.85439904 7.71670673,8.03971154 L5.87213942,8.03971154 C5.72394231,8.03971154 5.57725962,8.09293269 5.47254808,8.18855769 C5.36848558,8.28569712 5.30769231,8.4159375 5.30769231,8.55439904 L4.875,14.4861779 C4.875,14.6222596 4.93665865,14.7548798 5.03985577,14.8496394 C5.14802885,14.9459135 5.29125,15 5.43944712,15 L15.5627163,15 C15.7139423,15 15.8541346,14.9476442 15.9590625,14.8496394 C16.0678846,14.7525 16.125,14.6248558 16.125,14.4861779 L15.6923077,8.55439904 C15.6923077,8.41918269 15.6328125,8.28569712 15.5291827,8.18855769"/>
+  </svg>
+</svg>

package/assets/streets-poi/train.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24">
+  <title>Train and rail</title>
+  <circle cx="12" cy="13" r="10.5" fill="#44515E" opacity=".08"/>
+  <circle cx="12" cy="12.5" r="10" fill="#44515E" opacity=".22"/>
+  <circle cx="12" cy="11" r="10" fill="#FFFFFF"/>
+  <circle cx="12" cy="11" r="8.25" fill="#10BDFF"/>
+  <svg x="7.875" y="5.9" width="8.25" height="9.8" viewBox="0 0 16 19" fill="#FFFFFF">
+    <path d="M8,0C4,0,0,.5,0,4v9.5A3.5,3.5,0,0,0,3.5,17L2,18.5V19H4.23l2-2H10l2,2h2v-.5L12.5,17A3.5,3.5,0,0,0,16,13.5V4c0-3.5-3.58-4-8-4ZM3.5,15A1.5,1.5,0,1,1,5,13.5,1.5,1.5,0,0,1,3.5,15ZM7,8H2V4H7V8ZM9,8V4h5V8Zm3.5,7A1.5,1.5,0,1,1,14,13.5,1.5,1.5,0,0,1,12.5,15Z"/>
+  </svg>
+</svg>

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 = {
@@ -163,6 +163,7 @@ declare function prepareTileflowProjectIcons(project: TileflowProjectConfig, opt
 }): Promise<PreparedTileflowProject>;
 
 type TileflowFeatureInspectionOptions = {
+    apiBaseUrl?: string;
     center: readonly [number, number];
     fetch?: typeof fetch;
     height?: number;
@@ -170,7 +171,6 @@ type TileflowFeatureInspectionOptions = {
     properties?: readonly string[];
     signal?: AbortSignal;
     sourceLayers: readonly string[];
-    tileBaseUrl?: string;
     timeoutMs?: number;
     width?: number;
     zoom: number;
@@ -231,30 +231,44 @@ declare function validateTileflowStyle(style: MapLibreStyle, map: string): Tilef
 declare const defaultTileflowApiUrl = "https://api.tileflow.dev";
 declare const defaultTileflowConfigPath = "tileflow.config.ts";
 declare const defaultTileflowManifestPath = "public/tileflow/manifest.json";
-declare const defaultTileflowTileset = "world";
 type LoadTileflowConfigOptions = {
     cwd?: string;
     fresh?: boolean;
 };
 type TileflowManifestOptions = {
     styleBaseUrl?: string;
-    tileBaseUrl?: string;
 };
 type TileflowDevRequestHandlerOptions = {
+    apiBaseUrl?: string;
     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 = {
+    apiBaseUrl?: string;
     assetBaseUrl?: string;
     config?: string;
     cwd?: string;
     styleBaseUrl?: string;
-    tileBaseUrl?: string;
 };
 type TileflowBuildArtifacts = {
     assets: TileflowBuildAsset[];
@@ -278,6 +292,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 +317,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, 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,12 +8,14 @@ import {
   compareCodeUnits as compareCodeUnits3,
   createManifest,
   createStyleFromProject as createStyleFromProject2,
+  normalizeTileflowCaptureScene,
   validateConfig
 } from "@tileflow/core";
 
 // src/icons.ts
 import { readdir, readFile, realpath, stat } from "fs/promises";
 import { basename, extname, isAbsolute, relative, resolve, sep } from "path";
+import { fileURLToPath } from "url";
 import { SaxesParser } from "saxes";
 import {
   compareCodeUnits,
@@ -24,7 +26,8 @@ import {
   tileflowHostedIconIdPattern,
   tileflowIconPackageLabelSchema,
   tileflowIconPackageLimits,
-  tileflowIconPackageManifestSchema
+  tileflowIconPackageManifestSchema,
+  tileflowStreetsPoiIconMapping
 } from "@tileflow/core";
 var TileflowIconCompilationError = class extends Error {
   code = "ICON_INVALID";
@@ -43,6 +46,7 @@ var TileflowIconCompilationError = class extends Error {
 };
 var iconFileExtensions = /* @__PURE__ */ new Set([".svg", ".png", ".jpg", ".jpeg", ".webp"]);
 var iconSpriteSize = 24;
+var streetsPoiIconSourceDir = fileURLToPath(new URL("../assets/streets-poi", import.meta.url));
 async function compileTileflowIconPackages(project, options) {
   const result = await compileIconSources(project, options);
   const packagesByHash = /* @__PURE__ */ new Map();
@@ -66,7 +70,11 @@ async function compileTileflowIconPackages(project, options) {
     packages: [...packagesByHash.values()].sort(
       (left, right) => compareCodeUnits(left.contentHash, right.contentHash)
     ),
-    watchPaths: [...result.compiledBySource.keys()].sort(compareCodeUnits)
+    watchPaths: [
+      ...new Set(
+        result.resolvedRequests.filter((request) => !request.builtIn).map((request) => request.realSourceDir)
+      )
+    ].sort(compareCodeUnits)
   };
 }
 async function inspectTileflowIconCatalogs(project, options) {
@@ -192,7 +200,7 @@ async function compileIconSources(project, options) {
   for (const request of requests) {
     try {
       const realSourceDir = await realpath(request.sourceDir);
-      if (options.target === "hosted" && realCwd && !isPathInside(realCwd, realSourceDir)) {
+      if (options.target === "hosted" && realCwd && !request.builtIn && !isPathInside(realCwd, realSourceDir)) {
         issues.push({
           message: "Hosted icon sources must remain inside the selected working tree",
           path: sourcePath(request.mapName)
@@ -292,9 +300,9 @@ async function prepareTileflowProjectIcons(project, options) {
   };
 }
 function getTileflowIconWatchPaths(project, cwd) {
-  return uniqueStrings(getLocalIconRequests(project, cwd).map((request) => request.sourceDir)).sort(
-    compareCodeUnits
-  );
+  return uniqueStrings(
+    getLocalIconRequests(project, cwd).filter((request) => !request.builtIn).map((request) => request.sourceDir)
+  ).sort(compareCodeUnits);
 }
 function getLocalIconRequests(project, cwd) {
   return getMapIconRequests(project, cwd).filter(
@@ -309,6 +317,18 @@ function getMapIconRequests(project, cwd, mapNames) {
       throw new Error(`Unknown Tileflow map: ${mapName}`);
     }
     const iconSet = resolveIconSet(mapConfig.icons, project.icons);
+    if (!iconSet?.source && !iconSet?.sprite && usesBuiltInStreetsPoiIcons(mapConfig)) {
+      const mapping2 = sortMapping({ ...tileflowStreetsPoiIconMapping, ...iconSet?.mapping });
+      return {
+        builtIn: true,
+        kind: "local",
+        label: "tileflow-streets",
+        mapName,
+        ...mapping2 ? { mapping: mapping2 } : {},
+        source: "@tileflow/dev/assets/streets-poi",
+        sourceDir: streetsPoiIconSourceDir
+      };
+    }
     const mapping = sortMapping(iconSet?.mapping);
     if (iconSet?.source) {
       return {
@@ -327,6 +347,10 @@ function getMapIconRequests(project, cwd, mapNames) {
     };
   });
 }
+function usesBuiltInStreetsPoiIcons(mapConfig) {
+  const poi = mapConfig.modules?.poi;
+  return mapConfig.basemap?.type === "streets" && poi?.enabled !== false && poi?.preset !== "none" && poi?.icons !== false;
+}
 function resolveIconSet(icons, iconSets, path = []) {
   if (!icons) {
     return void 0;
@@ -993,11 +1017,11 @@ var TileflowArtifactSessionImpl = class {
     this.#ignoredPaths = (options.ignoredPaths ?? []).map((path) => resolve2(this.#cwd, path));
     this.#buildArtifacts = buildArtifacts;
     this.#buildOptions = {
+      apiBaseUrl: options.apiBaseUrl,
       assetBaseUrl: options.assetBaseUrl,
       config: options.config,
       cwd: this.#cwd,
-      styleBaseUrl: options.styleBaseUrl,
-      tileBaseUrl: options.tileBaseUrl
+      styleBaseUrl: options.styleBaseUrl
     };
   }
   async start() {
@@ -1428,7 +1452,7 @@ async function inspectTileflowFeatures(project, mapName, input) {
       `Unknown map "${mapName}". Available maps: ${available.join(", ") || "(none)"}`
     );
   }
-  const style = createStyleFromProject(project, mapName, { tileBaseUrl: options.tileBaseUrl });
+  const style = createStyleFromProject(project, mapName, { apiBaseUrl: options.apiBaseUrl });
   assertValidTileflowStyle(style, mapName);
   const source = resolveVectorSource(style, options.sourceLayers);
   const fetchImplementation = options.fetch ?? globalThis.fetch;
@@ -1494,7 +1518,8 @@ async function inspectTileflowFeatures(project, mapName, input) {
   }
   const uniqueFeatures = deduplicateFeatures(features).sort(compareInspectedFeatures);
   const limitedFeatures = uniqueFeatures.slice(0, options.limit);
-  const metadataVersion = style.metadata?.["tileflow:tilesetVersion"];
+  const dataIdentity = style.metadata?.["tileflow:data"];
+  const metadataVersion = dataIdentity && typeof dataIdentity === "object" && "revision" in dataIdentity ? dataIdentity.revision : void 0;
   return {
     schemaVersion: 1,
     map: mapName,
@@ -1839,7 +1864,13 @@ function isRecord(value) {
 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;
@@ -1881,17 +1912,7 @@ function asTileflowProjectConfig(input) {
   if (input && typeof input === "object" && "maps" in input && typeof input.maps === "object") {
     return input;
   }
-  return {
-    tilesets: {
-      [defaultTileflowTileset]: {
-        id: defaultTileflowTileset,
-        name: "World"
-      }
-    },
-    maps: {
-      main: input
-    }
-  };
+  return { maps: { main: input } };
 }
 function getTileflowMapNames(project) {
   return Object.keys(project.maps);
@@ -1903,6 +1924,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: map.view?.pitch ?? 0
+    },
+    label: mapName,
+    mapName
+  };
+}
 function getTileflowStyleMapName(path) {
   const fileName = path.split("/").pop() ?? "";
   return fileName.replace(/\.json$/, "");
@@ -1937,13 +2004,12 @@ async function createTileflowBuildArtifacts(options = {}) {
     assetBaseUrl: resolveAssetBaseUrl(options),
     cwd: options.cwd ?? process.cwd()
   });
-  const styleOptions = { tileBaseUrl: options.tileBaseUrl };
+  const styleOptions = { apiBaseUrl: options.apiBaseUrl };
   const styles = createTileflowStyles(prepared.project, styleOptions);
   return {
     assets: prepared.assets,
     manifest: createManifest(prepared.project, {
-      styleBaseUrl: options.styleBaseUrl,
-      tileBaseUrl: options.tileBaseUrl
+      styleBaseUrl: options.styleBaseUrl
     }),
     project: prepared.project,
     styles,
@@ -2048,7 +2114,7 @@ function createTileflowDevRequestHandler(options = {}) {
   const basePath = normalizeTileflowBasePath(options.basePath);
   const configPath = options.config ?? defaultTileflowConfigPath;
   const cwd = options.cwd ?? process.cwd();
-  const tileBaseUrl = options.tileBaseUrl ?? defaultTileflowApiUrl;
+  const apiBaseUrl = options.apiBaseUrl ?? defaultTileflowApiUrl;
   return async function handleTileflowDevRequest(request) {
     if (request.method !== "GET" && request.method !== "HEAD") {
       return jsonResponse({ error: "Method not allowed" }, 405);
@@ -2079,7 +2145,7 @@ function createTileflowDevRequestHandler(options = {}) {
           config: configPath,
           cwd,
           styleBaseUrl: options.styleBaseUrl ?? `${url.origin}${basePath}`,
-          tileBaseUrl
+          apiBaseUrl
         });
         state = {
           artifacts,
@@ -2092,8 +2158,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 +2265,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 +2332,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 +2357,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 +2398,85 @@ 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)};
+
+      const cameraRanges = {
+        bearing: [-180, 180],
+        lat: [-90, 90],
+        lng: [-180, 180],
+        pitch: [0, 85],
+        zoom: [0, 24]
+      };
+
+      function readCameraFromUrl() {
+        const params = new URL(location.href).searchParams;
+        const camera = {};
+
+        for (const [name, range] of Object.entries(cameraRanges)) {
+          const values = params.getAll(name);
+          if (values.length !== 1 || values[0].trim() === "") return undefined;
+          const value = Number(values[0]);
+          if (!Number.isFinite(value) || value < range[0] || value > range[1]) return undefined;
+          camera[name] = value;
+        }
+
+        return {
+          bearing: camera.bearing,
+          center: [camera.lng, camera.lat],
+          pitch: camera.pitch,
+          zoom: camera.zoom
+        };
+      }
+
+      function resolveInitialMapOptions(options) {
+        const camera = readCameraFromUrl();
+        if (!camera) return options;
+        const resolved = {...options};
+        delete resolved.bounds;
+        delete resolved.fitBoundsOptions;
+        return {...resolved, ...camera};
+      }
+
+      function formatCameraNumber(value) {
+        return String(Number(value.toFixed(6)));
+      }
+
+      function wrapLongitude(value) {
+        return ((value + 180) % 360 + 360) % 360 - 180;
+      }
+
+      function writeCameraToUrl(map) {
+        const center = map.getCenter();
+        const url = new URL(location.href);
+        const camera = {
+          bearing: map.getBearing(),
+          lat: center.lat,
+          lng: wrapLongitude(center.lng),
+          pitch: map.getPitch(),
+          zoom: map.getZoom()
+        };
+
+        for (const [name, value] of Object.entries(camera)) {
+          url.searchParams.set(name, formatCameraNumber(value));
+        }
+        history.replaceState(history.state, "", url.href);
+      }
 
       if (styleUrl) {
         const map = new maplibregl.Map({
           container: "map",
           style: styleUrl,
-          center: [-3.7038, 40.4168],
-          zoom: 12
+          ...resolveInitialMapOptions(previewMapOptions)
         });
         map.addControl(new maplibregl.NavigationControl(), "top-right");
+        map.on("load", () => writeCameraToUrl(map));
+        map.on("moveend", () => writeCameraToUrl(map));
       }
 
       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 +2500,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 +2566,7 @@ function isPathWithin(root, candidate) {
 }
 export {
   TileflowIconCompilationError,
+  TileflowPreviewSelectionError,
   TileflowStyleValidationError,
   TileflowValidationError,
   asTileflowProjectConfig,
@@ -2416,7 +2585,6 @@ export {
   defaultTileflowApiUrl,
   defaultTileflowConfigPath,
   defaultTileflowManifestPath,
-  defaultTileflowTileset,
   getFirstTileflowMapName,
   getTileflowAssetBasePath,
   getTileflowAssetFileName,
@@ -2432,6 +2600,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.18",
   "description": "Node development utilities for Tileflow configs and builds.",
   "type": "module",
   "sideEffects": false,
@@ -23,7 +23,9 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "assets",
+    "dist",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "exports": {
     ".": {
@@ -38,12 +40,12 @@
   "dependencies": {
     "@mapbox/vector-tile": "2.0.5",
     "@maplibre/maplibre-gl-style-spec": "24.8.5",
+    "@tileflow/core": ">=0.1.0-alpha.19 <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"