@mailwoman/map-tui 9.1.0 → 9.2.0

package/cli-args.ts

@@ -0,0 +1,232 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+/**
+ * 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.
+ */
+
+import { parseArgs } from "node:util"
+
+/**
+ * Center longitude when `--lon` is omitted — the world view mapscii opens on.
+ */
+const DEFAULT_LON = 0
+
+/**
+ * Center latitude when `--lat` is omitted.
+ */
+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.
+ */
+const DEFAULT_ZOOM = 2
+
+/**
+ * Widest zoom any tile archive uses.
+ */
+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.
+ */
+const MAX_ZOOM = 24
+
+const MIN_LAT = -90
+const MAX_LAT = 90
+const MIN_LON = -180
+const MAX_LON = 180
+
+/**
+ * A view request: an archive to read and where to open it.
+ */
+export interface BrowseArgs {
+	mode: "browse"
+	/**
+	 * Path to the PMTiles archive.
+	 */
+	tiles: string
+	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.
+	 */
+	zoom: number
+}
+
+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.
+ */
+export class CLIArgsError extends Error {
+	override name = "CLIArgsError"
+}
+
+/**
+ * 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.
+ */
+export const HELP_TEXT = `map-tui — the whole world in your terminal
+
+Usage
+  npx @mailwoman/map-tui --tiles <archive.pmtiles> [options]
+
+Options
+  --tiles <path|url>  PMTiles archive — local path or https:// URL (default: $MAILWOMAN_TILES)
+  --lat <degrees>   Initial center latitude, -90..90 (default: ${DEFAULT_LAT})
+  --lon <degrees>   Initial center longitude, -180..180 (default: ${DEFAULT_LON})
+  --zoom <level>    Initial zoom, ${MIN_ZOOM}..${MAX_ZOOM} (default: ${DEFAULT_ZOOM})
+  -h, --help        Print this help and exit
+  -v, --version     Print the package version and exit
+
+Keys
+  arrows, hjkl      Pan
+  +, =, a           Zoom in
+  -, _, z           Zoom out
+  q, Esc, Ctrl+C    Quit
+
+Mouse
+  Wheel zooms toward the pointer, drag pans, click centers.
+
+Tiles are never bundled with this package. Download a planet or region
+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.
+ */
+function numericFlag(name: string, raw: string | undefined, fallback: number, min: number, max: number): number {
+	if (raw == null) return fallback
+
+	const value = Number(raw.trim())
+
+	if (!Number.isFinite(value) || !raw.trim().length) {
+		throw new CLIArgsError(`--${name} expects a number, got ${JSON.stringify(raw)}`)
+	}
+
+	if (value < min || value > max) {
+		throw new CLIArgsError(`--${name} must be between ${min} and ${max}, got ${value}`)
+	}
+
+	return value
+}
+
+/**
+ * Flags whose value is a number, and may therefore 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.
+ */
+function joinNegativeNumbers(argv: readonly string[]): string[] {
+	const joined: string[] = []
+
+	for (let index = 0; index < argv.length; index++) {
+		const token = argv[index]!
+		const next = argv[index + 1]
+
+		if (NUMERIC_FLAGS.has(token) && next?.startsWith("-") && Number.isFinite(Number(next))) {
+			joined.push(`${token}=${next}`)
+			index += 1
+
+			continue
+		}
+
+		joined.push(token)
+	}
+
+	return joined
+}
+
+interface ParsedFlags {
+	tiles?: string | undefined
+	lat?: string | undefined
+	lon?: string | undefined
+	zoom?: string | undefined
+	help?: boolean | undefined
+	version?: boolean | undefined
+}
+
+/**
+ * `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`.
+ */
+function readFlags(argv: readonly string[]): ParsedFlags {
+	try {
+		const { values } = parseArgs({
+			args: joinNegativeNumbers(argv),
+			options: {
+				tiles: { type: "string" },
+				lat: { type: "string" },
+				lon: { type: "string" },
+				zoom: { type: "string" },
+				help: { type: "boolean", short: "h" },
+				version: { type: "boolean", short: "v" },
+			},
+			allowPositionals: false,
+			strict: true,
+		})
+
+		return values
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error)
+
+		throw new CLIArgsError(`${detail}\nRun \`map-tui --help\` for the supported flags.`)
+	}
+}
+
+/**
+ * Parses a `map-tui` command line.
+ *
+ * @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)
+
+	if (values.help) return { mode: "help" }
+
+	if (values.version) return { mode: "version" }
+
+	const tiles = (values.tiles ?? environment.MAILWOMAN_TILES ?? "").trim()
+
+	if (!tiles.length) {
+		throw new CLIArgsError(
+			"No tile archive: pass --tiles <archive.pmtiles> or set MAILWOMAN_TILES.\n" +
+				"Planet and region archives: https://protomaps.com/downloads"
+		)
+	}
+
+	return {
+		mode: "browse",
+		tiles,
+		lat: numericFlag("lat", values.lat, DEFAULT_LAT, MIN_LAT, MAX_LAT),
+		lon: numericFlag("lon", values.lon, DEFAULT_LON, MIN_LON, MAX_LON),
+		zoom: Math.round(numericFlag("zoom", values.zoom, DEFAULT_ZOOM, MIN_ZOOM, MAX_ZOOM)),
+	}
+}

package/cli.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+/**
+ * The `map-tui` bin — `npx @mailwoman/map-tui` opens a PMTiles archive as a full-screen terminal map.
+ *
+ * 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.
+ */
+
+import { createRequire } from "node:module"
+
+import { MapBrowser } from "./browser.ts"
+import { type CLIArgs, CLIArgsError, HELP_TEXT, parseCLIArgs } from "./cli-args.ts"
+import { TileSource } from "./tile-source.ts"
+
+/**
+ * Exit code for a command line that could not be parsed.
+ */
+const EXIT_USAGE = 1
+
+/**
+ * Reads the package's own 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.
+ */
+function readVersion(): string {
+	const require = createRequire(import.meta.url)
+	const manifest = require("@mailwoman/map-tui/package.json") as { version?: string }
+
+	return manifest.version ?? "0.0.0"
+}
+
+/**
+ * Opens the archive, translating the filesystem's error into something that names the flag that was wrong.
+ */
+async function openTiles(path: string): Promise<TileSource> {
+	try {
+		return await TileSource.open(path)
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error)
+
+		throw new CLIArgsError(
+			`Could not open the tile archive at ${path}: ${detail}\n` +
+				"Pass --tiles <archive.pmtiles>, or download one from https://protomaps.com/downloads"
+		)
+	}
+}
+
+/**
+ * Runs the interactive browser against an already-open archive, resolving with its exit code.
+ */
+async function browse(source: TileSource, args: { lat: number; lon: number; zoom: number }): Promise<number> {
+	const browser = new MapBrowser({
+		source,
+		input: process.stdin,
+		output: process.stdout,
+		lat: args.lat,
+		lon: args.lon,
+		zoom: args.zoom,
+	})
+
+	const onSignal = (): void => browser.requestExit(130)
+	const onExit = (): void => browser.restore()
+
+	process.on("SIGINT", onSignal)
+	process.on("SIGTERM", onSignal)
+	process.on("exit", onExit)
+
+	try {
+		return await browser.run()
+	} finally {
+		browser.restore()
+		process.off("SIGINT", onSignal)
+		process.off("SIGTERM", onSignal)
+		process.off("exit", onExit)
+	}
+}
+
+async function main(): Promise<number> {
+	let args: CLIArgs
+
+	try {
+		/**
+		 * This package takes no `@mailwoman` dependency by design (see ./mercator.ts), so the blessed readers are out of
+		 * reach: `@mailwoman/core/env` would pull core's shipped data behind a CLI whose whole premise is `npx`.
+		 * `parseCLIArgs` is the local equivalent — argv and the environment are read on this one line, and nowhere else in
+		 * the package.
+		 */
+		// oxlint-disable-next-line sister-software/no-process-globals -- see above.
+		args = parseCLIArgs(process.argv.slice(2), process.env)
+	} catch (error) {
+		if (!(error instanceof CLIArgsError)) throw error
+
+		process.stderr.write(`${error.message}\n`)
+
+		return EXIT_USAGE
+	}
+
+	if (args.mode === "help") {
+		process.stdout.write(HELP_TEXT)
+
+		return 0
+	}
+
+	if (args.mode === "version") {
+		process.stdout.write(`${readVersion()}\n`)
+
+		return 0
+	}
+
+	let source: TileSource
+
+	try {
+		source = await openTiles(args.tiles)
+	} catch (error) {
+		process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`)
+
+		return EXIT_USAGE
+	}
+
+	try {
+		return await browse(source, args)
+	} finally {
+		await source.close()
+	}
+}
+
+process.exitCode = await main()

package/frame.ts

@@ -11,7 +11,7 @@
  * 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.
+ * further asciify dependency; `blitFrame` is the seam back the other way, for callers driving a live terminal.
  */
 
 import { AsciifyTerminal } from "@sister.software/asciify/tui"
@@ -168,3 +168,32 @@ export function overlayText(
 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.
+ */
+const SPACE_CODEPOINT = 0x20
+
+/**
+ * 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. 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++) {
+		for (let column = 0; column < frame.columns; column++) {
+			const cellIndex = row * frame.columns + column
+			const char = frame.chars[cellIndex]!
+			const color = frame.colors[cellIndex]!
+
+			terminal.setCell(column, row, char === 0 ? SPACE_CODEPOINT : char, [
+				(color >> 16) & 0xff,
+				(color >> 8) & 0xff,
+				color & 0xff,
+			])
+		}
+	}
+}

package/input.ts

@@ -0,0 +1,288 @@
+/**
+ * @copyright Sister Software.
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+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.
+ */
+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.
+	 */
+	| { kind: "interrupt" }
+	| { kind: "pan"; dx: number; dy: number }
+	| { kind: "zoom"; delta: number }
+	| { kind: "wheel"; delta: number; column: number; row: number }
+	| { kind: "press"; column: number; row: number }
+	| { kind: "drag"; column: number; row: number }
+	| { kind: "release" }
+
+const ESC = "\u001B"
+const CTRL_C = "\u0003"
+
+/* oxlint-disable no-control-regex -- ESC (U+001B) is the byte every pattern below exists to match. A decoder of
+   terminal escape sequences cannot avoid the control character the sequences are made of. */
+
+/**
+ * SGR mouse report: `ESC [ < button ; column ; row (M|m)`, where `M` is a press/motion and `m` a release.
+ */
+const MOUSE_SGR_PATTERN = /\u001B\[<(\d+);(\d+);(\d+)([Mm])/y
+
+/**
+ * Cursor keys, in both normal (`ESC [ A`) and application (`ESC O A`) modes — a terminal may be left in either.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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).
+ */
+const WHEEL_FLAG = 64
+
+/**
+ * Motion reports set bit 5. With mode 1002 that means "moved with a button held" — a drag.
+ */
+const MOTION_FLAG = 32
+
+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.
+ */
+const MAX_PENDING_LENGTH = 65_536
+
+const ARROW_INPUTS: Record<string, MapTUIInput> = {
+	A: { kind: "pan", dx: 0, dy: -1 },
+	B: { kind: "pan", dx: 0, dy: 1 },
+	C: { kind: "pan", dx: 1, dy: 0 },
+	D: { kind: "pan", dx: -1, dy: 0 },
+}
+
+/**
+ * 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.
+ */
+const CHARACTER_INPUTS: Record<string, MapTUIInput> = {
+	q: { kind: "quit" },
+	Q: { kind: "quit" },
+	"+": { kind: "zoom", delta: 1 },
+	"=": { kind: "zoom", delta: 1 },
+	a: { kind: "zoom", delta: 1 },
+	"-": { kind: "zoom", delta: -1 },
+	_: { kind: "zoom", delta: -1 },
+	z: { kind: "zoom", delta: -1 },
+	y: { kind: "zoom", delta: -1 },
+	h: { kind: "pan", dx: -1, dy: 0 },
+	j: { kind: "pan", dx: 0, dy: 1 },
+	k: { kind: "pan", dx: 0, dy: -1 },
+	l: { kind: "pan", dx: 1, dy: 0 },
+}
+
+/**
+ * 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.
+	 */
+	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
+
+		if (pattern.exec(buffer)) return pattern.lastIndex
+	}
+
+	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
+
+		if (pattern.exec(buffer)) return true
+	}
+
+	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 }
+	}
+
+	if (final === "m") return { kind: "release" }
+
+	if ((button & BUTTON_MASK) !== LEFT_BUTTON) return null
+
+	return button & MOTION_FLAG ? { kind: "drag", column, row } : { kind: "press", column, row }
+}
+
+/**
+ * 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.
+ */
+export function decodeInputChunk(chunk: string, pending = ""): DecodedInput {
+	const events: MapTUIInput[] = []
+	const buffer = pending + chunk
+	let index = 0
+
+	while (index < buffer.length) {
+		const character = buffer[index]!
+
+		if (character !== ESC) {
+			const input = character === CTRL_C ? { kind: "interrupt" as const } : CHARACTER_INPUTS[character]
+
+			if (input) {
+				events.push(input)
+			}
+
+			index += 1
+
+			continue
+		}
+
+		MOUSE_SGR_PATTERN.lastIndex = index
+		const mouse = MOUSE_SGR_PATTERN.exec(buffer)
+
+		if (mouse) {
+			const input = mouseInput(Number(mouse[1]), Number(mouse[2]) - 1, Number(mouse[3]) - 1, mouse[4]!)
+
+			if (input) {
+				events.push(input)
+			}
+
+			index = MOUSE_SGR_PATTERN.lastIndex
+
+			continue
+		}
+
+		ARROW_PATTERN.lastIndex = index
+		const arrow = ARROW_PATTERN.exec(buffer)
+
+		if (arrow) {
+			events.push(ARROW_INPUTS[arrow[1]!]!)
+			index = ARROW_PATTERN.lastIndex
+
+			continue
+		}
+
+		const consumed = consumeUnrecognized(buffer, index)
+
+		if (consumed !== null) {
+			index = consumed
+
+			continue
+		}
+
+		// The buffer stops inside a sequence — hand the fragment back instead of guessing at it.
+		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.
+			return { events, pending: fragment.length > MAX_PENDING_LENGTH ? "" : fragment }
+		}
+
+		// An ESC whose next byte cannot continue a sequence: the Esc KEY.
+		events.push({ kind: "quit" })
+		index += 1
+	}
+
+	return { events, pending: "" }
+}