@tileflow/core 0.1.0-alpha.0 → 0.1.0-alpha.1

package/README.md

@@ -3,19 +3,28 @@
 Typed Tileflow config helpers and the MapLibre style compiler.
 
 ```ts
-import { defineTileflow } from "@tileflow/core";
+import {defineTileflow, osm, roads} from '@tileflow/core';
 
 export default defineTileflow({
+  themes: {
+    light: {
+      mode: 'light',
+      colors: {
+        water: '#8ED6E8',
+        park: '#C3F1D5',
+        road: '#D8E0E7',
+        text: '#566371',
+      },
+    },
+  },
   maps: {
     madrid: {
-      colors: {
-        canvas: "#F8F6F1",
-        land: "#F2EEE6",
-        water: "#B6CBD8",
-        nature: "#AEBB9B",
-        road: "#DED6C8",
-        text: "#2E2E2E",
-        accent: "#C6A15B",
+      basemap: osm(),
+      theme: 'light',
+      modules: [roads({preset: 'modern', density: 'balanced'})],
+      view: {
+        center: [-3.7038, 40.4168],
+        zoom: 12,
       },
     },
   },

package/dist/index.d.ts

@@ -1,7 +1,12 @@
-type TileflowDensity = "clean" | "balanced" | "dense";
-type TileflowRoads = "hidden" | "soft" | "standard" | "detailed";
-type TileflowLabels = "none" | "essential" | "balanced" | "full";
-type TileflowPoi = "none" | "minimal" | "balanced" | "full";
+type TileflowDensity = 'clean' | 'balanced' | 'dense';
+type TileflowRoads = 'hidden' | 'soft' | 'standard' | 'detailed';
+type TileflowLabels = 'none' | 'essential' | 'balanced' | 'full';
+type TileflowPoi = 'none' | 'minimal' | 'balanced' | 'full';
+type TileflowTheme = 'standard' | 'light' | 'dark' | 'minimal' | 'osm-bright-2';
+type TileflowBuildings = 'hidden' | 'flat' | '3d';
+type TileflowTerrainMode = 'none' | 'hillshade' | '3d';
+type TileflowTerrainEncoding = 'mapbox' | 'terrarium';
+type TileflowThemeMode = 'light' | 'dark';
 type TileflowColors = {
     canvas: string;
     land: string;
@@ -15,13 +20,19 @@ type LegacyTileflowColorAliases = {
     background?: string;
     park?: string;
     building?: string;
+    roadCasing?: string;
 };
 type TileflowColorConfig = Partial<TileflowColors> & LegacyTileflowColorAliases;
-type TileflowFontWeight = "regular" | "medium" | "semibold" | "bold";
+type TileflowFontWeight = 'regular' | 'medium' | 'semibold' | 'bold';
 type TileflowTypography = {
     font?: string;
     weight?: TileflowFontWeight;
 };
+type TileflowThemeConfig = {
+    mode?: TileflowThemeMode;
+    colors?: TileflowColorConfig;
+    typography?: TileflowTypography;
+};
 type TileflowSourceLayers = {
     landuse?: string;
     park?: string;
@@ -39,18 +50,59 @@ type TileflowTiles = {
     attribution?: string;
     sourceLayers?: TileflowSourceLayers;
 };
+type TileflowTerrainConfig = {
+    attribution?: string;
+    encoding?: TileflowTerrainEncoding;
+    exaggeration?: number;
+    mode?: TileflowTerrainMode;
+    sourceId?: string;
+    tileset?: string;
+    url?: string;
+};
+type TileflowTerrain = TileflowTerrainMode | TileflowTerrainConfig;
+type TileflowViewConfig = {
+    bearing?: number;
+    center?: readonly [number, number];
+    zoom?: number;
+};
+type TileflowOsmBasemapConfig = {
+    type: 'osm';
+    attribution?: string;
+    glyphs?: string;
+    sourceId?: string;
+    sourceLayers?: TileflowSourceLayers;
+    sprite?: string;
+    tileset?: string;
+    url?: string;
+};
+type TileflowBasemapConfig = TileflowOsmBasemapConfig;
+type TileflowOsmBasemapOptions = Omit<TileflowOsmBasemapConfig, 'type'>;
+type TileflowRoadsModulePreset = 'modern' | 'minimal';
+type TileflowRoadsModuleConfig = {
+    type: 'roads';
+    density?: TileflowDensity;
+    preset?: TileflowRoadsModulePreset;
+};
+type TileflowRoadsModuleOptions = Omit<TileflowRoadsModuleConfig, 'type'>;
+type TileflowModuleConfig = TileflowRoadsModuleConfig;
 type TileflowConfig = {
+    basemap?: TileflowBasemapConfig;
     name?: string;
     tileset?: string;
+    theme?: TileflowTheme | string | TileflowThemeConfig;
+    modules?: readonly TileflowModuleConfig[];
     colors?: TileflowColorConfig;
     typography?: TileflowTypography;
     density?: TileflowDensity;
     roads?: TileflowRoads;
     labels?: TileflowLabels;
     poi?: TileflowPoi;
+    buildings?: TileflowBuildings;
+    terrain?: TileflowTerrain;
     glyphs?: string;
     sprite?: string;
     tiles?: TileflowTiles;
+    view?: TileflowViewConfig;
     /**
      * Domains allowed to load this map in production (e.g. "example.com" or
      * "*.example.com"). When set, tile and session requests from other
@@ -67,10 +119,12 @@ type TileflowTilesetConfig = {
     sourceLayers?: TileflowSourceLayers;
 };
 type TileflowProjectConfig = {
+    themes?: Record<string, TileflowThemeConfig>;
     tilesets?: Record<string, TileflowTilesetConfig>;
     maps: Record<string, TileflowMapConfig>;
 };
 type TileflowStyleOptions = {
+    themes?: Record<string, TileflowThemeConfig>;
     tileBaseUrl?: string;
     tileset?: string;
 };
@@ -87,10 +141,11 @@ type MapLibreStyle = {
     sprite?: string;
     sources: Record<string, Record<string, unknown>>;
     layers: Array<Record<string, unknown>>;
+    terrain?: Record<string, unknown>;
     metadata?: Record<string, unknown>;
 };
 type ValidationMessage = {
-    level: "error" | "warning";
+    level: 'error' | 'warning';
     path: string;
     message: string;
 };
@@ -98,8 +153,6 @@ type ValidationResult = {
     valid: boolean;
     messages: ValidationMessage[];
 };
-declare function defineTileflow(config: TileflowProjectConfig): TileflowProjectConfig;
-declare function validateConfig(input: unknown): ValidationResult;
 declare function createStyle(input?: TileflowConfig, options?: TileflowStyleOptions): MapLibreStyle;
 declare function createStyleFromProject(projectConfig: TileflowProjectConfig, mapName: string, options?: TileflowStyleOptions): MapLibreStyle;
 declare function createManifest(projectConfig: TileflowProjectConfig, options?: {
@@ -108,4 +161,12 @@ declare function createManifest(projectConfig: TileflowProjectConfig, options?:
 }): TileflowManifest;
 declare function getDefaultColors(): TileflowColors;
 
-export { type MapLibreStyle, type TileflowColorConfig, type TileflowColors, type TileflowConfig, type TileflowDensity, type TileflowFontWeight, type TileflowLabels, type TileflowManifest, type TileflowMapConfig, type TileflowPoi, type TileflowProjectConfig, type TileflowRoads, type TileflowSourceLayers, type TileflowStyleOptions, type TileflowTiles, type TileflowTilesetConfig, type TileflowTypography, type ValidationMessage, type ValidationResult, createManifest, createStyle, createStyleFromProject, defineTileflow, getDefaultColors, validateConfig };
+declare function validateConfig(input: unknown): ValidationResult;
+
+declare function defineTileflow(config: TileflowProjectConfig): TileflowProjectConfig;
+
+declare function osm(options?: TileflowOsmBasemapOptions): TileflowOsmBasemapConfig;
+
+declare function roads(options?: TileflowRoadsModuleOptions): TileflowRoadsModuleConfig;
+
+export { type MapLibreStyle, type TileflowBasemapConfig, type TileflowBuildings, type TileflowColorConfig, type TileflowColors, type TileflowConfig, type TileflowDensity, type TileflowFontWeight, type TileflowLabels, type TileflowManifest, type TileflowMapConfig, type TileflowModuleConfig, type TileflowOsmBasemapConfig, type TileflowOsmBasemapOptions, type TileflowPoi, type TileflowProjectConfig, type TileflowRoads, type TileflowRoadsModuleConfig, type TileflowRoadsModuleOptions, type TileflowRoadsModulePreset, type TileflowSourceLayers, type TileflowStyleOptions, type TileflowTerrain, type TileflowTerrainConfig, type TileflowTerrainEncoding, type TileflowTerrainMode, type TileflowTheme, type TileflowThemeConfig, type TileflowThemeMode, type TileflowTiles, type TileflowTilesetConfig, type TileflowTypography, type TileflowViewConfig, type ValidationMessage, type ValidationResult, createManifest, createStyle, createStyleFromProject, defineTileflow, getDefaultColors, osm, roads, validateConfig };

package/dist/index.js

@@ -1,31 +1,97 @@
-// src/index.ts
+// src/basemaps.ts
+function osm(options = {}) {
+  return {
+    type: "osm",
+    ...options
+  };
+}
+
+// src/schema.ts
 import { z } from "zod";
+var legacyThemeNames = /* @__PURE__ */ new Set(["standard", "light", "dark", "minimal", "osm-bright-2"]);
 var hexColorSchema = z.string().regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, {
-  message: "Expected a hex color like #F8F6F1 or #F8F6F1FF"
+  message: "Expected a hex color like #F6F7F3 or #F6F7F3FF"
+});
+var colorConfigSchema = z.object({
+  canvas: hexColorSchema.optional(),
+  land: hexColorSchema.optional(),
+  background: hexColorSchema.optional(),
+  water: hexColorSchema.optional(),
+  nature: hexColorSchema.optional(),
+  text: hexColorSchema.optional(),
+  accent: hexColorSchema.optional(),
+  park: hexColorSchema.optional(),
+  road: hexColorSchema.optional(),
+  roadCasing: hexColorSchema.optional(),
+  building: hexColorSchema.optional()
+});
+var typographySchema = z.object({
+  font: z.string().trim().min(1).optional(),
+  weight: z.enum(["regular", "medium", "semibold", "bold"]).optional()
+});
+var themeConfigSchema = z.object({
+  mode: z.enum(["light", "dark"]).optional(),
+  colors: colorConfigSchema.optional(),
+  typography: typographySchema.optional()
+});
+var sourceLayersSchema = z.object({
+  landuse: z.string().optional(),
+  park: z.string().optional(),
+  water: z.string().optional(),
+  road: z.string().optional(),
+  building: z.string().optional(),
+  boundary: z.string().optional(),
+  place: z.string().optional(),
+  poi: z.string().optional()
+});
+var basemapSchema = z.object({
+  type: z.literal("osm"),
+  attribution: z.string().optional(),
+  glyphs: z.string().min(1).optional(),
+  sourceId: z.string().min(1).optional(),
+  sourceLayers: sourceLayersSchema.optional(),
+  sprite: z.string().min(1).optional(),
+  tileset: z.string().trim().min(1).optional(),
+  url: z.url().optional()
+});
+var roadsModuleSchema = z.object({
+  type: z.literal("roads"),
+  density: z.enum(["clean", "balanced", "dense"]).optional(),
+  preset: z.enum(["modern", "minimal"]).optional()
+});
+var moduleSchema = z.discriminatedUnion("type", [roadsModuleSchema]);
+var viewSchema = z.object({
+  bearing: z.number().finite().min(-180).max(180).optional(),
+  center: z.tuple([z.number().finite(), z.number().finite()]).refine(([lng, lat]) => lng >= -180 && lng <= 180 && lat >= -90 && lat <= 90, {
+    message: "Expected center as [lng, lat] within world bounds"
+  }).optional(),
+  zoom: z.number().finite().min(0).max(24).optional()
 });
 var configSchema = z.object({
+  basemap: basemapSchema.optional(),
   name: z.string().min(1).optional(),
   tileset: z.string().trim().min(1).optional(),
-  colors: z.object({
-    canvas: hexColorSchema.optional(),
-    land: hexColorSchema.optional(),
-    background: hexColorSchema.optional(),
-    water: hexColorSchema.optional(),
-    nature: hexColorSchema.optional(),
-    text: hexColorSchema.optional(),
-    accent: hexColorSchema.optional(),
-    park: hexColorSchema.optional(),
-    road: hexColorSchema.optional(),
-    building: hexColorSchema.optional()
-  }).optional(),
-  typography: z.object({
-    font: z.string().trim().min(1).optional(),
-    weight: z.enum(["regular", "medium", "semibold", "bold"]).optional()
-  }).optional(),
+  theme: z.union([z.string().trim().min(1), themeConfigSchema]).optional(),
+  modules: z.array(moduleSchema).optional(),
+  colors: colorConfigSchema.optional(),
+  typography: typographySchema.optional(),
   density: z.enum(["clean", "balanced", "dense"]).optional(),
   roads: z.enum(["hidden", "soft", "standard", "detailed"]).optional(),
   labels: z.enum(["none", "essential", "balanced", "full"]).optional(),
   poi: z.enum(["none", "minimal", "balanced", "full"]).optional(),
+  buildings: z.enum(["hidden", "flat", "3d"]).optional(),
+  terrain: z.union([
+    z.enum(["none", "hillshade", "3d"]),
+    z.object({
+      attribution: z.string().optional(),
+      encoding: z.enum(["mapbox", "terrarium"]).optional(),
+      exaggeration: z.number().min(0).max(10).optional(),
+      mode: z.enum(["none", "hillshade", "3d"]).optional(),
+      sourceId: z.string().min(1).optional(),
+      tileset: z.string().trim().min(1).optional(),
+      url: z.url().optional()
+    })
+  ]).optional(),
   glyphs: z.string().min(1).optional(),
   sprite: z.string().min(1).optional(),
   tiles: z.object({
@@ -33,40 +99,88 @@ var configSchema = z.object({
     tileset: z.string().trim().min(1).optional(),
     url: z.url().optional(),
     attribution: z.string().optional(),
-    sourceLayers: z.object({
-      landuse: z.string().optional(),
-      park: z.string().optional(),
-      water: z.string().optional(),
-      road: z.string().optional(),
-      building: z.string().optional(),
-      boundary: z.string().optional(),
-      place: z.string().optional(),
-      poi: z.string().optional()
-    }).optional()
+    sourceLayers: sourceLayersSchema.optional()
   }).optional(),
+  view: viewSchema.optional(),
   allowedOrigins: z.array(z.string().trim().min(1).max(253)).max(20).optional()
 });
 var tilesetConfigSchema = z.object({
   id: z.string().trim().min(1).optional(),
   name: z.string().trim().min(1).optional(),
   attribution: z.string().optional(),
-  sourceLayers: z.object({
-    landuse: z.string().optional(),
-    park: z.string().optional(),
-    water: z.string().optional(),
-    road: z.string().optional(),
-    building: z.string().optional(),
-    boundary: z.string().optional(),
-    place: z.string().optional(),
-    poi: z.string().optional()
-  }).optional()
+  sourceLayers: sourceLayersSchema.optional()
 });
 var projectConfigSchema = z.object({
+  themes: z.record(z.string(), themeConfigSchema).optional(),
   tilesets: z.record(z.string(), tilesetConfigSchema).optional(),
   maps: z.record(z.string(), configSchema).refine((maps) => {
     return Object.keys(maps).length > 0;
   }, "Expected at least one map")
 });
+function validateConfig(input) {
+  if (isProjectConfigLike(input)) {
+    const parsed2 = projectConfigSchema.safeParse(input);
+    if (parsed2.success) {
+      const messages = validateProjectThemeReferences(parsed2.data);
+      if (messages.length > 0) {
+        return { valid: false, messages };
+      }
+      return { valid: true, messages: [] };
+    }
+    return {
+      valid: false,
+      messages: parsed2.error.issues.map((issue) => ({
+        level: "error",
+        path: issue.path.join(".") || "config",
+        message: issue.message
+      }))
+    };
+  }
+  const parsed = configSchema.safeParse(input);
+  if (parsed.success) {
+    const messages = validateMapThemeReference(parsed.data, void 0, "theme");
+    if (messages.length > 0) {
+      return { valid: false, messages };
+    }
+    return { valid: true, messages: [] };
+  }
+  return {
+    valid: false,
+    messages: parsed.error.issues.map((issue) => ({
+      level: "error",
+      path: issue.path.join(".") || "config",
+      message: issue.message
+    }))
+  };
+}
+function isProjectConfigLike(input) {
+  return Boolean(
+    input && typeof input === "object" && "maps" in input && typeof input.maps === "object"
+  );
+}
+function validateProjectThemeReferences(project) {
+  const themeNames = new Set(Object.keys(project.themes ?? {}));
+  return Object.entries(project.maps).flatMap(
+    ([mapName, mapConfig]) => validateMapThemeReference(mapConfig, themeNames, `maps.${mapName}.theme`)
+  );
+}
+function validateMapThemeReference(config, themeNames, path) {
+  if (typeof config.theme !== "string") {
+    return [];
+  }
+  if (legacyThemeNames.has(config.theme) || themeNames?.has(config.theme)) {
+    return [];
+  }
+  return [
+    {
+      level: "error",
+      path,
+      message: `Unknown Tileflow theme "${config.theme}"`
+    }
+  ];
+}
+
+// src/compiler.ts
 var defaultSourceLayers = {
   landuse: "landuse",
   park: "park",
@@ -78,20 +192,97 @@ var defaultSourceLayers = {
   poi: "poi"
 };
 var defaultColors = {
-  canvas: "#F8F6F1",
-  land: "#F2EEE6",
-  water: "#B6CBD8",
-  nature: "#AEBB9B",
-  road: "#DED6C8",
-  text: "#2E2E2E",
-  accent: "#C6A15B"
+  canvas: "#F6F7F3",
+  land: "#F1F3ED",
+  water: "#A9D3F5",
+  nature: "#CDE8B5",
+  road: "#FFFFFF",
+  text: "#3C4043",
+  accent: "#F4C95D"
 };
 var defaultConfig = {
-  density: "clean",
-  roads: "soft",
-  labels: "essential",
+  density: "balanced",
+  roads: "standard",
+  labels: "balanced",
   poi: "minimal"
 };
+var themePresets = {
+  standard: {
+    colors: defaultColors,
+    density: "balanced",
+    labels: "balanced",
+    poi: "minimal",
+    roads: "standard"
+  },
+  light: {
+    colors: {
+      canvas: "#F9FAF8",
+      land: "#F6F7F3",
+      water: "#C5E1F5",
+      nature: "#DDEED2",
+      road: "#FFFFFF",
+      building: "#ECEAE4",
+      text: "#5F6368",
+      accent: "#C9D1D9"
+    },
+    density: "clean",
+    labels: "essential",
+    poi: "minimal",
+    roads: "standard"
+  },
+  dark: {
+    colors: {
+      canvas: "#1C2228",
+      land: "#232B32",
+      water: "#18384D",
+      nature: "#274230",
+      road: "#39434D",
+      building: "#2F363D",
+      text: "#D7DEE6",
+      accent: "#E4B857"
+    },
+    density: "balanced",
+    labels: "balanced",
+    poi: "minimal",
+    roads: "standard"
+  },
+  minimal: {
+    colors: {
+      canvas: "#FAFAF8",
+      land: "#F7F7F2",
+      water: "#D6EAF6",
+      nature: "#E5EEDB",
+      road: "#FFFFFF",
+      building: "#F0EEE8",
+      text: "#697079",
+      accent: "#B8C0CA"
+    },
+    density: "clean",
+    labels: "essential",
+    poi: "none",
+    roads: "soft"
+  },
+  // "OSM Bright 2" — Google Maps-inspired palette. Warm-neutral land, soft
+  // blue water, muted green parks, white roads on a light gray canvas, and a
+  // warm yellow accent that drives the highway color once the class-based road
+  // engine lands. Tuned to read as a familiar navigation basemap.
+  "osm-bright-2": {
+    colors: {
+      canvas: "#EBE9E4",
+      land: "#F5F4F1",
+      water: "#AADAFF",
+      nature: "#C7E6A8",
+      road: "#FFFFFF",
+      building: "#EFEDE7",
+      text: "#5F6368",
+      accent: "#F9C97C"
+    },
+    density: "balanced",
+    labels: "balanced",
+    poi: "balanced",
+    roads: "detailed"
+  }
+};
 var defaultTypography = {
   font: "Noto Sans",
   weight: "regular"
@@ -104,23 +295,6 @@ var fontWeightLabels = {
 };
 var defaultTileBaseUrl = "https://api.tileflow.dev";
 var defaultTileset = "world";
-function defineTileflow(config) {
-  return config;
-}
-function validateConfig(input) {
-  const parsed = isProjectConfigLike(input) ? projectConfigSchema.safeParse(input) : configSchema.safeParse(input);
-  if (parsed.success) {
-    return { valid: true, messages: [] };
-  }
-  return {
-    valid: false,
-    messages: parsed.error.issues.map((issue) => ({
-      level: "error",
-      path: issue.path.join(".") || "config",
-      message: issue.message
-    }))
-  };
-}
 function createStyle(input = {}, options = {}) {
   const parsed = configSchema.safeParse(input);
   if (!parsed.success) {
@@ -128,53 +302,83 @@ function createStyle(input = {}, options = {}) {
     throw new Error(`Invalid Tileflow config. ${message}`);
   }
   const config = parsed.data;
-  const density = config.density ?? defaultConfig.density;
-  const roads = config.roads ?? defaultConfig.roads;
-  const labels = config.labels ?? defaultConfig.labels;
-  const poi = config.poi ?? defaultConfig.poi;
-  const colors = resolveColors(config.colors);
-  const sourceId = config.tiles?.sourceId ?? "tileflow";
+  const basemap = config.basemap ?? osm();
+  const theme = resolveTheme(config.theme, options.themes);
+  const density = config.density ?? theme.preset.density ?? defaultConfig.density;
+  const roadModule = config.modules?.find(
+    (moduleConfig) => moduleConfig.type === "roads"
+  );
+  const roads2 = resolveRoads(config.roads, roadModule, theme.preset.roads ?? defaultConfig.roads);
+  const labels = config.labels ?? theme.preset.labels ?? defaultConfig.labels;
+  const poi = config.poi ?? theme.preset.poi ?? defaultConfig.poi;
+  const buildings = config.buildings ?? "flat";
+  const colors = resolveColors(config.colors, theme.colors);
+  const sourceId = config.tiles?.sourceId ?? basemap.sourceId ?? "tileflow";
   const tileBaseUrl = normalizeBaseUrl(options.tileBaseUrl);
-  const tileset = options.tileset ?? config.tileset ?? config.tiles?.tileset ?? defaultTileset;
-  const tilesUrl = config.tiles?.url ?? `${tileBaseUrl}/tiles/${tileset}/tiles.json`;
-  const typography = resolveTypography(config.typography, defaultTypography);
+  const tileset = options.tileset ?? config.tileset ?? config.tiles?.tileset ?? basemap.tileset ?? defaultTileset;
+  const tilesUrl = config.tiles?.url ?? basemap.url ?? `${tileBaseUrl}/tiles/${tileset}/tiles.json`;
+  const typography = resolveTypography(config.typography, theme.typography);
+  const terrain = resolveTerrain(config.terrain, tileBaseUrl);
   const sourceLayers = resolveSourceLayers(
     {
       ...defaultSourceLayers,
+      ...basemap.sourceLayers,
       ...config.tiles?.sourceLayers
     },
     void 0
   );
   const layers = openMapTilesLayers(sourceId, sourceLayers, colors, {
+    buildings,
     density,
     labels,
     poi,
-    roads,
+    roads: roads2,
     typography
   });
+  const resolvedLayers = terrain ? withTerrainLayers(layers, terrain) : layers;
   const style = {
     version: 8,
     name: config.name ?? "Tileflow",
-    glyphs: config.glyphs ?? `${tileBaseUrl}/fonts/{fontstack}/{range}.pbf`,
-    ...config.sprite ? { sprite: config.sprite } : {},
+    glyphs: config.glyphs ?? basemap.glyphs ?? `${tileBaseUrl}/fonts/{fontstack}/{range}.pbf`,
+    ...config.sprite || basemap.sprite ? { sprite: config.sprite ?? basemap.sprite } : {},
     sources: {
       [sourceId]: {
         type: "vector",
         url: tilesUrl,
-        attribution: config.tiles?.attribution ?? "\xA9 OpenMapTiles \xA9 OpenStreetMap contributors"
-      }
+        attribution: config.tiles?.attribution ?? basemap.attribution ?? "\xA9 OpenMapTiles \xA9 OpenStreetMap contributors"
+      },
+      ...terrain ? {
+        [terrain.sourceId]: terrain.source
+      } : {}
     },
-    layers,
+    layers: resolvedLayers,
+    ...terrain?.mode === "3d" ? {
+      terrain: {
+        exaggeration: terrain.exaggeration,
+        source: terrain.sourceId
+      }
+    } : {},
     metadata: {
+      "tileflow:basemap": basemap.type,
+      "tileflow:theme": theme.name,
+      "tileflow:themeMode": theme.mode,
       "tileflow:density": density,
-      "tileflow:roads": roads,
+      "tileflow:roads": roads2,
       "tileflow:labels": labels,
       "tileflow:poi": poi,
+      "tileflow:buildings": buildings,
+      "tileflow:modules": config.modules?.map((moduleConfig) => moduleConfig.type) ?? [],
+      "tileflow:terrain": terrain ? {
+        encoding: terrain.source.encoding,
+        mode: terrain.mode,
+        sourceId: terrain.sourceId
+      } : void 0,
       "tileflow:typography": typography,
       "tileflow:colors": colors,
       "tileflow:tileBaseUrl": tileBaseUrl,
       "tileflow:tileset": tileset,
-      "tileflow:tiles": "tileflow"
+      "tileflow:tiles": "tileflow",
+      "tileflow:view": config.view
     }
   };
   return style;
@@ -184,25 +388,31 @@ function createStyleFromProject(projectConfig, mapName, options = {}) {
   if (!config) {
     throw new Error(`Unknown Tileflow map: ${mapName}`);
   }
-  const tilesetName = options.tileset ?? config.tileset ?? config.tiles?.tileset;
+  const tilesetName = options.tileset ?? config.tileset ?? config.tiles?.tileset ?? config.basemap?.tileset;
   const tilesetConfig = tilesetName ? projectConfig.tilesets?.[tilesetName] : void 0;
   const resolvedTileset = tilesetConfig?.id ?? tilesetName ?? defaultTileset;
+  const baseBasemap = config.basemap ?? osm();
+  const { sourceLayers: tileSourceLayers, ...tileOptions } = config.tiles ?? {};
+  const resolvedTileSourceLayers = baseBasemap.sourceLayers || !tileSourceLayers ? void 0 : resolveSourceLayers(tileSourceLayers, tilesetConfig?.sourceLayers);
   return createStyle(
     {
       ...config,
       tileset: resolvedTileset,
+      basemap: {
+        ...baseBasemap,
+        tileset: resolvedTileset,
+        attribution: baseBasemap.attribution ?? tilesetConfig?.attribution,
+        sourceLayers: resolveSourceLayers(baseBasemap.sourceLayers, tilesetConfig?.sourceLayers)
+      },
       tiles: {
-        ...config.tiles,
+        ...tileOptions,
         tileset: resolvedTileset,
-        attribution: config.tiles?.attribution ?? tilesetConfig?.attribution,
-        sourceLayers: resolveSourceLayers(
-          config.tiles?.sourceLayers,
-          tilesetConfig?.sourceLayers
-        )
+        ...resolvedTileSourceLayers ? { sourceLayers: resolvedTileSourceLayers } : {}
       }
     },
     {
       ...options,
+      themes: projectConfig.themes,
       tileset: resolvedTileset
     }
   );
@@ -215,35 +425,96 @@ function createManifest(projectConfig, options = {}) {
     version: 1,
     tileBaseUrl,
     styles: Object.fromEntries(
-      maps.map((mapName) => [
-        mapName,
-        `${styleBaseUrl}/styles/${mapName}.json`
-      ])
+      maps.map((mapName) => [mapName, `${styleBaseUrl}/styles/${mapName}.json`])
     ),
     maps: Object.fromEntries(
-      maps.map((mapName) => [
-        mapName,
-        `${styleBaseUrl}/styles/${mapName}.json`
-      ])
+      maps.map((mapName) => [mapName, `${styleBaseUrl}/styles/${mapName}.json`])
     )
   };
 }
 function getDefaultColors() {
   return defaultColors;
 }
-function resolveColors(overrides = {}) {
+function resolveTheme(theme, projectThemes) {
+  if (!theme) {
+    return resolveLegacyTheme("standard");
+  }
+  if (typeof theme === "string") {
+    const projectTheme = projectThemes?.[theme];
+    if (projectTheme) {
+      return resolveThemeConfig(theme, projectTheme);
+    }
+    if (isLegacyTheme(theme)) {
+      return resolveLegacyTheme(theme);
+    }
+    throw new Error(`Unknown Tileflow theme: ${theme}`);
+  }
+  return resolveThemeConfig("inline", theme);
+}
+function resolveLegacyTheme(theme) {
+  const preset = themePresets[theme];
+  return {
+    colors: preset.colors,
+    mode: theme === "dark" ? "dark" : "light",
+    name: theme,
+    preset,
+    typography: defaultTypography
+  };
+}
+function resolveThemeConfig(name, theme) {
+  const colors = normalizeColorAliases(theme.colors);
+  const preset = theme.mode === "dark" ? themePresets.dark : theme.mode === "light" ? themePresets.light : themePresets.standard;
+  return {
+    colors: {
+      ...preset.colors,
+      ...colors
+    },
+    mode: theme.mode,
+    name,
+    preset,
+    typography: resolveTypography(theme.typography, defaultTypography)
+  };
+}
+function isLegacyTheme(value) {
+  return value in themePresets;
+}
+function normalizeColorAliases(colors) {
+  if (!colors) {
+    return {};
+  }
+  return {
+    ...colors,
+    canvas: colors.canvas ?? colors.background,
+    nature: colors.nature ?? colors.park
+  };
+}
+function resolveRoads(legacyRoads, moduleConfig, fallback) {
+  if (!moduleConfig) {
+    return legacyRoads ?? fallback;
+  }
+  if (moduleConfig.preset === "minimal" || moduleConfig.density === "clean") {
+    return "soft";
+  }
+  if (moduleConfig.density === "dense") {
+    return "detailed";
+  }
+  return "standard";
+}
+function resolveColors(overrides = {}, defaults = defaultColors) {
   const colors = {
-    ...defaultColors,
-    canvas: overrides.canvas ?? overrides.background ?? defaultColors.canvas,
-    land: overrides.land ?? defaultColors.land,
-    water: overrides.water ?? defaultColors.water,
-    nature: overrides.nature ?? overrides.park ?? defaultColors.nature,
-    road: overrides.road ?? defaultColors.road,
-    text: overrides.text ?? defaultColors.text,
-    accent: overrides.accent ?? defaultColors.accent,
-    building: overrides.building
+    ...defaults,
+    canvas: overrides.canvas ?? overrides.background ?? defaults.canvas ?? defaultColors.canvas,
+    land: overrides.land ?? defaults.land ?? defaultColors.land,
+    water: overrides.water ?? defaults.water ?? defaultColors.water,
+    nature: overrides.nature ?? overrides.park ?? defaults.nature ?? defaults.park ?? defaultColors.nature,
+    road: overrides.road ?? defaults.road ?? defaultColors.road,
+    text: overrides.text ?? defaults.text ?? defaultColors.text,
+    accent: overrides.accent ?? defaults.accent ?? defaultColors.accent,
+    building: overrides.building ?? defaults.building,
+    roadCasing: overrides.roadCasing ?? defaults.roadCasing
   };
-  const building = colors.building ?? mix(colors.land, colors.road, 0.46);
+  const building = colors.building ?? mix(colors.land, colors.text, 0.08);
+  const roadCasing = colors.roadCasing ?? mix(colors.road, colors.text, 0.2);
   return {
     canvas: cssColor(colors.canvas),
     land: cssColor(colors.land),
@@ -253,13 +524,38 @@ function resolveColors(overrides = {}) {
     text: cssColor(colors.text),
     accent: cssColor(colors.accent),
     building: cssColor(building),
-    roadCasing: mix(colors.road, colors.text, 0.2),
+    roadCasing: cssColor(roadCasing),
     roadMajor: mix(colors.road, colors.accent, 0.16),
     roadMinor: cssColor(colors.road),
     textHalo: alpha(colors.canvas, 0.84),
     textMuted: mix(colors.text, colors.canvas, 0.42)
   };
 }
+function resolveTerrain(terrain, tileBaseUrl) {
+  if (!terrain || terrain === "none") {
+    return void 0;
+  }
+  const terrainConfig = typeof terrain === "string" ? { mode: terrain } : terrain;
+  const mode = terrainConfig.mode ?? "hillshade";
+  if (mode === "none") {
+    return void 0;
+  }
+  const sourceId = terrainConfig.sourceId ?? "tileflow-terrain";
+  const tileset = terrainConfig.tileset ?? "terrain";
+  const url = terrainConfig.url ?? `${tileBaseUrl}/tiles/${tileset}/tiles.json`;
+  const encoding = terrainConfig.encoding ?? "terrarium";
+  return {
+    exaggeration: terrainConfig.exaggeration ?? 1.2,
+    mode,
+    sourceId,
+    source: {
+      attribution: terrainConfig.attribution,
+      encoding,
+      type: "raster-dem",
+      url
+    }
+  };
+}
 function resolveTypography(overrides = {}, defaults = defaultTypography) {
   return {
     ...defaults,
@@ -282,11 +578,6 @@ function normalizeStyleBaseUrl(value) {
 function normalizeUrl(value) {
   return value.replace(/\/+$/, "");
 }
-function isProjectConfigLike(input) {
-  return Boolean(
-    input && typeof input === "object" && "maps" in input && typeof input.maps === "object"
-  );
-}
 function textFont(typography) {
   return [`${typography.font} ${fontWeightLabels[typography.weight]}`];
 }
@@ -312,34 +603,82 @@ function openMapTilesLayers(source, sourceLayers, colors, options) {
       }
     },
     fillLayer("landuse", source, sourceLayers.landuse, colors.land, 0.42),
-    fillLayer(
-      "parks",
-      source,
-      sourceLayers.park,
-      colors.nature,
-      parkOpacity(options.density)
-    ),
+    fillLayer("parks", source, sourceLayers.park, colors.nature, parkOpacity(options.density)),
     fillLayer("water", source, sourceLayers.water, colors.water, 1),
-    ...buildingLayers(source, sourceLayers.building, colors, options.density),
+    ...buildingLayers(source, sourceLayers.building, colors, options.density, options.buildings),
     ...roadLayers(source, sourceLayers.road, colors, options.roads),
     ...boundaryLayers(source, sourceLayers.boundary, colors),
-    ...labelLayers(
-      source,
-      sourceLayers.place,
-      colors,
-      options.labels,
-      options.typography
-    ),
-    ...poiLayers(
-      source,
-      sourceLayers.poi,
-      colors,
-      options.poi,
-      options.typography
-    )
+    ...labelLayers(source, sourceLayers.place, colors, options.labels, options.typography),
+    ...poiLayers(source, sourceLayers.poi, colors, options.poi, options.typography)
+  ];
+}
+function withTerrainLayers(layers, terrain) {
+  const hillshadeLayer = {
+    id: "terrain-hillshade",
+    type: "hillshade",
+    source: terrain.sourceId,
+    maxzoom: 15,
+    paint: {
+      "hillshade-accent-color": "rgba(255, 255, 255, 0.18)",
+      "hillshade-exaggeration": terrain.mode === "3d" ? 0.24 : 0.42,
+      "hillshade-highlight-color": "rgba(255, 255, 255, 0.28)",
+      "hillshade-shadow-color": "rgba(38, 44, 50, 0.34)"
+    }
+  };
+  const insertionIndex = layers.findIndex((layer) => layer.id === "water");
+  if (insertionIndex === -1) {
+    return [hillshadeLayer, ...layers];
+  }
+  return [
+    ...layers.slice(0, insertionIndex + 1),
+    hillshadeLayer,
+    ...layers.slice(insertionIndex + 1)
   ];
 }
-function buildingLayers(source, sourceLayer, colors, density) {
+function buildingLayers(source, sourceLayer, colors, density, buildings) {
+  if (buildings === "hidden") {
+    return [];
+  }
+  if (buildings === "3d") {
+    return [
+      {
+        id: "buildings-3d",
+        type: "fill-extrusion",
+        source,
+        "source-layer": sourceLayer,
+        minzoom: 14,
+        filter: ["!=", ["get", "hide_3d"], true],
+        paint: {
+          "fill-extrusion-base": [
+            "case",
+            ["has", "render_min_height"],
+            ["to-number", ["get", "render_min_height"]],
+            ["has", "min_height"],
+            ["to-number", ["get", "min_height"]],
+            0
+          ],
+          "fill-extrusion-color": colors.building,
+          "fill-extrusion-height": [
+            "interpolate",
+            ["linear"],
+            ["zoom"],
+            14,
+            0,
+            15,
+            [
+              "case",
+              ["has", "render_height"],
+              ["to-number", ["get", "render_height"]],
+              ["has", "height"],
+              ["to-number", ["get", "height"]],
+              18
+            ]
+          ],
+          "fill-extrusion-opacity": 0.72
+        }
+      }
+    ];
+  }
   if (density === "clean") {
     return [
       {
@@ -381,12 +720,12 @@ function buildingLayers(source, sourceLayer, colors, density) {
     }
   ];
 }
-function roadLayers(source, sourceLayer, colors, roads) {
-  if (roads === "hidden") {
+function roadLayers(source, sourceLayer, colors, roads2) {
+  if (roads2 === "hidden") {
     return [];
   }
-  const opacity = roads === "soft" ? 0.72 : roads === "standard" ? 0.84 : 0.96;
-  const casingOpacity = roads === "detailed" ? 0.3 : 0.16;
+  const opacity = roads2 === "soft" ? 0.72 : roads2 === "standard" ? 0.84 : 0.96;
+  const casingOpacity = roads2 === "detailed" ? 0.3 : 0.16;
   const majorRoadFilter = [
     "match",
     ["get", "class"],
@@ -395,7 +734,22 @@ function roadLayers(source, sourceLayer, colors, roads) {
     false
   ];
   const minorRoadFilter = ["!", majorRoadFilter];
+  const nonTunnelRoadFilter = ["!=", ["get", "brunnel"], "tunnel"];
   return [
+    {
+      id: "roads-tunnels-casing",
+      type: "line",
+      source,
+      "source-layer": sourceLayer,
+      minzoom: 10,
+      filter: ["==", ["get", "brunnel"], "tunnel"],
+      paint: {
+        "line-color": colors.roadCasing,
+        "line-dasharray": [0.6, 0.8],
+        "line-opacity": 0.28,
+        "line-width": ["interpolate", ["linear"], ["zoom"], 10, 0.5, 14, 1.7, 16, 3.8]
+      }
+    },
     {
       id: "roads-tunnels",
       type: "line",
@@ -406,18 +760,8 @@ function roadLayers(source, sourceLayer, colors, roads) {
       paint: {
         "line-color": colors.roadMinor,
         "line-dasharray": [0.6, 0.8],
-        "line-opacity": opacity * 0.62,
-        "line-width": [
-          "interpolate",
-          ["linear"],
-          ["zoom"],
-          10,
-          0.25,
-          14,
-          1,
-          16,
-          2.4
-        ]
+        "line-opacity": 0.2,
+        "line-width": ["interpolate", ["linear"], ["zoom"], 10, 0.25, 14, 1, 16, 2.4]
       }
     },
     {
@@ -426,20 +770,11 @@ function roadLayers(source, sourceLayer, colors, roads) {
       source,
       "source-layer": sourceLayer,
       minzoom: 6,
+      filter: nonTunnelRoadFilter,
       paint: {
         "line-color": colors.roadCasing,
         "line-opacity": casingOpacity,
-        "line-width": [
-          "interpolate",
-          ["linear"],
-          ["zoom"],
-          6,
-          0.4,
-          12,
-          1.2,
-          16,
-          4
-        ]
+        "line-width": ["interpolate", ["linear"], ["zoom"], 6, 0.4, 12, 1.2, 16, 4]
       }
     },
     {
@@ -448,21 +783,11 @@ function roadLayers(source, sourceLayer, colors, roads) {
       source,
       "source-layer": sourceLayer,
       minzoom: 6,
-      filter: minorRoadFilter,
+      filter: ["all", nonTunnelRoadFilter, minorRoadFilter],
       paint: {
         "line-color": colors.roadMinor,
         "line-opacity": opacity * 0.88,
-        "line-width": [
-          "interpolate",
-          ["linear"],
-          ["zoom"],
-          6,
-          0.2,
-          12,
-          0.8,
-          16,
-          3
-        ]
+        "line-width": ["interpolate", ["linear"], ["zoom"], 6, 0.2, 12, 0.8, 16, 3]
       }
     },
     {
@@ -471,21 +796,11 @@ function roadLayers(source, sourceLayer, colors, roads) {
       source,
       "source-layer": sourceLayer,
       minzoom: 5,
-      filter: majorRoadFilter,
+      filter: ["all", nonTunnelRoadFilter, majorRoadFilter],
       paint: {
         "line-color": colors.roadMajor,
         "line-opacity": opacity,
-        "line-width": [
-          "interpolate",
-          ["linear"],
-          ["zoom"],
-          5,
-          0.35,
-          12,
-          1.2,
-          16,
-          4
-        ]
+        "line-width": ["interpolate", ["linear"], ["zoom"], 5, 0.35, 12, 1.2, 16, 4]
       }
     },
     {
@@ -498,17 +813,7 @@ function roadLayers(source, sourceLayer, colors, roads) {
       paint: {
         "line-color": mix(colors.roadMajor, colors.canvas, 0.14),
         "line-opacity": opacity,
-        "line-width": [
-          "interpolate",
-          ["linear"],
-          ["zoom"],
-          10,
-          0.45,
-          14,
-          1.6,
-          16,
-          4.4
-        ]
+        "line-width": ["interpolate", ["linear"], ["zoom"], 10, 0.45, 14, 1.6, 16, 4.4]
       }
     }
   ];
@@ -545,17 +850,7 @@ function labelLayers(source, sourceLayer, colors, labels, typography) {
       layout: {
         "text-field": ["coalesce", ["get", "name:en"], ["get", "name"]],
         "text-font": textFont(typography),
-        "text-size": [
-          "interpolate",
-          ["linear"],
-          ["zoom"],
-          3,
-          10,
-          8,
-          13,
-          14,
-          17
-        ],
+        "text-size": ["interpolate", ["linear"], ["zoom"], 3, 10, 8, 13, 14, 17],
         "text-letter-spacing": 0,
         "text-padding": 4
       },
@@ -648,11 +943,27 @@ function roundAlpha(value) {
 function rgbToHex(r, g, b) {
   return `#${[r, g, b].map((value) => value.toString(16).padStart(2, "0")).join("")}`;
 }
+
+// src/config.ts
+function defineTileflow(config) {
+  return config;
+}
+
+// src/modules.ts
+function roads(options = {}) {
+  return {
+    type: "roads",
+    preset: options.preset ?? "modern",
+    ...options.density ? { density: options.density } : {}
+  };
+}
 export {
   createManifest,
   createStyle,
   createStyleFromProject,
   defineTileflow,
   getDefaultColors,
+  osm,
+  roads,
   validateConfig
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",
   "homepage": "https://tileflow.dev",
@@ -39,6 +39,7 @@
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean",
+    "verify": "tsx scripts/verify.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "lint": "tsc -p tsconfig.json --noEmit"
   }