azeroth-shell 0.1.1 → 0.2.0

package/src/cli/sixel.mjs

@@ -0,0 +1,307 @@
+// Sixel sprites: real pixels for the creatures on the fight stage, where the terminal can draw them
+// (Windows Terminal 1.22+, WezTerm, foot, mlterm, xterm -ti vt340). The half-block art (modelArt.mjs) is a
+// pixel per half cell; a sixel image is the terminal's own pixels, about ten per cell across and twenty down.
+//
+// A screen is lines of text, so an image travels through them as a placeholder: a block of blank cells
+// whose rows each start with a marker, an SGR-shaped code (`ESC[9999;id;rowm`) the text helpers count as
+// zero width. RealTerm.draw takes the markers out before it writes, then sends the image at the block's
+// top-left cell after the text (term.mjs). The terminal says whether it speaks sixel in its DA1 reply.
+//
+// The pixels come from model-art-hd.bin.br (scripts/bake-model-art.mjs --hd): the same sprites as the
+// half-block pack at the renders' own size, up to 128 px wide; icons from icon-art-hd.bin.br. Neither ships in
+// the package: hdArt.mjs finds them (downloaded, or a checkout's bake). No pack, no sprite, or no sixel: null,
+// and the caller draws the half-block art. AZSH_SIXEL=0 turns it off, AZSH_SIXEL=1 on without asking.
+import { readFileSync } from 'node:fs';
+import { brotliDecompressSync } from 'node:zlib';
+import { useColor } from './text.mjs';
+import { hdArtPath } from './hdArt.mjs';
+
+const MAGIC = 9999;
+export const MARK_RE = /\x1b\[9999;(\d+);(\d+)m/g;
+
+let on = process.env.AZSH_SIXEL === '1';
+// The terminal's cell in pixels. Windows Terminal answers CSI 16 t with zeros and scales a sixel as if a
+// cell were 10 x 20 (the VT340's), whatever the font; that is the fallback for any terminal that does not say.
+let cellW = 10, cellH = 20;
+
+/** Is sixel art on? Never without colour or under AZSH_SIXEL=0. */
+export const sixelOn = () => on && useColor && process.env.AZSH_SIXEL !== '0';
+/** The DA1 reply's parameters (`?62;4;22`): 4 is sixel graphics. True when this turned sixel on. */
+export function noteDeviceAttributes(params) {
+  if (on || process.env.AZSH_SIXEL === '0') return false;
+  on = params.replace('?', '').split(';').includes('4');
+  return on;
+}
+/** The CSI 16 t reply: the cell's height and width in pixels; zeros (Windows Terminal) keep the fallback. */
+export function noteCellSize(h, w) {
+  if (h > 0 && w > 0) { cellH = h; cellW = w; }
+}
+
+// ---- the source images ------------------------------------------------------------------------------
+
+let index = null; // displayId -> byte offset of the sprite in `pack` (the half-block pack's layout, AZART v1)
+let pack = null;
+
+function load() {
+  if (index) return index;
+  index = new Map();
+  try {
+    pack = brotliDecompressSync(readFileSync(hdArtPath('model-art-hd.bin.br')));
+    if (pack.toString('ascii', 0, 5) !== 'AZART' || pack[5] !== 1) return index;
+    const count = pack.readUInt32LE(6);
+    let off = 10;
+    for (let i = 0; i < count && off + 7 <= pack.length; i++) {
+      index.set(pack.readUInt32LE(off), off);
+      off += 7 + pack[off + 6] * 3 + pack[off + 4] * pack[off + 5];
+    }
+  } catch { pack = null; }
+  return index;
+}
+
+/** Forget the packs (and what was missing) so the next draw reads them again: after a download. */
+export function forgetSixelPacks() { index = pack = iconIndex = iconPack = null; images.clear(); byKey.clear(); }
+
+/** The sprite for a display id as { w, h, rgba } (already cropped to its opaque box), or null. */
+function sourceOf(displayId) {
+  const off = load().get(displayId);
+  if (off == null) return null;
+  const w = pack[off + 4], h = pack[off + 5], palLen = pack[off + 6], pal = off + 7, idx = pal + palLen * 3;
+  const rgba = new Uint8Array(w * h * 4);
+  for (let i = 0; i < w * h; i++) {
+    const p = pack[idx + i];
+    if (!p) continue;
+    const c = pal + (p - 1) * 3;
+    rgba[i * 4] = pack[c]; rgba[i * 4 + 1] = pack[c + 1]; rgba[i * 4 + 2] = pack[c + 2]; rgba[i * 4 + 3] = 255;
+  }
+  return { w, h, rgba };
+}
+
+// ---- scaling and encoding -----------------------------------------------------------------------------
+
+/** The image scaled to tw x th, placed bottom-centre on a cw x ch canvas: area-sampled when it shrinks,
+ *  bilinear when it grows. Colour is weighted by alpha; a pixel shows where more than half of it is covered. */
+function scaleOnto(img, tw, th, cw, ch) {
+  const out = new Uint8Array(cw * ch * 4);
+  const ox = Math.floor((cw - tw) / 2), oy = ch - th;
+  const sx = img.w / tw, sy = img.h / th;
+  if (sx < 1) {
+    const at = (x, y, c) => img.rgba[(Math.min(img.h - 1, Math.max(0, y)) * img.w + Math.min(img.w - 1, Math.max(0, x))) * 4 + c];
+    for (let ty = 0; ty < th; ty++) {
+      const fy = (ty + 0.5) * sy - 0.5, y0 = Math.floor(fy), wy = fy - y0;
+      for (let tx = 0; tx < tw; tx++) {
+        const fx = (tx + 0.5) * sx - 0.5, x0 = Math.floor(fx), wx = fx - x0;
+        let r = 0, g = 0, b = 0, a = 0;
+        for (const [x, y, wt] of [[x0, y0, (1 - wx) * (1 - wy)], [x0 + 1, y0, wx * (1 - wy)], [x0, y0 + 1, (1 - wx) * wy], [x0 + 1, y0 + 1, wx * wy]]) {
+          const al = at(x, y, 3) * wt;
+          r += at(x, y, 0) * al; g += at(x, y, 1) * al; b += at(x, y, 2) * al; a += al;
+        }
+        if (a < 128) continue;
+        const d = ((oy + ty) * cw + ox + tx) * 4;
+        out[d] = r / a; out[d + 1] = g / a; out[d + 2] = b / a; out[d + 3] = 255;
+      }
+    }
+    return out;
+  }
+  for (let ty = 0; ty < th; ty++) {
+    const y0 = Math.floor(ty * sy), y1 = Math.max(y0 + 1, Math.floor((ty + 1) * sy));
+    for (let tx = 0; tx < tw; tx++) {
+      const x0 = Math.floor(tx * sx), x1 = Math.max(x0 + 1, Math.floor((tx + 1) * sx));
+      let r = 0, g = 0, b = 0, a = 0, n = 0;
+      for (let y = y0; y < y1 && y < img.h; y++) for (let x = x0; x < x1 && x < img.w; x++) {
+        const k = (y * img.w + x) * 4, al = img.rgba[k + 3];
+        r += img.rgba[k] * al; g += img.rgba[k + 1] * al; b += img.rgba[k + 2] * al; a += al; n++;
+      }
+      if (!n || a / n < 128) continue;
+      const d = ((oy + ty) * cw + ox + tx) * 4;
+      out[d] = r / a; out[d + 1] = g / a; out[d + 2] = b / a; out[d + 3] = 255;
+    }
+  }
+  return out;
+}
+
+/** Up to 255 colours: the most used 15-bit buckets (each the mean of its pixels), the rest mapped to the
+ *  nearest kept one. Returns the palette and a colour index per pixel (-1 where transparent). */
+function quantize(rgba, n) {
+  const count = new Uint32Array(32768), sum = new Float64Array(32768 * 3), bucket = new Int32Array(n).fill(-1);
+  for (let i = 0; i < n; i++) {
+    if (!rgba[i * 4 + 3]) continue;
+    const r = rgba[i * 4], g = rgba[i * 4 + 1], b = rgba[i * 4 + 2], k = ((r >> 3) << 10) | ((g >> 3) << 5) | (b >> 3);
+    bucket[i] = k; count[k]++; sum[k * 3] += r; sum[k * 3 + 1] += g; sum[k * 3 + 2] += b;
+  }
+  const used = [];
+  for (let k = 0; k < 32768; k++) if (count[k]) used.push(k);
+  used.sort((a, b) => count[b] - count[a]);
+  const kept = used.slice(0, 255);
+  const pal = kept.map((k) => [sum[k * 3] / count[k], sum[k * 3 + 1] / count[k], sum[k * 3 + 2] / count[k]]);
+  const slot = new Int32Array(32768).fill(-1);
+  kept.forEach((k, i) => { slot[k] = i; });
+  for (const k of used.slice(255)) {
+    const r = ((k >> 10) & 31) * 8 + 4, g = ((k >> 5) & 31) * 8 + 4, b = (k & 31) * 8 + 4;
+    let best = 0, bd = Infinity;
+    pal.forEach(([pr, pg, pb], i) => { const d = (pr - r) ** 2 + (pg - g) ** 2 + (pb - b) ** 2; if (d < bd) { bd = d; best = i; } });
+    slot[k] = best;
+  }
+  const idx = new Int16Array(n).fill(-1);
+  for (let i = 0; i < n; i++) if (bucket[i] >= 0) idx[i] = slot[bucket[i]];
+  return { pal, idx };
+}
+
+/** An RGBA image as a sixel string: 1:1 pixels, unset pixels transparent (P2=1), run-length coded. */
+function encode(rgba, w, h) {
+  const { pal, idx } = quantize(rgba, w * h);
+  let out = `\x1bP0;1;0q"1;1;${w};${h}`;
+  pal.forEach(([r, g, b], i) => { out += `#${i};2;${Math.round((r * 100) / 255)};${Math.round((g * 100) / 255)};${Math.round((b * 100) / 255)}`; });
+  const rle = (ch, n) => (n > 3 ? `!${n}${ch}` : ch.repeat(n));
+  for (let y0 = 0; y0 < h; y0 += 6) {
+    // Each colour in the band: a six-bit column per x, the rows it covers.
+    const bands = new Map();
+    for (let dy = 0; dy < 6 && y0 + dy < h; dy++) for (let x = 0; x < w; x++) {
+      const c = idx[(y0 + dy) * w + x];
+      if (c < 0) continue;
+      let cols = bands.get(c);
+      if (!cols) bands.set(c, (cols = new Uint8Array(w)));
+      cols[x] |= 1 << dy;
+    }
+    let first = true;
+    for (const [c, cols] of bands) {
+      let last = w - 1;
+      while (last >= 0 && !cols[last]) last--;
+      let s = `#${c}`, run = 0, prev = -1;
+      for (let x = 0; x <= last; x++) {
+        if (cols[x] === prev) { run++; continue; }
+        if (run) s += rle(String.fromCharCode(63 + prev), run);
+        prev = cols[x]; run = 1;
+      }
+      if (run) s += rle(String.fromCharCode(63 + prev), run);
+      out += (first ? '' : '$') + s;
+      first = false;
+    }
+    out += '-';
+  }
+  return `${out}\x1b\\`;
+}
+
+// ---- placements ----------------------------------------------------------------------------------------
+
+// Encoded images by id, the oldest dropped past IMAGES_MAX (a marker for a dropped id is ignored, and the
+// next draw that wants the picture encodes it again under a new id).
+const IMAGES_MAX = 480;
+const images = new Map(); // id -> { cols, rows, sixel, holes }
+const byKey = new Map(); // what was drawn and at which cell size -> id
+let nextId = 0;
+
+/** The sixel string, size in cells and transparent `holes` of a placed image, by the id its markers carry. */
+export const imageOf = (id) => images.get(id) ?? null;
+
+/** The id of the image under `key`, built by `make()` -> { cols, rows, rgba, holes? } (cols x rows cells of
+ *  pixels, `holes` the cells left transparent) the first time; null when `make` has nothing. */
+function imageId(key, make) {
+  key = `${key}|${cellW}x${cellH}`;
+  const hit = byKey.get(key);
+  if (hit != null && images.has(hit)) return hit;
+  const img = make();
+  if (!img) return null;
+  const id = nextId++;
+  images.set(id, { cols: img.cols, rows: img.rows, holes: img.holes ?? [], sixel: encode(img.rgba, img.cols * cellW, img.rows * cellH) });
+  byKey.set(key, id);
+  if (images.size > IMAGES_MAX) {
+    const old = images.keys().next().value;
+    images.delete(old);
+    for (const [k, v] of byKey) if (v === old) { byKey.delete(k); break; }
+  }
+  return id;
+}
+
+/** The placeholder for image `id`: one array of cells per row, the row's marker riding on its first cell. */
+function placeholderCells(id) {
+  const { cols, rows } = images.get(id);
+  return Array.from({ length: rows }, (_, r) => Array.from({ length: cols }, (_, x) => (x ? ' ' : `[${MAGIC};${id};${r}m `)));
+}
+
+/**
+ * A creature as a sixel placeholder that fits in `maxCols` x `maxRows` cells (bottom-centred, keeping its
+ * proportions): `rows` lines of `cols` blank cells, each line starting with its marker. Null when sixel is
+ * off or the pack has no sprite for the display id.
+ */
+export function sixelCreature(displayId, maxCols, maxRows) {
+  if (!sixelOn() || displayId == null || maxCols < 2 || maxRows < 2) return null;
+  return sixelImage(`c${displayId}`, () => sourceOf(displayId), maxCols, maxRows);
+}
+
+/** Any image (`source()` -> { w, h, rgba }, cropped) fitted to `maxCols` x `maxRows` cells as placeholder lines,
+ *  cached under `key`; null when sixel is off or there is no image. */
+export function sixelImage(key, source, maxCols, maxRows) {
+  if (!sixelOn()) return null;
+  const id = imageId(`${key}|${maxCols}x${maxRows}`, () => {
+    const img = source();
+    if (!img) return null;
+    const scale = Math.min((maxCols * cellW) / img.w, (maxRows * cellH) / img.h);
+    const tw = Math.max(1, Math.round(img.w * scale)), th = Math.max(1, Math.round(img.h * scale));
+    const cols = Math.ceil(tw / cellW), rows = Math.ceil(th / cellH);
+    return { cols, rows, rgba: scaleOnto(img, tw, th, cols * cellW, rows * cellH) };
+  });
+  return id == null ? null : placeholderCells(id).map((r) => r.join(''));
+}
+
+// ---- icons ----------------------------------------------------------------------------------------------
+
+let iconIndex = null; // name -> byte offset in `iconPack`
+let iconPack = null;
+
+function loadIcons() {
+  if (iconIndex) return iconIndex;
+  iconIndex = new Map();
+  try {
+    iconPack = brotliDecompressSync(readFileSync(hdArtPath('icon-art-hd.bin.br')));
+    if (iconPack.toString('ascii', 0, 5) !== 'AZICH' || iconPack[5] !== 1) return iconIndex;
+    const count = iconPack.readUInt32LE(6);
+    let off = 10;
+    for (let i = 0; i < count && off < iconPack.length; i++) {
+      const n = iconPack[off];
+      iconIndex.set(iconPack.toString('ascii', off + 1, off + 1 + n), off + 1 + n);
+      off += 1 + n;
+      off += 2 + iconPack[off + 1] * 3 + iconPack[off] * iconPack[off];
+    }
+  } catch { iconPack = null; }
+  return iconIndex;
+}
+
+/** An icon's picture as { w, h, rgba }; `tone` 'gray' greys and darkens it (a talent out of reach). */
+function iconSource(name, tone) {
+  const off = loadIcons().get(name);
+  if (off == null) return null;
+  const side = iconPack[off], palLen = iconPack[off + 1], pal = off + 2, idx = pal + palLen * 3;
+  const rgba = new Uint8Array(side * side * 4);
+  for (let i = 0; i < side * side; i++) {
+    const c = pal + iconPack[idx + i] * 3;
+    let r = iconPack[c], g = iconPack[c + 1], b = iconPack[c + 2];
+    if (tone === 'gray') r = g = b = Math.round((0.3 * r + 0.59 * g + 0.11 * b) * 0.6);
+    rgba[i * 4] = r; rgba[i * 4 + 1] = g; rgba[i * 4 + 2] = b; rgba[i * 4 + 3] = 255;
+  }
+  return { w: side, h: side, rgba };
+}
+
+/** Is there a full-size icon for `name` to draw as sixel? */
+export const sixelIconOn = (name) => sixelOn() && !!name && loadIcons().has(String(name).toLowerCase());
+
+/**
+ * The icon `name` filling `cols` x `cols / 2` cells, as rows of cells like iconCells (iconArt.mjs) makes,
+ * or null. `holes` ([{ x, y, w }] in cells) stay transparent so text drawn there (a rank, a count) shows
+ * through the picture.
+ */
+export function sixelIconCells(name, cols, tone = '', holes = []) {
+  if (!sixelIconOn(name)) return null;
+  name = String(name).toLowerCase();
+  const rows = cols / 2;
+  const id = imageId(`i${name}|${cols}|${tone}|${holes.map((h) => `${h.x},${h.y},${h.w}`).join(';')}`, () => {
+    const img = iconSource(name, tone);
+    if (!img) return null;
+    const pw = cols * cellW, ph = rows * cellH;
+    const rgba = scaleOnto(img, pw, ph, pw, ph);
+    for (const h of holes) for (let y = h.y * cellH; y < (h.y + 1) * cellH; y++) {
+      for (let x = h.x * cellW; x < (h.x + h.w) * cellW; x++) rgba[(y * pw + x) * 4 + 3] = 0;
+    }
+    return { cols, rows, rgba, holes };
+  });
+  return id == null ? null : placeholderCells(id);
+}

package/src/cli/term.mjs

@@ -7,6 +7,8 @@
 // the Esc key and is reported at once.
 import { stdin, stdout } from 'node:process';
 import { fit } from './text.mjs';
+import { splitCells } from './iconGrid.mjs';
+import { MARK_RE, imageOf, noteDeviceAttributes, noteCellSize } from './sixel.mjs';
 
 const ESC = '\x1b[';
 const MIN_COLS = 60, MIN_ROWS = 20;
@@ -62,6 +64,7 @@ export class RealTerm {
   constructor() {
     this.onKey = () => {};
     this.onResize = () => {};
+    this.onSixel = () => {}; // the terminal said it draws sixel
     this.isTTY = stdout.isTTY === true && stdin.isTTY === true;
     this.last = [];
   }
@@ -75,9 +78,19 @@ export class RealTerm {
     stdin.resume();
     // Autowrap off: a line a terminal measures wider than we do (an ambiguous-width glyph) is clipped
     // instead of wrapping and scrolling the whole frame out of step with `last`.
-    stdout.write(`${ESC}?1049h${ESC}?25l${ESC}?7l${ESC}H${ESC}2J`);
+    // Then ask what the terminal is (DA1: does it draw sixel) and its cell size in pixels (CSI 16 t); each
+    // image keeps its own colour registers (?1070h).
+    stdout.write(`${ESC}?1049h${ESC}?25l${ESC}?7l${ESC}H${ESC}2J${ESC}?1070h${ESC}c${ESC}16t`);
     // Ctrl-L forgets what is on screen and repaints everything, to recover from a terminal that moved it.
-    this._data = (chunk) => { for (const k of decodeKeys(chunk)) { if (k === 'ctrl-l') this.refresh(); else this.onKey(k); } };
+    // The replies to the questions above arrive as input; they are taken out before the keys are read.
+    this._data = (chunk) => {
+      let s = String(chunk), repaint = false;
+      s = s.replace(/\x1b\[(\?[0-9;]*)c/g, (_, p) => { if (noteDeviceAttributes(p)) { repaint = true; this.onSixel(); } return ''; });
+      s = s.replace(/\x1b\[6;(\d+);(\d+)t/g, (_, h, w) => { noteCellSize(+h, +w); repaint = true; return ''; });
+      if (repaint) this.refresh();
+      if (!s) return;
+      for (const k of decodeKeys(s)) { if (k === 'ctrl-l') this.refresh(); else this.onKey(k); }
+    };
     this._resize = () => this.refresh();
     stdin.on('data', this._data);
     stdout.on('resize', this._resize);
@@ -89,22 +102,54 @@ export class RealTerm {
     if (stdin.isTTY) stdin.setRawMode(false);
     stdin.pause();
   }
-  refresh() { this.last = []; this.onResize(); }
-  /** Paint a whole frame. Lines are fitted to the width; unchanged lines are skipped, unless most of the frame
-   *  changed (a new screen), which repaints it all so a stale row cannot outlive a screen change. The last
-   *  column stays blank so a terminal without deferred wrap never scrolls when the bottom row is painted. */
+  refresh() { this.last = []; this.lastImages = []; this.onResize(); }
+  /** Paint a whole frame. Lines are fitted to the width; of a changed line only the cells that changed are
+   *  written, unless most of the frame changed (a new screen), which repaints it all so a stale row cannot
+   *  outlive a screen change. The last column stays blank so a terminal without deferred wrap never scrolls
+   *  when the bottom row is painted. Sixel placeholders (sixel.mjs) are taken out of the lines and their images
+   *  sent after the text: an image that moved or went has its old rows erased, and one goes out again only when
+   *  a cell written this frame lies on its pixels (text in a hole, a count on an icon, leaves it be). The frame
+   *  is one synchronized update (mode 2026), so a terminal that knows it never shows the half-drawn state; one
+   *  that does not ignores it. */
   draw(lines) {
     if (this.tooSmall) { this.drawTooSmall(); return; }
     const w = this.cols - 1, h = this.rows;
-    const next = [];
-    for (let i = 0; i < h; i++) next.push(fit(lines[i] ?? '', w));
-    const changed = next.filter((line, i) => this.last[i] !== line).length;
+    const next = [], placed = new Map(); // `id@x,y` -> { id, x, y, bottom }: the same picture can stand twice
+    for (let i = 0; i < h; i++) next.push(takeMarks(fit(lines[i] ?? '', w), i, placed));
+    // An image goes out only when its bottom row made it to the screen: a pane that cut it short (a detail
+    // pane's last rows) would otherwise have it hang over what is below. Text drawn over its upper rows (a
+    // hit rising from the chest) can take a marker; the bottom row says where the image is all the same.
+    const images = [...placed.values()].filter((im) => im.bottom);
+    const same = (a, b) => a.id === b.id && a.x === b.x && a.y === b.y;
+    const erase = new Set();
+    for (const p of this.lastImages ?? []) {
+      if (images.some((im) => same(im, p))) continue;
+      for (let r = 0; r < (imageOf(p.id)?.rows ?? 0); r++) erase.add(p.y + r);
+    }
+    const changed = next.filter((line, i) => this.last[i] !== line || erase.has(i)).length;
     const full = !this.last.length || changed * 2 > h;
     // Every row is padded to the width, so only a frame with nothing known on screen needs a clear first.
     let out = this.last.length ? '' : `${ESC}0m${ESC}H${ESC}2J`;
-    next.forEach((line, i) => { if (full || this.last[i] !== line) out += `${ESC}${i + 1};1H${ESC}0m${line}`; });
+    const wrote = new Map(); // row -> [from, to) column spans written
+    next.forEach((line, i) => {
+      if (full || erase.has(i)) {
+        out += `${ESC}${i + 1};1H${ESC}2K${ESC}0m${line}`;
+        wrote.set(i, [[0, w]]);
+        return;
+      }
+      if (this.last[i] === line) return;
+      const spans = changedSpans(this.last[i], line);
+      for (const [from, to, text] of spans) out += `${ESC}${i + 1};${from + 1}H${ESC}0m${text}`;
+      wrote.set(i, spans);
+    });
+    for (const im of images) {
+      const img = imageOf(im.id);
+      const known = (this.lastImages ?? []).some((p) => same(im, p));
+      if (!known || covers(img, im, wrote)) out += `${ESC}${im.y + 1};${im.x + 1}H${img.sixel}`;
+    }
     this.last = next;
-    if (out) stdout.write(out);
+    this.lastImages = images;
+    if (out) stdout.write(`${ESC}?2026h${out}${ESC}?2026l`);
   }
   /** The screens need MIN_COLS x MIN_ROWS; a smaller terminal gets a notice instead of a frame drawn off its edge. */
   drawTooSmall() {
@@ -121,6 +166,55 @@ export class RealTerm {
   clearInterval(h) { clearInterval(h); }
 }
 
+/** The runs of cells that differ between two painted lines of one width, as [from, to, text]: `text` paints
+ *  columns from..to-1 of `line`, each cell carrying its own paint. */
+export function changedSpans(prev, line) {
+  const a = splitCells(prev ?? ''), b = splitCells(line);
+  const spans = [];
+  for (let x = 0; x < b.length; x++) {
+    if (a[x] === b[x]) continue;
+    let end = x + 1;
+    while (end < b.length && a[end] !== b[end]) end++;
+    spans.push([x, end, b.slice(x, end).join('')]);
+    x = end;
+  }
+  return spans;
+}
+
+/** Does a written span lie on the pixels of image `img` placed at `im` (a hole's cells are no pixels)? */
+function covers(img, im, wrote) {
+  for (let r = 0; r < img.rows; r++) {
+    for (const [from, to] of wrote.get(im.y + r) ?? []) {
+      for (let x = Math.max(from, im.x); x < Math.min(to, im.x + img.cols); x++) {
+        const cx = x - im.x;
+        if (!img.holes.some((h) => h.y === r && cx >= h.x && cx < h.x + h.w)) return true;
+      }
+    }
+  }
+  return false;
+}
+
+/** `line` without its sixel markers; each marker found notes a placement's top-left cell in `placed` (a row's
+ *  marker sits at the image's left edge, and its row number says how far down the image the line is). */
+export function takeMarks(line, y, placed) {
+  if (!line.includes('\x1b[9999;')) return line;
+  let out = '', col = 0, i = 0;
+  for (const m of line.matchAll(MARK_RE)) {
+    const before = line.slice(i, m.index);
+    out += before;
+    col += before.replace(/\x1b\[[0-9;]*m/g, '').length;
+    const id = +m[1], row = +m[2], img = imageOf(id);
+    if (img) {
+      const at = `${id}@${col},${y - row}`;
+      const p = placed.get(at) ?? { id, x: col, y: y - row, bottom: false };
+      if (row === img.rows - 1) p.bottom = true;
+      placed.set(at, p);
+    }
+    i = m.index + m[0].length;
+  }
+  return out + line.slice(i);
+}
+
 export class HeadlessTerm {
   constructor(cols = 100, rows = 32) {
     this.cols = cols; this.rows = rows;
@@ -132,7 +226,7 @@ export class HeadlessTerm {
   }
   open() {}
   close() {}
-  draw(lines) { this.frame = lines.slice(0, this.rows).map((l) => fit(l ?? '', this.cols)); this.frames++; }
+  draw(lines) { this.frame = lines.slice(0, this.rows).map((l, i) => takeMarks(fit(l ?? '', this.cols), i, new Map())); this.frames++; }
   /** Feed keys one at a time, as `decodeKeys` would produce them. */
   press(...keys) { for (const k of keys) this.onKey(k); }
   /** Type a string as individual character keys, then Enter. */

package/src/cli/text.mjs

@@ -16,8 +16,10 @@ export const orange = sgr('38;5;208');
 export const QUALITY = ['poor', 'common', 'uncommon', 'rare', 'epic', 'legendary', 'artifact'];
 // The client's item quality colours (24-bit): grey poor, white common, green uncommon, blue rare,
 // purple epic, orange legendary, light gold artifact.
-const rgb = (r, g, b) => sgr(`38;2;${r};${g};${b}`);
-const QUALITY_PAINT = [rgb(157, 157, 157), rgb(255, 255, 255), rgb(30, 255, 0), rgb(0, 112, 221), rgb(163, 53, 238), rgb(255, 128, 0), rgb(230, 204, 128)];
+const QUALITY_RGB = [[157, 157, 157], [255, 255, 255], [30, 255, 0], [0, 112, 221], [163, 53, 238], [255, 128, 0], [230, 204, 128]];
+const QUALITY_PAINT = QUALITY_RGB.map(([r, g, b]) => sgr(`38;2;${r};${g};${b}`));
+/** The quality colour as a bare SGR code, for a painter that builds its own escapes (an icon frame). */
+export function qualityCodes(quality) { const [r, g, b] = QUALITY_RGB[quality ?? 1] ?? QUALITY_RGB[1]; return `38;2;${r};${g};${b}`; }
 /** An item name in its 1.12 quality colour. */
 export function qualityPaint(quality) { return QUALITY_PAINT[quality ?? 1] ?? white; }
 /** An item record's name in its quality colour; `fallback` when the record is missing. */
@@ -51,7 +53,7 @@ export function wrapLines(text, width) {
   let open = '';
   return out.map((l) => {
     const line = open + l;
-    for (const m of l.match(SGR_RE) ?? []) open = m === '\x1b[0m' || m === '\x1b[m' ? '' : open + m;
+    for (const m of l.match(SGR_RE) ?? []) if (!m.startsWith('\x1b[9999;')) open = m === '\x1b[0m' || m === '\x1b[m' ? '' : open + m; // a sixel marker is no paint
     return open ? `${line}\x1b[0m` : line;
   });
 }