@mailwoman/map-tui 9.1.1 → 9.2.0

package/renderer.ts

@@ -19,8 +19,8 @@ import { type MapFrame, overlayText, rasterizeToFrame, rgbToPacked } from "./fra
 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 { type LayerStyle, type RGB, styleForFeatureKind, stylesFor } from "./style.ts"
+import type { DecodedTile, TileProvider } from "./tile-source.ts"
 
 export interface Viewport {
 	centerLon: number
@@ -84,22 +84,39 @@ 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
 }
 
+/**
+ * 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 clamp(value: number, min: number, max: number): number {
 	return Math.min(Math.max(value, min), max)
 }
 
 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 +195,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 +229,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 +295,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/style.ts

@@ -14,23 +14,28 @@
 
 export type RGB = readonly [red: number, green: number, blue: number]
 
-export interface FillStyle {
-	kind: "fill"
+/**
+ * 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 {
+export interface LineStyle extends StyleBase {
 	kind: "line"
-	color: RGB
-	minZoom: number
 	width: (zoom: number) => number
 }
 
-export interface LabelStyle {
+export interface LabelStyle extends StyleBase {
 	kind: "label"
-	color: RGB
-	minZoom: number
 	property: string
 }
 
@@ -39,15 +44,48 @@ 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 load-bearing — 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: [48, 48, 40], minZoom: 10 }],
+	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: [170, 170, 150], minZoom: 6, width: (zoom) => (zoom >= ROAD_WIDTH_THRESHOLD ? 2 : 1) },
+		{ 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" }],
@@ -60,3 +98,18 @@ const STYLE_TABLE: Record<string, LayerStyle[]> = {
 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
+}

package/tile-source.ts

@@ -22,6 +22,17 @@ export interface DecodedTile {
 	layers: DecodedLayer[]
 }
 
+/**
+ * What a renderer needs from a tile archive — the read surface of {@link TileSource}, separated so a renderer can be
+ * driven by any provider: a single archive, a stub in tests, or a composite over several archives.
+ */
+export interface TileProvider {
+	readonly minZoom: number
+	readonly maxZoom: number
+	readonly attribution: string
+	getTile(z: number, x: number, y: number): Promise<DecodedTile | null>
+}
+
 class FilePMTilesSource implements Source {
 	private readonly path: string
 	private readonly handle: FileHandle
@@ -45,6 +56,38 @@ class FilePMTilesSource implements Source {
 
 const TILE_CACHE_LIMIT = 64
 
+/**
+ * The named entities attribution strings actually carry — archive metadata is HTML (`<a>&copy; OpenStreetMap</a>`), and
+ * a terminal shows entities raw unless they decode here.
+ */
+const HTML_ENTITIES: Record<string, string> = {
+	"&amp;": "&",
+	"&copy;": "©",
+	"&gt;": ">",
+	"&lt;": "<",
+	"&quot;": '"',
+	"&#39;": "'",
+}
+
+/**
+ * Plain-text attribution out of archive metadata (HTML tags stripped, entities decoded); empty string when absent.
+ */
+export function readAttribution(metadata: unknown): string {
+	if (
+		typeof metadata !== "object" ||
+		metadata === null ||
+		!("attribution" in metadata) ||
+		typeof (metadata as { attribution: unknown }).attribution !== "string"
+	) {
+		return ""
+	}
+
+	return (metadata as { attribution: string }).attribution
+		.replaceAll(/<[^>]+>/gu, "")
+		.replaceAll(/&[a-z]+;|&#\d+;/gu, (entity) => HTML_ENTITIES[entity] ?? entity)
+		.trim()
+}
+
 /**
  * A single LRU cache slot. Wrapping the decoded tile in an object lets `getTile` tell "cached and known absent" (`{
  * tile: null }`) apart from "not yet cached" (no entry in the Map) using plain presence, with no comparison against
@@ -54,7 +97,7 @@ interface CacheEntry {
 	tile: DecodedTile | null
 }
 
-export class TileSource {
+export class TileSource implements TileProvider {
 	readonly minZoom: number
 	readonly maxZoom: number
 
@@ -63,11 +106,20 @@ export class TileSource {
 	 */
 	readonly attribution: string
 
-	private readonly handle: FileHandle
+	/**
+	 * Null for HTTP sources — fetch connections have no handle to hold or close.
+	 */
+	private readonly handle: FileHandle | null
 	private readonly pmtiles: PMTiles
 	private readonly cache = new Map<string, CacheEntry>()
 
-	private constructor(handle: FileHandle, pmtiles: PMTiles, minZoom: number, maxZoom: number, attribution: string) {
+	private constructor(
+		handle: FileHandle | null,
+		pmtiles: PMTiles,
+		minZoom: number,
+		maxZoom: number,
+		attribution: string
+	) {
 		this.handle = handle
 		this.pmtiles = pmtiles
 		this.minZoom = minZoom
@@ -75,21 +127,24 @@ export class TileSource {
 		this.attribution = attribution
 	}
 
-	static async open(path: string): Promise<TileSource> {
-		const handle = await open(path, "r")
-		const pmtiles = new PMTiles(new FilePMTilesSource(path, handle))
+	/**
+	 * Opens a local `.pmtiles` path, or an `http(s)://` URL read via range requests — a hosted archive needs no tile
+	 * server, only a host honoring `Range` (any static file server or object store does).
+	 */
+	static async open(pathOrURL: string): Promise<TileSource> {
+		if (/^https?:\/\//u.test(pathOrURL)) {
+			const pmtiles = new PMTiles(pathOrURL)
+			const [header, metadata] = await Promise.all([pmtiles.getHeader(), pmtiles.getMetadata()])
 
-		const [header, metadata] = await Promise.all([pmtiles.getHeader(), pmtiles.getMetadata()])
+			return new TileSource(null, pmtiles, header.minZoom, header.maxZoom, readAttribution(metadata))
+		}
+
+		const handle = await open(pathOrURL, "r")
+		const pmtiles = new PMTiles(new FilePMTilesSource(pathOrURL, handle))
 
-		const attribution =
-			typeof metadata === "object" &&
-			metadata !== null &&
-			"attribution" in metadata &&
-			typeof (metadata as { attribution: unknown }).attribution === "string"
-				? (metadata as { attribution: string }).attribution.replaceAll(/<[^>]+>/gu, "").trim()
-				: ""
+		const [header, metadata] = await Promise.all([pmtiles.getHeader(), pmtiles.getMetadata()])
 
-		return new TileSource(handle, pmtiles, header.minZoom, header.maxZoom, attribution)
+		return new TileSource(handle, pmtiles, header.minZoom, header.maxZoom, readAttribution(metadata))
 	}
 
 	/**
@@ -125,6 +180,6 @@ export class TileSource {
 	}
 
 	async close(): Promise<void> {
-		await this.handle.close()
+		await this.handle?.close()
 	}
 }