dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/tui/src/images/coin.js

@@ -0,0 +1,22 @@
+import { drawBlockArt, drawPlaceholder } from "./blocks.js";
+export function coinImage(c, s) {
+    if (s.w <= 0 || s.h <= 0)
+        return;
+    if (s.img && c.imageMode === 'pixels' && s.key) {
+        for (let cy = 0; cy < s.h; cy++)
+            for (let cx = 0; cx < s.w; cx++)
+                c.put(s.x + cx, s.y + cy, ' ', { fg: s.bg, bg: s.bg, hard: true });
+        c.noRain(s.x, s.y, s.w, s.h);
+        c.images.push({ key: s.key, x: s.x, y: s.y, w: s.w, h: s.h, img: s.img, png: s.png ?? null });
+        return;
+    }
+    if (s.img) {
+        drawBlockArt(c, s.x, s.y, s.w, s.h, s.img, { mode: s.mode, depth: s.depth, bg: s.bg, cacheKey: s.key ?? null });
+        return;
+    }
+    drawPlaceholder(c, s.x, s.y, s.w, s.h, s.symbol, { depth: s.depth, bg: s.bg, pending: s.pending });
+}
+/** Cell boxes the screens use: a one-row list icon and the token-header hero. */
+export const COIN_ICON_W = 2;
+export const COIN_HERO_W = 8;
+export const COIN_HERO_H = 4;

package/dist/packages/tui/src/images/detect.js

@@ -0,0 +1,140 @@
+/** Stage 1: the environment's verdict. Pure. */
+export function protocolFromEnv(env) {
+    const prog = (env.TERM_PROGRAM || '').toLowerCase();
+    const term = (env.TERM || '').toLowerCase();
+    const lcTerm = (env.LC_TERMINAL || '').toLowerCase();
+    // Multiplexers do not pass graphics through without extra setup: block art is the only safe answer.
+    if (env.TMUX || prog === 'tmux' || term.startsWith('tmux') || term.startsWith('screen') || env.STY)
+        return { protocol: 'blocks', reason: 'tmux/screen multiplexer (no graphics passthrough)' };
+    if (env.KITTY_WINDOW_ID || prog === 'kitty' || term === 'xterm-kitty')
+        return { protocol: 'kitty', reason: 'kitty' };
+    if (prog === 'ghostty' || term === 'xterm-ghostty' || env.GHOSTTY_RESOURCES_DIR)
+        return { protocol: 'kitty', reason: 'Ghostty (kitty graphics)' };
+    if (prog === 'wezterm' || env.WEZTERM_EXECUTABLE)
+        return { protocol: 'kitty', reason: 'WezTerm (kitty graphics)' };
+    if (env.KONSOLE_VERSION)
+        return { protocol: 'kitty', reason: 'Konsole (kitty graphics)' };
+    if (prog === 'iterm.app' || lcTerm === 'iterm2')
+        return { protocol: 'iterm', reason: 'iTerm2 (inline images)' };
+    if (prog === 'apple_terminal')
+        return { protocol: 'blocks', reason: 'Apple Terminal.app has no inline-image protocol' };
+    if (prog === 'vscode' || env.VSCODE_INJECTION)
+        return { protocol: 'blocks', reason: 'VS Code terminal (images off by default)' };
+    if (env.WT_SESSION)
+        return { protocol: 'blocks', reason: 'Windows Terminal (sixel only when advertised)' };
+    return { protocol: 'blocks', reason: `unknown terminal (${env.TERM_PROGRAM || env.TERM || 'no TERM'})` };
+}
+/** The probe bytes written to the tty: kitty query, cell-size report, DA1 (always answered last). */
+export const CAPABILITY_QUERY = '\x1b_Gi=31,s=1,v=1,a=q,t=d,f=24;AAAA\x1b\\\x1b[16t\x1b[c';
+/**
+ * Stage 2 parser, pure: scan a reply buffer for the kitty acknowledgement, the `CSI 6;h;w t` cell size and
+ * the DA1 `CSI ? … c` line; sixel is advertised as parameter 4 in DA1. Returns how many bytes belong to
+ * the replies (the rest is user input). `done` is true once DA1 arrived.
+ */
+export function parseQueryReply(buf) {
+    let kittyOk = false, sixel = false, da1 = null, cellPx = null;
+    let consumed = 0;
+    let i = 0;
+    while (i < buf.length) {
+        if (buf[i] !== '\x1b') {
+            i += 1;
+            continue;
+        }
+        // APC: ESC _ ... ESC \  (kitty reply: ESC_Gi=31;OK ESC\)
+        if (buf[i + 1] === '_') {
+            const end = buf.indexOf('\x1b\\', i + 2);
+            if (end < 0)
+                break; // partial
+            const body = buf.slice(i + 2, end);
+            if (/^Gi=31;OK/.test(body))
+                kittyOk = true;
+            i = end + 2;
+            consumed = i;
+            continue;
+        }
+        if (buf[i + 1] === '[') {
+            let j = i + 2;
+            while (j < buf.length && /[0-9;?]/.test(buf[j]))
+                j += 1;
+            const fin = buf[j];
+            if (fin === undefined)
+                break; // partial CSI
+            const params = buf.slice(i + 2, j);
+            if (fin === 't') {
+                const m = /^6;(\d+);(\d+)$/.exec(params);
+                if (m)
+                    cellPx = { h: Number(m[1]), w: Number(m[2]) };
+                i = j + 1;
+                consumed = i;
+                continue;
+            }
+            if (fin === 'c' && params.startsWith('?')) {
+                da1 = params;
+                const ps = params.slice(1).split(';');
+                sixel = ps.includes('4');
+                i = j + 1;
+                consumed = i;
+                return { facts: { kittyOk, sixel, da1, cellPx, consumed }, done: true };
+            }
+            // some other CSI (a key?): not ours — stop consuming here
+            break;
+        }
+        break;
+    }
+    return { facts: { kittyOk, sixel, da1, cellPx, consumed }, done: false };
+}
+/** Stage 1 + 2 verdict, pure given the query facts. */
+export function resolveProtocol(env, q) {
+    const e = protocolFromEnv(env);
+    const forced = (env.DEXTERM_IMAGES || '').toLowerCase();
+    if (forced === 'kitty' || forced === 'iterm' || forced === 'sixel' || forced === 'blocks')
+        return { protocol: forced, cellPx: q?.cellPx ?? null, reason: `DEXTERM_IMAGES=${forced}`, envProtocol: e.protocol, ...(q ? { query: q } : {}) };
+    if (e.reason.startsWith('tmux'))
+        return { protocol: 'blocks', cellPx: q?.cellPx ?? null, reason: e.reason, envProtocol: e.protocol, ...(q ? { query: q } : {}) };
+    if (q?.kittyOk)
+        return { protocol: 'kitty', cellPx: q.cellPx, reason: 'terminal answered the kitty graphics query', envProtocol: e.protocol, query: q };
+    if (e.protocol === 'kitty' && (!q || q.timedOut))
+        return { protocol: 'kitty', cellPx: q?.cellPx ?? null, reason: `${e.reason}; query unanswered, trusting the environment`, envProtocol: e.protocol, ...(q ? { query: q } : {}) };
+    if (e.protocol === 'kitty' && q && !q.kittyOk)
+        return { protocol: q.sixel ? 'sixel' : 'blocks', cellPx: q.cellPx, reason: `${e.reason} but the kitty query was refused`, envProtocol: e.protocol, query: q };
+    if (e.protocol === 'iterm')
+        return { protocol: 'iterm', cellPx: q?.cellPx ?? null, reason: e.reason, envProtocol: e.protocol, ...(q ? { query: q } : {}) };
+    if (q?.sixel)
+        return { protocol: 'sixel', cellPx: q.cellPx, reason: 'DA1 advertises sixel', envProtocol: e.protocol, query: q };
+    return { protocol: 'blocks', cellPx: q?.cellPx ?? null, reason: e.reason, envProtocol: e.protocol, ...(q ? { query: q } : {}) };
+}
+/**
+ * Run the capability query on a raw-mode tty. Resolves with the facts plus any trailing bytes that were
+ * NOT part of a reply (early keypresses), so the caller can feed them to its key parser. Never rejects.
+ */
+export function queryTerminal(io, timeoutMs = 150) {
+    const now = io.now ?? (() => Date.now());
+    const t0 = now();
+    return new Promise((resolve) => {
+        let buf = '';
+        let settled = false;
+        let off = () => { };
+        const finish = (timedOut) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            off();
+            const { facts } = parseQueryReply(buf);
+            resolve({ facts: { ...facts, elapsedMs: now() - t0, timedOut }, leftover: buf.slice(facts.consumed) });
+        };
+        const timer = setTimeout(() => finish(true), timeoutMs);
+        timer.unref?.();
+        off = io.onData((chunk) => {
+            buf += chunk;
+            if (parseQueryReply(buf).done)
+                finish(false);
+        });
+        try {
+            io.write(CAPABILITY_QUERY);
+        }
+        catch {
+            finish(true);
+        }
+    });
+}

package/dist/packages/tui/src/images/index.js

@@ -0,0 +1,7 @@
+// @dexterm/tui — coin images in the terminal (task-1326).
+export { protocolFromEnv, parseQueryReply, resolveProtocol, queryTerminal, CAPABILITY_QUERY } from "./detect.js";
+export { sampleGrid, ditherTo256, nearest256, gridHex, luma, flattenTo, resampleRgba } from "./pixels.js";
+export { drawBlockArt, drawPlaceholder, placeholderColor, placeholderInitial } from "./blocks.js";
+export { cup, kittyTransmit, kittyPlace, kittyDeletePlacement, kittyDeleteAllPlacements, kittyFreeAll, itermInline, sixelEncode, KITTY_CHUNK } from "./protocols.js";
+export { ImageLayer } from "./layer.js";
+export { coinImage, COIN_ICON_W, COIN_HERO_W, COIN_HERO_H } from "./coin.js";

package/dist/packages/tui/src/images/layer.js

@@ -0,0 +1,146 @@
+import { flattenTo, resampleRgba } from "./pixels.js";
+import { cup, kittyTransmit, kittyPlace, kittyDeletePlacement, kittyDeleteAllPlacements, kittyFreeAll, itermInline, sixelEncode } from "./protocols.js";
+export class ImageLayer {
+    protocol;
+    opts;
+    ids = new Map();
+    transmitted = new Set();
+    placements = [];
+    drawn = new Map(); // iterm/sixel: "x,y" → key
+    nextId = 1000;
+    nextPid = 1;
+    lastScreen = null;
+    /** Counters for the handoff / measurements. */
+    stats = { transmits: 0, places: 0, deletes: 0, emits: 0, bytes: 0 };
+    constructor(protocol, opts) {
+        this.protocol = protocol;
+        this.opts = opts;
+    }
+    idFor(key) {
+        let id = this.ids.get(key);
+        if (id === undefined) {
+            id = this.nextId++;
+            this.ids.set(key, id);
+        }
+        return id;
+    }
+    /** Largest pixel box for a `w × h` cell slot: square-ish, bounded by maxPx. */
+    pixelBox(w, h) {
+        const cell = this.opts.cellPx ?? { w: 9, h: 18 };
+        const maxPx = this.opts.maxPx ?? 144;
+        const bw = w * cell.w, bh = h * cell.h;
+        const side = Math.min(bw, bh, maxPx);
+        return { pw: Math.max(1, Math.round(side)), ph: Math.max(1, Math.round(side)) };
+    }
+    /** Bytes to write after a flush. */
+    sync(input) {
+        let out = '';
+        const slots = dedupe(input.slots);
+        if (this.protocol === 'kitty') {
+            const full = input.changed === 'all';
+            if (this.lastScreen !== null && (input.screen !== this.lastScreen || full)) {
+                if (this.placements.length) {
+                    out += kittyDeleteAllPlacements();
+                    this.stats.deletes += this.placements.length;
+                }
+                this.placements = [];
+            }
+            this.lastScreen = input.screen;
+            const keep = [];
+            const want = new Map();
+            for (const s of slots)
+                want.set(`${s.key}@${s.x},${s.y},${s.w},${s.h}`, s);
+            for (const p of this.placements) {
+                const k = `${p.key}@${p.x},${p.y},${p.w},${p.h}`;
+                if (want.has(k)) {
+                    keep.push(p);
+                    want.delete(k);
+                }
+                else {
+                    out += kittyDeletePlacement(p.id, p.pid);
+                    this.stats.deletes += 1;
+                }
+            }
+            for (const s of want.values()) {
+                const id = this.idFor(s.key);
+                if (!this.transmitted.has(id)) {
+                    const { pw, ph } = this.pixelBox(s.w, s.h);
+                    const small = s.img.w > pw * 2 || s.img.h > ph * 2 ? resampleRgba(s.img, Math.min(s.img.w, pw * 2), Math.min(s.img.h, ph * 2)) : s.img;
+                    const t = kittyTransmit(id, small);
+                    out += t;
+                    this.stats.transmits += 1;
+                    this.stats.bytes += t.length;
+                    this.transmitted.add(id);
+                }
+                const pid = this.nextPid++;
+                out += cup(s.y, s.x) + kittyPlace(id, pid, s.w, s.h);
+                this.stats.places += 1;
+                keep.push({ key: s.key, x: s.x, y: s.y, w: s.w, h: s.h, id, pid });
+            }
+            this.placements = keep;
+            return out;
+        }
+        // iterm / sixel: cell-bound images
+        const changed = input.changed;
+        const nextDrawn = new Map();
+        for (const s of slots) {
+            const pos = `${s.x},${s.y}`;
+            let rowsChanged = changed === 'all';
+            if (!rowsChanged)
+                for (let y = s.y; y < s.y + s.h; y++)
+                    if (changed[y]) {
+                        rowsChanged = true;
+                        break;
+                    }
+            const isNew = this.drawn.get(pos) !== s.key;
+            if (rowsChanged || isNew) {
+                const { pw, ph } = this.pixelBox(s.w, s.h);
+                let seq;
+                if (this.protocol === 'iterm') {
+                    const png = s.png ?? (this.opts.encodePng ? this.opts.encodePng(resampleRgba(s.img, Math.min(s.img.w, pw * 2), Math.min(s.img.h, ph * 2))) : null);
+                    if (!png)
+                        continue;
+                    seq = itermInline(png, s.w, s.h);
+                }
+                else {
+                    // sixel has no alpha: flatten over the theme bg; height rounded down to a 6-row band multiple
+                    const sh = Math.max(6, Math.floor(ph / 6) * 6);
+                    seq = sixelEncode(flattenTo(s.img, pw, sh, this.opts.bg()));
+                }
+                out += cup(s.y, s.x) + seq;
+                this.stats.emits += 1;
+                this.stats.bytes += seq.length;
+            }
+            nextDrawn.set(pos, s.key);
+        }
+        this.drawn = nextDrawn;
+        return out;
+    }
+    /** Screen is about to change: forget cell-bound images (their rows will be rewritten). */
+    invalidate() { this.drawn.clear(); }
+    /** Everything off the screen; kitty also frees transmitted data. */
+    teardown() {
+        this.drawn.clear();
+        if (this.protocol !== 'kitty')
+            return '';
+        const had = this.placements.length > 0 || this.transmitted.size > 0;
+        this.placements = [];
+        this.transmitted.clear();
+        this.ids.clear();
+        return had ? kittyFreeAll() : '';
+    }
+}
+function dedupe(slots) {
+    const seen = new Set();
+    const out = [];
+    for (const s of slots) {
+        if (s.w <= 0 || s.h <= 0)
+            continue;
+        const k = `${s.x},${s.y}`;
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(s);
+    }
+    return out;
+}

package/dist/packages/tui/src/images/pixels.js

@@ -0,0 +1,157 @@
+// @dexterm/tui — pixel helpers for the terminal image renderers (task-1326). Pure, dependency-free
+// (the data package owns decoding; this file only needs an RGBA buffer). Compositing over the theme
+// background, area-average sampling to a tiny grid, 256-colour quantisation with error diffusion.
+import { hexToRgb, rgbToHex } from "../color.js";
+/** Area-average the source over a `w × h` grid, compositing alpha over `bg`. Returns packed RGB rows. */
+export function sampleGrid(img, w, h, bg) {
+    const [br, bgG, bb] = hexToRgb(bg);
+    const out = new Float32Array(w * h * 3);
+    const xs = img.w / w, ys = img.h / h;
+    for (let y = 0; y < h; y++) {
+        const y0 = y * ys, y1 = (y + 1) * ys;
+        for (let x = 0; x < w; x++) {
+            const x0 = x * xs, x1 = (x + 1) * xs;
+            let r = 0, g = 0, b = 0, a = 0, wsum = 0;
+            for (let sy = Math.floor(y0); sy < Math.min(img.h, Math.ceil(y1)); sy++) {
+                const wy = Math.min(y1, sy + 1) - Math.max(y0, sy);
+                if (wy <= 0)
+                    continue;
+                for (let sx = Math.floor(x0); sx < Math.min(img.w, Math.ceil(x1)); sx++) {
+                    const wx = Math.min(x1, sx + 1) - Math.max(x0, sx);
+                    if (wx <= 0)
+                        continue;
+                    const wgt = wx * wy, o = (sy * img.w + sx) * 4, al = img.rgba[o + 3] / 255;
+                    r += img.rgba[o] * al * wgt;
+                    g += img.rgba[o + 1] * al * wgt;
+                    b += img.rgba[o + 2] * al * wgt;
+                    a += al * wgt;
+                    wsum += wgt;
+                }
+            }
+            const oo = (y * w + x) * 3;
+            if (wsum <= 0) {
+                out[oo] = br;
+                out[oo + 1] = bgG;
+                out[oo + 2] = bb;
+                continue;
+            }
+            const cov = a / wsum; // coverage 0..1
+            const cr = a > 0 ? r / a : 0, cg = a > 0 ? g / a : 0, cb = a > 0 ? b / a : 0;
+            out[oo] = cr * cov + br * (1 - cov);
+            out[oo + 1] = cg * cov + bgG * (1 - cov);
+            out[oo + 2] = cb * cov + bb * (1 - cov);
+        }
+    }
+    return out;
+}
+// xterm-256: 6×6×6 cube (16..231) + 24 greys (232..255). Same tables as color.ts hexToAnsi256.
+const CUBE = [0, 95, 135, 175, 215, 255];
+const GREYS = Array.from({ length: 24 }, (_, i) => 8 + 10 * i);
+/** Nearest xterm-256 colour (as RGB) to an RGB triple: cube or grey, whichever is closer. */
+export function nearest256(r, g, b) {
+    const ci = (v) => { let best = 0, bd = Infinity; for (let i = 0; i < 6; i++) {
+        const d = Math.abs(CUBE[i] - v);
+        if (d < bd) {
+            bd = d;
+            best = i;
+        }
+    } return CUBE[best]; };
+    const cr = ci(r), cg = ci(g), cb = ci(b);
+    const cubeD = (cr - r) ** 2 + (cg - g) ** 2 + (cb - b) ** 2;
+    const avg = (r + g + b) / 3;
+    let gi = Math.round((avg - 8) / 10);
+    gi = Math.max(0, Math.min(23, gi));
+    const gv = GREYS[gi];
+    const greyD = (gv - r) ** 2 + (gv - g) ** 2 + (gv - b) ** 2;
+    return greyD < cubeD ? [gv, gv, gv] : [cr, cg, cb];
+}
+/**
+ * Quantise a sampled grid to the 256-colour palette with Floyd–Steinberg error diffusion. The palette
+ * cube is coarse (6 levels), so without diffusion a round logo on a dark panel turns into one flat blob;
+ * with it the tone gradients that make a disc read as a disc survive. Error is clamped so a single hot
+ * pixel cannot smear across the icon. In place; returns the same array.
+ */
+export function ditherTo256(grid, w, h, strength = 0.75) {
+    const err = new Float32Array((w + 2) * 3 * 2); // two rows of error, 1px padding each side
+    const idx = (row, x) => (row * (w + 2) + x + 1) * 3;
+    for (let y = 0; y < h; y++) {
+        const cur = y & 1, nxt = cur ^ 1;
+        for (let x = -1; x <= w; x++) {
+            const o = idx(nxt, x);
+            err[o] = 0;
+            err[o + 1] = 0;
+            err[o + 2] = 0;
+        }
+        for (let x = 0; x < w; x++) {
+            const o = (y * w + x) * 3, e = idx(cur, x);
+            const r = Math.max(0, Math.min(255, grid[o] + err[e])), g = Math.max(0, Math.min(255, grid[o + 1] + err[e + 1])), b = Math.max(0, Math.min(255, grid[o + 2] + err[e + 2]));
+            const [qr, qg, qb] = nearest256(r, g, b);
+            grid[o] = qr;
+            grid[o + 1] = qg;
+            grid[o + 2] = qb;
+            const dr = Math.max(-48, Math.min(48, (r - qr) * strength)), dg = Math.max(-48, Math.min(48, (g - qg) * strength)), db = Math.max(-48, Math.min(48, (b - qb) * strength));
+            const spread = (row, xx, f) => { const q = idx(row, xx); err[q] += dr * f; err[q + 1] += dg * f; err[q + 2] += db * f; };
+            spread(cur, x + 1, 7 / 16);
+            spread(nxt, x - 1, 3 / 16);
+            spread(nxt, x, 5 / 16);
+            spread(nxt, x + 1, 1 / 16);
+        }
+    }
+    return grid;
+}
+export function gridHex(grid, i) {
+    return rgbToHex(Math.round(grid[i * 3]), Math.round(grid[i * 3 + 1]), Math.round(grid[i * 3 + 2]));
+}
+/** Luma 0..255. */
+export function luma(r, g, b) { return 0.2126 * r + 0.7152 * g + 0.0722 * b; }
+/**
+ * Composite straight-alpha RGBA over an opaque background colour and resample to `w × h` (area average),
+ * returning an opaque RGBA buffer — what the pixel protocols (sixel, kitty RGB) and the HTML proof use.
+ */
+export function flattenTo(img, w, h, bg) {
+    const grid = sampleGrid(img, w, h, bg);
+    const rgba = new Uint8Array(w * h * 4);
+    for (let i = 0; i < w * h; i++) {
+        rgba[i * 4] = Math.round(grid[i * 3]);
+        rgba[i * 4 + 1] = Math.round(grid[i * 3 + 1]);
+        rgba[i * 4 + 2] = Math.round(grid[i * 3 + 2]);
+        rgba[i * 4 + 3] = 255;
+    }
+    return { w, h, rgba };
+}
+/** Area-average resample keeping alpha (for kitty RGBA placements that let the terminal composite). */
+export function resampleRgba(img, w, h) {
+    const out = new Uint8Array(w * h * 4);
+    const xs = img.w / w, ys = img.h / h;
+    for (let y = 0; y < h; y++) {
+        const y0 = y * ys, y1 = (y + 1) * ys;
+        for (let x = 0; x < w; x++) {
+            const x0 = x * xs, x1 = (x + 1) * xs;
+            let r = 0, g = 0, b = 0, a = 0, wsum = 0;
+            for (let sy = Math.floor(y0); sy < Math.min(img.h, Math.ceil(y1)); sy++) {
+                const wy = Math.min(y1, sy + 1) - Math.max(y0, sy);
+                if (wy <= 0)
+                    continue;
+                for (let sx = Math.floor(x0); sx < Math.min(img.w, Math.ceil(x1)); sx++) {
+                    const wx = Math.min(x1, sx + 1) - Math.max(x0, sx);
+                    if (wx <= 0)
+                        continue;
+                    const wgt = wx * wy, o = (sy * img.w + sx) * 4, al = img.rgba[o + 3] / 255;
+                    r += img.rgba[o] * al * wgt;
+                    g += img.rgba[o + 1] * al * wgt;
+                    b += img.rgba[o + 2] * al * wgt;
+                    a += al * wgt;
+                    wsum += wgt;
+                }
+            }
+            const oo = (y * w + x) * 4;
+            if (wsum <= 0 || a <= 0)
+                continue;
+            out[oo] = Math.round(r / a);
+            out[oo + 1] = Math.round(g / a);
+            out[oo + 2] = Math.round(b / a);
+            out[oo + 3] = Math.round((a / wsum) * 255);
+        }
+    }
+    return { w, h, rgba: out };
+}

package/dist/packages/tui/src/images/protocols.js

@@ -0,0 +1,87 @@
+const ESC = '\x1b';
+export const KITTY_CHUNK = 4096;
+/** `CSI row;col H` (1-based). */
+export function cup(row, col) { return `${ESC}[${row + 1};${col + 1}H`; }
+// ---------------------------------------------------------------------------------------------- kitty
+/** Transmit straight-alpha RGBA as image `id` (no placement). Chunked at 4096 base64 bytes per APC. */
+export function kittyTransmit(id, img) {
+    const b64 = Buffer.from(img.rgba.buffer, img.rgba.byteOffset, img.rgba.byteLength).toString('base64');
+    let out = '';
+    for (let i = 0; i < b64.length; i += KITTY_CHUNK) {
+        const chunk = b64.slice(i, i + KITTY_CHUNK);
+        const more = i + KITTY_CHUNK < b64.length ? 1 : 0;
+        const ctl = i === 0 ? `a=t,f=32,s=${img.w},v=${img.h},i=${id},q=2,m=${more}` : `m=${more}`;
+        out += `${ESC}_G${ctl};${chunk}${ESC}\\`;
+    }
+    return out;
+}
+/** Place image `id` as placement `pid` over `cols × rows` cells at the cursor, cursor unmoved. */
+export function kittyPlace(id, pid, cols, rows) {
+    return `${ESC}_Ga=p,i=${id},p=${pid},c=${cols},r=${rows},C=1,q=2${ESC}\\`;
+}
+export function kittyDeletePlacement(id, pid) { return `${ESC}_Ga=d,d=i,i=${id},p=${pid},q=2${ESC}\\`; }
+/** Delete every visible placement, keep the transmitted data (screen change). */
+export function kittyDeleteAllPlacements() { return `${ESC}_Ga=d,d=a,q=2${ESC}\\`; }
+/** Delete every placement AND free the image data (quit). */
+export function kittyFreeAll() { return `${ESC}_Ga=d,d=A,q=2${ESC}\\`; }
+// ---------------------------------------------------------------------------------------------- iTerm2
+export function itermInline(png, cols, rows) {
+    const b64 = Buffer.from(png.buffer, png.byteOffset, png.byteLength).toString('base64');
+    return `${ESC}]1337;File=inline=1;size=${png.byteLength};width=${cols};height=${rows};preserveAspectRatio=1;doNotMoveCursor=1:${b64}\x07`;
+}
+// ---------------------------------------------------------------------------------------------- sixel
+/** Opaque pixels → a ≤ 252-colour sixel image (6×7×6 uniform levels; plenty for a thumbnail). */
+export function sixelEncode(img) {
+    const { w, h, rgba } = img;
+    if (w <= 0 || h <= 0)
+        return '';
+    const RL = 6, GL = 7, BL = 6;
+    const q = (v, levels) => Math.min(levels - 1, Math.round((v / 255) * (levels - 1)));
+    const idx = new Uint16Array(w * h);
+    const used = new Set();
+    for (let i = 0; i < w * h; i++) {
+        const r = q(rgba[i * 4], RL), g = q(rgba[i * 4 + 1], GL), b = q(rgba[i * 4 + 2], BL);
+        const k = (r * GL + g) * BL + b;
+        idx[i] = k;
+        used.add(k);
+    }
+    let out = `${ESC}P0;1q"1;1;${w};${h}`;
+    for (const k of used) {
+        const b = k % BL, g = Math.floor(k / BL) % GL, r = Math.floor(k / (BL * GL));
+        const pc = (v, levels) => Math.round((v / (levels - 1)) * 100);
+        out += `#${k};2;${pc(r, RL)};${pc(g, GL)};${pc(b, BL)}`;
+    }
+    for (let band = 0; band < h; band += 6) {
+        const rows = Math.min(6, h - band);
+        const bandColors = new Set();
+        for (let y = band; y < band + rows; y++)
+            for (let x = 0; x < w; x++)
+                bandColors.add(idx[y * w + x]);
+        let first = true;
+        for (const k of bandColors) {
+            if (!first)
+                out += '$';
+            first = false;
+            out += `#${k}`;
+            let run = 0, last = -1;
+            const flush = () => { if (run <= 0)
+                return; const ch = String.fromCharCode(63 + last); out += run > 3 ? `!${run}${ch}` : ch.repeat(run); run = 0; };
+            for (let x = 0; x < w; x++) {
+                let bits = 0;
+                for (let r = 0; r < rows; r++)
+                    if (idx[(band + r) * w + x] === k)
+                        bits |= 1 << r;
+                if (bits === last)
+                    run += 1;
+                else {
+                    flush();
+                    last = bits;
+                    run = 1;
+                }
+            }
+            flush();
+        }
+        out += '-';
+    }
+    return out + `${ESC}\\`;
+}

package/dist/packages/tui/src/index.js

@@ -0,0 +1,15 @@
+// @dexterm/tui — public surface.
+export * from "./color.js";
+export * from "./theme.js";
+export * from "./fmt.js";
+export * from "./canvas.js";
+export * from "./flush.js";
+export * from "./layout.js";
+export * from "./keymap.js";
+export * from "./widgets.js";
+export * from "./fx.js";
+export * from "./fx-trade.js";
+export * from "./sound.js";
+export * from "./bubbles.js";
+export * from "./chrome.js";
+export * from "./images/index.js";