@tileflow/dev 0.1.0-alpha.27 → 0.1.0-alpha.29

package/README.md

@@ -73,6 +73,12 @@ manifest pointer, tracks its own files, and refuses to replace a hosted manifest
 Production rejects unresolved local PMTiles; publish data explicitly or provide an application-owned
 production source. Local development snapshots do not publish or redistribute the original dataset.
 
+Maps whose labels use a line-fitted `text.background` draw text with derived glyph stacks. Local
+previews and captures route such a map's glyph URL through `__glyphs/<map>/…`. Ordinary stacks pass
+through from the declared provider; derived ranges are computed from their source ranges, which are
+cached under `.tileflow/cache/glyphs/v1`. Production output keeps the declared provider, which must
+serve derived stacks.
+
 ## Keep a watched request handler
 
 Use one session for repeated work and close it when the owning server stops:
@@ -137,8 +143,9 @@ This is the one normal icon-preparation path. `compileTileflowIconPackages`,
 `prepareTileflowCatalogIcons`, `inspectTileflowIconCatalogs` and `getTileflowIconWatchPaths` all use
 it, so `createTileflowBuildArtifacts`, `createTileflowArtifactSession`, and every adapter that
 enters them accept the same explicit `icons` resolution options: `cacheRoot`, `offline`,
-`deliveryOrigins`, `fetch` and `signal`. Nothing selects a cache, an origin, or a transport from
-implicit process state, and no build or watch polls a catalog head. `prepareTileflowCatalogIcons`
+`deliveryOrigins`, `fetch` and `signal`. An explicit `cacheRoot` takes precedence over
+`TILEFLOW_ICON_CACHE_DIR`, then the OS cache default. Origins and transport use their documented
+defaults unless supplied explicitly; no build or watch polls a catalog head. `prepareTileflowCatalogIcons`
 returns `mapIconCompositions` alongside `mapIconSources`, and build-manifest entries carry the
 receipt as `sourceAssets.iconComposition` with `mapRevisionSchemaVersion: 2`.
 
@@ -159,8 +166,8 @@ Applications may explicitly configure trusted `deliveryOrigins`; locks cannot ad
 forbids all fetches and fails on missing or corrupt entries. Complete-map offline rendering still
 depends on unrelated tiles, glyphs, and other external resources.
 
-The cache lives under the OS user cache with `tileflow/icons/v1/<contentHash>`. `cacheRoot` or
-`TILEFLOW_ICON_CACHE_DIR` overrides its parent. Atomic directory installation and exact-entry
+The cache lives under the OS user cache with `tileflow/icons/v1/<contentHash>`. `cacheRoot`, then
+`TILEFLOW_ICON_CACHE_DIR`, overrides its parent. Atomic directory installation and exact-entry
 retirement support concurrent writers and corruption repair. Symlink entries are rejected. This is
 a disposable cache, not a security sandbox against another process controlling the same user
 account. Incomplete temporary entries are never accepted as published cache entries.

package/dist/artifacts.d.ts

@@ -5,6 +5,38 @@ import { TileflowRenderer, TileflowNativeBuildRecord } from '@tileflow/core/nati
 import { TileflowBuildAsset, TileflowIconResolutionOptions, PreparedTileflowBuildCatalog, TileflowSourceCatalog, PreparedTileflowCatalog } from './icons.js';
 export { defaultTileflowConfigPath } from './config.js';
 
+/**
+ * Local glyph serving for line-fitted text backgrounds.
+ *
+ * A style whose text uses a derived `<stack> lines-v1-…` font stack needs a glyph provider that
+ * derives those ranges. Local previews and captures route such a map's glyph URL through
+ * `__glyphs/<map>/…`: ordinary stacks pass through from the map's declared provider unchanged, and
+ * derived stacks are computed from their source stack's range. Production output keeps the
+ * declared provider, which must serve derived stacks itself.
+ */
+declare const tileflowLineBackgroundGlyphRoute = "__glyphs";
+/** Map name to the upstream glyph URL template its styles declared. Local only; never serialized. */
+type TileflowLineBackgroundGlyphProviders = Readonly<Record<string, string>>;
+type TileflowLineBackgroundGlyphResponderOptions = {
+    /** Project root; ranges are cached under `.tileflow/cache/glyphs/v1`. */
+    cwd: string;
+    fetch?: typeof globalThis.fetch;
+};
+type TileflowLineBackgroundGlyphResponder = (upstream: string, fontStack: string, range: string) => Promise<Response>;
+/** Whether a compiled style draws text with a derived line-background stack. */
+declare function usesTileflowLineBackgroundGlyphs(style: MapLibreStyle): boolean;
+/** Parses `/__glyphs/<map>/<fontstack>/<range>.pbf` from a decoded route path. */
+declare function parseTileflowLineBackgroundGlyphPath(path: string): {
+    fontStack: string;
+    mapName: string;
+    range: string;
+} | undefined;
+/**
+ * Serves one glyph range for a declared upstream template. Upstream ranges are cached on disk;
+ * derived ranges are recomputed from them and kept in a bounded in-memory cache.
+ */
+declare function createTileflowLineBackgroundGlyphResponder(options: TileflowLineBackgroundGlyphResponderOptions): TileflowLineBackgroundGlyphResponder;
+
 type TileflowLocalTilesetFile = Readonly<{
     byteLength: number;
     etag: string;
@@ -121,6 +153,12 @@ type TileflowBuildArtifactsOptions = {
     assetBaseUrl?: string;
     config?: string;
     cwd?: string;
+    /**
+     * Native local preview only: the exact HTTP origin serving these artifacts, such as
+     * `http://127.0.0.1:3333`. Native checks accept HTTP resources at this origin only; every other
+     * origin still requires HTTPS. It is never inferred, and web or production output rejects it.
+     */
+    developmentOrigin?: string;
     /**
      * Explicit shared Icon Set resolution settings for this build.
      *
@@ -149,6 +187,8 @@ type TileflowBuildArtifacts = {
     project: TileflowBuildCatalog;
     /** Local-only archive ports. Paths never enter serialized build artifacts. */
     localTilesets?: TileflowLocalTilesetFile[];
+    /** Local-only upstream glyph templates for maps whose text uses line-fitted backgrounds. */
+    lineBackgroundGlyphs?: TileflowLineBackgroundGlyphProviders;
     /** Optional local-only provenance. It is never serialized as a build artifact. */
     styleInspections?: TileflowBuildStyleInspections;
     styles: TileflowBuildStyles;
@@ -172,7 +212,7 @@ type TileflowArtifactPlan = TileflowBuildArtifacts & {
     schemaVersion: typeof tileflowArtifactPlanSchemaVersion;
     sourceProject: TileflowSourceCatalog;
 };
-type CreateTileflowArtifactPlanOptions = Pick<TileflowBuildArtifactsOptions, 'apiBaseUrl' | 'assetBaseUrl' | 'inspection' | 'renderer' | 'styleBaseUrl' | 'target'> & {
+type CreateTileflowArtifactPlanOptions = Pick<TileflowBuildArtifactsOptions, 'apiBaseUrl' | 'assetBaseUrl' | 'developmentOrigin' | 'inspection' | 'renderer' | 'styleBaseUrl' | 'target'> & {
     inputFiles?: readonly string[];
 };
 type WriteTileflowArtifactPlanOptions = {
@@ -222,4 +262,4 @@ declare function assertTileflowSelfHostedManifestTarget(manifestPath: string, op
     overwriteHostedManifest?: boolean;
 }): Promise<void>;
 
-export { type CreateTileflowArtifactPlanOptions, PreparedTileflowBuildCatalog, PreparedTileflowCatalog, type TileflowArtifactAcquisition, type TileflowArtifactDiagnostic, type TileflowArtifactFile, type TileflowArtifactInputGraph, type TileflowArtifactPlan, type TileflowArtifactSession, type TileflowArtifactSessionOptions, type TileflowArtifactSessionState, type TileflowBuildArtifacts, type TileflowBuildArtifactsOptions, TileflowBuildAsset, type TileflowBuildStyleInspections, TileflowHostedManifestOverwriteError, TileflowIconResolutionOptions, type TileflowLocalTilesetFile, TileflowLocalTilesetProductionError, type TileflowManifestOptions, TileflowSourceCatalog, type WriteTileflowArtifactPlanOptions, type WriteTileflowBuildArtifactsOptions, assertNoLocalTilesetsForProduction, assertTileflowSelfHostedManifestTarget, createTileflowArtifactDiagnostics, createTileflowArtifactPlan, createTileflowArtifactSession, createTileflowBuildArtifacts, createTileflowBuildProvenance, createTileflowManifest, createTileflowStyle, createTileflowStyles, disposeTileflowBuildArtifacts, getTileflowArtifactFiles, getTileflowAssetBasePath, getTileflowAssetFileName, getTileflowWatchPaths, isTileflowArtifactInputPath, joinTileflowPublicUrl, normalizeTileflowBasePath, prepareTileflowHostedNativeDeployment, prepareTileflowLocalTilesets, refreshTileflowArtifactSession, resolveTileflowArtifactPublicUrls, tileflowArtifactInventoryFileName, tileflowArtifactPlanSchemaVersion, tileflowArtifactSessionSchemaVersion, writeTileflowArtifactPlan, writeTileflowBuildArtifacts };
+export { type CreateTileflowArtifactPlanOptions, PreparedTileflowBuildCatalog, PreparedTileflowCatalog, type TileflowArtifactAcquisition, type TileflowArtifactDiagnostic, type TileflowArtifactFile, type TileflowArtifactInputGraph, type TileflowArtifactPlan, type TileflowArtifactSession, type TileflowArtifactSessionOptions, type TileflowArtifactSessionState, type TileflowBuildArtifacts, type TileflowBuildArtifactsOptions, TileflowBuildAsset, type TileflowBuildStyleInspections, TileflowHostedManifestOverwriteError, TileflowIconResolutionOptions, type TileflowLineBackgroundGlyphProviders, type TileflowLineBackgroundGlyphResponder, type TileflowLocalTilesetFile, TileflowLocalTilesetProductionError, type TileflowManifestOptions, TileflowSourceCatalog, type WriteTileflowArtifactPlanOptions, type WriteTileflowBuildArtifactsOptions, assertNoLocalTilesetsForProduction, assertTileflowSelfHostedManifestTarget, createTileflowArtifactDiagnostics, createTileflowArtifactPlan, createTileflowArtifactSession, createTileflowBuildArtifacts, createTileflowBuildProvenance, createTileflowLineBackgroundGlyphResponder, createTileflowManifest, createTileflowStyle, createTileflowStyles, disposeTileflowBuildArtifacts, getTileflowArtifactFiles, getTileflowAssetBasePath, getTileflowAssetFileName, getTileflowWatchPaths, isTileflowArtifactInputPath, joinTileflowPublicUrl, normalizeTileflowBasePath, parseTileflowLineBackgroundGlyphPath, prepareTileflowHostedNativeDeployment, prepareTileflowLocalTilesets, refreshTileflowArtifactSession, resolveTileflowArtifactPublicUrls, tileflowArtifactInventoryFileName, tileflowArtifactPlanSchemaVersion, tileflowArtifactSessionSchemaVersion, tileflowLineBackgroundGlyphRoute, usesTileflowLineBackgroundGlyphs, writeTileflowArtifactPlan, writeTileflowBuildArtifacts };

package/dist/artifacts.js

@@ -8,6 +8,7 @@ import {
   createTileflowArtifactSession,
   createTileflowBuildArtifacts,
   createTileflowBuildProvenance,
+  createTileflowLineBackgroundGlyphResponder,
   createTileflowManifest,
   createTileflowStyle,
   createTileflowStyles,
@@ -15,15 +16,18 @@ import {
   getTileflowArtifactFiles,
   getTileflowWatchPaths,
   isTileflowArtifactInputPath,
+  parseTileflowLineBackgroundGlyphPath,
   prepareTileflowHostedNativeDeployment,
   prepareTileflowLocalTilesets,
   refreshTileflowArtifactSession,
   tileflowArtifactInventoryFileName,
   tileflowArtifactPlanSchemaVersion,
   tileflowArtifactSessionSchemaVersion,
+  tileflowLineBackgroundGlyphRoute,
+  usesTileflowLineBackgroundGlyphs,
   writeTileflowArtifactPlan,
   writeTileflowBuildArtifacts
-} from "./chunk-QAMFAM3S.js";
+} from "./chunk-LXSFLPIU.js";
 import "./chunk-ONYQNLNA.js";
 import {
   getTileflowAssetBasePath,
@@ -49,6 +53,7 @@ export {
   createTileflowArtifactSession,
   createTileflowBuildArtifacts,
   createTileflowBuildProvenance,
+  createTileflowLineBackgroundGlyphResponder,
   createTileflowManifest,
   createTileflowStyle,
   createTileflowStyles,
@@ -61,6 +66,7 @@ export {
   isTileflowArtifactInputPath,
   joinTileflowPublicUrl,
   normalizeTileflowBasePath,
+  parseTileflowLineBackgroundGlyphPath,
   prepareTileflowHostedNativeDeployment,
   prepareTileflowLocalTilesets,
   refreshTileflowArtifactSession,
@@ -68,6 +74,8 @@ export {
   tileflowArtifactInventoryFileName,
   tileflowArtifactPlanSchemaVersion,
   tileflowArtifactSessionSchemaVersion,
+  tileflowLineBackgroundGlyphRoute,
+  usesTileflowLineBackgroundGlyphs,
   writeTileflowArtifactPlan,
   writeTileflowBuildArtifacts
 };

package/dist/{chunk-6OJICHB3.js → chunk-CJGM6HTT.js}

@@ -168,7 +168,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
       body { font-family: ui-sans-serif, system-ui, sans-serif; }
       #map {
         --tileflow-globe-radius: 220px;
-        background-color: #2F5070;
+        background-color: var(--tileflow-space, #2F5070);
         background-image:
           radial-gradient(circle at 18% 24%, rgba(225, 240, 250, 0.34) 0 1px, transparent 1.4px),
           radial-gradient(circle at 72% 62%, rgba(225, 240, 250, 0.22) 0 1px, transparent 1.3px),
@@ -191,12 +191,12 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
         top: 50%;
         width: calc(var(--tileflow-globe-radius) * 2);
         height: calc(var(--tileflow-globe-radius) * 2);
-        border: 1px solid rgba(248, 252, 255, 0.88);
+        border: 1px solid var(--tileflow-rim-line, rgba(248, 252, 255, 0.88));
         border-radius: 50%;
         box-shadow:
-          0 0 9px 3px rgba(248, 252, 255, 0.9),
-          0 0 28px 10px rgba(176, 220, 246, 0.52),
-          0 0 58px 20px rgba(132, 195, 232, 0.2);
+          0 0 9px 3px var(--tileflow-rim-core, rgba(248, 252, 255, 0.9)),
+          0 0 28px 10px var(--tileflow-rim-glow, rgba(176, 220, 246, 0.52)),
+          0 0 58px 20px var(--tileflow-rim-haze, rgba(132, 195, 232, 0.2));
         pointer-events: none;
         transform: translate(-50%, -50%);
       }
@@ -233,7 +233,8 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
         white-space: pre-wrap;
       }
       .maplibregl-ctrl-group .tileflow-3d-toggle,
-      .maplibregl-ctrl-group .tileflow-tree-toggle {
+      .maplibregl-ctrl-group .tileflow-tree-toggle,
+      .maplibregl-ctrl-group .tileflow-theme-toggle {
         width: auto;
         min-width: 58px;
         padding: 0 9px;
@@ -247,7 +248,8 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
         color: #174EA6;
       }
       .maplibregl-ctrl-group .tileflow-3d-toggle:hover,
-      .maplibregl-ctrl-group .tileflow-tree-toggle:hover {
+      .maplibregl-ctrl-group .tileflow-tree-toggle:hover,
+      .maplibregl-ctrl-group .tileflow-theme-toggle:hover {
         background-color: #F1F3F4;
       }
     </style>
@@ -275,6 +277,8 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
       const previewLabel = ${JSON.stringify(preview?.label)};
       const styleUrl = ${JSON.stringify(styleUrl)};
       const previewMapOptions = ${JSON.stringify(mapOptions)};
+      const previewTheme = ${serializeInlineJson(preview?.themeName ?? null)};
+      const previewThemes = ${serializeInlineJson(preview?.themeNames ?? [])};
       const isSemanticPreview = ${JSON.stringify(isSemanticPreview)};
       const previewFontFaces = ${serializeInlineJson(fontFaces)};
       const treeSearchParameters = new URL(location.href).searchParams;
@@ -985,6 +989,30 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
         );
         container.classList.add("tileflow-globe");
         container.style.setProperty("--tileflow-globe-radius", radius.toFixed(2) + "px");
+        applyAtmosphereBackdrop(map, container);
+      }
+
+      // Uses the map's declared atmosphere for the preview's space and rim, so a themed globe shows
+      // its own colours; maps without one keep the default backdrop.
+      function applyAtmosphereBackdrop(map, container) {
+        const atmosphere = map.getStyle?.()?.metadata?.["tileflow:atmosphere"];
+        const rgba = (hex, alpha) => {
+          const match = /^#([0-9a-f]{6})$/i.exec(String(hex ?? ""));
+          if (!match) return undefined;
+          const value = Number.parseInt(match[1], 16);
+          return "rgba(" + (value >> 16) + ", " + ((value >> 8) & 255) + ", " + (value & 255) + ", " + alpha + ")";
+        };
+        const properties = {
+          "--tileflow-space": rgba(atmosphere?.spaceColor, 1),
+          "--tileflow-rim-line": rgba(atmosphere?.horizonColor, 0.88),
+          "--tileflow-rim-core": rgba(atmosphere?.horizonColor, 0.9),
+          "--tileflow-rim-glow": rgba(atmosphere?.horizonColor, 0.52),
+          "--tileflow-rim-haze": rgba(atmosphere?.skyColor, 0.35),
+        };
+        for (const [name, value] of Object.entries(properties)) {
+          if (value) container.style.setProperty(name, value);
+          else container.style.removeProperty(name);
+        }
       }
 
       function createBuildingWireframeLayer(map, styleLayer) {
@@ -3777,6 +3805,38 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
         }
       }
 
+      // Switches a map preview between its themes. The preview reloads with the next theme and keeps
+      // the camera and toggles already written to the URL; scene previews own their theme.
+      class ThemeControl {
+        onAdd(map) {
+          this.map = map;
+          this.container = document.createElement("div");
+          this.container.className = "maplibregl-ctrl maplibregl-ctrl-group";
+          this.button = document.createElement("button");
+          this.button.type = "button";
+          this.button.className = "tileflow-theme-toggle";
+          const next = previewThemes[(previewThemes.indexOf(previewTheme) + 1) % previewThemes.length];
+          this.button.textContent = String(previewTheme).toUpperCase();
+          this.button.title = "Switch to the " + next + " theme";
+          this.button.setAttribute("aria-label", "Switch to the " + next + " theme");
+          this.handleClick = () => {
+            writeCameraToUrl(map);
+            const url = new URL(location.href);
+            url.searchParams.set("theme", next);
+            location.assign(url.href);
+          };
+          this.button.addEventListener("click", this.handleClick);
+          this.container.appendChild(this.button);
+          return this.container;
+        }
+
+        onRemove() {
+          this.button?.removeEventListener("click", this.handleClick);
+          this.container?.remove();
+          this.map = undefined;
+        }
+      }
+
       const previewLayerGroupIds = [
         "labels", "pois", "roads", "transit", "buildings", "landuse", "water"
       ];
@@ -3913,6 +3973,7 @@ function renderTileflowPreviewHtml(preview, basePath, initialStatus, isSemanticP
           map.addControl(threeDimensionalControl, "top-right");
           map.addControl(treeControl, "top-right");
         }
+        if (previewThemes.length > 1) map.addControl(new ThemeControl(), "top-right");
         let ensuringThreeDimensionalLayers;
         const treeRuntimeMinimumZoom = 16;
         const ensureThreeDimensionalLayers = () => {
@@ -4200,7 +4261,8 @@ function resolveTileflowPreview(project, selection = {}) {
     },
     label: `${mapName} / ${selectedTheme.name}`,
     mapName,
-    themeName: selectedTheme.name
+    themeName: selectedTheme.name,
+    themeNames: Object.keys(resolvedMap.themes)
   };
 }
 function resolvePreviewTheme(map, requested) {