@hraness/dawg 0.4.1 → 0.5.0

package/tui/guide.ts

@@ -0,0 +1,351 @@
+/**
+ * The `/guide` pane: the user guides (`guides/*.md`) as a tree that opens a
+ * guide into a page. Pure: keys go in, rows come out; `tui/app.ts` paints.
+ *
+ *   tree   ↑↓ (j k) move · → l enter expand, then open · ← h collapse or
+ *          go to the parent · / filter (title and text) · esc back
+ *   page   ↑↓ (j k) scroll · pgup pgdn home end · ← h esc back to the tree
+ */
+import type { Guide } from "../guides/index.ts";
+import { overlayKey } from "./keys.ts";
+import { displayWidth } from "./text.ts";
+
+export type GuideRow = Readonly<{
+  text: string;
+  /** The highlighted tree row. */
+  selected?: boolean;
+  /** A `##` heading in a page. */
+  heading?: boolean;
+  /** Secondary text (a filter line, an empty result). */
+  muted?: boolean;
+}>;
+
+export type GuideView = Readonly<{
+  title: string;
+  rows: readonly GuideRow[];
+  /** First row shown and the total, for a page longer than the pane. */
+  scroll: number;
+  hint: string;
+}>;
+
+export const GUIDE_HINTS = {
+  tree: " ↑↓ move · → open · ← close · / filter · esc back · ? keys ",
+  filtering: " type to filter · enter open · esc clear · ? keys ",
+  page: " ↑↓ scroll · ← back · esc back · ? keys ",
+} as const;
+
+/**
+ * `## Ask` → `── Ask`, `- x` → `• x`, code spans lose their backticks. The
+ * blank line Markdown wants after a heading is dropped: in a pane the rule
+ * already separates it.
+ */
+export function guideLines(body: string, unicode = true): GuideRow[] {
+  const lines = body
+    .split("\n")
+    .filter(
+      (line, index, all) =>
+        line.trim() !== "" || !/^#{1,6}\s/.test(all[index - 1] ?? ""),
+    );
+  return lines.map((line) => {
+    const heading = line.match(/^#{1,6}\s+(.*)$/);
+    if (heading)
+      return { text: `${unicode ? "──" : "--"} ${heading[1]}`, heading: true };
+    const plain = line.replace(/`([^`]*)`/g, "$1");
+    return { text: plain.replace(/^- /, unicode ? "• " : "- ") };
+  });
+}
+
+/** Word-wrap rows to `width` columns; continuation lines indent under bullets. */
+export function wrapRows(rows: readonly GuideRow[], width: number): GuideRow[] {
+  const out: GuideRow[] = [];
+  for (const row of rows) {
+    if (displayWidth(row.text) <= width || width < 10) {
+      out.push(row);
+      continue;
+    }
+    const indent = /^[•-] /.test(row.text) ? "  " : "";
+    let line = "";
+    for (const word of row.text.split(" ")) {
+      const next = line ? `${line} ${word}` : word;
+      if (line && displayWidth(next) > width) {
+        out.push({ ...row, text: line });
+        line = indent + word;
+      } else line = next;
+    }
+    if (line) out.push({ ...row, text: line });
+  }
+  return out;
+}
+
+export class GuideBrowser {
+  readonly guides: readonly Guide[];
+  /** Expanded parents in the tree. */
+  readonly expanded = new Set<string>();
+  /** Highlighted guide id in the tree. */
+  selected: string;
+  query = "";
+  filtering = false;
+  /** The guide open as a page, or undefined in the tree. */
+  page: string | undefined;
+  scroll = 0;
+
+  constructor(guides: readonly Guide[], open?: string) {
+    this.guides = guides;
+    this.selected = guides[0]?.id ?? "";
+    if (open) this.open(open);
+  }
+
+  /** Open a guide by id or title word (`/guide chords`); false if unknown. */
+  open(name: string): boolean {
+    const word = name.trim().toLowerCase();
+    const guide =
+      this.guides.find((g) => g.id === word) ??
+      this.guides.find((g) => g.title.toLowerCase().startsWith(word)) ??
+      this.guides.find((g) => g.id.includes(word));
+    if (!guide) return false;
+    for (let p = guide.parent; p; p = this.byId(p)?.parent)
+      this.expanded.add(p);
+    this.selected = guide.id;
+    this.page = guide.id;
+    this.scroll = 0;
+    return true;
+  }
+
+  get typing(): boolean {
+    return this.page === undefined && this.filtering;
+  }
+
+  private byId(id: string): Guide | undefined {
+    return this.guides.find((g) => g.id === id);
+  }
+
+  private children(id: string | undefined): Guide[] {
+    return this.guides.filter((g) => g.parent === id);
+  }
+
+  /** Guides matching the filter, plus their ancestors; all when no filter. */
+  private matches(): Set<string> | undefined {
+    const query = this.query.trim().toLowerCase();
+    if (!query) return undefined;
+    const keep = new Set<string>();
+    for (const guide of this.guides) {
+      const text = `${guide.title}\n${guide.body}`.toLowerCase();
+      if (!text.includes(query)) continue;
+      for (let g: Guide | undefined = guide; g; g = this.byId(g.parent ?? ""))
+        keep.add(g.id);
+    }
+    return keep;
+  }
+
+  /** The tree rows shown now, in order, with their depth. */
+  visible(): { guide: Guide; depth: number }[] {
+    const keep = this.matches();
+    const out: { guide: Guide; depth: number }[] = [];
+    const visit = (parent: string | undefined, depth: number) => {
+      for (const guide of this.children(parent)) {
+        if (keep && !keep.has(guide.id)) continue;
+        out.push({ guide, depth });
+        if (keep || this.expanded.has(guide.id)) visit(guide.id, depth + 1);
+      }
+    };
+    visit(undefined, 0);
+    return out;
+  }
+
+  private move(step: number): void {
+    const rows = this.visible();
+    if (rows.length === 0) return;
+    const at = Math.max(
+      0,
+      rows.findIndex((row) => row.guide.id === this.selected),
+    );
+    const next = Math.max(0, Math.min(rows.length - 1, at + step));
+    this.selected = rows[next]!.guide.id;
+  }
+
+  /** Keep the selection on a visible row after the filter changes. */
+  private settle(): void {
+    const rows = this.visible();
+    if (!rows.some((row) => row.guide.id === this.selected))
+      this.selected = rows[0]?.guide.id ?? this.selected;
+  }
+
+  private openSelected(): void {
+    if (this.visible().some((row) => row.guide.id === this.selected)) {
+      this.page = this.selected;
+      this.scroll = 0;
+    }
+  }
+
+  /**
+   * One key. `close` means Esc at the top level; `handled` that it changed
+   * (or deliberately swallowed) something; `ignored` that it was not ours.
+   * `pageRows` is the page height, for pgup/pgdn and clamping.
+   */
+  key(value: string, pageRows = 10): "handled" | "close" | "ignored" {
+    const nav = overlayKey(value);
+    const left = value === "\u001b[D" || value === "\u001bOD";
+    const right = value === "\u001b[C" || value === "\u001bOC";
+    const esc = value === "\u001b";
+    if (this.page !== undefined) {
+      const total = this.pageLength();
+      const max = Math.max(0, total - pageRows);
+      const step =
+        nav === "down" || value === "j"
+          ? 1
+          : nav === "up" || value === "k"
+            ? -1
+            : nav === "pgdn" || value === " "
+              ? pageRows
+              : nav === "pgup"
+                ? -pageRows
+                : nav === "home"
+                  ? -total
+                  : nav === "end"
+                    ? total
+                    : 0;
+      if (step !== 0) {
+        this.scroll = Math.max(0, Math.min(max, this.scroll + step));
+        return "handled";
+      }
+      if (esc || left || value === "h" || value === "\u007f") {
+        this.page = undefined;
+        this.scroll = 0;
+        return "handled";
+      }
+      return "handled";
+    }
+    if (this.filtering) {
+      if (esc) {
+        this.query = "";
+        this.filtering = false;
+        this.settle();
+        return "handled";
+      }
+      if (value === "\u007f" || value === "\b") {
+        this.query = this.query.slice(0, -1);
+        if (!this.query) this.filtering = false;
+        this.settle();
+        return "handled";
+      }
+      if (nav === "enter") {
+        this.filtering = false;
+        this.openSelected();
+        return "handled";
+      }
+      if (nav === "up" || nav === "down") {
+        this.filtering = false;
+        this.move(nav === "up" ? -1 : 1);
+        return "handled";
+      }
+      if (!value.startsWith("\u001b") && value >= " " && value.length <= 4) {
+        this.query = (this.query + value).slice(0, 40);
+        this.settle();
+        return "handled";
+      }
+      return "handled";
+    }
+    if (nav === "up" || value === "k") return this.moved(-1);
+    if (nav === "down" || value === "j") return this.moved(1);
+    if (nav === "pgup") return this.moved(-pageRows);
+    if (nav === "pgdn") return this.moved(pageRows);
+    if (nav === "home") return this.moved(-this.guides.length);
+    if (nav === "end") return this.moved(this.guides.length);
+    if (value === "/") {
+      this.filtering = true;
+      return "handled";
+    }
+    const hasChildren = this.children(this.selected).length > 0;
+    const open = this.query !== "" || this.expanded.has(this.selected);
+    if (right || value === "l" || nav === "enter") {
+      if (hasChildren && !open) this.expanded.add(this.selected);
+      else this.openSelected();
+      return "handled";
+    }
+    if (left || value === "h") {
+      if (hasChildren && this.expanded.has(this.selected) && !this.query)
+        this.expanded.delete(this.selected);
+      else {
+        const parent = this.byId(this.selected)?.parent;
+        if (parent) this.selected = parent;
+      }
+      return "handled";
+    }
+    if (esc) {
+      if (this.query) {
+        this.query = "";
+        this.settle();
+        return "handled";
+      }
+      return "close";
+    }
+    return "ignored";
+  }
+
+  private moved(step: number): "handled" {
+    this.move(step);
+    return "handled";
+  }
+
+  private pageWidth = 72;
+
+  private pageLength(): number {
+    const guide = this.byId(this.page ?? "");
+    return guide ? wrapRows(guideLines(guide.body), this.pageWidth).length : 0;
+  }
+
+  /** What to paint in a pane `width` columns wide and `height` rows tall. */
+  view(width: number, height: number, unicode = true): GuideView {
+    this.pageWidth = width;
+    const page = this.page === undefined ? undefined : this.byId(this.page);
+    if (page) {
+      const rows = wrapRows(guideLines(page.body, unicode), width);
+      const max = Math.max(0, rows.length - height);
+      this.scroll = Math.max(0, Math.min(max, this.scroll));
+      const crumb = page.parent ? `${this.byId(page.parent)?.title} › ` : "";
+      return {
+        title: `guide · ${crumb}${page.title}`.replace(
+          "›",
+          unicode ? "›" : ">",
+        ),
+        rows: rows.slice(this.scroll, this.scroll + height),
+        scroll: this.scroll,
+        hint: GUIDE_HINTS.page,
+      };
+    }
+    const visible = this.visible();
+    const rows: GuideRow[] = visible.map(({ guide, depth }) => {
+      const parent = this.children(guide.id).length > 0;
+      const open = this.query !== "" || this.expanded.has(guide.id);
+      const marker = parent
+        ? open
+          ? unicode
+            ? "▾"
+            : "v"
+          : unicode
+            ? "▸"
+            : ">"
+        : " ";
+      return {
+        text: `${"  ".repeat(depth)}${marker} ${guide.title}`,
+        selected: guide.id === this.selected,
+      };
+    });
+    if (rows.length === 0) rows.push({ text: "no guide matches", muted: true });
+    const filter = this.filtering || this.query;
+    if (filter)
+      rows.unshift({
+        text: `/ ${this.query}${this.filtering ? "_" : ""}`,
+        muted: true,
+      });
+    const body = Math.max(1, height);
+    const at = rows.findIndex((row) => row.selected);
+    const scroll = Math.max(0, Math.min(rows.length - body, at - body + 2));
+    return {
+      title: "guide",
+      rows: rows.slice(scroll, scroll + body),
+      scroll,
+      hint: this.filtering ? GUIDE_HINTS.filtering : GUIDE_HINTS.tree,
+    };
+  }
+}

package/tui/highway.ts

@@ -34,6 +34,16 @@ export interface NoteSnapshot {
   selected?: boolean | undefined;
   pending?: boolean | undefined;
   muted?: boolean | undefined;
+  /**
+   * Cents the note sounds away from the nearest 12-TET pitch (tuning plus note
+   * cents). Drawn as a compact `+14`/`−32` tag beside the approaching head.
+   */
+  cents?: number | undefined;
+  /**
+   * In a linear non-12 tuning, the 12-TET pitch class `cents` is measured
+   * from (`D` for a `D−47` tag), since the lane is the key, not the sound.
+   */
+  centsFrom?: string | undefined;
 }
 
 export interface TrackScoreSnapshot {
@@ -45,6 +55,11 @@ export interface TrackScoreSnapshot {
   bpm?: number | undefined;
   key?: string | undefined;
   beatsPerBar?: number | undefined;
+  /**
+   * Bar starts in beats within the loop when the meter changes (bar 1 at
+   * 0); omitted, bars repeat every `beatsPerBar` beats.
+   */
+  barBeats?: readonly number[] | undefined;
   loopBeats?: number | undefined;
   laneCount?: number | undefined;
   /** Optional lane legend (drum voices) drawn just below the hit line. */
@@ -53,6 +68,11 @@ export interface TrackScoreSnapshot {
   projection?: LaneProjection | undefined;
   /** Static transport position when the score is paused. */
   transportBeat?: number | undefined;
+  /**
+   * Steps per period and degree-0 key of a linear non-12 tuning; lane labels
+   * then mark each period from the root instead of every C.
+   */
+  tuningPeriod?: { size: number; root: number } | undefined;
   /** Alias accepted by adapters that call this value currentBeat. */
   currentBeat?: number | undefined;
   transportStartedAtMs?: number | undefined;
@@ -128,6 +148,21 @@ const NOTE_NAMES = [
   "B",
 ];
 
+/**
+ * `+14`/`−32` for a cents deviation, empty within ±1 cent; with `from` (a
+ * linear non-12 tuning) the pitch class leads: `D−47`, or `C` alone.
+ */
+export function centsTag(cents: number | undefined, from?: string): string {
+  const rounded = Math.round(cents ?? 0);
+  const value =
+    Math.abs(rounded) < 1 || !Number.isFinite(rounded)
+      ? ""
+      : rounded > 0
+        ? `+${rounded}`
+        : `−${-rounded}`;
+  return from ? `${from}${value}` : value;
+}
+
 export function pitchName(pitch: number): string {
   const rounded = Math.round(pitch);
   return `${NOTE_NAMES[((rounded % 12) + 12) % 12]}${Math.floor(rounded / 12) - 1}`;
@@ -140,6 +175,7 @@ export function pitchName(pitch: number): string {
 export function pitchProjection(
   notes: readonly NoteSnapshot[],
   minimumSpan = 12,
+  period?: { size: number; root: number },
 ): LaneProjection {
   const pitches = notes
     .map((note) => note.pitch)
@@ -164,6 +200,16 @@ export function pitchProjection(
     },
     label(lane) {
       const pitch = low + lane;
+      if (period) {
+        // Mark each period from the root, named as the root plus octaves.
+        const offset = pitch - period.root;
+        if (offset % period.size !== 0) return undefined;
+        const octaves = offset / period.size;
+        return pitchName(period.root).replace(
+          /-?\d+$/,
+          String(Math.floor(period.root / 12) - 1 + octaves),
+        );
+      }
       return pitch % 12 === 0 ? pitchName(pitch) : undefined;
     },
   };
@@ -187,6 +233,8 @@ export function projectionFor(score: TrackScoreSnapshot): LaneProjection {
     .flatMap((layer) => layer.notes);
   return pitchProjection(
     melodic.length ? [...score.notes, ...melodic] : score.notes,
+    12,
+    score.tuningPeriod,
   );
 }
 
@@ -480,15 +528,36 @@ export function paintHighway(
     !(score.layers ?? []).some((layer) => layer.notes.length > 0);
 
   // Beat, bar, and loop rules of increasing strength.
+  const barBeats =
+    score.barBeats && score.barBeats.length > 0 ? score.barBeats : undefined;
   for (let row = 0; row <= lastNoteRow; row += 1) {
     if (row === hitRow) continue;
     const center = rowBeat(row);
     const half = 0.5 / rowsPerBeat;
-    const k = Math.ceil(center - half - 1e-9);
+    let k = Math.ceil(center - half - 1e-9);
+    // Meter changes: a bar may start between beats (7/8), so the row's
+    // bar start wins over the whole beat.
+    let barIndex: number | undefined;
+    if (barBeats) {
+      const base = loop ? Math.floor((center - half) / loop) * loop : 0;
+      for (const offset of loop ? [base, base + loop] : [0]) {
+        const found = barBeats.findIndex((start) => {
+          const at = offset + start;
+          return at >= center - half - 1e-9 && at < center + half - 1e-9;
+        });
+        if (found >= 0) {
+          barIndex = found;
+          k = offset + barBeats[found]!;
+          break;
+        }
+      }
+    }
     if (k > center + half - 1e-9 || k < 0) continue;
     const inLoop = loop ? ((k % loop) + loop) % loop : k;
     const isLoop = loop !== undefined && Math.abs(inLoop) < 1e-9;
-    const isBar = Math.abs(inLoop % beatsPerBar) < 1e-9;
+    const isBar = barBeats
+      ? barIndex !== undefined
+      : Math.abs(inLoop % beatsPerBar) < 1e-9;
     const glyph = isLoop
       ? glyphs.loopRule
       : isBar
@@ -506,7 +575,11 @@ export function paintHighway(
     if (gutter > 0 && (isBar || isLoop) && !empty) {
       const label = isLoop
         ? glyphs.loop
-        : String(Math.floor(inLoop / beatsPerBar) + 1);
+        : String(
+            barIndex !== undefined
+              ? barIndex + 1
+              : Math.floor(inLoop / beatsPerBar) + 1,
+          );
       const text = label.slice(-(gutter - 1)).padStart(gutter - 1, " ");
       for (let index = 0; index < text.length; index += 1)
         painter.put(
@@ -760,7 +833,17 @@ export function paintHighway(
           : glow > 0.6
             ? { ...shade(base, 0.45 * glow), bold: true }
             : shade(base, 0.45 * glow);
-        if (headRow <= hitRow - 1) tile(headRow, headGlyph, style);
+        if (headRow <= hitRow - 1) {
+          tile(headRow, headGlyph, style);
+          const tag =
+            (note.cents !== undefined || note.centsFrom !== undefined) &&
+            !note.muted
+              ? centsTag(note.cents, note.centsFrom)
+              : "";
+          if (tag && x + width + tag.length <= region.width)
+            for (let index = 0; index < tag.length; index += 1)
+              painter.put(x + width + index, headRow, tag[index]!, roles.muted);
+        }
         // The target on the hit line lights up as the note approaches.
         if (!note.muted && glow > 0 && width > 0) {
           for (let offset = 0; offset < width; offset += 1)

package/tui/hits.ts

@@ -0,0 +1,68 @@
+/**
+ * Click targets, recorded by the same paint code that draws them: every
+ * frame rebuilds the list, so hit-testing can never drift from the screen.
+ * Later regions sit on top (an overlay paints after what it covers).
+ */
+
+export type HitTarget =
+  /** A row of the open picker (or the menu), by index into its items. */
+  | { kind: "picker-row"; index: number }
+  /** The header's transport pill (play / pause). */
+  | { kind: "transport" }
+  /** The header's track name (the track list). */
+  | { kind: "tracks" }
+  /** The header's model pill (`/model`). */
+  | { kind: "model" }
+  /** A fader's step buttons, by field index in the drawer. */
+  | { kind: "fader-step"; field: number; direction: 1 | -1 }
+  /** A fader bar: `x` columns from `left` map onto min…max. */
+  | { kind: "fader-bar"; field: number; left: number; width: number }
+  /** A fader's row (label and value): focuses that field. */
+  | { kind: "fader-row"; field: number }
+  /** One option of a choice field. */
+  | { kind: "fader-option"; field: number; option: number }
+  /** The drawer's keep / revert buttons. */
+  | { kind: "fader-keep" }
+  | { kind: "fader-revert" }
+  /** The piano roll / highway area. */
+  | { kind: "highway" }
+  /** Scrollable text (`/help`, the transcript, the `?` panel). */
+  | { kind: "text" };
+
+export interface HitRegion {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  target: HitTarget;
+}
+
+export class HitMap {
+  readonly regions: HitRegion[] = [];
+
+  add(
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+    target: HitTarget,
+  ): void {
+    if (width <= 0 || height <= 0) return;
+    this.regions.push({ x, y, width, height, target });
+  }
+
+  /** The topmost region under a cell, or undefined. */
+  at(x: number, y: number): HitRegion | undefined {
+    for (let index = this.regions.length - 1; index >= 0; index -= 1) {
+      const region = this.regions[index]!;
+      if (
+        x >= region.x &&
+        x < region.x + region.width &&
+        y >= region.y &&
+        y < region.y + region.height
+      )
+        return region;
+    }
+    return undefined;
+  }
+}

package/tui/input.ts

@@ -53,8 +53,15 @@ export class TerminalInputDecoder {
     // shared a read with the next key, e.g. Esc then Ctrl+Z.
     const next = this.buffer.charCodeAt(1);
     if (next < 0x20 || next === 0x7f) return "\u001b";
+    // A legacy X10 mouse report (a terminal without SGR 1006): CSI M and
+    // three raw bytes. One event, so its bytes never type into the prompt.
+    if (this.buffer.startsWith("\u001b[M"))
+      return this.buffer.length >= 6 ? this.buffer.slice(0, 6) : undefined;
     const final = this.buffer.match(/^\u001b\[[\x20-?]*[\x40-~]/)?.[0];
     if (final !== undefined) return final;
+    // SS3: arrows in application mode and F1-F4 (`ESC O P` is F1).
+    const ss3 = this.buffer.match(/^\u001bO[A-DHFPQRS]/)?.[0];
+    if (ss3 !== undefined) return ss3;
     // An unrecognised Alt-prefixed character is still one complete event.
     if (this.buffer.length >= 2 && this.buffer[1] !== "[")
       return this.buffer.slice(0, 2);

package/tui/keys.ts

@@ -100,3 +100,75 @@ const OVERLAY_SEQUENCES: Record<string, OverlayKey> = {
 export function overlayKey(value: string): OverlayKey | undefined {
   return OVERLAY_SEQUENCES[value];
 }
+
+// ---------------------------------------------------------------------------
+// Mouse (SGR 1006)
+
+/**
+ * Mouse reporting: 1000 clicks, 1002 drags with a button held, 1006 the
+ * SGR encoding (`ESC [ < b ; x ; y M|m`), which has no 223-column limit and
+ * tells a release from a press. Off is the same modes in reverse order.
+ */
+export const MOUSE_ON = "\u001b[?1000h\u001b[?1002h\u001b[?1006h";
+export const MOUSE_OFF = "\u001b[?1006l\u001b[?1002l\u001b[?1000l";
+
+export type MouseButton = "left" | "middle" | "right" | "none";
+
+export interface MouseEvent {
+  kind: "down" | "up" | "drag" | "move" | "wheel";
+  button: MouseButton;
+  /** 0-based cell column and row. */
+  x: number;
+  y: number;
+  /** For `wheel`: -1 up (away from you), 1 down. */
+  delta: -1 | 1 | 0;
+  shift: boolean;
+  alt: boolean;
+  ctrl: boolean;
+}
+
+const SGR_MOUSE = /^\u001b\[<(\d{1,4});(\d{1,5});(\d{1,5})([Mm])$/;
+const BUTTONS: readonly MouseButton[] = ["left", "middle", "right", "none"];
+
+/** Decode one SGR mouse report; undefined for anything else. */
+export function parseMouse(value: string): MouseEvent | undefined {
+  const match = SGR_MOUSE.exec(value);
+  if (!match) return undefined;
+  const code = Number(match[1]);
+  const x = Number(match[2]) - 1;
+  const y = Number(match[3]) - 1;
+  if (x < 0 || y < 0) return undefined;
+  const modifiers = {
+    shift: (code & 4) !== 0,
+    alt: (code & 8) !== 0,
+    ctrl: (code & 16) !== 0,
+  };
+  const button = BUTTONS[code & 3]!;
+  if (code & 64) {
+    // 64/65 wheel up/down; 66/67 (horizontal wheels) are ignored.
+    if ((code & 3) > 1) return undefined;
+    return {
+      kind: "wheel",
+      button: "none",
+      x,
+      y,
+      delta: (code & 1) === 0 ? -1 : 1,
+      ...modifiers,
+    };
+  }
+  const motion = (code & 32) !== 0;
+  const kind =
+    match[4] === "m"
+      ? "up"
+      : motion
+        ? button === "none"
+          ? "move"
+          : "drag"
+        : "down";
+  return { kind, button, x, y, delta: 0, ...modifiers };
+}
+
+/** True for any mouse report, SGR or a legacy X10 one (dropped). */
+export function isMouseSequence(value: string): boolean {
+  return value.startsWith("\u001b[<") || value.startsWith("\u001b[M");
+}