@mailwoman/map-tui 10.0.0 → 10.1.0

package/README.md

@@ -5,8 +5,8 @@ A frame-first terminal map renderer. It decodes vector tiles from a
 resolves the result to a grid of terminal cells — braille-glyph map frames
 suitable for TUIs and other character-grid displays.
 
-The unit of output is a `MapFrame`: frames are values, not side effects.
-Rendering never writes to stdout, an Ink component, or any other presentation
+The unit of output is a `MapFrame`: frames are values rather than side effects.
+The renderer never writes to stdout, an Ink component, or any other presentation
 layer directly — a caller reads the frame's cells and decides how (and
 whether) to draw them.
 
@@ -60,12 +60,11 @@ with the [protomaps-basemap](https://github.com/protomaps/basemaps) layer names
 (`earth`, `water`, `roads`, `boundaries`, `places`, …) renders; other schemas
 decode fine but draw only the layers this package styles.
 
-Working in this repo, the committed test fixture — a hand-authored slice of
-southeast Portland — is enough to see the browser run without downloading
-anything:
+The committed test fixture, a hand-authored extract of southeast Portland, lets you run the browser
+without downloading anything:
 
 ```sh
-node map-tui/out/cli.js \
+node map-tui/out/cli/main.js \
   --tiles map-tui/test/fixtures/portland.pmtiles \
   --lat 45.5034 --lon -122.6023 --zoom 12
 ```

package/{lib/cli → cli}/args.ts

@@ -1,5 +1,7 @@
 import { errorMessage } from "@mailwoman/core/errors/schema"
+import { stringifyJSON } from "@mailwoman/core/json"
 import { parseArguments } from "@mailwoman/core/scripting/arguments"
+
 /**
  * @copyright Sister Software.
  * @license AGPL-3.0
@@ -9,9 +11,12 @@ import { parseArguments } from "@mailwoman/core/scripting/arguments"
 /**
  * Argument parsing for the `map-tui` bin.
  *
- * `parseCLIArgs` is pure: it takes the argv slice and an environment record, and answers with a discriminated result
- * (`help` / `version` / `browse`) or throws {@link CLIArgsError}. Reading `process.argv` / `process.env` is the bin's
- * job (./cli.ts), which keeps every rejection path testable without a subprocess.
+ * `parseCLIArgs` is pure.
+ * It takes the argv array and an environment record, then returns a discriminated
+ * result (`help` / `version` / `browse`) or throws {@link CLIArgsError}.
+ *
+ * The bin (`./cli.ts`) reads `process.argv` and `process.env`.
+ * This keeps every rejection path testable without a subprocess.
  */
 
 /**
@@ -25,8 +30,8 @@ const DEFAULT_LON = 0
 const DEFAULT_LAT = 0
 
 /**
- * Zoom when `--zoom` is omitted. z2 shows a full hemisphere in a typical terminal, so a planet archive opens on
- * something recognizable rather than a single ocean tile.
+ * Zoom when `--zoom` is omitted. z2 shows a full hemisphere in a typical terminal,
+ * so a planet archive opens on something recognizable rather than a single ocean tile.
  */
 const DEFAULT_ZOOM = 2
 
@@ -36,14 +41,16 @@ const DEFAULT_ZOOM = 2
 const MIN_ZOOM = 0
 
 /**
- * Deepest zoom the Web-Mercator tile pyramid is defined for. The archive's own `maxZoom` clamps further at runtime;
- * this is only the range a flag value must fall inside to be meaningful at all.
+ * Deepest zoom the Web-Mercator tile pyramid is defined for.
+ *
+ * The archive's own `maxZoom` clamps further at runtime.
+ * This is only the range a flag value must fall inside to be meaningful at all.
  */
 const MAX_ZOOM = 24
 
-// True geographic bounds, not Web-Mercator's ±85.05113: the flag accepts any real latitude, and the browser clamps
-// the CENTER to the projection's MERCATOR_LATITUDE_LIMIT itself (see ./browser.ts) — rejecting 87 here would refuse a
-// value the viewport handles fine.
+// The flag accepts any real latitude.
+// The browser clamps the center to the projection's MERCATOR_LATITUDE_LIMIT (see ./browser.ts) —
+// rejecting 87 here would refuse a value the viewport handles fine.
 const MIN_LAT = -90
 const MAX_LAT = 90
 const MIN_LON = -180
@@ -61,8 +68,10 @@ export interface BrowseArgs {
 	lat: number
 	lon: number
 	/**
-	 * Integer zoom level. The renderer draws whole tile-pyramid levels, so a fractional flag value is rounded here rather
-	 * than carried as a lie through the viewport.
+	 * Integer zoom level.
+	 *
+	 * The renderer draws whole tile-pyramid levels, so a fractional flag value is rounded here
+	 * rather than preserved as a lie through the viewport.
 	 */
 	zoom: number
 }
@@ -70,23 +79,30 @@ export interface BrowseArgs {
 export type CLIArgs = { mode: "help" } | { mode: "version" } | BrowseArgs
 
 /**
- * A rejected command line. The message is user-facing: it says what was wrong AND what to pass instead, since the bin
- * prints it verbatim to stderr.
+ * A rejected command line.
+ *
+ * The message is user-facing: it explains what was wrong and what to pass instead,
+ * since the bin prints it verbatim to stderr.
  */
 export class CLIArgsError extends Error {
 	override name = "CLIArgsError"
 }
 
 /**
- * Environment keys the CLI reads. Passed in rather than read here so the parser stays pure.
+ * Environment keys the CLI reads.
+ *
+ * Passed in rather than read here so the parser stays pure.
  */
 export interface CLIEnvironment {
 	MAILWOMAN_TILES?: string | undefined
 }
 
 /**
- * `--help` output. It doubles as the package's key reference, so the bindings listed here and the ones ./input.ts
- * decodes are the same list said twice — a key added there without a line here is a key nobody finds.
+ * `--help` output.
+ *
+ * It doubles as the package's key reference, so the bindings listed here
+ * and the ones ./input.ts decodes are the same list said twice.
+ * A key added there without a line here is missing from CLI help.
  */
 export const HELP_TEXT = `map-tui — the whole world in your terminal
 
@@ -115,8 +131,8 @@ archive from https://protomaps.com/downloads and point --tiles at it.
 `
 
 /**
- * Reads one numeric flag, rejecting anything `Number` would quietly accept as garbage (empty string, whitespace,
- * `Infinity`) as well as out-of-range values.
+ * Reads one numeric flag, rejecting anything `Number` would quietly accept as garbage
+ * (empty string, whitespace, `Infinity`) as well as out-of-range values.
  */
 function numericFlag(name: string, raw: string | undefined, fallback: number, min: number, max: number): number {
 	if (raw == null) return fallback
@@ -124,7 +140,7 @@ function numericFlag(name: string, raw: string | undefined, fallback: number, mi
 	const value = Number(raw.trim())
 
 	if (!Number.isFinite(value) || !raw.trim().length) {
-		throw new CLIArgsError(`--${name} expects a number, got ${JSON.stringify(raw)}`)
+		throw new CLIArgsError(`--${name} expects a number, got ${stringifyJSON(raw)}`)
 	}
 
 	if (value < min || value > max) {
@@ -135,17 +151,21 @@ function numericFlag(name: string, raw: string | undefined, fallback: number, mi
 }
 
 /**
- * Flags whose value is a number, and may therefore start with a dash.
+ * Flags with numeric values.
+ * Their values may start with a dash.
  */
 const NUMERIC_FLAGS = new Set(["--lat", "--lon", "--zoom"])
 
 /**
  * Joins `--lon -122.6` into `--lon=-122.6` before `parseArgs` sees it.
  *
- * `node:util`'s parser refuses a separate value that starts with a dash — it cannot tell a negative number from a
- * mistyped flag, and says so ("argument is ambiguous"). Half the planet has a negative longitude, so the space-form has
- * to work. The join is conditional on the next token parsing as a finite number, which leaves a genuinely missing value
- * (`--lon --zoom 3`) to `parseArgs` and its own error.
+ * `node:util`'s parser refuses a separate value that starts with a dash.
+ * It reports "argument is ambiguous" because a negative number can resemble a mistyped flag.
+ *
+ * Half the planet has a negative longitude, so the space-form has to work.
+ *
+ * The join occurs only when the next token parses as a finite number.
+ * `parseArgs` then handles a missing value such as `--lon --zoom 3` and returns its own error.
  */
 function joinNegativeNumbers(argv: readonly string[]): string[] {
 	const joined: string[] = []
@@ -177,8 +197,8 @@ interface ParsedFlags {
 }
 
 /**
- * `node:util`'s own rejections (unknown flag, missing value) name the flag but not the remedy, so they're re-thrown as
- * a {@link CLIArgsError} pointing at `--help`.
+ * `node:util`'s own rejections (unknown flag, missing value) name the flag but not the action,
+ * so they're re-thrown as a {@link CLIArgsError} pointing at `--help`.
  */
 function readFlags(argv: readonly string[]): ParsedFlags {
 	try {
@@ -205,7 +225,8 @@ function readFlags(argv: readonly string[]): ParsedFlags {
 /**
  * Parses a `map-tui` command line.
  *
- * @throws {CLIArgsError} On an unknown flag, an unparseable or out-of-range number, or a missing archive path.
+ * @throws {CLIArgsError} On an unknown flag, an unparseable or out-of-range number,
+ * or a missing archive path.
  */
 export function parseCLIArgs(argv: readonly string[], environment: CLIEnvironment = {}): CLIArgs {
 	const values = readFlags(argv)

package/{lib/cli/index.ts → cli/main.ts}

@@ -7,17 +7,11 @@
  */
 
 /**
- * The `map-tui` bin — `npx @mailwoman/map-tui` opens a PMTiles archive as a full-screen terminal map.
+ * Opens a PMTiles archive as a full-screen terminal map through the `map-tui` binary.
  *
- * This file owns everything process-shaped so the rest of the package stays testable without one: argv and the
- * environment (parsed by ./cli-args.ts), the archive handle, signal handlers, and the exit code. `MapBrowser` takes
- * streams rather than reaching for `process` itself, which is what lets the PTY smoke test drive the real bin and a
- * unit test drive the parser with neither.
- *
- * Signal handling is not optional here. This is a raw-mode app on the alternate screen with mouse reporting on, and
- * there is no framework underneath to put any of that back — a process killed between `start` and `restore` leaves the
- * user with an unusable shell. So `restore` is wired to SIGINT, SIGTERM and `exit`, and it is idempotent for exactly
- * that reason.
+ * This file is the only place in the package that touches `process`.
+ * It restores the terminal on SIGINT, SIGTERM and `exit`, because a process killed
+ * while in raw mode leaves the shell unusable.
  */
 
 import { errorMessage } from "@mailwoman/core/errors/schema"
@@ -33,11 +27,10 @@ import { TileSource } from "#tile-source"
 const EXIT_USAGE = 1
 
 /**
- * Reads the package's own version.
+ * Reads the package version.
  *
- * Self-reference (`@mailwoman/map-tui/...`, which the package's `exports` publishes) rather than a path relative to
- * this file: the bin runs from `out/` when installed and from the workspace root in development, and only the package
- * graph knows which. `createRequire` parses the JSON itself, so no reader here has to.
+ * The package self-reference resolves correctly both from the installed `out/`
+ * directory and from the workspace.
  */
 function readVersion(): string {
 	const require = createRequire(import.meta.url)
@@ -47,7 +40,7 @@ function readVersion(): string {
 }
 
 /**
- * Opens the archive, translating the filesystem's error into something that names the flag that was wrong.
+ * Opens the tile archive and reports a failure as a usage error that mentions `--tiles`.
  */
 async function openTiles(path: string): Promise<TileSource> {
 	try {
@@ -61,7 +54,7 @@ async function openTiles(path: string): Promise<TileSource> {
 }
 
 /**
- * Runs the interactive browser against an already-open archive, resolving with its exit code.
+ * Runs the interactive browser on an open archive and resolves with its exit code.
  */
 async function browse(source: TileSource, args: { lat: number; lon: number; zoom: number }): Promise<number> {
 	const browser = new MapBrowser({
@@ -94,11 +87,8 @@ async function main(): Promise<number> {
 	let args: CLIArgs
 
 	try {
-		/**
-		 * `parseCLIArgs` keeps argv and the environment read on this one line, and nowhere else in the package —
-		 * `@mailwoman/core/env`'s typed readers would pull core's data-backed environment schema behind a CLI whose whole
-		 * premise is `npx`, so the bin passes the raw records to the pure parser instead.
-		 */
+		// The bin reads raw argv and env here because `@mailwoman/core/env` depends on core's data-backed schema,
+		// Core's data-backed schema is too heavy for an `npx` entry point.
 		// oxlint-disable-next-line sister-software/no-process-globals -- see above.
 		args = parseCLIArgs(process.argv.slice(2), process.env)
 	} catch (error) {
@@ -123,8 +113,7 @@ async function main(): Promise<number> {
 
 	let opened: TileSource
 
-	// A bad `--tiles` path is a usage error, not a crash — the guard stays around the open, and ownership passes to the
-	// `using` declaration only once the open succeeded.
+	// The `using` declaration takes ownership only after the open succeeds.
 	try {
 		opened = await openTiles(args.tiles)
 	} catch (error) {

package/lib/browser.ts

@@ -4,22 +4,6 @@
  * @author Teffen Ellis, et al.
  */
 
-/**
- * The interactive map browser — a full-screen, alternate-screen terminal app over `MapRenderer`.
- *
- * `MapBrowser` owns exactly three things the frame-first library deliberately does not: terminal MODE (alternate
- * screen, hidden cursor, raw stdin, mouse reporting), viewport STATE (center, zoom, drag anchor), and the write path.
- * Frames still come from `MapRenderer.renderFrame` as values; `blitFrame` copies one into an `AsciifyTerminal`, whose
- * damage diff decides what actually goes down the wire.
- *
- * The pane is the terminal minus its bottom row, which is the status bar. `AsciifyTerminal` is told that size and never
- * addresses a cell outside it, so the two writers never fight over a cell.
- *
- * Every mode change made in {@link MapBrowser.start} is undone by {@link MapBrowser.restore}, which is idempotent so a
- * signal handler, an `exit` hook and the normal path can all call it. A terminal left in raw mode with mouse reporting
- * on is not a recoverable shell, so restore is the one operation that must survive any exit path.
- */
-
 import { errorMessage } from "@mailwoman/core/errors/schema"
 import { clamp } from "@mailwoman/core/numeric"
 import { AsciifyTerminal, cursorTo, SGR_RESET } from "@sister.software/asciify/tui"
@@ -44,41 +28,26 @@ const CLEAR_SCREEN = "\u001B[2J"
 const CLEAR_LINE = "\u001B[2K"
 const REVERSE_VIDEO = "\u001B[7m"
 
-/**
- * Rows reserved at the bottom of the terminal for the status bar.
- */
 const STATUS_BAR_ROWS = 1
 
-/**
- * Size assumed when the output reports none. A pty opened without a window size (util-linux `script`, some CI
- * harnesses) reports 0 columns and 0 rows, which is neither an error nor a usable grid.
- */
 const FALLBACK_COLUMNS = 80
 const FALLBACK_ROWS = 24
 
 /**
- * Floor on the pane's dimensions. Below this the renderer is being asked for a grid too small to mean anything, and a
- * zero-sized one would divide by zero in the projection.
+ * A zero-sized pane would divide by zero in the projection.
  */
 const MIN_COLUMNS = 4
 const MIN_PANE_ROWS = 1
 
-/**
- * How much of the pane one arrow-key press travels. An eighth is far enough to feel like progress at a keystroke and
- * short enough that the next frame still overlaps the last.
- */
 const PAN_FRACTION = 0.125
 
-/**
- * Web-Mercator's latitude cutoff — the projection is undefined at the poles, and the square tile pyramid ends here.
- */
 const MERCATOR_LATITUDE_LIMIT = 85.05112878
 
 const COORDINATE_DIGITS = 4
 
 /**
- * The subset of a readable stream the browser drives. Structural so `process.stdin` satisfies it without the app being
- * welded to it — the same reasoning asciify applies to its own output type.
+ * The subset of a readable stream the browser uses, kept structural so that
+ * `process.stdin` and test doubles both satisfy it.
  */
 export interface BrowserInput {
 	setRawMode?(mode: boolean): unknown
@@ -90,7 +59,7 @@ export interface BrowserInput {
 }
 
 /**
- * The subset of a writable terminal the browser drives.
+ * The subset of a writable terminal the browser uses.
  */
 export interface BrowserOutput {
 	write(chunk: string): unknown
@@ -100,6 +69,9 @@ export interface BrowserOutput {
 	off(event: "resize", listener: () => void): unknown
 }
 
+/**
+ * Options for {@link MapBrowser}: the tile source, the terminal streams and the initial viewport.
+ */
 export interface MapBrowserOptions {
 	source: TileSource
 	input: BrowserInput
@@ -119,8 +91,7 @@ interface DragAnchor {
 }
 
 /**
- * Clips a string to a cell budget, counting codepoints — the status bar's arrows are one cell each but two UTF-16
- * units, and `String.prototype.slice` would split one in half.
+ * Code-point counts keep `slice` from splitting a surrogate pair.
  */
 function clipToCells(text: string, cells: number): string {
 	const codePoints = Array.from(text)
@@ -128,6 +99,10 @@ function clipToCells(text: string, cells: number): string {
 	return codePoints.length <= cells ? text : codePoints.slice(0, cells).join("")
 }
 
+/**
+ * A full-screen terminal map browser built on `MapRenderer` that owns terminal modes,
+ * viewport state and output, leaving the bottom row as a status bar.
+ */
 export class MapBrowser {
 	private readonly source: TileSource
 	private readonly renderer: MapRenderer
@@ -151,9 +126,8 @@ export class MapBrowser {
 	private resolveExit: ((code: number) => void) | null = null
 
 	/**
-	 * The trailing bytes of the last chunk that could not be decoded yet — a sequence the kernel split across two reads.
-	 * Threading it back through `decodeInputChunk` is what keeps a split mouse report from being read as an Esc keypress
-	 * (which used to quit); the decoder itself stays pure.
+	 * The next `decodeInputChunk` call receives trailing bytes from an incomplete escape sequence
+	 * so a mouse report split across reads does not decode as an Esc keypress.
 	 */
 	private pendingInput = ""
 
@@ -192,8 +166,8 @@ export class MapBrowser {
 	}
 
 	/**
-	 * Runs until the user quits, resolving with the process exit code (0 for a normal quit, 130 for Ctrl+C). The terminal
-	 * is restored before this resolves.
+	 * Runs until the user quits, resolving with the exit code (0 for a normal quit, 130 for Ctrl+C)
+	 * after the terminal is restored.
 	 */
 	async run(): Promise<number> {
 		this.start()
@@ -208,8 +182,8 @@ export class MapBrowser {
 	}
 
 	/**
-	 * Asks the browser to exit with a code. Safe to call from a signal handler, and a no-op once an exit is already under
-	 * way.
+	 * Asks the browser to exit with a code, ignoring calls after the first
+	 * so that a signal handler may call it.
 	 */
 	requestExit(code: number): void {
 		const resolve = this.resolveExit
@@ -220,9 +194,6 @@ export class MapBrowser {
 		resolve(code)
 	}
 
-	/**
-	 * Enters the alternate screen and takes over input. Paired with {@link restore}.
-	 */
 	start(): void {
 		if (this.started) return
 
@@ -239,10 +210,6 @@ export class MapBrowser {
 		this.scheduleRender()
 	}
 
-	/**
-	 * Puts the terminal back exactly as it was found. Idempotent: the normal exit path, a signal handler and a
-	 * process-level `exit` hook may each call it.
-	 */
 	restore(): void {
 		if (!this.started || this.restored) return
 
@@ -293,8 +260,8 @@ export class MapBrowser {
 	}
 
 	/**
-	 * Moves the center by a cell delta, through world pixels so the step is the same distance on screen at every latitude
-	 * — the naive degrees-per-keypress version crawls at the equator and sprints near the poles.
+	 * Moves the center by a cell delta in world pixels, so one step covers the
+	 * same screen distance at every latitude.
 	 */
 	private panByCells(columns: number, rows: number): void {
 		const center = lonLatToWorldPx(this.centerLon, this.centerLat, this.zoom)
@@ -313,9 +280,6 @@ export class MapBrowser {
 		this.centerLat = clamp(lat, -MERCATOR_LATITUDE_LIMIT, MERCATOR_LATITUDE_LIMIT)
 	}
 
-	/**
-	 * Longitude/latitude at the center of a pane cell.
-	 */
 	private cellToLonLat(column: number, row: number): { lon: number; lat: number } {
 		const center = lonLatToWorldPx(this.centerLon, this.centerLat, this.zoom)
 		const originX = center.x - (this.columns * SUBPIXEL_COLUMNS_PER_CELL) / 2
@@ -329,8 +293,7 @@ export class MapBrowser {
 	}
 
 	/**
-	 * Zooms one or more whole levels. With an anchor cell (the wheel's pointer), the center shifts so whatever was under
-	 * the pointer stays under it; without one, the pane center holds.
+	 * Zooms by whole levels, shifting the center so the point under an anchor cell stays under it.
 	 */
 	private zoomBy(delta: number, anchor: { column: number; row: number } | null): void {
 		const next = clamp(this.zoom + delta, this.source.minZoom, this.source.maxZoom)
@@ -381,8 +344,8 @@ export class MapBrowser {
 	}
 
 	/**
-	 * Pans relative to where the drag STARTED, not the previous motion report. Accumulating per-report deltas would
-	 * drift, since each one is rounded to a whole cell.
+	 * Pans relative to the drag's starting point, because summing per-report deltas
+	 * would drift as each report is rounded to a whole cell.
 	 */
 	private continueDrag(column: number, row: number): void {
 		const anchor = this.drag
@@ -404,8 +367,7 @@ export class MapBrowser {
 	}
 
 	/**
-	 * A press and release with no motion between them is a click, which centers the map — mapscii's behavior, and the
-	 * reason centering waits for the release rather than acting on the press.
+	 * A press and release without motion counts as a click that centers the map on the clicked cell.
 	 */
 	private endDrag(): void {
 		const anchor = this.drag
@@ -414,8 +376,7 @@ export class MapBrowser {
 
 		if (!anchor || anchor.moved) return
 
-		// A wheel event between press and release moved the map out from under the click, so the cell no longer names
-		// the place the user pointed at.
+		// A zoom between press and release means the cell no longer covers the point the user clicked.
 		if (anchor.zoom !== this.zoom) return
 
 		const target = this.cellToLonLat(anchor.column, anchor.row)
@@ -424,11 +385,8 @@ export class MapBrowser {
 		this.scheduleRender()
 	}
 
-	/**
-	 * Reads the terminal's size and re-sizes the pane around the status bar.
-	 */
 	private measure(): void {
-		// `||` and not `??`: a pty with no window size reports 0, which is as unusable as absent.
+		// The `||` operator also replaces the 0 that a pty without a window size reports.
 		const columns = Math.floor(this.output.columns || FALLBACK_COLUMNS)
 		const rows = Math.floor(this.output.rows || FALLBACK_ROWS)
 
@@ -439,8 +397,8 @@ export class MapBrowser {
 	}
 
 	/**
-	 * Requests a frame. Renders never overlap: a request arriving mid-render is coalesced into one more pass, so a held
-	 * arrow key queues a single redraw rather than a backlog of them.
+	 * Requests a frame, collapsing requests that arrive during a render into one
+	 * follow-up so renders never overlap.
 	 */
 	private scheduleRender(): void {
 		if (this.renderInFlight) {
@@ -478,12 +436,10 @@ export class MapBrowser {
 		try {
 			const frame = await this.renderer.renderFrame(viewport)
 
-			// The terminal may have been restored while the tiles were in flight; writing then would paint over the
-			// user's shell.
+			// A write after restore would draw over the user's shell.
 			if (this.restored) return
 
-			// A resize between the request and now leaves the frame the wrong shape for the pane — drop it and let the
-			// resize's own render answer instead.
+			// A resize during the render makes this frame the wrong shape and schedules its own render.
 			if (frame.columns !== this.columns || frame.rows !== this.paneRows) return
 
 			this.error = null
@@ -511,12 +467,13 @@ export class MapBrowser {
 
 		const credited = `${status}  © ${attribution}`
 
-		// Attribution is a courtesy to the tile source, never a reason to push the controls off the bar.
+		// The attribution is dropped when it would push the controls off the bar.
 		return Array.from(credited).length < this.columns ? credited : status
 	}
 
 	private drawStatusBar(attribution: string): void {
-		// One cell short of the width: writing the bottom-right cell leaves some terminals in a pending-wrap state.
+		// The line stops one cell short because writing the bottom-right cell leaves
+		// some terminals in a pending-wrap state.
 		const width = Math.max(0, this.columns - 1)
 		const line = clipToCells(this.statusText(attribution), width).padEnd(width)