stdout-chat 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stdout.chat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# stdout-chat
+
+`#void` from your terminal. A tiny client for the public room of [stdout.chat](https://stdout.chat) — read it, tail it live, post to it from a shell.
+
+```
+npx stdout-chat
+```
+
+Zero dependencies · Node ≥ 18 · ESM · MIT · no telemetry.
+
+```
+#void · what's the most underrated sound? · 3 in room
+a1b2  kira 👑      the hum of a fridge at 3am  ❤️ 2 😂 1
+a1b4  mox          → kira  ceiling fans, obviously
+      ↳ the hum of a fridge at 3am
+a1b5  anon·c31d    ping
+type /key sc_… to post · get it in the app: /key
+>
+```
+
+## Reading
+
+Anyone can read. The first run prints the last 30 lines and keeps tailing.
+
+```
+npx stdout-chat            # history + live tail + prompt
+npx stdout-chat --read     # print the last N lines and exit
+npx stdout-chat --tail     # live tail only, no prompt (pipe-friendly)
+npx stdout-chat -n 100     # more history
+```
+
+## Posting: get a key
+
+Posting is tied to your identity in the app. Open **#void** in the stdout.chat iOS app and type `/key` — it whispers you a key starting with `sc_`. Then, at the CLI prompt:
+
+```
+/key sc_…
+```
+
+The key is checked against the server, then saved to `~/.config/stdout-chat/config.json` (directory `0700`, file `0600`) with a plain-text twin `~/.config/stdout-chat/key` for shell scripts. Nothing else is stored. Rotate with `/key new` in the app; revoke with `/key off` in the app (`/key off` at the CLI only forgets the local copy).
+
+## Commands
+
+| at the `>` prompt | |
+|---|---|
+| `anything else` | posted to #void as-is (`@nick` mentions pass through) |
+| `/r <id> text` | reply to a line — ids are the dim column on the left |
+| `/top` | this week's top authors |
+| `/who` | how many are in the room |
+| `/key sc_…` | save a key · `/key` shows who you are · `/key off` forgets it |
+| `/clear` | clear the screen |
+| `/help` | list this |
+| `/quit` | leave (Ctrl-C and Ctrl-D too) |
+
+Server errors are printed as the server phrases them (`slow down · retry in 2s`), never as stack traces. Your own line is not echoed locally — it shows up when the room sees it, in order.
+
+## Flags
+
+```
+--read          print the last N lines and exit
+--tail          stream only: no history, no prompt
+-n <count>      lines of history (default 30, max 100)
+--api <url>     API base (default https://api.stdout.chat; env STDOUT_CHAT_API)
+--no-color      plain output (NO_COLOR is honoured too)
+--help, --version
+```
+
+## Without the CLI: curl
+
+The same room over plain HTTP.
+
+```
+curl https://stdout.chat/void
+curl -N https://api.stdout.chat/void/stream
+curl -d 'hi' -H "Authorization: Bearer $(cat ~/.config/stdout-chat/key)" https://stdout.chat/void
+```
+
+A `void()` for your `.bashrc` / `.zshrc`:
+
+```bash
+void() {  # void · void -f · void -r a1b4 text · void some words
+  local api=https://stdout.chat/void key=~/.config/stdout-chat/key reply=
+  case "$1" in
+    "") curl -s "$api"; return ;;
+    -f) curl -sN https://api.stdout.chat/void/stream; return ;;
+    -r) reply="$2"; shift 2 ;;
+  esac
+  [ -s "$key" ] || { echo "no key · in the app: /key, then: umask 077; echo sc_… > $key" >&2; return 1; }
+  curl -s -H "Authorization: Bearer $(cat "$key")" --data-urlencode "text=$*" ${reply:+--data-urlencode "reply=$reply"} "$api"
+}
+```
+
+## How it works
+
+- `GET /void` for history, `GET /void/stream` (Server-Sent Events) for the live feed, `POST /void` to speak, `GET /void/me` to check a key. All JSON.
+- Reconnects with backoff (1 → 30 s) and `Last-Event-ID`, so nothing is missed across the server's 15-minute stream rotation.
+- Plain scrolling output with a `readline` prompt: no alternate screen, no curses — works in tmux splits and over ssh.
+
+## Privacy
+
+No telemetry, no analytics, no crash reporting. The only thing the server learns is what any HTTP client sends: your requests and a `User-Agent` of `stdout-chat-cli/<version> node/<version>`. The key lives only in your config directory.
+
+## Development
+
+```
+git clone https://github.com/stdout-chat/cli && cd cli
+node --test                      # unit + smoke tests (spins up scripts/stub-server.js)
+node scripts/stub-server.js 4999 # fake server; STUB_KEY=sc_test
+node bin/stdout-chat.js --api http://127.0.0.1:4999
+```
+
+## License
+
+MIT © 2026 stdout.chat

package/bin/stdout-chat.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+// stdout-chat — #void from your terminal. Zero dependencies, Node ≥ 18.
+import fs from 'node:fs';
+import process from 'node:process';
+import { createApi, DEFAULT_API, errorMessage } from '../lib/api.js';
+import { loadConfig } from '../lib/config.js';
+import { createUI } from '../lib/ui.js';
+import { Session } from '../lib/session.js';
+import { renderError } from '../lib/render.js';
+
+const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+const USAGE = `stdout-chat ${pkg.version} — #void from your terminal
+
+usage: npx stdout-chat [options]
+
+  --read          print the last N lines and exit
+  --tail          stream only: no history, no prompt
+  -n <count>      how many lines to load (default 30, max 100)
+  --api <url>     API base (default ${DEFAULT_API}; env STDOUT_CHAT_API)
+  --no-color      plain output (NO_COLOR is honoured too)
+  -h, --help      this text
+  -v, --version   print the version
+
+at the prompt:
+  /help  /r <id> text  /top  /who  /key sc_…  /key off  /clear  /quit
+  anything else is posted to #void
+
+key file: ~/.config/stdout-chat/config.json (get a key in the app: /key)
+no telemetry · https://stdout.chat/void`;
+
+class UsageError extends Error {}
+
+function parseArgs(argv) {
+  const o = { read: false, tail: false, api: null, color: true, help: false, version: false, n: 30 };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const eq = a.startsWith('--') ? a.indexOf('=') : -1;
+    const k = eq > 0 ? a.slice(0, eq) : a;
+    const inline = eq > 0 ? a.slice(eq + 1) : undefined;
+    const next = () => (inline !== undefined ? inline : argv[++i]);
+    switch (k) {
+      case '--read': o.read = true; break;
+      case '--tail': o.tail = true; break;
+      case '--api': o.api = next(); if (!o.api) throw new UsageError('--api needs a url'); break;
+      case '--no-color': o.color = false; break;
+      case '--color': o.color = true; break;
+      case '-h': case '--help': o.help = true; break;
+      case '-v': case '--version': o.version = true; break;
+      case '-n': case '--lines': {
+        const v = next();
+        const n = Number(v);
+        if (!Number.isInteger(n) || n < 1) throw new UsageError(`-n needs a positive number, got "${v ?? ''}"`);
+        o.n = Math.min(n, 100);
+        break;
+      }
+      default:
+        throw new UsageError(`unknown option: ${a}`);
+    }
+  }
+  return o;
+}
+
+function wantColor(opts) {
+  if (!opts.color) return false;
+  if (process.env.NO_COLOR != null && process.env.NO_COLOR !== '') return false;
+  if (process.env.FORCE_COLOR != null && process.env.FORCE_COLOR !== '0') return true;
+  return Boolean(process.stdout.isTTY);
+}
+
+async function main() {
+  let opts;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    process.stderr.write(`${err.message}\n\n${USAGE}\n`);
+    return 2;
+  }
+  if (opts.help) { process.stdout.write(`${USAGE}\n`); return 0; }
+  if (opts.version) { process.stdout.write(`${pkg.version}\n`); return 0; }
+
+  const cfg = loadConfig();
+  const explicitApi = opts.api || process.env.STDOUT_CHAT_API || null;
+  const base = explicitApi || cfg.api || DEFAULT_API;
+  const api = createApi({ base, version: pkg.version });
+  const color = wantColor(opts);
+
+  const mode = opts.read ? 'read'
+    : opts.tail ? 'tail'
+      : (process.stdin.isTTY && process.stdout.isTTY) ? 'interactive'
+        : 'follow'; // piped: history + stream, no prompt
+
+  const ui = createUI();
+  const stop = new AbortController();
+  let closing = false;
+
+  const session = new Session({
+    api,
+    print: ui.print,
+    color,
+    width: () => process.stdout.columns || 80,
+    key: cfg.key || null,
+    persistApi: api.base !== DEFAULT_API ? api.base : null, // keep a non-default api next to the key
+    n: opts.n,
+    onQuit: () => shutdown(0),
+  });
+  session.onClear = () => ui.clear();
+
+  function shutdown(code = 0) {
+    if (closing) return;
+    closing = true;
+    stop.abort();
+    ui.close();
+    process.exitCode = code;
+    const t = setTimeout(() => process.exit(code), 500);
+    t.unref();
+  }
+
+  if (mode === 'read') {
+    try {
+      await session.loadHistory({ show: true, n: opts.n });
+      return 0;
+    } catch (err) {
+      process.stdout.write(`${renderError(errorMessage(err), { color })}\n`);
+      return 1;
+    }
+  }
+
+  process.on('SIGTERM', () => shutdown(0));
+  process.on('SIGHUP', () => shutdown(0));
+  if (mode !== 'interactive') process.on('SIGINT', () => shutdown(0));
+
+  if (mode !== 'tail') {
+    await session.verifyKey();
+    try {
+      await session.loadHistory({ show: true, n: opts.n });
+    } catch (err) {
+      session.error(errorMessage(err));
+      if (mode === 'follow') return 1;
+    }
+    if (mode === 'interactive') session.greet();
+  }
+
+  if (mode === 'interactive') {
+    ui.start({
+      onLine: async (line) => {
+        try {
+          await session.handleInput(line);
+        } catch (err) {
+          session.error(errorMessage(err));
+        }
+        if (/^\s*\/key\s+sc_/i.test(line)) ui.scrubHistory((h) => /^\s*\/key\s+sc_/i.test(h));
+      },
+      onClose: () => shutdown(0),
+    });
+  }
+
+  await session.runStream(stop.signal);
+  return process.exitCode || 0;
+}
+
+main().then(
+  (code) => { if (!process.exitCode) process.exitCode = code; },
+  (err) => {
+    process.stderr.write(`${renderError(errorMessage(err), { color: false })}\n`);
+    process.exitCode = 1;
+  },
+);

package/lib/api.js

@@ -0,0 +1,115 @@
+// Thin fetch helpers for the #void HTTP contract. No retries here; the
+// session decides. Every failure becomes an ApiError with a human `message`.
+
+export const DEFAULT_API = 'https://api.stdout.chat';
+
+export class ApiError extends Error {
+  constructor(message, { status = 0, code = null, until = null, retryAfter = null } = {}) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.code = code;
+    this.until = until;
+    this.retryAfter = retryAfter;
+  }
+}
+
+function normalizeBase(base) {
+  let b = String(base || DEFAULT_API).trim();
+  if (!/^https?:\/\//i.test(b)) b = `https://${b}`;
+  return b.replace(/\/+$/, '');
+}
+
+async function toError(res) {
+  let text = '';
+  try { text = await res.text(); } catch { /* body unreadable */ }
+  let parsed = null;
+  try { parsed = JSON.parse(text); } catch { /* not json */ }
+  const retryHeader = Number(res.headers.get('retry-after'));
+  const retryAfter = Number.isFinite(retryHeader) && retryHeader > 0 ? retryHeader : null;
+  if (parsed && typeof parsed === 'object' && typeof parsed.message === 'string' && parsed.message) {
+    return new ApiError(parsed.message, {
+      status: res.status,
+      code: typeof parsed.error === 'string' ? parsed.error : null,
+      until: parsed.until == null ? null : parsed.until,
+      retryAfter: parsed.retry_after == null ? retryAfter : Number(parsed.retry_after),
+    });
+  }
+  const plain = text.replace(/\s+/g, ' ').trim();
+  return new ApiError(plain || `http ${res.status}`, { status: res.status, retryAfter });
+}
+
+function networkError(err) {
+  if (err && err.name === 'AbortError') throw err;
+  const cause = err && err.cause;
+  const detail = (cause && (cause.code || cause.message)) || (err && err.message) || String(err);
+  return new ApiError(`network error · ${detail}`, { status: 0, code: 'network' });
+}
+
+export function createApi({ base = DEFAULT_API, version = '0.0.0', fetchImpl = null } = {}) {
+  const root = normalizeBase(base);
+  const userAgent = `stdout-chat-cli/${version} node/${process.version}`;
+  const doFetch = (url, init) => (fetchImpl || globalThis.fetch)(url, init);
+
+  function headers(extra = {}, key = null) {
+    const h = { Accept: 'application/json', 'User-Agent': userAgent, ...extra };
+    if (key) h.Authorization = `Bearer ${key}`;
+    return h;
+  }
+
+  async function json(url, init) {
+    let res;
+    try { res = await doFetch(url, init); } catch (err) { throw networkError(err); }
+    if (!res.ok) throw await toError(res);
+    try { return await res.json(); } catch { throw new ApiError('bad response · not json', { status: res.status }); }
+  }
+
+  return {
+    base: root,
+    userAgent,
+
+    /** GET /void?n=N → { topic, count, top_week, messages } */
+    getVoid(n = 30) {
+      const count = Math.max(1, Math.min(100, Number(n) || 30));
+      return json(`${root}/void?n=${count}`, { headers: headers() });
+    },
+
+    /** GET /void/me with Bearer → { username, tag, top?, week? } */
+    getMe(key) {
+      return json(`${root}/void/me`, { headers: headers({}, key) });
+    },
+
+    /** POST /void {text, reply?} → 201 { id, sid, username, text, ts } */
+    post({ text, reply } = {}, key) {
+      const body = { text: String(text) };
+      if (reply) body.reply = String(reply);
+      return json(`${root}/void`, {
+        method: 'POST',
+        headers: headers({ 'Content-Type': 'application/json' }, key),
+        body: JSON.stringify(body),
+      });
+    },
+
+    /** GET /void/stream → Response (200, body is a ReadableStream). Throws ApiError on non-2xx. */
+    async openStream({ lastEventId = null, signal = null } = {}) {
+      const extra = { 'Cache-Control': 'no-cache' };
+      if (lastEventId != null && lastEventId !== '') extra['Last-Event-ID'] = String(lastEventId);
+      let res;
+      try {
+        res = await doFetch(`${root}/void/stream`, { headers: headers(extra), signal });
+      } catch (err) {
+        throw networkError(err);
+      }
+      if (!res.ok) throw await toError(res);
+      if (!res.body) throw new ApiError('stream has no body', { status: res.status });
+      return res;
+    },
+  };
+}
+
+/** Human message for any thrown value — never a stack trace. */
+export function errorMessage(err) {
+  if (err instanceof ApiError) return err.message;
+  if (err && typeof err.message === 'string' && err.message) return err.message;
+  return String(err);
+}

package/lib/config.js

@@ -0,0 +1,64 @@
+// Key storage: ~/.config/stdout-chat/config.json  { "key": "sc_…", "api": "https://…" }
+// plus a plain-text twin ~/.config/stdout-chat/key so shell one-liners can
+// `$(cat ~/.config/stdout-chat/key)`. Directory 0700, files 0600.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export function configDir() {
+  if (process.env.STDOUT_CHAT_CONFIG_DIR) return process.env.STDOUT_CHAT_CONFIG_DIR;
+  const base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
+  return path.join(base, 'stdout-chat');
+}
+
+export function configPath() {
+  return path.join(configDir(), 'config.json');
+}
+
+export function keyPath() {
+  return path.join(configDir(), 'key');
+}
+
+/** Returns {} when missing or unreadable; never throws. */
+export function loadConfig() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath(), 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    const out = {};
+    if (typeof parsed.key === 'string' && parsed.key) out.key = parsed.key;
+    if (typeof parsed.api === 'string' && parsed.api) out.api = parsed.api;
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+function writePrivate(file, content) {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, content, { mode: 0o600 });
+  try { fs.chmodSync(tmp, 0o600); } catch { /* win32 */ }
+  fs.renameSync(tmp, file);
+}
+
+function rmQuiet(file) {
+  try { fs.unlinkSync(file); } catch { /* absent */ }
+}
+
+/** Writes config.json (+ plain `key` file). `api` is omitted when falsy. */
+export function saveConfig({ key, api } = {}) {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try { fs.chmodSync(dir, 0o700); } catch { /* win32 */ }
+  const data = {};
+  if (key) data.key = key;
+  if (api) data.api = api;
+  writePrivate(configPath(), `${JSON.stringify(data, null, 2)}\n`);
+  if (key) writePrivate(keyPath(), `${key}\n`);
+  else rmQuiet(keyPath());
+}
+
+/** Deletes the local key files (server-side revoke happens in the app). */
+export function removeConfig() {
+  rmQuiet(configPath());
+  rmQuiet(keyPath());
+}

package/lib/render.js

@@ -0,0 +1,265 @@
+// Pure line rendering: message object → string. No I/O, no process access.
+// Layout (mirrors the app / the text mode of GET /void):
+//
+//   a1b4  mox 👑       → kira  ceiling fans, obviously  ❤️ 2 😂 1
+//         ↳ the hum of a fridge at 3am
+//   ^sid  ^nick(12)    ^text column, wrapped with a hanging indent
+
+export const CSI = {
+  reset: '\x1b[0m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+  green: '\x1b[32m',
+  brightGreen: '\x1b[92m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m',
+  dimRed: '\x1b[2;31m',
+};
+
+export const SID_W = 5;
+export const NICK_W = 12;
+export const TEXT_COL = SID_W + 1 + NICK_W + 1; // 19
+export const QUOTE_MAX = 90;
+export const MEDALS = { 1: '👑', 2: '🥈', 3: '🥉' };
+
+/** Returns a paint(str, ...codes) function; identity when colour is off. */
+export function painter(color) {
+  if (!color) return (s) => s;
+  return (s, ...codes) => (codes.length ? codes.join('') + s + CSI.reset : s);
+}
+
+function isWide(cp) {
+  return (
+    (cp >= 0x1100 && cp <= 0x115f) ||
+    (cp >= 0x2e80 && cp <= 0x303e) ||
+    (cp >= 0x3041 && cp <= 0x33ff) ||
+    (cp >= 0x3400 && cp <= 0x4dbf) ||
+    (cp >= 0x4e00 && cp <= 0x9fff) ||
+    (cp >= 0xa000 && cp <= 0xa4cf) ||
+    (cp >= 0xac00 && cp <= 0xd7a3) ||
+    (cp >= 0xf900 && cp <= 0xfaff) ||
+    (cp >= 0xfe30 && cp <= 0xfe4f) ||
+    (cp >= 0xff00 && cp <= 0xff60) ||
+    (cp >= 0xffe0 && cp <= 0xffe6) ||
+    (cp >= 0x1f300 && cp <= 0x1f64f) ||
+    (cp >= 0x1f680 && cp <= 0x1f6ff) ||
+    (cp >= 0x1f900 && cp <= 0x1f9ff) ||
+    (cp >= 0x1fa70 && cp <= 0x1faff) ||
+    (cp >= 0x20000 && cp <= 0x3fffd) ||
+    cp === 0x231a || cp === 0x231b || (cp >= 0x23e9 && cp <= 0x23ec) || cp === 0x23f0 || cp === 0x23f3 ||
+    (cp >= 0x25fd && cp <= 0x25fe) || (cp >= 0x2614 && cp <= 0x2615) || (cp >= 0x2648 && cp <= 0x2653) ||
+    cp === 0x267f || cp === 0x2693 || cp === 0x26a1 || (cp >= 0x26aa && cp <= 0x26ab) ||
+    (cp >= 0x26bd && cp <= 0x26be) || (cp >= 0x26c4 && cp <= 0x26c5) || cp === 0x26ce || cp === 0x26d4 ||
+    cp === 0x26ea || (cp >= 0x26f2 && cp <= 0x26f3) || cp === 0x26f5 || cp === 0x26fa || cp === 0x26fd ||
+    cp === 0x2705 || (cp >= 0x270a && cp <= 0x270b) || cp === 0x2728 || cp === 0x274c || cp === 0x274e ||
+    (cp >= 0x2753 && cp <= 0x2755) || cp === 0x2757 || (cp >= 0x2795 && cp <= 0x2797) || cp === 0x27b0 ||
+    cp === 0x27bf || (cp >= 0x2b1b && cp <= 0x2b1c) || cp === 0x2b50 || cp === 0x2b55
+  );
+}
+
+function isZeroWidth(cp) {
+  return (
+    cp === 0x200d || cp === 0xfe0e || cp === 0x20e3 ||
+    (cp >= 0x300 && cp <= 0x36f) ||
+    (cp >= 0x1f3fb && cp <= 0x1f3ff) ||
+    (cp >= 0xe0020 && cp <= 0xe007f) ||
+    cp < 0x20 || (cp >= 0x7f && cp < 0xa0)
+  );
+}
+
+/** Terminal cell width of a string (best effort: CJK/emoji = 2, VS16 promotes, ZWJ joins). */
+export function displayWidth(str) {
+  let w = 0;
+  let prev = 0;
+  for (const ch of String(str)) {
+    const cp = ch.codePointAt(0);
+    if (cp === 0xfe0f) {
+      // Variation selector 16: a narrow symbol rendered as emoji becomes wide.
+      if (prev >= 0x2000 && prev <= 0x2bff && !isWide(prev)) w += 1;
+      prev = cp;
+      continue;
+    }
+    if (isZeroWidth(cp) || prev === 0x200d) { prev = cp; continue; }
+    w += isWide(cp) ? 2 : 1;
+    prev = cp;
+  }
+  return w;
+}
+
+/** Pad on the right with spaces to `n` display cells (never truncates). */
+export function padTo(str, n) {
+  const w = displayWidth(str);
+  return w >= n ? str : str + ' '.repeat(n - w);
+}
+
+/** Cut a string to at most `n` cells, appending '…' when cut. */
+export function truncate(str, n) {
+  if (displayWidth(str) <= n) return str;
+  let out = '';
+  let w = 0;
+  for (const ch of str) {
+    const cw = displayWidth(ch);
+    if (w + cw > n - 1) break;
+    out += ch;
+    w += cw;
+  }
+  return out + '…';
+}
+
+function splitAt(word, n) {
+  let head = '';
+  let w = 0;
+  let i = 0;
+  for (const ch of word) {
+    const cw = displayWidth(ch);
+    if (w + cw > n) break;
+    head += ch;
+    w += cw;
+    i += ch.length;
+  }
+  if (!head) { // pathological: first char wider than the line
+    const ch = String.fromCodePoint(word.codePointAt(0));
+    return [ch, word.slice(ch.length)];
+  }
+  return [head, word.slice(i)];
+}
+
+/** Greedy word wrap by display width. First line gets `first` cells, the rest `rest`. */
+export function wrap(text, first, rest = first) {
+  const out = [];
+  let cur = '';
+  let curW = 0;
+  let avail = Math.max(first, 8);
+  const flush = () => { out.push(cur); cur = ''; curW = 0; avail = Math.max(rest, 8); };
+  for (let word of String(text).split(/\s+/).filter(Boolean)) {
+    for (;;) {
+      const ww = displayWidth(word);
+      const need = curW ? curW + 1 + ww : ww;
+      if (need <= avail) {
+        cur = curW ? `${cur} ${word}` : word;
+        curW = need;
+        break;
+      }
+      if (curW) { flush(); continue; }
+      const [head, tail] = splitAt(word, avail);
+      cur = head;
+      curW = displayWidth(head);
+      flush();
+      word = tail;
+      if (!word) break;
+    }
+  }
+  if (cur || out.length === 0) out.push(cur);
+  return out;
+}
+
+/** `nick·tag` only when the nick collides with another tag this session, or for anon. */
+export function displayNick(msg, collisions) {
+  const nick = msg.username == null || msg.username === '' ? 'anon' : String(msg.username);
+  const tag = msg.tag == null ? '' : String(msg.tag);
+  if (tag && (nick === 'anon' || (collisions && collisions.has(nick)))) return `${nick}·${tag}`;
+  return nick;
+}
+
+/** `[["❤️",2],["😂",1]]` or `{"❤️":2}` → `❤️ 2 😂 1`. Unknown shapes → ''. */
+export function formatReactions(reactions) {
+  if (!reactions) return '';
+  const pairs = Array.isArray(reactions) ? reactions : (typeof reactions === 'object' ? Object.entries(reactions) : []);
+  return pairs
+    .filter((p) => Array.isArray(p) && p.length >= 2 && Number(p[1]) > 0)
+    .map(([emoji, n]) => `${emoji} ${Number(n)}`)
+    .join(' ');
+}
+
+function oneLine(s) {
+  return String(s == null ? '' : s).replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Render one message. opts: { width=80, color=true, myNick=null, collisions=null }.
+ * Returns a string that may contain newlines (wrap + quote line).
+ */
+export function renderLine(msg, opts = {}) {
+  const { width = 80, color = true, myNick = null, collisions = null } = opts;
+  const p = painter(color);
+  const own = myNick != null && msg.username === myNick;
+
+  const sid = padTo(String(msg.sid == null ? '' : msg.sid), SID_W);
+  const nickText = displayNick(msg, collisions);
+  const medal = MEDALS[msg.top] ? ` ${MEDALS[msg.top]}` : '';
+  const nickPad = ' '.repeat(Math.max(0, NICK_W - displayWidth(nickText + medal)));
+  const head = `${p(sid, CSI.dim)} ${p(nickText, ...(own ? [CSI.bold, CSI.brightGreen] : [CSI.green]))}${medal}${nickPad} `;
+
+  const avail = Math.max(width - TEXT_COL, 10);
+  const reply = msg.reply && typeof msg.reply === 'object' ? msg.reply : null;
+  const prefix = reply ? `→ ${oneLine(reply.username) || 'anon'}  ` : '';
+  const prefixW = displayWidth(prefix);
+  const lines = wrap(oneLine(msg.text), avail - prefixW, avail);
+  const indent = ' '.repeat(TEXT_COL);
+
+  const out = lines.map((l, i) => {
+    const body = own ? p(l, CSI.bold) : l;
+    return i === 0 ? `${head}${prefix ? p(prefix, CSI.dim) : ''}${body}` : `${indent}${body}`;
+  });
+
+  const reactions = formatReactions(msg.reactions);
+  if (reactions) {
+    const lastW = (lines.length === 1 ? prefixW : 0) + displayWidth(lines[lines.length - 1]);
+    if (lastW + 2 + displayWidth(reactions) <= avail) out[out.length - 1] += `  ${p(reactions, CSI.dim)}`;
+    else out.push(`${indent}${p(reactions, CSI.dim)}`);
+  }
+
+  if (reply) {
+    const quote = reply.gone ? '(gone)' : truncate(oneLine(reply.text), QUOTE_MAX);
+    out.push(`${' '.repeat(SID_W + 1)}${p(`↳ ${quote}`, CSI.dim)}`);
+  }
+  return out.join('\n');
+}
+
+/** Dim one-liner printed when a recent line's reactions change. */
+export function renderReactions(msg, opts = {}) {
+  const p = painter(opts.color !== false);
+  const sid = padTo(String(msg.sid == null ? '' : msg.sid), SID_W);
+  return p(`${sid} ${formatReactions(msg.reactions) || '·'}`, CSI.dim);
+}
+
+export function renderHide(sid, opts = {}) {
+  const p = painter(opts.color !== false);
+  return p(`${padTo(String(sid == null ? '' : sid), SID_W)} ↳ message removed`, CSI.dim);
+}
+
+export function renderTopic(topic, opts = {}) {
+  const p = painter(opts.color !== false);
+  return p(`// topic: ${oneLine(topic)}`, CSI.cyan);
+}
+
+export function renderHeader({ topic, count } = {}, opts = {}) {
+  const p = painter(opts.color !== false);
+  const parts = [p('#void', CSI.green)];
+  if (topic) parts.push(oneLine(topic));
+  if (count != null) parts.push(`${Number(count)} in room`);
+  return parts.join(' · ');
+}
+
+export function renderTop(topWeek, opts = {}) {
+  const p = painter(opts.color !== false);
+  const list = Array.isArray(topWeek) ? topWeek.filter((t) => t && t.nick) : [];
+  if (!list.length) return p('no top this week yet', CSI.dim);
+  return list
+    .map((t, i) => {
+      const rank = Number(t.rank) || i + 1;
+      const medal = MEDALS[rank] ? ` ${MEDALS[rank]}` : '';
+      return `${p(`#${rank}`, CSI.dim)} ${p(String(t.nick), CSI.green)}${medal}`;
+    })
+    .join('\n');
+}
+
+export function renderError(message, opts = {}) {
+  const p = painter(opts.color !== false);
+  return p(oneLine(message), CSI.dimRed);
+}
+
+export function renderInfo(message, opts = {}) {
+  const p = painter(opts.color !== false);
+  return p(String(message), CSI.dim);
+}

package/lib/session.js

@@ -0,0 +1,364 @@
+// Session state machine: history, SSE event handling, reconnect loop, and the
+// slash commands. All I/O is injected (api, print, config) so it is testable.
+import { errorMessage } from './api.js';
+import { readEvents } from './sse.js';
+import {
+  renderLine, renderReactions, renderHide, renderTopic, renderHeader, renderTop,
+  renderError, renderInfo, MEDALS,
+} from './render.js';
+import * as defaultConfig from './config.js';
+
+export const HINT_NO_KEY = 'type /key sc_… to post · get it in the app: /key';
+export const HELP_TEXT = [
+  '/help              this list',
+  '/r <id> text       reply to a line (ids are the dim column on the left)',
+  '/top               this week\'s top authors',
+  '/who               how many are in the room',
+  '/key sc_…          save your key (get it in the app: /key)',
+  '/key off           forget the key on this machine (revoke it in the app)',
+  '/clear             clear the screen',
+  '/quit              leave (Ctrl-C / Ctrl-D work too)',
+  'anything else is posted to #void · @nick mentions pass through as typed',
+].join('\n');
+
+const MAX_LINES = 1000;
+const RECENT = 5;
+const MAX_BACKOFF_MS = 30_000;
+const NOTICE_AFTER_MS = 5_000;
+const STALL_MS = 60_000;
+
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    if (!ms || (signal && signal.aborted)) { resolve(); return; }
+    const t = setTimeout(done, ms);
+    function done() { clearTimeout(t); if (signal) signal.removeEventListener('abort', done); resolve(); }
+    if (signal) signal.addEventListener('abort', done, { once: true });
+  });
+}
+
+export function greeting(me) {
+  if (!me || !me.username) return null;
+  const medal = MEDALS[me.top] ? ` ${MEDALS[me.top]}` : '';
+  const rank = me.week && me.week.rank != null ? Number(me.week.rank) : (me.top ? Number(me.top) : null);
+  return `you are ${me.username}${medal}${rank ? ` · #${rank} this week` : ''}`;
+}
+
+export class Session {
+  constructor({
+    api,
+    print,
+    color = true,
+    width = () => 80,
+    key = null,
+    persistApi = null,
+    config = defaultConfig,
+    n = 30,
+    onQuit = () => {},
+    onKeyChange = () => {},
+    timers = { setTimeout, clearTimeout },
+  }) {
+    this.api = api;
+    this.print = print;
+    this.color = color;
+    this.width = width;
+    this.key = key;
+    this.persistApi = persistApi;
+    this.config = config;
+    this.n = n;
+    this.onQuit = onQuit;
+    this.onKeyChange = onKeyChange;
+    this.timers = timers;
+
+    this.me = null;
+    this.topic = null;
+    this.count = null;
+    this.topWeek = [];
+    this.lines = new Map(); // String(id) → message
+    this.recent = []; // last printed ids (String)
+    this.nickTags = new Map(); // nick → Set(tag)
+    this.collisions = new Set();
+    this.lastEventId = null;
+  }
+
+  ropts() {
+    return {
+      width: this.width(),
+      color: this.color,
+      myNick: this.me ? this.me.username : null,
+      collisions: this.collisions,
+    };
+  }
+
+  info(s) { this.print(renderInfo(s, { color: this.color })); }
+  error(s) { this.print(renderError(s, { color: this.color })); }
+
+  // ── startup ─────────────────────────────────────────────────────────────
+
+  /** Verifies the stored key via /void/me. Never throws; leaves the key in place on failure. */
+  async verifyKey() {
+    if (!this.key) return null;
+    try {
+      this.me = await this.api.getMe(this.key);
+      return this.me;
+    } catch (err) {
+      if (err && err.status === 401) this.error(`${errorMessage(err)} · /key sc_… to replace it`);
+      else this.info(`· couldn't verify key: ${errorMessage(err)}`);
+      return null;
+    }
+  }
+
+  /** GET /void and (optionally) print header + lines. Throws ApiError on failure. */
+  async loadHistory({ show = true, n = this.n } = {}) {
+    const data = await this.api.getVoid(n);
+    this.absorbMeta(data);
+    const msgs = Array.isArray(data.messages) ? data.messages : [];
+    if (show) {
+      this.print(renderHeader({ topic: this.topic, count: this.count }, { color: this.color }));
+      if (!msgs.length) this.info('nobody has spoken in the last 24h · the room is not empty. it\'s waiting.');
+    }
+    for (const m of msgs) this.printMsg(m, { show });
+    return data;
+  }
+
+  absorbMeta(data) {
+    if (!data || typeof data !== 'object') return;
+    if (typeof data.topic === 'string') this.topic = data.topic;
+    if (data.count != null && Number.isFinite(Number(data.count))) this.count = Number(data.count);
+    if (Array.isArray(data.top_week)) this.topWeek = data.top_week;
+  }
+
+  greet() {
+    if (this.me) this.info(greeting(this.me));
+    else if (!this.key) this.info(HINT_NO_KEY);
+  }
+
+  // ── lines ───────────────────────────────────────────────────────────────
+
+  ingest(msg) {
+    const nick = msg.username == null || msg.username === '' ? 'anon' : String(msg.username);
+    const tag = msg.tag == null ? '' : String(msg.tag);
+    if (tag) {
+      let set = this.nickTags.get(nick);
+      if (!set) { set = new Set(); this.nickTags.set(nick, set); }
+      set.add(tag);
+      if (set.size > 1) this.collisions.add(nick);
+    }
+    const id = String(msg.id);
+    this.lines.set(id, msg);
+    if (this.lines.size > MAX_LINES) {
+      const oldest = this.lines.keys().next().value;
+      this.lines.delete(oldest);
+    }
+    if (msg.id != null) this.lastEventId = String(msg.id);
+  }
+
+  /** Prints a message unless already seen. Returns true when printed. */
+  printMsg(msg, { show = true } = {}) {
+    if (!msg || typeof msg !== 'object') return false;
+    const id = msg.id == null ? null : String(msg.id);
+    if (id != null && this.lines.has(id)) return false;
+    this.ingest(msg);
+    if (!show) return false;
+    this.print(renderLine(msg, this.ropts()));
+    if (id != null) {
+      this.recent.push(id);
+      if (this.recent.length > RECENT) this.recent.shift();
+    }
+    return true;
+  }
+
+  /** Handles one SSE event. Returns 'bye' when the server asked us to reconnect. */
+  handleEvent(ev) {
+    if (!ev) return undefined;
+    if (ev.event === 'bye') return 'bye';
+    let data;
+    try { data = JSON.parse(ev.data); } catch { return undefined; }
+    if (!data || typeof data !== 'object') return undefined;
+    switch (ev.event) {
+      case 'msg':
+      case 'message': {
+        if (data.id == null && ev.id) data.id = ev.id;
+        this.printMsg(data);
+        break;
+      }
+      case 'react': {
+        const id = String(data.id);
+        const m = this.lines.get(id);
+        if (!m) break;
+        m.reactions = data.reactions;
+        if (this.recent.includes(id)) this.print(renderReactions(m, { color: this.color }));
+        break;
+      }
+      case 'hide': {
+        const id = String(data.id);
+        const m = this.lines.get(id);
+        if (m) m.hidden = true;
+        const sid = data.sid != null ? data.sid : (m ? m.sid : null);
+        if (sid != null) this.print(renderHide(sid, { color: this.color }));
+        break;
+      }
+      case 'topic': {
+        if (typeof data.topic === 'string') {
+          this.topic = data.topic;
+          this.print(renderTopic(data.topic, { color: this.color }));
+        }
+        break;
+      }
+      default:
+        break; // unknown event types are ignored (forward compatible)
+    }
+    return undefined;
+  }
+
+  // ── stream ──────────────────────────────────────────────────────────────
+
+  /** Runs until `signal` aborts. Backoff 1,2,4…30 s; `bye` → immediate quiet reconnect. */
+  async runStream(signal) {
+    const { setTimeout: setT, clearTimeout: clearT } = this.timers;
+    let attempt = 0;
+    let noticeTimer = null;
+    let noticed = false;
+    let lastErrorShown = null;
+
+    const clearNotice = () => { if (noticeTimer) { clearT(noticeTimer); noticeTimer = null; } };
+
+    while (!signal.aborted) {
+      const conn = new AbortController();
+      const onAbort = () => conn.abort();
+      signal.addEventListener('abort', onAbort, { once: true });
+      let bye = false;
+      let stall = null;
+      try {
+        const res = await this.api.openStream({ lastEventId: this.lastEventId, signal: conn.signal });
+        attempt = 0;
+        lastErrorShown = null;
+        clearNotice();
+        if (noticed) { this.info('· back'); noticed = false; }
+        const kick = () => { if (stall) clearT(stall); stall = setT(() => conn.abort(), STALL_MS); if (stall && stall.unref) stall.unref(); };
+        kick();
+        for await (const ev of readEvents(res.body, { onChunk: kick })) {
+          if (this.handleEvent(ev) === 'bye') { bye = true; break; }
+        }
+      } catch (err) {
+        if (!signal.aborted && !(err && err.name === 'AbortError')) {
+          const msg = errorMessage(err);
+          if (msg !== lastErrorShown) { this.error(msg); lastErrorShown = msg; }
+        }
+      } finally {
+        if (stall) clearT(stall);
+        signal.removeEventListener('abort', onAbort);
+      }
+      if (signal.aborted) break;
+      if (bye) continue;
+      if (!noticeTimer && !noticed) {
+        noticeTimer = setT(() => { noticeTimer = null; noticed = true; this.info('· reconnecting'); }, NOTICE_AFTER_MS);
+        if (noticeTimer && noticeTimer.unref) noticeTimer.unref();
+      }
+      const delay = Math.min(MAX_BACKOFF_MS, 1000 * 2 ** attempt);
+      attempt = Math.min(attempt + 1, 10);
+      await sleep(delay, signal);
+    }
+    clearNotice();
+  }
+
+  // ── input ───────────────────────────────────────────────────────────────
+
+  async handleInput(raw) {
+    const line = String(raw == null ? '' : raw).trim();
+    if (!line) return;
+    if (line[0] !== '/') { await this.post(line); return; }
+    const cmd = line.split(/\s+/, 1)[0].toLowerCase();
+    const rest = line.slice(cmd.length).trim();
+    switch (cmd) {
+      case '/help': case '/h': case '/?':
+        this.print(renderInfo(HELP_TEXT, { color: this.color }));
+        return;
+      case '/quit': case '/q': case '/exit':
+        this.onQuit();
+        return;
+      case '/clear':
+        this.onClear && this.onClear();
+        return;
+      case '/top':
+        await this.cmdTop();
+        return;
+      case '/who':
+        await this.cmdWho();
+        return;
+      case '/key':
+        await this.cmdKey(rest);
+        return;
+      case '/r': case '/reply': {
+        const m = rest.match(/^(\S+)\s+([\s\S]+)$/);
+        if (!m) { this.info('usage: /r <id> text'); return; }
+        await this.post(m[2].trim(), m[1]);
+        return;
+      }
+      default:
+        await this.post(line); // the server owns slash semantics (e.g. 422 command not found)
+    }
+  }
+
+  async post(text, reply = null) {
+    if (!this.key) { this.info(HINT_NO_KEY); return false; }
+    try {
+      await this.api.post({ text, reply }, this.key); // echo arrives via SSE, not from the response
+      return true;
+    } catch (err) {
+      this.error(errorMessage(err));
+      return false;
+    }
+  }
+
+  async refreshMeta() {
+    try { this.absorbMeta(await this.api.getVoid(1)); } catch { /* fall back to cached */ }
+  }
+
+  async cmdTop() {
+    await this.refreshMeta();
+    this.print(renderTop(this.topWeek, { color: this.color }));
+  }
+
+  async cmdWho() {
+    await this.refreshMeta();
+    if (this.count == null) { this.info('no idea · try again'); return; }
+    this.info(this.count === 1 ? '1 in room' : `${this.count} in room`);
+  }
+
+  async cmdKey(arg) {
+    if (!arg) {
+      if (this.me) this.info(greeting(this.me));
+      else if (this.key) this.info('a key is on file but not verified · /key sc_… to replace it');
+      else this.info('no key · get it in the app: /key');
+      return;
+    }
+    if (arg.toLowerCase() === 'off') {
+      this.config.removeConfig();
+      this.key = null;
+      this.me = null;
+      this.onKeyChange(null);
+      this.info('key removed from this machine · to revoke it, run /key off in the app');
+      return;
+    }
+    if (!/^sc_[A-Za-z0-9]+$/.test(arg)) {
+      this.info('usage: /key sc_…  ·  /key off');
+      return;
+    }
+    let me;
+    try {
+      me = await this.api.getMe(arg);
+    } catch (err) {
+      this.error(errorMessage(err));
+      return;
+    }
+    this.key = arg;
+    this.me = me;
+    try {
+      this.config.saveConfig({ key: arg, api: this.persistApi || undefined });
+    } catch (err) {
+      this.error(`saved in memory only · ${errorMessage(err)}`);
+    }
+    this.onKeyChange(arg);
+    this.info(greeting(me) || 'key saved');
+  }
+}

package/lib/sse.js

@@ -0,0 +1,114 @@
+// Pure Server-Sent Events parser (WHATWG EventSource line semantics), no I/O.
+//
+//   const p = new SSEParser();
+//   p.feed('event: msg\nid: 12\ndata: {"a":1}\n\n')  // → [{ event: 'msg', id: '12', data: '{"a":1}' }]
+//
+// Handles events split across arbitrary chunk boundaries, LF / CRLF / CR line
+// endings, `: comment` heartbeats, multi-line `data:` fields, and `retry:`.
+// `id` on a yielded event is the *last seen* event id (spec behaviour), so an
+// event without its own `id:` line inherits the previous one.
+
+export class SSEParser {
+  constructor() {
+    this.buf = '';
+    this.lastEventId = '';
+    this.retry = null;
+    this._event = '';
+    this._data = [];
+  }
+
+  /** Feed a string chunk; returns an array of complete events (possibly empty). */
+  feed(chunk) {
+    if (!chunk) return [];
+    this.buf += chunk;
+    const out = [];
+    let start = 0;
+    for (;;) {
+      let i = start;
+      let term = -1;
+      let len = 0;
+      while (i < this.buf.length) {
+        const c = this.buf.charCodeAt(i);
+        if (c === 10) { term = i; len = 1; break; }
+        if (c === 13) {
+          // A trailing CR may be the first half of CRLF arriving in the next chunk.
+          if (i + 1 >= this.buf.length) { term = -2; break; }
+          term = i;
+          len = this.buf.charCodeAt(i + 1) === 10 ? 2 : 1;
+          break;
+        }
+        i++;
+      }
+      if (term < 0) break;
+      const ev = this._line(this.buf.slice(start, term));
+      if (ev) out.push(ev);
+      start = term + len;
+    }
+    this.buf = this.buf.slice(start);
+    return out;
+  }
+
+  /** Drop any partial event (spec: incomplete events at EOF are discarded). */
+  reset() {
+    this.buf = '';
+    this._event = '';
+    this._data = [];
+  }
+
+  _line(line) {
+    if (line === '') return this._dispatch();
+    if (line.charCodeAt(0) === 58) return null; // ':' comment
+    let field;
+    let value;
+    const colon = line.indexOf(':');
+    if (colon === -1) {
+      field = line;
+      value = '';
+    } else {
+      field = line.slice(0, colon);
+      value = line.slice(colon + 1);
+      if (value.charCodeAt(0) === 32) value = value.slice(1);
+    }
+    switch (field) {
+      case 'event': this._event = value; break;
+      case 'data': this._data.push(value); break;
+      case 'id': if (!value.includes('\0')) this.lastEventId = value; break;
+      case 'retry': if (/^\d+$/.test(value)) this.retry = Number(value); break;
+      default: break; // unknown fields are ignored
+    }
+    return null;
+  }
+
+  _dispatch() {
+    if (this._data.length === 0) {
+      this._event = '';
+      return null;
+    }
+    const ev = { event: this._event || 'message', id: this.lastEventId, data: this._data.join('\n') };
+    this._event = '';
+    this._data = [];
+    return ev;
+  }
+}
+
+/**
+ * Async-iterate SSE events from a WHATWG ReadableStream of bytes (fetch body).
+ * `onChunk` fires for every received chunk (used as a liveness watchdog).
+ * Breaking out of the loop cancels the underlying stream.
+ */
+export async function* readEvents(body, { onChunk } = {}) {
+  const parser = new SSEParser();
+  const decoder = new TextDecoder('utf-8');
+  const reader = body.getReader();
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (onChunk) onChunk();
+      const events = parser.feed(decoder.decode(value, { stream: true }));
+      for (const ev of events) yield ev;
+    }
+  } finally {
+    try { await reader.cancel(); } catch { /* already closed */ }
+  }
+}

package/lib/ui.js

@@ -0,0 +1,59 @@
+// Readline management: plain scrolling output with a `> ` prompt pinned at the
+// bottom. No alternate screen, no curses — works in tmux splits and pipes.
+import readline from 'node:readline';
+
+export function createUI({ input = process.stdin, output = process.stdout, prompt = '> ' } = {}) {
+  let rl = null;
+  let closed = false;
+
+  function print(text) {
+    if (closed && !rl) { output.write(`${text}\n`); return; }
+    if (rl) {
+      readline.clearLine(output, 0);
+      readline.cursorTo(output, 0);
+    }
+    output.write(`${text}\n`);
+    if (rl) rl.prompt(true);
+  }
+
+  function start({ onLine, onClose }) {
+    rl = readline.createInterface({ input, output, prompt, terminal: true, historySize: 200 });
+    rl.on('line', (line) => { Promise.resolve(onLine(line)).catch(() => {}).then(() => { if (rl) rl.prompt(true); }); });
+    rl.on('SIGINT', () => close());
+    rl.on('close', () => {
+      const wasOpen = !closed;
+      closed = true;
+      rl = null;
+      if (wasOpen && onClose) onClose();
+    });
+    rl.prompt();
+  }
+
+  /** Closes readline (restores terminal mode) and clears the prompt line. */
+  function close() {
+    if (!rl) { closed = true; return; }
+    const r = rl;
+    readline.clearLine(output, 0);
+    readline.cursorTo(output, 0);
+    r.close(); // emits 'close' → onClose
+  }
+
+  function clear() {
+    output.write('\x1b[2J\x1b[3J\x1b[H');
+    if (rl) rl.prompt(true);
+  }
+
+  /** Remove entries matching `pred` from the in-memory input history (e.g. `/key sc_…`). */
+  function scrubHistory(pred) {
+    if (rl && Array.isArray(rl.history)) rl.history = rl.history.filter((h) => !pred(h));
+  }
+
+  return {
+    print,
+    start,
+    close,
+    clear,
+    scrubHistory,
+    get interactive() { return rl !== null; },
+  };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "stdout-chat",
+  "version": "0.1.0",
+  "description": "#void from your terminal — read, tail and post to stdout.chat's public room. Zero dependencies.",
+  "type": "module",
+  "bin": {
+    "stdout-chat": "bin/stdout-chat.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node bin/stdout-chat.js",
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stdout-chat/cli.git"
+  },
+  "homepage": "https://stdout.chat/void",
+  "bugs": {
+    "url": "https://github.com/stdout-chat/cli/issues"
+  },
+  "keywords": [
+    "chat",
+    "terminal",
+    "cli",
+    "sse",
+    "void",
+    "stdout.chat"
+  ],
+  "author": "stdout.chat",
+  "license": "MIT"
+}