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

package/dist/index.js

@@ -2721,16 +2721,16 @@ function validateTileflowWorldV1Tilejson(tilejson, schema = tileflowWorldV1Schem
   }
   return issues;
 }
-function requireTilejsonLayer(layers, id, issues) {
+function requireTilejsonLayer(layers, id2, issues) {
   const matches = layers.filter(
-    (layer) => typeof layer === "object" && layer !== null && layer.id === id
+    (layer) => typeof layer === "object" && layer !== null && layer.id === id2
   );
   if (matches.length === 0) {
-    issues.push(`Tileflow World V1 requires ${id}.`);
+    issues.push(`Tileflow World V1 requires ${id2}.`);
     return void 0;
   }
   if (matches.length !== 1) {
-    issues.push(`Tileflow World V1 requires exactly one ${id} layer.`);
+    issues.push(`Tileflow World V1 requires exactly one ${id2} layer.`);
     return void 0;
   }
   return matches[0];
@@ -3100,9 +3100,9 @@ function inferTileflowDataRequirements(style, options = {}) {
     dynamicAccesses: [...dynamicAccesses].sort(compareCodeUnits),
     schemaVersion: 1,
     sourceId,
-    sourceLayers: [...fieldsByLayer].sort(([left], [right]) => compareCodeUnits(left, right)).map(([id, fields]) => ({
+    sourceLayers: [...fieldsByLayer].sort(([left], [right]) => compareCodeUnits(left, right)).map(([id2, fields]) => ({
       fields: [...fields].sort(([left], [right]) => compareCodeUnits(left, right)).map(([name, type]) => ({ name, ...type === void 0 ? {} : { type } })),
-      id
+      id: id2
     }))
   };
 }
@@ -3479,6 +3479,47 @@ var tileflowLayerSlots = [
   "vegetation",
   "symbols"
 ];
+var tileflowLayerBands = [
+  "land",
+  "relief",
+  "water",
+  "roads",
+  "boundaries",
+  "buildings",
+  "vegetation",
+  "labels"
+];
+var bandSlots = {
+  land: ["background", "land"],
+  relief: ["terrain", "terrain"],
+  water: ["hydro", "hydro"],
+  roads: ["transport-areas", "transport-symbols"],
+  boundaries: ["boundaries", "boundaries"],
+  buildings: ["buildings", "buildings"],
+  vegetation: ["vegetation", "vegetation"],
+  labels: ["symbols", "symbols"]
+};
+var tileflowBandPlacements = tileflowLayerBands.flatMap(
+  (band) => [`below-${band}`, `above-${band}`]
+);
+function tileflowBandPlacementSlot(placement) {
+  const [side, band] = splitBandPlacement(placement);
+  return bandSlots[band][side === "below" ? 0 : 1];
+}
+function tileflowBandPlacementIndex(slotRanks, placement) {
+  const [side, band] = splitBandPlacement(placement);
+  const [first, last] = bandSlots[band];
+  const threshold = side === "below" ? tileflowLayerSlots.indexOf(first) : tileflowLayerSlots.indexOf(last) + 1;
+  const index = slotRanks.findIndex((rank) => rank !== void 0 && rank >= threshold);
+  return index < 0 ? slotRanks.length : index;
+}
+function splitBandPlacement(placement) {
+  const separator = placement.indexOf("-");
+  return [
+    placement.slice(0, separator),
+    placement.slice(separator + 1)
+  ];
+}
 var tileflowSemanticTargetPattern = /^[a-z][a-z0-9-]*(?:\.[A-Za-z0-9_-]+)*$/u;
 var tileflowRenderStackOperationNamePattern = /^[a-z][A-Za-z0-9_-]*$/u;
 var tileflowCompilerMetadataKeys = Object.freeze({
@@ -3505,6 +3546,332 @@ function typographyTextStyle(typography) {
   };
 }
 
+// src/cartography/layer-style.ts
+import { Color as Color2 } from "@maplibre/maplibre-gl-style-spec";
+
+// src/text-background.ts
+var tileflowLineBackgroundDefaults = Object.freeze({
+  letterSpacing: 0,
+  lineHeight: 1.2,
+  padding: 0.33
+});
+var tileflowLineBackgroundLimits = Object.freeze({
+  letterSpacing: Object.freeze({ max: 0.5, min: 0 }),
+  lineHeight: Object.freeze({ max: 3, min: 0.8 }),
+  padding: Object.freeze({ max: 1, min: 0 })
+});
+var tileflowLineBackgroundHaloRatio = 1 / 6;
+var STACK_PATTERN = /^(.+) lines-v1-t(\d{1,3})-l(\d{3,4})-p(\d{1,4})$/u;
+var SOURCE_PATTERN = /^[\p{L}\p{N} _.-]+$/u;
+var MAX_STACK_LENGTH = 256;
+var BORDER = 3;
+var TOP_OF_BITMAP = -20;
+var STRIP_CENTER = 0.5;
+var CELL_VALUE = 128;
+var CELL_EDGE = 64;
+var CELL_SLOPE = 64;
+var CELL_OVERLAP = 0.75;
+var MAX_GLYPH_SIDE = 255;
+function thousandths(value) {
+  return Math.round(value * 1e3);
+}
+function normalizeTileflowLineBackgroundMetrics(metrics = {}) {
+  const resolved = { ...tileflowLineBackgroundDefaults, ...metrics };
+  const normalized = {};
+  for (const key of ["letterSpacing", "lineHeight", "padding"]) {
+    const value = resolved[key];
+    const { max, min } = tileflowLineBackgroundLimits[key];
+    if (typeof value !== "number" || !Number.isFinite(value) || value < min || value > max) {
+      throw new RangeError(
+        `Line-fitted text background ${key} must be a constant number from ${min} to ${max} ems.`
+      );
+    }
+    normalized[key] = thousandths(value) / 1e3;
+  }
+  return normalized;
+}
+function createTileflowLineBackgroundFontStack(source, metrics = {}) {
+  if (!SOURCE_PATTERN.test(source) || source !== source.trim()) {
+    throw new TypeError(
+      `Line-fitted text backgrounds need one exact font stack of letters, numbers, spaces, underscores, dots or hyphens; received "${source}".`
+    );
+  }
+  if (parseTileflowLineBackgroundFontStack(source)) {
+    throw new TypeError(`Font stack "${source}" is already a line-fitted background stack.`);
+  }
+  const { letterSpacing, lineHeight, padding } = normalizeTileflowLineBackgroundMetrics(metrics);
+  const stack = `${source} lines-v1-t${thousandths(letterSpacing)}-l${thousandths(lineHeight)}-p${thousandths(padding)}`;
+  if (stack.length > MAX_STACK_LENGTH) {
+    throw new RangeError(
+      `Line-fitted text background font stack exceeds ${MAX_STACK_LENGTH} characters.`
+    );
+  }
+  return stack;
+}
+function parseTileflowLineBackgroundFontStack(stack) {
+  const match2 = STACK_PATTERN.exec(stack);
+  if (!match2 || stack.length > MAX_STACK_LENGTH || !SOURCE_PATTERN.test(match2[1]))
+    return void 0;
+  const metrics = {
+    letterSpacing: Number(match2[2]) / 1e3,
+    lineHeight: Number(match2[3]) / 1e3,
+    padding: Number(match2[4]) / 1e3
+  };
+  try {
+    const normalized = normalizeTileflowLineBackgroundMetrics(metrics);
+    if (`lines-v1-t${thousandths(normalized.letterSpacing)}-l${thousandths(normalized.lineHeight)}-p${thousandths(normalized.padding)}` !== stack.slice(match2[1].length + 1)) {
+      return void 0;
+    }
+    return { metrics: normalized, source: match2[1] };
+  } catch {
+    return void 0;
+  }
+}
+function scaleTileflowTextSizeForLineBackground(size) {
+  const ratio = tileflowLineBackgroundHaloRatio;
+  const scale = (output) => typeof output === "number" ? output * ratio : ["*", ratio, output];
+  if (size === void 0) return 16 * ratio;
+  if (typeof size === "number") return size * ratio;
+  if (Array.isArray(size) && size[0] === "interpolate" && isZoomInput(size[2])) {
+    return size.map((entry, index) => index >= 4 && index % 2 === 0 ? scale(entry) : entry);
+  }
+  if (Array.isArray(size) && size[0] === "step" && isZoomInput(size[1])) {
+    return size.map(
+      (entry, index) => index === 2 || index >= 4 && index % 2 === 0 ? scale(entry) : entry
+    );
+  }
+  return ["*", ratio, size];
+}
+function isZoomInput(value) {
+  return Array.isArray(value) && value.length === 1 && value[0] === "zoom";
+}
+function deriveTileflowLineBackgroundGlyphs(range2, metrics = {}) {
+  const normalized = normalizeTileflowLineBackgroundMetrics(metrics);
+  const stacks = decodeGlyphStacks(range2);
+  return encodeGlyphStacks(
+    stacks.map((stack) => ({
+      ...stack,
+      glyphs: stack.glyphs.map((glyph) => deriveGlyph(glyph, normalized))
+    }))
+  );
+}
+function deriveGlyph(glyph, metrics) {
+  const letterSpacing = metrics.letterSpacing * 24;
+  const padding = metrics.padding * 24;
+  const height = metrics.lineHeight * 24;
+  const cell = {
+    x0: -letterSpacing / 2 - padding - CELL_OVERLAP,
+    x1: glyph.advance + letterSpacing / 2 + padding + CELL_OVERLAP,
+    y0: STRIP_CENTER - height / 2 - CELL_OVERLAP,
+    y1: STRIP_CENTER + height / 2 + CELL_OVERLAP
+  };
+  const ramp = Math.ceil(CELL_EDGE / CELL_SLOPE) + 1;
+  const hasBitmap = glyph.width > 0 && glyph.height > 0 && glyph.bitmap.length > 0;
+  const sourceWidth = glyph.width + 2 * BORDER;
+  const sourceHeight = glyph.height + 2 * BORDER;
+  const sourceX = glyph.left - BORDER;
+  const sourceY = TOP_OF_BITMAP - glyph.top;
+  if (hasBitmap && glyph.bitmap.length !== sourceWidth * sourceHeight) {
+    throw new RangeError(`Glyph ${glyph.id} has a bitmap that does not match its metrics.`);
+  }
+  let x0 = Math.floor(cell.x0 - ramp);
+  let x1 = Math.ceil(cell.x1 + ramp);
+  let y0 = Math.floor(cell.y0 - ramp);
+  let y1 = Math.ceil(cell.y1 + ramp);
+  if (hasBitmap) {
+    x0 = Math.min(x0, sourceX);
+    x1 = Math.max(x1, sourceX + sourceWidth);
+    y0 = Math.min(y0, sourceY);
+    y1 = Math.max(y1, sourceY + sourceHeight);
+  }
+  const width = x1 - x0;
+  const rows = y1 - y0;
+  if (width - 2 * BORDER > MAX_GLYPH_SIDE || rows - 2 * BORDER > MAX_GLYPH_SIDE) {
+    throw new RangeError(`Glyph ${glyph.id} would exceed the derived glyph size limit.`);
+  }
+  const bitmap = new Uint8Array(width * rows);
+  for (let row = 0; row < rows; row++) {
+    const y = y0 + row + 0.5;
+    for (let column = 0; column < width; column++) {
+      const x = x0 + column + 0.5;
+      const distance = Math.min(x - cell.x0, cell.x1 - x, y - cell.y0, cell.y1 - y);
+      const background = Math.min(CELL_VALUE, Math.max(0, CELL_EDGE + CELL_SLOPE * distance));
+      let letter = 0;
+      if (hasBitmap) {
+        const sourceColumn = x0 + column - sourceX;
+        const sourceRow = y0 + row - sourceY;
+        if (sourceColumn >= 0 && sourceColumn < sourceWidth && sourceRow >= 0 && sourceRow < sourceHeight) {
+          letter = glyph.bitmap[sourceRow * sourceWidth + sourceColumn];
+        }
+      }
+      bitmap[row * width + column] = Math.round(Math.max(letter, background));
+    }
+  }
+  return {
+    advance: glyph.advance,
+    bitmap,
+    height: rows - 2 * BORDER,
+    id: glyph.id,
+    left: x0 + BORDER,
+    top: TOP_OF_BITMAP - y0,
+    width: width - 2 * BORDER
+  };
+}
+var GlyphReader = class {
+  constructor(bytes) {
+    this.bytes = bytes;
+  }
+  bytes;
+  position = 0;
+  fields(read) {
+    while (this.position < this.bytes.length) {
+      const key = this.varint();
+      if (!read(Math.floor(key / 8), this)) this.skip(key % 8);
+    }
+  }
+  varint() {
+    let result = 0;
+    let shift = 0;
+    let byte;
+    do {
+      if (this.position >= this.bytes.length || shift > 49) {
+        throw new RangeError("Invalid glyph PBF varint.");
+      }
+      byte = this.bytes[this.position++];
+      result += (byte & 127) * 2 ** shift;
+      shift += 7;
+    } while (byte & 128);
+    return result;
+  }
+  signed() {
+    const value = this.varint();
+    return value % 2 === 1 ? (value + 1) / -2 : value / 2;
+  }
+  message() {
+    const length = this.varint();
+    const end = this.position + length;
+    if (end > this.bytes.length) throw new RangeError("Truncated glyph PBF field.");
+    const value = this.bytes.subarray(this.position, end);
+    this.position = end;
+    return value;
+  }
+  skip(wire) {
+    if (wire === 0) this.varint();
+    else if (wire === 1) this.position += 8;
+    else if (wire === 2) this.message();
+    else if (wire === 5) this.position += 4;
+    else throw new RangeError(`Unsupported glyph PBF wire type ${wire}.`);
+    if (this.position > this.bytes.length) throw new RangeError("Truncated glyph PBF field.");
+  }
+};
+function decodeGlyphStacks(bytes) {
+  const stacks = [];
+  const text = new TextDecoder();
+  new GlyphReader(bytes).fields((tag, reader) => {
+    if (tag !== 1) return false;
+    const stack = { glyphs: [], name: "", range: "" };
+    new GlyphReader(reader.message()).fields((stackTag, stackReader) => {
+      if (stackTag === 1) stack.name = text.decode(stackReader.message());
+      else if (stackTag === 2) stack.range = text.decode(stackReader.message());
+      else if (stackTag === 3) stack.glyphs.push(decodeGlyph(stackReader.message()));
+      else return false;
+      return true;
+    });
+    stacks.push(stack);
+    return true;
+  });
+  return stacks;
+}
+function decodeGlyph(bytes) {
+  const glyph = {
+    advance: 0,
+    bitmap: new Uint8Array(0),
+    height: 0,
+    id: 0,
+    left: 0,
+    top: 0,
+    width: 0
+  };
+  new GlyphReader(bytes).fields((tag, reader) => {
+    if (tag === 1) glyph.id = reader.varint();
+    else if (tag === 2) glyph.bitmap = reader.message().slice();
+    else if (tag === 3) glyph.width = reader.varint();
+    else if (tag === 4) glyph.height = reader.varint();
+    else if (tag === 5) glyph.left = reader.signed();
+    else if (tag === 6) glyph.top = reader.signed();
+    else if (tag === 7) glyph.advance = reader.varint();
+    else return false;
+    return true;
+  });
+  return glyph;
+}
+var GlyphWriter = class {
+  parts = [];
+  length = 0;
+  varint(value) {
+    const bytes = [];
+    let remaining = value;
+    while (remaining >= 128) {
+      bytes.push(remaining % 128 | 128);
+      remaining = Math.floor(remaining / 128);
+    }
+    bytes.push(remaining);
+    this.raw(Uint8Array.from(bytes));
+  }
+  signed(value) {
+    this.varint(value < 0 ? -2 * value - 1 : 2 * value);
+  }
+  key(tag, wire) {
+    this.varint(tag * 8 + wire);
+  }
+  message(tag, bytes) {
+    this.key(tag, 2);
+    this.varint(bytes.length);
+    this.raw(bytes);
+  }
+  finish() {
+    const output = new Uint8Array(this.length);
+    let offset = 0;
+    for (const part of this.parts) {
+      output.set(part, offset);
+      offset += part.length;
+    }
+    return output;
+  }
+  raw(bytes) {
+    this.parts.push(bytes);
+    this.length += bytes.length;
+  }
+};
+function encodeGlyphStacks(stacks) {
+  const text = new TextEncoder();
+  const root = new GlyphWriter();
+  for (const stack of stacks) {
+    const writer = new GlyphWriter();
+    writer.message(1, text.encode(stack.name));
+    writer.message(2, text.encode(stack.range));
+    for (const glyph of stack.glyphs) {
+      const glyphWriter = new GlyphWriter();
+      glyphWriter.key(1, 0);
+      glyphWriter.varint(glyph.id);
+      if (glyph.bitmap.length > 0) glyphWriter.message(2, glyph.bitmap);
+      glyphWriter.key(3, 0);
+      glyphWriter.varint(glyph.width);
+      glyphWriter.key(4, 0);
+      glyphWriter.varint(glyph.height);
+      glyphWriter.key(5, 0);
+      glyphWriter.signed(glyph.left);
+      glyphWriter.key(6, 0);
+      glyphWriter.signed(glyph.top);
+      glyphWriter.key(7, 0);
+      glyphWriter.varint(glyph.advance);
+      writer.message(3, glyphWriter.finish());
+    }
+    root.message(1, writer.finish());
+  }
+  return root.finish();
+}
+
 // src/cartography/layer-style.ts
 init_values();
 function applyBackgroundStyle(layer, style) {
@@ -3584,8 +3951,52 @@ function applyTextStyle(layer, style) {
   setPaint(paint, "text-halo-color", style.haloColor);
   setPaint(paint, "text-halo-width", style.haloWidth);
   setPaint(paint, "text-opacity", style.opacity);
+  applyLineBackground(layer.id, layout, paint, style, backedFontStack(asRecord2(layer.layout)));
   return applyLayerRange(withLayerParts(layer, layout, paint), style);
 }
+function applyLineBackground(id2, layout, paint, style, previous) {
+  const fonts = layout["text-font"];
+  const single = Array.isArray(fonts) && fonts.length === 1 && typeof fonts[0] === "string";
+  const current = backedFontStack(layout);
+  const background = style.background;
+  if (!background && !current && !previous) return;
+  if (!single) {
+    throw new Error(
+      `Layer "${id2}" needs exactly one text font without fallbacks for a line-fitted background.`
+    );
+  }
+  const padding = background?.padding === void 0 ? (current ?? previous)?.metrics.padding ?? tileflowLineBackgroundDefaults.padding : constantNumber(id2, toMapLibreStyleValue(background.padding), "background padding");
+  const stack = createTileflowLineBackgroundFontStack(current?.source ?? fonts[0], {
+    letterSpacing: constantNumber(id2, layout["text-letter-spacing"] ?? 0, "letterSpacing"),
+    lineHeight: constantNumber(id2, layout["text-line-height"] ?? 1.2, "lineHeight"),
+    padding
+  });
+  const { metrics } = parseTileflowLineBackgroundFontStack(stack);
+  layout["text-font"] = [stack];
+  layout["text-letter-spacing"] = metrics.letterSpacing;
+  layout["text-line-height"] = metrics.lineHeight;
+  if (background) {
+    const color3 = toMapLibreStyleValue(background.color);
+    if (typeof color3 === "string" && (Color2.parse(color3)?.a ?? 1) < 1) {
+      throw new Error(
+        `Layer "${id2}" needs an opaque line-fitted background colour; "${color3}" is translucent.`
+      );
+    }
+    paint["text-halo-color"] = color3;
+  }
+  paint["text-halo-width"] = scaleTileflowTextSizeForLineBackground(layout["text-size"]);
+  paint["text-halo-blur"] = 0;
+}
+function backedFontStack(layout) {
+  const fonts = layout["text-font"];
+  return Array.isArray(fonts) && fonts.length === 1 && typeof fonts[0] === "string" ? parseTileflowLineBackgroundFontStack(fonts[0]) : void 0;
+}
+function constantNumber(id2, value, property) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  throw new Error(
+    `Layer "${id2}" uses a line-fitted text background, so its ${property} must be a constant number.`
+  );
+}
 function applyIconStyle(layer, style) {
   const paint = { ...asRecord2(layer.paint) };
   const layout = { ...asRecord2(layer.layout) };
@@ -3728,12 +4139,12 @@ function setLayout(layout, property, value) {
 function invertPriority(value) {
   const resolved = toMapLibreStyleValue(value);
   if (typeof resolved === "number") return -resolved;
-  if (Array.isArray(resolved) && resolved[0] === "interpolate" && isZoomInput(resolved[2])) {
+  if (Array.isArray(resolved) && resolved[0] === "interpolate" && isZoomInput2(resolved[2])) {
     return resolved.map(
       (entry, index) => index >= 4 && index % 2 === 0 ? negateExpressionOutput(entry) : entry
     );
   }
-  if (Array.isArray(resolved) && resolved[0] === "step" && isZoomInput(resolved[1])) {
+  if (Array.isArray(resolved) && resolved[0] === "step" && isZoomInput2(resolved[1])) {
     return resolved.map(
       (entry, index) => index === 2 || index >= 4 && index % 2 === 0 ? negateExpressionOutput(entry) : entry
     );
@@ -3746,7 +4157,7 @@ function resolvePriority(value, order) {
 function negateExpressionOutput(value) {
   return typeof value === "number" ? -value : ["*", -1, value];
 }
-function isZoomInput(value) {
+function isZoomInput2(value) {
   return Array.isArray(value) && value.length === 1 && value[0] === "zoom";
 }
 function asRecord2(value) {
@@ -3940,7 +4351,7 @@ function compileAeroways(request, context) {
     ["taxiway", config.taxiway, 10],
     ["runway", config.runway, 20]
   ]) {
-    for (const [phase, style, phaseOrder2] of [
+    for (const [phase, style, phaseOrder] of [
       ["shadow", target?.shadow, 0],
       ["casing", target?.casing, 1],
       ["fill", target?.fill, 2]
@@ -3962,7 +4373,7 @@ function compileAeroways(request, context) {
           },
           style
         ),
-        localOrder: order + phaseOrder2,
+        localOrder: order + phaseOrder,
         owner: "aeroways",
         slot: "aeroways",
         target: `aeroways.${name}.${phase}`
@@ -4748,14 +5159,14 @@ function compileLabels(request, roadRequest, context) {
   for (const placeClass of visiblePlaceClasses) {
     const style = styles.places?.[placeClass];
     if (!style || style.visible === false || style.text?.visible === false) continue;
-    const id = `tileflow-label-place-${placeClass}`;
+    const id2 = `tileflow-label-place-${placeClass}`;
     result.push(
       symbolContribution(
         `labels.places.${placeClass}`,
         (navigationPriority ? 1300 : 800) + order++,
         applySymbolStyle(
           {
-            id,
+            id: id2,
             type: "symbol",
             source,
             "source-layer": schema.layers.place,
@@ -4780,14 +5191,14 @@ function compileLabels(request, roadRequest, context) {
   for (const roadClass of orderedRoads) {
     const style = styles.roads?.[roadClass];
     if (!style || style.visible === false || style.text?.visible === false) continue;
-    const id = `tileflow-label-road-${roadClass}`;
+    const id2 = `tileflow-label-road-${roadClass}`;
     result.push(
       symbolContribution(
         `labels.roads.${roadClass}`,
         (navigationPriority ? 1200 : 200) + order++,
         applySymbolStyle(
           {
-            id,
+            id: id2,
             type: "symbol",
             source,
             "source-layer": schema.layers.roadName,
@@ -4799,7 +5210,7 @@ function compileLabels(request, roadRequest, context) {
           },
           mergeTileflowDesign(style, { text: { field: field2 } })
         ),
-        navigationPriority ? "symbols" : "transport-symbols",
+        "symbols",
         { group: "roads", kind: "road-label", member: roadClass }
       )
     );
@@ -4891,8 +5302,7 @@ function compileLabels(request, roadRequest, context) {
               ]
             },
             style
-          ),
-          "transport-symbols"
+          )
         )
       );
     }
@@ -4930,8 +5340,7 @@ function compileLabels(request, roadRequest, context) {
               ])
             }
           })
-        ),
-        "transport-symbols"
+        )
       )
     );
   }
@@ -7734,10 +8143,10 @@ function isExpressionOutput(value) {
 }
 function rewriteZoomOutputs(value, rewrite) {
   if (!Array.isArray(value)) return rewrite(value);
-  if (value[0] === "interpolate" && isZoomInput2(value[2])) {
+  if (value[0] === "interpolate" && isZoomInput3(value[2])) {
     return value.map((entry, index) => index >= 4 && index % 2 === 0 ? rewrite(entry) : entry);
   }
-  if (value[0] === "step" && isZoomInput2(value[1])) {
+  if (value[0] === "step" && isZoomInput3(value[1])) {
     return value.map(
       (entry, index) => index === 2 || index >= 4 && index % 2 === 0 ? rewrite(entry) : entry
     );
@@ -7747,7 +8156,7 @@ function rewriteZoomOutputs(value, rewrite) {
 function expressionOutput(value) {
   return Array.isArray(value) && typeof value[0] !== "string" ? ["literal", value] : value;
 }
-function isZoomInput2(value) {
+function isZoomInput3(value) {
   return Array.isArray(value) && value.length === 1 && value[0] === "zoom";
 }
 function restrictedAccessFilter(field2) {
@@ -9164,7 +9573,7 @@ function insertTileflowOverlays(input) {
     });
     groups.set(overlay.placement, [...groups.get(overlay.placement) ?? [], ...layers2]);
     identities[overlayId] = Object.freeze({
-      layers: Object.freeze(overlay.layers.map(({ id }) => id)),
+      layers: Object.freeze(overlay.layers.map(({ id: id2 }) => id2)),
       placement: overlay.placement,
       source: overlay.source
     });
@@ -9201,22 +9610,13 @@ function cloneJson18(value) {
   );
 }
 function tileflowOverlayInsertionIndex(layers, placement) {
-  const threshold = {
-    "above-water": tileflowLayerSlots.indexOf("building-areas"),
-    "below-roads": tileflowLayerSlots.indexOf("transport-areas"),
-    "above-roads": tileflowLayerSlots.indexOf("boundaries"),
-    "above-buildings": tileflowLayerSlots.indexOf("vegetation"),
-    "below-labels": tileflowLayerSlots.indexOf("symbols"),
-    "above-labels": Number.POSITIVE_INFINITY
-  }[placement];
-  if (!Number.isFinite(threshold)) return layers.length;
-  const index = layers.findIndex((layer) => {
-    const ranks = readTileflowCompilerProvenance(layer).map(
+  const ranks = layers.map((layer) => {
+    const slots = readTileflowCompilerProvenance(layer).map(
       ({ slot }) => tileflowLayerSlots.indexOf(slot)
     );
-    return ranks.length > 0 && Math.min(...ranks) >= threshold;
+    return slots.length > 0 ? Math.min(...slots) : void 0;
   });
-  return index < 0 ? layers.length : index;
+  return tileflowBandPlacementIndex(ranks, placement);
 }
 function compareCodeUnits4(left, right) {
   return left < right ? -1 : left > right ? 1 : 0;
@@ -9228,7 +9628,7 @@ function isPlainRecord2(value) {
 }
 
 // src/resolved-map-schema.ts
-import { Color as Color2 } from "@maplibre/maplibre-gl-style-spec";
+import { Color as Color3 } from "@maplibre/maplibre-gl-style-spec";
 import { z as z6 } from "zod";
 
 // src/cartography/data-expression.ts
@@ -9247,6 +9647,9 @@ function literal(value) {
 function zoom2() {
   return make(["zoom"]);
 }
+function id() {
+  return make(["id"]);
+}
 function coalesce(first, ...rest) {
   if (rest.length === 0) throw new Error("expr.coalesce requires at least two values.");
   validateOperandCount(1 + rest.length, "expr.coalesce");
@@ -9297,6 +9700,9 @@ function subtract(first, second) {
 function divide(dividend, divisor) {
   return make(["/", node(dividend), node(divisor)]);
 }
+function modulo(dividend, divisor) {
+  return make(["%", node(dividend), node(divisor)]);
+}
 function multiply(first, second, ...rest) {
   validateOperandCount(2 + rest.length, "expr.multiply");
   return make(["*", node(first), node(second), ...rest.map(node)]);
@@ -9502,6 +9908,7 @@ function visitExpression(value, path, variables, issues) {
       }
       return;
     }
+    case "id":
     case "zoom": {
       exact(1);
       return;
@@ -9551,6 +9958,7 @@ function visitExpression(value, path, variables, issues) {
     }
     case "-":
     case "/":
+    case "%":
     case "!=":
     case "<":
     case "<=":
@@ -9775,6 +10183,7 @@ var expr = Object.freeze({
   gt: (left, right) => compare(">", left, right),
   gte: (left, right) => compare(">=", left, right),
   has,
+  id,
   featureState,
   interpolate: interpolate2,
   let: letValue,
@@ -9784,6 +10193,7 @@ var expr = Object.freeze({
   match,
   max: maximum,
   min: minimum,
+  modulo,
   multiply,
   ne: (left, right) => compare("!=", left, right),
   not,
@@ -9916,7 +10326,7 @@ function createTileflowLayerFamilyIR(contribution) {
 function createTileflowLayerTemplateIR(layer, semanticKey) {
   const {
     filter,
-    id,
+    id: id2,
     layout,
     maxzoom,
     metadata,
@@ -9927,7 +10337,7 @@ function createTileflowLayerTemplateIR(layer, semanticKey) {
     type,
     ...properties
   } = layer;
-  if (typeof id !== "string" || !id.trim()) {
+  if (typeof id2 !== "string" || !id2.trim()) {
     throw new TileflowDomainIRError(
       "TILEFLOW_DOMAIN_IR_INVALID_KEY",
       "Layer key must not be empty."
@@ -9942,7 +10352,7 @@ function createTileflowLayerTemplateIR(layer, semanticKey) {
   if (typeof type !== "string" || !type.trim()) {
     throw new TileflowDomainIRError(
       "TILEFLOW_DOMAIN_IR_INVALID_RENDERER",
-      `Layer family ${id} requires a renderer.`
+      `Layer family ${id2} requires a renderer.`
     );
   }
   const annotations = publicMetadata(metadata);
@@ -10224,13 +10634,6 @@ function isRecord5(value) {
 }
 
 // src/cartography/render-stack.ts
-var tileflowRenderStackPhases = [
-  "underlay",
-  "overlay",
-  "postRelief",
-  "annotation",
-  "finish"
-];
 var tileflowRenderStackRenderers = [
   "background",
   "circle",
@@ -10438,15 +10841,14 @@ var geometryTypes = {
   point: "Point",
   polygon: "Polygon"
 };
-var phaseOrder = new Map(tileflowRenderStackPhases.map((phase, index) => [phase, index]));
 function renderPass(input) {
   assertOnlyKeys(
     input,
-    ["attachTo", "feature", "phase", "renderer", "requirements", "selector", "style"],
+    ["feature", "placement", "renderer", "requirements", "selector", "style"],
     "renderPass"
   );
   requireRenderer(input.renderer);
-  requirePhase(input.phase);
+  requirePlacement(input.placement);
   validateStyle(input.renderer, input.style);
   if (input.renderer === "background" && ("feature" in input || "selector" in input)) {
     throw renderStackError(
@@ -10461,11 +10863,10 @@ function renderPass(input) {
 function refineRenderTarget(input) {
   assertOnlyKeys(
     input,
-    ["renderer", "requirements", "selector", "style", "target"],
+    ["placement", "renderer", "requirements", "selector", "style", "target"],
     "refineRenderTarget"
   );
-  requireRenderer(input.renderer);
-  validateStyle(input.renderer, input.style);
+  validateRefinementShape(input);
   if (input.renderer === "background" && "selector" in input) {
     throw renderStackError(
       "invalid-background-refinement",
@@ -10515,71 +10916,118 @@ function compileRenderSelector(selector, data) {
 }
 function applyCompiledRenderStacks(input, operations2) {
   let layers = input.map(cloneJson21);
-  const activeOwners = new Set(layers.map(({ owner }) => owner));
-  const layerOperations = operations2.filter(
+  const passes = operations2.filter(
     (operation) => operation.kind === "layer"
   );
-  const suppressedTargets = new Set(
-    layerOperations.filter(
-      (operation) => operation.requirements.some((requirement) => !activeOwners.has(requirement))
-    ).map((operation) => operation.target)
+  const refinements = operations2.filter(
+    (operation) => operation.kind === "refinement"
   );
-  let changed = true;
-  while (changed) {
+  requireUniqueCompiledLayers(layers, passes);
+  const passTargets = new Set(passes.map(({ target }) => target));
+  const knownTargets = /* @__PURE__ */ new Set([...layers.map(({ target }) => target), ...passTargets]);
+  const activeOwners = new Set(layers.map(({ owner }) => owner));
+  const drawn = /* @__PURE__ */ new Set();
+  for (let changed = true; changed; ) {
     changed = false;
-    for (const operation of layerOperations) {
-      if (!suppressedTargets.has(operation.target) && suppressedTargets.has(operation.attachTo)) {
-        suppressedTargets.add(operation.target);
-        changed = true;
-      }
+    for (const pass of passes) {
+      if (drawn.has(pass.target)) continue;
+      const anchor = placementAnchor(pass.placement);
+      if (pass.requirements.some((requirement) => !activeOwners.has(requirement))) continue;
+      if (anchor !== void 0 && passTargets.has(anchor) && !drawn.has(anchor)) continue;
+      drawn.add(pass.target);
+      activeOwners.add(pass.owner);
+      changed = true;
+    }
+  }
+  const activeRefinements = refinements.filter(
+    (refinement) => refinement.requirements.every((requirement) => activeOwners.has(requirement))
+  ).sort(compareCompiledOperations);
+  for (const refinement of activeRefinements) {
+    const index = findTargetIndex(layers, refinement.target);
+    if (index < 0 && !passTargets.has(refinement.target)) {
+      throw renderStackError(
+        "unknown-refinement-target",
+        `Render refinement targets unknown semantic contribution: ${refinement.target}.`
+      );
     }
-  }
-  const pending = layerOperations.filter((operation) => !suppressedTargets.has(operation.target)).sort(compareCompiledOperations);
-  requireUniqueCompiledLayers(layers, pending);
-  while (pending.length > 0) {
-    const ready = pending.find((operation) => findTargetIndex(layers, operation.attachTo) >= 0);
-    if (!ready) {
+    if (refinement.placement !== void 0 && placementAnchor(refinement.placement) === refinement.target) {
       throw renderStackError(
         "unknown-or-circular-anchor",
-        `Render passes target unknown or circular anchors: ${pending.map((operation) => `${operation.target}->${operation.attachTo}`).join(", ")}.`
+        `Render refinement ${refinement.target} cannot be placed beside itself.`
       );
     }
-    const anchorTarget = ready.attachTo;
-    const group = pending.filter((operation) => operation.attachTo === anchorTarget).sort(compareCompiledOperations);
-    const anchorIndex = findTargetIndex(layers, anchorTarget);
-    const anchor = layers[anchorIndex];
-    const before = group.filter((operation) => operation.phase === "underlay").map((operation) => materializeRenderLayer(operation, anchor));
-    const after = group.filter((operation) => operation.phase !== "underlay").map((operation) => materializeRenderLayer(operation, anchor));
-    layers = [
-      ...layers.slice(0, anchorIndex),
-      ...before,
-      anchor,
-      ...after,
-      ...layers.slice(anchorIndex + 1)
-    ];
-    for (const operation of group) pending.splice(pending.indexOf(operation), 1);
   }
-  const refinements = operations2.filter(
-    (operation) => operation.kind === "refinement"
-  ).filter(
-    (operation) => operation.requirements.every((requirement) => activeOwners.has(requirement))
-  ).sort(compareCompiledOperations);
-  for (const refinement of refinements) {
-    const index = findTargetIndex(layers, refinement.target);
-    if (index < 0) {
+  const isDrawn = (target) => !passTargets.has(target) || drawn.has(target);
+  const pending = [
+    ...passes.filter(({ target }) => drawn.has(target)),
+    ...activeRefinements.filter(({ placement, target }) => {
+      if (placement === void 0 || !isDrawn(target)) return false;
+      const anchor = placementAnchor(placement);
+      return anchor === void 0 || isDrawn(anchor);
+    })
+  ].sort(compareCompiledOperations);
+  for (const operation of pending) {
+    const anchor = placementAnchor(operation.placement);
+    if (anchor !== void 0 && !knownTargets.has(anchor)) {
       throw renderStackError(
-        "unknown-refinement-target",
-        `Render refinement targets unknown semantic contribution: ${refinement.target}.`
+        "unknown-or-circular-anchor",
+        `${operation.target} is placed beside unknown semantic target ${anchor}.`
       );
     }
-    const previous = layers[index];
-    const actualOwner = previous.owner;
-    if (actualOwner !== refinement.owner) {
+  }
+  const lastPlaced = /* @__PURE__ */ new Map();
+  const isMovePending = (target) => pending.some((operation) => operation.kind === "refinement" && operation.target === target);
+  const isReady = (operation) => {
+    if (operation.kind === "refinement" && findTargetIndex(layers, operation.target) < 0) {
+      return false;
+    }
+    const anchor = placementAnchor(operation.placement);
+    return anchor === void 0 || findTargetIndex(layers, anchor) >= 0 && !isMovePending(anchor);
+  };
+  while (pending.length > 0) {
+    const first = pending.find(isReady);
+    if (first === void 0) {
       throw renderStackError(
-        "refinement-owner-mismatch",
-        `Render refinement ${refinement.target} belongs to ${actualOwner ?? "no owner"}, not ${refinement.owner}.`
+        "unknown-or-circular-anchor",
+        `Render operations are placed beside circular anchors: ${pending.map((operation) => `${operation.target}->${placementKey(operation.placement)}`).join(", ")}.`
       );
     }
+    const key = placementKey(first.placement);
+    const group = pending.filter(
+      (operation) => placementKey(operation.placement) === key && isReady(operation)
+    );
+    for (const operation of group) pending.splice(pending.indexOf(operation), 1);
+    const moved = /* @__PURE__ */ new Map();
+    for (const operation of group) {
+      if (operation.kind !== "refinement") continue;
+      const index2 = findTargetIndex(layers, operation.target);
+      moved.set(operation.target, requireRefinementOwner(layers[index2], operation));
+      layers = [...layers.slice(0, index2), ...layers.slice(index2 + 1)];
+      for (const [placed, target] of lastPlaced) {
+        if (target === operation.target) lastPlaced.delete(placed);
+      }
+    }
+    const placement = first.placement;
+    const anchor = placementAnchor(placement);
+    const anchorLayer = anchor === void 0 ? void 0 : layers[findTargetIndex(layers, anchor)];
+    const slot = anchorLayer === void 0 ? tileflowBandPlacementSlot(placement) : requireSemanticSlot(anchorLayer, anchor);
+    const block = group.map(
+      (operation) => operation.kind === "layer" ? materializeRenderLayer(operation, anchorLayer, slot) : moveLayer(moved.get(operation.target), operation, slot, anchorLayer)
+    );
+    const previous = lastPlaced.get(key);
+    const previousIndex = previous === void 0 ? -1 : findTargetIndex(layers, previous);
+    const index = anchorLayer !== void 0 ? findTargetIndex(layers, anchor) + (key.startsWith("above:") ? 1 : 0) : previousIndex >= 0 ? previousIndex + 1 : tileflowBandPlacementIndex(
+      layers.map((candidate) => tileflowLayerSlots.indexOf(candidate.slot)),
+      placement
+    );
+    layers = [...layers.slice(0, index), ...block, ...layers.slice(index)];
+    lastPlaced.set(key, block.at(-1).target);
+  }
+  for (const refinement of activeRefinements) {
+    if (refinement.patch === void 0) continue;
+    const index = findTargetIndex(layers, refinement.target);
+    if (index < 0) continue;
+    const previous = requireRefinementOwner(layers[index], refinement);
     const expectedType = rendererLayerType(refinement.renderer);
     if (previous.renderer !== expectedType) {
       throw renderStackError(
@@ -10587,26 +11035,48 @@ function applyCompiledRenderStacks(input, operations2) {
         `Render refinement ${refinement.target} expects ${expectedType}, found ${String(previous.renderer)}.`
       );
     }
-    layers[index] = applyRefinement(previous, refinement);
+    layers[index] = applyRefinement(previous, { ...refinement, patch: refinement.patch });
   }
   return layers;
 }
+function requireRefinementOwner(layer, refinement) {
+  if (layer.owner !== refinement.owner) {
+    throw renderStackError(
+      "refinement-owner-mismatch",
+      `Render refinement ${refinement.target} belongs to ${layer.owner ?? "no owner"}, not ${refinement.owner}.`
+    );
+  }
+  return layer;
+}
+function placementAnchor(placement) {
+  if (placement === void 0 || typeof placement === "string") return void 0;
+  return placement.above ?? placement.below;
+}
+function placementKey(placement) {
+  if (typeof placement === "string") return placement;
+  return placement.above === void 0 ? `below:${placement.below}` : `above:${placement.above}`;
+}
 function compileOperation(owner, name, operation, order, data) {
   requireOperationName(name);
   if (operation.kind === "render-pass") {
     validateRenderPassOperation(operation);
     const requirements2 = normalizeRequirements(operation.requirements);
-    requireAttachTarget(owner, operation.attachTo, requirements2);
+    requirePlacementAnchor(owner, operation.placement, requirements2);
     const target = `${owner}.render.${name}`;
     requirePortableTarget(target, "generated render target");
+    if (typeof operation.placement === "string" && operation.renderer !== "background" && operation.feature === void 0) {
+      throw renderStackError(
+        "missing-inherited-feature",
+        `Render pass ${target} is placed at ${operation.placement} and must declare its feature.`
+      );
+    }
     const template2 = compileRenderLayer(target, operation, data);
     return {
-      attachTo: operation.attachTo,
       kind: "layer",
       name,
       order,
       owner,
-      phase: operation.phase,
+      placement: cloneJson21(operation.placement),
       renderer: operation.renderer,
       requirements: requirements2,
       target,
@@ -10616,6 +11086,21 @@ function compileOperation(owner, name, operation, order, data) {
   validateRefinementOperation(operation);
   requireOwnedTarget(owner, operation.target, "refinement target");
   const requirements = normalizeRequirements(operation.requirements);
+  if (operation.placement !== void 0) {
+    requirePlacementAnchor(owner, operation.placement, requirements);
+  }
+  const placement = operation.placement === void 0 ? {} : { placement: cloneJson21(operation.placement) };
+  if (operation.renderer === void 0) {
+    return {
+      kind: "refinement",
+      name,
+      order,
+      owner,
+      ...placement,
+      requirements,
+      target: operation.target
+    };
+  }
   const template = applyRendererStyle(
     { id: "tileflow-render-refinement-template", type: rendererLayerType(operation.renderer) },
     operation.renderer,
@@ -10629,6 +11114,7 @@ function compileOperation(owner, name, operation, order, data) {
     order,
     owner,
     patch,
+    ...placement,
     renderer: operation.renderer,
     requirements,
     target: operation.target
@@ -10806,26 +11292,42 @@ function requireFieldBinding(fieldName, data) {
   }
   return field(fieldName);
 }
-function materializeRenderLayer(operation, anchor) {
+function materializeRenderLayer(operation, anchor, slot) {
   let template = cloneJson21(operation.template);
   if (operation.renderer !== "background" && template.feature?.dataSource === void 0) {
-    if (anchor.feature?.dataSource === void 0 || anchor.feature.dataLayer === void 0) {
+    if (anchor?.feature?.dataSource === void 0 || anchor.feature.dataLayer === void 0) {
       throw renderStackError(
         "missing-inherited-feature",
-        `Render pass ${operation.target} has no feature and anchor ${operation.attachTo} has no vector feature to inherit.`
+        `Render pass ${operation.target} has no feature and ${placementKey(operation.placement)} provides no vector feature to inherit.`
       );
     }
     template = { ...template, feature: cloneJson21(anchor.feature) };
   }
-  const slot = requireSemanticSlot(anchor, operation.attachTo);
   return materializeTileflowLayerFamilyIR(template, {
     operations: [{ kind: "pass", owner: operation.owner, target: operation.target }],
-    order: anchor.order,
+    order: anchor?.order ?? 0,
     owner: operation.owner,
     slot,
     target: operation.target
   });
 }
+function moveLayer(layer, refinement, slot, anchor) {
+  return {
+    ...layer,
+    order: anchor?.order ?? layer.order,
+    origins: layer.origins.map(
+      (origin) => origin.owner === refinement.owner && origin.target === refinement.target ? {
+        ...origin,
+        operations: [
+          ...origin.operations,
+          { kind: "refinement", owner: refinement.owner, target: refinement.target }
+        ],
+        slot
+      } : origin
+    ),
+    slot
+  };
+}
 function applyRefinement(previous, refinement) {
   const patch = refinement.patch;
   const operation = {
@@ -10841,7 +11343,8 @@ function applyRefinement(previous, refinement) {
     ...patch.range === void 0 ? {} : { range: { ...previous.range ?? {}, ...patch.range } },
     ...!Object.hasOwn(patch, "selector") ? {} : { selector: cloneJson21(patch.selector) },
     origins: previous.origins.map(
-      (origin) => origin.owner === refinement.owner && origin.target === refinement.target ? { ...origin, operations: [...origin.operations, operation] } : origin
+      (origin) => origin.owner === refinement.owner && origin.target === refinement.target && // A move already recorded this refinement on the target.
+      refinement.placement === void 0 ? { ...origin, operations: [...origin.operations, operation] } : origin
     ),
     style: {
       ...previous.style,
@@ -10872,10 +11375,34 @@ function requireRenderer(value) {
     throw renderStackError("invalid-renderer", `Unknown render-stack renderer: ${String(value)}.`);
   }
 }
-function requirePhase(value) {
-  if (!tileflowRenderStackPhases.includes(value)) {
-    throw renderStackError("invalid-phase", `Unknown render-stack phase: ${String(value)}.`);
+function requirePlacement(value) {
+  if (typeof value === "string") {
+    if (tileflowBandPlacements.includes(value)) return;
+  } else if (isRecord6(value)) {
+    const keys = Object.keys(value);
+    if (keys.length === 1 && (keys[0] === "above" || keys[0] === "below")) {
+      requirePortableTarget(value[keys[0]], "render placement target");
+      return;
+    }
+  }
+  throw renderStackError(
+    "invalid-placement",
+    `A render placement is a band edge (${tileflowBandPlacements.join(", ")}) or {above} / {below} one semantic target: ${JSON.stringify(value)}.`
+  );
+}
+function validateRefinementShape(operation) {
+  if (operation.placement !== void 0) requirePlacement(operation.placement);
+  if (operation.renderer === void 0) {
+    if (operation.placement === void 0 || "style" in operation || "selector" in operation) {
+      throw renderStackError(
+        "invalid-refinement",
+        "A render refinement declares a renderer with its style, a placement, or both."
+      );
+    }
+    return;
   }
+  requireRenderer(operation.renderer);
+  validateStyle(operation.renderer, operation.style);
 }
 function validateStyle(renderer, style) {
   if (!isRecord6(style)) {
@@ -10995,13 +11522,15 @@ function requireRenderStackEntries(stack) {
   }
   return entries;
 }
-function requireAttachTarget(owner, target, requirements) {
-  requirePortableTarget(target, "render attachment target");
+function requirePlacementAnchor(owner, placement, requirements) {
+  requirePlacement(placement);
+  const target = placementAnchor(placement);
+  if (target === void 0) return;
   const targetOwner = target.split(".")[0];
   if (targetOwner !== owner && !requirements.includes(targetOwner)) {
     throw renderStackError(
       "cross-owner-attachment",
-      `Render pass owner ${owner} may attach to ${target} only with an explicit ${targetOwner} requirement.`
+      `Render operation owner ${owner} may be placed beside ${target} only with an explicit ${targetOwner} requirement.`
     );
   }
 }
@@ -11048,18 +11577,16 @@ function requireUniqueCompiledLayers(layers, operations2) {
   }
 }
 function compareCompiledOperations(left, right) {
-  const leftPhase = left.kind === "layer" ? phaseOrder.get(left.phase) : Number.MAX_SAFE_INTEGER;
-  const rightPhase = right.kind === "layer" ? phaseOrder.get(right.phase) : Number.MAX_SAFE_INTEGER;
-  return leftPhase - rightPhase || left.order - right.order || compareCodeUnits6(left.owner, right.owner) || compareCodeUnits6(left.name, right.name);
+  return left.order - right.order || compareCodeUnits6(left.owner, right.owner) || compareCodeUnits6(left.name, right.name);
 }
 function validateRenderPassOperation(operation) {
   assertOnlyKeys(
     operation,
-    ["attachTo", "feature", "kind", "phase", "renderer", "requirements", "selector", "style"],
+    ["feature", "kind", "placement", "renderer", "requirements", "selector", "style"],
     "render pass operation"
   );
   requireRenderer(operation.renderer);
-  requirePhase(operation.phase);
+  requirePlacement(operation.placement);
   validateStyle(operation.renderer, operation.style);
   if (operation.renderer === "background" && ("feature" in operation || "selector" in operation)) {
     throw renderStackError(
@@ -11071,11 +11598,10 @@ function validateRenderPassOperation(operation) {
 function validateRefinementOperation(operation) {
   assertOnlyKeys(
     operation,
-    ["kind", "renderer", "requirements", "selector", "style", "target"],
+    ["kind", "placement", "renderer", "requirements", "selector", "style", "target"],
     "render refinement operation"
   );
-  requireRenderer(operation.renderer);
-  validateStyle(operation.renderer, operation.style);
+  validateRefinementShape(operation);
   if (operation.renderer === "background" && "selector" in operation) {
     throw renderStackError(
       "invalid-background-refinement",
@@ -11725,6 +12251,11 @@ var textStyleSchema = z6.object({
     "top-left",
     "top-right"
   ]).optional(),
+  background: z6.object({
+    color: colorValueSchema,
+    fit: z6.literal("lines"),
+    padding: themeNumberValueSchema.optional()
+  }).strict().optional(),
   color: colorValueSchema.optional(),
   fallbacks: moduleFontFallbacksSchema.optional(),
   field: stringValueSchema.optional(),
@@ -11971,12 +12502,16 @@ var renderRequirementsSchema = z6.array(z6.enum(tileflowLayerDomains)).min(1).ma
     seen.add(requirement);
   }
 });
+var renderPlacementSchema = z6.union([
+  z6.enum(tileflowBandPlacements),
+  z6.object({ above: renderTargetSchema }).strict(),
+  z6.object({ below: renderTargetSchema }).strict()
+]);
 var vectorRenderPassSchemas = tileflowRenderStackRenderers.filter((renderer) => renderer !== "background").map(
   (renderer) => z6.object({
-    attachTo: renderTargetSchema,
     feature: z6.enum(tileflowSemanticLayerNames).optional(),
     kind: z6.literal("render-pass"),
-    phase: z6.enum(tileflowRenderStackPhases),
+    placement: renderPlacementSchema,
     renderer: z6.literal(renderer),
     requirements: renderRequirementsSchema.optional(),
     selector: renderSelectorSchema.optional(),
@@ -11985,9 +12520,8 @@ var vectorRenderPassSchemas = tileflowRenderStackRenderers.filter((renderer) =>
 );
 var renderPassSchema = z6.discriminatedUnion("renderer", [
   z6.object({
-    attachTo: renderTargetSchema,
     kind: z6.literal("render-pass"),
-    phase: z6.enum(tileflowRenderStackPhases),
+    placement: renderPlacementSchema,
     renderer: z6.literal("background"),
     requirements: renderRequirementsSchema.optional(),
     style: renderStyleSchemas.background
@@ -11997,6 +12531,7 @@ var renderPassSchema = z6.discriminatedUnion("renderer", [
 var renderRefinementSchemas = tileflowRenderStackRenderers.map(
   (renderer) => z6.object({
     kind: z6.literal("refine-render-target"),
+    placement: renderPlacementSchema.optional(),
     requirements: renderRequirementsSchema.optional(),
     renderer: z6.literal(renderer),
     ...renderer === "background" ? {} : { selector: renderSelectorSchema.optional() },
@@ -12004,7 +12539,17 @@ var renderRefinementSchemas = tileflowRenderStackRenderers.map(
     target: renderTargetSchema
   }).strict()
 );
-var renderStackOperationSchema = z6.union([renderPassSchema, ...renderRefinementSchemas]);
+var renderPlacementRefinementSchema = z6.object({
+  kind: z6.literal("refine-render-target"),
+  placement: renderPlacementSchema,
+  requirements: renderRequirementsSchema.optional(),
+  target: renderTargetSchema
+}).strict();
+var renderStackOperationSchema = z6.union([
+  renderPassSchema,
+  ...renderRefinementSchemas,
+  renderPlacementRefinementSchema
+]);
 var renderStackSchema = z6.record(renderStackOperationNameSchema, renderStackOperationSchema).superRefine((stack, context) => {
   const size = Object.keys(stack).length;
   if (size === 0) {
@@ -12846,7 +13391,7 @@ var terrainSchema = z6.union([
     url: z6.string().trim().min(1).optional()
   }).strict()
 ]);
-var atmosphereColorLiteralSchema = z6.string().refine((value) => Color2.parse(value)?.a === 1, "Expected an opaque color");
+var atmosphereColorLiteralSchema = z6.string().refine((value) => Color3.parse(value)?.a === 1, "Expected an opaque color");
 var atmosphereColorSchema = z6.union([
   atmosphereColorLiteralSchema,
   fixedStringSchema.extend({ value: atmosphereColorLiteralSchema }),
@@ -13343,7 +13888,7 @@ function cloneJson22(value) {
 }
 
 // src/icon-appearance.ts
-import { Color as Color3 } from "@maplibre/maplibre-gl-style-spec";
+import { Color as Color4 } from "@maplibre/maplibre-gl-style-spec";
 import { z as z8 } from "zod";
 
 // src/icon-layout.ts
@@ -13417,7 +13962,7 @@ function scaleTileflowIconLayout(layout, scale) {
 }
 
 // src/icon-appearance.ts
-var color2 = z8.string().max(128).refine((value) => Color3.parse(value) !== void 0, "Expected a MapLibre color");
+var color2 = z8.string().max(128).refine((value) => Color4.parse(value) !== void 0, "Expected a MapLibre color");
 var tileflowIconAppearanceSchema = z8.object({
   representation: z8.literal("sdf"),
   defaults: z8.object({
@@ -13491,9 +14036,9 @@ function applyTileflowIconCapabilities(style, icons) {
   if (!icons?.appearances || !Object.keys(icons.appearances).length) return;
   const ids = [...icons.ids];
   const appearances = icons.appearances;
-  for (const [id, appearance] of Object.entries(appearances)) {
-    if (!ids.includes(id))
-      throw new Error(`Icon capability metadata references unknown icon "${id}".`);
+  for (const [id2, appearance] of Object.entries(appearances)) {
+    if (!ids.includes(id2))
+      throw new Error(`Icon capability metadata references unknown icon "${id2}".`);
     tileflowIconAppearanceSchema.parse(appearance);
   }
   for (const layer of style.layers) {
@@ -13504,7 +14049,7 @@ function applyTileflowIconCapabilities(style, icons) {
       "background-pattern"
     ]) {
       const pattern = record(layer.paint)[property];
-      if (pattern !== void 0 && [...outputs(pattern, ids)].some((id) => appearances[id]?.representation === "sdf")) {
+      if (pattern !== void 0 && [...outputs(pattern, ids)].some((id2) => appearances[id2]?.representation === "sdf")) {
         throw Object.assign(new Error(`Layer "${layer.id}" cannot use an SDF icon as a pattern.`), {
           code: "TF_ICON_PATTERN_SDF",
           path: `layers.${layer.id}.paint.${property}`,
@@ -13522,7 +14067,7 @@ function applyTileflowIconCapabilities(style, icons) {
       });
     }
     const names = [...outputs(image, ids)];
-    const sdf = names.filter((id) => appearances[id]?.representation === "sdf");
+    const sdf = names.filter((id2) => appearances[id2]?.representation === "sdf");
     if (!sdf.length) continue;
     if (sdf.length !== names.length) {
       throw Object.assign(
@@ -13634,7 +14179,7 @@ function numericBounds(value) {
   ];
 }
 function defaultPaint(image, key, names, appearances, ids) {
-  const values = names.map((id) => appearances[id].defaults[key]);
+  const values = names.map((id2) => appearances[id2].defaults[key]);
   if (new Set(values).size === 1) return values[0];
   if (Array.isArray(image) && (image[0] === "step" || image[0] === "interpolate")) {
     const copy = [...image];
@@ -13645,7 +14190,7 @@ function defaultPaint(image, key, names, appearances, ids) {
   return [
     "match",
     ["to-string", selection(image, ids)],
-    ...names.flatMap((id, i) => [id, values[i]]),
+    ...names.flatMap((id2, i) => [id2, values[i]]),
     values[0]
   ];
 }
@@ -13655,18 +14200,18 @@ var tileflowInteractionManifestMetadataKey = "tileflow:interaction-manifest";
 var tileflowInteractionManifestVersion = 2;
 function createTileflowInteractionManifest(layers, fields) {
   const poiLayers = layers.flatMap((layer, priority) => {
-    const id = typeof layer.id === "string" ? layer.id : void 0;
+    const id2 = typeof layer.id === "string" ? layer.id : void 0;
     const source = typeof layer.source === "string" ? layer.source : void 0;
     const sourceLayer = typeof layer["source-layer"] === "string" ? layer["source-layer"] : void 0;
     const target = semanticTarget(layer);
-    if (!id || !source || !sourceLayer || !target?.startsWith("poi.")) return [];
+    if (!id2 || !source || !sourceLayer || !target?.startsWith("poi.")) return [];
     const parsed = parsePoiTarget(target);
     if (!parsed) return [];
     return [
       {
         ...parsed,
         anchor: "pointer-coordinate",
-        layerId: id,
+        layerId: id2,
         priority,
         source,
         sourceLayer
@@ -13765,11 +14310,11 @@ function createTileflowOverlayPlacementManifest(layers) {
   const anchors = Object.fromEntries(
     tileflowOverlayPlacements.map((placement) => {
       const index = tileflowOverlayInsertionIndex(layers, placement);
-      const id = index < layers.length ? layers[index]?.id : void 0;
-      if (id !== void 0 && typeof id !== "string") {
+      const id2 = index < layers.length ? layers[index]?.id : void 0;
+      if (id2 !== void 0 && typeof id2 !== "string") {
         throw new Error(`Tileflow overlay placement ${placement} resolved an invalid layer ID.`);
       }
-      return [placement, id ?? null];
+      return [placement, id2 ?? null];
     })
   );
   return {
@@ -15013,10 +15558,10 @@ function compileSemanticStyleInternal(input, options, inspect, onReport) {
 function finalizeTileflowLayers(input) {
   const ids = /* @__PURE__ */ new Set();
   return input.map((layer, index) => {
-    const id = typeof layer.id === "string" ? layer.id : "";
-    if (!id) throw new Error(`Compiled Tileflow layer at index ${index} has no ID.`);
-    if (ids.has(id)) throw new Error(`Duplicate compiled Tileflow layer ID: ${id}`);
-    ids.add(id);
+    const id2 = typeof layer.id === "string" ? layer.id : "";
+    if (!id2) throw new Error(`Compiled Tileflow layer at index ${index} has no ID.`);
+    if (ids.has(id2)) throw new Error(`Duplicate compiled Tileflow layer ID: ${id2}`);
+    ids.add(id2);
     const minimum2 = layer.minzoom;
     const maximum2 = layer.maxzoom;
     for (const [name, value] of [
@@ -15025,11 +15570,11 @@ function finalizeTileflowLayers(input) {
     ]) {
       if (value === void 0) continue;
       if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 24) {
-        throw new Error(`Compiled Tileflow layer ${id} has invalid ${name}: ${String(value)}`);
+        throw new Error(`Compiled Tileflow layer ${id2} has invalid ${name}: ${String(value)}`);
       }
     }
     if (typeof minimum2 === "number" && typeof maximum2 === "number" && minimum2 > maximum2) {
-      throw new Error(`Compiled Tileflow layer ${id} requires minzoom <= maxzoom.`);
+      throw new Error(`Compiled Tileflow layer ${id2} requires minzoom <= maxzoom.`);
     }
     const metadata = isRecord8(layer.metadata) ? { ...layer.metadata } : void 0;
     if (metadata) {
@@ -15073,7 +15618,7 @@ function assertPreparedIconReferences(style, config, prepared) {
   const references = collectStyleImageReferences(style);
   if (references.size === 0) return;
   const available = new Set(prepared?.icons?.ids ?? []);
-  const missing = [...references].filter((id) => !available.has(id)).sort();
+  const missing = [...references].filter((id2) => !available.has(id2)).sort();
   if (missing.length === 0 && prepared?.icons?.sprite) return;
   const authoring = config.icons?.length ? "Run the Node build so map.icons directories are prepared." : "Declare map.icons with directories containing those canonical filenames.";
   throw new Error(
@@ -15177,7 +15722,8 @@ function assertGlyphFontStacks(style, config) {
     const font = layout?.["text-font"];
     if (!Array.isArray(font) || !font.every((entry) => typeof entry === "string")) continue;
     const stack = font.join(",");
-    if (stack && !declared.has(stack)) missing.add(stack);
+    const source = parseTileflowLineBackgroundFontStack(stack)?.source ?? stack;
+    if (stack && !declared.has(source)) missing.add(source);
   }
   if (missing.size > 0) {
     throw new Error(
@@ -15200,6 +15746,15 @@ function assertTextAssets(style, config) {
   }
   if (textLayers.length === 0) return;
   if (config.fonts !== void 0) {
+    const backed = style.layers.find((layer) => {
+      const font = isRecord8(layer.layout) ? layer.layout["text-font"] : void 0;
+      return Array.isArray(font) && font.length === 1 && typeof font[0] === "string" && parseTileflowLineBackgroundFontStack(font[0]) !== void 0;
+    });
+    if (backed) {
+      throw new Error(
+        `Tileflow map "${config.id}" layer "${String(backed.id)}" uses a line-fitted text background, which needs a glyphs provider; browser-rendered fonts cannot draw its cells.`
+      );
+    }
     if (config.fonts.length > 0) return;
     throw new Error(
       `Tileflow map "${config.id}" contains text but declares an empty fonts directory array.`
@@ -15416,10 +15971,10 @@ function resolveMap(map, options = {}) {
     }
   }
   const leaf = lineage[0];
-  const id = parseMapId(leaf.id);
+  const id2 = parseMapId(leaf.id);
   const resolved = {
-    id,
-    name: leaf.name ?? id,
+    id: id2,
+    name: leaf.name ?? id2,
     version: leaf.version,
     ...design,
     ...modules === void 0 ? {} : { modules }
@@ -15802,12 +16357,12 @@ function validateTileflowMap(input) {
 }
 
 // src/icon-preview.ts
-import { Color as Color4 } from "@maplibre/maplibre-gl-style-spec";
+import { Color as Color5 } from "@maplibre/maplibre-gl-style-spec";
 function resolveTileflowIconPreviewPaint(appearance) {
   return {
     ...appearance.defaults,
-    color: Color4.parse(appearance.defaults.color),
-    haloColor: Color4.parse(appearance.defaults.haloColor)
+    color: Color5.parse(appearance.defaults.color),
+    haloColor: Color5.parse(appearance.defaults.haloColor)
   };
 }
 function createTileflowIconPreviewRuntime() {
@@ -15928,13 +16483,13 @@ var operations = [
   },
   {
     api: "withRenderStack(module, { name: renderPass(...) })",
-    description: "Add an owner-local semantic pass around a semantic target.",
+    description: "Add an owner-local semantic pass at a band edge or beside a semantic target.",
     name: "render-pass",
     scope: "render-stack"
   },
   {
     api: "withRenderStack(module, { name: refineRenderTarget(...) })",
-    description: "Refine an owner-local semantic target without a physical layer patch.",
+    description: "Refine or move an owner-local semantic target without a physical layer patch.",
     name: "refine-render-target",
     scope: "render-stack"
   }
@@ -16081,6 +16636,7 @@ var expressionBuilders = [
     returns: "boolean",
     serializedOperator: "has"
   },
+  { arguments: [], name: "id", returns: "string | number | null", serializedOperator: "id" },
   {
     arguments: [
       "interpolation: linear | exponential(base) | cubic-bezier(x1,y1,x2,y2)",
@@ -16137,6 +16693,12 @@ var expressionBuilders = [
     returns: "number",
     serializedOperator: "min"
   },
+  {
+    arguments: ["dividend: number", "divisor: number"],
+    name: "modulo",
+    returns: "number",
+    serializedOperator: "%"
+  },
   {
     arguments: ["first: number", "second: number", "...rest: number[]"],
     name: "multiply",
@@ -16286,7 +16848,10 @@ var tileflowAuthoringManifest = deepFreeze2({
     geometries: [...tileflowRenderSelectorGeometries],
     limits: tileflowRenderStackLimits,
     operationNamePattern: tileflowRenderStackOperationNamePattern.source,
-    phases: [...tileflowRenderStackPhases],
+    placements: {
+      bands: [...tileflowBandPlacements],
+      targets: ["{ above: target }", "{ below: target }"]
+    },
     renderers: [...tileflowRenderStackRenderers],
     selectorKinds: [...tileflowRenderSelectorKinds],
     targetPattern: tileflowSemanticTargetPattern.source
@@ -16984,6 +17549,30 @@ function validateTileflowRuntimeSource(source) {
 function validateTileflowThemeSelection(value) {
   return value === "system" || isTileflowThemeName(value);
 }
+var tileflowThemeBlendLimits = Object.freeze({ maximumThemes: 8, minimumThemes: 2 });
+function validateTileflowThemeBlendSelection(value) {
+  if (!value || typeof value !== "object") return false;
+  const { position, themes } = value;
+  return Array.isArray(themes) && themes.length >= tileflowThemeBlendLimits.minimumThemes && themes.length <= tileflowThemeBlendLimits.maximumThemes && themes.every((theme) => isTileflowThemeName(theme)) && typeof position === "number" && Number.isFinite(position) && position >= 0 && position <= themes.length - 1;
+}
+function nearestTileflowBlendTheme(blend) {
+  const index = Math.min(blend.themes.length - 1, Math.max(0, Math.round(blend.position)));
+  return blend.themes[index];
+}
+function resolveTileflowRuntimeThemeBlend(options) {
+  if (!validateTileflowThemeBlendSelection(options.blend)) {
+    throw new TypeError(
+      "A Tileflow theme blend requires two to eight concrete themes and a position."
+    );
+  }
+  return options.blend.themes.map(
+    (theme) => resolveTileflowRuntimeStyle({
+      manifestMap: options.manifestMap,
+      source: options.source,
+      theme
+    })
+  );
+}
 function assertValidTileflowRuntimeSource(source) {
   const validation = validateTileflowRuntimeSource(source);
   if (!validation.ok) {
@@ -17936,7 +18525,7 @@ async function serializeTileflowIconsLockfile(input) {
 import { z as z12 } from "zod";
 var tileflowIconCompositionMaximumBytes = 1024 * 1024;
 var idsSchema = z12.array(tileflowIconIdSchema).max(tileflowIconPackageLimits.maxIconCount).refine(
-  (ids) => new Set(ids).size === ids.length && ids.every((id, index) => index === 0 || compareCodeUnits11(ids[index - 1], id) < 0),
+  (ids) => new Set(ids).size === ids.length && ids.every((id2, index) => index === 0 || compareCodeUnits11(ids[index - 1], id2) < 0),
   "Icon exports must be unique and sorted by code unit"
 );
 var localContributorSchema = z12.object({ kind: z12.literal("local"), iconIds: idsSchema }).strict();
@@ -18031,7 +18620,7 @@ var tileflowIconCompositionSchema = z12.object({
       teams.add(contributor.teamId);
       teamSlugs.add(contributor.reference.split("/")[0]);
     }
-    for (const id of contributor.iconIds) expected.set(id, ordinal);
+    for (const id2 of contributor.iconIds) expected.set(id2, ordinal);
   }
   if (teams.size !== 1 || teamSlugs.size !== 1)
     context.addIssue({
@@ -18123,12 +18712,14 @@ export {
   createStyle,
   createStyleResult,
   createTileflowIconPreviewRuntime,
+  createTileflowLineBackgroundFontStack,
   createTileflowSessionController,
   createTileflowSessionId,
   defaultTileflowManifestUrl,
   defaultTileflowRuntimeView,
   defineMap,
   defineTheme,
+  deriveTileflowLineBackgroundGlyphs,
   diffTileflowIconPackageManifests,
   diffTileflowMaps,
   disable,
@@ -18161,8 +18752,10 @@ export {
   maplibreOverlay,
   mergeTileflowAnalytics,
   nautical,
+  nearestTileflowBlendTheme,
   normalizeTileflowCaptureId,
   normalizeTileflowCaptureScene,
+  normalizeTileflowLineBackgroundMetrics,
   normalizeTileflowRuntimeCenter,
   normalizeTileflowStaticImageSize,
   normalizeTileflowUrl,
@@ -18172,6 +18765,7 @@ export {
   parseTileflowIconComposition,
   parseTileflowIconJson,
   parseTileflowIconsLockfile,
+  parseTileflowLineBackgroundFontStack,
   parseTileflowMap,
   parseTileflowRuntimeManifest,
   poi,
@@ -18193,12 +18787,14 @@ export {
   resolveTileflowMapMode,
   resolveTileflowRuntimeStyle,
   resolveTileflowRuntimeTheme,
+  resolveTileflowRuntimeThemeBlend,
   resolveTileflowRuntimeView,
   resolveTileflowStaticImageUrl,
   resolveTileflowTheme,
   roads,
   safeParseTileflowRuntimeManifest,
   scaleTileflowIconLayout,
+  scaleTileflowTextSizeForLineBackground,
   serializeCanonicalJson,
   serializeTileflowFontBundleManifest,
   serializeTileflowIconPackageManifest,
@@ -18208,6 +18804,7 @@ export {
   startTileflowSession,
   tileflowAuthoringManifest,
   tileflowAuthoringManifestSchemaVersion,
+  tileflowBandPlacements,
   tileflowBathymetryDemSourceId,
   tileflowBathymetrySourceId,
   tileflowBathymetryV1Schema,
@@ -18259,6 +18856,10 @@ export {
   tileflowIconsLockfileName,
   tileflowIconsLockfileSchema,
   tileflowLandformClasses,
+  tileflowLayerBands,
+  tileflowLineBackgroundDefaults,
+  tileflowLineBackgroundHaloRatio,
+  tileflowLineBackgroundLimits,
   tileflowLocalDirectoryMaximumLength,
   tileflowLocalDirectoryMessage,
   tileflowMapDefaultMaxDepth,
@@ -18275,7 +18876,6 @@ export {
   tileflowRenderSelectorGeometries,
   tileflowRenderSelectorKinds,
   tileflowRenderStackLimits,
-  tileflowRenderStackPhases,
   tileflowRenderStackRenderers,
   tileflowRenderedIconIdentitySchema,
   tileflowRenderedIconManifestEntrySchema,
@@ -18286,6 +18886,7 @@ export {
   tileflowSemanticDiffSchemaVersion,
   tileflowStyleFontFaceLimits,
   tileflowStyleFontFacesMetadataKey,
+  tileflowThemeBlendLimits,
   tileflowThemeLimits,
   tileflowThemeNameSchema,
   tileflowThemeTokenCategories,
@@ -18304,6 +18905,7 @@ export {
   validateTileflowDataCompatibility,
   validateTileflowMap,
   validateTileflowRuntimeSource,
+  validateTileflowThemeBlendSelection,
   validateTileflowThemeSelection,
   validateTileflowWorldV1Tilejson,
   vectorTiles,