@mailwoman/cartographer 10.0.0 → 10.1.0

package/lib/base/buildings.ts

@@ -11,7 +11,7 @@ import type {
 } from "@maplibre/maplibre-gl-style-spec"
 
 import { MailwomanBaseTileSetID } from "#base/theme"
-import { PROTOMAPS_FONT_REGULAR } from "#styles/fonts"
+import { MAP_FONT_REGULAR } from "#styles/fonts"
 import { LayerID } from "#styles/layers"
 
 const BuildingLayerID = LayerID.bind(null, "buildings")
@@ -80,8 +80,7 @@ export const BuildingLayers: LayerSpecification[] = [
 			"fill-extrusion-vertical-gradient": false,
 			"fill-extrusion-translate-anchor": "map",
 			"fill-extrusion-opacity": 1,
-			// top of the band = full building height
-			// "fill-extrusion-height": popHeight(buildingHeight()),
+			// top of the band = full building height "fill-extrusion-height": popHeight(buildingHeight()),
 			// // base of the band = full height minus the cap thickness (clamped ≥ 0)
 			// "fill-extrusion-base": popHeight([ "max", [ "-", buildingHeight(), ROOF_CAP ], 0 ]),
 			"fill-extrusion-height": popHeight(["+", buildingHeight(), ROOF_GAP, ROOF_CAP]),
@@ -115,7 +114,7 @@ export const BuildingLayers: LayerSpecification[] = [
 			"text-field": ["to-string", ["id"]],
 			"text-offset": [0, 0],
 			"text-anchor": "center",
-			"text-font": [PROTOMAPS_FONT_REGULAR],
+			"text-font": [MAP_FONT_REGULAR],
 		},
 
 		paint: {

package/lib/base/composition.ts

@@ -16,9 +16,9 @@ import {
 } from "#styles/layers"
 import type { TileSetSourceRecord } from "#styles/sources"
 
-//#endregion
+// #endregion
 
-//#region Spec Creators
+// #region Spec Creators
 
 export function createLightSpec(spec?: Partial<LightSpecification>): LightSpecification {
 	return {
@@ -46,19 +46,23 @@ export function createSkySpec(spec?: Partial<SkySpecification>): SkySpecificatio
 	}
 }
 
-//#endregion
+// #endregion
 
-//#region Style Composition
+// #region Style Composition
 
 /**
- * The glyph host every style composed here reads fonts from. The Protomaps font set, mirrored under the public bucket
- * so a style never depends on an upstream host at render time.
+ * The glyph host every style composed here reads fonts from.
+ *
+ * The Protomaps font set, mirrored under the public bucket so a style never
+ * depends on an upstream host at render time.
  */
 export const PROTOMAPS_GLYPHS_URL = "https://public.mailwoman.ai/protomaps/fonts/{fontstack}/{range}.pbf"
 
 /**
- * The Earth sprite. It must match the basemap schema version: the v4 sprite carries the icons the v4 theme's layers
- * reference by name, so a style over a different basemap version needs a different sprite.
+ * The Earth sprite.
+ *
+ * It must match the basemap schema version: the v4 sprite includes the icons the v4 theme's
+ * layers reference by name, so a style over a different basemap version needs a different sprite.
  */
 export const PROTOMAPS_SPRITE_URL = "https://public.mailwoman.ai/protomaps/sprites/v4/light"
 
@@ -69,16 +73,22 @@ export interface StyleSpecificationComposition {
 	sky?: Partial<SkySpecification>
 	terrain?: Partial<TerrainSpecification>
 	/**
-	 * The layer list every `layers` entry inserts into. Earth's basemap layers by default; a body with no roads, water or
-	 * buildings brings its own.
+	 * The layer list every `layers` entry inserts into.
+	 *
+	 * Earth's basemap layers by default.
+	 * A body with no roads, water or buildings brings its own.
 	 */
 	baseLayers?: LayerSpecification[]
 	/**
-	 * The `hillshade` source. Earth's terrarium DEM by default; `null` adds no such source.
+	 * The `hillshade` source.
+	 *
+	 * Earth's terrarium DEM by default; `null` adds no such source.
 	 */
 	hillshadeSource?: SourceSpecification | null
 	/**
-	 * The sprite URL. Earth's Protomaps v4 sprite by default; `null` omits the key, for a style with no icons.
+	 * The sprite URL.
+	 *
+	 * Earth's Protomaps v4 sprite by default; `null` omits the key, for a style with no icons.
 	 */
 	sprite?: string | null
 	glyphs?: string
@@ -146,4 +156,4 @@ export class StyleSpecificationComposer {
 	}
 }
 
-//#endregion
+// #endregion

package/lib/base/layers.ts

@@ -18,9 +18,15 @@ import { LayerID } from "#styles/layers"
 export const HillsLayerID = LayerID(HillshadeTileSetID, "hills")
 
 /**
- * Splits `layers()` into non-label + label groups so building footprints, water outlines, and hillshade sit between
- * base geometry and labels. `@protomaps/basemaps@5.x` doesn't expose a `noLabels` helper — `labelsOnly: true` gives
- * only the label layers; subtracting that set from the full list yields the non-label group.
+ * Splits `layers()` into non-label and label groups.
+ *
+ * The interval between base geometry and labels holds the footprints.
+ * It also holds water outlines and hillshade.
+ *
+ * `@protomaps/basemaps@5.x` doesn't expose a `noLabels` helper.
+ * `labelsOnly: true` gives only the label layers.
+ *
+ * The full list minus that set yields the non-label group.
  */
 const allBaseLayers = layers(MailwomanBaseTileSetID, MailwomanBaseFlavor, { lang: "en" })
 const labelLayers = layers(MailwomanBaseTileSetID, MailwomanBaseFlavor, { lang: "en", labelsOnly: true })

package/lib/base/theme.ts

@@ -6,25 +6,34 @@
 
 import { type Flavor, namedFlavor } from "@protomaps/basemaps"
 
+import { MAP_FONT_ITALIC, MAP_FONT_MEDIUM, MAP_FONT_REGULAR } from "#styles/fonts"
 import { TileSetSourceID } from "#styles/sources"
 
 /**
- * Identifier for the Mailwoman base tileset. Matches the R2 object basename (`nexus-assets/tiles/basemap-v4.pmtiles`) —
- * `tiles.mailwoman.ai/basemap-v4.json` returns its tilejson, `tiles.mailwoman.ai/basemap-v4/{z}/{x}/{y}.mvt` returns
- * vector tiles.
+ * Identifier for the Mailwoman base tileset.
+ *
+ * Matches the R2 object basename (`nexus-assets/tiles/basemap-v4.pmtiles`).
+ * `tiles.mailwoman.ai/basemap-v4.json` returns its tilejson,
+ * `tiles.mailwoman.ai/basemap-v4/{z}/{x}/{y}.mvt` returns vector tiles.
  */
 export const MailwomanBaseTileSetID = TileSetSourceID("basemap-v4")
 
 const darkFlavor = namedFlavor("dark")
 
 /**
- * The Mailwoman theme for Protomaps via MapLibre. Keys follow `@protomaps/basemaps@5.x` which targets the v4 tile
- * schema (`["==","kind","..."]` filters), matching the basemap-v4 PMTiles on R2.
+ * The Mailwoman theme for Protomaps via MapLibre.
+ *
+ * Keys follow `@protomaps/basemaps@5.x` which targets the v4 tile schema
+ * (`["==","kind","..."]` filters), matching the basemap-v4 PMTiles on R2.
  */
 export const MailwomanBaseFlavor: Flavor = {
 	...darkFlavor,
 
-	//#region Base
+	regular: MAP_FONT_REGULAR,
+	bold: MAP_FONT_MEDIUM,
+	italic: MAP_FONT_ITALIC,
+
+	// #region Base
 	background: "hsl(0deg 10% 5%)",
 	earth: "hsl(0deg 10% 5%)",
 
@@ -51,8 +60,8 @@ export const MailwomanBaseFlavor: Flavor = {
 	zoo: "#222323",
 	military: "#242323",
 
-	//#endregion
-	//#region Tunnel
+	// #endregion
+	// #region Tunnel
 	tunnel_other_casing: "#141414",
 	tunnel_minor_casing: "#141414",
 	tunnel_link_casing: "#141414",
@@ -64,10 +73,10 @@ export const MailwomanBaseFlavor: Flavor = {
 	tunnel_major: "#292929",
 	tunnel_highway: "#292929",
 
-	//#endregion
+	// #endregion
 	buildings: "#111111",
 
-	//#region Casing
+	// #region Casing
 	minor_service_casing: "#1f1f1f",
 	minor_casing: "#1f1f1f",
 	link_casing: "#1f1f1f",
@@ -83,11 +92,11 @@ export const MailwomanBaseFlavor: Flavor = {
 	highway_casing_early: "#1f1f1f",
 	highway: "hsl(36deg 10% 50%)",
 
-	//#endregion
+	// #endregion
 	railway: "#000000",
 	boundaries: "hsl(240deg 100% 90%)",
 
-	//#region Bridges
+	// #region Bridges
 	bridges_other_casing: "#2b2b2b",
 	bridges_minor_casing: "#1f1f1f",
 	bridges_link_casing: "#1f1f1f",
@@ -99,7 +108,7 @@ export const MailwomanBaseFlavor: Flavor = {
 	bridges_major: "#3d3d3d",
 	bridges_highway: "#474747",
 
-	//#endregion
+	// #endregion
 
 	ocean_label: "#717784",
 	subplace_label: "hsl(50deg 50% 70%)",

package/lib/{bdc/index.ts → bdc.ts}

@@ -47,13 +47,14 @@ export type BaseBDCLayerSpecification<T> = T extends BDCLayerSpecificationInput
 	: never
 
 /**
- * The three builders below take a spec WITHOUT the source fields and return one with them filled in.
+ * The three builders below take a spec without the source fields and return one with them filled in.
  *
- * They are not generic, and the assertion each ends with is single rather than through `unknown`, both for the same
- * reason: TypeScript cannot verify that `Omit<T, K>` plus the omitted keys reconstitutes `T`, so a builder declared
- * `<T>(…): T` can only reach its return type by defeating the checker entirely — which then covers the `id`, `minzoom`
- * and `maxzoom` values too. Nothing wanted the narrowing: the sole consumer, {@linkcode BroadbandDataCollectionLayers},
- * annotates the union.
+ * These are specific assertions.
+ * Each avoids `unknown`.
+ *
+ * TypeScript cannot verify that because TypeScript cannot verify that `Omit<T, K>` plus
+ * the omitted keys reconstitutes `T` — a `<T>(…): T` builder could only reach its return
+ * type by defeating the checker, covering the `id`, `minzoom` and `maxzoom` values too.
  */
 type BDCLayerBuilderInput = BaseBDCLayerSpecification<BDCLayerSpecificationInput>
 
@@ -101,9 +102,6 @@ const GIGABIT_BROADBAND_SPEED = 1000
 export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 	{
 		afterID: "earth",
-		// metadata: {
-		// 	queryable: false,
-		// },
 		id: "blocks-underserved",
 		layout: {
 			visibility: "none",
@@ -112,43 +110,19 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		source: BDCTileSetID,
 		type: "fill",
 		filter: [
-			// ---
 			"all",
 			["in", 50, ["get", "technology_codes"]], // Fiber only
 			[">", ["get", "land_area_sqm"], 0],
-			// ["==", ["get", "UR"], "R"],
 		],
 		paint: {
-			// "fill-extrusion-height": [
-			// 	// Our extrusion height represents the magnitude of broadband underservice,
-			// 	// e.g. How many people are underserved per square meter of land area.
-			// 	"let",
-			// 	"population_density",
-			// 	["/", ["to-number", ["get", "population"]], ["to-number", ["get", "land_area_sqm"]]],
-			// 	["*", ["var", "population_density"], 10000],
-			// ],
 			"fill-color": "hsl(60deg, 100%, 50%)",
 			"fill-opacity": [
-				// Underserved areas are emphasized to their level importance,
-				// relative to the impact of the underservice.
 				"let",
 				"internet_speed_impact",
 				["/", ["to-number", ["get", "average_download_speed"]], GIGABIT_BROADBAND_SPEED],
-				[
-					// ---
-					"interpolate",
-					["linear"],
-					["var", "internet_speed_impact"],
-					0,
-					0.1,
-					1,
-					0.5,
-				],
+				["interpolate", ["linear"], ["var", "internet_speed_impact"], 0, 0.1, 1, 0.5],
 			],
 		},
-		// layout: {
-		// 	visibility: "none",
-		// },
 	},
 
 	{
@@ -163,7 +137,6 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		"source-layer": `bdc_${TIGERLevel.Block}`,
 		source: BDCTileSetID,
 		type: "line",
-		// filter: [">=", ["get", "ALAND"], 0],
 		minzoom: 9,
 		paint: {
 			"line-color": "#000",
@@ -180,13 +153,7 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		"source-layer": `bdc_${TIGERLevel.Block}`,
 		source: BDCTileSetID,
 		type: "symbol",
-		filter: [
-			// ---
-			"all",
-			// ["in", 50, ["get", "technology_codes"]], // Fiber only
-			[">", ["get", "land_area_sqm"], 0],
-			// ["==", ["get", "UR"], "R"],
-		],
+		filter: ["all", [">", ["get", "land_area_sqm"], 0]],
 		paint: {
 			"text-color": "black",
 			"text-halo-color": "white",
@@ -208,13 +175,7 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 	...createBDCLayer({
 		id: "coverage-fiber-label",
 		beforeID: "places_subplace",
-		filter: [
-			// ---
-
-			"all",
-			["==", ["get", "provider_id"], 131_425],
-			// ["in", 50, ["get", "technology_codes"]],
-		],
+		filter: ["all", ["==", ["get", "provider_id"], 131_425]],
 		type: "symbol",
 		layout: {
 			visibility: "none",
@@ -224,13 +185,8 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 				" Mbps",
 			],
 			"text-size": [
-				// ---
 				"let",
 				"multiplier",
-				// We scale the text size based on the average download speed.
-				// By default, we're no smaller than 14, Any speed above the gigabit threshold
-				// acts as a multiplier for the text size.
-				// ---
 				["/", ["get", "average_download_speed"], GIGABIT_BROADBAND_SPEED / 4],
 				["+", 14, ["var", "multiplier"]],
 			],
@@ -246,7 +202,6 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		paint: {
 			"text-halo-width": 2,
 			"text-halo-color": [
-				// ---
 				"interpolate",
 				["exponential", 0.5],
 				["get", "average_download_speed"],
@@ -258,7 +213,6 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 			],
 
 			"text-color": [
-				// ---
 				"interpolate",
 				["exponential", 0.25],
 				["get", "average_download_speed"],
@@ -287,22 +241,7 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		paint: {
 			"line-color": "#ff009c",
 
-			"line-width": [
-				"interpolate",
-				["exponential", 1.6],
-				["zoom"],
-				// ---
-				3,
-				0,
-				6,
-				1.1,
-				12,
-				1.6,
-				15,
-				5,
-				18,
-				15,
-			],
+			"line-width": ["interpolate", ["exponential", 1.6], ["zoom"], 3, 0, 6, 1.1, 12, 1.6, 15, 5, 18, 15],
 		},
 		layout: {
 			"line-cap": "round",
@@ -312,12 +251,7 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 	...createBDCLayer({
 		afterID: "earth",
 		id: "coverage-fiber-heat",
-		filter: [
-			// ---
-
-			"all",
-			["==", ["get", "provider_id"], 131_425],
-		],
+		filter: ["all", ["==", ["get", "provider_id"], 131_425]],
 		minzoom: 10,
 		type: "heatmap",
 		layout: {
@@ -325,7 +259,6 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		},
 		paint: {
 			"heatmap-color": [
-				// ---
 				"interpolate",
 				["linear"],
 				["heatmap-density"],
@@ -334,22 +267,8 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 				}).flat(),
 			],
 
-			"heatmap-radius": [
-				// ---
-				"interpolate",
-				["linear"],
-				["zoom"],
-				10,
-				5,
-				15,
-				20,
-			],
-			"heatmap-weight": [
-				// ---
-				"*",
-				["get", "land_area_sqm"],
-				0.00001,
-			],
+			"heatmap-radius": ["interpolate", ["linear"], ["zoom"], 10, 5, 15, 20],
+			"heatmap-weight": ["*", ["get", "land_area_sqm"], 0.00001],
 		},
 	}),
 
@@ -381,30 +300,17 @@ export const BroadbandDataCollectionLayers: BDCLayerSpecificationInput[] = [
 		source: "composite",
 		"source-layer": "DataCentersCombined20220921",
 		layout: {
-			// visibility: "none",
 			"text-field": ["get", "Category"],
 			"text-size": 12,
 			"text-anchor": "top",
 			"text-offset": [0, 0.5],
-			// "text-allow-overlap": true,
 			"text-font": ["Fira Code Regular"],
 		},
 		paint: {
 			"text-color": "#fff",
 			"text-halo-color": "#fb8429",
 			"text-halo-width": 1,
-			"text-opacity": [
-				// We fade out the outline at higher zoom levels
-				"interpolate",
-				["linear"],
-				["zoom"],
-				1,
-				0.01,
-				6,
-				0.5,
-				16,
-				1,
-			],
+			"text-opacity": ["interpolate", ["linear"], ["zoom"], 1, 0.01, 6, 0.5, 16, 1],
 		},
 	},
 ]

package/lib/coverage.ts

@@ -0,0 +1,73 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Address-coverage overlays rendered from the `mailwoman coverage build` H3 tile set. Each cell
+ *   supplies optimistic (`fog_opt`) and observed-coverage (`fog`) values. The demo exposes both as
+ *   default-off layers. Tiles are served from `coverage-v5.pmtiles`.
+ */
+
+import type { FillLayerSpecification, VectorSourceSpecification } from "@maplibre/maplibre-gl-style-spec"
+
+import { TileSetSourceID } from "#styles/sources"
+
+/**
+ * MapLibre source ID for the v5 coverage tiles.
+ * Keep it aligned with the archive and layer specs.
+ */
+export const CoverageTileSetID = TileSetSourceID("coverage-v5")
+
+/**
+ * Source-layer name stored in the coverage archive.
+ */
+export const COVERAGE_SOURCE_LAYER = "coverage"
+
+/**
+ * Near-black indigo used to mark unknown or unsurveyed areas.
+ */
+export const COVERAGE_FOG_COLOR = "#663399" // Rebecca Purple
+
+/**
+ * Maximum opacity for an uncovered cell.
+ */
+export const COVERAGE_MAX_FOG_OPACITY = 0.9
+
+/**
+ * IDs for the optimistic and observed-coverage layers.
+ */
+export const CoverageLayerID = {
+	optimistic: "coverage-opt-fog",
+	honest: "coverage-honest-fog",
+} as const
+
+/**
+ * Create a vector source from its TileJSON URL.
+ */
+export function createCoverageSource(url: string): VectorSourceSpecification {
+	return { type: "vector", url }
+}
+
+function fogFill(id: string, fogProperty: "fog" | "fog_opt"): FillLayerSpecification {
+	return {
+		id,
+		type: "fill",
+		source: CoverageTileSetID,
+		"source-layer": COVERAGE_SOURCE_LAYER,
+		// Keep coverage overlays hidden until selected.
+		layout: { visibility: "none" },
+		paint: {
+			"fill-color": COVERAGE_FOG_COLOR,
+			// Rows without coverage values render as clear.
+			"fill-opacity": ["*", ["coalesce", ["to-number", ["get", fogProperty]], 0], COVERAGE_MAX_FOG_OPACITY],
+		},
+	}
+}
+
+/**
+ * The two hidden fog layers, added beneath place labels by the demo.
+ */
+export const CoverageLayers: FillLayerSpecification[] = [
+	fogFill(CoverageLayerID.optimistic, "fog_opt"),
+	fogFill(CoverageLayerID.honest, "fog"),
+]

package/lib/index.ts

@@ -4,9 +4,9 @@
  * @author Teffen Ellis, et al.
  */
 
-export * from "#base/index"
-export * from "#bdc/index"
-export * from "#hspa/index"
-export * from "#styles/index"
-export * from "#tiger/index"
-export * from "#tiles/index"
+export * from "#base"
+export * from "#bdc"
+export * from "#hspa"
+export * from "#styles"
+export * from "#tiger"
+export * from "#tiles"

package/lib/planetary/layers.ts

@@ -12,24 +12,23 @@ import type {
 } from "@maplibre/maplibre-gl-style-spec"
 
 import { PlanetaryHillshadeSourceID, PlanetaryNomenclatureSourceID } from "#planetary/sources"
-import { PROTOMAPS_FONT_REGULAR } from "#styles/fonts"
+import { MAP_FONT_REGULAR } from "#styles/fonts"
 import { LayerID } from "#styles/layers"
 
 export interface PlanetaryPalette {
 	/**
-	 * The body's own surface tone, under the relief. Named `space` for the layer it feeds, which paints the SPHERE under
-	 * globe projection rather than the area around it — the field around the globe is the page behind a transparent
-	 * canvas, and the app's stylesheet paints it.
+	 * The body's own surface tone, under the relief, painted on the sphere
+	 * rather than the page behind the canvas.
 	 */
 	space: string
 	/**
-	 * Where a slope faces the light. With `shadow` and `accent` these are what make one body's relief differ from
-	 * another's; the tiles carry encoded elevation and no colour of their own.
+	 * Where a slope faces the light.
+	 *
+	 * The tiles store encoded elevation and have no color of their own.
 	 */
 	reliefHighlight: string
 	/**
-	 * Where a slope faces away. Kept translucent so the surface tone reads through flat ground, which would otherwise
-	 * take the shadow colour everywhere the terrain is level.
+	 * Where a slope faces away, kept translucent so the surface tone reads through flat ground.
 	 */
 	reliefShadow: string
 	/**
@@ -42,8 +41,8 @@ export interface PlanetaryPalette {
 }
 
 /**
- * One palette per body with a published style. The record's keys are the bodies a style can be composed for, so a body
- * without a row here has no style rather than a wrong one.
+ * One palette per body with a published style, so a body without a row here
+ * has no style rather than a wrong one.
  */
 export const PALETTES = {
 	moon: {
@@ -71,9 +70,7 @@ export type PlanetaryStyleBody = keyof typeof PALETTES
 const PLANETARY_NAMESPACE = "planetary"
 
 /**
- * The body's surface tone, under the relief. Under globe projection a background layer paints the SPHERE, not the
- * viewport, so this is the ground the hillshade shades and not the field around the globe; the app's stylesheet paints
- * that behind a transparent canvas.
+ * The body's surface tone, under the relief, painted on the sphere rather than the viewport.
  */
 export const PlanetarySpaceLayerID = LayerID(PLANETARY_NAMESPACE, "space")
 
@@ -93,8 +90,8 @@ export const PlanetaryLabelsLayerID = LayerID(PLANETARY_NAMESPACE, "nomenclature
 export const PlanetarySelectionLayerID = LayerID(PLANETARY_NAMESPACE, "selection")
 
 /**
- * The IAU feature-type codes drawn as spaced capitals: a mare, planitia, oceanus or terra spans a region rather than
- * marking a point, and the wide setting reads as an area name the way a printed atlas sets one.
+ * The IAU feature-type codes for features that span a region rather than marking
+ * a point, drawn as spaced capitals.
  */
 const REGION_FEATURE_TYPE_CODES = ["ME", "PL", "OC", "TA"]
 
@@ -107,9 +104,8 @@ export function spaceLayer(palette: PlanetaryPalette): BackgroundLayerSpecificat
 }
 
 /**
- * The relief, shaded at draw time from the body's encoded elevation. The tiles carry height and no colour, so every
- * body-specific decision is here: a greyscale image could not be tinted at all, because MapLibre's raster paint
- * properties are brightness, contrast, saturation and hue-rotate, and the last two do nothing without chroma.
+ * The relief, shaded at draw time from the body's encoded elevation,
+ * since the tiles store height and have no color.
  */
 export function hillshadeLayer(palette: PlanetaryPalette): HillshadeLayerSpecification {
 	return {
@@ -117,8 +113,8 @@ export function hillshadeLayer(palette: PlanetaryPalette): HillshadeLayerSpecifi
 		type: "hillshade",
 		source: PlanetaryHillshadeSourceID,
 		paint: {
-			// Under 1: these bodies carry relief far sharper than Earth's relative to their radius, and unexaggerated
-			// shading reads as noise at globe zooms.
+			// Under 1: these bodies have relief sharper than Earth's relative to their radius.
+			// Unexaggerated shading reads as noise at globe zoom levels.
 			"hillshade-exaggeration": 0.6,
 			"hillshade-highlight-color": palette.reliefHighlight,
 			"hillshade-shadow-color": palette.reliefShadow,
@@ -128,9 +124,9 @@ export function hillshadeLayer(palette: PlanetaryPalette): HillshadeLayerSpecifi
 }
 
 /**
- * Labels by feature scale: the tile's per-feature `minzoom` already hides a small crater at a low zoom, so the symbol
- * layer only sizes and prioritizes. `featureTypeCode` is the IAU feature-type code carried in the tile properties (AA
- * crater, MO mons, VA vallis, ME mare, PL planitia, SF satellite feature); `diameterKm` is the feature's diameter.
+ * Labels by feature scale: the tile's per-feature `minzoom` already hides a
+ * small crater at a low zoom, so the symbol layer only sizes and prioritizes,
+ * reading `featureTypeCode` (the IAU feature-type code) and `diameterKm`.
  */
 export function labelLayer(palette: PlanetaryPalette): SymbolLayerSpecification {
 	return {
@@ -140,7 +136,7 @@ export function labelLayer(palette: PlanetaryPalette): SymbolLayerSpecification
 		"source-layer": "nomenclature",
 		layout: {
 			"text-field": ["get", "name"],
-			"text-font": [PROTOMAPS_FONT_REGULAR],
+			"text-font": [MAP_FONT_REGULAR],
 			"text-size": ["interpolate", ["linear"], ["coalesce", ["get", "diameterKm"], 0], 0, 11, 100, 14, 1000, 18],
 			"text-transform": ["match", ["get", "featureTypeCode"], REGION_FEATURE_TYPE_CODES, "uppercase", "none"],
 			"text-letter-spacing": ["match", ["get", "featureTypeCode"], REGION_FEATURE_TYPE_CODES, 0.15, 0.02],
@@ -152,8 +148,8 @@ export function labelLayer(palette: PlanetaryPalette): SymbolLayerSpecification
 }
 
 /**
- * The selection ring. Its filter matches no feature until the app sets one by `id`, so the layer ships in the style and
- * the app never inserts a layer at runtime.
+ * The selection ring, shipped in the style with a filter that matches no feature
+ * until the app sets one by `id`.
  */
 export function selectionLayer(palette: PlanetaryPalette): CircleLayerSpecification {
 	return {