@tileflow/core 0.1.0-alpha.34 → 0.1.0-alpha.35

package/dist/{manifest-types-hmzy2bBX.d.ts → manifest-types-Bzxon3dx.d.ts}

@@ -1,3 +1,10 @@
+/** Artistic presets; selecting one never starts a clock or moves the real sun. */
+declare const tileflowTimesOfDay: readonly ["day", "dawn", "dusk", "night"];
+type TileflowTimeOfDay = (typeof tileflowTimesOfDay)[number];
+/** A named theme family points to complete, already compiled themes. */
+type TileflowTimeOfDayVariants = Readonly<Record<string, Readonly<Partial<Record<TileflowTimeOfDay, string>>>>>;
+declare function isTileflowTimeOfDay(value: unknown): value is TileflowTimeOfDay;
+
 declare const expressionBrand: unique symbol;
 declare const themeValueBrand: unique symbol;
 declare const zoomBrand: unique symbol;
@@ -535,21 +542,50 @@ declare const tileflowPoiCategories: readonly ["arts-entertainment", "education"
 type TileflowPoiCategory = (typeof tileflowPoiCategories)[number];
 type TileflowPoiDensity = 1 | 2 | 3 | 4 | 5;
 type TileflowPoiColorMode = 'uniform' | 'category';
-type TileflowPoiCategoryStyle = Omit<TileflowMarkerSymbolStyle, 'priority'> & {
-    /** Optional category-local cap within the module's canonical density tiers. */
-    density?: TileflowPoiDensity;
-};
+/**
+ * How POI categories are placed against each other. `importance` places every category in one
+ * order, by World's ranks. `categories` gives each category its own layer and places the
+ * categories in the order they are listed, the first on top; ranks order each category only.
+ */
+type TileflowPoiPlacementOrder = 'categories' | 'importance';
+/**
+ * The appearance of one POI category. With the default `importance` order every category shares
+ * one placement layer, so categories may differ only in properties MapLibre evaluates per feature
+ * (image, size, colors, font, offsets); layer-wide properties such as zoom ranges, padding,
+ * overlap or `optional` must match, or the module uses `placement.order: 'categories'`.
+ */
+type TileflowPoiCategoryStyle = Omit<TileflowMarkerSymbolStyle, 'priority'>;
 type TileflowPoiModuleConfig = {
     type: 'poi';
     categories?: readonly TileflowPoiCategory[];
     color?: TileflowPoiColorMode;
+    /** One density for the whole module: World's ranks decide what each category shows. */
     density?: TileflowPoiDensity;
     icons?: boolean;
     labels?: boolean;
     minZoom?: number;
     placement?: {
+        /**
+         * Places each pictogram with its name as one unit that needs room for both. Defaults to
+         * `false`.
+         */
         coupleIconAndLabel?: boolean;
         iconPadding?: number;
+        /**
+         * World POI `type` values whose pictogram explains them. When pictograms and names are both
+         * drawn, every other POI needs a name, and these types are drawn as a pictogram alone.
+         * Defaults to parking and public toilets.
+         */
+        iconOnlyTypes?: readonly string[];
+        /** Defaults to `importance`. */
+        order?: TileflowPoiPlacementOrder;
+        /**
+         * With the `importance` order, POIs whose World `filter_rank` is at most this value are placed
+         * before the map's road and place labels, and the others after them. A map that gives street
+         * names priority over POIs (labels `collisionPriority: 'navigation'`) keeps its landmarks this
+         * way. Unset, every POI is placed at the module's own position.
+         */
+        prominentRank?: 0 | 1 | 2 | 3 | 4 | 5;
         textPadding?: number;
     };
     styles?: Partial<Record<TileflowPoiCategory, TileflowPoiCategoryStyle>>;
@@ -668,6 +704,7 @@ type TileflowRuntimeSource = {
     map: string;
 };
 type TileflowRuntimeStyleOptions = {
+    timeOfDay?: TileflowTimeOfDay;
     colorScheme?: TileflowRuntimeColorScheme;
     manifestMap?: TileflowRuntimeManifestMap | null;
     source: TileflowRuntimeSource;
@@ -733,7 +770,7 @@ declare function resolveTileflowRuntimeThemeBlend(options: {
 declare function assertValidTileflowRuntimeSource(source: unknown): asserts source is TileflowRuntimeSource;
 declare function resolveTileflowRuntimeStyle(options: TileflowRuntimeStyleOptions): TileflowRuntimeStyle | null;
 /** Resolve one concrete published theme without consulting ambient browser state. */
-declare function resolveTileflowRuntimeTheme(map: TileflowRuntimeManifestMap, selection: TileflowThemeSelection | undefined, colorScheme?: TileflowRuntimeColorScheme): TileflowResolvedRuntimeTheme;
+declare function resolveTileflowRuntimeTheme(map: TileflowRuntimeManifestMap, selection: TileflowThemeSelection | undefined, colorScheme?: TileflowRuntimeColorScheme, timeOfDay?: TileflowTimeOfDay): TileflowResolvedRuntimeTheme;
 /** Strictly reads Tileflow-owned web-font metadata from a compiled MapLibre style. */
 declare function getTileflowStyleFontFaces(style: Pick<MapLibreStyle, 'metadata'>): TileflowStyleFontFace[];
 declare function normalizeTileflowUrl(value: string): string;
@@ -769,6 +806,7 @@ declare function resolveTileflowStaticImageUrl(input: {
     } | null;
     manifestMap: TileflowRuntimeManifestMap | null;
     theme?: TileflowThemeSelection;
+    timeOfDay?: TileflowTimeOfDay;
     zoom: number;
 }): string | undefined;
 declare function normalizeTileflowStaticImageSize(input: {
@@ -780,8 +818,10 @@ declare function normalizeTileflowStaticImageSize(input: {
 };
 declare function inferTileflowAnalyticsFromStyleUrl(styleUrl: string): TileflowAnalytics | undefined;
 
-/** The first and only public multi-theme runtime manifest contract. */
+/** The original public multi-theme runtime manifest contract. */
 declare const tileflowRuntimeManifestVersion: 1;
+/** V2 adds the optional time-of-day catalog; maps without it still publish V1. */
+declare const tileflowTimeOfDayManifestVersion: 2;
 declare const tileflowRuntimeManifestLimits: Readonly<{
     maximumBytes: number;
 }>;
@@ -807,6 +847,7 @@ type TileflowRuntimeManifestMapEntry = {
     mapId?: string;
     systemThemes?: TileflowRuntimeSystemThemes;
     themes: Record<string, TileflowRuntimeManifestTheme>;
+    timeOfDay?: TileflowTimeOfDayVariants;
     usageMode?: 'session';
     view?: TileflowViewConfig;
     worldGeneration?: 'v1';
@@ -820,7 +861,7 @@ type TileflowRuntimeManifestMapEntry = {
 type TileflowRuntimeManifest = {
     apiUrl?: string;
     maps: Record<string, TileflowRuntimeManifestMapEntry>;
-    version: typeof tileflowRuntimeManifestVersion;
+    version: typeof tileflowRuntimeManifestVersion | typeof tileflowTimeOfDayManifestVersion;
 };
 
-export { type TileflowManifestFetchOptions as $, type TileflowAreaStyle as A, type TileflowBackgroundPaint as B, type TileflowCirclePaint as C, type TileflowColor as D, type TileflowColorStyleValue as E, type TileflowExtrusionPaint as F, type TileflowFillPaint as G, type TileflowIconAnchor as H, type TileflowIconLayout as I, type TileflowIconPaint as J, type TileflowIconStyle as K, type TileflowIconTextFit as L, type MapLibreStyle as M, type TileflowImageStyleValue as N, type TileflowLabelDetail as O, type TileflowLabelLanguage as P, type TileflowLabelStyles as Q, type TileflowLayerRange as R, type TileflowLight as S, type TileflowRuntimeManifest as T, type TileflowLineCap as U, type ValidationMessage as V, type TileflowLineHatchStyle as W, type TileflowLineJoin as X, type TileflowLineLayout as Y, type TileflowLinePaint as Z, type TileflowLineStackStyle as _, type TileflowRuntimeColorScheme as a, type TileflowTerrainMode as a$, type TileflowManifestLoadOptions as a0, type TileflowMapMode as a1, type TileflowMapModeOptions as a2, type TileflowMarkerSymbolStyle as a3, type TileflowMountainBikeScale as a4, type TileflowNumberInsetsStyleValue as a5, type TileflowNumberStyleValue as a6, type TileflowPlaceLabelClass as a7, type TileflowPoiCategory as a8, type TileflowPoiCategoryStyle as a9, type TileflowRoadTreatmentStyle as aA, type TileflowRoadWeight as aB, type TileflowRuntimeCenterLike as aC, type TileflowRuntimeManifestMap as aD, type TileflowRuntimeSource as aE, type TileflowRuntimeSourceValidation as aF, type TileflowRuntimeStyle as aG, type TileflowRuntimeStyleOptions as aH, type TileflowRuntimeViewOptions as aI, type TileflowSessionController as aJ, type TileflowSessionGrantResponse as aK, type TileflowStringStyleValue as aL, type TileflowStructuralStyleValue as aM, type TileflowStyleFontFace as aN, type TileflowStyleValue as aO, type TileflowSymbolOverlap as aP, type TileflowSymbolPlacement as aQ, type TileflowSymbolPlacementStyle as aR, type TileflowSymbolZOrder as aS, type TileflowTerrain as aT, type TileflowTerrainConfig as aU, type TileflowTerrainContourLabelStyle as aV, type TileflowTerrainContourLineStyle as aW, type TileflowTerrainContoursConfig as aX, type TileflowTerrainEncoding as aY, type TileflowTerrainHillshadeStyle as aZ, type TileflowTerrainLayerRange as a_, type TileflowPoiColorMode as aa, type TileflowPoiDensity as ab, type TileflowPriorityOrder as ac, type TileflowProjection as ad, type TileflowResolvedRuntimeTheme as ae, type TileflowRoadAreaStyle as af, type TileflowRoadClass as ag, type TileflowRoadClassStyle as ah, type TileflowRoadCrossingStyle as ai, type TileflowRoadDetail as aj, type TileflowRoadExtras as ak, type TileflowRoadHierarchy as al, type TileflowRoadLabelDetail as am, type TileflowRoadLayerStyle as an, type TileflowRoadModifier as ao, type TileflowRoadOutline as ap, type TileflowRoadRestriction as aq, type TileflowRoadRoundaboutStyle as ar, type TileflowRoadServiceType as as, type TileflowRoadShieldDetail as at, type TileflowRoadShieldStyles as au, type TileflowRoadSidewalkStyle as av, type TileflowRoadStreetLightStyle as aw, type TileflowRoadStructure as ax, type TileflowRoadTreatmentLayerStyle as ay, type TileflowRoadTreatmentLineStyle as az, type TileflowRuntimeManifestMapEntry as b, type TileflowTextAnchor as b0, type TileflowTextBackground as b1, type TileflowTextJustify as b2, type TileflowTextLayout as b3, type TileflowTextPaint as b4, type TileflowTextStyle as b5, type TileflowThemeBlendSelection as b6, type TileflowThemeColorAlpha as b7, type TileflowThemeColorMix as b8, type TileflowThemeColorValue as b9, normalizeTileflowStaticImageSize as bA, normalizeTileflowUrl as bB, resolveTileflowAnalyticsRequestUrl as bC, resolveTileflowManifestMap as bD, resolveTileflowMapMode as bE, resolveTileflowRuntimeStyle as bF, resolveTileflowRuntimeTheme as bG, resolveTileflowRuntimeThemeBlend as bH, resolveTileflowRuntimeView as bI, resolveTileflowStaticImageUrl as bJ, shouldLoadTileflowManifest as bK, startTileflowSession as bL, tileflowPoiCategories as bM, tileflowStyleFontFaceLimits as bN, tileflowStyleFontFacesMetadataKey as bO, tileflowThemeBlendLimits as bP, tileflowThemeTokenCategories as bQ, token as bR, validateTileflowRuntimeSource as bS, validateTileflowThemeBlendSelection as bT, validateTileflowThemeSelection as bU, zoom as bV, type TileflowTypographyStyle as bW, type ResolvedTileflowTypography as bX, normalizeTileflowSurfaceId as bY, type TileflowThemeFontValue as ba, type TileflowThemeImageValue as bb, type TileflowThemeNumberValue as bc, type TileflowThemeSelection as bd, type TileflowThemeTokenCategory as be, type TileflowThemeValue as bf, type TileflowViewConfig as bg, type TileflowWaterLabelClass as bh, type TileflowZoomInterpolation as bi, type TileflowZoomValue as bj, type ValidationResult as bk, assertValidTileflowRuntimeSource as bl, clearTileflowManifestCache as bm, color as bn, createTileflowSessionController as bo, createTileflowSessionId as bp, defaultTileflowManifestUrl as bq, defaultTileflowRuntimeView as br, fixed as bs, getTileflowAnalyticsApiUrl as bt, getTileflowStyleFontFaces as bu, inferTileflowAnalyticsFromStyleUrl as bv, loadTileflowManifest as bw, mergeTileflowAnalytics as bx, nearestTileflowBlendTheme as by, normalizeTileflowRuntimeCenter as bz, type TileflowRuntimeManifestTheme as c, type TileflowRuntimeSystemThemes as d, tileflowRuntimeManifestVersion as e, type TileflowExpression as f, type TileflowFixedValue as g, type TileflowThemeTokenReference as h, type TileflowThemeColorOperation as i, type TileflowBackgroundStyle as j, type TileflowCircleStyle as k, type TileflowExtrusionStyle as l, type TileflowFillStyle as m, type TileflowLineStyle as n, type TileflowSymbolStyle as o, type TileflowRoadsModuleOptions as p, type TileflowRoadsModuleConfig as q, type TileflowLabelsModuleOptions as r, type TileflowLabelsModuleConfig as s, tileflowRuntimeManifestLimits as t, type TileflowPoiModuleOptions as u, type TileflowPoiModuleConfig as v, type MapLibreSprite as w, type TileflowAerodromeCodeDetail as x, type TileflowAlignment as y, type TileflowAnalytics as z };
+export { type TileflowLineLayout as $, type TileflowAerodromeCodeDetail as A, type TileflowAlignment as B, type TileflowAnalytics as C, type TileflowAreaStyle as D, type TileflowBackgroundPaint as E, type TileflowCirclePaint as F, type TileflowColor as G, type TileflowColorStyleValue as H, type TileflowExtrusionPaint as I, type TileflowFillPaint as J, type TileflowIconAnchor as K, type TileflowIconLayout as L, type MapLibreStyle as M, type TileflowIconPaint as N, type TileflowIconStyle as O, type TileflowIconTextFit as P, type TileflowImageStyleValue as Q, type TileflowLabelDetail as R, type TileflowLabelLanguage as S, type TileflowRuntimeManifest as T, type TileflowLabelStyles as U, type ValidationMessage as V, type TileflowLayerRange as W, type TileflowLight as X, type TileflowLineCap as Y, type TileflowLineHatchStyle as Z, type TileflowLineJoin as _, type TileflowRuntimeColorScheme as a, type TileflowTerrainContoursConfig as a$, type TileflowLinePaint as a0, type TileflowLineStackStyle as a1, type TileflowManifestFetchOptions as a2, type TileflowManifestLoadOptions as a3, type TileflowMapMode as a4, type TileflowMapModeOptions as a5, type TileflowMarkerSymbolStyle as a6, type TileflowMountainBikeScale as a7, type TileflowNumberInsetsStyleValue as a8, type TileflowNumberStyleValue as a9, type TileflowRoadStreetLightStyle as aA, type TileflowRoadStructure as aB, type TileflowRoadTreatmentLayerStyle as aC, type TileflowRoadTreatmentLineStyle as aD, type TileflowRoadTreatmentStyle as aE, type TileflowRoadWeight as aF, type TileflowRuntimeCenterLike as aG, type TileflowRuntimeManifestMap as aH, type TileflowRuntimeSource as aI, type TileflowRuntimeSourceValidation as aJ, type TileflowRuntimeStyle as aK, type TileflowRuntimeStyleOptions as aL, type TileflowRuntimeViewOptions as aM, type TileflowSessionController as aN, type TileflowSessionGrantResponse as aO, type TileflowStringStyleValue as aP, type TileflowStructuralStyleValue as aQ, type TileflowStyleFontFace as aR, type TileflowStyleValue as aS, type TileflowSymbolOverlap as aT, type TileflowSymbolPlacement as aU, type TileflowSymbolPlacementStyle as aV, type TileflowSymbolZOrder as aW, type TileflowTerrain as aX, type TileflowTerrainConfig as aY, type TileflowTerrainContourLabelStyle as aZ, type TileflowTerrainContourLineStyle as a_, type TileflowPlaceLabelClass as aa, type TileflowPoiCategory as ab, type TileflowPoiCategoryStyle as ac, type TileflowPoiColorMode as ad, type TileflowPoiDensity as ae, type TileflowPoiPlacementOrder as af, type TileflowPriorityOrder as ag, type TileflowProjection as ah, type TileflowResolvedRuntimeTheme as ai, type TileflowRoadAreaStyle as aj, type TileflowRoadClass as ak, type TileflowRoadClassStyle as al, type TileflowRoadCrossingStyle as am, type TileflowRoadDetail as an, type TileflowRoadExtras as ao, type TileflowRoadHierarchy as ap, type TileflowRoadLabelDetail as aq, type TileflowRoadLayerStyle as ar, type TileflowRoadModifier as as, type TileflowRoadOutline as at, type TileflowRoadRestriction as au, type TileflowRoadRoundaboutStyle as av, type TileflowRoadServiceType as aw, type TileflowRoadShieldDetail as ax, type TileflowRoadShieldStyles as ay, type TileflowRoadSidewalkStyle as az, type TileflowRuntimeManifestMapEntry as b, zoom as b$, type TileflowTerrainEncoding as b0, type TileflowTerrainHillshadeStyle as b1, type TileflowTerrainLayerRange as b2, type TileflowTerrainMode as b3, type TileflowTextAnchor as b4, type TileflowTextBackground as b5, type TileflowTextJustify as b6, type TileflowTextLayout as b7, type TileflowTextPaint as b8, type TileflowTextStyle as b9, isTileflowTimeOfDay as bA, loadTileflowManifest as bB, mergeTileflowAnalytics as bC, nearestTileflowBlendTheme as bD, normalizeTileflowRuntimeCenter as bE, normalizeTileflowStaticImageSize as bF, normalizeTileflowUrl as bG, resolveTileflowAnalyticsRequestUrl as bH, resolveTileflowManifestMap as bI, resolveTileflowMapMode as bJ, resolveTileflowRuntimeStyle as bK, resolveTileflowRuntimeTheme as bL, resolveTileflowRuntimeThemeBlend as bM, resolveTileflowRuntimeView as bN, resolveTileflowStaticImageUrl as bO, shouldLoadTileflowManifest as bP, startTileflowSession as bQ, tileflowPoiCategories as bR, tileflowStyleFontFaceLimits as bS, tileflowStyleFontFacesMetadataKey as bT, tileflowThemeBlendLimits as bU, tileflowThemeTokenCategories as bV, tileflowTimesOfDay as bW, token as bX, validateTileflowRuntimeSource as bY, validateTileflowThemeBlendSelection as bZ, validateTileflowThemeSelection as b_, type TileflowThemeBlendSelection as ba, type TileflowThemeColorAlpha as bb, type TileflowThemeColorMix as bc, type TileflowThemeColorValue as bd, type TileflowThemeFontValue as be, type TileflowThemeImageValue as bf, type TileflowThemeNumberValue as bg, type TileflowThemeSelection as bh, type TileflowThemeTokenCategory as bi, type TileflowThemeValue as bj, type TileflowViewConfig as bk, type TileflowWaterLabelClass as bl, type TileflowZoomInterpolation as bm, type TileflowZoomValue as bn, type ValidationResult as bo, assertValidTileflowRuntimeSource as bp, clearTileflowManifestCache as bq, color as br, createTileflowSessionController as bs, createTileflowSessionId as bt, defaultTileflowManifestUrl as bu, defaultTileflowRuntimeView as bv, fixed as bw, getTileflowAnalyticsApiUrl as bx, getTileflowStyleFontFaces as by, inferTileflowAnalyticsFromStyleUrl as bz, type TileflowRuntimeManifestTheme as c, type TileflowTypographyStyle as c0, type ResolvedTileflowTypography as c1, normalizeTileflowSurfaceId as c2, type TileflowRuntimeSystemThemes as d, type TileflowTimeOfDay as e, type TileflowTimeOfDayVariants as f, tileflowRuntimeManifestVersion as g, tileflowTimeOfDayManifestVersion as h, type TileflowExpression as i, type TileflowFixedValue as j, type TileflowThemeTokenReference as k, type TileflowThemeColorOperation as l, type TileflowBackgroundStyle as m, type TileflowCircleStyle as n, type TileflowExtrusionStyle as o, type TileflowFillStyle as p, type TileflowLineStyle as q, type TileflowSymbolStyle as r, type TileflowRoadsModuleOptions as s, tileflowRuntimeManifestLimits as t, type TileflowRoadsModuleConfig as u, type TileflowLabelsModuleOptions as v, type TileflowLabelsModuleConfig as w, type TileflowPoiModuleOptions as x, type TileflowPoiModuleConfig as y, type MapLibreSprite as z };

package/dist/manifest.d.ts

@@ -1,6 +1,6 @@
+import { T as TileflowRuntimeManifest } from './manifest-types-Bzxon3dx.js';
+export { a as TileflowRuntimeColorScheme, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, d as TileflowRuntimeSystemThemes, e as TileflowTimeOfDay, f as TileflowTimeOfDayVariants, t as tileflowRuntimeManifestLimits, g as tileflowRuntimeManifestVersion, h as tileflowTimeOfDayManifestVersion } from './manifest-types-Bzxon3dx.js';
 import { z } from 'zod';
-import { T as TileflowRuntimeManifest } from './manifest-types-hmzy2bBX.js';
-export { a as TileflowRuntimeColorScheme, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, d as TileflowRuntimeSystemThemes, t as tileflowRuntimeManifestLimits, e as tileflowRuntimeManifestVersion } from './manifest-types-hmzy2bBX.js';
 
 declare const tileflowRuntimeManifestSchema: z.ZodType<TileflowRuntimeManifest>;
 declare function parseTileflowRuntimeManifest(input: unknown): TileflowRuntimeManifest;

package/dist/manifest.js

@@ -1,5 +1,6 @@
 // src/manifest-types.ts
 var tileflowRuntimeManifestVersion = 1;
+var tileflowTimeOfDayManifestVersion = 2;
 var tileflowRuntimeManifestLimits = Object.freeze({ maximumBytes: 1024 * 1024 });
 
 // src/portable-identity-rules.ts
@@ -48,6 +49,43 @@ function createTileflowRuntimeViewSchema(operations) {
   });
 }
 
+// src/time-of-day.ts
+var tileflowTimesOfDay = ["day", "dawn", "dusk", "night"];
+function isTileflowTimeOfDay(value) {
+  return typeof value === "string" && tileflowTimesOfDay.includes(value);
+}
+function validateTileflowTimeOfDayVariants(variants, themes) {
+  const issues = [];
+  const owners = /* @__PURE__ */ new Map();
+  const families = Object.entries(variants);
+  for (const [family, moments] of families) {
+    if (!isTileflowThemeName(family) || !Object.hasOwn(themes, family)) {
+      issues.push({ path: [family], message: "Time-of-day family must name an existing theme" });
+    }
+    if (!Object.values(moments).includes(family)) {
+      issues.push({ path: [family], message: "A family must include its own theme in its presets" });
+    }
+    for (const [moment, name] of Object.entries(moments)) {
+      if (name === void 0) continue;
+      if (!isTileflowTimeOfDay(moment) || !isTileflowThemeName(name) || !Object.hasOwn(themes, name)) {
+        issues.push({
+          path: [family, moment],
+          message: "Expected a supported moment and an existing theme"
+        });
+      }
+      const owner = owners.get(name);
+      if (owner !== void 0 && owner !== family) {
+        issues.push({
+          path: [family, moment],
+          message: `Theme "${name}" already belongs to family "${owner}"`
+        });
+      }
+      owners.set(name, family);
+    }
+  }
+  return issues;
+}
+
 // src/themes/model.ts
 var tileflowThemeLimits = Object.freeze({ maxThemes: 64 });
 var themeTypographyStyleKeys = ["fallbacks", "font", "letterSpacing", "transform"];
@@ -59,6 +97,19 @@ var themeTypographyKeys = [
   "water"
 ];
 
+// src/time-of-day-schema.ts
+function createTileflowTimeOfDaySchema(operations, themeName) {
+  return operations.record(
+    themeName,
+    operations.object({
+      day: operations.optional(themeName),
+      dawn: operations.optional(themeName),
+      dusk: operations.optional(themeName),
+      night: operations.optional(themeName)
+    })
+  );
+}
+
 // src/manifest-schema.ts
 function createTileflowRuntimeManifestSchema(primitives, operations, identities = createPortableIdentitySchemas(operations)) {
   const { tileflowPortableIdSchema: tileflowPortableIdSchema2, tileflowThemeNameSchema: tileflowThemeNameSchema2 } = identities;
@@ -114,12 +165,24 @@ function createTileflowRuntimeManifestSchema(primitives, operations, identities
         })
       ),
       themes: operations.record(tileflowThemeNameSchema2, manifestThemeSchema),
+      timeOfDay: operations.optional(
+        createTileflowTimeOfDaySchema(operations, tileflowThemeNameSchema2)
+      ),
       usageMode: operations.optional(operations.literal("session")),
       view: operations.optional(viewSchema),
       worldGeneration: operations.optional(operations.literal("v1"))
     }),
     (entry, context) => {
       const names = Object.keys(entry.themes);
+      if (entry.timeOfDay) {
+        for (const issue of validateTileflowTimeOfDayVariants(entry.timeOfDay, entry.themes)) {
+          context.addIssue({
+            code: "custom",
+            message: issue.message,
+            path: ["timeOfDay", ...issue.path]
+          });
+        }
+      }
       if (names.length === 0) {
         context.addIssue({
           code: "custom",
@@ -173,10 +236,23 @@ function createTileflowRuntimeManifestSchema(primitives, operations, identities
     operations.object({
       apiUrl: operations.optional(apiOriginSchema),
       maps: operations.record(tileflowPortableIdSchema2, manifestMapSchema),
-      version: operations.literal(tileflowRuntimeManifestVersion)
+      version: operations.union(
+        operations.literal(tileflowRuntimeManifestVersion),
+        operations.literal(2)
+      )
     }),
     (manifest, context) => {
       const mapCount = Object.keys(manifest.maps).length;
+      if (manifest.version === 1) {
+        for (const [name, map] of Object.entries(manifest.maps)) {
+          if (map.timeOfDay !== void 0)
+            context.addIssue({
+              code: "custom",
+              message: "timeOfDay requires manifest version 2",
+              path: ["maps", name, "timeOfDay"]
+            });
+        }
+      }
       if (mapCount === 0) {
         context.addIssue({ code: "custom", message: "Expected at least one map", path: ["maps"] });
       }
@@ -326,6 +402,7 @@ var classicManifestSchemaOperations = {
     return z2.enum(values);
   },
   literal: (value) => z2.literal(value),
+  union: (left, right) => z2.union([classic(left), classic(right)]),
   tuplePair(left, right) {
     return z2.tuple([classic(left), classic(right)]);
   },
@@ -364,5 +441,6 @@ export {
   safeParseTileflowRuntimeManifest,
   tileflowRuntimeManifestLimits,
   tileflowRuntimeManifestSchema,
-  tileflowRuntimeManifestVersion
+  tileflowRuntimeManifestVersion,
+  tileflowTimeOfDayManifestVersion
 };

package/dist/native-profile.js

@@ -8744,6 +8744,7 @@ var classicManifestSchemaOperations = {
     return z3.enum(values);
   },
   literal: (value) => z3.literal(value),
+  union: (left, right) => z3.union([classic(left), classic(right)]),
   tuplePair(left, right) {
     return z3.tuple([classic(left), classic(right)]);
   },

package/dist/native.d.ts

@@ -1,3 +1,9 @@
+/** Artistic presets; selecting one never starts a clock or moves the real sun. */
+declare const tileflowTimesOfDay: readonly ["day", "dawn", "dusk", "night"];
+type TileflowTimeOfDay = (typeof tileflowTimesOfDay)[number];
+/** A named theme family points to complete, already compiled themes. */
+type TileflowTimeOfDayVariants = Readonly<Record<string, Readonly<Partial<Record<TileflowTimeOfDay, string>>>>>;
+
 /** URL resolution for native clients, without a renderer or an ambient application origin. */
 declare const tileflowNativeUrlLimits: Readonly<{
     maximumLength: 2048;
@@ -93,8 +99,10 @@ declare function validateTileflowThemeBlendSelection(value: unknown): value is T
 /** The theme nearest to a blend position, which a blend shows when it cannot blend. */
 declare function nearestTileflowBlendTheme(blend: TileflowThemeBlendSelection): string;
 
-/** The first and only public multi-theme runtime manifest contract. */
+/** The original public multi-theme runtime manifest contract. */
 declare const tileflowRuntimeManifestVersion: 1;
+/** V2 adds the optional time-of-day catalog; maps without it still publish V1. */
+declare const tileflowTimeOfDayManifestVersion: 2;
 type TileflowRuntimeColorScheme = 'dark' | 'light';
 type TileflowRuntimeManifestTheme = {
     colorScheme: TileflowRuntimeColorScheme;
@@ -117,6 +125,7 @@ type TileflowRuntimeManifestMapEntry = {
     mapId?: string;
     systemThemes?: TileflowRuntimeSystemThemes;
     themes: Record<string, TileflowRuntimeManifestTheme>;
+    timeOfDay?: TileflowTimeOfDayVariants;
     usageMode?: 'session';
     view?: TileflowViewConfig;
     worldGeneration?: 'v1';
@@ -130,7 +139,7 @@ type TileflowRuntimeManifestMapEntry = {
 type TileflowRuntimeManifest = {
     apiUrl?: string;
     maps: Record<string, TileflowRuntimeManifestMapEntry>;
-    version: typeof tileflowRuntimeManifestVersion;
+    version: typeof tileflowRuntimeManifestVersion | typeof tileflowTimeOfDayManifestVersion;
 };
 
 /** The adapter must honor the requested read bound, without first buffering an unbounded body. */
@@ -179,6 +188,7 @@ type TileflowNativeSource = {
 };
 type TileflowNativeSourceOptions = {
     theme?: string;
+    timeOfDay?: TileflowTimeOfDay;
     /** Required only for theme="system"; no ambient appearance access. */
     colorScheme?: TileflowRuntimeColorScheme;
     signal?: TileflowNativeAbortSignal;
@@ -352,4 +362,4 @@ declare function planTileflowThemeBlend(styles: readonly MapLibreStyle[], option
 /** Fills one blend template for a position. Plain values pass through unchanged. */
 declare function fillTileflowThemeBlendTemplate(template: unknown, position: number): unknown;
 
-export { type TileflowNativeAbortSignal, type TileflowNativeInitialView, type TileflowNativeInitialViewOptions, type TileflowNativeManifestAcquire, type TileflowNativeManifestLoadOptions, type TileflowNativeManifestOperation, type TileflowNativeManifestReader, type TileflowNativeManifestResponse, type TileflowNativeManifestResult, type TileflowNativeNetworkOptions, type TileflowNativeResourceUrlOptions, type TileflowNativeSource, type TileflowNativeSourceController, TileflowNativeSourceError, type TileflowNativeSourceErrorCode, type TileflowNativeSourceErrorField, type TileflowNativeSourceOptions, type TileflowNativeSourceState, TileflowNativeUrlError, type TileflowNativeUrlErrorCode, type TileflowNativeUrlField, type TileflowThemeBlendClock, TileflowThemeBlendError, type TileflowThemeBlendImage, type TileflowThemeBlendOptions, type TileflowThemeBlendPaint, type TileflowThemeBlendPlan, type TileflowThemeBlendSelection, type TileflowThemeBlendSwitch, createTileflowNativeSourceController, fillTileflowThemeBlendTemplate, loadTileflowNativeManifest, nearestTileflowBlendTheme, planTileflowThemeBlend, resolveTileflowNativeInitialView, resolveTileflowNativeManifestUrl, resolveTileflowNativeResourceUrl, tileflowNativeManifestLimits, tileflowNativeUrlLimits, tileflowThemeBlendLimits, validateTileflowThemeBlendSelection };
+export { type TileflowNativeAbortSignal, type TileflowNativeInitialView, type TileflowNativeInitialViewOptions, type TileflowNativeManifestAcquire, type TileflowNativeManifestLoadOptions, type TileflowNativeManifestOperation, type TileflowNativeManifestReader, type TileflowNativeManifestResponse, type TileflowNativeManifestResult, type TileflowNativeNetworkOptions, type TileflowNativeResourceUrlOptions, type TileflowNativeSource, type TileflowNativeSourceController, TileflowNativeSourceError, type TileflowNativeSourceErrorCode, type TileflowNativeSourceErrorField, type TileflowNativeSourceOptions, type TileflowNativeSourceState, TileflowNativeUrlError, type TileflowNativeUrlErrorCode, type TileflowNativeUrlField, type TileflowThemeBlendClock, TileflowThemeBlendError, type TileflowThemeBlendImage, type TileflowThemeBlendOptions, type TileflowThemeBlendPaint, type TileflowThemeBlendPlan, type TileflowThemeBlendSelection, type TileflowThemeBlendSwitch, type TileflowTimeOfDay, type TileflowTimeOfDayVariants, createTileflowNativeSourceController, fillTileflowThemeBlendTemplate, loadTileflowNativeManifest, nearestTileflowBlendTheme, planTileflowThemeBlend, resolveTileflowNativeInitialView, resolveTileflowNativeManifestUrl, resolveTileflowNativeResourceUrl, tileflowNativeManifestLimits, tileflowNativeUrlLimits, tileflowThemeBlendLimits, validateTileflowThemeBlendSelection };