@hncode/hncode 0.5.6 → 0.6.0

package/src/tex/font.js

@@ -0,0 +1,292 @@
+/**
+ * A TrueType font reader: the tables a rasteriser needs, and glyph outlines as flat contours.
+ *
+ * Only the `glyf` outline format is read. STIX Two ships CFF outlines in its OpenType build (`.otf`), whose
+ * Type 2 charstrings are a postfix program with subroutines, flex operators and hint masks; the TrueType
+ * build (`.ttf`) holds the same outlines as quadratic `glyf` contours, which is a fraction of the surface
+ * area. That is the one bundled here, and it is what `tools/otf-to-ttf.py` produces from the CFF original.
+ *
+ * Nothing here tries to be a full font engine. Hints, kerning and shaping are absent on purpose: a formula
+ * is laid out by its own rules, and the size is fixed, so none of them affect the raster.
+ */
+import fs from 'node:fs';
+
+/** Read a big-endian uint16 / int16 / uint32 helpers over a Buffer. */
+const u16 = (b, o) => b.readUInt16BE(o);
+const i16 = (b, o) => b.readInt16BE(o);
+const u32 = (b, o) => b.readUInt32BE(o);
+
+/** Decode a UTF-16BE string of `len` bytes at `o`. */
+function utf16be(buf, o, len) {
+  let s = '';
+  for (let i = 0; i < len; i += 2) s += String.fromCharCode(buf.readUInt16BE(o + i));
+  return s;
+}
+
+export class TrueTypeFont {
+  /**
+   * @param {Buffer} buf The whole file.
+   */
+  constructor(buf) {
+    this.buf = buf;
+    const numTables = u16(buf, 4);
+    this.tables = new Map();
+    for (let i = 0; i < numTables; i++) {
+      const rec = 12 + i * 16;
+      const tag = buf.toString('latin1', rec, rec + 4);
+      this.tables.set(tag, { offset: u32(buf, rec + 8), length: u32(buf, rec + 12) });
+    }
+
+    const head = this.table('head');
+    this.unitsPerEm = u16(head, 18);
+    this.indexToLocFormat = i16(head, 50);
+
+    const hhea = this.table('hhea');
+    this.numHMetrics = u16(hhea, 34);
+    this.ascender = i16(hhea, 4);
+    this.descender = i16(hhea, 6);
+
+    this.numGlyphs = u16(this.table('maxp'), 4);
+    this._cmap = this._readCmap();
+    this._loca = null;
+    this._outlineCache = new Map();
+  }
+
+  table(tag) {
+    const t = this.tables.get(tag);
+    if (!t) throw new Error('font is missing the ' + tag + ' table');
+    return this.buf.subarray(t.offset, t.offset + t.length);
+  }
+
+  /**
+   * The Unicode → glyph id map, from the best `cmap` subtable available.
+   * Prefers a full-repertoire format 12 over the BMP-only format 4.
+   */
+  _readCmap() {
+    const cmap = this.table('cmap');
+    const count = u16(cmap, 2);
+    let best = null;
+    for (let i = 0; i < count; i++) {
+      const rec = 4 + i * 8;
+      const platform = u16(cmap, rec);
+      const encoding = u16(cmap, rec + 2);
+      const offset = u32(cmap, rec + 4);
+      const format = u16(cmap, offset);
+      // Unicode full repertoire: platform 3 encoding 10, or platform 0 encoding 4/6.
+      if (format === 12 && ((platform === 3 && encoding === 10) || (platform === 0 && (encoding === 4 || encoding === 6)))) {
+        best = { offset, format };
+      }
+      if (!best && format === 4 && (platform === 3 && encoding === 1 || platform === 0)) {
+        best = { offset, format };
+      }
+    }
+    if (!best) throw new Error('font has no usable cmap subtable');
+    return best;
+  }
+
+  /** Glyph id for a code point, or 0 when the font has none. */
+  glyphIndex(cp) {
+    const cmap = this.table('cmap');
+    const { offset, format } = this._cmap;
+
+    if (format === 12) {
+      const nGroups = u32(cmap, offset + 12);
+      let lo = 0;
+      let hi = nGroups - 1;
+      while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const g = offset + 16 + mid * 12;
+        const start = u32(cmap, g);
+        const end = u32(cmap, g + 4);
+        if (cp < start) hi = mid - 1;
+        else if (cp > end) lo = mid + 1;
+        else return u32(cmap, g + 8) + (cp - start);
+      }
+      return 0;
+    }
+
+    // Format 4: segmented into 16-bit ranges.
+    const segX2 = u16(cmap, offset + 6);
+    const segCount = segX2 / 2;
+    const endAt = offset + 14;
+    const startAt = endAt + segX2 + 2;
+    const deltaAt = startAt + segX2;
+    const rangeAt = deltaAt + segX2;
+    for (let s = 0; s < segCount; s++) {
+      if (cp > u16(cmap, endAt + s * 2)) continue;
+      const start = u16(cmap, startAt + s * 2);
+      if (cp < start) return 0;
+      const delta = i16(cmap, deltaAt + s * 2);
+      const rangeOffset = u16(cmap, rangeAt + s * 2);
+      if (rangeOffset === 0) return (cp + delta) & 0xffff;
+      const glyphAt = rangeAt + s * 2 + rangeOffset + (cp - start) * 2;
+      const g = u16(cmap, glyphAt);
+      return g === 0 ? 0 : (g + delta) & 0xffff;
+    }
+    return 0;
+  }
+
+  /** Advance width of a glyph, in font units. */
+  advance(gid) {
+    const hmtx = this.table('hmtx');
+    const n = Math.min(gid, this.numHMetrics - 1);
+    return u16(hmtx, n * 4);
+  }
+
+  _locaTable() {
+    if (this._loca) return this._loca;
+    const buf = this.table('loca');
+    const n = this.numGlyphs + 1;
+    const out = new Uint32Array(n);
+    for (let i = 0; i < n; i++) {
+      out[i] = this.indexToLocFormat === 0 ? u16(buf, i * 2) * 2 : u32(buf, i * 4);
+    }
+    this._loca = out;
+    return out;
+  }
+
+  /**
+   * The contours of a glyph in font units, with y pointing UP.
+   *
+   * Each contour is an array of points `{x, y, on}` where `on` marks a point on the curve; consecutive
+   * off-curve points imply a quadratic control point between them, which is how TrueType stores curves.
+   * Composite glyphs are resolved by recursing into their components.
+   */
+  outline(gid, depth = 0) {
+    if (this._outlineCache.has(gid)) return this._outlineCache.get(gid);
+    const contours = this._readGlyph(gid, depth);
+    this._outlineCache.set(gid, contours);
+    return contours;
+  }
+
+  _readGlyph(gid, depth) {
+    if (depth > 8 || gid >= this.numGlyphs) return [];
+    const loca = this._locaTable();
+    const glyf = this.table('glyf');
+    const start = loca[gid];
+    const end = loca[gid + 1];
+    if (end <= start) return [];   // empty glyph, e.g. a space
+
+    const g = glyf.subarray(start, end);
+    const numberOfContours = i16(g, 0);
+
+    if (numberOfContours < 0) return this._readComposite(g, depth);
+    return this._readSimple(g, numberOfContours);
+  }
+
+  _readSimple(g, numberOfContours) {
+    const endPts = [];
+    for (let i = 0; i < numberOfContours; i++) endPts.push(u16(g, 10 + i * 2));
+    const nPoints = endPts.length ? endPts[endPts.length - 1] + 1 : 0;
+    if (nPoints === 0) return [];
+
+    let p = 10 + numberOfContours * 2;
+    const instructionLength = u16(g, p);
+    p += 2 + instructionLength;
+
+    // Flags, with the repeat bit collapsing runs of identical ones.
+    const flags = new Uint8Array(nPoints);
+    for (let i = 0; i < nPoints;) {
+      const f = g[p++];
+      flags[i++] = f;
+      if (f & 0x08) {
+        let repeat = g[p++];
+        while (repeat-- > 0 && i < nPoints) flags[i++] = f;
+      }
+    }
+
+    // X coordinates.
+    const xs = new Int32Array(nPoints);
+    let x = 0;
+    for (let i = 0; i < nPoints; i++) {
+      const f = flags[i];
+      if (f & 0x02) {
+        const d = g[p++];
+        x += (f & 0x10) ? d : -d;
+      } else if (!(f & 0x10)) {
+        x += i16(g, p);
+        p += 2;
+      }
+      xs[i] = x;
+    }
+
+    // Y coordinates.
+    const ys = new Int32Array(nPoints);
+    let y = 0;
+    for (let i = 0; i < nPoints; i++) {
+      const f = flags[i];
+      if (f & 0x04) {
+        const d = g[p++];
+        y += (f & 0x20) ? d : -d;
+      } else if (!(f & 0x20)) {
+        y += i16(g, p);
+        p += 2;
+      }
+      ys[i] = y;
+    }
+
+    const contours = [];
+    let first = 0;
+    for (const last of endPts) {
+      const pts = [];
+      for (let i = first; i <= last; i++) pts.push({ x: xs[i], y: ys[i], on: !!(flags[i] & 1) });
+      if (pts.length) contours.push(pts);
+      first = last + 1;
+    }
+    return contours;
+  }
+
+  _readComposite(g, depth) {
+    const out = [];
+    let p = 10;
+    for (;;) {
+      const flags = u16(g, p);
+      const glyphIndex = u16(g, p + 2);
+      p += 4;
+
+      let dx = 0;
+      let dy = 0;
+      if (flags & 0x0001) {
+        // ARG_1_AND_2_ARE_WORDS
+        dx = i16(g, p); dy = i16(g, p + 2); p += 4;
+      } else {
+        dx = (g[p] << 24) >> 24; dy = (g[p + 1] << 24) >> 24; p += 2;
+      }
+
+      let a = 1, b = 0, c = 0, d = 1;
+      if (flags & 0x0008) {
+        a = d = i16(g, p) / 16384; p += 2;
+      } else if (flags & 0x0040) {
+        a = i16(g, p) / 16384; d = i16(g, p + 2) / 16384; p += 4;
+      } else if (flags & 0x0080) {
+        a = i16(g, p) / 16384; b = i16(g, p + 2) / 16384;
+        c = i16(g, p + 4) / 16384; d = i16(g, p + 6) / 16384;
+        p += 8;
+      }
+
+      // ARGS_ARE_XY_VALUES: dx/dy are offsets. Otherwise they are point indices, which no math glyph uses.
+      for (const contour of this._readGlyph(glyphIndex, depth + 1)) {
+        out.push(contour.map((pt) => ({
+          x: a * pt.x + c * pt.y + dx,
+          y: b * pt.x + d * pt.y + dy,
+          on: pt.on,
+        })));
+      }
+
+      if (!(flags & 0x0020)) break;   // MORE_COMPONENTS
+    }
+    return out;
+  }
+}
+
+/** Load a font from disk. */
+export function loadFont(file) {
+  return new TrueTypeFont(fs.readFileSync(file));
+}
+
+/** The bundled formula font. It is ~900 KB, so it is read on the first formula that needs it, never at startup. */
+export const BUNDLED_FONT = new URL('./fonts/STIX2Math.ttf', import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1');
+
+export function loadBundledFont() {
+  return loadFont(BUNDLED_FONT);
+}

package/src/tex/fonts/LICENSE.txt

@@ -0,0 +1,11 @@
+The formula font in this directory is STIX Two Math (TrueType build, "STIX Two Math TT").
+It is distributed under the SIL Open Font License, Version 1.1.
+
+Copyright:
+Copyright (c) 2001-2016 by the STI Pub Companies, consisting of the American Chemical Society, the American Institute of Physics, the American Mathematical Society, the American Physical Society, Elsevier, Inc., and The Institute of Electrical and Electronic Engineers, Inc.  Portions copyright (c) 1998-2003 by MicroPress, Inc.  Portions copyright (c) 1990 by Elsevier, Inc.  All rights reserved.  Portions copyright (c) Copyright 2010, 2012, 2014 Adobe Systems Incorporated.
+
+License:
+As a condition for receiving these fonts at no charge, each person downloading the fonts must agree to some simple license terms. The license is based on the SIL Open Font License <http://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL>. The SIL License is a free and open source license specifically designed for fonts and related software. The basic terms are that the recipient will not remove the copyright and trademark statements from the fonts and that, if the person decides to create a derivative work based on the STIX Fonts but incorporating some changes or enhancements, the derivative work ("Modified Version") will carry a different name. The copyright and trademark restrictions are part of the agreement between the STI Pub companies and the typeface designer. The "renaming" restriction results from the desire of the STI Pub companies to assure that the STIX Fonts will continue to function in a predictable fashion for all that use them. No copy of one or more of the individual Font typefaces that form the STIX Fonts(TM) set may be sold by itself, but other than this one restriction, licensees are free to sell the fonts either separately or as part of a package that combines other software or fonts with this font set.
+
+License URL:
+http://www.stixfonts.org/user_license.html

package/src/tex/index.js

@@ -0,0 +1,293 @@
+/**
+ * The public face of the bitmap renderer: the policy that decides whether a formula is drawn as a picture,
+ * how large its raster is, and what to do when it cannot be drawn at all.
+ *
+ * The pieces below it know nothing about terminals. `parse.js` builds the node tree, `layout.js` measures it
+ * in font units, `render.js` turns it into RGBA and `sixel.js` encodes that for the terminal. This module is
+ * where the terminal's facts arrive — its protocol and its cell size — so the same formula lands on whole
+ * cells on every display.
+ *
+ * The bundled face is STIX Two Math: it carries the repertoire this pipeline uses (fractions, big operators
+ * with limits, radicals, braces), so a formula typeset here looks like the one in a paper rather than like
+ * assembled ASCII.
+ */
+import { loadBundledFont } from './font.js';
+import { parseTex } from './parse.js';
+import { layout } from './layout.js';
+import { renderBox } from './render.js';
+import { encodeSixel } from './sixel.js';
+import { kittyTransmit, kittyPlace, kittyImageId } from './kitty.js';
+
+/**
+ * Ex per cell height. A formula is set to the same size as the text around it by matching the x-HEIGHT, not
+ * the em: a terminal cell is about twice as tall as it is wide, and a font's em is roughly twice its
+ * x-height, so one ex per cell height lands the two on the same scale. dsh-tui uses 0.5 of the cell height
+ * for body text and 0.72 for display math (src/math/layout.ts there); 0.55 is the display value here.
+ */
+const EX_PER_CELL_HEIGHT = 0.55;
+/** Margin around the ink, in pixels. A bracket's arms sit exactly on the box edge, so this is not optional. */
+const PAD = 4;
+/** A formula taller than this many rows is a matrix to scroll, not a picture to paint. */
+const MAX_ROWS = 12;
+/** Cells to measure with when the terminal never reported its cell size (XTWINOPS 16). */
+const FALLBACK_CELL = { w: 10, h: 20 };
+
+/** The font is ~900 KB, so it is read on the first formula that needs it, never at startup. */
+let fontCache = null;
+/** The font's x-height as a fraction of its em, measured from the `x` glyph rather than assumed. */
+let exRatio = null;
+
+function font() {
+  if (!fontCache) fontCache = loadBundledFont();
+  return fontCache;
+}
+
+/** Fraction of the em occupied by the x-height. Measured once, from the glyph itself. */
+function xHeightRatio(face) {
+  if (exRatio !== null) return exRatio;
+  let top = 0;
+  const gid = face.glyphIndex('x'.codePointAt(0));
+  for (const contour of face.outline(gid)) for (const p of contour) if (p.y > top) top = p.y;
+  // A font with no usable `x` falls back to a typical maths face's x-height.
+  exRatio = top > 0 ? top / face.unitsPerEm : 0.47;
+  return exRatio;
+}
+
+/** Laid-out boxes, keyed by source: parsing and laying out is the expensive half and is size-independent. */
+const layoutCache = new Map();
+const LAYOUT_CACHE_MAX = 128;
+
+/**
+ * Whether the parse kept a command as literal source text.
+ *
+ * `parse.js` does not throw on a command it does not know: it emits the command as an atom so nothing is
+ * lost. For a BITMAP that is the wrong answer — the picture would spell `\notacommand` in STIX glyphs — so a
+ * formula carrying one is declined and the caller falls back to the text form, which shows the same source
+ * in the code style the reader expects.
+ */
+function hasUnknownCommand(nodes) {
+  for (const node of nodes || []) {
+    if (!node || typeof node !== 'object') continue;
+    if (node.cls === 'raw') return true;
+    if (Array.isArray(node) && hasUnknownCommand(node)) return true;
+    for (const key of ['body', 'num', 'den', 'index', 'scripts', 'rows']) {
+      const value = node[key];
+      if (!value) continue;
+      if (Array.isArray(value)) {
+        if (hasUnknownCommand(value)) return true;
+        if (value.some((row) => Array.isArray(row) && hasUnknownCommand(row))) return true;
+      } else if (typeof value === 'object') {
+        if (hasUnknownCommand(value.sup) || hasUnknownCommand(value.sub)) return true;
+      }
+    }
+  }
+  return false;
+}
+
+function layoutOf(tex) {
+  const hit = layoutCache.get(tex);
+  if (hit !== undefined) return hit;
+  let box = null;
+  try {
+    const nodes = parseTex(tex);
+    box = hasUnknownCommand(nodes) ? null : layout(nodes, font(), 1000);
+    if (box && !(box.width > 0 && box.height + box.depth > 0)) box = null;
+  } catch {
+    box = null;
+  }
+  if (layoutCache.size >= LAYOUT_CACHE_MAX) {
+    const oldest = layoutCache.keys().next().value;
+    if (oldest !== undefined) layoutCache.delete(oldest);
+  }
+  layoutCache.set(tex, box);
+  return box;
+}
+
+/**
+ * The cell box a formula occupies at its natural size, without rasterising it.
+ *
+ * @param {string} tex TeX without delimiters.
+ * @param {{cell?: {w: number, h: number}}} [opts] The terminal's cell size in pixels.
+ * @returns {{columns: number, rows: number, px: number, width: number, height: number}|null} Null when the
+ *   TeX is outside the subset.
+ */
+export function measureTex(tex, opts = {}) {
+  const box = layoutOf(tex);
+  if (!box) return null;
+  const cell = opts.cell && opts.cell.w > 0 && opts.cell.h > 0 ? opts.cell : FALLBACK_CELL;
+  const face = font();
+  // One ex is this many pixels, and the em the rasteriser wants is the em that PRODUCES that x-height.
+  const exPx = Math.max(3, cell.h * EX_PER_CELL_HEIGHT);
+  const px = Math.max(6, Math.round(exPx / xHeightRatio(face)));
+  // Round UP: a picture a pixel taller than its box must claim the extra row rather than be clipped.
+  const width = Math.ceil(box.width * px / face.unitsPerEm) + PAD * 2;
+  const height = Math.ceil((box.height + box.depth) * px / face.unitsPerEm) + PAD * 2;
+  return {
+    columns: Math.max(1, Math.ceil(width / cell.w)),
+    rows: Math.max(1, Math.ceil(height / cell.h)),
+    px,
+    width,
+    height,
+  };
+}
+
+/** Rendered rasters, keyed by source + size + colour. A formula is redrawn on every frame it stays on screen. */
+const rasterCache = new Map();
+const RASTER_CACHE_MAX = 48;
+
+/**
+ * Encoded Sixel sequences, keyed by the raster they came from.
+ *
+ * The raster cache saves the layout and the glyph rasterising; this one saves the ENCODING, which walks every
+ * pixel again with a palette pass and run-length coding. Scrolling moves a formula up and down without changing
+ * what it depicts, so without this the same picture was re-encoded on every frame of a scroll.
+ */
+const sequenceCache = new Map();
+const SEQUENCE_CACHE_MAX = 64;
+
+
+/** Below this fraction of the natural size a formula is unreadable; the caller keeps the text form instead. */
+const MIN_SCALE = 0.55;
+
+/**
+ * Render a formula as an RGBA image, shrunk uniformly when it would not fit.
+ *
+ * The size policy is dsh-tui's (src/math/layout.ts there): set the formula at ONE base size tied to the
+ * terminal's cell, then shrink it UNIFORMLY — never stretch it, never enlarge it — only as far as it must to
+ * fit the columns and rows it is allowed. Below a legibility floor the picture is refused, so the caller
+ * falls back to text instead of drawing something unreadable.
+ *
+ * @param {string} tex TeX without delimiters.
+ * @param {object} [opts]
+ * @param {{w: number, h: number}} [opts.cell] The terminal's cell size in pixels.
+ * @param {{r:number,g:number,b:number}} [opts.colour] Ink colour.
+ * @param {number} [opts.maxWidth] Columns the picture may occupy.
+ * @param {number} [opts.maxRows] Rows the picture may occupy.
+ * @returns {{rgba: Uint8ClampedArray, width: number, height: number, columns: number, rows: number}|null}
+ */
+export function renderTexImage(tex, opts = {}) {
+  const cell = opts.cell && opts.cell.w > 0 && opts.cell.h > 0 ? opts.cell : FALLBACK_CELL;
+  const natural = measureTex(tex, { cell });
+  if (!natural) return null;
+  const maxColumns = opts.maxWidth || Infinity;
+  const maxRows = Math.min(MAX_ROWS, opts.maxRows || MAX_ROWS);
+
+  // Shrink by whichever axis overflows, and only by the amount needed.
+  const fit = Math.min(
+    natural.columns > maxColumns ? maxColumns / natural.columns : 1,
+    natural.rows > maxRows ? maxRows / natural.rows : 1,
+  );
+  if (fit < MIN_SCALE) return null;
+  const px = Math.max(6, Math.round(natural.px * fit));
+  // Measured again at the FINAL size, so the cells claimed are the cells the raster covers.
+  const box = layoutOf(tex);
+  const em = font().unitsPerEm;
+  const columns = Math.max(1, Math.ceil((Math.ceil(box.width * px / em) + PAD * 2) / cell.w));
+  const rows = Math.max(1, Math.ceil((Math.ceil((box.height + box.depth) * px / em) + PAD * 2) / cell.h));
+  if (columns > maxColumns || rows > maxRows) return null;
+
+  const colour = opts.colour || { r: 220, g: 220, b: 220 };
+  // A crop is part of a raster's identity: the same formula cut at a different pixel row is a different
+  // picture, and serving the uncropped one from the cache would put it back where it started.
+  const skipTop = Math.max(0, Math.round(opts.skipTop || 0));
+  // `maxHeight` is an exact PIXEL limit, not a row limit: it is what a picture clipped by the transcript panel
+  // needs, and it has to cut the raster itself — a band crop cannot express it.
+  const maxHeight = opts.maxHeight > 0 ? Math.round(opts.maxHeight) : 0;
+  const key = [tex, px, skipTop, maxHeight, colour.r, colour.g, colour.b].join('\u0000');
+  const hit = rasterCache.get(key);
+  if (hit) return hit;
+
+  let image = null;
+  try {
+    const rendered = renderBox(box, font(), { px, colour, padding: PAD, skipTop, maxHeight });
+    // The claimed cell box shrinks with the crop: what is left is what gets drawn.
+    const drawnRows = Math.max(1, Math.ceil(rendered.height / cell.h));
+    image = { ...rendered, columns, rows: drawnRows };
+  } catch {
+    image = null;
+  }
+  if (rasterCache.size >= RASTER_CACHE_MAX) {
+    const oldest = rasterCache.keys().next().value;
+    if (oldest !== undefined) rasterCache.delete(oldest);
+  }
+  rasterCache.set(key, image);
+  return image;
+}
+
+/**
+ * A formula as the terminal sequence that draws it, with the cell box it covers.
+ *
+ * @param {string} tex TeX without delimiters.
+ * @param {object} opts As `renderTexImage`, plus `protocol` ('sixel' or 'kitty').
+ * @returns {{sequence: string, width: number, height: number, columns: number, rows: number, kittyId?: number,
+ *   kittyPlacement?: string}|null}
+ */
+export function encodeTexImage(tex, opts = {}) {
+  const image = renderTexImage(tex, opts);
+  if (!image) return null;
+  const protocol = opts.protocol || 'sixel';
+  if (protocol !== 'sixel' && protocol !== 'kitty') return null;
+  const colour = opts.colour || { r: 220, g: 220, b: 220 };
+
+  // THE SEQUENCE IS CACHED TOO, keyed by the raster it comes from.
+  //
+  // Encoding is the expensive half of the pipeline — a palette pass for Sixel, a base64 stream for Kitty —
+  // and it was paid on EVERY frame even when the raster itself came from a cache. Scrolling changes a
+  // placement's ROW, not the picture it draws, so the same formula was re-encoded dozens of times while the
+  // view moved. The key is the raster's own identity, so a hit can only return bytes for exactly these pixels.
+  const key = `${protocol}\u0000${image.width}x${image.height}\u0000${tex}\u0000${Math.round(opts.skipTop || 0)}`
+    + `\u0000${colour.r},${colour.g},${colour.b}`;
+  const hit = sequenceCache.get(key);
+  if (hit) {
+    sequenceCache.delete(key);            // refresh its position: the least recently used goes first
+    sequenceCache.set(key, hit);
+    return { ...hit, columns: image.columns, rows: image.rows };
+  }
+
+  // KITTY IS TWO PARTS, AND ONLY ONE OF THEM IS RESENT. `kittyId` owns the uploaded pixels; `kittyPlacement`
+  // is the twenty-byte command that puts them at a cell. A frame that only moves a picture re-sends the
+  // placement and leaves the pixels alone — which is the whole point of the protocol.
+  const built = protocol === 'kitty'
+    ? {
+      sequence: kittyTransmit(kittyImageId(image.rgba, image.width, image.height), image.rgba, image.width, image.height),
+      kittyId: kittyImageId(image.rgba, image.width, image.height),
+      kittyPlacement: (x, y, columns, rows) => kittyPlace(kittyImageId(image.rgba, image.width, image.height), 1, x, y, columns, rows),
+      width: image.width,
+      height: image.height,
+      columns: image.columns,
+      rows: image.rows,
+    }
+    : {
+      // A FORMULA IS LINE ART: one ink colour, and the raster is its antialiased coverage. Encoding that as a
+      // grey ramp dissolves hairline strokes into speckle once the terminal fits it, so the coverage is
+      // promoted to a one-bit mask in that single ink colour — the rule dsh-tui applies for the same reason
+      // (src/ink/sixel-codec.ts, `lineArt`).
+      sequence: encodeSixel(image.rgba, image.width, image.height, {
+        transparent: true,
+        lineArt: true,
+        ink: colour,
+      }),
+      width: image.width,
+      height: image.height,
+      columns: image.columns,
+      rows: image.rows,
+    };
+  sequenceCache.set(key, built);
+  while (sequenceCache.size > SEQUENCE_CACHE_MAX) {
+    const oldest = sequenceCache.keys().next().value;
+    if (oldest === undefined) break;
+    sequenceCache.delete(oldest);
+  }
+  return built;
+}
+
+
+/** Drop the font and the caches; for tests and for a settings change. */
+export function resetTexRenderer() {
+  fontCache = null;
+  layoutCache.clear();
+  rasterCache.clear();
+  sequenceCache.clear();
+}
+
+export { MAX_ROWS as TEX_MAX_ROWS };