@mailwoman/tiger 5.8.0 → 5.10.0

package/tabulation-block.ts

@@ -6,32 +6,32 @@
 
 import { type MultiPolygonLiteral } from "@mailwoman/spatial"
 
-import { TIGERProperty, type TIGERPropertyRecord } from "./constants.js"
-import { GeoIDPart, type FIPSBlockGeoID, type ParsedGeoIDBlockLevel } from "./geoid.js"
+import { TIGERProperty, type TIGERPropertyRecord } from "./constants.ts"
+import { GeoIDPart, type FIPSBlockGeoID, type ParsedGeoIDBlockLevel } from "./geoid.ts"
 
 /**
  * The properties of a tabulated block from the TIGER/Line dataset.
  */
 export type TIGERTabulatedBlockProperties = Pick<
 	TIGERPropertyRecord<FIPSBlockGeoID>,
-	| TIGERProperty.GeoID
-	| GeoIDPart.CountySubDivision
-	| GeoIDPart.Tract
-	| GeoIDPart.Place
-	| GeoIDPart.BlockGroup
-	| GeoIDPart.Block
-	| GeoIDPart.Place
-	| GeoIDPart.CongressionalDistrict
-	| TIGERProperty.ClassCode
-	| TIGERProperty.UrbanRuralCode
-	| TIGERProperty.UrbanizedAreaCode
-	| TIGERProperty.FunctionalStatus
-	| TIGERProperty.LandAreaSqm
-	| TIGERProperty.WaterAreaSqm
-	| TIGERProperty.CentroidLatitude
-	| TIGERProperty.CentroidLongitude
-	| TIGERProperty.HousingUnitCount
-	| TIGERProperty.Population
+	| typeof TIGERProperty.GeoID
+	| typeof GeoIDPart.CountySubDivision
+	| typeof GeoIDPart.Tract
+	| typeof GeoIDPart.Place
+	| typeof GeoIDPart.BlockGroup
+	| typeof GeoIDPart.Block
+	| typeof GeoIDPart.Place
+	| typeof GeoIDPart.CongressionalDistrict
+	| typeof TIGERProperty.ClassCode
+	| typeof TIGERProperty.UrbanRuralCode
+	| typeof TIGERProperty.UrbanizedAreaCode
+	| typeof TIGERProperty.FunctionalStatus
+	| typeof TIGERProperty.LandAreaSqm
+	| typeof TIGERProperty.WaterAreaSqm
+	| typeof TIGERProperty.CentroidLatitude
+	| typeof TIGERProperty.CentroidLongitude
+	| typeof TIGERProperty.HousingUnitCount
+	| typeof TIGERProperty.Population
 >
 
 export interface TIGERBlockFeature {

package/tools/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   TIGER operator tools — the `run()`-style modules behind `mailwoman tiger race-dots` /
+ *   `race-dots-map` (see the 2026-07-09 scripts→Pastel spec). No argv, no `process.exit`: commands
+ *   own parsing, rendering, and exit codes. Heavy deps (`@turf/boolean-contains`,
+ *   `@protomaps/basemaps`) are lazy-imported inside their entry fns. NOT `sdk/` — that submodule
+ *   means data acquisition.
+ */
+
+export * from "./race-dots.ts"
+export * from "./race-dots-map.ts"
+export * from "./serve-range.ts"

package/tools/race-dots-map.ts

@@ -8,51 +8,40 @@
  *   inlined here, à la `registry/map-html.ts`) under a circle layer of the dots, colored by race
  *   category. The dots PMTiles is read client-side via the `pmtiles` protocol.
  *
- *   Each dot is one of `--per` people of a category, placed at random inside its Census block — a
+ *   Each dot is one of `per` people of a category, placed at random inside its Census block — a
  *   representation, not a record about any address. Serve over localhost (the house tile server
- *   CORS-restricts to localhost + the docs domains).
+ *   CORS-restricts to localhost + the docs domains) — `mailwoman tiger race-dots-map --serve` wires
+ *   {@linkcode serveWithRangeSupport} for exactly this.
  *
- *   Run: node --experimental-strip-types scripts/census/race-dots-map.ts\
- *   --pmtiles-url http://localhost:8899/race-dots-oc.pmtiles --out /tmp/race-dots-oc.html
+ *   Run: `mailwoman tiger race-dots-map --pmtiles-url
+ *   http://localhost:8899/race-dots-oc.pmtiles --out /tmp/race-dots-oc.html`
  */
 
 import { writeFileSync } from "node:fs"
-import { parseArgs } from "node:util"
 
-import { layers, namedFlavor } from "@protomaps/basemaps"
-
-// Loose scan parity with the retired local argv helpers: unknown flags tolerated.
-const { values: rawValues } = parseArgs({
-	options: {
-		lat: { type: "string" },
-		lng: { type: "string" },
-		out: { type: "string" },
-		per: { type: "string" },
-		"pmtiles-url": { type: "string" },
-		title: { type: "string" },
-		zoom: { type: "string" },
-	},
-	strict: false,
-	allowPositionals: true,
-})
-// Typed view: strict:false loosens TS inference, but declared options always parse to their schema type.
-const values = rawValues as {
-	lat?: string
-	lng?: string
+/** Options for {@linkcode raceDotsMap}. */
+export interface RaceDotsMapOptions {
+	/** Dots tileset URL the page reads client-side. Default `http://localhost:8899/race-dots-oc.pmtiles`. */
+	pmtilesURL?: string
+	/** Output HTML path. Default `/tmp/race-dots-oc.html`. */
 	out?: string
-	per?: string
-	"pmtiles-url"?: string
+	/** People represented by one dot (title/legend copy only). Default 5. */
+	per?: number
+	/** Page title. Default derives from `per`. */
 	title?: string
-	zoom?: string
+	/** Initial map center longitude. Default -117.83 (Orange County, CA). */
+	lng?: number
+	/** Initial map center latitude. Default 33.68. */
+	lat?: number
+	/** Initial map zoom. Default 9.4. */
+	zoom?: number
+}
+
+/** Result of {@linkcode raceDotsMap}. */
+export interface RaceDotsMapResult {
+	outPath: string
+	pmtilesURL: string
 }
-const PMTILES_URL = values["pmtiles-url"] || "http://localhost:8899/race-dots-oc.pmtiles"
-const OUT = values["out"] || "/tmp/race-dots-oc.html"
-const PER = Number(values["per"] || "5")
-const PER_PHRASE = PER === 1 ? "one dot is one person" : `one dot ≈ ${PER} people`
-const TITLE = values["title"] || `Race in Orange County, CA — ${PER_PHRASE} (2020 Census)`
-const CENTER_LNG = Number(values["lng"] || "-117.83")
-const CENTER_LAT = Number(values["lat"] || "33.68")
-const ZOOM = Number(values["zoom"] || "9.4")
 
 const MAPLIBRE_VERSION = "5.24.0"
 const MAPLIBRE_JS_SRI = "sha384-5+cfbwT0iiub6VsQAdn6yz16nr6sDiQoHx6tm4O8OVYXHYOxcffFmCJBL0dgdvGp"
@@ -86,43 +75,60 @@ const CATEGORY_LABEL: Record<string, string> = {
 	multi: "Two or more races",
 }
 
-const colorMatch: unknown[] = ["match", ["get", "cat"]]
+/** Race-dots MapLibre page writer — see the module doc. */
+export async function raceDotsMap(
+	options: RaceDotsMapOptions = {},
+	report?: (line: string) => void
+): Promise<RaceDotsMapResult> {
+	const PMTILES_URL = options.pmtilesURL || "http://localhost:8899/race-dots-oc.pmtiles"
+	const OUT = options.out || "/tmp/race-dots-oc.html"
+	const PER = options.per ?? 5
+	const PER_PHRASE = PER === 1 ? "one dot is one person" : `one dot ≈ ${PER} people`
+	const TITLE = options.title || `Race in Orange County, CA — ${PER_PHRASE} (2020 Census)`
+	const CENTER_LNG = options.lng ?? -117.83
+	const CENTER_LAT = options.lat ?? 33.68
+	const ZOOM = options.zoom ?? 9.4
 
-for (const [cat, color] of Object.entries(CATEGORY_COLOR)) {
-	colorMatch.push(cat, color)
-}
-colorMatch.push("#9e9e9e")
+	// Heavy dep (devDependency — operator tooling), lazy-imported so loading the tools barrel stays cheap.
+	const { layers, namedFlavor } = await import("@protomaps/basemaps")
 
-const style = {
-	version: 8,
-	glyphs: GLYPHS_URL,
-	sprite: SPRITE_URL,
-	sources: {
-		[BASEMAP_SOURCE_ID]: { type: "vector", url: BASEMAP_TILEJSON_URL },
-		dots: { type: "vector", url: "pmtiles://" + PMTILES_URL },
-	},
-	layers: [
-		...(layers(BASEMAP_SOURCE_ID, namedFlavor("light"), { lang: "en" }) as unknown[]),
-		{
-			id: "race-dots",
-			type: "circle",
-			source: "dots",
-			"source-layer": "dots",
-			paint: {
-				"circle-radius": ["interpolate", ["linear"], ["zoom"], 4, 0.7, 9, 1.7, 12, 2.8, 16, 4.5],
-				"circle-color": colorMatch,
-				"circle-opacity": 0.85,
-			},
+	const colorMatch: unknown[] = ["match", ["get", "cat"]]
+
+	for (const [cat, color] of Object.entries(CATEGORY_COLOR)) {
+		colorMatch.push(cat, color)
+	}
+	colorMatch.push("#9e9e9e")
+
+	const style = {
+		version: 8,
+		glyphs: GLYPHS_URL,
+		sprite: SPRITE_URL,
+		sources: {
+			[BASEMAP_SOURCE_ID]: { type: "vector", url: BASEMAP_TILEJSON_URL },
+			dots: { type: "vector", url: "pmtiles://" + PMTILES_URL },
 		},
-	],
-}
+		layers: [
+			...(layers(BASEMAP_SOURCE_ID, namedFlavor("light"), { lang: "en" }) as unknown[]),
+			{
+				id: "race-dots",
+				type: "circle",
+				source: "dots",
+				"source-layer": "dots",
+				paint: {
+					"circle-radius": ["interpolate", ["linear"], ["zoom"], 4, 0.7, 9, 1.7, 12, 2.8, 16, 4.5],
+					"circle-color": colorMatch,
+					"circle-opacity": 0.85,
+				},
+			},
+		],
+	}
 
-const legendRows = Object.keys(CATEGORY_COLOR)
-	.map((c) => `<div><i style="background:${CATEGORY_COLOR[c]}"></i>${CATEGORY_LABEL[c]}</div>`)
-	.join("")
+	const legendRows = Object.keys(CATEGORY_COLOR)
+		.map((c) => `<div><i style="background:${CATEGORY_COLOR[c]}"></i>${CATEGORY_LABEL[c]}</div>`)
+		.join("")
 
-// The client script avoids template literals / `${` so it survives this outer template verbatim.
-const html = `<!doctype html>
+	// The client script avoids template literals / `${` so it survives this outer template verbatim.
+	const html = `<!doctype html>
 <html lang="en">
 <head>
 <meta charset="utf-8" />
@@ -162,5 +168,8 @@ const html = `<!doctype html>
 </html>
 `
 
-writeFileSync(OUT, html)
-console.error(`[written] ${OUT}  (pmtiles: ${PMTILES_URL})`)
+	writeFileSync(OUT, html)
+	report?.(`[written] ${OUT}  (pmtiles: ${PMTILES_URL})`)
+
+	return { outPath: OUT, pmtilesURL: PMTILES_URL }
+}

package/tools/race-dots.ts

@@ -7,40 +7,46 @@
  *   `mailwoman tiger` CLI produces.
  *
  *   Reads `tabblock20 ⋈ pl_block` (block geometry + Census 2020 P.L. 94-171 table P2 counts) and
- *   scatters one dot per `--per` people uniformly at random inside each block, tagged with its
+ *   scatters one dot per `per` people uniformly at random inside each block, tagged with its
  *   race/ethnicity category. Output is NDJSON (one GeoJSON Point Feature per line, with a
  *   `tippecanoe` layer hint) ready for `tippecanoe -o race-dots.pmtiles`.
  *
  *   Point-in-polygon uses `@turf/boolean-contains` (ships with `@mailwoman/tiger`). The dot is a
  *   _representation_, not a record: a random position inside the block it belongs to, standing in
- *   for `--per` real people of that category. It says nothing about any individual address.
+ *   for `per` real people of that category. It says nothing about any individual address.
  *
- *   Build the input DB first: mailwoman tiger fetch --state 06 --county 059 --out tiger-oc.db
- *   mailwoman tiger redistricting --state 06 --county 059 --out tiger-oc.db
+ *   Build the input DB first: `mailwoman tiger fetch --state 06 --county 059 --out tiger-oc.db` then
+ *   `mailwoman tiger redistricting --state 06 --county 059 --out tiger-oc.db`.
  *
- *   Run: node --experimental-strip-types scripts/census/race-dots.ts\
- *   --db tiger-oc.db --per 10 --out /tmp/race-dots.ndjson
+ *   Run: `mailwoman tiger race-dots --db tiger-oc.db --per 10 --out /tmp/race-dots.ndjson`
  */
 
 import { createWriteStream } from "node:fs"
 import { DatabaseSync } from "node:sqlite"
-import { parseArgs } from "node:util"
 
 import { dataRootPath } from "@mailwoman/core/utils"
-import booleanContains from "@turf/boolean-contains"
-
-// Loose scan parity with the retired local argv helpers: unknown flags tolerated.
-const { values: rawValues } = parseArgs({
-	options: { db: { type: "string" }, layer: { type: "string" }, out: { type: "string" }, per: { type: "string" } },
-	strict: false,
-	allowPositionals: true,
-})
-// Typed view: strict:false loosens TS inference, but declared options always parse to their schema type.
-const values = rawValues as { db?: string; layer?: string; out?: string; per?: string }
-const DB = values["db"] || dataRootPath("tiger", "tiger-oc.db")
-const OUT = values["out"] || "/tmp/race-dots.ndjson"
-const PER = Number(values["per"] || "10") // people represented by one dot
-const LAYER = values["layer"] || "dots"
+
+/** Options for {@linkcode raceDots}. */
+export interface RaceDotsOptions {
+	/** TIGER SQLite DB (`tabblock20` ⋈ `pl_block`). Default `$MAILWOMAN_DATA_ROOT/tiger/tiger-oc.db`. */
+	db?: string
+	/** Output NDJSON path. Default `/tmp/race-dots.ndjson`. */
+	out?: string
+	/** People represented by one dot. Default 10. */
+	per?: number
+	/** Tippecanoe layer name. Default `dots`. */
+	layer?: string
+}
+
+/** Result of {@linkcode raceDots}. */
+export interface RaceDotsResult {
+	outPath: string
+	dots: number
+	skipped: number
+	blocks: number
+	/** Dots emitted per P2 category. */
+	totals: Record<string, number>
+}
 
 // The eight P2 categories (columns in pl_block) that partition each block's population.
 const CATEGORIES = ["hispanic", "white", "black", "asian", "aian", "nhpi", "other", "multi"] as const
@@ -75,97 +81,114 @@ function bbox(rings: PolygonCoords): [number, number, number, number] {
 	return [minX, minY, maxX, maxY]
 }
 
-// A block geometry is one or more polygons. Pick a sub-polygon weighted by bbox area, then
-// rejection-sample inside it with a turf containment test (handles holes + winding correctly).
-function randomPointIn(polys: PolygonCoords[], areas: number[], totalArea: number): [number, number] | null {
-	let r = Math.random() * totalArea
-	let pick = 0
-
-	while (pick < polys.length - 1 && (r -= areas[pick]!) > 0) {
-		pick++
-	}
-	const poly = polys[pick]!
-	const polyFeature = {
-		type: "Feature" as const,
-		geometry: { type: "Polygon" as const, coordinates: poly },
-		properties: {},
-	}
-	const [minX, minY, maxX, maxY] = bbox(poly)
-
-	for (let tries = 0; tries < 60; tries++) {
-		const x = minX + Math.random() * (maxX - minX)
-		const y = minY + Math.random() * (maxY - minY)
-		const pt = { type: "Feature" as const, geometry: { type: "Point" as const, coordinates: [x, y] }, properties: {} }
+/** Race-by-dot-density NDJSON builder — see the module doc. */
+export async function raceDots(
+	options: RaceDotsOptions = {},
+	report?: (line: string) => void
+): Promise<RaceDotsResult> {
+	const DB = options.db || dataRootPath("tiger", "tiger-oc.db")
+	const OUT = options.out || "/tmp/race-dots.ndjson"
+	const PER = options.per ?? 10 // people represented by one dot
+	const LAYER = options.layer || "dots"
+
+	// Heavy dep, lazy-imported so loading the tools barrel stays cheap.
+	const { default: booleanContains } = await import("@turf/boolean-contains")
+
+	// A block geometry is one or more polygons. Pick a sub-polygon weighted by bbox area, then
+	// rejection-sample inside it with a turf containment test (handles holes + winding correctly).
+	function randomPointIn(polys: PolygonCoords[], areas: number[], totalArea: number): [number, number] | null {
+		let r = Math.random() * totalArea
+		let pick = 0
+
+		while (pick < polys.length - 1 && (r -= areas[pick]!) > 0) {
+			pick++
+		}
+		const poly = polys[pick]!
+		const polyFeature = {
+			type: "Feature" as const,
+			geometry: { type: "Polygon" as const, coordinates: poly },
+			properties: {},
+		}
+		const [minX, minY, maxX, maxY] = bbox(poly)
 
-		if (booleanContains(polyFeature, pt)) return [x, y]
-	}
+		for (let tries = 0; tries < 60; tries++) {
+			const x = minX + Math.random() * (maxX - minX)
+			const y = minY + Math.random() * (maxY - minY)
+			const pt = { type: "Feature" as const, geometry: { type: "Point" as const, coordinates: [x, y] }, properties: {} }
 
-	return null
-}
+			if (booleanContains(polyFeature, pt)) return [x, y]
+		}
 
-const db = new DatabaseSync(DB, { readOnly: true })
-const rows = db
-	.prepare(
-		`SELECT b.geometry AS geometry, ${CATEGORIES.map((c) => `p.${c} AS ${c}`).join(", ")}
-		 FROM tabblock20 b JOIN pl_block p ON b.GEOID = p.GEOID
-		 WHERE p.pop_total > 0`
-	)
-	.all() as Array<{ geometry: string } & Record<(typeof CATEGORIES)[number], number>>
-db.close()
-
-const out = createWriteStream(OUT)
-const totals = new Map<string, number>()
-let dots = 0,
-	skipped = 0
-
-for (const row of rows) {
-	let geom: { type: string; coordinates: unknown }
-
-	try {
-		geom = JSON.parse(row.geometry)
-	} catch {
-		continue
+		return null
 	}
-	const polys: PolygonCoords[] =
-		geom.type === "Polygon" ? [geom.coordinates as PolygonCoords] : (geom.coordinates as PolygonCoords[])
-	const areas = polys.map((p) => {
-		const [a, b, c, d] = bbox(p)
-
-		return Math.max((c - a) * (d - b), 1e-12)
-	})
-	const totalArea = areas.reduce((s, a) => s + a, 0)
-
-	for (const cat of CATEGORIES) {
-		const people = row[cat]
-
-		if (people <= 0) continue
-		const exact = people / PER
-		const n = Math.floor(exact) + (Math.random() < exact - Math.floor(exact) ? 1 : 0)
 
-		for (let k = 0; k < n; k++) {
-			const pt = randomPointIn(polys, areas, totalArea)
-
-			if (!pt) {
-				skipped++
-				continue
+	const db = new DatabaseSync(DB, { readOnly: true })
+	const rows = db
+		.prepare(
+			`SELECT b.geometry AS geometry, ${CATEGORIES.map((c) => `p.${c} AS ${c}`).join(", ")}
+			 FROM tabblock20 b JOIN pl_block p ON b.GEOID = p.GEOID
+			 WHERE p.pop_total > 0`
+		)
+		.all() as Array<{ geometry: string } & Record<(typeof CATEGORIES)[number], number>>
+	db.close()
+
+	const out = createWriteStream(OUT)
+	const totals = new Map<string, number>()
+	let dots = 0,
+		skipped = 0
+
+	for (const row of rows) {
+		let geom: { type: string; coordinates: unknown }
+
+		try {
+			geom = JSON.parse(row.geometry)
+		} catch {
+			continue
+		}
+		const polys: PolygonCoords[] =
+			geom.type === "Polygon" ? [geom.coordinates as PolygonCoords] : (geom.coordinates as PolygonCoords[])
+		const areas = polys.map((p) => {
+			const [a, b, c, d] = bbox(p)
+
+			return Math.max((c - a) * (d - b), 1e-12)
+		})
+		const totalArea = areas.reduce((s, a) => s + a, 0)
+
+		for (const cat of CATEGORIES) {
+			const people = row[cat]
+
+			if (people <= 0) continue
+			const exact = people / PER
+			const n = Math.floor(exact) + (Math.random() < exact - Math.floor(exact) ? 1 : 0)
+
+			for (let k = 0; k < n; k++) {
+				const pt = randomPointIn(polys, areas, totalArea)
+
+				if (!pt) {
+					skipped++
+					continue
+				}
+				out.write(
+					JSON.stringify({
+						type: "Feature",
+						tippecanoe: { layer: LAYER },
+						properties: { cat },
+						geometry: { type: "Point", coordinates: [Math.round(pt[0] * 1e5) / 1e5, Math.round(pt[1] * 1e5) / 1e5] },
+					}) + "\n"
+				)
+				dots++
+				totals.set(cat, (totals.get(cat) ?? 0) + 1)
 			}
-			out.write(
-				JSON.stringify({
-					type: "Feature",
-					tippecanoe: { layer: LAYER },
-					properties: { cat },
-					geometry: { type: "Point", coordinates: [Math.round(pt[0] * 1e5) / 1e5, Math.round(pt[1] * 1e5) / 1e5] },
-				}) + "\n"
-			)
-			dots++
-			totals.set(cat, (totals.get(cat) ?? 0) + 1)
 		}
 	}
-}
 
-out.end()
-console.error(`[done] ${dots} dots from ${rows.length} blocks (1 dot ≈ ${PER} people); ${skipped} skipped`)
+	out.end()
+	await new Promise<void>((resolve) => out.on("finish", () => resolve()))
+	report?.(`[done] ${dots} dots from ${rows.length} blocks (1 dot ≈ ${PER} people); ${skipped} skipped`)
+
+	for (const [cat, n] of [...totals.entries()].sort((a, b) => b[1] - a[1])) {
+		report?.(`  ${n.toString().padStart(7)}  ${cat}`)
+	}
 
-for (const [cat, n] of [...totals.entries()].sort((a, b) => b[1] - a[1])) {
-	console.error(`  ${n.toString().padStart(7)}  ${cat}`)
+	return { outPath: OUT, dots, skipped, blocks: rows.length, totals: Object.fromEntries(totals) }
 }

package/tools/serve-range.ts

@@ -5,20 +5,31 @@
  *
  *   Minimal static file server that honours HTTP Range requests (206) — Python's `http.server` does
  *   not, and PMTiles reads via Range, so it can't be served by it. Used to preview/render a local
- *   `.pmtiles` tileset (e.g. the race-dot map). Not for production; the deployed tiles go through
- *   the tile worker.
+ *   `.pmtiles` tileset (e.g. the race-dot map, via `mailwoman tiger race-dots-map --serve`). Not for
+ *   production; the deployed tiles go through the tile worker.
  *
- *   Run: node scripts/census/serve-range.ts [dir=/tmp] [port=8899]
+ *   Internal helper module — no standalone command.
  */
 
 import { createReadStream, statSync, type Stats } from "node:fs"
-import { createServer, type IncomingMessage, type ServerResponse } from "node:http"
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http"
 import { extname, join, normalize } from "node:path"
-import { parseArgs } from "node:util"
 
-const { positionals } = parseArgs({ allowPositionals: true, strict: false })
-const DIR = positionals[0] || "/tmp"
-const PORT = Number(positionals[1] || 8899)
+/** Options for {@linkcode serveWithRangeSupport}. */
+export interface ServeRangeOptions {
+	/** Directory to serve. Default `/tmp`. */
+	dir?: string
+	/** Port to listen on. Default 8899. */
+	port?: number
+}
+
+/** A running range-capable static server, resolved once listening. */
+export interface RangeServer {
+	dir: string
+	port: number
+	server: Server
+	close: () => void
+}
 
 const TYPES: Record<string, string> = {
 	".html": "text/html; charset=utf-8",
@@ -28,34 +39,54 @@ const TYPES: Record<string, string> = {
 	".png": "image/png",
 }
 
-createServer((req: IncomingMessage, res: ServerResponse) => {
-	const rel = normalize(decodeURIComponent((req.url || "/").split("?")[0]!)).replace(/^(\.\.[/\\])+/, "")
-	const path = join(DIR, rel)
-	let st: Stats
-
-	try {
-		st = statSync(path)
-	} catch {
-		res.writeHead(404)
-
-		return res.end("not found")
-	}
-	const type = TYPES[extname(path)] || "application/octet-stream"
-	const base = { "Content-Type": type, "Accept-Ranges": "bytes", "Access-Control-Allow-Origin": "*" }
-	const range = req.headers.range
-	const m = range && /bytes=(\d+)-(\d*)/.exec(range)
-
-	if (m) {
-		const start = Number(m[1])
-		const end = m[2] ? Number(m[2]) : st.size - 1
-		res.writeHead(206, {
-			...base,
-			"Content-Range": `bytes ${start}-${end}/${st.size}`,
-			"Content-Length": end - start + 1,
+/**
+ * Serve `dir` over localhost with HTTP Range support. Resolves once the server is listening; the caller owns the
+ * lifetime (`close()` to stop — commands typically hold the process open instead).
+ */
+export function serveWithRangeSupport(
+	options: ServeRangeOptions = {},
+	report?: (line: string) => void
+): Promise<RangeServer> {
+	const dir = options.dir || "/tmp"
+	const port = options.port ?? 8899
+
+	const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+		const rel = normalize(decodeURIComponent((req.url || "/").split("?")[0]!)).replace(/^(\.\.[/\\])+/, "")
+		const path = join(dir, rel)
+		let st: Stats
+
+		try {
+			st = statSync(path)
+		} catch {
+			res.writeHead(404)
+
+			return res.end("not found")
+		}
+		const type = TYPES[extname(path)] || "application/octet-stream"
+		const base = { "Content-Type": type, "Accept-Ranges": "bytes", "Access-Control-Allow-Origin": "*" }
+		const range = req.headers.range
+		const m = range && /bytes=(\d+)-(\d*)/.exec(range)
+
+		if (m) {
+			const start = Number(m[1])
+			const end = m[2] ? Number(m[2]) : st.size - 1
+			res.writeHead(206, {
+				...base,
+				"Content-Range": `bytes ${start}-${end}/${st.size}`,
+				"Content-Length": end - start + 1,
+			})
+			createReadStream(path, { start, end }).pipe(res)
+		} else {
+			res.writeHead(200, { ...base, "Content-Length": st.size })
+			createReadStream(path).pipe(res)
+		}
+	})
+
+	return new Promise<RangeServer>((resolve, reject) => {
+		server.once("error", reject)
+		server.listen(port, () => {
+			report?.(`range server: ${dir} on http://localhost:${port}`)
+			resolve({ dir, port, server, close: () => server.close() })
 		})
-		createReadStream(path, { start, end }).pipe(res)
-	} else {
-		res.writeHead(200, { ...base, "Content-Length": st.size })
-		createReadStream(path).pipe(res)
-	}
-}).listen(PORT, () => console.error(`range server: ${DIR} on http://localhost:${PORT}`))
+	})
+}