@tileflow/core 0.1.0-alpha.29 → 0.1.0-alpha.30

package/dist/browser.js

@@ -2065,6 +2065,7 @@ var maxStaticImagePixels = 1280 * 1280;
 var maximumManifestBytes = 1024 * 1024;
 var maximumSessionGrantBytes = 64 * 1024;
 var manifestCache = new globalThis.Map();
+var tileflowThemeBlendLimits = Object.freeze({ maximumThemes: 8, minimumThemes: 2 });
 function getTileflowStyleFontFaces(style) {
   const input = style.metadata?.[tileflowStyleFontFacesMetadataKey];
   if (input === void 0) return [];
@@ -2201,6 +2202,876 @@ function getTileflowLocationOrigin() {
   return window.location.origin;
 }
 
+// src/theme-blend.ts
+var TileflowThemeBlendError = class extends Error {
+  name = "TileflowThemeBlendError";
+};
+var BlendLeaf = class {
+  constructor(values) {
+    this.values = values;
+  }
+  values;
+};
+var imageProperties = /* @__PURE__ */ new Set([
+  "icon-image",
+  "fill-pattern",
+  "line-pattern",
+  "background-pattern",
+  "fill-extrusion-pattern"
+]);
+var opacityProperties = {
+  background: "background-opacity",
+  circle: "circle-opacity",
+  fill: "fill-opacity",
+  "fill-extrusion": "fill-extrusion-opacity",
+  heatmap: "heatmap-opacity",
+  line: "line-opacity",
+  raster: "raster-opacity"
+};
+var featureOperators = /* @__PURE__ */ new Set([
+  "feature-state",
+  "geometry-type",
+  "get",
+  "has",
+  "id",
+  "in",
+  "properties"
+]);
+var maximumBranches = 24;
+function planTileflowThemeBlend(styles) {
+  if (styles.length < 2)
+    throw new TileflowThemeBlendError("A theme blend needs two or more themes.");
+  const [base] = styles;
+  assertSameStructure(styles, base);
+  const paints = [];
+  const switches = [];
+  const imageGroups = collectImageNames(styles, base);
+  const images = /* @__PURE__ */ new Map();
+  let splitLayers = 0;
+  let copiedLayers = 0;
+  const layers = [];
+  for (const [index, layer] of base.layers.entries()) {
+    const variants = styles.map((style) => style.layers[index]);
+    layers.push(...planLayer(variants, String(layer.type)));
+  }
+  const switchesByLayer = /* @__PURE__ */ new Map();
+  for (const entry of switches) {
+    const list = switchesByLayer.get(entry.layer) ?? [];
+    list.push(entry);
+    switchesByLayer.set(entry.layer, list);
+  }
+  const sky = differingRoot(styles, "sky");
+  const light = differingRoot(styles, "light");
+  return {
+    themes: styles.length,
+    paints,
+    images: [...images.values()],
+    switches,
+    ...sky === void 0 ? {} : { sky },
+    ...light === void 0 ? {} : { light },
+    summary: { splitLayers, copiedLayers, switchedValues: switches.length },
+    styleAt(position) {
+      const at = clampPosition(position, styles.length);
+      const dominant = Math.round(at);
+      const style = {
+        ...base,
+        layers: layers.map(
+          (layer) => fillLayer(layer, at, dominant, switchesByLayer.get(String(layer.id)))
+        )
+      };
+      if (sky !== void 0) style.sky = fillTemplate(sky, at);
+      if (light !== void 0) style.light = fillTemplate(light, at);
+      return style;
+    }
+  };
+  function planLayer(variants, type) {
+    const [layer] = variants;
+    const id = String(layer.id);
+    const paint = { ...layer.paint };
+    const layout = { ...layer.layout };
+    const follows = type === "symbol" ? "dominant" : "position";
+    const ownPaints = [];
+    const ownSwitches = [];
+    const driven = [];
+    const paintOf = (variant) => variant.paint ?? {};
+    for (const group of ["layout", "paint"]) {
+      const target = group === "paint" ? paint : layout;
+      for (const property of propertyNames(variants, group)) {
+        const values = variants.map(
+          (variant) => variant[group]?.[property]
+        );
+        if (values.every((value) => same(value, values[0]))) continue;
+        if (imageProperties.has(property)) {
+          const tuples = imageTuples(values);
+          if (tuples && tuples.every((names) => imageGroups.get(names[0])?.size === 1)) {
+            for (const names of tuples) {
+              if (names.every((name) => name === names[0])) continue;
+              images.set(JSON.stringify(names), {
+                names,
+                follows: property === "icon-image" ? "dominant" : "position"
+              });
+            }
+            continue;
+          }
+        }
+        if (group === "layout" || values.includes(void 0) || imageProperties.has(property)) {
+          ownSwitches.push({ group, property, values });
+          continue;
+        }
+        if (values.some(isDataDriven)) {
+          driven.push(property);
+          continue;
+        }
+        const template = tryMixTemplate(values);
+        if (template === void 0) {
+          ownSwitches.push({ group, property, values });
+          continue;
+        }
+        ownPaints.push({ property, template });
+        target[property] = template;
+      }
+    }
+    const planned = { ...layer, paint, layout };
+    let results = [{ layer: planned, extra: [] }];
+    if (driven.length > 0) {
+      const split = type === "symbol" ? void 0 : splitLayer();
+      const copies = split ?? (type === "symbol" ? void 0 : copyLayer());
+      if (copies) results = copies;
+      else
+        for (const property of driven)
+          ownSwitches.push({
+            group: "paint",
+            property,
+            values: variants.map((variant) => paintOf(variant)[property])
+          });
+    }
+    for (const result of results) {
+      const resultId = String(result.layer.id);
+      const overridden = new Set(result.extra.map((entry) => entry.property));
+      for (const entry of [
+        ...ownPaints.filter((own) => !overridden.has(own.property)),
+        ...result.extra
+      ])
+        paints.push({ layer: resultId, property: entry.property, template: entry.template, follows });
+      for (const entry of ownSwitches) switches.push({ layer: resultId, ...entry });
+    }
+    return results.map((result) => result.layer);
+    function splitLayer() {
+      if (isLegacyFilter(layer.filter)) return void 0;
+      const branches = splitBranches(
+        Object.fromEntries(
+          driven.map((property) => [
+            property,
+            variants.map((variant) => paintOf(variant)[property])
+          ])
+        )
+      );
+      if (!branches) return void 0;
+      const groups = /* @__PURE__ */ new Map();
+      for (const branch of branches) {
+        const key = JSON.stringify(branch.valuesByProperty);
+        let group = groups.get(key);
+        if (!group) {
+          const templates = {};
+          for (const [property, values] of Object.entries(branch.valuesByProperty)) {
+            const template = tryMixTemplate(values);
+            if (template === void 0) return void 0;
+            templates[property] = template;
+          }
+          group = { templates, conditions: [] };
+          groups.set(key, group);
+        }
+        group.conditions.push(
+          branch.conditions.length === 1 ? branch.conditions[0] : ["all", ...branch.conditions]
+        );
+      }
+      splitLayers += groups.size;
+      return [...groups.values()].map((group, number) => {
+        const chosen = group.conditions.length === 1 ? group.conditions[0] : ["any", ...group.conditions];
+        return {
+          layer: {
+            ...planned,
+            id: `${id}::branch-${number}`,
+            filter: layer.filter === void 0 ? chosen : ["all", layer.filter, chosen],
+            paint: { ...paint, ...group.templates }
+          },
+          extra: Object.entries(group.templates).filter(([, template]) => containsLeaf(template)).map(([property, template]) => ({ property, template }))
+        };
+      });
+    }
+    function copyLayer() {
+      const opacity = opacityProperties[type];
+      if (!opacity || variants.some((variant) => isDataDriven(paintOf(variant)[opacity])))
+        return void 0;
+      copiedLayers += variants.length;
+      return variants.map((variant, theme) => {
+        const weight = new BlendLeaf(variants.map((_2, other) => other === theme ? 1 : 0));
+        const template = scaleByWeight(paint[opacity] ?? 1, weight);
+        const copyPaint = { ...paint, [opacity]: template };
+        for (const property of driven) copyPaint[property] = paintOf(variant)[property];
+        return {
+          layer: { ...planned, id: `${id}::theme-${theme}`, paint: copyPaint },
+          extra: [{ property: opacity, template }]
+        };
+      });
+    }
+  }
+}
+function fillTileflowThemeBlendTemplate(template, position) {
+  return fillTemplate(template, position);
+}
+function fillLayer(layer, position, dominant, layerSwitches) {
+  const filled = { ...layer };
+  for (const group of ["layout", "paint"]) {
+    const values = layer[group];
+    if (!values) continue;
+    const out = {};
+    for (const [key, value] of Object.entries(values)) out[key] = fillTemplate(value, position);
+    for (const entry of layerSwitches ?? []) {
+      if (entry.group !== group) continue;
+      const value = entry.values[dominant];
+      if (value === void 0) delete out[entry.property];
+      else out[entry.property] = value;
+    }
+    if (Object.keys(out).length > 0) filled[group] = out;
+    else delete filled[group];
+  }
+  return filled;
+}
+function fillTemplate(node, position) {
+  if (node instanceof BlendLeaf) return mixLeaf(node.values, position);
+  if (Array.isArray(node)) return node.map((item) => fillTemplate(item, position));
+  if (node && typeof node === "object" && containsLeaf(node)) {
+    return Object.fromEntries(
+      Object.entries(node).map(([key, value]) => [key, fillTemplate(value, position)])
+    );
+  }
+  return node;
+}
+function containsLeaf(node) {
+  if (node instanceof BlendLeaf) return true;
+  if (Array.isArray(node)) return node.some(containsLeaf);
+  if (node && typeof node === "object") return Object.values(node).some(containsLeaf);
+  return false;
+}
+function mixLeaf(values, position) {
+  const at = clampPosition(position, values.length);
+  const index = Math.min(values.length - 2, Math.floor(at));
+  const t = at - index;
+  const from = values[index];
+  const to = values[index + 1];
+  if (t <= 0 || from === to) return from;
+  if (t >= 1) return to;
+  if (typeof from === "number" && typeof to === "number") return from + (to - from) * t;
+  const a = oklab(String(from));
+  const b2 = oklab(String(to));
+  if (!a || !b2) return t < 0.5 ? from : to;
+  return colourFromOklab(a.map((value, channel) => value + (b2[channel] - value) * t));
+}
+function clampPosition(position, themes) {
+  if (!Number.isFinite(position)) return 0;
+  return Math.min(themes - 1, Math.max(0, position));
+}
+function assertSameStructure(styles, base) {
+  const ids = (style) => style.layers.map((layer) => layer.id);
+  for (const style of styles) {
+    if (!same(ids(style), ids(base)))
+      throw new TileflowThemeBlendError(
+        "Blended themes must have the same layers in the same order."
+      );
+    if (!same(style.sources, base.sources))
+      throw new TileflowThemeBlendError("Blended themes must use the same sources.");
+    if (!same(style.sprite, base.sprite) || !same(style.glyphs, base.glyphs))
+      throw new TileflowThemeBlendError("Blended themes must use the same sprite and glyphs.");
+    for (const [index, layer] of style.layers.entries()) {
+      const other = base.layers[index];
+      for (const key of ["type", "source", "source-layer", "filter", "minzoom", "maxzoom"])
+        if (!same(layer[key], other[key]))
+          throw new TileflowThemeBlendError(
+            `Blended themes differ in ${key} of layer ${JSON.stringify(layer.id)}.`
+          );
+    }
+  }
+}
+function propertyNames(variants, group) {
+  const names = /* @__PURE__ */ new Set();
+  for (const variant of variants)
+    for (const name of Object.keys(variant[group] ?? {})) names.add(name);
+  return [...names];
+}
+function differingRoot(styles, key) {
+  const values = styles.map((style) => style[key]);
+  if (values.every((value) => same(value, values[0]))) return void 0;
+  return tryMixTemplate(values);
+}
+function collectImageNames(styles, base) {
+  const uses = /* @__PURE__ */ new Map();
+  for (const [index] of base.layers.entries()) {
+    for (const group of ["layout", "paint"]) {
+      for (const property of imageProperties) {
+        const values = styles.map(
+          (style) => style.layers[index]?.[group]?.[property]
+        );
+        if (values[0] === void 0) continue;
+        for (const names of imageTuples(values) ?? []) {
+          const set = uses.get(names[0]) ?? /* @__PURE__ */ new Set();
+          set.add(JSON.stringify(names));
+          uses.set(names[0], set);
+        }
+      }
+    }
+  }
+  return uses;
+}
+function imageTuples(values, out = []) {
+  const [first] = values;
+  if (values.every((value) => typeof value === "string")) {
+    out.push(values);
+    return out;
+  }
+  if (!Array.isArray(first) || typeof first[0] !== "string") {
+    return values.every((value) => same(value, first)) ? out : void 0;
+  }
+  const operator = first[0];
+  if (!values.every(
+    (value) => Array.isArray(value) && value[0] === operator && value.length === first.length
+  )) {
+    return void 0;
+  }
+  const at = (index) => values.map((value) => value[index]);
+  const sameAt = (index) => at(index).every((value) => same(value, first[index]));
+  const outputs = [];
+  if (operator === "literal" || operator === "image") outputs.push(1);
+  else if (operator === "coalesce")
+    for (let index = 1; index < first.length; index += 1) outputs.push(index);
+  else if (operator === "match") {
+    if (!sameAt(1)) return void 0;
+    for (let index = 2; index < first.length - 1; index += 2) {
+      if (!sameAt(index)) return void 0;
+      outputs.push(index + 1);
+    }
+    outputs.push(first.length - 1);
+  } else if (operator === "case") {
+    for (let index = 1; index < first.length - 1; index += 2) {
+      if (!sameAt(index)) return void 0;
+      outputs.push(index + 1);
+    }
+    outputs.push(first.length - 1);
+  } else if (operator === "step") {
+    if (!sameAt(1)) return void 0;
+    outputs.push(2);
+    for (let index = 3; index < first.length; index += 2) {
+      if (!sameAt(index)) return void 0;
+      outputs.push(index + 1);
+    }
+  } else {
+    return values.every((value) => same(value, first)) ? out : void 0;
+  }
+  for (const index of outputs) if (!imageTuples(at(index), out)) return void 0;
+  return out;
+}
+function tryMixTemplate(values) {
+  const [first] = values;
+  if (values.every((value) => same(value, first))) return first;
+  if (Array.isArray(first) && first[0] !== "literal" && values.every((value) => Array.isArray(value) && value.length === first.length)) {
+    const items = [];
+    for (let index = 0; index < first.length; index += 1) {
+      const item = tryMixTemplate(values.map((value) => value[index]));
+      if (item === void 0 && first[index] !== void 0) return void 0;
+      items.push(item);
+    }
+    return items;
+  }
+  if (first && typeof first === "object" && !Array.isArray(first)) {
+    const keys = Object.keys(first);
+    if (!values.every((value) => value && typeof value === "object" && same(Object.keys(value), keys)))
+      return void 0;
+    const out = {};
+    for (const key of keys) {
+      const item = tryMixTemplate(values.map((value) => value[key]));
+      if (item === void 0) return void 0;
+      out[key] = item;
+    }
+    return out;
+  }
+  if (values.every((value) => typeof value === "number")) return new BlendLeaf(values);
+  if (values.every((value) => typeof value === "string" && oklab(value)))
+    return new BlendLeaf(values);
+  return void 0;
+}
+function isDataDriven(value) {
+  if (!Array.isArray(value)) return false;
+  if (typeof value[0] === "string" && featureOperators.has(value[0])) return true;
+  return value.some(isDataDriven);
+}
+var reads = (value, operator) => Array.isArray(value) && (value[0] === operator || value.some((item) => reads(item, operator)));
+function decisionOf(node) {
+  if (!Array.isArray(node) || typeof node[0] !== "string") return void 0;
+  const [operator] = node;
+  if (operator === "match" && isDataDriven(node[1])) {
+    const labels = [];
+    const outputs = [];
+    for (let index = 2; index < node.length - 1; index += 2) {
+      labels.push(node[index]);
+      outputs.push(node[index + 1]);
+    }
+    outputs.push(node.at(-1));
+    return {
+      index: ["match", node[1], ...labels.flatMap((label, index) => [label, index]), labels.length],
+      outputs
+    };
+  }
+  if (operator === "case") {
+    const conditions = [];
+    const outputs = [];
+    for (let index = 1; index < node.length - 1; index += 2) {
+      conditions.push(node[index]);
+      outputs.push(node[index + 1]);
+    }
+    outputs.push(node.at(-1));
+    if (!conditions.some(isDataDriven)) return void 0;
+    return {
+      index: [
+        "case",
+        ...conditions.flatMap((condition, index) => [condition, index]),
+        conditions.length
+      ],
+      outputs
+    };
+  }
+  if (operator === "step" && isDataDriven(node[1])) {
+    const outputs = [node[2]];
+    const stops = [];
+    for (let index = 3; index < node.length; index += 2) {
+      stops.push(node[index]);
+      outputs.push(node[index + 1]);
+    }
+    return {
+      index: ["step", node[1], 0, ...stops.flatMap((stop, index) => [stop, index + 1])],
+      outputs
+    };
+  }
+  return void 0;
+}
+function firstDecision(value) {
+  const decision = decisionOf(value);
+  if (decision) return decision;
+  if (!Array.isArray(value) || value[0] === "literal") return void 0;
+  for (const item of value) {
+    const found = firstDecision(item);
+    if (found) return found;
+  }
+  return void 0;
+}
+function choose(value, key, branch) {
+  const decision = decisionOf(value);
+  if (decision && JSON.stringify(decision.index) === key)
+    return choose(decision.outputs[branch], key, branch);
+  if (!Array.isArray(value) || value[0] === "literal") return value;
+  return value.map((item) => choose(item, key, branch));
+}
+function splitBranches(valuesByProperty, conditions = []) {
+  let decision;
+  for (const values of Object.values(valuesByProperty)) {
+    decision = firstDecision(values[0]);
+    if (decision) break;
+  }
+  if (!decision) {
+    const residual = Object.values(valuesByProperty).some((values) => values.some(isDataDriven));
+    return residual ? void 0 : [{ conditions, valuesByProperty }];
+  }
+  if (reads(decision.index, "zoom") || reads(decision.index, "feature-state")) return void 0;
+  const key = JSON.stringify(decision.index);
+  const branches = [];
+  for (let branch = 0; branch < decision.outputs.length; branch += 1) {
+    const chosen = Object.fromEntries(
+      Object.entries(valuesByProperty).map(([property, values]) => [
+        property,
+        values.map((value) => choose(value, key, branch))
+      ])
+    );
+    const nested = splitBranches(chosen, [...conditions, ["==", decision.index, branch]]);
+    if (!nested) return void 0;
+    branches.push(...nested);
+    if (branches.length > maximumBranches) return void 0;
+  }
+  return branches;
+}
+var isLegacyFilter = (filter) => Array.isArray(filter) && typeof filter[1] === "string" && !Array.isArray(filter[1]);
+function scaleByWeight(opacity, weight) {
+  const input = Array.isArray(opacity) ? opacity[0] === "interpolate" ? opacity[2] : opacity[1] : void 0;
+  if (Array.isArray(opacity) && (opacity[0] === "interpolate" || opacity[0] === "step") && reads(input, "zoom")) {
+    const head = opacity[0] === "interpolate" ? 3 : 2;
+    return opacity.map(
+      (item, index) => index >= head && (index - head) % 2 === (opacity[0] === "interpolate" ? 1 : 0) ? scaleByWeight(item, weight) : item
+    );
+  }
+  if (typeof opacity === "number")
+    return new BlendLeaf(weight.values.map((value) => opacity * Number(value)));
+  return ["*", opacity, weight];
+}
+function same(a, b2) {
+  return JSON.stringify(a) === JSON.stringify(b2);
+}
+var oklabCache = /* @__PURE__ */ new Map();
+function oklab(colour) {
+  const cached = oklabCache.get(colour);
+  if (cached !== void 0) return cached;
+  const rgba = parseColour(colour);
+  let result = null;
+  if (rgba) {
+    const [r, g2, b2] = rgba.slice(0, 3).map((channel) => {
+      const value = channel / 255;
+      return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+    });
+    const l2 = Math.cbrt(0.4122214708 * r + 0.5363325363 * g2 + 0.0514459929 * b2);
+    const m2 = Math.cbrt(0.2119034982 * r + 0.6806995451 * g2 + 0.1073969566 * b2);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g2 + 0.6299787005 * b2);
+    result = [
+      0.2104542553 * l2 + 0.793617785 * m2 - 0.0040720468 * s,
+      1.9779984951 * l2 - 2.428592205 * m2 + 0.4505937099 * s,
+      0.0259040371 * l2 + 0.7827717662 * m2 - 0.808675766 * s,
+      rgba[3]
+    ];
+  }
+  if (oklabCache.size > 4096) oklabCache.clear();
+  oklabCache.set(colour, result);
+  return result;
+}
+function colourFromOklab([lightness, a, b2, alpha]) {
+  const l2 = (lightness + 0.3963377774 * a + 0.2158037573 * b2) ** 3;
+  const m2 = (lightness - 0.1055613458 * a - 0.0638541728 * b2) ** 3;
+  const s = (lightness - 0.0894841775 * a - 1.291485548 * b2) ** 3;
+  const [red, green, blue] = [
+    4.0767416621 * l2 - 3.3077115913 * m2 + 0.2309699292 * s,
+    -1.2684380046 * l2 + 2.6097574011 * m2 - 0.3413193965 * s,
+    -0.0041960863 * l2 - 0.7034186147 * m2 + 1.707614701 * s
+  ].map((value) => {
+    const clamped = Math.min(1, Math.max(0, value));
+    const encoded = clamped <= 31308e-7 ? clamped * 12.92 : 1.055 * clamped ** (1 / 2.4) - 0.055;
+    return Math.round(encoded * 255);
+  });
+  return `rgba(${red}, ${green}, ${blue}, ${Number(alpha.toFixed(3))})`;
+}
+function parseColour(colour) {
+  const text = colour.trim().toLowerCase();
+  const hex = /^#([\da-f]{3,8})$/u.exec(text)?.[1];
+  if (hex && [3, 4, 6, 8].includes(hex.length)) {
+    const full = hex.length <= 4 ? [...hex].map((digit) => digit + digit).join("") : hex;
+    const channels = full.match(/../gu).map((pair) => Number.parseInt(pair, 16));
+    return [channels[0], channels[1], channels[2], channels.length > 3 ? channels[3] / 255 : 1];
+  }
+  const functional = /^(rgba?|hsla?)\(([^)]+)\)$/u.exec(text);
+  if (!functional) return null;
+  const parts = functional[2].split(/[\s,/]+/u).filter(Boolean);
+  if (parts.length < 3 || parts.length > 4) return null;
+  const alpha = parts[3] === void 0 ? 1 : parseUnit(parts[3], 1);
+  if (functional[1].startsWith("rgb")) {
+    const [r, g2, b2] = parts.slice(0, 3).map((part) => parseUnit(part, 255));
+    if ([r, g2, b2, alpha].some((value) => value === null)) return null;
+    return [r, g2, b2, alpha];
+  }
+  const hue = Number.parseFloat(parts[0]);
+  const saturation = parseUnit(parts[1], 1);
+  const light = parseUnit(parts[2], 1);
+  if (!Number.isFinite(hue) || saturation === null || light === null || alpha === null) return null;
+  const chroma = (1 - Math.abs(2 * light - 1)) * saturation;
+  const sector = (hue % 360 + 360) % 360 / 60;
+  const x3 = chroma * (1 - Math.abs(sector % 2 - 1));
+  const [r1, g1, b1] = sector < 1 ? [chroma, x3, 0] : sector < 2 ? [x3, chroma, 0] : sector < 3 ? [0, chroma, x3] : sector < 4 ? [0, x3, chroma] : sector < 5 ? [x3, 0, chroma] : [chroma, 0, x3];
+  const offset = light - chroma / 2;
+  return [(r1 + offset) * 255, (g1 + offset) * 255, (b1 + offset) * 255, alpha];
+}
+function parseUnit(part, scale) {
+  const percentage = part.endsWith("%");
+  const value = Number.parseFloat(part);
+  if (!Number.isFinite(value)) return null;
+  return percentage ? value / 100 * scale : value;
+}
+
+// src/theme-motion-browser.ts
+var settleFrames = 3;
+var settleTimeoutMs = 1e4;
+function beginTileflowStyleCrossfade(input, duration) {
+  if (duration <= 0 || !isCrossfadeMap(input)) return void 0;
+  const map = input;
+  const canvas = map.getCanvas();
+  const document2 = canvas.ownerDocument;
+  const view = document2?.defaultView;
+  if (!view || prefersReducedMotion(view)) return void 0;
+  let snapshot;
+  try {
+    map.redraw();
+    snapshot = document2.createElement("canvas");
+    snapshot.width = canvas.width;
+    snapshot.height = canvas.height;
+    const context = snapshot.getContext("2d");
+    if (!context) return void 0;
+    context.drawImage(canvas, 0, 0);
+  } catch {
+    return void 0;
+  }
+  const width = canvas.clientWidth;
+  const height = canvas.clientHeight;
+  Object.assign(snapshot.style, {
+    height: `${height}px`,
+    left: "0",
+    pointerEvents: "none",
+    position: "absolute",
+    top: "0",
+    transformOrigin: "0 0",
+    width: `${width}px`
+  });
+  snapshot.setAttribute("aria-hidden", "true");
+  snapshot.dataset.tileflowThemeCrossfade = "";
+  canvas.after(snapshot);
+  const corners = [
+    [width * 0.1, height * 0.45],
+    [width * 0.9, height * 0.45],
+    [width * 0.9, height * 0.9],
+    [width * 0.1, height * 0.9]
+  ];
+  const anchors = corners.map((corner) => map.unproject(corner));
+  const follow = () => {
+    const to = anchors.map((anchor) => map.project(anchor));
+    if (to.some((point) => !Number.isFinite(point.x) || !Number.isFinite(point.y))) return;
+    const matrix = homography(
+      corners,
+      to.map((point) => [point.x, point.y])
+    );
+    if (matrix) snapshot.style.transform = matrix3d(matrix);
+  };
+  map.on("move", follow);
+  let removed = false;
+  const remove = () => {
+    if (removed) return;
+    removed = true;
+    map.off("move", follow);
+    snapshot.remove();
+  };
+  const frame = (callback) => {
+    if (typeof view.requestAnimationFrame === "function") view.requestAnimationFrame(callback);
+    else view.setTimeout(callback, 16);
+  };
+  return {
+    cancel: remove,
+    finish(options = {}) {
+      return new Promise((resolve) => {
+        const started = view.performance?.now?.() ?? Date.now();
+        let settled = 0;
+        const check = () => {
+          if (removed) return resolve();
+          if (options.stop?.()) {
+            remove();
+            return resolve();
+          }
+          const now = view.performance?.now?.() ?? Date.now();
+          settled = map.isStyleLoaded() && map.areTilesLoaded() ? settled + 1 : 0;
+          if (settled < settleFrames && now - started < settleTimeoutMs) {
+            frame(check);
+            return;
+          }
+          snapshot.style.transition = `opacity ${duration}ms ease`;
+          snapshot.style.opacity = "0";
+          view.setTimeout(() => {
+            remove();
+            resolve();
+          }, duration + 20);
+        };
+        frame(() => frame(check));
+      });
+    }
+  };
+}
+function canBlendTileflowThemes(map) {
+  return typeof map.setPaintProperty === "function" && typeof map.setLayoutProperty === "function" && typeof map.getImage === "function" && typeof map.updateImage === "function";
+}
+function createTileflowThemeBlender(input, plan, options) {
+  if (!canBlendTileflowThemes(input)) {
+    throw new TypeError("Tileflow theme blends require a MapLibre GL JS map.");
+  }
+  const map = input;
+  const clamp = (value) => Math.min(plan.themes - 1, Math.max(0, Number.isFinite(value) ? value : 0));
+  const view = viewOf(input);
+  const positionPaints = plan.paints.filter((paint) => paint.follows === "position");
+  const dominantPaints = plan.paints.filter((paint) => paint.follows === "dominant");
+  const pixels = createImageMixer(map, plan.images);
+  const shownValues = /* @__PURE__ */ new Map();
+  let position = clamp(options.position);
+  let dominant = Math.round(position);
+  let label = dominant;
+  let fade;
+  let frameRequest;
+  let disposed = false;
+  pixels.paint("position", position);
+  pixels.paint("dominant", label);
+  const drive = (paints, at) => {
+    for (const paint of paints) {
+      const value = fillTileflowThemeBlendTemplate(paint.template, at);
+      const key = JSON.stringify(value);
+      if (shownValues.get(paint) === key) continue;
+      shownValues.set(paint, key);
+      map.setPaintProperty(paint.layer, paint.property, value, { validate: false });
+    }
+  };
+  const now = () => view?.performance?.now?.() ?? Date.now();
+  const step = () => {
+    frameRequest = void 0;
+    if (disposed || !fade) return;
+    const t = options.labelFadeMs <= 0 || !view ? 1 : Math.min(1, (now() - fade.start) / options.labelFadeMs);
+    label = fade.from + (fade.to - fade.from) * t * t * (3 - 2 * t);
+    drive(dominantPaints, label);
+    pixels.paint("dominant", label);
+    if (t >= 1) fade = void 0;
+    else schedule();
+  };
+  const schedule = () => {
+    if (frameRequest !== void 0 || !view) return;
+    frameRequest = typeof view.requestAnimationFrame === "function" ? view.requestAnimationFrame(step) : view.setTimeout(step, 16);
+  };
+  const applySwitches = (theme) => {
+    for (const entry of plan.switches) {
+      const value = entry.values[theme];
+      if (entry.group === "paint")
+        map.setPaintProperty(entry.layer, entry.property, value, { validate: false });
+      else map.setLayoutProperty(entry.layer, entry.property, value, { validate: false });
+    }
+  };
+  return {
+    get dominant() {
+      return dominant;
+    },
+    get position() {
+      return position;
+    },
+    dispose() {
+      disposed = true;
+      if (frameRequest !== void 0 && view) {
+        if (typeof view.cancelAnimationFrame === "function")
+          view.cancelAnimationFrame(frameRequest);
+        view.clearTimeout(frameRequest);
+      }
+      frameRequest = void 0;
+    },
+    set(next) {
+      if (disposed) return;
+      const target = clamp(next);
+      const reachesTheme = target % 1 === 0 && target !== position;
+      if (Math.abs(target - position) >= 25e-4 || reachesTheme) {
+        position = target;
+        drive(positionPaints, position);
+        pixels.paint("position", position);
+        if (plan.sky !== void 0 && typeof map.setSky === "function")
+          map.setSky(fillTileflowThemeBlendTemplate(plan.sky, position), { validate: false });
+        if (plan.light !== void 0 && typeof map.setLight === "function")
+          map.setLight(fillTileflowThemeBlendTemplate(plan.light, position), { validate: false });
+      }
+      const nextDominant = Math.round(target);
+      if (nextDominant === dominant) return;
+      dominant = nextDominant;
+      if (plan.switches.length > 0) {
+        const change = () => applySwitches(nextDominant);
+        if (options.cover) options.cover(change);
+        else change();
+      }
+      fade = { from: label, start: now(), to: nextDominant };
+      if (options.labelFadeMs <= 0 || !view) step();
+      else schedule();
+    }
+  };
+}
+function createImageMixer(map, images) {
+  const art = /* @__PURE__ */ new Map();
+  const shown = /* @__PURE__ */ new Map();
+  const unusable = /* @__PURE__ */ new Set();
+  const artOf = (name) => {
+    if (!art.has(name)) {
+      const image = map.getImage(name)?.data;
+      if (!image) return void 0;
+      art.set(name, { data: Uint8Array.from(image.data), height: image.height, width: image.width });
+    }
+    return art.get(name);
+  };
+  return {
+    paint(follows, position) {
+      const quantized = Math.round(position * 32) / 32;
+      for (const image of images) {
+        if (image.follows !== follows || unusable.has(image) || shown.get(image) === quantized)
+          continue;
+        const sources = image.names.map(artOf);
+        if (sources.some((source) => !source)) continue;
+        const [first] = sources;
+        if (sources.some((source) => source.width !== first.width || source.height !== first.height)) {
+          unusable.add(image);
+          continue;
+        }
+        shown.set(image, quantized);
+        const index = Math.min(sources.length - 2, Math.floor(quantized));
+        const t = quantized - index;
+        const from = sources[index];
+        const to = sources[index + 1];
+        let data = from.data;
+        if (t >= 1) data = to.data;
+        else if (t > 0 && from !== to) {
+          data = new Uint8Array(from.data.length);
+          for (let byte = 0; byte < data.length; byte += 1)
+            data[byte] = from.data[byte] + (to.data[byte] - from.data[byte]) * t;
+        }
+        map.updateImage(image.names[0], { data, height: from.height, width: from.width });
+      }
+    }
+  };
+}
+function isCrossfadeMap(map) {
+  return typeof map.getCanvas === "function" && typeof map.redraw === "function" && typeof map.project === "function" && typeof map.unproject === "function" && typeof map.isStyleLoaded === "function" && typeof map.areTilesLoaded === "function";
+}
+function viewOf(map) {
+  if (typeof map.getCanvas !== "function") return void 0;
+  try {
+    return map.getCanvas().ownerDocument?.defaultView ?? void 0;
+  } catch {
+    return void 0;
+  }
+}
+function prefersReducedMotion(view) {
+  try {
+    return view.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
+  } catch {
+    return false;
+  }
+}
+function tileflowThemeMotionView(map) {
+  return viewOf(map);
+}
+function homography(from, to) {
+  const rows = [];
+  for (let index = 0; index < 4; index += 1) {
+    const [x3, y] = from[index];
+    const [u, v2] = to[index];
+    rows.push([x3, y, 1, 0, 0, 0, -u * x3, -u * y, u]);
+    rows.push([0, 0, 0, x3, y, 1, -v2 * x3, -v2 * y, v2]);
+  }
+  for (let column = 0; column < 8; column += 1) {
+    let pivot = column;
+    for (let row = column + 1; row < 8; row += 1)
+      if (Math.abs(rows[row][column]) > Math.abs(rows[pivot][column])) pivot = row;
+    if (Math.abs(rows[pivot][column]) < 1e-12) return void 0;
+    [rows[column], rows[pivot]] = [rows[pivot], rows[column]];
+    for (let row = 0; row < 8; row += 1) {
+      if (row === column) continue;
+      const factor = rows[row][column] / rows[column][column];
+      for (let k2 = column; k2 <= 8; k2 += 1) rows[row][k2] -= factor * rows[column][k2];
+    }
+  }
+  return [...rows.map((row, index) => row[8] / row[index]), 1];
+}
+function matrix3d(matrix) {
+  const [a, b2, c, d, e, f, g2, h, i2] = matrix.map(
+    (value) => Math.abs(value) < 1e-12 ? 0 : Number(value.toPrecision(10))
+  );
+  return `matrix3d(${a},${d},0,${g2},${b2},${e},0,${h},0,0,1,0,${c},${f},0,${i2})`;
+}
+
 // src/atmosphere.ts
 var tileflowAtmosphereMetadataKey = "tileflow:atmosphere";
 function readTileflowAtmosphere(value) {
@@ -4081,11 +4952,22 @@ function handleSystemColorSchemeChange() {
   systemColorScheme = next;
   for (const listener of systemColorSchemeListeners) listener(next);
 }
+var maximumBlendThemes = 8;
+var maximumTransitionMs = 5e3;
+var blendLabelFadeMs = 450;
+var maximumTileflowBlendStyleBytes = 16 * 1024 * 1024;
 function createTileflowThemeController(options) {
   assertConcreteRuntimeTheme(options.initial, "initial");
   const loadFonts = options.loadFonts ?? ((runtimeStyle) => loadTileflowStyleFonts(runtimeStyle.style, { fontFaces: runtimeStyle.fontFaces }));
+  const loadStyle = options.loadStyle ?? loadTileflowBlendStyle;
   const timeoutMs = normalizeThemeTransitionTimeout(options.timeoutMs);
+  const defaultTransition = normalizeThemeTransitionDuration(options.transition);
+  const styleIdentities = /* @__PURE__ */ new WeakMap();
+  let nextStyleIdentity = 0;
   let current = options.initial;
+  let shown = { style: options.initial.style };
+  let activeBlend;
+  let pendingBlend;
   let disposed = false;
   let requestId = 0;
   let applyQueue = Promise.resolve();
@@ -4093,23 +4975,67 @@ function createTileflowThemeController(options) {
     dispose() {
       disposed = true;
       requestId += 1;
+      activeBlend?.blender.dispose();
+    },
+    getBlend() {
+      if (!activeBlend) return void 0;
+      return {
+        position: activeBlend.blender.position,
+        themes: activeBlend.themes.map((theme) => theme.theme)
+      };
     },
     getCurrent() {
       return current;
     },
-    setTheme(style) {
+    setBlend(request, changeOptions) {
+      const targetTheme = nearestTheme(request);
+      const invalid = validateBlendRequest(request);
+      if (invalid) return Promise.resolve({ error: invalid, status: "failed", theme: targetTheme });
+      if (disposed) return Promise.resolve(disposedResult(targetTheme));
+      const transition = transitionOf(changeOptions);
+      if (transition instanceof TypeError)
+        return Promise.resolve({ error: transition, status: "failed", theme: targetTheme });
+      const key = blendKey(request.themes);
+      if (activeBlend?.key === key) {
+        requestId += 1;
+        activeBlend.blender.set(request.position);
+        current = activeBlend.themes[activeBlend.blender.dominant];
+        return Promise.resolve({ status: "applied", theme: current.theme });
+      }
+      if (pendingBlend?.key === key) {
+        pendingBlend.position = request.position;
+        return pendingBlend.promise;
+      }
+      const runId = ++requestId;
+      options.onTransition?.({ currentTheme: current.theme, phase: "preloading", targetTheme });
+      const pending = { key, position: request.position, promise: void 0 };
+      pending.promise = prepareBlend(request.themes).then(
+        (plan) => enqueue(runId, {
+          key,
+          kind: "blend",
+          plan,
+          position: () => pending.position,
+          themes: request.themes,
+          transition
+        }),
+        (error) => handlePreloadFailure(runId, targetTheme, error)
+      ).finally(() => {
+        if (pendingBlend === pending) pendingBlend = void 0;
+      });
+      pendingBlend = pending;
+      return pending.promise;
+    },
+    setTheme(style, changeOptions) {
       const invalidTheme = validateConcreteRuntimeTheme(style, "target");
       if (invalidTheme) {
         return Promise.resolve({ error: invalidTheme, status: "failed", theme: style.theme });
       }
-      if (disposed) {
-        return Promise.resolve({
-          error: new Error("Tileflow theme controller is disposed."),
-          status: "failed",
-          theme: style.theme
-        });
-      }
+      if (disposed) return Promise.resolve(disposedResult(style.theme));
+      const transition = transitionOf(changeOptions);
+      if (transition instanceof TypeError)
+        return Promise.resolve({ error: transition, status: "failed", theme: style.theme });
       const runId = ++requestId;
+      pendingBlend = void 0;
       options.onTransition?.({
         currentTheme: current.theme,
         phase: "preloading",
@@ -4119,18 +5045,54 @@ function createTileflowThemeController(options) {
       try {
         preloaded = loadFonts(style);
       } catch (error) {
-        return Promise.resolve(handlePreloadFailure(runId, style, error));
+        return Promise.resolve(handlePreloadFailure(runId, style.theme, error));
       }
       return preloaded.then(
-        () => enqueueTheme(runId, style),
-        (error) => handlePreloadFailure(runId, style, error)
+        () => enqueue(runId, { kind: "theme", style, transition }),
+        (error) => handlePreloadFailure(runId, style.theme, error)
       );
     }
   };
-  function enqueueTheme(runId, style) {
+  function transitionOf(changeOptions) {
+    if (changeOptions?.transition === void 0) return defaultTransition;
+    try {
+      return normalizeThemeTransitionDuration(changeOptions.transition);
+    } catch (error) {
+      return error;
+    }
+  }
+  function blendKey(themes) {
+    return JSON.stringify(
+      themes.map((theme) => {
+        if (typeof theme.style === "string") return [theme.theme, theme.style];
+        let identity = styleIdentities.get(theme.style);
+        if (identity === void 0) {
+          nextStyleIdentity += 1;
+          identity = nextStyleIdentity;
+          styleIdentities.set(theme.style, identity);
+        }
+        return [theme.theme, identity];
+      })
+    );
+  }
+  async function prepareBlend(themes) {
+    if (!canBlendTileflowThemes(options.map)) {
+      throw new TypeError("Tileflow theme blends require a MapLibre GL JS map.");
+    }
+    const [styles] = await Promise.all([
+      Promise.all(
+        themes.map(
+          (theme) => typeof theme.style === "string" ? loadStyle(theme.style) : Promise.resolve(theme.style)
+        )
+      ),
+      Promise.all(themes.map((theme) => loadFonts(theme)))
+    ]);
+    return planTileflowThemeBlend(styles);
+  }
+  function enqueue(runId, target) {
     const operation = applyQueue.then(
-      () => applyTheme(runId, style),
-      () => applyTheme(runId, style)
+      () => applyTarget(runId, target),
+      () => applyTarget(runId, target)
     );
     applyQueue = operation.then(
       () => void 0,
@@ -4138,59 +5100,160 @@ function createTileflowThemeController(options) {
     );
     return operation;
   }
-  async function applyTheme(runId, style) {
-    if (disposed || runId !== requestId) return { status: "superseded", theme: style.theme };
-    const previous = current;
-    options.onTransition?.({
-      currentTheme: previous.theme,
-      phase: "applying",
-      targetTheme: style.theme
-    });
+  function targetThemeOf(target) {
+    return target.kind === "theme" ? target.style.theme : target.themes[Math.round(clampBlendPosition(target.position(), target.themes.length))]?.theme;
+  }
+  async function applyTarget(runId, target) {
+    const targetTheme = targetThemeOf(target);
+    if (disposed || runId !== requestId) return { status: "superseded", theme: targetTheme };
+    const previous = { current, shown };
+    options.onTransition?.({ currentTheme: previous.current.theme, phase: "applying", targetTheme });
+    const cover = beginTileflowStyleCrossfade(options.map, target.transition);
+    activeBlend?.blender.dispose();
+    activeBlend = void 0;
+    const styleInput = target.kind === "theme" ? target.style.style : target.plan.styleAt(target.position());
     try {
-      await applyMapStyle(options.map, style.style, timeoutMs);
-      if (disposed) return { status: "superseded", theme: style.theme };
+      await applyMapStyle(options.map, styleInput, timeoutMs);
+      if (disposed) {
+        cover?.cancel();
+        return { status: "superseded", theme: targetTheme };
+      }
       if (runId !== requestId) {
+        cover?.cancel();
         try {
-          await applyMapStyle(options.map, current.style, timeoutMs);
+          await restore(previous);
         } catch {
         }
-        return { status: "superseded", theme: style.theme };
+        return { status: "superseded", theme: targetTheme };
+      }
+      if (target.kind === "theme") {
+        current = target.style;
+        shown = { style: styleInput };
+      } else {
+        const blender = createBlender(target.plan, target.position());
+        activeBlend = { blender, key: target.key, plan: target.plan, themes: target.themes };
+        shown = { blend: activeBlend, style: styleInput };
+        current = target.themes[blender.dominant];
+        if (pendingBlend?.key === target.key) pendingBlend = void 0;
       }
-      current = style;
+      await cover?.finish({ stop: () => disposed || runId !== requestId });
       options.onTransition?.({
-        currentTheme: style.theme,
+        currentTheme: current.theme,
         phase: "ready",
-        targetTheme: style.theme
+        targetTheme: current.theme
       });
-      return { status: "applied", theme: style.theme };
+      return { status: "applied", theme: current.theme };
     } catch (error) {
+      cover?.cancel();
       const normalized = normalizeThemeTransitionError(error, "Tileflow theme change failed.");
       try {
-        await applyMapStyle(options.map, previous.style, timeoutMs);
-        current = previous;
+        await restore(previous);
       } catch {
       }
-      if (disposed || runId !== requestId) return { status: "superseded", theme: style.theme };
+      if (disposed || runId !== requestId) return { status: "superseded", theme: targetTheme };
       options.onTransition?.({
         currentTheme: current.theme,
         error: normalized,
         phase: "error",
-        targetTheme: style.theme
+        targetTheme
       });
-      return { error: normalized, status: "failed", theme: style.theme };
+      return { error: normalized, status: "failed", theme: targetTheme };
+    }
+  }
+  function createBlender(plan, position) {
+    return createTileflowThemeBlender(options.map, plan, {
+      cover(change) {
+        const fade = beginTileflowStyleCrossfade(options.map, blendLabelFadeMs);
+        change();
+        void fade?.finish();
+      },
+      labelFadeMs: reducedMotion() ? 0 : blendLabelFadeMs,
+      position
+    });
+  }
+  async function restore(previous) {
+    const blend = previous.shown.blend;
+    if (blend) {
+      const position = blend.blender.position;
+      const style = blend.plan.styleAt(position);
+      await applyMapStyle(options.map, style, timeoutMs);
+      activeBlend = { ...blend, blender: createBlender(blend.plan, position) };
+      shown = { blend: activeBlend, style };
+    } else {
+      await applyMapStyle(options.map, previous.shown.style, timeoutMs);
+      shown = previous.shown;
     }
+    current = previous.current;
+  }
+  function reducedMotion() {
+    const view = tileflowThemeMotionView(options.map);
+    return view ? prefersReducedMotion(view) : false;
   }
-  function handlePreloadFailure(runId, style, error) {
-    if (disposed || runId !== requestId) return { status: "superseded", theme: style.theme };
+  function handlePreloadFailure(runId, targetTheme, error) {
+    if (disposed || runId !== requestId) return { status: "superseded", theme: targetTheme };
     const normalized = normalizeThemeTransitionError(error, "Tileflow theme preload failed.");
     options.onTransition?.({
       currentTheme: current.theme,
       error: normalized,
       phase: "error",
-      targetTheme: style.theme
+      targetTheme
     });
-    return { error: normalized, status: "failed", theme: style.theme };
+    return { error: normalized, status: "failed", theme: targetTheme };
+  }
+}
+function disposedResult(theme) {
+  return { error: new Error("Tileflow theme controller is disposed."), status: "failed", theme };
+}
+function clampBlendPosition(position, themes) {
+  return Math.min(themes - 1, Math.max(0, Number.isFinite(position) ? position : 0));
+}
+function nearestTheme(request) {
+  if (!Array.isArray(request?.themes) || request.themes.length === 0) return void 0;
+  return request.themes[Math.round(clampBlendPosition(request.position, request.themes.length))]?.theme;
+}
+function validateBlendRequest(request) {
+  if (!request || !Array.isArray(request.themes) || request.themes.length < 2 || request.themes.length > maximumBlendThemes) {
+    return new TypeError(
+      `A Tileflow theme blend requires two to ${maximumBlendThemes} concrete themes.`
+    );
+  }
+  for (const theme of request.themes) {
+    const invalid = validateConcreteRuntimeTheme(theme, "target");
+    if (invalid) return invalid;
+  }
+  if (typeof request.position !== "number" || !Number.isFinite(request.position) || request.position < 0 || request.position > request.themes.length - 1) {
+    return new TypeError(
+      `A Tileflow theme blend position must be a number from 0 to ${request.themes.length - 1}.`
+    );
+  }
+  return void 0;
+}
+function normalizeThemeTransitionDuration(transition) {
+  const duration = transition?.duration ?? 0;
+  if (typeof duration !== "number" || !Number.isFinite(duration) || duration < 0 || duration > maximumTransitionMs) {
+    throw new TypeError(
+      `A Tileflow theme transition duration must be a number of milliseconds from 0 to ${maximumTransitionMs}.`
+    );
+  }
+  return Math.round(duration);
+}
+async function loadTileflowBlendStyle(url) {
+  const response = await globalThis.fetch(resolveTileflowBrowserResourceUrl(url), {
+    cache: "default",
+    credentials: "same-origin",
+    redirect: "error"
+  });
+  if (!response.ok) throw new Error(`Tileflow theme style failed: ${response.status}`);
+  const bytes = await readBoundedTileflowBrowserResource(
+    response,
+    maximumTileflowBlendStyleBytes,
+    "Tileflow theme style"
+  );
+  const style = JSON.parse(new TextDecoder().decode(bytes));
+  if (!style || typeof style !== "object" || !Array.isArray(style.layers)) {
+    throw new Error("Tileflow theme style is not a MapLibre style document.");
   }
+  return style;
 }
 function assertConcreteRuntimeTheme(style, role) {
   const error = validateConcreteRuntimeTheme(style, role);