jaitus 0.3.0

package/src/rewind.js

@@ -0,0 +1,130 @@
+// ─── Rewind: go back to any earlier turn ────────────────────────────────────────
+//
+// Esc+Esc rewinds the conversation to a previous point — and restores the files as
+// they were. The mechanism is simple and honest: before each user prompt
+// is processed, snapshot the message history; before any write/edit command the agent
+// makes, snapshot the file it is about to touch. Restoring a checkpoint then means
+// truncating the message array and copying the file bytes back.
+//
+// Snapshots live in memory for the session's life: this is undo, not backup. Files are
+// capped (count and size) so one `run_command` that rewrites a giant file cannot eat
+// the heap.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const MAX_FILE_SNAPSHOTS = 60;
+const MAX_FILE_BYTES = 2_000_000;
+
+/**
+ * The rewind journal for one session. Kept per-session so two windows on the same
+ * project never share checkpoints.
+ */
+export function createJournal() {
+  const checkpoints = []; // { seq, at, prompt, messages, files }
+  const fileSnapshots = []; // newest last, global cap
+  let seqCounter = 0;
+
+  return {
+    /** Snapshot the conversation before a user prompt is processed. */
+    checkpoint(messages, files = []) {
+      checkpoints.push({
+        seq: ++seqCounter,
+        at: new Date().toISOString(),
+        prompt: messages.filter((m) => m.role === 'user' && typeof m.content === 'string').at(-1)?.content?.slice(0, 120) || '',
+        messages: JSON.parse(JSON.stringify(messages)),
+        files,
+      });
+      if (checkpoints.length > 60) checkpoints.shift();
+    },
+
+    /** Remember a file's current bytes before the agent overwrites it. */
+    snapshotFile(absPath) {
+      if (fileSnapshots.length >= MAX_FILE_SNAPSHOTS) fileSnapshots.shift();
+      const seq = ++seqCounter; // monotonic: immune to clock granularity
+      const takenAt = new Date().toISOString();
+      try {
+        const stat = fs.statSync(absPath);
+        if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return;
+        fileSnapshots.push({ path: absPath, data: fs.readFileSync(absPath), takenAt, seq });
+      } catch {
+        // Unreadable or vanished — restoring means deleting it if it exists now.
+        fileSnapshots.push({ path: absPath, data: null, takenAt, seq });
+      }
+    },
+
+    /**
+     * Snapshot every file this journal has already seen, plus the session save file.
+     * Used before run_command: the shell can touch anything, but re-snapshotting
+     * known files is bounded and covers the session's own blast radius.
+     */
+    snapshotTracked(cwd) {
+      for (const snap of fileSnapshots) {
+        try { this.snapshotFile(snap.path); } catch { /* already counted */ }
+      }
+      try { this.snapshotFile(path.join(cwd, '.jaitus', 'session.json')); } catch { /* fine */ }
+    },
+
+    /**
+     * The most recent snapshot of one path, as text.
+     *
+     * The journal already holds what a file looked like before the agent touched it,
+     * which is exactly the "before" side of a diff — so showing what an edit actually
+     * did costs a lookup rather than a second read of the disk.
+     */
+    latestSnapshot(absPath) {
+      for (let i = fileSnapshots.length - 1; i >= 0; i--) {
+        if (fileSnapshots[i].path === absPath) {
+          return fileSnapshots[i].data ? fileSnapshots[i].data.toString('utf8') : '';
+        }
+      }
+      return null;
+    },
+
+    /** Turn summaries for the rewind dialog, oldest first. */
+    list() {
+      return checkpoints.map((cp, i) => ({ index: i, at: cp.at, prompt: cp.prompt, files: cp.files.length }));
+    },
+
+    /**
+     * Restore checkpoint `index`: truncate messages to that point and restore every
+     * file the agent changed after it. Returns what happened, for the transcript.
+     */
+    restore(index, messages) {
+      const cp = checkpoints[index];
+      if (!cp) return { ok: false, error: 'No such checkpoint.' };
+      const restored = [];
+      const deleted = [];
+      for (const snap of [...fileSnapshots].reverse()) {
+        if (snap.seq <= cp.seq) continue;
+        try {
+          if (snap.data) {
+            fs.mkdirSync(path.dirname(snap.path), { recursive: true });
+            fs.writeFileSync(snap.path, snap.data);
+            restored.push(snap.path);
+          } else if (fs.existsSync(snap.path)) {
+            fs.rmSync(snap.path);
+            deleted.push(snap.path);
+          }
+        } catch { /* best effort per file */ }
+      }
+      messages.length = 0;
+      messages.push(...JSON.parse(JSON.stringify(cp.messages)));
+      return { ok: true, restored, deleted, messageCount: cp.messages.length };
+    },
+
+    /** Drop all checkpoints (new session, /clear). */
+    reset() {
+      checkpoints.length = 0;
+      fileSnapshots.length = 0;
+    },
+  };
+}
+
+/** Human-friendly absolute-path display (short home, forward slashes). */
+export function displayPath(p) {
+  const home = os.homedir();
+  const s = String(p || '');
+  return s.startsWith(home) ? `~${s.slice(home.length)}` : s;
+}

package/src/session.js

@@ -0,0 +1,207 @@
+// ─── This device's Jaitus session ───────────────────────────────────────────────
+//
+// `jaitus login` leaves two tokens in ~/.jaitus/credentials.json: an ACCESS token good
+// for an hour, and a REFRESH token that buys the next pair and is retired when it does.
+// This file is the only code that touches them. Everything else asks for "a token that
+// works right now" and gets one — renewed here, silently, when its hour is up.
+//
+// Renewal is serialised across processes with a lock file. Two terminals running
+// `jaitus` share one credentials file; if both renewed the same pair at once, the server
+// would accept one and see the other presenting a retired token. It treats that as a
+// race for thirty seconds (and says so), but the lock means it almost never happens: the
+// second process waits, re-reads the file, and finds the pair the first one just saved.
+//
+// JAITUS_TOKEN, when set, is used as-is and never renewed — for the test harness and for
+// pointing one command at a local backend.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { HOME, loadCredentials, saveCredentials, clearCredentials, endpoints } from './config.js';
+import { JaitusError, fromGatewayBody, fromNetwork } from './errors.js';
+
+const DEVICE_FILE = path.join(HOME, 'device.json');
+const LOCK_FILE = path.join(HOME, 'refresh.lock');
+// Renew a little early: a token that expires between the check and the request is a
+// needless 401 and a retry.
+const EARLY_MS = 60 * 1000;
+const LOCK_STALE_MS = 15 * 1000;
+const LOCK_WAIT_MS = 10 * 1000;
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * A random id naming this machine to the server, made once and kept. It is what lets a
+ * second `jaitus login` on the same machine REPLACE the first session instead of adding
+ * another. Not a secret: it grants nothing on its own.
+ */
+export function deviceId() {
+  try {
+    const saved = JSON.parse(fs.readFileSync(DEVICE_FILE, 'utf8'));
+    if (typeof saved?.id === 'string' && /^[A-Za-z0-9_-]{8,80}$/.test(saved.id)) return saved.id;
+  } catch { /* first run */ }
+  const id = crypto.randomBytes(18).toString('base64url');
+  try {
+    fs.mkdirSync(HOME, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(DEVICE_FILE, JSON.stringify({ id, createdAt: new Date().toISOString() }, null, 2), { mode: 0o600 });
+  } catch { /* an unwritable home still signs in; it just cannot dedupe next time */ }
+  return id;
+}
+
+export function deviceName() {
+  return os.hostname().slice(0, 60);
+}
+
+/** Whether there is anything to sign requests with. */
+export function signedIn() {
+  if (process.env.JAITUS_TOKEN) return true;
+  const c = loadCredentials();
+  return Boolean(c?.refreshToken && c?.accessToken);
+}
+
+function fresh(creds) {
+  const at = Date.parse(creds?.accessExpiresAt || '');
+  return Boolean(creds?.accessToken) && Number.isFinite(at) && at - EARLY_MS > Date.now();
+}
+
+async function withLock(fn) {
+  fs.mkdirSync(HOME, { recursive: true, mode: 0o700 });
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  let fd = null;
+  while (fd === null) {
+    try {
+      fd = fs.openSync(LOCK_FILE, 'wx');
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      // A process that died holding the lock must not wedge every later one.
+      try {
+        if (Date.now() - fs.statSync(LOCK_FILE).mtimeMs > LOCK_STALE_MS) { fs.rmSync(LOCK_FILE, { force: true }); continue; }
+      } catch { continue; }
+      if (Date.now() > deadline) throw new JaitusError({ code: 'busy', message: 'Another Jaitus window is renewing your session. Try again.' });
+      await sleep(100);
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    try { fs.closeSync(fd); } catch { /* ignore */ }
+    try { fs.rmSync(LOCK_FILE, { force: true }); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Renew the pair. Returns the new access token, or throws a JaitusError. `rejected` is
+ * the access token the server just refused, if any: if the file already holds a
+ * different, fresh one, another process renewed first and there is nothing to do.
+ */
+async function renew({ rejected = null } = {}) {
+  return withLock(async () => {
+    const creds = loadCredentials();
+    if (!creds?.refreshToken) throw new JaitusError({ code: 'auth_required' });
+    if (fresh(creds) && creds.accessToken !== rejected) return creds.accessToken;
+
+    const { baseUrl } = endpoints();
+    let res;
+    try {
+      res = await fetch(`${baseUrl}/api/auth/cli/refresh`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'user-agent': 'jaitus-cli' },
+        body: JSON.stringify({ refreshToken: creds.refreshToken }),
+      });
+    } catch (cause) {
+      throw fromNetwork(cause);
+    }
+    const body = await res.json().catch(() => ({}));
+
+    if (res.ok && body?.data?.accessToken && body?.data?.refreshToken) {
+      saveCredentials({
+        ...creds,
+        accessToken: body.data.accessToken,
+        refreshToken: body.data.refreshToken,
+        accessExpiresAt: body.data.accessExpiresAt,
+      });
+      return body.data.accessToken;
+    }
+
+    const err = fromGatewayBody(res.status, body);
+    if (err.code === 'refresh_race' || res.status === 409) {
+      // Someone renewed this pair a moment ago without our lock (an older CLI, or a
+      // second machine sharing a home directory). Their pair is in the file now.
+      await sleep(250);
+      const after = loadCredentials();
+      if (after?.refreshToken && after.refreshToken !== creds.refreshToken) return after.accessToken;
+    }
+    if (res.status === 401) {
+      // The server has ended this session — signed out from the website, replaced by a
+      // newer login on this machine, or expired. The tokens are dead; keeping them
+      // would only make every command fail the same way.
+      clearCredentials();
+      throw new JaitusError({ code: 'session_expired', status: 401 });
+    }
+    throw err;
+  });
+}
+
+/**
+ * An access token that works right now, renewing it if its hour is (nearly) up.
+ * Pass `rejected` when the server just refused a token, to force a renewal.
+ */
+export async function accessToken({ rejected = null } = {}) {
+  if (process.env.JAITUS_TOKEN) return process.env.JAITUS_TOKEN.trim();
+  const creds = loadCredentials();
+  if (!creds?.refreshToken) throw new JaitusError({ code: 'auth_required' });
+  if (!rejected && fresh(creds)) return creds.accessToken;
+  // Another process may already have renewed: the file holds a different, fresh token.
+  if (rejected && fresh(creds) && creds.accessToken !== rejected) return creds.accessToken;
+  return renew({ rejected });
+}
+
+/**
+ * Run `send(token)`; if the server says the token is spent (its hour is up, or another
+ * process renewed the pair under us), renew once and send once more. Never loops.
+ */
+export async function withAuth(send) {
+  if (process.env.JAITUS_TOKEN) return send(process.env.JAITUS_TOKEN.trim());
+  const token = await accessToken();
+  const res = await send(token);
+  if (res.status !== 401) return res;
+
+  let code = '';
+  try { code = (await res.clone().json())?.error?.code || ''; } catch { /* not ours */ }
+  if (code !== 'jaitus_token_expired' && code !== 'jaitus_session_expired') return res;
+
+  let next;
+  try {
+    next = await accessToken({ rejected: token });
+  } catch (e) {
+    if (e?.code === 'session_expired' || e?.code === 'auth_required') return res;
+    throw e;
+  }
+  return send(next);
+}
+
+/**
+ * End this device's session on the server, then forget it here. The server call is best
+ * effort — offline, the local tokens are still removed and the session lapses on its own.
+ */
+export async function signOut() {
+  const creds = loadCredentials();
+  if (!creds?.refreshToken && !creds?.accessToken) return { hadSession: false, server: false };
+  const { baseUrl } = endpoints();
+  let server = false;
+  try {
+    const res = await fetch(`${baseUrl}/api/auth/cli/logout`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'user-agent': 'jaitus-cli',
+        ...(fresh(creds) ? { authorization: `Bearer ${creds.accessToken}` } : {}),
+      },
+      body: JSON.stringify({ refreshToken: creds.refreshToken }),
+    });
+    server = res.ok;
+  } catch { /* offline: the local copy still goes */ }
+  clearCredentials();
+  return { hadSession: true, server };
+}

package/src/sessions.js

@@ -0,0 +1,179 @@
+// ─── Local conversation sessions ───────────────────────────────────────────────
+//
+// A terminal session is durable: a closed terminal does not erase the work. Sessions
+// live in a small, inspectable JSON store under ~/.jaitus/sessions.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { SESSIONS } from './config.js';
+import { c } from './ui.js';
+
+function safeId(id) {
+  return String(id || '').replace(/[^a-zA-Z0-9_-]/g, '').slice(0, 80);
+}
+
+function fileFor(id) {
+  const clean = safeId(id);
+  if (!clean) return null;
+  return path.join(SESSIONS, `${clean}.json`);
+}
+
+export function newSession({ cwd, model, id = null } = {}) {
+  const sessionId = safeId(id) || crypto.randomUUID();
+  const now = new Date().toISOString();
+  return {
+    id: sessionId,
+    cwd: path.resolve(cwd || process.cwd()),
+    model: model || null,
+    createdAt: now,
+    updatedAt: now,
+    title: '',
+    messages: [],
+  };
+}
+
+export function saveSession(session) {
+  if (!session?.id) return;
+  fs.mkdirSync(SESSIONS, { recursive: true, mode: 0o700 });
+  const file = fileFor(session.id);
+  if (!file) return;
+  session.updatedAt = new Date().toISOString();
+  const snapshot = { ...session };
+  const temp = `${file}.tmp`;
+  fs.writeFileSync(temp, JSON.stringify(snapshot, null, 2), { mode: 0o600 });
+  fs.renameSync(temp, file);
+}
+
+export function loadSession(id) {
+  const file = fileFor(id);
+  if (!file) return null;
+  try {
+    const session = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!session?.id || !Array.isArray(session.messages)) return null;
+    return session;
+  } catch {
+    return null;
+  }
+}
+
+export function listSessions({ cwd = null } = {}) {
+  try {
+    return fs.readdirSync(SESSIONS)
+      .filter((name) => name.endsWith('.json'))
+      .map((name) => loadSession(name.slice(0, -5)))
+      .filter(Boolean)
+      .filter((session) => !cwd || path.resolve(session.cwd) === path.resolve(cwd))
+      .sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+  } catch {
+    return [];
+  }
+}
+
+export function latestSession({ cwd = null } = {}) {
+  return listSessions({ cwd })[0] || null;
+}
+
+/**
+ * Render a saved conversation back onto the screen: resuming must put the
+ * user into the same old session visibly, not just swap the model's memory.
+ * Tool calls replay as one dim summary row each; images ride silently.
+ */
+/**
+ * Put a saved conversation back on screen.
+ *
+ * Through the STRUCTURED api, not `print`. It used to flatten every turn into a
+ * pre-formatted ANSI string: a resumed session lost all its markdown, its code blocks
+ * became run-on prose, its newlines were replaced with spaces, and every tool call
+ * collapsed into one dim line of JSON. The conversation was all there in the file and
+ * none of it was legible — which is what "resume doesn't load the chat properly" is.
+ *
+ * Tool calls are replayed with the outcome recorded against them, so a call that failed
+ * still reads as failed rather than as a tick. The result text lives in the NEXT
+ * message's tool_result blocks, so those are indexed first and matched by id.
+ */
+export function replaySession(tui, messages) {
+  if (!tui || !Array.isArray(messages)) return 0;
+  tui.clearTranscript();
+  let shown = 0;
+
+  // tool_use_id → its result, from wherever it lands later in the conversation.
+  const results = new Map();
+  for (const m of messages) {
+    if (!Array.isArray(m?.content)) continue;
+    for (const b of m.content) {
+      if (b?.type === 'tool_result' && b.tool_use_id) {
+        results.set(b.tool_use_id, { text: String(b.content ?? ''), failed: !!b.is_error });
+      }
+    }
+  }
+
+  const structured = typeof tui.user === 'function' && typeof tui.assistant === 'function';
+
+  for (const m of messages) {
+    if (m.role === 'user') {
+      // A user message that is only tool results is the loop's bookkeeping, not
+      // something the user said; replaying it as a turn would invent one.
+      const text = typeof m.content === 'string'
+        ? m.content
+        : (Array.isArray(m.content) ? m.content : [])
+          .filter((b) => b?.type === 'text' && b.text)
+          .map((b) => b.text)
+          .join('\n\n');
+      if (!text.trim()) continue;
+      if (structured) tui.user(text); else tui.print(`\n${c.bold(c.brand('›'))} ${c.bold(text.replace(/\n/g, ' '))}`, 'user');
+      shown += 1;
+      continue;
+    }
+
+    if (m.role !== 'assistant') continue;
+    const blocks = Array.isArray(m.content) ? m.content : [];
+    const text = blocks.filter((b) => b?.type === 'text' && b.text).map((b) => b.text).join('\n\n');
+    if (text.trim()) {
+      if (structured) tui.assistant(text); else tui.print(`${c.brand('◆')} ${text}`, 'assistant');
+      shown += 1;
+    }
+    for (const call of blocks.filter((b) => b?.type === 'tool_use')) {
+      const outcome = results.get(call.id);
+      const label = summariseCall(call);
+      if (structured && tui.tool) {
+        tui.tool({
+          name: call.name,
+          label,
+          status: outcome ? (outcome.failed ? 'failed' : 'ok') : 'ok',
+          file: call.input?.path,
+          error: outcome?.failed ? outcome.text.split('\n')[0].slice(0, 200) : '',
+        });
+      } else {
+        tui.print(`  ${c.accent('✓')} ${c.dim(`${call.name} ${label}`.slice(0, 100))}`, 'tool');
+      }
+      shown += 1;
+    }
+  }
+  return shown;
+}
+
+/** The same one-line summary the live loop shows, without importing the tool table. */
+function summariseCall(call) {
+  const input = call.input && typeof call.input === 'object' ? call.input : {};
+  if (input.command) return String(input.command);
+  if (input.path) return String(input.path);
+  if (input.pattern) return String(input.pattern);
+  if (input.url) return String(input.url);
+  if (input.query) return String(input.query);
+  if (input.description) return String(input.description);
+  const json = JSON.stringify(input);
+  return json === '{}' ? call.name : json.replace(/\s+/g, ' ').slice(0, 90);
+}
+
+export function sessionSummary(session) {
+  const firstPrompt = session.messages?.find((m) => m.role === 'user' && typeof m.content === 'string')?.content;
+  return {
+    id: session.id,
+    title: session.title || firstPrompt?.replace(/\s+/g, ' ').slice(0, 80) || 'Untitled session',
+    cwd: session.cwd,
+    model: session.model,
+    messages: session.messages?.length || 0,
+    updatedAt: session.updatedAt,
+  };
+}

package/src/sixel.js

@@ -0,0 +1,131 @@
+// ─── The logo as a real image: sixel ────────────────────────────────────────────
+//
+// Sixel (DEC's 1980s graphics protocol) paints real pixels: the terminal allocates
+// colours into registers (`#<n>;2;<r>;<g>;<b>`, components 0-100), then six pixel-rows
+// at a time are emitted as one character each (codepoint 63 + 6 bit-flags, bit 0 = the
+// band's top row). Windows Terminal ≥ 1.22 renders the result inline; xterm, WezTerm,
+// foot and rio do too.
+//
+// Encoded from the checked-in pixel data rather than from a PNG at run time: zero
+// dependencies and one data format. The badge is a smooth gradient, so raw pixels
+// would need more colour registers than terminals provide; every channel is therefore
+// quantised (8/255 steps, coarsening if a terminal's 256-register budget would
+// overflow) before a register is spent on it.
+
+import { pixels, SIZE as MARK } from './logo-data.js';
+
+const MAX_REGISTERS = 250; // stay clear of the 256 every sixel terminal provides
+
+/** The 0-255 channel values this encoder is willing to spend a register on. */
+const quantise = (v, step) => Math.min(255, Math.round(v / step) * step);
+
+/**
+ * Encode the mark as a sixel sequence.
+ *
+ * @param {{maxWidth?: number, maxRows?: number}} opts
+ *   device-pixel caps; the image is integer-downscaled if it exceeds them. The mark's
+ *   native 125px fits any window, so the caps only matter for future bigger sources.
+ * @returns {string} the complete escape sequence, ready for stdout
+ */
+export function markSixel({ maxWidth = 480, maxRows = 240 } = {}) {
+  const src = pixels();
+  const W = MARK.width;
+  const H = MARK.height;
+
+  let scale = 1;
+  while (W / scale > maxWidth || H / scale > maxRows) scale++;
+
+  const cw = Math.floor(W / scale);
+  const chh = Math.floor(H / scale);
+
+  // Register assignment: quantise at 8, coarsen until the palette fits the budget.
+  // One flat pass per step is cheap (15,625 pixels worst case) and keeps the code
+  // honest — no cleverness to get wrong.
+  let reg = null;
+  for (const step of [8, 16, 32, 64]) {
+    const map = new Map();
+    const assigned = new Uint16Array(cw * chh).fill(0xffff);
+    let next = 0;
+    for (let y = 0; y < chh; y++) {
+      for (let x = 0; x < cw; x++) {
+        // Box over the scale×scale source block; opaque wins if any source pixel is.
+        let r = 0; let g = 0; let b = 0; let n = 0;
+        for (let dy = 0; dy < scale; dy++) {
+          for (let dx = 0; dx < scale; dx++) {
+            const s = (y * scale + dy) * W + (x * scale + dx);
+            if (!src.opaque[s]) continue;
+            r += src.rgb[s * 3]; g += src.rgb[s * 3 + 1]; b += src.rgb[s * 3 + 2]; n++;
+          }
+        }
+        if (!n) continue;
+        r = quantise(r / n, step); g = quantise(g / n, step); b = quantise(b / n, step);
+        const key = (r << 16) | (g << 8) | b;
+        let idx = map.get(key);
+        if (idx === undefined) {
+          idx = next++;
+          map.set(key, idx);
+        }
+        assigned[y * cw + x] = idx;
+      }
+    }
+    if (next <= MAX_REGISTERS || step === 64) {
+      reg = { map, assigned, count: next };
+      break;
+    }
+  }
+  if (!reg || !reg.count) return '';
+
+  // Header: sixel intro, 1:1 raster aspect, full extent.
+  const out = ['\x1bPq', `"1;1;${cw};${chh}`];
+  for (const [key, idx] of reg.map) {
+    const r = (key >> 16) & 0xff; const g = (key >> 8) & 0xff; const b = key & 0xff;
+    // Sixel components are 0-100.
+    out.push(`#${idx};2;${Math.round(r * 100 / 255)};${Math.round(g * 100 / 255)};${Math.round(b * 100 / 255)}`);
+  }
+
+  // Bands of six rows. Each column of the band belongs to exactly one register (a
+  // pixel has one colour) or none (transparent). Walk the band column by column and
+  // emit runs of identical (register, mask): `#idx` switches the pen, `!N?` skips
+  // transparent columns — a pen switch does NOT move the cursor, so gaps must be
+  // skipped explicitly or every later colour paints shifted left.
+  const bands = Math.ceil(chh / 6);
+  for (let band = 0; band < bands; band++) {
+    const rows = Math.min(6, chh - band * 6);
+    const colReg = new Int16Array(cw).fill(-1);
+    const colMask = new Uint8Array(cw);
+    for (let y = 0; y < rows; y++) {
+      const row = band * 6 + y;
+      for (let x = 0; x < cw; x++) {
+        const idx = reg.assigned[row * cw + x];
+        if (idx === 0xffff) continue;
+        colReg[x] = idx;
+        colMask[x] |= 1 << y;
+      }
+    }
+    out.push('$');
+    let x = 0;
+    let pen = -1;
+    while (x < cw) {
+      if (colReg[x] === -1) {
+        let gap = 1;
+        while (x + gap < cw && colReg[x + gap] === -1) gap++;
+        out.push(gap > 3 ? `!${gap}?` : '?'.repeat(gap));
+        x += gap;
+        continue;
+      }
+      if (colReg[x] !== pen) {
+        pen = colReg[x];
+        out.push(`#${pen}`);
+      }
+      let run = 1;
+      while (x + run < cw && colReg[x + run] === pen && colMask[x + run] === colMask[x]) run++;
+      const ch6 = String.fromCharCode(63 + colMask[x]);
+      out.push(run > 3 ? `!${run}${ch6}` : ch6.repeat(run));
+      x += run;
+    }
+    if (band < bands - 1) out.push('-');
+  }
+
+  out.push('\x1b\\');
+  return out.join('');
+}