@mailwoman/map-tui 9.4.0 → 10.1.0

package/lib/frame.ts

@@ -7,11 +7,15 @@
 /**
  * Braille frame value + conversion for map-tui's debug view.
  *
- * `rasterizeToFrame` turns an `RGBAGrid` (drawn by ./raster.ts) into a `MapFrame`: one codepoint and one packed color
- * per cell. The braille dither/luminance work is asciify's — `FrameRasterizer` subclasses `AsciifyTerminal` with a
- * no-op sink purely to reach its protected `_computeBrailleCells`, `_cellChars`, `_cellColors`, so this module never
- * re-implements the dot math. `frameToANSILines` and `overlayText` then work on the plain `MapFrame` value, with no
- * further asciify dependency; `blitFrame` is the path back the other way, for callers driving a live terminal.
+ * `rasterizeToFrame` turns an `RGBAGrid` (drawn by ./raster.ts) into a `MapFrame`:
+ * one codepoint and one packed color per cell.
+ * The braille dither/luminance work is asciify's.
+ *
+ * `FrameRasterizer` subclasses `AsciifyTerminal` with a no-op sink purely to reach its guarded
+ * `_computeBrailleCells`, `_cellChars`, `_cellColors`, so this module never re-implements the dot math.
+ *
+ * `frameToANSILines` and `overlayText` then work on the plain `MapFrame` value, with no further
+ * asciify dependency; `blitFrame` is the path back the other way, for callers driving a live terminal.
  */
 
 import { AsciifyTerminal, SGR_RESET } from "@sister.software/asciify/tui"
@@ -26,20 +30,23 @@ export interface MapFrame {
 	columns: number
 	rows: number
 	/**
-	 * Codepoint per cell, row-major (braille U+2800.. or overlay text).
+	 * Codepoint per cell, row-major (braille U+2800.. Or overlay text).
 	 */
 	chars: Uint32Array
 	/**
-	 * 0xRRGGBB per cell; 0 = inkless.
+	 * 0xRRGGBB per cell. 0 = inkless.
 	 */
 	colors: Uint32Array
 	attribution: string
 }
 
 /**
- * Reaches asciify's protected braille conversion from the outside. Constructed fresh per {@link rasterizeToFrame} call
- * — cheap, since the state is just two typed arrays sized to the cell grid. The `write` sink is never invoked: this
- * class only ever calls `_computeBrailleCells` directly, never `rasterize`/`flush`.
+ * Reaches asciify's guarded braille conversion from the outside.
+ *
+ * Constructed fresh per {@link rasterizeToFrame} call — cheap, since the state
+ * is just two typed arrays sized to the cell grid.
+ * The `write` sink is never invoked: this class only ever calls `_computeBrailleCells`
+ * directly, never `rasterize`/`flush`.
  */
 class FrameRasterizer extends AsciifyTerminal {
 	constructor(columns: number, rows: number) {
@@ -55,10 +62,12 @@ class FrameRasterizer extends AsciifyTerminal {
 }
 
 /**
- * Converts a 2×4-subpixel RGBA grid into braille cells. Grid must be `columns * 2` x `rows * 4`.
+ * Converts a 2×4-subpixel rgba grid into braille cells.
  *
- * @throws If the grid's dimensions don't match `columns * 2` x `rows * 4` — a caller sizing bug, not something to
- *   silently clip.
+ * Grid must be `columns * 2` x `rows * 4`.
+ *
+ * @throws If the grid's dimensions don't match `columns * 2` x `rows * 4` —
+ * a caller sizing bug rather than something to silently clip.
  */
 export function rasterizeToFrame(grid: RGBAGrid, columns: number, rows: number, attribution: string): MapFrame {
 	if (grid.width !== columns * 2 || grid.height !== rows * 4) {
@@ -74,11 +83,14 @@ export function rasterizeToFrame(grid: RGBAGrid, columns: number, rows: number,
 }
 
 /**
- * One SGR-styled string per row. `color: false` strips styling (NO_COLOR consumers).
+ * One SGR-styled string per row.
+ *
+ * `color: false` strips styling (NO_COLOR consumers).
  *
- * Inkless cells (packed color 0) never emit a color escape, matching asciify's own damage emitter — a cell going from
- * inked to inkless shouldn't touch color state. Each styled line ends with the SGR reset so a truncated terminal write
- * never bleeds color into whatever follows.
+ * Inkless cells (packed color 0) never emit a color escape, matching asciify's own damage
+ * emitter — a cell going from inked to inkless shouldn't touch color state.
+ * Each styled line ends with the SGR reset so a truncated terminal write never
+ * bleeds color into whatever follows.
  */
 export function frameToANSILines(frame: MapFrame, options?: { color?: boolean }): string[] {
 	const colorEnabled = options?.color ?? true
@@ -111,9 +123,11 @@ export function frameToANSILines(frame: MapFrame, options?: { color?: boolean })
 /**
  * Writes text into cells (clipped); occupied is the label-collision bitmap, updated in place.
  *
- * When `occupied` is given, every target cell plus one cell of padding on each side is checked before anything is
- * written — a single colliding cell rejects the whole label rather than partially overlaying it. Without `occupied`,
- * writes proceed unconditionally (still clipped to the frame's bounds) and always report success.
+ * When `occupied` is given, every target cell plus one cell of padding on each side is
+ * checked before anything is written — a single colliding cell rejects the whole label
+ * rather than partially overlaying it.
+ * Without `occupied`, writes proceed unconditionally (still clipped to the frame's bounds)
+ * and always report success.
  */
 export function overlayText(
 	frame: MapFrame,
@@ -160,25 +174,33 @@ export function overlayText(
 }
 
 /**
- * Packs RGB channels into the frame's 0xRRGGBB color representation. Shared with Task 8's marker colors so both sides
- * of the frame boundary agree on the packing.
+ * Packs RGB channels into the frame's 0xRRGGBB color representation.
+ *
+ * Shared with Task 8's marker colors so both sides of the frame boundary agree on the packing.
  */
 export function rgbToPacked(color: RGB): number {
 	return (color[0] << 16) | (color[1] << 8) | color[2]
 }
 
 /**
- * Codepoint written for a cell the frame left empty. `MapFrame` stores 0 there; `AsciifyTerminal` expects a real
- * character, and normalizes a space to the inkless color itself.
+ * Codepoint written for a cell the frame left empty.
+ *
+ * `MapFrame` stores 0 there.
+ * `AsciifyTerminal` expects a real character. and normalizes a space to the inkless color itself.
  */
 const SPACE_CODEPOINT = 0x20
 
 /**
- * Writes a frame's cells into an `AsciifyTerminal`'s current frame. Call `flush()` afterwards to emit the damage.
+ * Writes a frame's cells into an `AsciifyTerminal`'s current frame.
+ *
+ * Call `flush()` afterwards to emit the damage.
+ *
+ * The frame's packed color is the exact representation asciify canonicalizes truecolor to,
+ * so this is a copy and not a conversion.
+ * The channels are unpacked here only because {@linkcode AsciifyTerminal.setCell} takes them apart.
  *
- * The frame's packed color is the exact representation asciify canonicalizes truecolor to, so this is a copy and not a
- * conversion — the channels are unpacked here only because {@linkcode AsciifyTerminal.setCell} takes them apart. Cells
- * beyond the terminal's own grid are dropped by `setCell`, so a frame larger than the pane clips rather than throws.
+ * Cells beyond the terminal's own grid are dropped by `setCell`, so a frame
+ * larger than the pane clips rather than throws.
  */
 export function blitFrame(terminal: AsciifyTerminal, frame: MapFrame): void {
 	for (let row = 0; row < frame.rows; row++) {

package/lib/input.ts

@@ -5,52 +5,34 @@
  */
 
 /**
- * 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.
+ * The fallback separates a sequence this decoder recognizes (consumed and acted on), a complete
+ * but unrecognized sequence (consumed whole so a `q` inside it cannot quit the app), and a
+ * chunk that ends mid-sequence (returned as {@link DecodedInput.pending} rather than decoded),
+ * emitting quit only for an ESC whose following byte cannot continue a sequence.
  */
 
 /**
- * Enables mouse reporting: button events (1000), drag/button-motion tracking (1002), and SGR extended coordinates
- * (1006) so columns past 223 survive.
+ * 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.
+ * Disables the three mouse-reporting modes {@link MOUSE_ENABLE} turns on.
  */
 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.
+ * A decoded input event.
+ *
+ * Pan and zoom encode direction and magnitude only, since how far a step moves the
+ * map is the browser's decision rather than 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.
+	 * Ctrl+C sends an interrupt. The process exits with status 130.
+	 * Raw mode prevents the terminal from raising SIGINT.
 	 */
 	| { kind: "interrupt" }
 	| { kind: "pan"; dx: number; dy: number }
@@ -77,46 +59,48 @@ const MOUSE_SGR_PATTERN = /\u001B\[<(\d+);(\d+);(\d+)([Mm])/y
 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.
+ * Any other CSI sequence, consumed whole and ignored so an unhandled body is not re-scanned as key presses.
  */
 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.
+ * Any other SS3 sequence (`ESC O <final>`).
+ *
+ * On xterm this includes F1–F4 and the application-mode numeric keypad.
  */
 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.
+ * The string-sequence family (OSC, DCS, SOS, PM, APC), each running to a BEL
+ * or an ST, sent unasked by a terminal with no key pressed.
  */
 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.
+ * Every "unrecognized but complete" sequence, in the order they are tried.
+ *
+ * One shared list keeps a new family from being added here and forgotten in the incomplete test.
  */
 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.
+ * A chunk that stops inside a sequence, each end-anchored pattern requiring the whole
+ * remainder of the chunk to be a legal prefix and no more.
  */
 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).
+ * Wheel reports set bit 6 of the button field.
+ * The low bit 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.
+ * Motion reports set bit 5.
+ *
+ * In mode 1002, that bit means "moved with a button held" — a drag.
  */
 const MOTION_FLAG = 32
 
@@ -124,8 +108,8 @@ 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.
+ * The longest fragment held for the next chunk (64 KB), bounding an unterminated
+ * string sequence rather than a real key.
  */
 const MAX_PENDING_LENGTH = 65_536
 
@@ -137,9 +121,13 @@ const ARROW_INPUTS: Record<string, MapTUIInput> = {
 }
 
 /**
- * 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.
+ * Single-character bindings taken from mapscii.
+ *
+ * `a` and `z` zoom.
+ * `+` and `-` form the common pair.
+ *
+ * `hjkl` pans like vim.
+ * `y` zooms out beside `z` on QWERTZ keyboards, where QWERTY places `z`.
  */
 const CHARACTER_INPUTS: Record<string, MapTUIInput> = {
 	q: { kind: "quit" },
@@ -158,20 +146,17 @@ const CHARACTER_INPUTS: Record<string, MapTUIInput> = {
 }
 
 /**
- * One decoded chunk: its events, plus whatever trailing bytes could not be decoded YET.
+ * 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.
+	 * An unresolved escape fragment from the end of the chunk to prepend to the next,
+	 * empty when the chunk ended cleanly.
 	 */
 	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
@@ -182,10 +167,6 @@ function consumeUnrecognized(buffer: string, index: number): number | null {
 	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
@@ -196,9 +177,6 @@ function isIncompleteSequence(buffer: string, index: number): boolean {
 	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 }
@@ -212,8 +190,8 @@ function mouseInput(button: number, column: number, row: number, final: string):
 }
 
 /**
- * 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.
+ * Decodes one raw-mode stdin chunk into input events, dropping unrecognized bytes
+ * and returning an unresolved trailing escape fragment as `pending`.
  */
 export function decodeInputChunk(chunk: string, pending = ""): DecodedInput {
 	const events: MapTUIInput[] = []
@@ -272,10 +250,9 @@ export function decodeInputChunk(chunk: string, pending = ""): DecodedInput {
 		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.
+			// An unterminated string sequence could grow the held fragment for the life of the process.
+			// Drop an overlong fragment.
+			// A body flush would make terminal content read as key presses.
 			return { events, pending: fragment.length > MAX_PENDING_LENGTH ? "" : fragment }
 		}
 

package/lib/mercator.ts

@@ -7,22 +7,21 @@
 /**
  * Web-Mercator projection math for map-tui.
  *
- * This module reimplements the standard Web-Mercator projection (EPSG:3857) math locally rather than importing from
- * `@mailwoman/cartographer` or `@mailwoman/spatial`. The cartographer dependency drags maplibre-gl +
- * `@mailwoman/tiger`; spatial drags `@mailwoman/core`'s shipped data. map-tui maintains a dependency-lean surface for
- * the standalone `npx` story (the nuts-lookup precedent).
+ * This module reimplements the standard Web-Mercator projection (epsg:3857) math locally
+ * rather than importing from `@mailwoman/cartographer` or `@mailwoman/spatial`.
+ * The cartographer dependency drags maplibre-gl + `@mailwoman/tiger`;
+ * spatial drags `@mailwoman/core`'s shipped data.
+ *
+ * Map-tui maintains a dependency-lean surface for the standalone `npx` story (the nuts-lookup precedent).
  */
 
+import type { LatLon } from "@mailwoman/spatial"
+
 /**
  * Number of pixels per tile in the Web-Mercator projection (standard: 256).
  */
 export const TILE_SIZE = 256
 
-export interface LonLat {
-	lon: number
-	lat: number
-}
-
 export interface WorldPx {
 	x: number
 	y: number
@@ -38,7 +37,7 @@ export function lonLatToWorldPx(lon: number, lat: number, zoom: number): WorldPx
 	}
 }
 
-export function worldPxToLonLat(x: number, y: number, zoom: number): LonLat {
+export function worldPxToLonLat(x: number, y: number, zoom: number): LatLon {
 	const scale = TILE_SIZE * 2 ** zoom
 	const n = Math.PI * (1 - (2 * y) / scale)
 
@@ -64,8 +63,10 @@ export function wrapLongitude(lon: number): number {
 }
 
 /**
- * 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.
+ * 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
 

package/lib/mvt.ts

@@ -7,8 +7,8 @@
 /**
  * Mapbox Vector Tile (MVT) decoding for map-tui.
  *
- * Wraps @mapbox/vector-tile + pbf behind a plain-data shape (DecodedLayer / DecodedFeature) so the rest of map-tui
- * never touches the upstream library's lazy-geometry classes.
+ * Wraps @mapbox/vector-tile + pbf behind a plain-data shape (DecodedLayer / DecodedFeature)
+ * so the rest of map-tui never touches the upstream library's lazy-geometry classes.
  */
 
 import { VectorTile } from "@mapbox/vector-tile"

package/lib/raster.ts

@@ -5,25 +5,33 @@
  */
 
 /**
- * RGBA pixel rasterizer for map-tui's debug view.
+ * Rgba pixel rasterizer for map-tui's debug view.
  *
- * Rasterizes vector geometry (polylines, filled polygons, circles) onto a plain RGBA byte grid — the shape asciify's
- * rasterize step consumes. Every draw call clips through {@link RGBAGrid.setPixel}, so callers never need to
- * bounds-check geometry themselves. The polyline and circle primitives floor their coordinates to integers on entry;
- * {@link fillPolygon} does not — its scanline edge math keeps ring vertices as given, see its own docstring.
+ * Rasterizes vector geometry (polylines, filled polygons, circles) onto a plain rgba
+ * byte grid — the shape asciify's rasterize step consumes.
+ * Every draw call clips through {@link RGBAGrid.setPixel}, so callers never
+ * need to bounds-check geometry themselves.
+ *
+ * The polyline and circle primitives floor their coordinates to integers on entry;
+ * {@link fillPolygon} does not.
+ * Its scanline edge math keeps ring vertices as given, see its own docstring.
  */
 
 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,
- * which is how callers (including this module's own tests) distinguish "lit" from "background".
+ * A row-major rgba pixel buffer.
+ *
+ * Alpha starts at 0 (unlit/transparent) everywhere.
+ * A drawn pixel has value 255.
+ *
+ * Callers, including this module's own tests, distinguish "lit" from "background".
  */
 export class RGBAGrid {
 	readonly width: number
 	readonly height: number
 	/**
-	 * RGBA, row-major, width * height * 4 bytes — the shape asciify's rasterize consumes.
+	 * Rgba, row-major, width * height * 4 bytes — the shape asciify's rasterize consumes.
 	 */
 	readonly data: Uint8ClampedArray
 
@@ -34,9 +42,12 @@ export class RGBAGrid {
 	}
 
 	/**
-	 * Writes a pixel's RGB channels and sets alpha to fully opaque (255). Coordinates outside the grid are silently
-	 * ignored — this is the one clipping boundary every drawing primitive in this module routes through, so geometry that
-	 * runs off the grid (or arrives with negative/oversized coordinates) never needs special-casing upstream.
+	 * Writes a pixel's RGB channels and sets alpha to fully opaque (255).
+	 *
+	 * Coordinates outside the grid are silently ignored.
+	 * This is the one clipping boundary every drawing primitive in this module routes through,
+	 * so geometry that runs off the grid (or arrives with negative/oversized coordinates)
+	 * never needs special-casing upstream.
 	 */
 	setPixel(x: number, y: number, color: RGB): void {
 		const px = Math.floor(x)
@@ -54,8 +65,9 @@ export class RGBAGrid {
 }
 
 /**
- * Stamps a `width`-sized square centered on (x, y) — used by {@link drawPolyline} for `width > 1`. `width === 1` callers
- * should use `grid.setPixel` directly rather than pay the square-stamp loop.
+ * Stamps a `width`-sized square centered on (x, y) — used by {@link drawPolyline} for `width > 1`.
+ *
+ * `width === 1` callers should use `grid.setPixel` directly rather than pay the square-stamp loop.
  */
 function stampSquare(grid: RGBAGrid, x: number, y: number, color: RGB, width: number): void {
 	const half = Math.floor(width / 2)
@@ -68,8 +80,11 @@ function stampSquare(grid: RGBAGrid, x: number, y: number, color: RGB, width: nu
 }
 
 /**
- * Draws a single line segment with the integer Bresenham algorithm. Coordinates are floored on entry; every plotted
- * point routes through `grid.setPixel`, so segments that run partly or fully off-grid clip for free.
+ * Draws a single line segment with the integer Bresenham algorithm.
+ *
+ * Coordinates are floored on entry.
+ * Every plotted point routes through `grid.setPixel`, so segments that run partly
+ * or fully off-grid clip for free.
  */
 function drawSegment(grid: RGBAGrid, x0: number, y0: number, x1: number, y1: number, color: RGB, width: number): void {
 	let x = Math.floor(x0)
@@ -107,9 +122,11 @@ function drawSegment(grid: RGBAGrid, x0: number, y0: number, x1: number, y1: num
 }
 
 /**
- * Draws a connected polyline through `points`, one Bresenham segment per consecutive pair. `width > 1` stamps a
- * `width`-sized square at every plotted step instead of a single pixel, thickening the line. Segments that run outside
- * the grid clip through `setPixel` rather than throwing.
+ * Draws a connected polyline through `points`, one Bresenham segment per consecutive pair.
+ *
+ * `width > 1` stamps a `width`-sized square at every plotted step instead of
+ * a single pixel, thickening the line.
+ * Segments that run outside the grid clip through `setPixel` rather than throwing.
  */
 export function drawPolyline(
 	grid: RGBAGrid,
@@ -126,12 +143,18 @@ export function drawPolyline(
 }
 
 /**
- * Fills one or more polygon rings with the even-odd rule: a pixel is interior when a ray from it crosses an odd number
- * of ring edges. Rings after the first behave as holes wherever they overlap the first ring, and holes nested inside
- * holes fill again, purely as a consequence of the parity count — no explicit hole/outer distinction is tracked.
- * Scanlines sample row centers (`y + 0.5`) rather than integer row coordinates, which is what keeps horizontal edges
- * and grid-aligned polygon boundaries from producing degenerate (zero-width or doubled) intersections. Coordinates are
- * floored to the grid via `setPixel`; edge math itself uses the ring vertices as given.
+ * Fills one or more polygon rings with the even-odd rule: a pixel is interior
+ * when a ray from it crosses an odd number of ring edges.
+ *
+ * Rings after the first behave as holes wherever they overlap the first ring.
+ * Holes nested inside holes fill again as a consequence of the parity count.
+ * No explicit hole/outer distinction is tracked.
+ *
+ * Scanlines sample row centers (`y + 0.5`) rather than integer row coordinates.
+ * This keeps horizontal edges and grid-aligned polygon boundaries from producing
+ * degenerate (zero-width or doubled) intersections.
+ *
+ * Coordinates are floored to the grid via `setPixel`; edge math itself uses the ring vertices as given.
  */
 export function fillPolygon(
 	grid: RGBAGrid,
@@ -174,9 +197,12 @@ export function fillPolygon(
 }
 
 /**
- * Draws a circle's outline (ring, not a filled disc) with the midpoint circle algorithm, plotting all eight symmetric
- * octant points per step. `centerX`/`centerY`/`radius` are floored on entry; every plotted point routes through
- * `setPixel`, so a circle that runs off the grid clips rather than throwing.
+ * Draws a circle's outline (ring rather than a filled disc) with the midpoint circle
+ * algorithm, plotting all eight symmetric octant points per step.
+ *
+ * `centerX`/`centerY`/`radius` are floored on entry.
+ * Every plotted point routes through `setPixel`, so a circle that runs off
+ * the grid clips rather than throwing.
  */
 export function drawCircle(grid: RGBAGrid, centerX: number, centerY: number, radius: number, color: RGB): void {
 	const cx = Math.floor(centerX)