subrouter-cli 0.0.0-stage → 0.1.0

package/test/client.test.ts

@@ -0,0 +1,327 @@
+// M6: RouterClient against a local HTTP server — error envelope, retry policy,
+// Retry-After handling, dialect routing, and the pure helpers. Fully offline.
+
+import assert from 'node:assert/strict';
+import http from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { describe, it } from 'node:test';
+import {
+  RouterClient,
+  RouterError,
+  dialectFor,
+  errorMessage,
+  parseModelCatalog,
+  rootFromBase,
+  statusHint,
+  routerErrorFromResponse,
+} from '../src/client.ts';
+
+const KEY = 'sk-sub-test-0000000000';
+const OPENAI_OK = {
+  choices: [{ message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }],
+  usage: { prompt_tokens: 1, completion_tokens: 1 },
+};
+const ANTHROPIC_OK = {
+  content: [{ type: 'text', text: 'hi' }],
+  stop_reason: 'end_turn',
+  usage: { input_tokens: 2, output_tokens: 1 },
+};
+
+interface CannedServer {
+  baseUrl: string; // http://127.0.0.1:PORT/v1
+  requests: { method: string; url: string; headers: http.IncomingHttpHeaders }[];
+  close: () => Promise<void>;
+}
+
+type Handler = (req: http.IncomingMessage, res: http.ServerResponse, n: number) => void;
+
+async function startServer(handler: Handler): Promise<CannedServer> {
+  const requests: CannedServer['requests'] = [];
+  const server = http.createServer((req, res) => {
+    requests.push({ method: req.method ?? '', url: req.url ?? '', headers: req.headers });
+    handler(req, res, requests.length);
+  });
+  await new Promise<void>((r) => server.listen(0, '127.0.0.1', r));
+  const port = (server.address() as AddressInfo).port;
+  return {
+    baseUrl: `http://127.0.0.1:${port}/v1`,
+    requests,
+    close: () => new Promise((r) => server.close(() => r())),
+  };
+}
+
+function send(res: http.ServerResponse, status: number, body: unknown, headers: Record<string, string> = {}): void {
+  res.writeHead(status, { 'content-type': 'application/json', ...headers });
+  res.end(typeof body === 'string' ? body : JSON.stringify(body));
+}
+
+function client(baseUrl: string, sleeps?: number[]): { c: RouterClient; sleeps: number[] } {
+  const log: number[] = sleeps ?? [];
+  return {
+    c: new RouterClient({ baseUrl, apiKey: KEY, sleep: (ms) => (log.push(ms), Promise.resolve()) }),
+    sleeps: log,
+  };
+}
+
+describe('error envelope + no-retry statuses', () => {
+  it('400 maps {"error":{"message"}} to RouterError without retrying', async (t) => {
+    const srv = await startServer((_req, res) => send(res, 400, { error: { message: 'bad model' } }));
+    t.after(() => srv.close());
+    const { c } = client(srv.baseUrl);
+    await assert.rejects(
+      c.complete({ model: 'gpt-x', dialect: 'openai', messages: [{ role: 'user', content: 'hi' }] }),
+      (err: RouterError) => err instanceof RouterError && err.status === 400 && err.message === 'bad model',
+    );
+    assert.equal(srv.requests.length, 1); // 400 is never retried
+  });
+
+  it('401 and 403 pass through with one request each', async (t) => {
+    let n401 = 0;
+    let n403 = 0;
+    const srv = await startServer((_req, res, n) => {
+      if (n === 1) {
+        n401++;
+        send(res, 401, { error: { message: 'bad key' } });
+      } else {
+        n403++;
+        send(res, 403, { error: { message: 'not allowlisted' } });
+      }
+    });
+    t.after(() => srv.close());
+    const { c } = client(srv.baseUrl);
+    const req = { model: 'gpt-x', dialect: 'openai' as const, messages: [{ role: 'user' as const, content: 'hi' }] };
+    await assert.rejects(c.complete(req), (err: RouterError) => err.status === 401);
+    await assert.rejects(c.complete(req), (err: RouterError) => err.status === 403 && err.message === 'not allowlisted');
+    assert.deepEqual([n401, n403, srv.requests.length], [1, 1, 2]);
+  });
+
+  it('bounds error text and falls back to the status hint when the body is unreadable', async () => {
+    // a parseable message longer than 1000 chars gets bounded()'d
+    const err = await routerErrorFromResponse(
+      502,
+      new Response(JSON.stringify({ error: { message: 'x'.repeat(3000) } }), { status: 502 }),
+    );
+    assert.equal(err.message.length, 1001); // 1000 chars capped with '…'
+    // a body over the 4 KB drain cap truncates the JSON — hint instead of garbage
+    const drained = await routerErrorFromResponse(
+      502,
+      new Response(JSON.stringify({ error: { message: 'x'.repeat(5000) } }), { status: 502 }),
+    );
+    assert.equal(drained.message, statusHint(502));
+    const bare = await routerErrorFromResponse(503, new Response('not json', { status: 503 }));
+    assert.equal(bare.message, statusHint(503));
+  });
+});
+
+describe('retry policy', () => {
+  const REQ = { model: 'gpt-x', dialect: 'openai' as const, messages: [{ role: 'user' as const, content: 'hi' }] };
+
+  it('429 with digit Retry-After waits exactly that many seconds and retries once', async (t) => {
+    const srv = await startServer((_req, res, n) => {
+      if (n === 1) send(res, 429, { error: { message: 'slow down' } }, { 'retry-after': '1' });
+      else send(res, 200, OPENAI_OK);
+    });
+    t.after(() => srv.close());
+    const { c, sleeps } = client(srv.baseUrl);
+    const turn = await c.complete(REQ);
+    assert.equal(turn.message.content, 'ok');
+    assert.deepEqual(sleeps, [1000]);
+    assert.equal(srv.requests.length, 2);
+  });
+
+  it('429 without Retry-After waits the 2s default', async (t) => {
+    const srv = await startServer((_req, res, n) => {
+      if (n === 1) send(res, 429, { error: { message: 'slow down' } });
+      else send(res, 200, OPENAI_OK);
+    });
+    t.after(() => srv.close());
+    const { c, sleeps } = client(srv.baseUrl);
+    await c.complete(REQ);
+    assert.deepEqual(sleeps, [2000]);
+  });
+
+  it('caps Retry-After at 60s and rejects non-digit headers', async () => {
+    const capped = await routerErrorFromResponse(
+      429,
+      new Response(JSON.stringify({ error: { message: 'slow' } }), { status: 429, headers: { 'retry-after': '120' } }),
+    );
+    assert.equal(capped.retryAfterSeconds, 60);
+    assert.match(capped.message, /Retry after 60 seconds\./);
+    const dated = await routerErrorFromResponse(
+      429,
+      new Response(JSON.stringify({ error: { message: 'slow' } }), {
+        status: 429,
+        headers: { 'retry-after': 'Wed, 21 Oct 2026 07:28:00 GMT' },
+      }),
+    );
+    assert.equal(dated.retryAfterSeconds, undefined);
+    assert.doesNotMatch(dated.message, /Retry after/); // delta-seconds only (Swift parity)
+  });
+
+  it('502 retries once after 1s', async (t) => {
+    const srv = await startServer((_req, res, n) => {
+      if (n === 1) send(res, 502, { error: { message: 'provider down' } });
+      else send(res, 200, OPENAI_OK);
+    });
+    t.after(() => srv.close());
+    const { c, sleeps } = client(srv.baseUrl);
+    await c.complete(REQ);
+    assert.deepEqual(sleeps, [1000]);
+    assert.equal(srv.requests.length, 2);
+  });
+
+  it('network failure (fetch TypeError) retries once', async (t) => {
+    const srv = await startServer((req, res, n) => {
+      if (n === 1) {
+        res.on('error', () => {});
+        req.socket.destroy(); // connection reset — undici throws TypeError
+      } else send(res, 200, OPENAI_OK);
+    });
+    t.after(() => srv.close());
+    const { c, sleeps } = client(srv.baseUrl);
+    const turn = await c.complete(REQ);
+    assert.equal(turn.message.content, 'ok');
+    assert.deepEqual(sleeps, [1000]);
+  });
+
+  it('never retries a user abort', async (t) => {
+    const srv = await startServer((_req, res) => send(res, 500, { error: { message: 'x' } }));
+    t.after(() => srv.close());
+    const { c, sleeps } = client(srv.baseUrl);
+    const ac = new AbortController();
+    ac.abort(); // pre-aborted: undici rejects before any request is made
+    await assert.rejects(c.complete(REQ, ac.signal), (err: unknown) => err instanceof DOMException && err.name === 'AbortError');
+    assert.deepEqual(sleeps, []);
+    assert.equal(srv.requests.length, 0);
+  });
+});
+
+describe('streaming chat', () => {
+  it('a truncated stream is retried only when nothing was emitted', async (t) => {
+    const srv = await startServer((_req, res, n) => {
+      res.writeHead(200, { 'content-type': 'text/event-stream' });
+      if (n === 1) {
+        // one text frame, then the stream dies without [DONE] — but text was emitted
+        res.write('data: {"choices":[{"delta":{"content":"partial"}}]}\n\n');
+        res.end();
+      } else {
+        res.write(
+          'data: {"choices":[{"delta":{"content":"full"},"finish_reason":"stop"}],"usage":{"prompt_tokens":1,"completion_tokens":1}}\n\n',
+        );
+        res.write('data: [DONE]\n\n');
+        res.end();
+      }
+    });
+    t.after(() => srv.close());
+    const { c } = client(srv.baseUrl);
+    const events: string[] = [];
+    await assert.rejects(
+      c.chat({ model: 'gpt-x', dialect: 'openai', messages: [{ role: 'user', content: 'hi' }] }, (e) => events.push(e.kind)),
+      (err: RouterError) => err.message === 'The router closed the response before it finished.',
+    );
+    assert.deepEqual(events, ['text']); // partial text already streamed — a retry would duplicate it
+    assert.equal(srv.requests.length, 1);
+  });
+
+  it('an empty-then-closed stream retries and succeeds', async (t) => {
+    const srv = await startServer((_req, res, n) => {
+      res.writeHead(200, { 'content-type': 'text/event-stream' });
+      if (n === 1) {
+        res.end(); // nothing emitted
+      } else {
+        res.write('data: {"choices":[{"delta":{"content":"hi"},"finish_reason":"stop"}]}\n\n');
+        res.end();
+      }
+    });
+    t.after(() => srv.close());
+    const { c, sleeps } = client(srv.baseUrl);
+    const turn = await c.chat(
+      { model: 'gpt-x', dialect: 'openai', messages: [{ role: 'user', content: 'hi' }] },
+      () => {},
+    );
+    assert.equal(turn.message.content, 'hi');
+    assert.equal(turn.stopReason, 'stop');
+    assert.deepEqual(sleeps, [1000]);
+    assert.equal(srv.requests.length, 2);
+  });
+});
+
+describe('dialect routing + wire translation', () => {
+  it('anthropic dialect POSTs /v1/messages off the bare root with both auth headers', async (t) => {
+    const srv = await startServer((_req, res) => send(res, 200, ANTHROPIC_OK));
+    t.after(() => srv.close());
+    const { c } = client(srv.baseUrl);
+    const turn = await c.complete({
+      model: 'anthropic/fake',
+      dialect: 'anthropic',
+      messages: [{ role: 'user', content: 'hi' }],
+      system: 'be brief',
+    });
+    assert.equal(turn.message.content, 'hi');
+    assert.equal(turn.stopReason, 'stop');
+    assert.equal(turn.usage?.inputTokens, 2);
+    const [r] = srv.requests;
+    assert.equal(r.url, '/v1/messages'); // /v1 stripped from the base, anthropic endpoint appended
+    assert.equal(r.headers.authorization, `Bearer ${KEY}`);
+    assert.equal(r.headers['x-api-key'], KEY);
+    assert.equal(r.headers['anthropic-version'], '2023-06-01');
+  });
+
+  it('openai dialect POSTs /v1/chat/completions', async (t) => {
+    const srv = await startServer((_req, res) => send(res, 200, OPENAI_OK));
+    t.after(() => srv.close());
+    const { c } = client(srv.baseUrl);
+    await c.complete({ model: 'gpt-x', dialect: 'openai', messages: [{ role: 'user', content: 'hi' }] });
+    assert.equal(srv.requests[0].url, '/v1/chat/completions');
+  });
+});
+
+describe('pure helpers', () => {
+  it('errorMessage turns bare network failures into actionable copy', () => {
+    assert.equal(errorMessage(new TypeError('fetch failed')), 'Network error — could not reach the router.');
+    assert.equal(errorMessage(new RouterError('bad model')), 'bad model');
+    assert.equal(errorMessage('plain'), 'plain');
+  });
+
+  it('statusHint maps every status', () => {
+    assert.match(statusHint(400), /model ID/);
+    assert.match(statusHint(401), /SUBROUTER_API_KEY/);
+    assert.match(statusHint(403), /allowlist/);
+    assert.match(statusHint(429), /\/usage/);
+    assert.match(statusHint(502), /provider is disconnected/);
+    assert.equal(statusHint(999), 'The router could not complete the request.');
+  });
+
+  it('dialectFor: provider prefix wins, bare ids resolve, unknowns error', () => {
+    assert.equal(dialectFor('anthropic/claude-fake'), 'anthropic');
+    assert.equal(dialectFor('openai/claude-proxy'), 'openai'); // prefix wins, never silently rerouted
+    assert.equal(dialectFor('grok/grok-5'), 'openai');
+    assert.equal(dialectFor('claude-opus-5-5'), 'anthropic');
+    assert.equal(dialectFor('gpt-5'), 'openai');
+    assert.equal(dialectFor('deepseek-v4-pro'), 'openai');
+    assert.throws(() => dialectFor('opencode-gl'), /provider-prefixed id/);
+    assert.throws(() => dialectFor(''), /empty/);
+  });
+
+  it('rootFromBase strips /v1 and trailing slashes', () => {
+    assert.equal(rootFromBase('https://router.eva.pink/v1'), 'https://router.eva.pink');
+    assert.equal(rootFromBase('https://router.eva.pink/v1/'), 'https://router.eva.pink');
+    assert.equal(rootFromBase('https://router.eva.pink'), 'https://router.eva.pink');
+    assert.equal(rootFromBase('http://127.0.0.1:9/v1'), 'http://127.0.0.1:9');
+  });
+
+  it('parseModelCatalog accepts both documented shapes and string entries', () => {
+    const fromData = parseModelCatalog({ data: [{ id: 'grok/a' }, 'deepseek/b'] });
+    assert.ok(fromData);
+    assert.deepEqual(fromData.map((e) => e.id), ['grok/a', 'deepseek/b']);
+    const models = parseModelCatalog({
+      models: [{ name: 'x', context_length: 131072, max_output_tokens: 8192 }],
+    });
+    assert.ok(models);
+    assert.equal(models[0].id, 'x');
+    assert.equal(models[0].contextLength, 131072);
+    assert.equal(models[0].maxOutputTokens, 8192);
+    assert.equal(parseModelCatalog({}), null);
+    assert.equal(parseModelCatalog('garbage'), null);
+  });
+});

package/test/clipboard.test.ts

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { test } from 'node:test';
+import { CLIPBOARD_SCRIPT, decodeClipboardImage, readClipboardImage } from '../src/clipboard.ts';
+import { MAX_IMAGE_BYTES } from '../src/images.ts';
+
+const png = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aWVAAAAAASUVORK5CYII=';
+
+test('clipboard payload becomes the existing image attachment type', () => {
+  assert.deepEqual(decodeClipboardImage(JSON.stringify({ data: png })), {
+    name: 'clipboard.png', mediaType: 'image/png', data: png,
+  });
+});
+
+test('empty, malformed, unsupported and oversized clipboard data fail without revealing content', () => {
+  assert.throws(() => decodeClipboardImage('{"error":"empty"}'), /no image in the clipboard/);
+  assert.throws(() => decodeClipboardImage('{"error":"large"}'), /10 MiB/);
+  assert.throws(() => decodeClipboardImage('{"error":"dimensions"}'), /smaller screenshot/);
+  for (const payload of ['private text', 'null', '"secret"', '{"data":"???"}', '{"data":"aQ"}', '{"error":"private text"}']) {
+    assert.throws(() => decodeClipboardImage(payload), (err: unknown) => {
+      assert.ok(err instanceof Error);
+      assert.match(err.message, /could not read/);
+      assert.ok(!err.message.includes(payload));
+      return true;
+    });
+  }
+  assert.throws(() => decodeClipboardImage(JSON.stringify({ data: Buffer.from('not an image').toString('base64') })), /unsupported image/);
+  const large = Buffer.alloc(MAX_IMAGE_BYTES + 1).toString('base64');
+  assert.throws(() => decodeClipboardImage(JSON.stringify({ data: large })), /10 MiB/);
+});
+
+test('an already cancelled clipboard request does not spawn the native reader', async () => {
+  await assert.rejects(readClipboardImage(AbortSignal.abort()), { name: 'AbortError' });
+});
+
+// These exercise AppKit against synthetic private pasteboards only. Never read or
+// replace the person's general clipboard, and never contact the router.
+for (const format of ['png', 'tiff', 'empty'] as const) {
+  test(`native macOS reader handles ${format} on an isolated pasteboard`, { skip: process.platform !== 'darwin' }, () => {
+    let setup = 'const board = $.NSPasteboard.pasteboardWithUniqueName; board.clearContents;';
+    if (format !== 'empty') {
+      setup += format === 'png'
+        ? `board.setDataForType($.NSData.alloc.initWithBase64EncodedStringOptions('${png}', 0), $.NSPasteboardTypePNG);`
+        : `const fixture = $.NSBitmapImageRep.alloc.initWithBitmapDataPlanesPixelsWidePixelsHighBitsPerSampleSamplesPerPixelHasAlphaIsPlanarColorSpaceNameBytesPerRowBitsPerPixel(null, 1, 1, 8, 4, true, false, $.NSDeviceRGBColorSpace, 0, 0);
+           fixture.setColorAtXY($.NSColor.redColor, 0, 0);
+           board.setDataForType(fixture.TIFFRepresentation, $.NSPasteboardTypeTIFF);`;
+    }
+    const script = CLIPBOARD_SCRIPT
+      .replace('const board = $.NSPasteboard.generalPasteboard;', setup)
+      .replace('return encode(png);', '{ const output = encode(png); board.releaseGlobally; return output; }')
+      .replace("return JSON.stringify({ error: 'empty' });", "{ board.releaseGlobally; return JSON.stringify({ error: 'empty' }); }")
+      .replace('return encode(data);', 'const output = encode(data); board.releaseGlobally; return output;');
+    const child = spawnSync('/usr/bin/osascript', ['-l', 'JavaScript', '-e', script], { encoding: 'utf8', timeout: 10_000, maxBuffer: 64 * 1024 });
+    assert.equal(child.status, 0, child.stderr || String(child.error));
+    if (format === 'empty') assert.throws(() => decodeClipboardImage(child.stdout), /no image/);
+    else {
+      const image = decodeClipboardImage(child.stdout);
+      assert.equal(image.mediaType, 'image/png');
+      if (format === 'png') assert.equal(image.data, png);
+      else assert.ok(Buffer.from(image.data, 'base64').length > 8);
+    }
+  });
+}

package/test/command-input.test.ts

@@ -0,0 +1,183 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { test } from 'node:test';
+import { matchingCommands } from '../src/commands.ts';
+
+function exercise(script: string): void {
+  const child = spawnSync(process.execPath, ['--input-type=module', '-e', `
+    import assert from 'node:assert/strict';
+    Object.defineProperty(process.stdin, 'isTTY', { value: true });
+    Object.defineProperty(process.stdout, 'isTTY', { value: true });
+    Object.defineProperty(process.stdout, 'rows', { value: 24, configurable: true });
+    Object.defineProperty(process.stdout, 'columns', { value: 80 });
+    process.stdin.setRawMode = () => {};
+    const { ui } = await import('./src/ui.ts');
+    const { LineInput } = await import('./src/lineinput.ts');
+    const submitted = [];
+    let selected = '';
+    let panel = [];
+    const menu = ui.menu.bind(ui);
+    ui.menu = (items, index, ...rest) => { selected = items[index]; return menu(items, index, ...rest); };
+    const showPanel = ui.panel.bind(ui);
+    ui.panel = (lines, ...rest) => { panel = lines; return showPanel(lines, ...rest); };
+    let pastedImages = 0, clearedImages = 0, interrupts = 0;
+    const input = new LineInput({ onLine: (line) => submitted.push(line), onInterrupt: () => { interrupts++; }, onEof: () => {},
+      onPasteImage: () => { pastedImages++; }, onClearImages: () => { clearedImages++; } });
+    ui.welcome('openai/test', '/tmp/project');
+    input.setModel('openai/test');
+    input.start();
+    const key = (text) => process.stdin.emit('data', Buffer.from(text));
+    const wait = (ms = 0) => new Promise((resolve) => setTimeout(resolve, ms));
+    try { ${script} } finally { input.stop(); }
+  `], { cwd: new URL('..', import.meta.url), encoding: 'utf8', timeout: 15000 });
+  assert.equal(child.status, 0, child.stderr || String(child.error));
+}
+
+test('command matching filters prefixes and leaves argument input alone', () => {
+  assert.deepEqual(matchingCommands('/MO').map((c) => c.id), ['/model', '/models', '/mode']);
+  assert.equal(matchingCommands('/mode')[0].id, '/mode');
+  assert.equal(matchingCommands('/model')[0].id, '/model');
+  assert.equal(matchingCommands('/').length, 7);
+  for (const removed of ['/attach', '/detach', '/paste', '/help']) assert.deepEqual(matchingCommands(removed), []);
+  for (const text of ['hello', '/model openai/test', '/unknown']) assert.deepEqual(matchingCommands(text), []);
+});
+
+test('slash palette supports fragmented arrows, Tab completion and Enter execution', () => {
+  exercise(String.raw`
+    key('/mo');
+    assert.match(selected, /^\/model /);
+    key('\x1b'); key('['); key('B');
+    await wait(130);
+    assert.match(selected, /^\/models /);
+    key('\t'); key('\r');
+    assert.deepEqual(submitted, ['/models ']);
+    key('/'); key('\x1b[B'); key('\x1b[B'); key('\r');
+    assert.deepEqual(submitted, ['/models ', '/usage']);
+    key('/model openai/direct\r');
+    assert.equal(submitted.at(-1), '/model openai/direct');
+  `);
+});
+
+test('Escape dismisses the palette until text changes, without losing typed input', () => {
+  exercise(String.raw`
+    key('/mo'); key('\x1b'); await wait(130);
+    key('\r');
+    assert.deepEqual(submitted, ['/mo']);
+    key('/mo'); key('\x1b'); await wait(130);
+    key('d');
+    assert.match(selected, /^\/model /);
+    key('\r');
+    assert.equal(submitted.at(-1), '/model');
+  `);
+});
+
+test('usage view supports fragmented arrows, refresh and dismissal', () => {
+  exercise(String.raw`
+    let done = false;
+    let refreshes = 0;
+    const view = input.view(['initial usage'], async () => ['refreshed ' + ++refreshes]).then(() => { done = true; });
+    key('\x1b'); key('['); key('B');
+    await wait(130);
+    assert.equal(done, false);
+    key('r'); await wait();
+    assert.deepEqual(panel, ['refreshed 1']);
+    key('\x1b'); await wait(130);
+    await view;
+    assert.equal(done, true);
+    input.redraw(); key('hello\r');
+    assert.equal(submitted.at(-1), 'hello');
+  `);
+});
+
+test('wheel and Page keys scroll chat even while input is paused, without inserting mouse bytes', () => {
+  exercise(String.raw`
+    const scrolls = [];
+    ui.scrollChat = (delta) => scrolls.push(delta);
+    key('\x1b[<64;'); await wait(25); key('10;5M');
+    key('\x1b[<0;10;5M'); key('\x1b[<0;10;5m');
+    key('hello\r');
+    assert.deepEqual(submitted, ['hello']);
+    input.pause();
+    key('\x1b[5'); await wait(25); key('~');
+    key('\x1b[<65;10;5M'); key('\x1b[6~');
+    assert.deepEqual(scrolls, [3, 8, -3, -8]);
+    input.resume(); key('next\r');
+    assert.deepEqual(submitted, ['hello', 'next']);
+  `);
+});
+
+test('scroll keys navigate active controls instead of conversation history', () => {
+  exercise(String.raw`
+    ui.scrollChat = () => { throw new Error('modal must own navigation'); };
+    key('/'); key('\x1b[<65;10;22M'); key('\r');
+    assert.deepEqual(submitted, ['/models']);
+    const picker = input.select(['one', 'two', 'three', 'four']);
+    key('\x1b[6~'); key('\r');
+    assert.equal(await picker, 3);
+    let panelScroll = 0;
+    ui.scrollPanel = (delta) => { panelScroll += delta; };
+    const view = input.view(['usage'], async () => ['usage']);
+    key('\x1b[<65;10;22M'); key('\x1b[5~'); key('\r');
+    await view;
+    assert.equal(panelScroll, -5);
+  `);
+});
+
+test('navigation decoding preserves bracketed paste with fragmented end markers', () => {
+  exercise(String.raw`
+    key('\x1b[200~hello\nworld\n\x1b[20'); key('1~');
+    assert.deepEqual(submitted, ['hello world']);
+    key('\x1b[200~plain paste\x1b[201~'); key('\r');
+    assert.deepEqual(submitted, ['hello world', 'plain paste']);
+  `);
+});
+
+test('image shortcuts preserve drafts and do not fire inside paste, questions, panels or paused input', () => {
+  exercise(String.raw`
+    key('draft'); key('\x16'); key('\x18'); key('\r');
+    assert.deepEqual(submitted, ['draft']);
+    assert.equal(pastedImages, 1); assert.equal(clearedImages, 1);
+    key('\x1b[200~text\x16\x18\x1b[201~'); key('\x15');
+    input.pause(); key('\x16\x18'); input.resume();
+    const question = input.question('allow?'); key('\x16\x18n\r'); await question;
+    const picker = input.select(['one']); key('\x16\x18\r'); await picker;
+    const panel = input.view(['usage'], async () => ['usage']); key('\x16\x18\r'); await panel;
+    assert.equal(pastedImages, 1); assert.equal(clearedImages, 1);
+  `);
+});
+
+test('working editor preserves drafts through approvals and interruption without printing into the stream', () => {
+  exercise(String.raw`
+    const printed = [];
+    const submit = ui.submitInput.bind(ui);
+    ui.submitInput = (prompt, text) => { printed.push(text); submit(prompt, text); };
+    input.setWorking(true);
+    key('steer this');
+    const approval = input.question('allow?');
+    key('n\r'); assert.equal(await approval, 'n');
+    key('\r');
+    assert.deepEqual(submitted, ['steer this']);
+    assert.deepEqual(printed, ['n']); // draft is queued, not mixed into the streaming answer
+    key('unfinished'); key('\x03');
+    assert.equal(interrupts, 1);
+    input.setWorking(false); key('\r');
+    assert.equal(submitted.at(-1), 'unfinished');
+    key('saved draft'); input.setWorking(true);
+    const cancelled = input.question('allow?'); key('\x03');
+    assert.equal(await cancelled, 'n');
+    assert.equal(interrupts, 2);
+    input.setWorking(false); key('\r');
+    assert.equal(submitted.at(-1), 'saved draft');
+    input.restoreDraft(['queued one', 'queued two']); key('\r');
+    assert.equal(submitted.at(-1), 'queued one queued two');
+  `);
+});
+
+test('shrinking to a tiny terminal cancels the live usage view', () => {
+  exercise(String.raw`
+    const view = input.view(['usage'], async () => ['usage']);
+    Object.defineProperty(process.stdout, 'rows', { value: 8, configurable: true });
+    process.stdout.emit('resize');
+    await view;
+  `);
+});