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

package/dist/build.js

@@ -504,9 +504,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
     }))
   };
 }
@@ -880,6 +880,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({
@@ -906,6 +947,98 @@ 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;
+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";
+}
+
 // src/cartography/expression-operators.ts
 var mapLibreExpressionOperators = /* @__PURE__ */ new Set([
   "!",
@@ -1216,8 +1349,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(asRecord(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 color2 = toMapLibreStyleValue(background.color);
+    if (typeof color2 === "string" && (Color2.parse(color2)?.a ?? 1) < 1) {
+      throw new Error(
+        `Layer "${id2}" needs an opaque line-fitted background colour; "${color2}" is translucent.`
+      );
+    }
+    paint["text-halo-color"] = color2;
+  }
+  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 = { ...asRecord(layer.paint) };
   const layout = { ...asRecord(layer.layout) };
@@ -1360,12 +1537,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
     );
@@ -1378,7 +1555,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 asRecord(value) {
@@ -1569,7 +1746,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]
@@ -1591,7 +1768,7 @@ function compileAeroways(request, context) {
           },
           style
         ),
-        localOrder: order + phaseOrder2,
+        localOrder: order + phaseOrder,
         owner: "aeroways",
         slot: "aeroways",
         target: `aeroways.${name}.${phase}`
@@ -2373,14 +2550,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,
@@ -2405,14 +2582,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,
@@ -2424,7 +2601,7 @@ function compileLabels(request, roadRequest, context) {
           },
           mergeTileflowDesign(style, { text: { field: field2 } })
         ),
-        navigationPriority ? "symbols" : "transport-symbols",
+        "symbols",
         { group: "roads", kind: "road-label", member: roadClass }
       )
     );
@@ -2516,8 +2693,7 @@ function compileLabels(request, roadRequest, context) {
               ]
             },
             style
-          ),
-          "transport-symbols"
+          )
         )
       );
     }
@@ -2555,8 +2731,7 @@ function compileLabels(request, roadRequest, context) {
               ])
             }
           })
-        ),
-        "transport-symbols"
+        )
       )
     );
   }
@@ -6608,10 +6783,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
     );
@@ -6621,7 +6796,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) {
@@ -8048,7 +8223,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
     });
@@ -8085,22 +8260,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;
@@ -8112,7 +8278,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 z5 } from "zod";
 
 // src/cartography/data-expression.ts
@@ -8130,6 +8296,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");
@@ -8180,6 +8349,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)]);
@@ -8385,6 +8557,7 @@ function visitExpression(value, path, variables, issues) {
       }
       return;
     }
+    case "id":
     case "zoom": {
       exact(1);
       return;
@@ -8434,6 +8607,7 @@ function visitExpression(value, path, variables, issues) {
     }
     case "-":
     case "/":
+    case "%":
     case "!=":
     case "<":
     case "<=":
@@ -8658,6 +8832,7 @@ var expr = Object.freeze({
   gt: (left, right) => compare(">", left, right),
   gte: (left, right) => compare(">=", left, right),
   has,
+  id,
   featureState,
   interpolate: interpolate2,
   let: letValue,
@@ -8667,6 +8842,7 @@ var expr = Object.freeze({
   match,
   max: maximum,
   min: minimum,
+  modulo,
   multiply,
   ne: (left, right) => compare("!=", left, right),
   not,
@@ -8799,7 +8975,7 @@ function createTileflowLayerFamilyIR(contribution) {
 function createTileflowLayerTemplateIR(layer, semanticKey) {
   const {
     filter,
-    id,
+    id: id2,
     layout,
     maxzoom,
     metadata,
@@ -8810,7 +8986,7 @@ function createTileflowLayerTemplateIR(layer, semanticKey) {
     type,
     ...properties2
   } = 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."
@@ -8825,7 +9001,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);
@@ -9107,13 +9283,6 @@ function isRecord5(value) {
 }
 
 // src/cartography/render-stack.ts
-var tileflowRenderStackPhases = [
-  "underlay",
-  "overlay",
-  "postRelief",
-  "annotation",
-  "finish"
-];
 var tileflowRenderStackRenderers = [
   "background",
   "circle",
@@ -9309,7 +9478,6 @@ var geometryTypes = {
   point: "Point",
   polygon: "Polygon"
 };
-var phaseOrder = new Map(tileflowRenderStackPhases.map((phase, index) => [phase, index]));
 function compileRenderStack(module, data) {
   if (!tileflowLayerDomains.includes(module.type)) {
     throw renderStackError("invalid-owner", `Unknown render-stack owner: ${String(module.type)}.`);
@@ -9327,71 +9495,118 @@ function compileRenderSelector(selector, data) {
 }
 function applyCompiledRenderStacks(input, operations) {
   let layers = input.map(cloneJson21);
-  const activeOwners = new Set(layers.map(({ owner }) => owner));
-  const layerOperations = operations.filter(
+  const passes = operations.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 = operations.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 = operations.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(
@@ -9399,26 +9614,48 @@ function applyCompiledRenderStacks(input, operations) {
         `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,
@@ -9428,6 +9665,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,
@@ -9441,6 +9693,7 @@ function compileOperation(owner, name, operation, order, data) {
     order,
     owner,
     patch,
+    ...placement,
     renderer: operation.renderer,
     requirements,
     target: operation.target
@@ -9618,26 +9871,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 = {
@@ -9653,7 +9922,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,
@@ -9684,10 +9954,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)) {
@@ -9807,13 +10101,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.`
     );
   }
 }
@@ -9860,18 +10156,16 @@ function requireUniqueCompiledLayers(layers, operations) {
   }
 }
 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(
@@ -9883,11 +10177,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",
@@ -10522,6 +10815,11 @@ var textStyleSchema = z5.object({
     "top-left",
     "top-right"
   ]).optional(),
+  background: z5.object({
+    color: colorValueSchema,
+    fit: z5.literal("lines"),
+    padding: themeNumberValueSchema.optional()
+  }).strict().optional(),
   color: colorValueSchema.optional(),
   fallbacks: moduleFontFallbacksSchema.optional(),
   field: stringValueSchema.optional(),
@@ -10768,12 +11066,16 @@ var renderRequirementsSchema = z5.array(z5.enum(tileflowLayerDomains)).min(1).ma
     seen.add(requirement);
   }
 });
+var renderPlacementSchema = z5.union([
+  z5.enum(tileflowBandPlacements),
+  z5.object({ above: renderTargetSchema }).strict(),
+  z5.object({ below: renderTargetSchema }).strict()
+]);
 var vectorRenderPassSchemas = tileflowRenderStackRenderers.filter((renderer) => renderer !== "background").map(
   (renderer) => z5.object({
-    attachTo: renderTargetSchema,
     feature: z5.enum(tileflowSemanticLayerNames).optional(),
     kind: z5.literal("render-pass"),
-    phase: z5.enum(tileflowRenderStackPhases),
+    placement: renderPlacementSchema,
     renderer: z5.literal(renderer),
     requirements: renderRequirementsSchema.optional(),
     selector: renderSelectorSchema.optional(),
@@ -10782,9 +11084,8 @@ var vectorRenderPassSchemas = tileflowRenderStackRenderers.filter((renderer) =>
 );
 var renderPassSchema = z5.discriminatedUnion("renderer", [
   z5.object({
-    attachTo: renderTargetSchema,
     kind: z5.literal("render-pass"),
-    phase: z5.enum(tileflowRenderStackPhases),
+    placement: renderPlacementSchema,
     renderer: z5.literal("background"),
     requirements: renderRequirementsSchema.optional(),
     style: renderStyleSchemas.background
@@ -10794,6 +11095,7 @@ var renderPassSchema = z5.discriminatedUnion("renderer", [
 var renderRefinementSchemas = tileflowRenderStackRenderers.map(
   (renderer) => z5.object({
     kind: z5.literal("refine-render-target"),
+    placement: renderPlacementSchema.optional(),
     requirements: renderRequirementsSchema.optional(),
     renderer: z5.literal(renderer),
     ...renderer === "background" ? {} : { selector: renderSelectorSchema.optional() },
@@ -10801,7 +11103,17 @@ var renderRefinementSchemas = tileflowRenderStackRenderers.map(
     target: renderTargetSchema
   }).strict()
 );
-var renderStackOperationSchema = z5.union([renderPassSchema, ...renderRefinementSchemas]);
+var renderPlacementRefinementSchema = z5.object({
+  kind: z5.literal("refine-render-target"),
+  placement: renderPlacementSchema,
+  requirements: renderRequirementsSchema.optional(),
+  target: renderTargetSchema
+}).strict();
+var renderStackOperationSchema = z5.union([
+  renderPassSchema,
+  ...renderRefinementSchemas,
+  renderPlacementRefinementSchema
+]);
 var renderStackSchema = z5.record(renderStackOperationNameSchema, renderStackOperationSchema).superRefine((stack, context) => {
   const size = Object.keys(stack).length;
   if (size === 0) {
@@ -11643,7 +11955,7 @@ var terrainSchema = z5.union([
     url: z5.string().trim().min(1).optional()
   }).strict()
 ]);
-var atmosphereColorLiteralSchema = z5.string().refine((value) => Color2.parse(value)?.a === 1, "Expected an opaque color");
+var atmosphereColorLiteralSchema = z5.string().refine((value) => Color3.parse(value)?.a === 1, "Expected an opaque color");
 var atmosphereColorSchema = z5.union([
   atmosphereColorLiteralSchema,
   fixedStringSchema.extend({ value: atmosphereColorLiteralSchema }),
@@ -12166,7 +12478,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 z7 } from "zod";
 
 // src/icon-layout.ts
@@ -12224,7 +12536,7 @@ function assertTileflowIconLayoutBounds(layout, width, height) {
 }
 
 // src/icon-appearance.ts
-var color = z7.string().max(128).refine((value) => Color3.parse(value) !== void 0, "Expected a MapLibre color");
+var color = z7.string().max(128).refine((value) => Color4.parse(value) !== void 0, "Expected a MapLibre color");
 var tileflowIconAppearanceSchema = z7.object({
   representation: z7.literal("sdf"),
   defaults: z7.object({
@@ -12257,9 +12569,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) {
@@ -12270,7 +12582,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}`,
@@ -12288,7 +12600,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(
@@ -12400,7 +12712,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];
@@ -12411,7 +12723,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]
   ];
 }
@@ -12421,18 +12733,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
@@ -12531,11 +12843,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 {
@@ -13759,10 +14071,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 [
@@ -13771,11 +14083,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) {
@@ -13819,7 +14131,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(
@@ -13923,7 +14235,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(
@@ -13946,6 +14259,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.`
@@ -14525,10 +14847,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 }
@@ -15036,7 +15358,7 @@ function containsControlCharacter(value) {
 // src/icon-composition.ts
 var tileflowIconCompositionMaximumBytes = 1024 * 1024;
 var idsSchema = z10.array(tileflowIconIdSchema).max(tileflowIconPackageLimits.maxIconCount).refine(
-  (ids) => new Set(ids).size === ids.length && ids.every((id, index) => index === 0 || compareCodeUnits8(ids[index - 1], id) < 0),
+  (ids) => new Set(ids).size === ids.length && ids.every((id2, index) => index === 0 || compareCodeUnits8(ids[index - 1], id2) < 0),
   "Icon exports must be unique and sorted by code unit"
 );
 var localContributorSchema = z10.object({ kind: z10.literal("local"), iconIds: idsSchema }).strict();
@@ -15131,7 +15453,7 @@ var tileflowIconCompositionSchema = z10.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({
@@ -24375,9 +24697,9 @@ function validateNativeStyle(input, options, stage) {
   if (Object.keys(sources).length > tileflowNativeProfileLimits.maximumSources) {
     add2("NATIVE_UNSUPPORTED_SOURCE", "/sources");
   }
-  for (const id of Object.keys(sources).sort().slice(0, tileflowNativeProfileLimits.maximumSources)) {
-    const source = sources[id];
-    const path = nativePointer("/sources", id);
+  for (const id2 of Object.keys(sources).sort().slice(0, tileflowNativeProfileLimits.maximumSources)) {
+    const source = sources[id2];
+    const path = nativePointer("/sources", id2);
     if (!record2(source) || typeof source.type !== "string" || !sourceKinds.has(source.type)) {
       add2("NATIVE_UNSUPPORTED_SOURCE", path);
       continue;
@@ -24672,8 +24994,8 @@ var teamSourcesSchema = z14.record(
   const entries = Object.entries(sources);
   const tilesets = /* @__PURE__ */ new Set();
   if (entries.length > 16) context.addIssue({ code: "custom", message: "Too many Team sources" });
-  for (const [id, value] of entries) {
-    if (id === "tileflow" || id.startsWith("tileflow-") || ["world", "terrain"].includes(value.tileset) || tilesets.has(value.tileset))
+  for (const [id2, value] of entries) {
+    if (id2 === "tileflow" || id2.startsWith("tileflow-") || ["world", "terrain"].includes(value.tileset) || tilesets.has(value.tileset))
       context.addIssue({ code: "custom", message: "Invalid logical Team source binding" });
     tilesets.add(value.tileset);
   }
@@ -24784,11 +25106,11 @@ async function parseTileflowRendererDeploymentArtifact(input) {
 function nativeValidationStyle(style, bindings) {
   const copy = JSON.parse(serializeCanonicalJson(style));
   const sources = object(copy.sources);
-  for (const [id, binding] of Object.entries(bindings)) {
-    const source = object(sources?.[id]);
-    if (!source || source.type !== binding.type || source.url !== `tileflow://hosted-sources/${id}` || source.tiles !== void 0)
+  for (const [id2, binding] of Object.entries(bindings)) {
+    const source = object(sources?.[id2]);
+    if (!source || source.type !== binding.type || source.url !== `tileflow://hosted-sources/${id2}` || source.tiles !== void 0)
       throw new Error();
-    source.url = `https://artifacts.invalid/tiles/${id}/tiles.json`;
+    source.url = `https://artifacts.invalid/tiles/${id2}/tiles.json`;
   }
   return copy;
 }
@@ -24942,7 +25264,7 @@ function createStyleFromCatalog(catalog, mapName, options = {}) {
   };
   return compileSemanticStyle(resolved, {
     ...options,
-    map: { ...metadata, lineage: metadata.lineage.map(({ id }) => id) }
+    map: { ...metadata, lineage: metadata.lineage.map(({ id: id2 }) => id2) }
   });
 }
 function createStyleFromCatalogWithInspection(catalog, mapName, options = {}) {
@@ -24957,7 +25279,7 @@ function createStyleFromCatalogWithInspection(catalog, mapName, options = {}) {
   };
   return compileSemanticStyleWithInspection(resolved, {
     ...options,
-    map: { ...metadata, lineage: metadata.lineage.map(({ id }) => id) }
+    map: { ...metadata, lineage: metadata.lineage.map(({ id: id2 }) => id2) }
   });
 }
 function createStylesFromCatalog(catalog, options = {}) {