@mailwoman/map-tui 9.1.1 → 9.3.0

package/lib/input.ts

@@ -0,0 +1,288 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+/**
+ * Terminal input decoding for the interactive map browser.
+ *
+ * `decodeInputChunk` turns a raw-mode stdin chunk into zero or more {@link MapTUIInput} events. It stays pure — the
+ * caller owns the only state there is, the unresolved trailing fragment the function hands back — so one chunk in gives
+ * the same events out every time.
+ *
+ * THE FALLBACK IS THE DANGEROUS PART. An ESC this decoder had no rule for used to mean "the Esc key", i.e. QUIT, which
+ * made every unrecognized escape sequence a quit: F1 (`ESC O P`), an OSC reply the terminal sends unasked (`ESC ] 11 ;
+ * rgb:… BEL`), and — worst, because it needs no exotic key at all — a mouse report split across two stdin reads, whose
+ * first half ends inside the sequence. So the fallback now separates three cases:
+ *
+ * - A sequence this decoder recognizes is consumed and acted on (arrows, SGR mouse).
+ * - A sequence it does NOT recognize is consumed WHOLE and ignored: CSI (`ESC [ … final`), SS3 (`ESC O final`), and the
+ *   string family (OSC/DCS/SOS/PM/APC, terminated by BEL or ST). Re-scanning their bodies as characters is how a `q`
+ *   inside a cursor-position report quit the app.
+ * - A chunk that ENDS mid-sequence — including a lone trailing ESC, which is byte-for-byte the start of one — is not
+ *   decoded at all: it comes back as {@link DecodedInput.pending} for the caller to prepend to the next chunk. Quit is
+ *   emitted only for an ESC that is neither, i.e. one whose following byte cannot continue a sequence.
+ *
+ * Holding costs a lone Esc keypress its effect until the next byte arrives. That is the right side of the trade for a
+ * browser whose advertised quit keys are `q` and Ctrl+C: the alternative is a drag ending the session because the
+ * kernel split a read.
+ *
+ * Mouse reports are SGR-encoded (DEC private mode 1006), which is what {@link MOUSE_ENABLE} asks for. Their coordinates
+ * are 1-based on the wire and 0-based in every event here — the off-by-one lives at this boundary and nowhere else.
+ */
+
+/**
+ * Enables mouse reporting: button events (1000), drag/button-motion tracking (1002), and SGR extended coordinates
+ * (1006) so columns past 223 survive.
+ */
+export const MOUSE_ENABLE = "\u001B[?1000h\u001B[?1002h\u001B[?1006h"
+
+/**
+ * Disables mouse reporting, in the reverse order it was enabled.
+ */
+export const MOUSE_DISABLE = "\u001B[?1006l\u001B[?1002l\u001B[?1000l"
+
+/**
+ * A decoded input event. Pan and zoom carry direction and magnitude only — how far a step moves the map is the
+ * browser's decision, not the decoder's.
+ */
+export type MapTUIInput =
+	| { kind: "quit" }
+	/**
+	 * Ctrl+C. Distinct from `quit` because the process must exit 130, and because raw mode means no SIGINT is raised.
+	 */
+	| { kind: "interrupt" }
+	| { kind: "pan"; dx: number; dy: number }
+	| { kind: "zoom"; delta: number }
+	| { kind: "wheel"; delta: number; column: number; row: number }
+	| { kind: "press"; column: number; row: number }
+	| { kind: "drag"; column: number; row: number }
+	| { kind: "release" }
+
+const ESC = "\u001B"
+const CTRL_C = "\u0003"
+
+/* oxlint-disable no-control-regex -- ESC (U+001B) is the byte every pattern below exists to match. A decoder of
+   terminal escape sequences cannot avoid the control character the sequences are made of. */
+
+/**
+ * SGR mouse report: `ESC [ < button ; column ; row (M|m)`, where `M` is a press/motion and `m` a release.
+ */
+const MOUSE_SGR_PATTERN = /\u001B\[<(\d+);(\d+);(\d+)([Mm])/y
+
+/**
+ * Cursor keys, in both normal (`ESC [ A`) and application (`ESC O A`) modes — a terminal may be left in either.
+ */
+const ARROW_PATTERN = /\u001B(?:\[|O)([ABCD])/y
+
+/**
+ * Any other CSI sequence, consumed whole and ignored. Without this, an unhandled sequence's body would be re-scanned as
+ * individual key presses, and a stray `q` inside one would quit the app.
+ */
+const UNKNOWN_CSI_PATTERN = /\u001B\[[\d;<>?]*[\u0020-\u002F]*[\u0040-\u007E]/y
+
+/**
+ * Any other SS3 sequence (`ESC O <final>`) — F1–F4 on xterm, and the numeric keypad in application mode. Two bytes
+ * shorter than a CSI, and until this pattern existed the likeliest key on a keyboard to quit the browser by accident.
+ */
+const UNKNOWN_SS3_PATTERN = /\u001BO[\u0040-\u007E]/y
+
+/**
+ * The string-sequence family: OSC (`ESC ]`), DCS (`ESC P`), SOS (`ESC X`), PM (`ESC ^`), APC (`ESC _`), each running to
+ * a BEL or an ST (`ESC \`). A terminal sends these UNASKED — an OSC colour or clipboard reply lands on stdin with no
+ * key pressed — so consuming them is not a nicety.
+ */
+const STRING_SEQUENCE_PATTERN = /\u001B[P\]X^_][\s\S]*?(?:\u0007|\u001B\\)/y
+
+/**
+ * Every "unrecognized but complete" sequence, in the order they are tried. Sharing one list is what keeps a new
+ * sequence family from being added to the consumer and forgotten in the incomplete test below.
+ */
+const UNRECOGNIZED_PATTERNS = [UNKNOWN_CSI_PATTERN, UNKNOWN_SS3_PATTERN, STRING_SEQUENCE_PATTERN] as const
+
+/**
+ * A chunk that STOPS inside a sequence. The end-anchors are what make these "incomplete" rather than "unrecognized":
+ * each requires the WHOLE remainder of the chunk to be a legal prefix and nothing more. The first covers both a lone
+ * trailing ESC and an `ESC O` still waiting for its final byte.
+ */
+const PARTIAL_PATTERNS = [/\u001BO?$/y, /\u001B\[[\d;<>?]*[\u0020-\u002F]*$/y, /\u001B[P\]X^_][^\u0007]*$/y] as const
+
+/* oxlint-enable no-control-regex */
+
+/**
+ * Wheel reports set bit 6 of the button field; the low bit then separates up (0) from down (1).
+ */
+const WHEEL_FLAG = 64
+
+/**
+ * Motion reports set bit 5. With mode 1002 that means "moved with a button held" — a drag.
+ */
+const MOTION_FLAG = 32
+
+const BUTTON_MASK = 3
+const LEFT_BUTTON = 0
+
+/**
+ * The longest fragment worth holding for the next chunk (64 KB). See the drop site: this bounds an unterminated string
+ * sequence, not a real key.
+ */
+const MAX_PENDING_LENGTH = 65_536
+
+const ARROW_INPUTS: Record<string, MapTUIInput> = {
+	A: { kind: "pan", dx: 0, dy: -1 },
+	B: { kind: "pan", dx: 0, dy: 1 },
+	C: { kind: "pan", dx: 1, dy: 0 },
+	D: { kind: "pan", dx: -1, dy: 0 },
+}
+
+/**
+ * Single-character bindings. `a`/`z` are mapscii's zoom keys, `+`/`-` the ones every other map uses, and `hjkl` the vim
+ * pan set mapscii also accepts. `y` joins `z` for zoom-out because on a QWERTZ keyboard it sits where `z` does on
+ * QWERTY — mapscii binds both for the same reason.
+ */
+const CHARACTER_INPUTS: Record<string, MapTUIInput> = {
+	q: { kind: "quit" },
+	Q: { kind: "quit" },
+	"+": { kind: "zoom", delta: 1 },
+	"=": { kind: "zoom", delta: 1 },
+	a: { kind: "zoom", delta: 1 },
+	"-": { kind: "zoom", delta: -1 },
+	_: { kind: "zoom", delta: -1 },
+	z: { kind: "zoom", delta: -1 },
+	y: { kind: "zoom", delta: -1 },
+	h: { kind: "pan", dx: -1, dy: 0 },
+	j: { kind: "pan", dx: 0, dy: 1 },
+	k: { kind: "pan", dx: 0, dy: -1 },
+	l: { kind: "pan", dx: 1, dy: 0 },
+}
+
+/**
+ * One decoded chunk: its events, plus whatever trailing bytes could not be decoded YET.
+ */
+export interface DecodedInput {
+	events: MapTUIInput[]
+	/**
+	 * An unresolved escape fragment from the end of the chunk — prepend it to the next one. Empty when the chunk ended
+	 * cleanly, which is the overwhelmingly common case.
+	 */
+	pending: string
+}
+
+/**
+ * The length of the unrecognized-but-complete sequence at `index`, or null when there isn't one.
+ */
+function consumeUnrecognized(buffer: string, index: number): number | null {
+	for (const pattern of UNRECOGNIZED_PATTERNS) {
+		pattern.lastIndex = index
+
+		if (pattern.exec(buffer)) return pattern.lastIndex
+	}
+
+	return null
+}
+
+/**
+ * True when everything from `index` to the end of the chunk is a legal PREFIX of a sequence — i.e. the terminal is
+ * mid-sequence and the rest is in the next read.
+ */
+function isIncompleteSequence(buffer: string, index: number): boolean {
+	for (const pattern of PARTIAL_PATTERNS) {
+		pattern.lastIndex = index
+
+		if (pattern.exec(buffer)) return true
+	}
+
+	return false
+}
+
+/**
+ * Builds the event for one SGR mouse report.
+ */
+function mouseInput(button: number, column: number, row: number, final: string): MapTUIInput | null {
+	if (button & WHEEL_FLAG) {
+		return { kind: "wheel", delta: button & 1 ? -1 : 1, column, row }
+	}
+
+	if (final === "m") return { kind: "release" }
+
+	if ((button & BUTTON_MASK) !== LEFT_BUTTON) return null
+
+	return button & MOTION_FLAG ? { kind: "drag", column, row } : { kind: "press", column, row }
+}
+
+/**
+ * Decodes one raw-mode stdin chunk into input events. Unrecognized bytes are dropped; an unresolved trailing escape
+ * fragment is returned rather than decoded, and the caller passes it back as `pending` with the next chunk.
+ */
+export function decodeInputChunk(chunk: string, pending = ""): DecodedInput {
+	const events: MapTUIInput[] = []
+	const buffer = pending + chunk
+	let index = 0
+
+	while (index < buffer.length) {
+		const character = buffer[index]!
+
+		if (character !== ESC) {
+			const input = character === CTRL_C ? { kind: "interrupt" as const } : CHARACTER_INPUTS[character]
+
+			if (input) {
+				events.push(input)
+			}
+
+			index += 1
+
+			continue
+		}
+
+		MOUSE_SGR_PATTERN.lastIndex = index
+		const mouse = MOUSE_SGR_PATTERN.exec(buffer)
+
+		if (mouse) {
+			const input = mouseInput(Number(mouse[1]), Number(mouse[2]) - 1, Number(mouse[3]) - 1, mouse[4]!)
+
+			if (input) {
+				events.push(input)
+			}
+
+			index = MOUSE_SGR_PATTERN.lastIndex
+
+			continue
+		}
+
+		ARROW_PATTERN.lastIndex = index
+		const arrow = ARROW_PATTERN.exec(buffer)
+
+		if (arrow) {
+			events.push(ARROW_INPUTS[arrow[1]!]!)
+			index = ARROW_PATTERN.lastIndex
+
+			continue
+		}
+
+		const consumed = consumeUnrecognized(buffer, index)
+
+		if (consumed !== null) {
+			index = consumed
+
+			continue
+		}
+
+		// The buffer stops inside a sequence — hand the fragment back instead of guessing at it.
+		if (isIncompleteSequence(buffer, index)) {
+			const fragment = buffer.slice(index)
+
+			// …unless it has stopped being plausible. An unterminated string sequence would otherwise grow the held
+			// fragment for the life of the process. Dropping is the safe failure: it emits nothing, where flushing
+			// the fragment back through the decoder would read its body as keys, which is the bug this all exists
+			// for. The cap is generous because an OSC 52 clipboard reply is legitimately large.
+			return { events, pending: fragment.length > MAX_PENDING_LENGTH ? "" : fragment }
+		}
+
+		// An ESC whose next byte cannot continue a sequence: the Esc KEY.
+		events.push({ kind: "quit" })
+		index += 1
+	}
+
+	return { events, pending: "" }
+}

package/{mercator.ts → lib/mercator.ts}

@@ -53,3 +53,23 @@ const EARTH_CIRCUMFERENCE_M = 40_075_016.686
 export function metersPerPixel(lat: number, zoom: number): number {
 	return (EARTH_CIRCUMFERENCE_M * Math.cos((lat * Math.PI) / 180)) / (TILE_SIZE * 2 ** zoom)
 }
+
+/**
+ * Wraps a longitude into [-180, 180) so panning past the antimeridian continues rather than running off the pyramid.
+ */
+export function wrapLongitude(lon: number): number {
+	const wrapped = (((lon + 180) % 360) + 360) % 360
+
+	return wrapped - 180
+}
+
+/**
+ * Subpixel dimensions of one braille cell — 2 columns wide, 4 rows tall. The unit every projection-to-cell conversion
+ * works in, shared by the renderer and the browser so both sides of the frame boundary agree on the grid.
+ */
+export const SUBPIXEL_COLUMNS_PER_CELL = 2
+
+/**
+ * See {@link SUBPIXEL_COLUMNS_PER_CELL} — the vertical half of the braille 2×4 subpixel grid.
+ */
+export const SUBPIXEL_ROWS_PER_CELL = 4

package/{mvt.ts → lib/mvt.ts}

@@ -12,7 +12,7 @@
  */
 
 import { VectorTile } from "@mapbox/vector-tile"
-import Pbf from "pbf"
+import { PbfReader } from "pbf"
 
 export interface DecodedFeature {
 	/**
@@ -34,7 +34,7 @@ export interface DecodedLayer {
 }
 
 export function decodeMVT(data: Uint8Array): DecodedLayer[] {
-	const tile = new VectorTile(new Pbf(data))
+	const tile = new VectorTile(new PbfReader(data))
 
 	return Object.entries(tile.layers).map(([name, layer]) => {
 		const features: DecodedFeature[] = []

package/{raster.ts → lib/raster.ts}

@@ -13,7 +13,7 @@
  * {@link fillPolygon} does not — its scanline edge math keeps ring vertices as given, see its own docstring.
  */
 
-import type { RGB } from "./style.ts"
+import type { RGB } from "#style"
 
 /**
  * A row-major RGBA pixel buffer. Alpha starts at 0 (unlit/transparent) everywhere; drawing a pixel sets it to 255,

package/{renderer.ts → lib/renderer.ts}

@@ -15,12 +15,20 @@
  * requested marker always wins the cell.
  */
 
-import { type MapFrame, overlayText, rasterizeToFrame, rgbToPacked } from "./frame.ts"
-import { lonLatToWorldPx, metersPerPixel, TILE_SIZE } from "./mercator.ts"
-import type { DecodedFeature } from "./mvt.ts"
-import { drawCircle, drawPolyline, fillPolygon, RGBAGrid } from "./raster.ts"
-import { type LayerStyle, type RGB, stylesFor } from "./style.ts"
-import type { DecodedTile, TileSource } from "./tile-source.ts"
+import { clamp } from "@mailwoman/core/numeric"
+
+import { type MapFrame, overlayText, rasterizeToFrame, rgbToPacked } from "#frame"
+import {
+	lonLatToWorldPx,
+	metersPerPixel,
+	SUBPIXEL_COLUMNS_PER_CELL,
+	SUBPIXEL_ROWS_PER_CELL,
+	TILE_SIZE,
+} from "#mercator"
+import type { DecodedFeature } from "#mvt"
+import { drawCircle, drawPolyline, fillPolygon, RGBAGrid } from "#raster"
+import { type LayerStyle, type RGB, styleForFeatureKind, stylesFor } from "#style"
+import type { DecodedTile, TileProvider } from "#tile-source"
 
 export interface Viewport {
 	centerLon: number
@@ -46,12 +54,6 @@ export interface RingSpec {
 const DEFAULT_MARKER_CHAR = "●"
 const DEFAULT_MARKER_COLOR: RGB = [255, 80, 80]
 
-/**
- * Subpixel dimensions per braille cell: 2 columns wide, 4 rows tall.
- */
-const SUBPIXEL_COLUMNS_PER_CELL = 2
-const SUBPIXEL_ROWS_PER_CELL = 4
-
 /**
  * Minimum ring radius (in device pixels) worth drawing — smaller than this, the midpoint circle algorithm degenerates
  * to a single point or nothing useful.
@@ -84,22 +86,35 @@ interface GridOrigin {
  * — that's what keeps `rasterizeFeature` under `max-params` (8) once `style`, `renderZoom`, and `pendingLabels` join
  * it. Threaded through as a value rather than closed over so those rasterizers stay free functions (no nesting inside
  * `renderFrame` deep enough to trip `max-depth`).
+ *
+ * `worldX`/`worldY` are the tile's top-left corner in render-zoom world pixels — for a native tile that is `tileX *
+ * TILE_SIZE`, for an overzoomed parent it is scaled by the tile's span, so the projection needs no zoom arithmetic of
+ * its own.
  */
 interface TileProjection {
-	tileX: number
-	tileY: number
+	worldX: number
+	worldY: number
 	scale: number
 	origin: GridOrigin
 }
 
-function clamp(value: number, min: number, max: number): number {
-	return Math.min(Math.max(value, min), max)
+/**
+ * A tile chosen for a viewport slot: the native tile when the archive has one, otherwise the nearest ancestor that
+ * exists. `span` is how many render-zoom world pixels the tile covers (`TILE_SIZE << dz` for an ancestor `dz` levels
+ * up) — a spatially sparse archive (deep zooms only where people are) degrades to coarse geometry instead of blank
+ * cells.
+ */
+interface ResolvedTile {
+	tile: DecodedTile
+	tileX: number
+	tileY: number
+	span: number
 }
 
 function projectPoint(projection: TileProjection, gx: number, gy: number): ProjectedPoint {
 	return {
-		x: projection.tileX * TILE_SIZE + gx * projection.scale - projection.origin.x,
-		y: projection.tileY * TILE_SIZE + gy * projection.scale - projection.origin.y,
+		x: projection.worldX + gx * projection.scale - projection.origin.x,
+		y: projection.worldY + gy * projection.scale - projection.origin.y,
 	}
 }
 
@@ -178,23 +193,28 @@ function rasterizeFeature(
  */
 function rasterizeTileForKind(
 	grid: RGBAGrid,
-	tile: DecodedTile,
-	tileX: number,
-	tileY: number,
+	resolved: ResolvedTile,
 	kind: LayerStyle["kind"],
 	renderZoom: number,
 	origin: GridOrigin,
 	pendingLabels: PendingLabel[]
 ): void {
-	for (const layer of tile.layers) {
+	for (const layer of resolved.tile.layers) {
 		const styles = stylesFor(layer.name, renderZoom).filter((style) => style.kind === kind)
 
 		if (!styles.length) continue
 
-		const projection: TileProjection = { tileX, tileY, scale: TILE_SIZE / layer.extent, origin }
+		const projection: TileProjection = {
+			worldX: resolved.tileX * resolved.span,
+			worldY: resolved.tileY * resolved.span,
+			scale: resolved.span / layer.extent,
+			origin,
+		}
+
+		for (const feature of layer.features) {
+			const style = styleForFeatureKind(styles, feature.properties.kind)
 
-		for (const style of styles) {
-			for (const feature of layer.features) {
+			if (style) {
 				rasterizeFeature(grid, feature, style, renderZoom, projection, pendingLabels)
 			}
 		}
@@ -207,12 +227,48 @@ function rasterizeTileForKind(
  * `TileSource` — it holds no per-frame state itself.
  */
 export class MapRenderer {
-	private readonly source: TileSource
+	private readonly source: TileProvider
 
-	constructor(source: TileSource) {
+	constructor(source: TileProvider) {
 		this.source = source
 	}
 
+	/**
+	 * Resolves each viewport slot to its native tile or, when the archive has none — a spatially sparse deep band, a
+	 * zoom-capped extract — the nearest existing ancestor. Ancestors shared by several absent slots are deduplicated so
+	 * their geometry rasterizes once, and coarse tiles sort first so native detail paints over the fallback wherever both
+	 * cover a cell.
+	 */
+	private async resolveTiles(
+		tileCoords: ReadonlyArray<{ x: number; y: number }>,
+		renderZoom: number
+	): Promise<ResolvedTile[]> {
+		const resolved = new Map<string, ResolvedTile>()
+
+		await Promise.all(
+			tileCoords.map(async ({ x, y }) => {
+				for (let zoom = renderZoom; zoom >= this.source.minZoom; zoom--) {
+					const shift = renderZoom - zoom
+					const tileX = x >> shift
+					const tileY = y >> shift
+					const key = `${zoom}/${tileX}/${tileY}`
+
+					if (resolved.has(key)) return
+
+					const tile = await this.source.getTile(zoom, tileX, tileY)
+
+					if (tile) {
+						resolved.set(key, { tile, tileX, tileY, span: TILE_SIZE * 2 ** shift })
+
+						return
+					}
+				}
+			})
+		)
+
+		return [...resolved.values()].toSorted((a, b) => b.span - a.span)
+	}
+
 	async renderFrame(viewport: Viewport, overlays?: { markers?: MarkerSpec[]; ring?: RingSpec }): Promise<MapFrame> {
 		const { centerLon, centerLat, columns, rows } = viewport
 
@@ -237,20 +293,14 @@ export class MapRenderer {
 			}
 		}
 
-		const tiles = await Promise.all(tileCoords.map((coord) => this.source.getTile(renderZoom, coord.x, coord.y)))
+		const resolvedTiles = await this.resolveTiles(tileCoords, renderZoom)
 
 		const grid = new RGBAGrid(subpixelW, subpixelH)
 		const pendingLabels: PendingLabel[] = []
 
 		for (const kind of ["fill", "line", "label"] as const) {
-			for (let i = 0; i < tileCoords.length; i++) {
-				const tile = tiles[i]
-
-				if (!tile) continue
-
-				const { x: tileX, y: tileY } = tileCoords[i]!
-
-				rasterizeTileForKind(grid, tile, tileX, tileY, kind, renderZoom, origin, pendingLabels)
+			for (const resolved of resolvedTiles) {
+				rasterizeTileForKind(grid, resolved, kind, renderZoom, origin, pendingLabels)
 			}
 		}
 

package/lib/style.ts

@@ -0,0 +1,115 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+/**
+ * Protomaps-basemap style table for the map-tui debug view.
+ *
+ * Defines fill, line, and label styles for each of the nine protomaps-basemap layers, restricted by zoom level. Color
+ * palette calibrated for dark-terminal rendering: dim fills (read as stipple density via dithering), bright lines and
+ * labels.
+ */
+
+export type RGB = readonly [red: number, green: number, blue: number]
+
+/**
+ * Fields shared by every style entry. `featureKinds` scopes an entry to features whose `kind` tile attribute is in the
+ * list; an entry without it is the layer's catch-all. Entries are consulted in table order and the first match wins, so
+ * kind-scoped entries precede the catch-all.
+ */
+interface StyleBase {
+	color: RGB
+	minZoom: number
+	featureKinds?: readonly string[]
+}
+
+export interface FillStyle extends StyleBase {
+	kind: "fill"
+}
+
+export interface LineStyle extends StyleBase {
+	kind: "line"
+	width: (zoom: number) => number
+}
+
+export interface LabelStyle extends StyleBase {
+	kind: "label"
+	property: string
+}
+
+export type LayerStyle = FillStyle | LineStyle | LabelStyle
+
+// Zoom level at which roads render with 2px width instead of 1px.
+const ROAD_WIDTH_THRESHOLD = 14
+
+const roadWidth = (zoom: number) => (zoom >= ROAD_WIDTH_THRESHOLD ? 2 : 1)
+
+// At braille scale every road is one dot wide and every fill is stipple, so CLASS has to ride on color instead of
+// geometry: arteries brighten toward amber, paths dim toward the vegetation green, and urban landuse runs warmer and
+// brighter than vegetation so a city reads as denser texture. Luminance is required — asciify's ordered dither
+// turns it into stipple density.
+const VEGETATION_KINDS = [
+	"allotments",
+	"cemetery",
+	"farmland",
+	"forest",
+	"garden",
+	"grass",
+	"meadow",
+	"nature_reserve",
+	"park",
+	"scrub",
+	"wetland",
+	"wood",
+] as const
+
+const STYLE_TABLE: Record<string, LayerStyle[]> = {
+	earth: [{ kind: "fill", color: [40, 44, 36], minZoom: 0 }],
+	landcover: [{ kind: "fill", color: [36, 52, 32], minZoom: 4 }],
+	landuse: [
+		{ kind: "fill", color: [66, 60, 52], minZoom: 10, featureKinds: ["residential"] },
+		{ kind: "fill", color: [72, 62, 50], minZoom: 10, featureKinds: ["commercial"] },
+		{ kind: "fill", color: [58, 60, 64], minZoom: 10, featureKinds: ["industrial"] },
+		{ kind: "fill", color: [36, 52, 32], minZoom: 10, featureKinds: VEGETATION_KINDS },
+		{ kind: "fill", color: [48, 48, 40], minZoom: 10 },
+	],
+	water: [{ kind: "fill", color: [24, 48, 90], minZoom: 0 }],
+	buildings: [{ kind: "fill", color: [70, 66, 60], minZoom: 13 }],
+	boundaries: [{ kind: "line", color: [140, 110, 160], minZoom: 0, width: () => 1 }],
+	roads: [
+		{ kind: "line", color: [255, 190, 90], minZoom: 6, featureKinds: ["highway"], width: roadWidth },
+		{ kind: "line", color: [215, 210, 180], minZoom: 6, featureKinds: ["major_road"], width: roadWidth },
+		{ kind: "line", color: [185, 182, 158], minZoom: 6, featureKinds: ["medium_road"], width: roadWidth },
+		{ kind: "line", color: [150, 150, 132], minZoom: 6, featureKinds: ["minor_road"], width: roadWidth },
+		{ kind: "line", color: [105, 115, 98], minZoom: 6, featureKinds: ["path"], width: roadWidth },
+		{ kind: "line", color: [115, 125, 140], minZoom: 6, featureKinds: ["rail"], width: () => 1 },
+		{ kind: "line", color: [170, 170, 150], minZoom: 6, width: roadWidth },
+	],
+	places: [{ kind: "label", color: [235, 235, 220], minZoom: 2, property: "name" }],
+	pois: [{ kind: "label", color: [180, 200, 160], minZoom: 14, property: "name" }],
+}
+
+/**
+ * Styles applying to a protomaps-basemap layer at a zoom, draw-ordered (fills < lines < labels). Empty for unstyled or
+ * zoom-restricted layers.
+ */
+export function stylesFor(layerName: string, zoom: number): LayerStyle[] {
+	return (STYLE_TABLE[layerName] ?? []).filter((style) => zoom >= style.minZoom)
+}
+
+/**
+ * The one style painting a feature: the first entry whose `featureKinds` contains the feature's `kind` attribute, or
+ * the first catch-all. A feature is painted at most once per draw pass — kind-scoped entries recolor, they never
+ * double-paint.
+ */
+export function styleForFeatureKind(styles: readonly LayerStyle[], featureKind: unknown): LayerStyle | null {
+	for (const style of styles) {
+		if (style.featureKinds == null) return style
+
+		if (typeof featureKind === "string" && style.featureKinds.includes(featureKind)) return style
+	}
+
+	return null
+}