@young1lin/dsh-ui-gitworkbench 0.1.5 → 0.1.7

package/src/client/side-rows.ts

@@ -0,0 +1,258 @@
+/**
+ * The side-by-side diff's row model: a parsed full-context diff turned into
+ * rows that pair the two columns.
+ *
+ * A unified diff already IS an alignment — `context` lines hit both columns, a
+ * `del` the left one, an `add` the right one — so no diff algorithm is needed
+ * here or bundled: `git diff -U1000000` emits one hunk covering the whole file
+ * and this module only has to read that alignment into rows.
+ *
+ * The pairing rule is positional, the way IDEA renders it: inside a run of
+ * consecutive changed lines the 1st deletion pairs with the 1st addition, the
+ * 2nd with the 2nd, … into `change` rows, and whatever has no partner becomes a
+ * one-sided `del` or `add` row. A one-line edit is then ONE row with both
+ * sides, not a delete row above an add row.
+ *
+ * A block — a maximal run of changed rows uninterrupted by a `same` row — is
+ * the unit the stage/discard/unstage buttons of the editable view act on.
+ * `blockLines` names a block back in the hunk's own coordinates: the line
+ * indices it returns are exactly the selection `patch-model`'s `emitPatch`
+ * needs to reproduce that block alone, which is the contract that keeps those
+ * buttons correct.
+ *
+ * `` markers belong to the line before them and
+ * never form a row of their own. They are carried, not dropped: a row's
+ * `leftIndex`/`rightIndex` stay true indices into `hunk.lines`, so the marker
+ * describing a row's line is reachable as `index + 1` when a later task wants
+ * to render it.
+ *
+ * Pure: no React, no CSS, no git. `tests/side-rows.test.ts` loads it directly.
+ */
+
+import type { FilePatch } from '../patch-model.ts'
+
+/** One column's half of a row: that side's real line number and text. */
+export interface SideCell {
+  readonly line: number
+  readonly text: string
+}
+
+export interface SideRow {
+  /** `same` both columns equal; `change` a paired del/add; `del`/`add` one-sided. */
+  readonly kind: 'same' | 'change' | 'del' | 'add'
+  readonly left: SideCell | null
+  readonly right: SideCell | null
+  /** Index into the hunk's `lines` for the LEFT cell, -1 when absent. */
+  readonly leftIndex: number
+  /** Index into the hunk's `lines` for the RIGHT cell, -1 when absent. */
+  readonly rightIndex: number
+  /** Which change block this row belongs to; -1 for unchanged rows. */
+  readonly block: number
+}
+
+/** One collected side of a run of changed lines, with its hunk-line index. */
+interface RunSide {
+  readonly index: number
+  readonly text: string
+}
+
+/**
+ * Align a full-context diff's single hunk into two-column rows.
+ *
+ * @param file - a parsed diff. Full context means one hunk; anything else is
+ *               the caller's bug, and mis-aligning it silently would be worse
+ *               than refusing.
+ * @returns the rows, in file order: `same` rows carry both line numbers,
+ *          changed rows carry their block id.
+ * @throws when the patch does not have exactly one hunk.
+ */
+export function alignRows(file: FilePatch): readonly SideRow[] {
+  if (file.hunks.length !== 1) {
+    throw new Error(`alignRows expects the one hunk of a full-context diff, got ${file.hunks.length}`)
+  }
+  const hunk = file.hunks[0]!
+  const rows: SideRow[] = []
+  let oldL = hunk.oldStart
+  let newL = hunk.newStart
+  let block = -1
+
+  let i = 0
+  while (i < hunk.lines.length) {
+    const line = hunk.lines[i]!
+    if (line.kind === 'nonewline') {
+      // Describes the line before it, which a row already carries; never a row.
+      i += 1
+      continue
+    }
+    if (line.kind === 'context') {
+      rows.push({
+        kind: 'same',
+        left: { line: oldL, text: line.text },
+        right: { line: newL, text: line.text },
+        leftIndex: i,
+        rightIndex: i,
+        block: -1,
+      })
+      oldL += 1
+      newL += 1
+      i += 1
+      continue
+    }
+
+    // A run of del/add lines — one block. `\ No newline` markers inside the
+    // run are transparent: git can put one between the deletions and the
+    // additions, and that is still ONE change, not two blocks with no context
+    // line between them.
+    const dels: RunSide[] = []
+    const adds: RunSide[] = []
+    let j = i
+    while (j < hunk.lines.length) {
+      const run = hunk.lines[j]!
+      if (run.kind === 'del') dels.push({ index: j, text: run.text })
+      else if (run.kind === 'add') adds.push({ index: j, text: run.text })
+      else if (run.kind !== 'nonewline') break
+      j += 1
+    }
+    block += 1
+
+    const pairs = Math.min(dels.length, adds.length)
+    for (let p = 0; p < pairs; p += 1) {
+      rows.push({
+        kind: 'change',
+        left: { line: oldL, text: dels[p]!.text },
+        right: { line: newL, text: adds[p]!.text },
+        leftIndex: dels[p]!.index,
+        rightIndex: adds[p]!.index,
+        block,
+      })
+      oldL += 1
+      newL += 1
+    }
+    for (let p = pairs; p < dels.length; p += 1) {
+      rows.push({
+        kind: 'del',
+        left: { line: oldL, text: dels[p]!.text },
+        right: null,
+        leftIndex: dels[p]!.index,
+        rightIndex: -1,
+        block,
+      })
+      oldL += 1
+    }
+    for (let p = pairs; p < adds.length; p += 1) {
+      rows.push({
+        kind: 'add',
+        left: null,
+        right: { line: newL, text: adds[p]!.text },
+        leftIndex: -1,
+        rightIndex: adds[p]!.index,
+        block,
+      })
+      newL += 1
+    }
+    i = j
+  }
+  return rows
+}
+
+/**
+ * Every hunk line index a block covers: each of its rows' `leftIndex` and
+ * `rightIndex` where present, ascending, without duplicates.
+ *
+ * @param rows - rows from {@link alignRows}.
+ * @param block - a block id the rows carry.
+ * @returns the indices, exactly the selection `emitPatch` takes to reproduce
+ *          this block alone (its own changes plus the file's context).
+ */
+export function blockLines(rows: readonly SideRow[], block: number): readonly number[] {
+  const indices = new Set<number>()
+  for (const row of rows) {
+    if (row.block !== block) continue
+    if (row.leftIndex !== -1) indices.add(row.leftIndex)
+    if (row.rightIndex !== -1) indices.add(row.rightIndex)
+  }
+  return [...indices].sort((a, b) => a - b)
+}
+
+/**
+ * How many change blocks the rows hold.
+ *
+ * @param rows - rows from {@link alignRows}.
+ * @returns the block count, 0 for an unchanged file.
+ */
+export function blockCount(rows: readonly SideRow[]): number {
+  let max = -1
+  for (const row of rows) if (row.block > max) max = row.block
+  return max + 1
+}
+
+/**
+ * Whether a block is the file's ENTIRE content: the one block of a diff with
+ * no context row at all.
+ *
+ * An untracked file's synthesized new-file diff is exactly this shape — every
+ * line an addition, nothing unchanged — and it is the case whose roll-back
+ * DELETES the file rather than rewriting it, so the confirmation's wording
+ * asks for it by name. A tracked file whose every line changed has the same
+ * shape and only rewrites, which is why the caller combines this with the
+ * file row's status instead of reading deletion into the shape alone.
+ *
+ * @param rows - rows from {@link alignRows}.
+ * @param block - a block id the rows carry.
+ * @returns true when the block covers every row and no row is unchanged.
+ */
+export function blockIsWholeFile(rows: readonly SideRow[], block: number): boolean {
+  if (rows.length === 0 || block !== 0 || blockCount(rows) !== 1) return false
+  return rows.every(row => row.kind !== 'same')
+}
+
+/** What the pane's body area renders for the payload on screen. */
+export type SideBody =
+  | { readonly kind: 'editor' }
+  | { readonly kind: 'empty' }
+  | { readonly kind: 'rows' }
+
+/**
+ * Decide the pane's BODY area — never the whole pane.
+ *
+ * The tab row above it always renders: an empty layer diff (a fully staged
+ * file's unstaged side, a file with nothing staged) is one click from the
+ * other layer — and, on the unstaged side, one Edit button from the editor,
+ * because the working tree is the edit target even when every change in it is
+ * already staged. So "no rows" is a state of the body, not an early return
+ * for the pane, and an ARMED editor over an emptied diff still edits: the
+ * file's unstaged delta can vanish (the agent staged everything) under a
+ * buffer the reader is mid-edit in.
+ *
+ * @param rows - rows from {@link alignRows}; empty when the layer diff is.
+ * @param editable - whether the editor is armed (unstaged layer only).
+ * @returns which of the three body treatments the pane renders.
+ */
+export function sideBodyState(rows: readonly SideRow[], editable: boolean): SideBody {
+  if (editable) return { kind: 'editor' }
+  if (rows.length === 0) return { kind: 'empty' }
+  return { kind: 'rows' }
+}
+
+/**
+ * A block's line tallies: how many of its rows carry a right cell (added) and
+ * how many a left one (deleted). A paired edit counts one on each side.
+ *
+ * The roll-back confirmation states the consequence in these terms — "these N
+ * added and M deleted lines are reverted" — so the count must come from the
+ * same row model the buttons act on, not from the file row's whole-file stats.
+ *
+ * @param rows - rows from {@link alignRows}.
+ * @param block - a block id the rows carry.
+ * @returns the tallies; zeros for an id no row carries.
+ */
+export function blockTally(rows: readonly SideRow[], block: number): { readonly added: number; readonly deleted: number } {
+  let added = 0
+  let deleted = 0
+  for (const row of rows) {
+    if (row.block !== block) continue
+    if (row.left !== null) deleted += 1
+    if (row.right !== null) added += 1
+  }
+  return { added, deleted }
+}

package/src/client/stable-list.ts

@@ -0,0 +1,31 @@
+/**
+ * Is this list the same list as last time?
+ *
+ * React memoisation keys on IDENTITY, and the drawer polls: `git status` comes
+ * back every 3–15 seconds and every derived array is a new object even when
+ * the repository has not moved. In the Files tab that identity change is the
+ * head of a chain — the untracked paths feed the merged path list, which feeds
+ * the directory tree, which feeds the rows — so one fresh array per poll
+ * rebuilds a 20,000-path tree that is byte-for-byte what it already was.
+ *
+ * Comparing the contents costs one pass over the list; rebuilding costs a sort
+ * and a tree walk. The comparison wins by two orders of magnitude, and it wins
+ * by more the larger the repository is, which is exactly where it matters.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/stable-list
+ */
+
+/**
+ * Element-wise equality, in order.
+ *
+ * Identity first: the common case is that nothing upstream changed at all, and
+ * then there is nothing to compare.
+ */
+export function sameList(a: readonly string[], b: readonly string[]): boolean {
+  if (a === b) return true
+  if (a.length !== b.length) return false
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) return false
+  }
+  return true
+}

package/src/client/use-change-nav.ts

@@ -0,0 +1,83 @@
+/**
+ * Walking a scroller change by change — the wiring half of `diff-nav.ts`.
+ *
+ * The decisions (which block is next, where to stop, how to survive the end of
+ * the file) are pure and live next door, where vitest can reach them. What is
+ * left is the part that cannot be pure: reading the DOM for where the blocks
+ * actually are, and moving the scroller. Both panes that offer the walk — the
+ * side-by-side view in Changes and the unified view in History and Compare —
+ * need exactly this, and a second copy of it is a second place for the
+ * scroll-position bookkeeping to be got subtly wrong.
+ *
+ * The scroller is passed IN rather than created here: in Changes the pane owns
+ * it, in History the drawer does. The blocks are found by attribute, so any
+ * renderer that marks its changed rows with `data-block` can be walked.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/client/use-change-nav
+ */
+
+import { useRef, type MutableRefObject } from 'react'
+
+import { anchorFrom, scrollTopFor, stepToBlock, type BlockTop, type NavMemory } from './diff-nav.ts'
+
+/** What a pane needs to offer the walk. */
+export interface ChangeNav {
+  /** Move to the next (1) or previous (-1) change, wrapping at both ends. */
+  readonly goToChange: (direction: 1 | -1) => void
+}
+
+/**
+ * @param scrollRef - the element that scrolls, and the one whose subtree
+ *   carries the `data-block` marks.
+ */
+export function useChangeNav(scrollRef: MutableRefObject<HTMLDivElement | null>): ChangeNav {
+  /** What the last press landed on. A ref, not state: it exists to make the
+   *  NEXT press correct, and nothing on screen reads it. */
+  const navMemory = useRef<NavMemory | null>(null)
+
+  /**
+   * Every change block's position inside the scrolled content.
+   *
+   * Measured off the DOM rather than derived from a row model: a model knows
+   * which rows changed, not how many pixels down the page they sit, and the
+   * rows are never the only thing in the scroller — padding, a sticky bar and,
+   * in the armed side-by-side pane, a CodeMirror view of a different height
+   * all move the answer. One layout read per PRESS is cheap; nothing here runs
+   * on scroll.
+   *
+   * `offsetTop` is deliberately not used: it is relative to whichever ancestor
+   * happens to be positioned, which no rule in the stylesheet guarantees.
+   * Measuring both boxes and subtracting is independent of that.
+   */
+  const blockTops = (): readonly BlockTop[] => {
+    const scroller = scrollRef.current
+    if (scroller === null) return []
+    // First element carrying each id, in document order. A side-by-side row
+    // marks both of its columns, so the first hit for a block is its first row.
+    const first = new Map<number, HTMLElement>()
+    for (const cell of scroller.querySelectorAll<HTMLElement>('[data-block]')) {
+      const block = Number(cell.dataset.block)
+      if (!Number.isInteger(block) || block < 0 || first.has(block)) continue
+      first.set(block, cell)
+    }
+    const base = scroller.getBoundingClientRect().top - scroller.scrollTop
+    const tops: BlockTop[] = []
+    for (const [block, cell] of first) tops.push({ block, top: cell.getBoundingClientRect().top - base })
+    return tops
+  }
+
+  const goToChange = (direction: 1 | -1): void => {
+    const scroller = scrollRef.current
+    if (scroller === null) return
+    const tops = blockTops()
+    const target = stepToBlock(tops, anchorFrom(tops, scroller.scrollTop, navMemory.current), direction)
+    if (target === null) return
+    scroller.scrollTop = scrollTopFor(target.top)
+    // Read back rather than storing what was asked for: the browser clamps at
+    // the end of the content, and the clamped value is what the next press
+    // compares against to tell "still here" from "the reader scrolled".
+    navMemory.current = { block: target.block, scrollTop: scroller.scrollTop }
+  }
+
+  return { goToChange }
+}

package/src/client/worktree-view.ts

@@ -12,6 +12,16 @@ function normalize(path: string): string {
   return path.replace(/\\/g, '/').replace(/\/+$/, '')
 }
 
+/**
+ * A path in the one form everything compares by — the same normalisation
+ * {@link samePath} uses, exposed so state can be KEYED by a worktree rather
+ * than only tested against one. An absent path keys as '', which is a real
+ * key: it names the session's own repository, the source the drawer starts on.
+ */
+export function pathKey(path: string | null | undefined): string {
+  return path === null || path === undefined ? '' : normalize(path)
+}
+
 /**
  * Whether two paths name the same place.
  *
@@ -23,7 +33,7 @@ function normalize(path: string): string {
  */
 export function samePath(a: string | null | undefined, b: string | null | undefined): boolean {
   if (a === null || a === undefined || b === null || b === undefined) return false
-  return normalize(a) === normalize(b)
+  return pathKey(a) === pathKey(b)
 }
 
 /**

package/src/git-ops.ts

@@ -210,7 +210,15 @@ export function stageStateOf(xy: string): StageState {
   return { staged: index !== ' ', unstaged: worktree !== ' ' }
 }
 
-/** Why an operation failed, in terms the drawer can explain to a person. */
+/**
+ * Why an operation failed, in terms the drawer can explain to a person.
+ *
+ * The last two are caller-derived, which is why {@link classifyFailure} never
+ * returns them: `stale` is a sha mismatch the caller compared before running
+ * git at all, and `invalid` an argument combination the caller refused before
+ * anything spawned. They ride the same union so a `GitOpResult` needs no
+ * parallel classification for the operations that produce them.
+ */
 export type OpFailure =
   | 'auth'
   | 'network'
@@ -219,6 +227,8 @@ export type OpFailure =
   | 'conflict'
   | 'nothing-to-commit'
   | 'dirty'
+  | 'stale'
+  | 'invalid'
   | 'unknown'
 
 /**
@@ -489,6 +499,31 @@ export function isBinaryPrefix(bytes: Buffer, windowBytes: number): boolean {
   return bytes.subarray(0, windowBytes).includes(0)
 }
 
+/**
+ * Whether a buffer is valid UTF-8, and so survives a decode/encode round trip.
+ *
+ * The editable pane hands the browser a decoded string and writes back what
+ * comes home encoded as UTF-8. For a file in any other encoding — GBK, Shift
+ * JIS, Latin-1 — that trip is LOSSY: every byte the decoder cannot read
+ * becomes U+FFFD, and writing the result replaces every non-ASCII byte in the
+ * file, including the lines nobody edited. Such a file carries no NUL byte,
+ * so the binary sniff above waves it through; only decoding it says so.
+ *
+ * `fatal` makes the decoder throw on the first invalid sequence rather than
+ * substituting, which is the whole question asked in one call and without
+ * allocating the string twice to compare it.
+ *
+ * @param bytes - the file's contents.
+ */
+export function decodesAsUtf8(bytes: Buffer): boolean {
+  try {
+    new TextDecoder('utf-8', { fatal: true }).decode(bytes)
+    return true
+  } catch {
+    return false
+  }
+}
+
 /**
  * Clip a diff to a character cap, and SAY so when the clip happened — a
  * silently shortened diff reads as a complete one (TESTS.md H1).

package/src/image-sniff.ts

@@ -0,0 +1,204 @@
+/**
+ * Is this file actually an image, and which kind?
+ *
+ * The extension is a hint, never the answer: `.png` is a filename, not a
+ * format, and a repository full of generated assets has mislabelled files in
+ * it. So the bytes decide — every format below is identified by the signature
+ * its own specification mandates in the first few bytes.
+ *
+ * The obvious alternative is the `file-type` package, which is the mature
+ * packaging of exactly this idea. It is not used here for three reasons: it
+ * is four transitive dependencies in a package that is published to npm, it
+ * identifies two hundred types where this needs eight, and — the deciding one
+ * — it could not make the render any safer than it already is. Sniffing is
+ * the FIRST of two gates; the second is the browser's own image decoder, and
+ * that one is authoritative in a way no table can be. If the trade ever turns,
+ * `sniffImage` is the only function to replace.
+ *
+ * Membership in the table is decided by one rule: browsers render it in an
+ * `<img>` element. That is why TIFF and HEIC are absent — recognising them
+ * would only let the view promise a picture it cannot draw, and "binary file"
+ * is the more honest answer for a format the reader's browser will refuse.
+ *
+ * SVG is the one member with no magic number, because it is XML rather than a
+ * container. It is admitted anyway: rendering happens through `<img>`, which
+ * the HTML specification defines as a non-scripted context — script elements,
+ * event handlers and external references inside the document do not run and do
+ * not load. That property, not a sanitiser, is what makes it safe.
+ *
+ * Pure: no node, no fs, no git. `tests/image-sniff.test.ts` loads it directly.
+ *
+ * @module @young1lin/dsh-ui-gitworkbench/image-sniff
+ */
+
+/** A file the sniffer recognised. */
+export interface SniffedImage {
+  /** MIME type, as the `<img>` blob should be labelled. */
+  readonly mime: string
+  /** Short human label for the caption: 'PNG', 'WebP', … */
+  readonly kind: string
+}
+
+/**
+ * Largest image handed to the browser, in bytes.
+ *
+ * This is a WIRE budget, not a rendering one. The bytes cross the RPC channel
+ * base64-encoded, which costs a third again on top, so a cap of four megabytes
+ * is a payload of five and a third — already the largest single message the
+ * drawer sends. Screenshots and icons, which is what repositories actually
+ * hold, sit two orders of magnitude below it.
+ */
+export const IMAGE_BYTE_CAP = 4_000_000
+
+/** How many leading bytes any signature below needs. */
+const SNIFF_BYTES = 64
+
+/** How much of a text file is read looking for an SVG root element.
+ *
+ *  Larger than any magic number needs because the prologue in front of that
+ *  root is unbounded in principle: an XML declaration, a DOCTYPE with an
+ *  internal subset of declarations, and any number of comments all come
+ *  first, and real files use all three. */
+const SVG_PROLOGUE_BYTES = 4096
+
+/** Do `bytes` begin with these byte values at `at`? */
+function at(bytes: Uint8Array, offset: number, signature: readonly number[]): boolean {
+  if (bytes.length < offset + signature.length) return false
+  for (let i = 0; i < signature.length; i += 1) {
+    if (bytes[offset + i] !== signature[i]) return false
+  }
+  return true
+}
+
+/** The bytes of an ASCII marker, so the tables read as the specs write them. */
+function ascii(text: string): readonly number[] {
+  return [...text].map(ch => ch.charCodeAt(0))
+}
+
+/** Little-endian uint32 at `offset`, or -1 when the buffer is too short. */
+function u32le(bytes: Uint8Array, offset: number): number {
+  if (bytes.length < offset + 4) return -1
+  return (bytes[offset] | (bytes[offset + 1] << 8) | (bytes[offset + 2] << 16) | (bytes[offset + 3] << 24)) >>> 0
+}
+
+/** DIB header sizes BMP has ever defined. A `BM` prefix alone is two bytes of
+ *  evidence, which any text beginning "BM" would satisfy; the header size is
+ *  what makes the match a bitmap. */
+const BMP_HEADERS: readonly number[] = [12, 16, 40, 52, 56, 64, 108, 124]
+
+/** ISO base-media brands that carry a still image a browser will draw. */
+const AVIF_BRANDS: readonly string[] = ['avif', 'avis']
+
+/**
+ * Identify one file from its leading bytes.
+ *
+ * @param bytes - the file's content, or at least its first {@link SNIFF_BYTES}.
+ * @returns what it is, or null for anything not in the table.
+ */
+export function sniffImage(bytes: Uint8Array): SniffedImage | null {
+  if (bytes.length === 0) return null
+
+  // PNG: the eight-byte signature from the specification, chosen there
+  // precisely so that no other format collides with it.
+  if (at(bytes, 0, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) {
+    return { mime: 'image/png', kind: 'PNG' }
+  }
+  // JPEG: SOI marker, then the first marker of the next segment.
+  if (at(bytes, 0, [0xff, 0xd8, 0xff])) {
+    return { mime: 'image/jpeg', kind: 'JPEG' }
+  }
+  if (at(bytes, 0, ascii('GIF87a')) || at(bytes, 0, ascii('GIF89a'))) {
+    return { mime: 'image/gif', kind: 'GIF' }
+  }
+  // WebP is a RIFF container; the four bytes after the length field are what
+  // separate it from a WAV or an AVI.
+  if (at(bytes, 0, ascii('RIFF')) && at(bytes, 8, ascii('WEBP'))) {
+    return { mime: 'image/webp', kind: 'WebP' }
+  }
+  // ISO base media: `ftyp` box, then the brand. Also matches HEIC and MP4,
+  // which is why only the still-image AVIF brands are admitted.
+  if (at(bytes, 4, ascii('ftyp')) && AVIF_BRANDS.some(brand => at(bytes, 8, ascii(brand)))) {
+    return { mime: 'image/avif', kind: 'AVIF' }
+  }
+  if (at(bytes, 0, ascii('BM')) && BMP_HEADERS.includes(u32le(bytes, 14))) {
+    return { mime: 'image/bmp', kind: 'BMP' }
+  }
+  // ICO: reserved zero, type 1 (icon) or 2 (cursor), then a non-zero count of
+  // images. The count is the check that a run of zero bytes cannot pass.
+  if (at(bytes, 0, [0x00, 0x00, 0x01, 0x00]) && (bytes[4] | (bytes[5] << 8)) > 0) {
+    return { mime: 'image/x-icon', kind: 'ICO' }
+  }
+  if (looksLikeSvg(bytes)) {
+    return { mime: 'image/svg+xml', kind: 'SVG' }
+  }
+  return null
+}
+
+/**
+ * Does this text begin an SVG document?
+ *
+ * Structural rather than a substring search: the prologue XML allows before a
+ * root element is skipped, and then the root element itself must be `svg`. A
+ * file that merely CONTAINS `<svg` somewhere — an HTML page with an inline
+ * icon, a TypeScript file with a template literal — is not one.
+ */
+function looksLikeSvg(bytes: Uint8Array): boolean {
+  const head = bytes.subarray(0, SVG_PROLOGUE_BYTES)
+  // A NUL rules out text before any parsing: the same test the diff side uses
+  // to call a file binary.
+  if (head.includes(0)) return false
+  let text: string
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(head)
+  } catch {
+    // A truncated multi-byte character at the cut is not a decode failure of
+    // the FILE, so retry lenient; a genuinely non-UTF-8 file yields U+FFFD,
+    // which no prologue below accepts.
+    text = new TextDecoder('utf-8').decode(head)
+  }
+  // Strip a byte-order mark, which is legal before an XML declaration.
+  let rest = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
+  for (;;) {
+    rest = rest.replace(/^\s+/, '')
+    if (rest.startsWith('<?')) {
+      const end = rest.indexOf('?>')
+      // Prologue cut off by the sniff window: undecidable, so not an image.
+      if (end === -1) return false
+      rest = rest.slice(end + 2)
+      continue
+    }
+    if (rest.startsWith('<!--')) {
+      const end = rest.indexOf('-->')
+      if (end === -1) return false
+      rest = rest.slice(end + 3)
+      continue
+    }
+    if (rest.startsWith('<!')) {
+      // A DOCTYPE may carry an internal subset in brackets, and the
+      // declarations inside it end with '>' characters of their own —
+      // scanning to the first one lands in the middle of the subset and the
+      // root element is never reached. Real files do this: matplotlib ships
+      // an SVG whose DOCTYPE declares an ATTLIST, and it was the one file in
+      // a hundred and twenty-five thousand that this missed.
+      const bracket = rest.indexOf('[')
+      const end = rest.indexOf('>')
+      if (end === -1) return false
+      if (bracket === -1 || bracket > end) {
+        rest = rest.slice(end + 1)
+        continue
+      }
+      const closed = rest.indexOf(']', bracket)
+      if (closed === -1) return false
+      const after = rest.indexOf('>', closed)
+      if (after === -1) return false
+      rest = rest.slice(after + 1)
+      continue
+    }
+    break
+  }
+  // The root element, and only `svg`: the character after the name must end
+  // it, so `<svgfoo>` is not a match.
+  if (!rest.startsWith('<svg')) return false
+  const after = rest.charAt(4)
+  return after === '' || after === '>' || after === '/' || /\s/.test(after)
+}