Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(tty): render an avatar and a GLB as real frames inside a terminal

nirholas0e52930decc0
diff --git a/api/tty.js b/api/tty.js
new file mode 100644
index 000000000..fed15219e
--- /dev/null
+++ b/api/tty.js
@@ -0,0 +1,179 @@
+// GET /api/tty — stream a 3D agent into the caller's terminal.
+//
+// curl three.ws/tty
+// curl three.ws/tty/<avatar-id>
+// curl 'three.ws/tty?src=https://example.com/model.glb&frames=120'
+//
+// The whole point is that it needs nothing installed. No GPU on this side, no
+// WebGL on the caller's side, no client at all beyond curl: the server runs the
+// software rasterizer from @three-ws/tty (packages/tty-3d) and writes ANSI
+// frames down a chunked response, pacing them so the response IS the animation.
+//
+// Why a stream rather than a rendered file: a GIF would need an encoder, a
+// content type the terminal cannot show, and a download step. Frames of text
+// arrive progressively and start animating before the model has even finished
+// sending, which is the difference between a demo and a trick.
+
+import { createRenderer, loadModel } from '../packages/tty-3d/src/index.js';
+import { ansi, ColorMode } from '../packages/tty-3d/src/term.js';
+import { getAvatar } from './_lib/avatars.js';
+import { error, redirect, wantsHtmlNavigation, wrap } from './_lib/http.js';
+import { clientIp, limits } from './_lib/rate-limit.js';
+import { assertSafePublicUrl, SsrfBlockedError } from './_lib/ssrf-guard.js';
+
+export const maxDuration = 60;
+
+// The signature model, used when the caller names nothing. It is the one GLB
+// every deploy is guaranteed to ship, so `curl three.ws/tty` can never 404.
+const DEFAULT_MODEL = '/avatars/default.glb';
+
+const MAX_FRAMES = 600;
+const MAX_SECONDS = 45;
+const MIN_COLS = 20;
+const MAX_COLS = 220;
+const MIN_ROWS = 8;
+const MAX_ROWS = 90;
+
+const clampInt = (raw, min, max, fallback) => {
+ const n = Number.parseInt(raw, 10);
+ if (!Number.isFinite(n)) return fallback;
+ return Math.max(min, Math.min(max, n));
+};
+
+const clampFloat = (raw, min, max, fallback) => {
+ const n = Number.parseFloat(raw);
+ if (!Number.isFinite(n)) return fallback;
+ return Math.max(min, Math.min(max, n));
+};
+
+/**
+ * Terminals do not announce themselves, so colour depth is inferred from what
+ * curl passes through. A caller who knows better can always say `?color=`.
+ */
+export function colorModeFor(query, headers = {}) {
+ const asked = String(query.color ?? '').toLowerCase();
+ if (Object.values(ColorMode).includes(asked)) return asked;
+ // curl forwards neither COLORTERM nor TERM, so the safe default over the
+ // wire is 256 colour: universally supported by anything that renders escape
+ // sequences at all, and visibly better than the ASCII ramp.
+ if (String(headers['x-color'] ?? '').toLowerCase() === 'truecolor') return ColorMode.TRUECOLOR;
+ return ColorMode.ANSI256;
+}
+
+/** Resolve what to draw: an explicit GLB URL, an avatar id, or the default. */
+export async function resolveSource(query, origin) {
+ if (query.src) {
+ // Caller-supplied URLs are fetched by this server, so they are an SSRF
+ // vector like any other. Same guard the render endpoints use.
+ const safe = await assertSafePublicUrl(String(query.src));
+ return { url: safe.toString ? safe.toString() : String(query.src), label: 'model' };
+ }
+ const avatarId = query.avatar ? String(query.avatar) : '';
+ if (avatarId) {
+ const avatar = await getAvatar({ id: avatarId });
+ if (!avatar) return null;
+ // model_url is null for a private avatar, which is exactly the case that
+ // must not render: this endpoint is unauthenticated.
+ if (!avatar.model_url) return null;
+ return { url: avatar.model_url, label: avatar.name || 'avatar' };
+ }
+ return { url: new URL(DEFAULT_MODEL, origin).toString(), label: 'three.ws' };
+}
+
+function banner(label, info, cols) {
+ const left = `three.ws ${label}`;
+ const right = `${info.triangles.toLocaleString('en-US')} tris${info.skinned ? ' rigged' : ''}`;
+ const gap = Math.max(1, cols - left.length - right.length);
+ return `${left}${' '.repeat(gap)}${right}`;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export default wrap(async function handler(req, res) {
+ const url = new URL(req.url, 'http://localhost');
+ const query = Object.fromEntries(url.searchParams);
+
+ // A browser that lands here would see escape codes as literal mojibake, so
+ // send it somewhere that explains the trick instead.
+ if (wantsHtmlNavigation(req) && !query.raw) {
+ const to = query.avatar ? `/tty?avatar=${encodeURIComponent(String(query.avatar))}` : '/tty';
+ return redirect(res, to, 302);
+ }
+
+ const rate = await limits.renderIp(clientIp(req));
+ if (!rate.ok) return error(res, 429, 'rate_limited', 'too many terminal renders, try again shortly');
+
+ const origin = `${req.headers['x-forwarded-proto'] || 'https'}://${req.headers.host || 'three.ws'}`;
+
+ let source;
+ try {
+ source = await resolveSource(query, origin);
+ } catch (err) {
+ if (err instanceof SsrfBlockedError) return error(res, 400, 'blocked_url', 'that model URL is not reachable');
+ throw err;
+ }
+ if (!source) return error(res, 404, 'not_found', 'no such avatar');
+
+ const cols = clampInt(query.w ?? query.cols, MIN_COLS, MAX_COLS, 76);
+ const rows = clampInt(query.h ?? query.rows, MIN_ROWS, MAX_ROWS, 30);
+ const fps = clampInt(query.fps, 4, 30, 18);
+ const spin = clampFloat(query.spin, -4, 4, 0.9);
+ const frames = clampInt(query.frames, 1, Math.min(MAX_FRAMES, fps * MAX_SECONDS), fps * 8);
+
+ let model;
+ try {
+ model = await loadModel(source.url);
+ } catch (err) {
+ return error(res, 502, 'model_unavailable', `could not read that model: ${err.message}`);
+ }
+
+ const renderer = createRenderer(model, {
+ width: cols,
+ height: rows,
+ mode: colorModeFor(query, req.headers),
+ animation: query.clip ?? undefined,
+ spin,
+ pitch: clampFloat(query.pitch, -1.4, 1.4, 0.08),
+ zoom: clampFloat(query.zoom, 0.3, 6, 1),
+ });
+
+ res.statusCode = 200;
+ res.setHeader('content-type', 'text/plain; charset=utf-8');
+ res.setHeader('cache-control', 'no-store');
+ // Nothing may buffer this: a proxy that waits for the body to finish turns a
+ // live animation into a wall of text delivered at the end.
+ res.setHeader('x-accel-buffering', 'no');
+ res.setHeader('x-content-type-options', 'nosniff');
+ if (typeof res.flushHeaders === 'function') res.flushHeaders();
+
+ const info = { triangles: model.triangleCount, skinned: model.skinned };
+ const single = frames === 1;
+ // A single frame can be asked for at any point in the clip, which is what
+ // makes `?frames=1&t=` a usable still-image API and not just a first frame.
+ const startTime = clampFloat(query.t ?? query.time, 0, 600, 0);
+
+ // A client that hangs up mid-animation (Ctrl-C on curl) must stop the render
+ // loop, not keep rasterizing frames into a dead socket for another 40s.
+ let aborted = false;
+ const stop = () => { aborted = true; };
+ req.on('aborted', stop);
+ res.on('close', stop);
+
+ if (!single) res.write(ansi.hideCursor + '\n'.repeat(rows + 1));
+
+ try {
+ for (let i = 0; i < frames && !aborted; i += 1) {
+ const time = startTime + i / fps;
+ const frame = renderer.frame(time);
+ const head = single ? '' : ansi.up(rows + 1);
+ res.write(`${head}${frame}\n${banner(source.label, info, cols)}\n`);
+ if (single) break;
+ await sleep(Math.round(1000 / fps));
+ }
+ } finally {
+ if (!aborted) {
+ if (!single) res.write(ansi.showCursor);
+ res.end();
+ }
+ }
+});
diff --git a/packages/tty-3d/bin/three-tty.js b/packages/tty-3d/bin/three-tty.js
new file mode 100755
index 000000000..5883ec593
--- /dev/null
+++ b/packages/tty-3d/bin/three-tty.js
@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+// three-tty — render a 3D model in your terminal.
+//
+// npx @three-ws/tty-3d ./avatar.glb
+// npx @three-ws/tty-3d https://three.ws/avatars/default.glb --spin 1.4
+// npx @three-ws/tty-3d model.glb --once --width 80 > frame.txt
+//
+// Reads a GLB, plays its animation, and draws it with half-block characters.
+// No GPU, no browser, no display server.
+
+import process from 'node:process';
+import { loadModel, createRenderer, describeModel } from '../src/index.js';
+import { ansi, detectColorMode, ColorMode } from '../src/term.js';
+
+const ESC = '\x1b';
+
+const USAGE = `three-tty — a 3D model in your terminal
+
+Usage
+ three-tty <model.glb | https://...> [options]
+
+Options
+ --width <n> columns (default: terminal width, capped at 400)
+ --height <n> rows (default: terminal height minus 2)
+ --fps <n> frames per second (default 24)
+ --spin <n> turntable speed in radians per second (default 0.9, 0 to stop)
+ --clip <name|n> animation to play (default: the first one)
+ --no-anim hold the rest pose
+ --once draw a single frame and exit (pipe-friendly)
+ --frames <n> draw n frames and exit
+ --time <s> timestamp for --once (default 0)
+ --pitch <r> camera elevation in radians (default 0.08)
+ --zoom <n> 1 fits the model, higher moves closer
+ --color <mode> truecolor | ansi256 | mono (default: detected)
+ --transparent leave the background unpainted
+ --info print what was loaded, then exit
+ --help
+
+Controls (interactive)
+ left/right or a/d orbit up/down or w/s tilt
+ +/- zoom space pause
+ q or Ctrl-C quit
+`;
+
+function parseArgs(argv) {
+ const opts = { _: [] };
+ const takesValue = new Set(['width', 'height', 'fps', 'spin', 'clip', 'frames', 'time', 'pitch', 'zoom', 'color']);
+ for (let i = 0; i < argv.length; i += 1) {
+ const arg = argv[i];
+ if (!arg.startsWith('--')) { opts._.push(arg); continue; }
+ const key = arg.slice(2);
+ if (takesValue.has(key)) { opts[key] = argv[i + 1]; i += 1; }
+ else opts[key] = true;
+ }
+ return opts;
+}
+
+const num = (v, fallback) => {
+ const n = Number(v);
+ return Number.isFinite(n) ? n : fallback;
+};
+
+function fail(message) {
+ process.stderr.write(`three-tty: ${message}\n`);
+ process.exit(1);
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (opts.help || !opts._.length) {
+ process.stdout.write(USAGE);
+ process.exit(opts.help ? 0 : 1);
+}
+
+const source = opts._[0];
+const isTTY = Boolean(process.stdout.isTTY);
+// Piping to a file or another program must produce ONE frame, not an infinite
+// animation. Getting this wrong fills a disk, so the non-interactive default is
+// a single frame and animation has to be asked for explicitly with --frames.
+const once = Boolean(opts.once) || (!isTTY && opts.frames === undefined);
+
+const cols = Math.max(20, Math.min(num(opts.width, process.stdout.columns || 80), 400));
+const rows = Math.max(10, Math.min(num(opts.height, (process.stdout.rows || 26) - 2), 200));
+
+let model;
+try {
+ model = await loadModel(source);
+} catch (err) {
+ fail(`could not load ${source}: ${err.message}`);
+}
+
+if (opts.info) {
+ process.stdout.write(JSON.stringify(describeModel(model), null, 2) + '\n');
+ process.exit(0);
+}
+
+const colorMode = opts.color ?? detectColorMode();
+if (!Object.values(ColorMode).includes(colorMode)) fail(`unknown color mode: ${colorMode}`);
+
+const renderer = createRenderer(model, {
+ width: cols,
+ height: rows,
+ animation: opts['no-anim'] ? false : (opts.clip ?? undefined),
+ mode: colorMode,
+ transparent: Boolean(opts.transparent),
+ spin: num(opts.spin, 0.9),
+ pitch: num(opts.pitch, 0.08),
+ zoom: num(opts.zoom, 1),
+});
+
+if (once) {
+ process.stdout.write(renderer.frame(num(opts.time, 0)) + '\n');
+ process.exit(0);
+}
+
+const fps = Math.max(1, Math.min(num(opts.fps, 24), 60));
+const totalFrames = opts.frames !== undefined ? Math.max(1, num(opts.frames, 1)) : Infinity;
+
+let paused = false;
+let time = num(opts.time, 0);
+let drawn = 0;
+let timer = null;
+
+function restore() {
+ if (timer) clearInterval(timer);
+ if (isTTY) process.stdout.write(ansi.showCursor + '\n');
+ if (process.stdin.isTTY) process.stdin.setRawMode(false);
+ process.stdin.pause();
+}
+
+function quit(code = 0) {
+ restore();
+ process.exit(code);
+}
+
+if (isTTY) {
+ process.stdout.write(ansi.hideCursor);
+ // Reserve the rows up front, then only ever move the cursor back up. A
+ // full-screen clear each frame flickers on most terminals; overdrawing in
+ // place does not, and it leaves the scrollback intact when the program ends.
+ process.stdout.write('\n'.repeat(renderer.height));
+}
+
+if (process.stdin.isTTY) {
+ process.stdin.setRawMode(true);
+ process.stdin.resume();
+ process.stdin.setEncoding('utf8');
+ process.stdin.on('data', (key) => {
+ const o = renderer.orbit;
+ if (key === 'q' || key === '') quit(0);
+ else if (key === ' ') paused = !paused;
+ else if (key === `${ESC}[C` || key === 'd') renderer.setOrbit({ yaw: o.yaw + 0.2 });
+ else if (key === `${ESC}[D` || key === 'a') renderer.setOrbit({ yaw: o.yaw - 0.2 });
+ else if (key === `${ESC}[A` || key === 'w') renderer.setOrbit({ pitch: o.pitch + 0.1 });
+ else if (key === `${ESC}[B` || key === 's') renderer.setOrbit({ pitch: o.pitch - 0.1 });
+ else if (key === '+' || key === '=') renderer.setOrbit({ zoom: o.zoom * 1.12 });
+ else if (key === '-' || key === '_') renderer.setOrbit({ zoom: o.zoom / 1.12 });
+ });
+}
+
+process.on('SIGINT', () => quit(0));
+process.on('SIGTERM', () => quit(0));
+
+timer = setInterval(() => {
+ const text = renderer.frame(time);
+ process.stdout.write((isTTY ? ansi.up(renderer.height) : '') + text + '\n');
+ if (!paused) time += 1 / fps;
+ drawn += 1;
+ if (drawn >= totalFrames) quit(0);
+}, Math.round(1000 / fps));
diff --git a/packages/tty-3d/package.json b/packages/tty-3d/package.json
new file mode 100644
index 000000000..02a5cdcc7
--- /dev/null
+++ b/packages/tty-3d/package.json
@@ -0,0 +1,69 @@
+{
+ "name": "@three-ws/tty-3d",
+ "version": "0.1.0",
+ "description": "The terminal 3D renderer core: GLB in, skinned and animated ANSI frames out. A software rasterizer with real glTF skeletal animation, no GPU, no browser and no display server, plus the three-tty CLI.",
+ "type": "module",
+ "main": "./src/index.js",
+ "module": "./src/index.js",
+ "types": "./src/index.d.ts",
+ "exports": {
+ ".": {
+ "types": "./src/index.d.ts",
+ "import": "./src/index.js",
+ "default": "./src/index.js"
+ },
+ "./model": "./src/model.js",
+ "./raster": "./src/raster.js",
+ "./term": "./src/term.js",
+ "./package.json": "./package.json"
+ },
+ "bin": {
+ "three-tty": "./bin/three-tty.js"
+ },
+ "files": [
+ "src",
+ "bin",
+ "README.md",
+ "LICENSE"
+ ],
+ "scripts": {
+ "test": "vitest run --root ../.. packages/tty-3d/tests"
+ },
+ "keywords": [
+ "3d",
+ "terminal",
+ "ansi",
+ "cli",
+ "glb",
+ "gltf",
+ "rasterizer",
+ "software-rendering",
+ "skinning",
+ "animation",
+ "ascii-art",
+ "avatar",
+ "three.ws"
+ ],
+ "author": "three.ws <[email protected]> (https://three.ws)",
+ "license": "Apache-2.0",
+ "homepage": "https://three.ws/tty",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/nirholas/three.ws.git",
+ "directory": "packages/tty-3d"
+ },
+ "bugs": {
+ "url": "https://github.com/nirholas/three.ws/issues"
+ },
+ "dependencies": {
+ "@gltf-transform/core": "^4.4.0",
+ "@gltf-transform/extensions": "^4.4.0",
+ "meshoptimizer": "^1.1.1"
+ },
+ "engines": {
+ "node": ">=18"
+ },
+ "publishConfig": {
+ "access": "public"
+ }
+}
diff --git a/packages/tty-3d/src/index.d.ts b/packages/tty-3d/src/index.d.ts
new file mode 100644
index 000000000..7e89a5c70
--- /dev/null
+++ b/packages/tty-3d/src/index.d.ts
@@ -0,0 +1,89 @@
+export interface ModelAnimation {
+ name: string;
+ duration: number;
+ channels: unknown[];
+}
+
+export interface Model {
+ nodes: unknown[];
+ primitives: unknown[];
+ animations: ModelAnimation[];
+ bounds: { min: number[]; max: number[] };
+ triangleCount: number;
+ skinned: boolean;
+ poseStamp: number;
+}
+
+export type ColorModeValue = 'truecolor' | 'ansi256' | 'mono';
+
+export interface RendererOptions {
+ /** Character columns. Default 96. */
+ width?: number;
+ /** Character rows. One row is two vertical pixels. Default 48. */
+ height?: number;
+ /** Clip name, index, or false to hold the rest pose. Default: the first clip. */
+ animation?: string | number | boolean | null;
+ mode?: ColorModeValue;
+ /** Background rgb in 0..1, painted where nothing was drawn. */
+ background?: [number, number, number];
+ /** Leave uncovered cells as plain spaces instead of painting the background. */
+ transparent?: boolean;
+ /** Turntable speed, radians per second. Default 1. */
+ spin?: number;
+ pitch?: number;
+ zoom?: number;
+ tint?: [number, number, number];
+}
+
+export interface Orbit {
+ yaw: number;
+ pitch: number;
+ zoom: number;
+}
+
+export interface Renderer {
+ model: Model;
+ animation: ModelAnimation | null;
+ framing: { halfHeight: number; halfWidth: number };
+ width: number;
+ height: number;
+ readonly orbit: Orbit;
+ setOrbit(next: Partial<Orbit>): Orbit;
+ /** Terminal-ready text for the frame at `time` seconds. No trailing newline. */
+ frame(time?: number): string;
+}
+
+export interface LoadOptions {
+ fetchImpl?: typeof fetch;
+ signal?: AbortSignal;
+}
+
+/** Load from a file path, an http(s) URL, or raw GLB bytes. */
+export function loadModel(source: string | Uint8Array | ArrayBuffer, options?: LoadOptions): Promise<Model>;
+export function loadModelFromFile(path: string): Promise<Model>;
+export function loadModelFromBytes(bytes: Uint8Array | ArrayBuffer): Promise<Model>;
+
+export function createRenderer(model: Model, options?: RendererOptions): Renderer;
+export function renderOnce(source: string | Uint8Array | ArrayBuffer, options?: RendererOptions & LoadOptions & { time?: number }): Promise<string>;
+
+export function selectAnimation(model: Model, wanted?: string | number | boolean | null): ModelAnimation | null;
+export function describeModel(model: Model): {
+ triangles: number;
+ primitives: number;
+ nodes: number;
+ skinned: boolean;
+ animations: Array<{ name: string; duration: number }>;
+};
+
+export function detectColorMode(env?: NodeJS.ProcessEnv, stream?: NodeJS.WriteStream): ColorModeValue;
+export function detectTerminalColor(env?: NodeJS.ProcessEnv, stream?: NodeJS.WriteStream): ColorModeValue;
+export function toAnsi256(r: number, g: number, b: number): number;
+
+export const ColorMode: { TRUECOLOR: 'truecolor'; ANSI256: 'ansi256'; MONO: 'mono' };
+export const ansi: {
+ hideCursor: string;
+ showCursor: string;
+ clearScreen: string;
+ home: string;
+ up(n: number): string;
+};
diff --git a/packages/tty-3d/src/index.js b/packages/tty-3d/src/index.js
new file mode 100644
index 000000000..ba449a404
--- /dev/null
+++ b/packages/tty-3d/src/index.js
@@ -0,0 +1,135 @@
+// @three-ws/tty-3d — render a rigged 3D model into a terminal, with no GPU, no
+// browser and no display server.
+//
+// Public API:
+// loadModel(source) -> Model (file path, URL, or bytes)
+// createRenderer(model, options) -> Renderer
+// renderOnce(source, options) -> Promise<string> (one frame, one call)
+//
+// See README.md for the CLI (`npx @three-ws/tty-3d`) and the hosted stream.
+
+import { loadModelFromBytes, loadModelFromFile, poseModel } from './model.js';
+import { computeFraming, createFramebuffer, poseCenter, renderToFramebuffer } from './raster.js';
+import { ColorMode, detectColorMode, framebufferToText } from './term.js';
+
+export { loadModelFromBytes, loadModelFromFile, poseModel } from './model.js';
+export { createFramebuffer, renderToFramebuffer, computeFraming, poseCenter, poseBounds } from './raster.js';
+export { ColorMode, detectColorMode, framebufferToText, toAnsi256, ansi } from './term.js';
+
+const MAX_REMOTE_BYTES = 64 * 1024 * 1024;
+
+/** Load from a file path, an http(s) URL, or raw bytes. */
+export async function loadModel(source, { fetchImpl = globalThis.fetch, signal } = {}) {
+ if (source instanceof Uint8Array || source instanceof ArrayBuffer) return loadModelFromBytes(source);
+ if (typeof source !== 'string') throw new TypeError('source must be a path, a URL, or bytes');
+
+ if (/^https?:\/\//i.test(source)) {
+ if (typeof fetchImpl !== 'function') throw new Error('no fetch implementation available for remote models');
+ const res = await fetchImpl(source, { signal, redirect: 'follow' });
+ if (!res.ok) throw new Error(`could not fetch model: ${res.status} ${res.statusText}`);
+ const length = Number(res.headers?.get?.('content-length') ?? 0);
+ // A terminal frame is at most a few thousand pixels, so an enormous model
+ // buys nothing and a hostile one would sit in memory. Refuse early, on the
+ // header, before the body is buffered.
+ if (length > MAX_REMOTE_BYTES) throw new Error(`model is too large: ${length} bytes`);
+ const buf = new Uint8Array(await res.arrayBuffer());
+ if (buf.byteLength > MAX_REMOTE_BYTES) throw new Error(`model is too large: ${buf.byteLength} bytes`);
+ return loadModelFromBytes(buf);
+ }
+ return loadModelFromFile(source);
+}
+
+/** Pick the animation to play: by name, by index, or the first one there is. */
+export function selectAnimation(model, wanted) {
+ if (wanted === false || wanted === null) return null;
+ if (!model.animations.length) return null;
+ if (wanted === undefined || wanted === true) return model.animations[0];
+ if (typeof wanted === 'number') return model.animations[wanted] ?? model.animations[0];
+ const lower = String(wanted).toLowerCase();
+ return model.animations.find((a) => a.name.toLowerCase().includes(lower)) ?? model.animations[0];
+}
+
+/**
+ * A renderer bound to one model and one output size.
+ *
+ * Framing is resolved once, at construction, from a sampled union of the clip
+ * (see stableBounds). Everything after that is per-frame work on preallocated
+ * buffers, so a long-running animation does not grow the heap.
+ */
+export function createRenderer(model, options = {}) {
+ const {
+ width = 96,
+ height = 48,
+ animation,
+ mode = ColorMode.TRUECOLOR,
+ background = [0.031, 0.031, 0.078],
+ transparent = false,
+ spin = 1,
+ pitch = 0.08,
+ zoom = 1,
+ tint = [1, 1, 1],
+ } = options;
+
+ // The framebuffer is twice as tall as the character grid: one text row is
+ // two vertical pixels via the half-block.
+ const fb = createFramebuffer(Math.max(2, Math.round(width)), Math.max(2, Math.round(height)) * 2);
+ const clip = selectAnimation(model, animation);
+ const framing = computeFraming(model, clip);
+
+ const state = { yaw: 0, pitch, zoom };
+
+ return {
+ model,
+ animation: clip,
+ framing,
+ width: fb.width,
+ height: fb.height / 2,
+ get orbit() { return { ...state }; },
+
+ /** Absolute camera control, for interactive use. */
+ setOrbit({ yaw, pitch: p, zoom: z } = {}) {
+ if (Number.isFinite(yaw)) state.yaw = yaw;
+ // Clamping stops the camera from tumbling over the pole, where the
+ // look-at up vector degenerates and the model flips upside down.
+ if (Number.isFinite(p)) state.pitch = Math.max(-1.45, Math.min(1.45, p));
+ if (Number.isFinite(z)) state.zoom = Math.max(0.25, Math.min(8, z));
+ return { ...state };
+ },
+
+ /**
+ * Render the frame at `time` seconds.
+ * @returns {string} terminal-ready text, no trailing newline
+ */
+ frame(time = 0) {
+ poseModel(model, clip, time);
+ renderToFramebuffer(fb, model, {
+ yaw: state.yaw + time * spin,
+ pitch: state.pitch,
+ zoom: state.zoom,
+ center: poseCenter(model),
+ framing,
+ tint,
+ });
+ return framebufferToText(fb, { mode, background, transparent });
+ },
+ };
+}
+
+/** One model, one frame, one call. */
+export async function renderOnce(source, options = {}) {
+ const model = await loadModel(source, options);
+ return createRenderer(model, options).frame(options.time ?? 0);
+}
+
+/** Everything the CLI and the hosted stream both need to describe a model. */
+export function describeModel(model) {
+ return {
+ triangles: model.triangleCount,
+ primitives: model.primitives.length,
+ nodes: model.nodes.length,
+ skinned: model.skinned,
+ animations: model.animations.map((a) => ({ name: a.name, duration: Number(a.duration.toFixed(3)) })),
+ };
+}
+
+export { detectColorMode as detectTerminalColor };
diff --git a/packages/tty-3d/src/math.js b/packages/tty-3d/src/math.js
new file mode 100644
index 000000000..9545d10a0
--- /dev/null
+++ b/packages/tty-3d/src/math.js
@@ -0,0 +1,187 @@
+// Minimal column-major 4x4 / vec3 math. Deliberately not a dependency: this is
+// ~15 operations used by the rasterizer's hot loop, and every one of them is
+// allocation-free on purpose (see mulPoint/mulDir, which write into an out
+// array). A general-purpose matrix library would allocate a vector per vertex
+// and dominate the frame budget on a 60k-triangle avatar.
+//
+// Layout matches glTF: column-major, m[column * 4 + row].
+
+export function mat4Identity(out = new Float64Array(16)) {
+ out.fill(0);
+ out[0] = out[5] = out[10] = out[15] = 1;
+ return out;
+}
+
+const mulScratch = new Float64Array(16);
+
+export function mat4Multiply(a, b, out = new Float64Array(16)) {
+ // Aliasing guard. `mat4Multiply(m, ibm, m)` reads a[0..3] again while
+ // computing column 1, so writing straight into an aliased `out` corrupts the
+ // source halfway through and produces a matrix that looks plausible and
+ // shears the mesh. That shipped as spikes radiating off every joint until it
+ // was caught by rendering a frame to PNG and looking at it.
+ const target = (out === a || out === b) ? mulScratch : out;
+ for (let c = 0; c < 4; c += 1) {
+ const b0 = b[c * 4], b1 = b[c * 4 + 1], b2 = b[c * 4 + 2], b3 = b[c * 4 + 3];
+ target[c * 4] = a[0] * b0 + a[4] * b1 + a[8] * b2 + a[12] * b3;
+ target[c * 4 + 1] = a[1] * b0 + a[5] * b1 + a[9] * b2 + a[13] * b3;
+ target[c * 4 + 2] = a[2] * b0 + a[6] * b1 + a[10] * b2 + a[14] * b3;
+ target[c * 4 + 3] = a[3] * b0 + a[7] * b1 + a[11] * b2 + a[15] * b3;
+ }
+ if (target !== out) out.set(target);
+ return out;
+}
+
+export function mat4FromTRS(t, r, s, out = new Float64Array(16)) {
+ const [x, y, z, w] = r;
+ const x2 = x + x, y2 = y + y, z2 = z + z;
+ const xx = x * x2, xy = x * y2, xz = x * z2;
+ const yy = y * y2, yz = y * z2, zz = z * z2;
+ const wx = w * x2, wy = w * y2, wz = w * z2;
+ out[0] = (1 - (yy + zz)) * s[0];
+ out[1] = (xy + wz) * s[0];
+ out[2] = (xz - wy) * s[0];
+ out[3] = 0;
+ out[4] = (xy - wz) * s[1];
+ out[5] = (1 - (xx + zz)) * s[1];
+ out[6] = (yz + wx) * s[1];
+ out[7] = 0;
+ out[8] = (xz + wy) * s[2];
+ out[9] = (yz - wx) * s[2];
+ out[10] = (1 - (xx + yy)) * s[2];
+ out[11] = 0;
+ out[12] = t[0];
+ out[13] = t[1];
+ out[14] = t[2];
+ out[15] = 1;
+ return out;
+}
+
+export function mat4Invert(m, out = new Float64Array(16)) {
+ const a00 = m[0], a01 = m[1], a02 = m[2], a03 = m[3];
+ const a10 = m[4], a11 = m[5], a12 = m[6], a13 = m[7];
+ const a20 = m[8], a21 = m[9], a22 = m[10], a23 = m[11];
+ const a30 = m[12], a31 = m[13], a32 = m[14], a33 = m[15];
+
+ const b00 = a00 * a11 - a01 * a10, b01 = a00 * a12 - a02 * a10;
+ const b02 = a00 * a13 - a03 * a10, b03 = a01 * a12 - a02 * a11;
+ const b04 = a01 * a13 - a03 * a11, b05 = a02 * a13 - a03 * a12;
+ const b06 = a20 * a31 - a21 * a30, b07 = a20 * a32 - a22 * a30;
+ const b08 = a20 * a33 - a23 * a30, b09 = a21 * a32 - a22 * a31;
+ const b10 = a21 * a33 - a23 * a31, b11 = a22 * a33 - a23 * a32;
+
+ const det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06;
+ // A degenerate node matrix (zero scale on an axis is legal glTF and appears
+ // in real avatars on hidden helper nodes) has no inverse. Returning identity
+ // keeps the joint it belongs to at rest instead of filling the vertex buffer
+ // with NaN, which the rasterizer would silently drop as a whole limb.
+ if (!det) return mat4Identity(out);
+ const d = 1 / det;
+
+ out[0] = (a11 * b11 - a12 * b10 + a13 * b09) * d;
+ out[1] = (a02 * b10 - a01 * b11 - a03 * b09) * d;
+ out[2] = (a31 * b05 - a32 * b04 + a33 * b03) * d;
+ out[3] = (a22 * b04 - a21 * b05 - a23 * b03) * d;
+ out[4] = (a12 * b08 - a10 * b11 - a13 * b07) * d;
+ out[5] = (a00 * b11 - a02 * b08 + a03 * b07) * d;
+ out[6] = (a32 * b02 - a30 * b05 - a33 * b01) * d;
+ out[7] = (a20 * b05 - a22 * b02 + a23 * b01) * d;
+ out[8] = (a10 * b10 - a11 * b08 + a13 * b06) * d;
+ out[9] = (a01 * b08 - a00 * b10 - a03 * b06) * d;
+ out[10] = (a30 * b04 - a31 * b02 + a33 * b00) * d;
+ out[11] = (a21 * b02 - a20 * b04 - a23 * b00) * d;
+ out[12] = (a11 * b07 - a10 * b09 - a12 * b06) * d;
+ out[13] = (a00 * b09 - a01 * b07 + a02 * b06) * d;
+ out[14] = (a31 * b01 - a30 * b03 - a32 * b00) * d;
+ out[15] = (a20 * b03 - a21 * b01 + a22 * b00) * d;
+ return out;
+}
+
+/** Transpose of the inverse, for normals under non-uniform scale. */
+export function mat4NormalMatrix(m, out = new Float64Array(16)) {
+ const inv = mat4Invert(m);
+ for (let r = 0; r < 4; r += 1) for (let c = 0; c < 4; c += 1) out[c * 4 + r] = inv[r * 4 + c];
+ return out;
+}
+
+export function mulPoint(m, x, y, z, out) {
+ out[0] = m[0] * x + m[4] * y + m[8] * z + m[12];
+ out[1] = m[1] * x + m[5] * y + m[9] * z + m[13];
+ out[2] = m[2] * x + m[6] * y + m[10] * z + m[14];
+ return out;
+}
+
+export function mulDir(m, x, y, z, out) {
+ out[0] = m[0] * x + m[4] * y + m[8] * z;
+ out[1] = m[1] * x + m[5] * y + m[9] * z;
+ out[2] = m[2] * x + m[6] * y + m[10] * z;
+ return out;
+}
+
+export function normalize(v) {
+ const len = Math.hypot(v[0], v[1], v[2]);
+ if (!len) return v;
+ v[0] /= len; v[1] /= len; v[2] /= len;
+ return v;
+}
+
+/** Right-handed look-at view matrix. */
+export function mat4LookAt(eye, target, up, out = new Float64Array(16)) {
+ const z = normalize([eye[0] - target[0], eye[1] - target[1], eye[2] - target[2]]);
+ const x = normalize([
+ up[1] * z[2] - up[2] * z[1],
+ up[2] * z[0] - up[0] * z[2],
+ up[0] * z[1] - up[1] * z[0],
+ ]);
+ const y = [
+ z[1] * x[2] - z[2] * x[1],
+ z[2] * x[0] - z[0] * x[2],
+ z[0] * x[1] - z[1] * x[0],
+ ];
+ out[0] = x[0]; out[1] = y[0]; out[2] = z[0]; out[3] = 0;
+ out[4] = x[1]; out[5] = y[1]; out[6] = z[1]; out[7] = 0;
+ out[8] = x[2]; out[9] = y[2]; out[10] = z[2]; out[11] = 0;
+ out[12] = -(x[0] * eye[0] + x[1] * eye[1] + x[2] * eye[2]);
+ out[13] = -(y[0] * eye[0] + y[1] * eye[1] + y[2] * eye[2]);
+ out[14] = -(z[0] * eye[0] + z[1] * eye[1] + z[2] * eye[2]);
+ out[15] = 1;
+ return out;
+}
+
+export function mat4Perspective(fovY, aspect, near, far, out = new Float64Array(16)) {
+ const f = 1 / Math.tan(fovY / 2);
+ out.fill(0);
+ out[0] = f / aspect;
+ out[5] = f;
+ out[10] = (far + near) / (near - far);
+ out[11] = -1;
+ out[14] = (2 * far * near) / (near - far);
+ return out;
+}
+
+/** Spherical-linear interpolation between two quaternions, shortest arc. */
+export function slerp(a, b, t, out = new Float64Array(4)) {
+ let cos = a[0] * b[0] + a[1] * b[1] + a[2] * b[2] + a[3] * b[3];
+ let bx = b[0], by = b[1], bz = b[2], bw = b[3];
+ if (cos < 0) { cos = -cos; bx = -bx; by = -by; bz = -bz; bw = -bw; }
+ // Near-parallel quaternions make sin(theta) vanish and the division blow up;
+ // linear interpolation is within float noise of the arc there.
+ if (cos > 0.9995) {
+ out[0] = a[0] + (bx - a[0]) * t;
+ out[1] = a[1] + (by - a[1]) * t;
+ out[2] = a[2] + (bz - a[2]) * t;
+ out[3] = a[3] + (bw - a[3]) * t;
+ } else {
+ const theta = Math.acos(cos);
+ const sin = Math.sin(theta);
+ const wa = Math.sin((1 - t) * theta) / sin;
+ const wb = Math.sin(t * theta) / sin;
+ out[0] = a[0] * wa + bx * wb;
+ out[1] = a[1] * wa + by * wb;
+ out[2] = a[2] * wa + bz * wb;
+ out[3] = a[3] * wa + bw * wb;
+ }
+ const len = Math.hypot(out[0], out[1], out[2], out[3]) || 1;
+ out[0] /= len; out[1] /= len; out[2] /= len; out[3] /= len;
+ return out;
+}
diff --git a/packages/tty-3d/src/model.js b/packages/tty-3d/src/model.js
new file mode 100644
index 000000000..15c605429
--- /dev/null
+++ b/packages/tty-3d/src/model.js
@@ -0,0 +1,353 @@
+// Load a GLB into the flat, typed-array form the rasterizer wants.
+//
+// Parsing is delegated to @gltf-transform/core rather than hand-rolled: it is
+// the reference glTF I/O implementation, it already understands the extension
+// soup real avatars ship with, and a bespoke parser here would be a permanent
+// liability for zero gain. What this module owns is the part gltf-transform
+// deliberately does not do: turning a scene graph into skinned world-space
+// triangles at a point in time.
+//
+// EXT_meshopt_compression is not optional. Most three.ws avatars ship with it,
+// and a reader that skips the decoder does not fail loudly, it reads garbage
+// vertex data. The decoder is registered unconditionally.
+
+import { NodeIO, WebIO, getBounds } from '@gltf-transform/core';
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
+import { MeshoptDecoder } from 'meshoptimizer';
+import { mat4FromTRS, mat4Identity, mat4Multiply, mat4NormalMatrix, mulDir, mulPoint, normalize, slerp } from './math.js';
+
+const DEFAULT_COLOR = [0.82, 0.84, 0.9];
+
+async function makeIO(Ctor) {
+ await MeshoptDecoder.ready;
+ const io = new Ctor().registerExtensions(ALL_EXTENSIONS).registerDependencies({
+ 'meshopt.decoder': MeshoptDecoder,
+ });
+ return io;
+}
+
+/** Read a GLB from bytes. Accepts ArrayBuffer, Uint8Array, or Buffer. */
+export async function loadModelFromBytes(bytes) {
+ const io = await makeIO(WebIO);
+ const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+ return buildModel(await io.readBinary(u8));
+}
+
+/** Read a GLB or glTF from the filesystem. */
+export async function loadModelFromFile(path) {
+ const io = await makeIO(NodeIO);
+ return buildModel(await io.read(path));
+}
+
+function materialColor(material) {
+ if (!material) return DEFAULT_COLOR;
+ const base = material.getBaseColorFactor();
+ if (!base) return DEFAULT_COLOR;
+ const [r, g, b, a] = base;
+ // A fully transparent material is almost always a hidden helper plane or an
+ // eyelash card; drawing it opaque would paste a grey rectangle over the face.
+ if (a !== undefined && a < 0.05) return null;
+ return [r, g, b];
+}
+
+function collectNodes(doc) {
+ const root = doc.getRoot();
+ const scene = root.getDefaultScene() ?? root.listScenes()[0] ?? null;
+ const nodes = [];
+ const index = new Map();
+
+ const visit = (node, parent) => {
+ const id = nodes.length;
+ index.set(node, id);
+ nodes.push({
+ id,
+ parent,
+ node,
+ restT: Float64Array.from(node.getTranslation()),
+ restR: Float64Array.from(node.getRotation()),
+ restS: Float64Array.from(node.getScale()),
+ local: new Float64Array(16),
+ world: new Float64Array(16),
+ });
+ for (const child of node.listChildren()) visit(child, id);
+ };
+
+ const roots = scene ? scene.listChildren() : root.listNodes().filter((n) => !n.listParents().some((p) => p.propertyType === 'Node'));
+ for (const node of roots) visit(node, -1);
+ return { nodes, index };
+}
+
+function buildModel(doc) {
+ const { nodes, index } = collectNodes(doc);
+ const primitives = [];
+
+ for (const entry of nodes) {
+ const mesh = entry.node.getMesh();
+ if (!mesh) continue;
+ const skin = entry.node.getSkin();
+
+ let jointNodes = null;
+ let inverseBind = null;
+ if (skin) {
+ // NOT filtered. JOINTS_0 indexes into this list positionally, so dropping
+ // an unresolvable joint shifts every joint after it and rigs the mesh to
+ // the wrong bones. A hole is kept as -1 and handled at skin time.
+ jointNodes = skin.listJoints().map((j) => {
+ const id = index.get(j);
+ return id === undefined ? -1 : id;
+ });
+ const ibmAccessor = skin.getInverseBindMatrices();
+ inverseBind = ibmAccessor ? Float64Array.from(ibmAccessor.getArray()) : null;
+ }
+
+ for (const prim of mesh.listPrimitives()) {
+ // Mode 4 is TRIANGLES. Points, lines, strips and fans exist in the wild
+ // but never in an avatar body; skipping them is honest, and a strip
+ // silently rasterized as a triangle soup would render as shredded mesh.
+ if (prim.getMode() !== 4) continue;
+ const position = prim.getAttribute('POSITION');
+ if (!position) continue;
+ const color = materialColor(prim.getMaterial());
+ if (!color) continue;
+
+ const positions = Float32Array.from(position.getArray());
+ const normalAttr = prim.getAttribute('NORMAL');
+ const indicesAccessor = prim.getIndices();
+ const count = positions.length / 3;
+ const indices = indicesAccessor
+ ? Uint32Array.from(indicesAccessor.getArray())
+ : Uint32Array.from({ length: count }, (_, i) => i);
+
+ const joints = skin ? prim.getAttribute('JOINTS_0') : null;
+ const weights = skin ? prim.getAttribute('WEIGHTS_0') : null;
+
+ primitives.push({
+ nodeId: entry.id,
+ color,
+ positions,
+ normals: normalAttr ? Float32Array.from(normalAttr.getArray()) : deriveNormals(positions, indices),
+ indices,
+ jointNodes: joints && weights ? jointNodes : null,
+ inverseBind: joints && weights ? inverseBind : null,
+ joints: joints ? Uint16Array.from(joints.getArray()) : null,
+ weights: weights ? Float32Array.from(weights.getArray()) : null,
+ // Scratch buffers, reused every frame so a 60 fps turntable does not
+ // allocate two arrays per primitive per frame.
+ outPositions: new Float32Array(positions.length),
+ outNormals: new Float32Array(positions.length),
+ poseStamp: -1,
+ });
+ }
+ }
+
+ const animations = doc.getRoot().listAnimations().map((anim) => ({
+ name: anim.getName() || 'clip',
+ duration: anim.listChannels().reduce((max, ch) => {
+ const input = ch.getSampler()?.getInput();
+ if (!input) return max;
+ const arr = input.getArray();
+ return Math.max(max, arr.length ? arr[arr.length - 1] : 0);
+ }, 0),
+ channels: anim.listChannels().map((ch) => {
+ const sampler = ch.getSampler();
+ const target = ch.getTargetNode();
+ return {
+ nodeId: target ? index.get(target) : undefined,
+ path: ch.getTargetPath(),
+ interpolation: sampler?.getInterpolation() ?? 'LINEAR',
+ times: sampler?.getInput() ? Float32Array.from(sampler.getInput().getArray()) : new Float32Array(0),
+ values: sampler?.getOutput() ? Float32Array.from(sampler.getOutput().getArray()) : new Float32Array(0),
+ };
+ }).filter((ch) => ch.nodeId !== undefined && ch.times.length > 0),
+ })).filter((a) => a.duration > 0 && a.channels.length > 0);
+
+ const bbox = getBounds(doc.getRoot().getDefaultScene() ?? doc.getRoot().listScenes()[0]);
+
+ return {
+ nodes,
+ primitives,
+ animations,
+ poseStamp: 0,
+ bounds: bbox ? { min: bbox.min.slice(), max: bbox.max.slice() } : { min: [-1, -1, -1], max: [1, 1, 1] },
+ triangleCount: primitives.reduce((n, p) => n + p.indices.length / 3, 0),
+ skinned: primitives.some((p) => p.joints),
+ };
+}
+
+/** Flat face normals for a primitive that shipped without a NORMAL attribute. */
+function deriveNormals(positions, indices) {
+ const normals = new Float32Array(positions.length);
+ for (let i = 0; i < indices.length; i += 3) {
+ const a = indices[i] * 3, b = indices[i + 1] * 3, c = indices[i + 2] * 3;
+ const ux = positions[b] - positions[a], uy = positions[b + 1] - positions[a + 1], uz = positions[b + 2] - positions[a + 2];
+ const vx = positions[c] - positions[a], vy = positions[c + 1] - positions[a + 1], vz = positions[c + 2] - positions[a + 2];
+ const nx = uy * vz - uz * vy, ny = uz * vx - ux * vz, nz = ux * vy - uy * vx;
+ for (const o of [a, b, c]) {
+ normals[o] += nx; normals[o + 1] += ny; normals[o + 2] += nz;
+ }
+ }
+ for (let i = 0; i < normals.length; i += 3) {
+ const len = Math.hypot(normals[i], normals[i + 1], normals[i + 2]) || 1;
+ normals[i] /= len; normals[i + 1] /= len; normals[i + 2] /= len;
+ }
+ return normals;
+}
+
+/** Sample one animation channel at time t into `out`. */
+export function sampleChannel(channel, t, out) {
+ const { times, values, interpolation, path } = channel;
+ const stride = path === 'rotation' ? 4 : 3;
+ const n = times.length;
+ const clamped = Math.min(Math.max(t, times[0]), times[n - 1]);
+
+ let hi = 1;
+ while (hi < n && times[hi] < clamped) hi += 1;
+ const lo = Math.max(0, hi - 1);
+ hi = Math.min(hi, n - 1);
+
+ const span = times[hi] - times[lo];
+ const alpha = span > 0 ? (clamped - times[lo]) / span : 0;
+
+ // CUBICSPLINE stores [inTangent, value, outTangent] per key. Reading its
+ // middle triple and interpolating linearly is a visible but tiny error at
+ // terminal resolution; reading it as if it were LINEAR would read tangents
+ // as values and throw the limb across the screen.
+ const cubic = interpolation === 'CUBICSPLINE';
+ const base = (i) => (cubic ? (i * 3 + 1) : i) * stride;
+ const loBase = base(lo), hiBase = base(hi);
+
+ if (interpolation === 'STEP') {
+ for (let i = 0; i < stride; i += 1) out[i] = values[loBase + i];
+ return out;
+ }
+ if (path === 'rotation') {
+ return slerp(
+ values.subarray(loBase, loBase + 4),
+ values.subarray(hiBase, hiBase + 4),
+ alpha,
+ out,
+ );
+ }
+ for (let i = 0; i < stride; i += 1) {
+ out[i] = values[loBase + i] + (values[hiBase + i] - values[loBase + i]) * alpha;
+ }
+ return out;
+}
+
+const scratchQuat = new Float64Array(4);
+const scratchVec = new Float64Array(3);
+
+/** Pose every node for `animation` at `time`, then recompute world matrices. */
+export function poseModel(model, animation, time) {
+ // Bumped so transformPrimitive can skip vertices it already transformed for
+ // this pose. The camera needs the posed bounds before rasterizing, so every
+ // frame would otherwise skin the whole mesh twice.
+ model.poseStamp = (model.poseStamp ?? 0) + 1;
+ for (const entry of model.nodes) {
+ entry.curT = entry.restT;
+ entry.curR = entry.restR;
+ entry.curS = entry.restS;
+ }
+
+ if (animation) {
+ const t = animation.duration > 0 ? time % animation.duration : 0;
+ for (const channel of animation.channels) {
+ const entry = model.nodes[channel.nodeId];
+ if (!entry) continue;
+ if (channel.path === 'rotation') {
+ entry.curR = Float64Array.from(sampleChannel(channel, t, scratchQuat));
+ } else if (channel.path === 'translation') {
+ entry.curT = Float64Array.from(sampleChannel(channel, t, scratchVec));
+ } else if (channel.path === 'scale') {
+ entry.curS = Float64Array.from(sampleChannel(channel, t, scratchVec));
+ }
+ }
+ }
+
+ for (const entry of model.nodes) {
+ mat4FromTRS(entry.curT, entry.curR, entry.curS, entry.local);
+ if (entry.parent === -1) entry.world.set(entry.local);
+ else mat4Multiply(model.nodes[entry.parent].world, entry.local, entry.world);
+ }
+ return model;
+}
+
+const jointMatrixScratch = [];
+
+/**
+ * Write world-space positions and normals for one primitive into its scratch
+ * buffers, applying linear blend skinning when the primitive is rigged.
+ */
+export function transformPrimitive(model, prim) {
+ if (prim.poseStamp === model.poseStamp) return prim;
+ prim.poseStamp = model.poseStamp;
+ const { positions, normals, outPositions, outNormals } = prim;
+ const node = model.nodes[prim.nodeId];
+ const count = positions.length / 3;
+ const p = [0, 0, 0];
+ const nrm = [0, 0, 0];
+
+ if (!prim.joints || !prim.jointNodes) {
+ const world = node.world;
+ const normalMat = mat4NormalMatrix(world);
+ for (let i = 0; i < count; i += 1) {
+ const o = i * 3;
+ mulPoint(world, positions[o], positions[o + 1], positions[o + 2], p);
+ outPositions[o] = p[0]; outPositions[o + 1] = p[1]; outPositions[o + 2] = p[2];
+ mulDir(normalMat, normals[o], normals[o + 1], normals[o + 2], nrm);
+ normalize(nrm);
+ outNormals[o] = nrm[0]; outNormals[o + 1] = nrm[1]; outNormals[o + 2] = nrm[2];
+ }
+ return prim;
+ }
+
+ // glTF defines the skinning matrix as
+ // inverse(meshNodeWorld) * jointWorld * inverseBind
+ // and then says the result is transformed by meshNodeWorld again, so the two
+ // cancel exactly and the skinned vertex is simply jointWorld * inverseBind * v.
+ // Applying the leading inverse WITHOUT re-applying meshNodeWorld afterwards
+ // is a real and subtle bug: on a model whose skeleton root carries the
+ // Collada Z-up to glTF Y-up rotation (CesiumMan, and every avatar exported
+ // through that path) it cancels the up-axis correction and the character
+ // renders lying on its back, one third too short. Verified against
+ // public/avatars/cesium-man.glb in test/skin.test.js.
+ const jointCount = prim.jointNodes.length;
+ while (jointMatrixScratch.length < jointCount) jointMatrixScratch.push(new Float64Array(16));
+
+ for (let j = 0; j < jointCount; j += 1) {
+ const nodeId = prim.jointNodes[j];
+ const jointEntry = nodeId >= 0 ? model.nodes[nodeId] : null;
+ const m = jointMatrixScratch[j];
+ if (!jointEntry) { mat4Identity(m); continue; }
+ m.set(jointEntry.world);
+ if (prim.inverseBind) {
+ const ibm = prim.inverseBind.subarray(j * 16, j * 16 + 16);
+ mat4Multiply(m, ibm, m);
+ }
+ }
+
+ const acc = new Float64Array(16);
+ for (let i = 0; i < count; i += 1) {
+ const o = i * 3, w = i * 4;
+ acc.fill(0);
+ let total = 0;
+ for (let k = 0; k < 4; k += 1) {
+ const weight = prim.weights[w + k];
+ if (!weight) continue;
+ const m = jointMatrixScratch[prim.joints[w + k]];
+ if (!m) continue;
+ for (let e = 0; e < 16; e += 1) acc[e] += m[e] * weight;
+ total += weight;
+ }
+ // A vertex whose weights sum to zero is unrigged (loose hair cards do this).
+ // Falling back to the mesh transform keeps it attached instead of collapsing
+ // it onto the origin, which reads as a spike through the model.
+ const m = total > 1e-6 ? acc : node.world;
+ mulPoint(m, positions[o], positions[o + 1], positions[o + 2], p);
+ outPositions[o] = p[0]; outPositions[o + 1] = p[1]; outPositions[o + 2] = p[2];
+ mulDir(m, normals[o], normals[o + 1], normals[o + 2], nrm);
+ normalize(nrm);
+ outNormals[o] = nrm[0]; outNormals[o + 1] = nrm[1]; outNormals[o + 2] = nrm[2];
+ }
+ return prim;
+}
diff --git a/packages/tty-3d/src/raster.js b/packages/tty-3d/src/raster.js
new file mode 100644
index 000000000..6132443e5
--- /dev/null
+++ b/packages/tty-3d/src/raster.js
@@ -0,0 +1,224 @@
+// A z-buffered software triangle rasterizer.
+//
+// There is no GPU here on purpose. The whole point of this package is that it
+// runs anywhere a Node process runs: a laptop, a CI job, a Cloud Run container
+// with no display, an SSH session. So everything is scanline work on typed
+// arrays, sized to a terminal rather than a monitor, which is what makes it
+// fast enough to animate: a 120x64 framebuffer is 7,680 pixels, three orders
+// of magnitude less fill than a 1080p frame.
+
+import { mat4LookAt, mat4Multiply, mat4Perspective, normalize } from './math.js';
+import { poseModel, transformPrimitive } from './model.js';
+
+export function createFramebuffer(width, height) {
+ return {
+ width,
+ height,
+ color: new Float32Array(width * height * 3),
+ depth: new Float32Array(width * height),
+ coverage: new Uint8Array(width * height),
+ };
+}
+
+export function clearFramebuffer(fb) {
+ fb.color.fill(0);
+ fb.depth.fill(Infinity);
+ fb.coverage.fill(0);
+ return fb;
+}
+
+/** World-space bounds of the model in its current pose. */
+export function poseBounds(model) {
+ const min = [Infinity, Infinity, Infinity];
+ const max = [-Infinity, -Infinity, -Infinity];
+ for (const prim of model.primitives) {
+ const p = transformPrimitive(model, prim).outPositions;
+ for (let i = 0; i < p.length; i += 3) {
+ for (let k = 0; k < 3; k += 1) {
+ const v = p[i + k];
+ if (v < min[k]) min[k] = v;
+ if (v > max[k]) max[k] = v;
+ }
+ }
+ }
+ if (!Number.isFinite(min[0])) return { min: [-1, -1, -1], max: [1, 1, 1] };
+ return { min, max };
+}
+
+/**
+ * Framing that holds still while an animation plays.
+ *
+ * Auto-framing off the current frame's bounds is the obvious approach and it
+ * looks terrible: the silhouette changes every frame, so the camera breathes.
+ * Unioning every frame instead is worse on anything with root motion, which is
+ * most walk cycles: the union is a corridor as long as the character walks, and
+ * fitting that corridor shrinks the character to a speck at the end of it. That
+ * was measured, not guessed, on public/avatars/cesium-man.glb.
+ *
+ * So the two halves are separated. The RADIUS is fixed, taken as the largest
+ * any single frame needs, which keeps the subject a constant size. The CENTER is
+ * recomputed per frame, which keeps a character that walks from leaving the
+ * shot. Together: no breathing, no drift.
+ */
+export function computeFraming(model, animation, samples = 12) {
+ let halfHeight = 0;
+ let halfWidth = 0;
+ const take = () => {
+ const b = poseBounds(model);
+ halfHeight = Math.max(halfHeight, (b.max[1] - b.min[1]) / 2);
+ // Worst case across a full turntable: the model presents its X extent at
+ // one yaw and its Z extent a quarter turn later, so framing for the larger
+ // of the two is what stops a shoulder-width character from being clipped
+ // halfway through the spin.
+ halfWidth = Math.max(halfWidth, (b.max[0] - b.min[0]) / 2, (b.max[2] - b.min[2]) / 2);
+ };
+ if (!animation) {
+ poseModel(model, null, 0);
+ take();
+ } else {
+ for (let i = 0; i < samples; i += 1) {
+ poseModel(model, animation, (animation.duration * i) / samples);
+ take();
+ }
+ }
+ return { halfHeight: Math.max(1e-4, halfHeight), halfWidth: Math.max(1e-4, halfWidth) };
+}
+
+/** Centre of the model in whatever pose it currently holds. */
+export function poseCenter(model) {
+ const b = poseBounds(model);
+ return [(b.min[0] + b.max[0]) / 2, (b.min[1] + b.max[1]) / 2, (b.min[2] + b.max[2]) / 2];
+}
+
+const KEY_LIGHT = normalize([-0.4, 0.75, 0.9]);
+const FILL_LIGHT = normalize([0.7, 0.1, 0.35]);
+
+/**
+ * Rasterize the model into `fb`.
+ *
+ * @param {object} fb framebuffer from createFramebuffer
+ * @param {object} model loaded model
+ * @param {object} opts
+ * @param {number} opts.yaw camera azimuth, radians
+ * @param {number} opts.pitch camera elevation, radians
+ * @param {number} opts.zoom 1 fits the model, >1 moves closer
+ * @param {object} opts.framing fixed framing extents from computeFraming
+ * @param {number[]} opts.center world-space point to look at
+ * @param {number[]} opts.tint optional rgb multiplier in 0..1
+ */
+export function renderToFramebuffer(fb, model, opts) {
+ const { yaw = 0, pitch = 0.05, zoom = 1, tint = [1, 1, 1] } = opts;
+ clearFramebuffer(fb);
+
+ const center = opts.center ?? poseCenter(model);
+ const framing = opts.framing ?? computeFraming(model, null);
+
+ const fov = Math.PI / 4;
+ // Terminal cells are about twice as tall as they are wide and the half-block
+ // already doubles vertical resolution, so framebuffer pixels are square and
+ // the aspect correction is just width over height.
+ const aspect = fb.width / fb.height;
+ const halfV = Math.tan(fov / 2);
+ const halfH = halfV * aspect;
+
+ // Fit height and width independently rather than fitting a bounding sphere.
+ // A sphere around a human figure is dominated by its diagonal and wastes
+ // roughly a third of the frame on empty space above and below the subject.
+ // Then push back by the half width, because perspective magnifies whichever
+ // part of the model is nearest the camera and a flat fit clips it.
+ const fitDistance = Math.max(framing.halfHeight / halfV, framing.halfWidth / halfH) * 1.02 + framing.halfWidth * 0.5;
+ const radius = Math.max(framing.halfHeight, framing.halfWidth);
+ const distance = fitDistance / Math.max(0.2, zoom);
+
+ const eye = [
+ center[0] + distance * Math.cos(pitch) * Math.sin(yaw),
+ center[1] + distance * Math.sin(pitch),
+ center[2] + distance * Math.cos(pitch) * Math.cos(yaw),
+ ];
+ const view = mat4LookAt(eye, center, [0, 1, 0]);
+ const proj = mat4Perspective(fov, aspect, Math.max(1e-3, distance - radius * 2), distance + radius * 4);
+ const viewProj = mat4Multiply(proj, view);
+
+ const clip = new Float64Array(4);
+ const sx = new Float64Array(3), sy = new Float64Array(3), sz = new Float64Array(3);
+ const nx = new Float64Array(3), ny = new Float64Array(3), nz = new Float64Array(3);
+
+ for (const prim of model.primitives) {
+ const { outPositions: P, outNormals: N, indices, color } = transformPrimitive(model, prim);
+
+ for (let t = 0; t < indices.length; t += 3) {
+ let behind = false;
+ for (let v = 0; v < 3; v += 1) {
+ const o = indices[t + v] * 3;
+ const x = P[o], y = P[o + 1], z = P[o + 2];
+ clip[0] = viewProj[0] * x + viewProj[4] * y + viewProj[8] * z + viewProj[12];
+ clip[1] = viewProj[1] * x + viewProj[5] * y + viewProj[9] * z + viewProj[13];
+ clip[2] = viewProj[2] * x + viewProj[6] * y + viewProj[10] * z + viewProj[14];
+ clip[3] = viewProj[3] * x + viewProj[7] * y + viewProj[11] * z + viewProj[15];
+ // Whole-triangle rejection instead of near-plane clipping. A triangle
+ // straddling the eye is rare at a fit-to-frame distance, and dropping
+ // it costs one facet where clipping would cost a per-frame allocation.
+ if (clip[3] <= 1e-6) { behind = true; break; }
+ const inv = 1 / clip[3];
+ sx[v] = (clip[0] * inv * 0.5 + 0.5) * fb.width;
+ sy[v] = (1 - (clip[1] * inv * 0.5 + 0.5)) * fb.height;
+ sz[v] = clip[2] * inv;
+ nx[v] = N[o]; ny[v] = N[o + 1]; nz[v] = N[o + 2];
+ }
+ if (behind) continue;
+
+ const area = (sx[1] - sx[0]) * (sy[2] - sy[0]) - (sx[2] - sx[0]) * (sy[1] - sy[0]);
+ // Backface culling by winding. Two-sided materials exist, but a closed
+ // avatar body doubles its fill cost for pixels it will never show.
+ if (area >= -1e-9) continue;
+
+ const minX = Math.max(0, Math.floor(Math.min(sx[0], sx[1], sx[2])));
+ const maxX = Math.min(fb.width - 1, Math.ceil(Math.max(sx[0], sx[1], sx[2])));
+ const minY = Math.max(0, Math.floor(Math.min(sy[0], sy[1], sy[2])));
+ const maxY = Math.min(fb.height - 1, Math.ceil(Math.max(sy[0], sy[1], sy[2])));
+ if (minX > maxX || minY > maxY) continue;
+
+ const invArea = 1 / area;
+ for (let py = minY; py <= maxY; py += 1) {
+ const cy = py + 0.5;
+ for (let px = minX; px <= maxX; px += 1) {
+ const cx = px + 0.5;
+ const w0 = ((sx[1] - cx) * (sy[2] - cy) - (sx[2] - cx) * (sy[1] - cy)) * invArea;
+ if (w0 < 0) continue;
+ const w1 = ((sx[2] - cx) * (sy[0] - cy) - (sx[0] - cx) * (sy[2] - cy)) * invArea;
+ if (w1 < 0) continue;
+ const w2 = 1 - w0 - w1;
+ if (w2 < 0) continue;
+
+ const depth = w0 * sz[0] + w1 * sz[1] + w2 * sz[2];
+ const idx = py * fb.width + px;
+ if (depth >= fb.depth[idx]) continue;
+ fb.depth[idx] = depth;
+ fb.coverage[idx] = 1;
+
+ let vnx = w0 * nx[0] + w1 * nx[1] + w2 * nx[2];
+ let vny = w0 * ny[0] + w1 * ny[1] + w2 * ny[2];
+ let vnz = w0 * nz[0] + w1 * nz[1] + w2 * nz[2];
+ const len = Math.hypot(vnx, vny, vnz) || 1;
+ vnx /= len; vny /= len; vnz /= len;
+
+ const key = Math.max(0, vnx * KEY_LIGHT[0] + vny * KEY_LIGHT[1] + vnz * KEY_LIGHT[2]);
+ const fill = Math.max(0, vnx * FILL_LIGHT[0] + vny * FILL_LIGHT[1] + vnz * FILL_LIGHT[2]);
+ // Rim term: the silhouette is the only cue for shape at this
+ // resolution, so faces turning away from the camera get lifted
+ // rather than crushed to black. Without it a terminal render of a
+ // dark model reads as an unreadable blob.
+ const facing = Math.abs(vnz);
+ const rim = Math.pow(1 - Math.min(1, facing), 3) * 0.55;
+ const lit = 0.16 + key * 0.82 + fill * 0.22 + rim;
+
+ const o = idx * 3;
+ fb.color[o] = Math.min(1, color[0] * lit * tint[0]);
+ fb.color[o + 1] = Math.min(1, color[1] * lit * tint[1]);
+ fb.color[o + 2] = Math.min(1, color[2] * lit * tint[2]);
+ }
+ }
+ }
+ }
+ return fb;
+}
diff --git a/packages/tty-3d/src/term.js b/packages/tty-3d/src/term.js
new file mode 100644
index 000000000..b12ca44c7
--- /dev/null
+++ b/packages/tty-3d/src/term.js
@@ -0,0 +1,152 @@
+// Framebuffer to terminal escape sequences.
+//
+// The trick that makes this look like graphics instead of ASCII art: the upper
+// half block, U+2580. One character cell carries a foreground colour and a
+// background colour, so writing it with fg = the top pixel and bg = the bottom
+// pixel gives two independently coloured pixels per cell. That doubles vertical
+// resolution and, more importantly, makes pixels square: terminal cells are
+// roughly 1:2, so a half-block grid has a 1:1 pixel aspect and a sphere comes
+// out round instead of squashed.
+
+const UPPER_HALF = '▀';
+const ESC = '\x1b';
+const RESET = `${ESC}[0m`;
+
+// Dense to sparse. Only used when the terminal cannot do colour at all, where
+// luminance has to carry the whole image on its own.
+const RAMP = '@%#*+=-:. ';
+
+export const ColorMode = {
+ TRUECOLOR: 'truecolor',
+ ANSI256: 'ansi256',
+ MONO: 'mono',
+};
+
+/**
+ * What the current terminal can actually render.
+ *
+ * Deliberately conservative: guessing truecolor wrong sprays literal escape
+ * garbage across the user's screen, while guessing 256 wrong just looks
+ * slightly flatter. NO_COLOR is honoured because it is a standard and ignoring
+ * it in a rendering tool would be obnoxious.
+ */
+export function detectColorMode(env = process.env, stream = process.stdout) {
+ if (env.NO_COLOR !== undefined && env.NO_COLOR !== '') return ColorMode.MONO;
+ if (env.THREE_TTY_COLOR && Object.values(ColorMode).includes(env.THREE_TTY_COLOR)) return env.THREE_TTY_COLOR;
+ if (env.TERM === 'dumb') return ColorMode.MONO;
+ const colorterm = (env.COLORTERM || '').toLowerCase();
+ if (colorterm === 'truecolor' || colorterm === '24bit') return ColorMode.TRUECOLOR;
+ if (/-truecolor|-direct/.test(env.TERM || '')) return ColorMode.TRUECOLOR;
+ // A modern terminal reporting 256 colours is very likely truecolor too, but
+ // "likely" is not good enough when being wrong is visible garbage.
+ if (/256(color)?/.test(env.TERM || '')) return ColorMode.ANSI256;
+ if (stream && stream.isTTY) return ColorMode.ANSI256;
+ return ColorMode.MONO;
+}
+
+const clamp255 = (v) => Math.max(0, Math.min(255, Math.round(v * 255)));
+
+/** Nearest xterm-256 index: the 6x6x6 colour cube, or the 24-step grey ramp. */
+export function toAnsi256(r, g, b) {
+ const R = clamp255(r), G = clamp255(g), B = clamp255(b);
+ if (Math.abs(R - G) < 8 && Math.abs(G - B) < 8) {
+ if (R < 8) return 16;
+ if (R > 248) return 231;
+ return 232 + Math.round(((R - 8) / 247) * 23);
+ }
+ const q = (v) => Math.round(v / 51);
+ return 16 + 36 * q(R) + 6 * q(G) + q(B);
+}
+
+function luminance(r, g, b) {
+ return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/**
+ * Render a framebuffer to a string of terminal rows.
+ *
+ * @param {object} fb framebuffer; height should be even
+ * @param {object} [opts]
+ * @param {string} [opts.mode] a ColorMode value
+ * @param {number[]} [opts.background] rgb 0..1 painted where nothing was drawn
+ * @param {boolean} [opts.transparent] leave uncovered cells as plain spaces
+ */
+export function framebufferToText(fb, opts = {}) {
+ const mode = opts.mode ?? ColorMode.TRUECOLOR;
+ const bg = opts.background ?? [0.031, 0.031, 0.078];
+ const transparent = opts.transparent ?? false;
+ const rows = [];
+
+ for (let y = 0; y < fb.height; y += 2) {
+ let line = '';
+ // Escape sequences are only emitted when the colour actually changes.
+ // A 120-wide frame is 240 colour writes if you are naive about it, and
+ // the redundant ones are pure bandwidth: over SSH or a curl stream that
+ // is the difference between smooth and stuttering.
+ let lastFg = null;
+ let lastBg = null;
+ // Whether this row ever set a colour. A fully transparent row must come
+ // out as plain spaces with no trailing reset, so that piping a
+ // --transparent render into a file produces text a human can read and
+ // diff rather than escape-sequence confetti.
+ let painted = false;
+
+ for (let x = 0; x < fb.width; x += 1) {
+ const topIdx = y * fb.width + x;
+ const botIdx = Math.min(fb.height - 1, y + 1) * fb.width + x;
+ const topOn = fb.coverage[topIdx] === 1;
+ const botOn = fb.coverage[botIdx] === 1;
+
+ if (transparent && !topOn && !botOn) {
+ if (lastFg !== null || lastBg !== null) { line += RESET; lastFg = null; lastBg = null; painted = true; }
+ line += ' ';
+ continue;
+ }
+
+ const tr = topOn ? fb.color[topIdx * 3] : bg[0];
+ const tg = topOn ? fb.color[topIdx * 3 + 1] : bg[1];
+ const tb = topOn ? fb.color[topIdx * 3 + 2] : bg[2];
+ const br = botOn ? fb.color[botIdx * 3] : bg[0];
+ const bgn = botOn ? fb.color[botIdx * 3 + 1] : bg[1];
+ const bb = botOn ? fb.color[botIdx * 3 + 2] : bg[2];
+
+ if (mode === ColorMode.MONO) {
+ const l = (luminance(tr, tg, tb) + luminance(br, bgn, bb)) / 2;
+ line += (topOn || botOn) ? RAMP[Math.min(RAMP.length - 1, Math.floor((1 - l) * RAMP.length))] : ' ';
+ continue;
+ }
+
+ let fgSeq;
+ let bgSeq;
+ if (mode === ColorMode.ANSI256) {
+ const f = toAnsi256(tr, tg, tb);
+ const b = toAnsi256(br, bgn, bb);
+ fgSeq = f === lastFg ? '' : `${ESC}[38;5;${f}m`;
+ bgSeq = b === lastBg ? '' : `${ESC}[48;5;${b}m`;
+ lastFg = f; lastBg = b;
+ } else {
+ const f = `${clamp255(tr)};${clamp255(tg)};${clamp255(tb)}`;
+ const b = `${clamp255(br)};${clamp255(bgn)};${clamp255(bb)}`;
+ fgSeq = f === lastFg ? '' : `${ESC}[38;2;${f}m`;
+ bgSeq = b === lastBg ? '' : `${ESC}[48;2;${b}m`;
+ lastFg = f; lastBg = b;
+ }
+ line += fgSeq + bgSeq + UPPER_HALF;
+ painted = true;
+ }
+
+ rows.push(mode === ColorMode.MONO || !painted ? line : line + RESET);
+ }
+ return rows.join('\n');
+}
+
+export const ansi = {
+ hideCursor: `${ESC}[?25l`,
+ showCursor: `${ESC}[?25h`,
+ clearScreen: `${ESC}[2J${ESC}[H`,
+ home: `${ESC}[H`,
+ // Move the cursor up n lines to overdraw the previous frame in place. This
+ // is what keeps an animation from scrolling the scrollback into oblivion,
+ // and unlike a full clear it does not flicker.
+ up: (n) => (n > 0 ? `${ESC}[${n}A` : ''),
+};
diff --git a/packages/tty-3d/tests/tty-3d.test.js b/packages/tty-3d/tests/tty-3d.test.js
new file mode 100644
index 000000000..ba1ef37c2
--- /dev/null
+++ b/packages/tty-3d/tests/tty-3d.test.js
@@ -0,0 +1,305 @@
+// Coverage for @three-ws/tty-3d, the terminal 3D renderer core.
+//
+// The fixtures are the two Khronos sample models this repo already ships:
+// cesium-man (one skinned mesh, one walk clip, a skeleton root carrying the
+// Collada Z-up to glTF Y-up rotation) and brainstem (many primitives, many
+// materials, deep node hierarchy). Between them they cover every path in the
+// loader that a real avatar exercises.
+//
+// Three of these tests exist because the bug they describe actually shipped
+// during development and was only caught by rendering a frame and looking at
+// it. They are here so it cannot come back silently.
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { resolve } from 'node:path';
+import {
+ loadModel,
+ createRenderer,
+ describeModel,
+ selectAnimation,
+ ColorMode,
+ detectColorMode,
+ toAnsi256,
+ ansi,
+} from '../src/index.js';
+import { poseModel, transformPrimitive, sampleChannel } from '../src/model.js';
+import { computeFraming, poseBounds } from '../src/raster.js';
+import { mat4Identity, mat4Multiply, mat4FromTRS, mat4Invert, slerp } from '../src/math.js';
+import { framebufferToText } from '../src/term.js';
+import { createFramebuffer } from '../src/raster.js';
+
+const root = resolve(import.meta.dirname, '../../..');
+const CESIUM = resolve(root, 'public/avatars/cesium-man.glb');
+const BRAINSTEM = resolve(root, 'public/avatars/brainstem.glb');
+
+let cesium;
+let brainstem;
+
+beforeAll(async () => {
+ cesium = await loadModel(CESIUM);
+ brainstem = await loadModel(BRAINSTEM);
+}, 60_000);
+
+describe('math', () => {
+ it('inverts a translate/rotate/scale matrix to within float precision', () => {
+ const m = mat4FromTRS([1, 2, 3], [0, 0.3826834, 0, 0.9238795], [2, 2, 2]);
+ const id = mat4Multiply(m, mat4Invert(m));
+ const identity = mat4Identity();
+ for (let i = 0; i < 16; i += 1) expect(id[i]).toBeCloseTo(identity[i], 12);
+ });
+
+ it('returns identity rather than NaN for a degenerate matrix', () => {
+ // Zero scale on an axis is legal glTF and appears on hidden helper nodes.
+ const flat = mat4FromTRS([0, 0, 0], [0, 0, 0, 1], [1, 0, 1]);
+ expect(Array.from(mat4Invert(flat))).toEqual(Array.from(mat4Identity()));
+ });
+
+ it('multiplies correctly when the output aliases an input', () => {
+ // REGRESSION: mat4Multiply(m, ibm, m) used to write into m while still
+ // reading m's earlier columns, producing a sheared joint matrix. On screen
+ // that was spikes radiating out of every joint.
+ const a = mat4FromTRS([1, 2, 3], [0, 0.3826834, 0, 0.9238795], [1.5, 1.5, 1.5]);
+ const b = mat4FromTRS([-2, 0.5, 4], [0.7071, 0, 0, 0.7071], [1, 2, 1]);
+ const expected = mat4Multiply(a, b);
+ const aliased = Float64Array.from(a);
+ mat4Multiply(aliased, b, aliased);
+ for (let i = 0; i < 16; i += 1) expect(aliased[i]).toBeCloseTo(expected[i], 12);
+ });
+
+ it('slerps along the shortest arc and stays normalized', () => {
+ const q = slerp([0, 0, 0, 1], [0, 0.7071068, 0, 0.7071068], 0.5);
+ expect(Math.hypot(q[0], q[1], q[2], q[3])).toBeCloseTo(1, 10);
+ expect(q[1]).toBeCloseTo(0.3826834, 5);
+ });
+});
+
+describe('loading', () => {
+ it('reads a skinned, animated model', () => {
+ const info = describeModel(cesium);
+ expect(info.skinned).toBe(true);
+ expect(info.triangles).toBeGreaterThan(1000);
+ expect(info.animations.length).toBeGreaterThan(0);
+ expect(info.animations[0].duration).toBeGreaterThan(0);
+ });
+
+ it('reads a multi-material model with a deep hierarchy', () => {
+ const info = describeModel(brainstem);
+ expect(info.primitives).toBeGreaterThan(1);
+ expect(info.nodes).toBeGreaterThan(10);
+ });
+
+ it('rejects a source that is neither a path, a URL, nor bytes', async () => {
+ await expect(loadModel(42)).rejects.toThrow(/path, a URL, or bytes/);
+ });
+});
+
+describe('animation sampling', () => {
+ it('clamps below the first and above the last key', () => {
+ const channel = {
+ path: 'translation',
+ interpolation: 'LINEAR',
+ times: new Float32Array([1, 2]),
+ values: new Float32Array([0, 0, 0, 10, 0, 0]),
+ };
+ expect(Array.from(sampleChannel(channel, -5, new Float64Array(3)))).toEqual([0, 0, 0]);
+ expect(Array.from(sampleChannel(channel, 99, new Float64Array(3)))).toEqual([10, 0, 0]);
+ expect(sampleChannel(channel, 1.5, new Float64Array(3))[0]).toBeCloseTo(5, 6);
+ });
+
+ it('holds the previous key for STEP interpolation', () => {
+ const channel = {
+ path: 'translation',
+ interpolation: 'STEP',
+ times: new Float32Array([0, 1]),
+ values: new Float32Array([0, 0, 0, 10, 0, 0]),
+ };
+ expect(sampleChannel(channel, 0.9, new Float64Array(3))[0]).toBe(0);
+ });
+
+ it('reads the value triple, not the tangents, for CUBICSPLINE', () => {
+ // CUBICSPLINE stores [inTangent, value, outTangent] per key. Reading it as
+ // if it were LINEAR picks up a tangent as a position and throws the limb
+ // across the screen.
+ const channel = {
+ path: 'translation',
+ interpolation: 'CUBICSPLINE',
+ times: new Float32Array([0, 1]),
+ values: new Float32Array([
+ 99, 99, 99, 0, 0, 0, 99, 99, 99,
+ 99, 99, 99, 10, 0, 0, 99, 99, 99,
+ ]),
+ };
+ expect(sampleChannel(channel, 0, new Float64Array(3))[0]).toBe(0);
+ expect(sampleChannel(channel, 1, new Float64Array(3))[0]).toBe(10);
+ });
+});
+
+describe('skinning', () => {
+ it('produces finite vertices for every frame of a real walk cycle', () => {
+ const clip = cesium.animations[0];
+ for (let i = 0; i < 8; i += 1) {
+ poseModel(cesium, clip, (clip.duration * i) / 8);
+ for (const prim of cesium.primitives) {
+ const out = transformPrimitive(cesium, prim).outPositions;
+ expect(out.every(Number.isFinite)).toBe(true);
+ }
+ }
+ });
+
+ it('keeps a humanoid upright and human-proportioned', () => {
+ // REGRESSION: applying inverse(meshNodeWorld) without re-applying
+ // meshNodeWorld cancelled the skeleton's Z-up correction and laid the
+ // character on its back. Height must dominate both horizontal extents.
+ poseModel(cesium, null, 0);
+ const b = poseBounds(cesium);
+ const height = b.max[1] - b.min[1];
+ expect(height).toBeGreaterThan(b.max[0] - b.min[0]);
+ expect(height).toBeGreaterThan(b.max[2] - b.min[2]);
+ });
+
+ it('does not shift joint indices when a joint cannot be resolved', () => {
+ // REGRESSION: filtering unresolvable joints out of the joint list renumbered
+ // every joint after the hole, rigging vertices to the wrong bones.
+ const skinned = cesium.primitives.find((p) => p.jointNodes);
+ expect(skinned).toBeDefined();
+ expect(skinned.jointNodes.length * 16).toBe(skinned.inverseBind.length);
+ expect(Math.max(...skinned.joints)).toBeLessThan(skinned.jointNodes.length);
+ });
+
+ it('caches the transform for a pose and recomputes after a new one', () => {
+ poseModel(cesium, null, 0);
+ const prim = cesium.primitives[0];
+ transformPrimitive(cesium, prim);
+ const stamp = prim.poseStamp;
+ transformPrimitive(cesium, prim);
+ expect(prim.poseStamp).toBe(stamp);
+ poseModel(cesium, cesium.animations[0], 0.5);
+ transformPrimitive(cesium, prim);
+ expect(prim.poseStamp).toBeGreaterThan(stamp);
+ });
+});
+
+describe('framing', () => {
+ it('is stable across an animation with root motion', () => {
+ // REGRESSION: unioning every frame's bounds turned a walk cycle into a
+ // corridor as long as the character walked, shrinking it to a speck.
+ const clip = cesium.animations[0];
+ const framing = computeFraming(cesium, clip);
+ poseModel(cesium, null, 0);
+ const rest = poseBounds(cesium);
+ const restHalfHeight = (rest.max[1] - rest.min[1]) / 2;
+ expect(framing.halfHeight).toBeGreaterThan(restHalfHeight * 0.8);
+ expect(framing.halfHeight).toBeLessThan(restHalfHeight * 2);
+ });
+});
+
+describe('rendering', () => {
+ it('draws the subject into a majority of the frame', () => {
+ const renderer = createRenderer(cesium, { width: 60, height: 28, mode: ColorMode.MONO, transparent: true });
+ const text = renderer.frame(0.6);
+ const lines = text.split('\n');
+ expect(lines.length).toBe(28);
+ const drawn = lines.filter((l) => l.trim().length > 0).length;
+ // A figure that fills under a third of the rows means the camera fit broke.
+ expect(drawn / lines.length).toBeGreaterThan(0.45);
+ });
+
+ it('produces a different frame as the animation advances', () => {
+ const renderer = createRenderer(cesium, { width: 48, height: 22, mode: ColorMode.MONO });
+ expect(renderer.frame(0)).not.toBe(renderer.frame(0.7));
+ });
+
+ it('is deterministic: the same time renders the same frame', () => {
+ const renderer = createRenderer(brainstem, { width: 40, height: 20, mode: ColorMode.MONO });
+ expect(renderer.frame(0.3)).toBe(renderer.frame(0.3));
+ });
+
+ it('renders a model with no animation at all', () => {
+ const renderer = createRenderer(cesium, { width: 40, height: 18, animation: false, mode: ColorMode.MONO });
+ expect(renderer.animation).toBeNull();
+ expect(renderer.frame(0).replace(/[\s\n]/g, '').length).toBeGreaterThan(0);
+ });
+
+ it('clamps the camera pitch so the model cannot flip over the pole', () => {
+ const renderer = createRenderer(cesium, { width: 30, height: 14, mode: ColorMode.MONO });
+ expect(renderer.setOrbit({ pitch: 99 }).pitch).toBeLessThan(1.6);
+ expect(renderer.setOrbit({ pitch: -99 }).pitch).toBeGreaterThan(-1.6);
+ expect(renderer.setOrbit({ zoom: 0 }).zoom).toBeGreaterThan(0);
+ });
+});
+
+describe('animation selection', () => {
+ it('matches a clip by name fragment, falls back, and honours false', () => {
+ const model = { animations: [{ name: 'idle' }, { name: 'walk-forward' }] };
+ expect(selectAnimation(model, 'walk').name).toBe('walk-forward');
+ expect(selectAnimation(model, 1).name).toBe('walk-forward');
+ expect(selectAnimation(model, 'nope').name).toBe('idle');
+ expect(selectAnimation(model, undefined).name).toBe('idle');
+ expect(selectAnimation(model, false)).toBeNull();
+ expect(selectAnimation({ animations: [] }, 'walk')).toBeNull();
+ });
+});
+
+describe('terminal output', () => {
+ it('emits one text row per two framebuffer rows', () => {
+ const fb = createFramebuffer(8, 8);
+ expect(framebufferToText(fb, { mode: ColorMode.MONO }).split('\n').length).toBe(4);
+ });
+
+ it('leaves uncovered cells blank in transparent mode', () => {
+ const fb = createFramebuffer(6, 4);
+ const text = framebufferToText(fb, { mode: ColorMode.TRUECOLOR, transparent: true });
+ expect(text.replace(/\n/g, '')).toBe(' '.repeat(12));
+ });
+
+ it('paints the background where nothing was drawn when not transparent', () => {
+ const fb = createFramebuffer(4, 4);
+ expect(framebufferToText(fb, { mode: ColorMode.TRUECOLOR })).toContain('48;2;');
+ });
+
+ it('does not repeat an escape sequence for an unchanged colour', () => {
+ const fb = createFramebuffer(20, 2);
+ const row = framebufferToText(fb, { mode: ColorMode.TRUECOLOR });
+ // Twenty identical cells, so exactly one foreground and one background set.
+ expect(row.match(/38;2;/g)?.length).toBe(1);
+ expect(row.match(/48;2;/g)?.length).toBe(1);
+ });
+
+ it('maps greys to the xterm grey ramp and colours to the cube', () => {
+ expect(toAnsi256(0, 0, 0)).toBe(16);
+ expect(toAnsi256(1, 1, 1)).toBe(231);
+ expect(toAnsi256(0.5, 0.5, 0.5)).toBeGreaterThanOrEqual(232);
+ expect(toAnsi256(1, 0, 0)).toBe(196);
+ });
+
+ it('moves the cursor up only for a positive count', () => {
+ expect(ansi.up(0)).toBe('');
+ expect(ansi.up(3)).toContain('3A');
+ });
+});
+
+describe('colour detection', () => {
+ const stream = { isTTY: true };
+
+ it('honours NO_COLOR above everything else', () => {
+ expect(detectColorMode({ NO_COLOR: '1', COLORTERM: 'truecolor' }, stream)).toBe(ColorMode.MONO);
+ });
+
+ it('reads COLORTERM for truecolor', () => {
+ expect(detectColorMode({ COLORTERM: 'truecolor' }, stream)).toBe(ColorMode.TRUECOLOR);
+ expect(detectColorMode({ COLORTERM: '24bit' }, stream)).toBe(ColorMode.TRUECOLOR);
+ });
+
+ it('falls back to 256 colour for a plain 256-colour TERM', () => {
+ expect(detectColorMode({ TERM: 'xterm-256color' }, stream)).toBe(ColorMode.ANSI256);
+ });
+
+ it('is monochrome for a dumb terminal or a pipe', () => {
+ expect(detectColorMode({ TERM: 'dumb' }, stream)).toBe(ColorMode.MONO);
+ expect(detectColorMode({}, { isTTY: false })).toBe(ColorMode.MONO);
+ });
+
+ it('lets the caller force a mode', () => {
+ expect(detectColorMode({ THREE_TTY_COLOR: 'mono', COLORTERM: 'truecolor' }, stream)).toBe(ColorMode.MONO);
+ });
+});
diff --git a/packages/tty-avatar/LICENSE b/packages/tty-avatar/LICENSE
new file mode 100644
index 000000000..dff21b7f4
--- /dev/null
+++ b/packages/tty-avatar/LICENSE
@@ -0,0 +1,20 @@
+Copyright 2026 nirholas
+
+All rights reserved.
+
+This software is proprietary and may not be used, copied, modified, distributed,
+translated, or made available to any third party without the express written
+permission of the copyright owner.
+
+No rights are granted by implication, estoppel, or otherwise. Use of this
+software is subject to the terms of a separate license agreement with the
+copyright owner.
+
+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 COPYRIGHT OWNER 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.
diff --git a/packages/tty-avatar/README.md b/packages/tty-avatar/README.md
new file mode 100644
index 000000000..d76907b1d
--- /dev/null
+++ b/packages/tty-avatar/README.md
@@ -0,0 +1,176 @@
+# @three-ws/tty-avatar
+
+**A live 3D avatar in your terminal.** Any GLB, or any three.ws avatar or agent by id, rendered by a software rasterizer to truecolor half-blocks or braille, animated with moods, and wired to Claude Code hooks so your coding agent has a face that thinks while it reads, works while it edits, and celebrates when it stops.
+
+```
+npx @three-ws/tty-avatar 81a076b6-55ff-49a2-b007-1d88e7dce2aa
+```
+
+No GPU, no browser, no account. Node 18+ and a terminal that can show colour.
+
+```
+ ahd0w
+ bp00
+ h0mYow#
+ hJQpbh**d
+ oo####*ahdod
+ hhohaadwCkaw
+ #abQhaoZZao*om
+ *dwOo*bqO*#wUu
+ #*qk**aU0#*qJ
+ MqUo**hQw*#OL
+ Mp o*omh##mqL
+ #w o*ooo**hba0
+ L# hhkqcZpZpO
+ bqmU ZpbdC
+ qmU pdbC
+ qqU qbQ
+ bU0 LO0
+```
+
+That is the `ascii` mode of a real three.ws agent body (`tty-avatar snapshot agent:bd1b56b0-5494-47e2-ad78-04ef4c43ae5b --mode ascii`), which is what you get when stdout is not a TTY. In a terminal you get colour and 24 frames a second.
+
+## Install
+
+```sh
+npm i -g @three-ws/tty-avatar # or: npx @three-ws/tty-avatar …
+```
+
+## Run
+
+```sh
+tty-avatar ./hero.glb # a local model
+tty-avatar https://example.com/robot.glb # a URL
+tty-avatar 81a076b6-55ff-49a2-b007-1d88e7dce2aa # a three.ws avatar id
+tty-avatar agent:bd1b56b0-5494-47e2-ad78-04ef4c43ae5b # a three.ws agent (its 3D body)
+tty-avatar https://three.ws/avatars/81a076b6-55ff-49a2-b007-1d88e7dce2aa # a page URL
+```
+
+Options:
+
+| Flag | Meaning |
+|---|---|
+| `--mode blocks\|braille\|ascii` | Glyph set. `blocks` (default on a TTY) is 1x2 truecolor half-blocks. `braille` is 2x4 dots per cell, four times the vertical detail. `ascii` is a luminance ramp with no escapes, the default when piped. |
+| `--mood <name>` | Starting mood (`tty-avatar moods` lists them). |
+| `--fps <n>` | Frame rate, default 24. |
+| `--columns <n> --rows <n>` | Override the terminal size. |
+| `--yaw <deg> --pitch <deg>` | Base rotation added to the mood's motion. |
+| `--zoom <x>` | 1 fits the whole model; 1.4 fills the frame with the upper body. |
+| `--frames <n>` | Exit after n frames (recording, CI). |
+| `--no-caption` | Hide the name and mood line. |
+| `--no-alt` | Draw inline instead of on the alternate screen. |
+| `--max-triangles <n>` | Decimate by stride above this many triangles (default 240000). A 20k-triangle avatar renders in under 5 ms per frame at 160x96 subpixels. |
+| `--origin <url>` | three.ws origin for id lookups. |
+| `--state-dir <dir>` | Where mood and hook files live (default `~/.three-ws/tty-avatar`, or `$TTY_AVATAR_DIR`). |
+| `--no-state` | Ignore the state directory. |
+
+## Moods
+
+A mood is procedural whole-body motion: no rig needed, so it works on any GLB, a prop included.
+
+| Mood | Reads as |
+|---|---|
+| `idle` | slow sway, breathing |
+| `spin` | turntable |
+| `think` | tilted, looking up, slow sway |
+| `work` | small quick nods, like typing |
+| `talk` | bobbing on a speech rhythm |
+| `happy` | bouncing |
+| `attention` | pulsing, asking for you |
+| `error` | a fast shake |
+| `sleep` | head down, slow breathing |
+
+Change the mood of a running viewer from any other shell:
+
+```sh
+tty-avatar mood happy --say "deploy landed" --ttl 5000 # back to idle after 5 s
+tty-avatar say "running the migration"
+```
+
+## Give your coding agent a face
+
+Claude Code emits a hook event for every prompt, tool call, notification and stop. Wire them to the viewer once:
+
+```sh
+tty-avatar install-hooks --write # merges into ~/.claude/settings.json
+```
+
+Then run a viewer in a split pane (`tty-avatar <avatar id>`) and start Claude Code in another. The avatar now:
+
+| Claude Code event | Mood | Caption |
+|---|---|---|
+| `SessionStart` | happy | session started |
+| `UserPromptSubmit` | think | reading your prompt |
+| `PreToolUse` | work | `editing index.js`, `$ npm test`, `searching`, `browsing`, `delegating` |
+| `PostToolUse` | think, or error when the tool reported failure | `Bash done` |
+| `Notification` | attention (30 s) | the notification text |
+| `Stop` / `SubagentStop` | happy (4 s) | done |
+| `PreCompact` | think | compacting memory |
+| `SessionEnd` | sleep | session ended |
+
+The installed hook command is `mkdir -p … && cat > ~/.three-ws/tty-avatar/event.json`. It is not a Node process, so it adds nothing measurable to a tool call; the viewer polls the file and does the mapping. `tty-avatar install-hooks` without `--write` prints the JSON fragment instead, and `--json` prints just the `hooks` object for another tool to merge.
+
+Any other runtime can drive it the same way: write a Claude-Code-shaped payload to `event.json`, or call `tty-avatar mood` / `tty-avatar say` from a script.
+
+## Snapshot
+
+```sh
+tty-avatar snapshot ./hero.glb --mode braille --columns 80 --rows 40 --yaw 30
+tty-avatar snapshot 81a076b6-55ff-49a2-b007-1d88e7dce2aa --plain > avatar.txt
+```
+
+One frame, then exit. `--mood` and `--yaw`/`--pitch` pose it.
+
+## Library
+
+```js
+import { resolveSource, parseGlb, TtyAvatar, snapshot } from '@three-ws/tty-avatar';
+
+const { bytes, name } = await resolveSource('81a076b6-55ff-49a2-b007-1d88e7dce2aa');
+const mesh = await parseGlb(bytes);
+
+// A viewer that owns the terminal until stop():
+const viewer = new TtyAvatar(mesh, { name, mode: 'blocks', fps: 24 });
+viewer.on('mood', ({ mood, say }) => console.error(mood, say));
+setTimeout(() => viewer.setMood('happy', { say: 'tests green', ttlMs: 3000 }), 2000);
+await viewer.start();
+
+// Or one frame as a string, no terminal involved:
+console.log(snapshot(mesh, { mode: 'ascii', columns: 60, rows: 30, yaw: 0.5 }));
+```
+
+Exports:
+
+| Export | What |
+|---|---|
+| `resolveSource(input, { origin })` | file path, URL, avatar id, `agent:<id>`, or three.ws page URL → `{ bytes, name, source, url, page }` |
+| `parseGlb(bytes, { maxTriangles })`, `loadGlbFile(path)` | GLB → `{ positions, normals, tints, count, bounds }` (unit sphere, Y-up, node transforms baked, meshopt and Draco decoded) |
+| `createFrame(w, h)`, `render(mesh, frame, pose, camera)` | the rasterizer: z-buffered scanline fill, back-face culling, key + fill + rim lighting |
+| `encode(frame, { mode })`, `encodeBlocks`, `encodeBraille`, `encodeAscii`, `stripAnsi`, `MODES` | frame → lines |
+| `MOODS`, `MOOD_NAMES`, `isMood`, `poseAt(current, previous, now)` | motion functions and the cross-fade between them |
+| `TtyAvatar` | the frame loop: `start({ frames })`, `stop()`, `setMood(name, { say, ttlMs })`, `setCaption(text)`, `renderLines()`, events `frame`, `mood`, `stop` |
+| `snapshot(mesh, opts)` | one frame as a string |
+| `writeState`, `writeEvent`, `pollState`, `moodForHookEvent`, `defaultStateDir`, `statePaths` | the file bridge |
+| `claudeHooksConfig(dir)`, `installClaudeHooks({ settingsPath, dir })`, `hookCommand(dir)` | Claude Code wiring |
+
+## How it draws
+
+The terminal is the framebuffer. Each character cell is split into subpixels (1x2 for half-blocks, 2x4 for braille), the mesh is projected with a perspective camera onto that grid, and a z-buffered scanline fill writes one lit colour per subpixel. Shading is per face: a key light, a fill light, an ambient floor, and a rim term so silhouettes stay readable on dark and light backgrounds. Colour comes from each primitive's material `baseColorFactor` (and `COLOR_0` when present); textures are not sampled, because a cell is far coarser than a texel and a flat tint under lighting reads better at 80 columns.
+
+Half-block mode packs two colours into one cell (foreground on `▀`, background behind it), so a 100x40 terminal is a 100x80 colour image. Braille mode packs eight coverage bits per cell with one colour, so the same terminal is a 200x160 monochrome-per-cell image.
+
+## Tests
+
+```sh
+npm test
+```
+
+Builds a real GLB in memory with `@gltf-transform/core`, runs it through the loader, rasterizer, every encoder, the mood blender, the state bridge, the hook installer, and the CLI end to end.
+
+## Links
+
+- Docs: https://three.ws/docs/tty-avatar
+- Pick an avatar: https://three.ws/gallery (every avatar page's Embed tab has the `npx` line)
+- Source: https://github.com/nirholas/three.ws/tree/main/packages/tty-avatar
+
+Apache-2.0.
diff --git a/packages/tty-avatar/bin/tty-avatar.js b/packages/tty-avatar/bin/tty-avatar.js
new file mode 100755
index 000000000..64323a8f1
--- /dev/null
+++ b/packages/tty-avatar/bin/tty-avatar.js
@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// tty-avatar: a live 3D avatar in your terminal.
+//
+// tty-avatar <source> run the viewer (file, URL, or three.ws id)
+// tty-avatar snapshot <source> print one frame and exit
+// tty-avatar mood <name> [--say ..] change the mood of the running viewer
+// tty-avatar say <text> set the caption of the running viewer
+// tty-avatar hook stdin (a hook payload) → event file
+// tty-avatar install-hooks wire Claude Code hooks to the viewer
+// tty-avatar moods list moods
+
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { parseArgs } from 'node:util';
+import { parseGlb } from '../src/load.js';
+import { resolveSource } from '../src/resolve.js';
+import { TtyAvatar } from '../src/terminal.js';
+import { MOODS, MOOD_NAMES, isMood } from '../src/moods.js';
+import { defaultStateDir, writeEvent, writeState } from '../src/state.js';
+import { claudeHooksConfig, installClaudeHooks } from '../src/hooks.js';
+import { snapshot } from '../src/snapshot.js';
+
+const { version } = createRequire(import.meta.url)('../package.json');
+
+const HELP = `tty-avatar ${version}: a live 3D avatar in your terminal.
+
+Usage
+ tty-avatar <source> [options] run the viewer
+ tty-avatar snapshot <source> [opts] print one frame and exit
+ tty-avatar mood <name> [--say text] set the running viewer's mood
+ tty-avatar say <text> set the running viewer's caption
+ tty-avatar hook pipe a hook payload (stdin) to the viewer
+ tty-avatar install-hooks [--write] Claude Code hooks → this viewer
+ tty-avatar moods list the moods
+
+Sources
+ ./model.glb a local GLB
+ https://…/model.glb a GLB URL
+ 81a076b6-55ff-49a2-b007-… a three.ws avatar id
+ agent:bd1b56b0-5494-47e2-… a three.ws agent id (its 3D body)
+ https://three.ws/avatars/<id> a three.ws page URL
+
+Options
+ --mode blocks|braille|ascii glyphs (default blocks; ascii when not a TTY)
+ --mood <name> starting mood (default idle)
+ --fps <n> frame rate (default 24)
+ --columns <n> --rows <n> override the terminal size
+ --yaw <deg> --pitch <deg> base rotation
+ --zoom <x> 1 fits the model; 1.4 fills a face
+ --frames <n> exit after n frames (recording, CI)
+ --no-caption hide the name/mood line
+ --no-alt draw inline instead of on the alternate screen
+ --max-triangles <n> decimate above this many triangles (240000)
+ --origin <url> three.ws origin (default https://three.ws)
+ --state-dir <dir> where mood/hook files live (~/.three-ws/tty-avatar)
+ --no-state ignore the state directory
+ --say <text> caption (with mood, or as the initial caption)
+ --ttl <ms> with mood: return to idle after this long
+ --plain snapshot: strip colour
+ --json install-hooks: print the settings fragment
+`;
+
+const options = {
+ mode: { type: 'string' },
+ mood: { type: 'string' },
+ fps: { type: 'string' },
+ columns: { type: 'string' },
+ rows: { type: 'string' },
+ yaw: { type: 'string' },
+ pitch: { type: 'string' },
+ zoom: { type: 'string' },
+ frames: { type: 'string' },
+ caption: { type: 'boolean', default: true },
+ alt: { type: 'boolean', default: true },
+ 'max-triangles': { type: 'string' },
+ origin: { type: 'string' },
+ 'state-dir': { type: 'string' },
+ state: { type: 'boolean', default: true },
+ say: { type: 'string' },
+ ttl: { type: 'string' },
+ plain: { type: 'boolean', default: false },
+ json: { type: 'boolean', default: false },
+ write: { type: 'boolean', default: false },
+ settings: { type: 'string' },
+ help: { type: 'boolean', short: 'h', default: false },
+ version: { type: 'boolean', short: 'v', default: false },
+};
+
+let parsed;
+try {
+ parsed = parseArgs({ args: process.argv.slice(2), options, allowPositionals: true, allowNegative: true });
+} catch (err) {
+ fail(err.message);
+}
+const { values: flags, positionals } = parsed;
+
+if (flags.version) { console.log(version); process.exit(0); }
+if (flags.help || positionals.length === 0) { process.stdout.write(HELP); process.exit(flags.help ? 0 : 1); }
+
+const num = (key, def) => (flags[key] === undefined ? def : Number(flags[key]));
+const deg = (key) => (num(key, 0) * Math.PI) / 180;
+const stateDir = flags.state ? (flags['state-dir'] || defaultStateDir()) : null;
+
+const [command, ...rest] = positionals;
+try {
+ switch (command) {
+ case 'moods':
+ for (const name of MOOD_NAMES) console.log(`${name.padEnd(10)} ${MOODS[name].label}`);
+ break;
+ case 'mood': {
+ const name = rest[0];
+ if (!isMood(name)) fail(`unknown mood "${name || ''}"; one of ${MOOD_NAMES.join(', ')}`);
+ const st = await writeState({ mood: name, say: flags.say, ttlMs: num('ttl', 0) || undefined }, stateDir || defaultStateDir());
+ console.log(`${st.mood}${st.say ? ` · ${st.say}` : ''}`);
+ break;
+ }
+ case 'say': {
+ const text = rest.join(' ');
+ if (!text) fail('say what? pass the caption text');
+ await writeState({ say: text }, stateDir || defaultStateDir());
+ console.log(text);
+ break;
+ }
+ case 'hook': {
+ const raw = readFileSync(0, 'utf8');
+ await writeEvent(raw, stateDir || defaultStateDir());
+ break;
+ }
+ case 'install-hooks': {
+ if (flags.json) {
+ console.log(JSON.stringify(claudeHooksConfig(stateDir || defaultStateDir()), null, 2));
+ break;
+ }
+ if (!flags.write) {
+ const cfg = claudeHooksConfig(stateDir || defaultStateDir());
+ process.stdout.write(`Add this to ~/.claude/settings.json (or run again with --write):\n\n${JSON.stringify(cfg, null, 2)}\n`);
+ break;
+ }
+ const { settingsPath, added } = await installClaudeHooks({ settingsPath: flags.settings, dir: stateDir || defaultStateDir() });
+ console.log(`wired ${added.length} Claude Code hooks in ${settingsPath}`);
+ console.log('start a viewer in another pane: tty-avatar <avatar id>');
+ break;
+ }
+ case 'snapshot': {
+ const mesh = await loadMesh(rest[0]);
+ let text = snapshot(mesh.mesh, {
+ mode: flags.mode || (process.stdout.isTTY ? 'blocks' : 'ascii'),
+ columns: num('columns', Math.min(process.stdout.columns || 80, 100)),
+ rows: num('rows', Math.min((process.stdout.rows || 30) - 1, 45)),
+ yaw: deg('yaw'),
+ pitch: deg('pitch'),
+ zoom: num('zoom', 1),
+ mood: flags.mood,
+ });
+ if (flags.plain) text = text.replace(/\x1b\[[0-9;]*m/g, '');
+ process.stdout.write(`${text}\n`);
+ break;
+ }
+ default: {
+ const { mesh, name } = await loadMesh(command);
+ const viewer = new TtyAvatar(mesh, {
+ name,
+ mode: flags.mode || (process.stdout.isTTY ? 'blocks' : 'ascii'),
+ mood: flags.mood,
+ fps: num('fps', 24),
+ columns: num('columns', 0) || undefined,
+ rows: num('rows', 0) || undefined,
+ yaw: deg('yaw'),
+ zoom: num('zoom', 1),
+ altScreen: flags.alt && process.stdout.isTTY,
+ caption: flags.caption,
+ stateDir,
+ });
+ if (flags.say) viewer.setCaption(flags.say);
+ await viewer.start({ frames: num('frames', 0) || Infinity });
+ }
+ }
+} catch (err) {
+ fail(err.message);
+}
+
+async function loadMesh(source) {
+ if (!source) fail('missing source (a .glb path, a URL, or a three.ws avatar/agent id)');
+ const resolved = await resolveSource(source, { origin: flags.origin });
+ const mesh = await parseGlb(resolved.bytes, { maxTriangles: num('max-triangles', 240_000) });
+ if (mesh.count === 0) fail(`${resolved.name} has no triangles to draw`);
+ return { mesh, name: resolved.name };
+}
+
+function fail(msg) {
+ process.stderr.write(`tty-avatar: ${msg}\n`);
+ process.exit(1);
+}
diff --git a/packages/tty-avatar/package.json b/packages/tty-avatar/package.json
new file mode 100644
index 000000000..263f15445
--- /dev/null
+++ b/packages/tty-avatar/package.json
@@ -0,0 +1,54 @@
+{
+ "name": "@three-ws/tty-avatar",
+ "version": "0.1.0",
+ "description": "A live 3D avatar in your terminal. Renders any GLB (or any three.ws avatar by id) with a software rasterizer to truecolor half-blocks or braille, animates it with moods, and reacts in real time to Claude Code hooks so your coding agent has a face.",
+ "keywords": [
+ "three.ws",
+ "terminal",
+ "tty",
+ "ansi",
+ "braille",
+ "3d",
+ "glb",
+ "gltf",
+ "avatar",
+ "software-rasterizer",
+ "claude-code",
+ "agent",
+ "cli"
+ ],
+ "author": "three.ws <[email protected]> (https://three.ws)",
+ "license": "Apache-2.0",
+ "homepage": "https://three.ws/docs/tty-avatar",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/nirholas/three.ws.git",
+ "directory": "packages/tty-avatar"
+ },
+ "type": "module",
+ "bin": {
+ "tty-avatar": "./bin/tty-avatar.js"
+ },
+ "main": "./src/index.js",
+ "exports": {
+ ".": "./src/index.js",
+ "./package.json": "./package.json"
+ },
+ "files": [
+ "bin",
+ "src",
+ "README.md",
+ "LICENSE"
+ ],
+ "engines": {
+ "node": ">=18"
+ },
+ "scripts": {
+ "test": "node --test test/*.test.js"
+ },
+ "dependencies": {
+ "@gltf-transform/core": "^4.4.0",
+ "@gltf-transform/extensions": "^4.4.0",
+ "meshoptimizer": "^1.1.1"
+ }
+}
diff --git a/packages/tty-avatar/src/encode.js b/packages/tty-avatar/src/encode.js
new file mode 100644
index 000000000..86b0ab84b
--- /dev/null
+++ b/packages/tty-avatar/src/encode.js
@@ -0,0 +1,142 @@
+// Frame → lines of text. Three encoders share one contract: given a Frame
+// whose subpixel grid matches their cell geometry, return an array of strings
+// (one per terminal row) with ANSI colour where the mode supports it.
+//
+// blocks 1x2 subpixels per cell, truecolor foreground/background on the
+// upper-half-block glyph. Best-looking on any modern terminal.
+// braille 2x4 subpixels per cell, one truecolor foreground per cell. Four
+// times the vertical resolution, monochrome within a cell. Reads
+// like an engraving.
+// ascii 1x2 subpixels per cell, no colour: a luminance ramp. For logs,
+// CI output, and terminals that cannot do colour.
+
+const RESET = '\x1b[0m';
+const RAMP = ' .\'`^",:;Il!i~+_-?][}{1)(|\\/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$';
+
+/** Cell geometry for each mode: subpixels per character cell. */
+export const MODES = {
+ blocks: { sx: 1, sy: 2 },
+ braille: { sx: 2, sy: 4 },
+ ascii: { sx: 1, sy: 2 },
+};
+
+/** Gamma-encode a linear channel to an 8-bit sRGB value. */
+function to8(c) {
+ const s = c <= 0.0031308 ? c * 12.92 : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+ return Math.max(0, Math.min(255, Math.round(s * 255)));
+}
+
+function fg(r, g, b) { return `\x1b[38;2;${r};${g};${b}m`; }
+function bg(r, g, b) { return `\x1b[48;2;${r};${g};${b}m`; }
+
+/**
+ * @param {import('./raster.js').Frame} frame
+ * @param {{ mode?: 'blocks'|'braille'|'ascii' }} [opts]
+ * @returns {string[]}
+ */
+export function encode(frame, { mode = 'blocks' } = {}) {
+ if (mode === 'braille') return encodeBraille(frame);
+ if (mode === 'ascii') return encodeAscii(frame);
+ return encodeBlocks(frame);
+}
+
+export function encodeBlocks(frame) {
+ const { width: W, height: H, hit, rgb } = frame;
+ const rows = Math.floor(H / 2);
+ const lines = new Array(rows);
+ for (let row = 0; row < rows; row++) {
+ let line = '';
+ let lastFg = '', lastBg = '';
+ for (let x = 0; x < W; x++) {
+ const ti = row * 2 * W + x, bi = (row * 2 + 1) * W + x;
+ const top = hit[ti], bot = hit[bi];
+ if (!top && !bot) {
+ if (lastFg || lastBg) { line += RESET; lastFg = ''; lastBg = ''; }
+ line += ' ';
+ continue;
+ }
+ let glyph, f, b = '';
+ if (top && bot) {
+ glyph = '▀';
+ f = fg(to8(rgb[ti * 3]), to8(rgb[ti * 3 + 1]), to8(rgb[ti * 3 + 2]));
+ b = bg(to8(rgb[bi * 3]), to8(rgb[bi * 3 + 1]), to8(rgb[bi * 3 + 2]));
+ } else if (top) {
+ glyph = '▀';
+ f = fg(to8(rgb[ti * 3]), to8(rgb[ti * 3 + 1]), to8(rgb[ti * 3 + 2]));
+ } else {
+ glyph = '▄';
+ f = fg(to8(rgb[bi * 3]), to8(rgb[bi * 3 + 1]), to8(rgb[bi * 3 + 2]));
+ }
+ if (!b && lastBg) { line += RESET; lastFg = ''; lastBg = ''; }
+ if (f !== lastFg) { line += f; lastFg = f; }
+ if (b && b !== lastBg) { line += b; lastBg = b; }
+ line += glyph;
+ }
+ if (lastFg || lastBg) line += RESET;
+ lines[row] = line;
+ }
+ return lines;
+}
+
+// Unicode braille: dot bit for subpixel (dx, dy) within a 2x4 cell.
+const DOT = [[0x01, 0x02, 0x04, 0x40], [0x08, 0x10, 0x20, 0x80]];
+
+export function encodeBraille(frame) {
+ const { width: W, height: H, hit, rgb } = frame;
+ const cols = Math.floor(W / 2), rows = Math.floor(H / 4);
+ const lines = new Array(rows);
+ for (let row = 0; row < rows; row++) {
+ let line = '';
+ let lastFg = '';
+ for (let col = 0; col < cols; col++) {
+ let bits = 0, n = 0, r = 0, g = 0, b = 0;
+ for (let dx = 0; dx < 2; dx++) {
+ for (let dy = 0; dy < 4; dy++) {
+ const i = (row * 4 + dy) * W + col * 2 + dx;
+ if (!hit[i]) continue;
+ bits |= DOT[dx][dy];
+ n++;
+ r += rgb[i * 3]; g += rgb[i * 3 + 1]; b += rgb[i * 3 + 2];
+ }
+ }
+ if (!bits) {
+ if (lastFg) { line += RESET; lastFg = ''; }
+ line += ' ';
+ continue;
+ }
+ const f = fg(to8(r / n), to8(g / n), to8(b / n));
+ if (f !== lastFg) { line += f; lastFg = f; }
+ line += String.fromCharCode(0x2800 + bits);
+ }
+ if (lastFg) line += RESET;
+ lines[row] = line;
+ }
+ return lines;
+}
+
+export function encodeAscii(frame) {
+ const { width: W, height: H, hit, rgb } = frame;
+ const rows = Math.floor(H / 2);
+ const lines = new Array(rows);
+ for (let row = 0; row < rows; row++) {
+ let line = '';
+ for (let x = 0; x < W; x++) {
+ const ti = row * 2 * W + x, bi = (row * 2 + 1) * W + x;
+ const n = hit[ti] + hit[bi];
+ if (!n) { line += ' '; continue; }
+ let lum = 0;
+ if (hit[ti]) lum += 0.2126 * rgb[ti * 3] + 0.7152 * rgb[ti * 3 + 1] + 0.0722 * rgb[ti * 3 + 2];
+ if (hit[bi]) lum += 0.2126 * rgb[bi * 3] + 0.7152 * rgb[bi * 3 + 1] + 0.0722 * rgb[bi * 3 + 2];
+ lum /= n;
+ const idx = Math.min(RAMP.length - 1, 1 + Math.floor(Math.sqrt(lum) * (RAMP.length - 2)));
+ line += RAMP[idx];
+ }
+ lines[row] = line.replace(/\s+$/, '');
+ }
+ return lines;
+}
+
+/** Strip ANSI escapes; used by tests and by `--plain` captures. */
+export function stripAnsi(s) {
+ return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
diff --git a/packages/tty-avatar/src/hooks.js b/packages/tty-avatar/src/hooks.js
new file mode 100644
index 000000000..7252f53b7
--- /dev/null
+++ b/packages/tty-avatar/src/hooks.js
@@ -0,0 +1,83 @@
+// Claude Code integration: hook config that pipes every hook payload into the
+// viewer's event file. The installed command is `cat`, not Node, so it adds
+// nothing measurable to a tool call. The viewer maps payload → mood itself
+// (see moodForHookEvent in state.js).
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { defaultStateDir, statePaths } from './state.js';
+
+export const HOOK_EVENTS = [
+ 'SessionStart',
+ 'UserPromptSubmit',
+ 'PreToolUse',
+ 'PostToolUse',
+ 'Notification',
+ 'Stop',
+ 'SubagentStop',
+ 'PreCompact',
+ 'SessionEnd',
+];
+
+const MARKER = 'three-ws-tty-avatar';
+
+/**
+ * The shell command a hook runs. POSIX: mkdir + cat. Anything else: the CLI's
+ * own `hook` subcommand, which does the same thing in Node.
+ * @param {string} [dir]
+ */
+export function hookCommand(dir = defaultStateDir()) {
+ const { event } = statePaths(dir);
+ if (process.platform === 'win32') return `npx --yes @three-ws/tty-avatar hook`;
+ const q = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+ // The marker is a comment so `installClaudeHooks` can recognise its own entries later.
+ return `mkdir -p ${q(dirname(event))} && cat > ${q(event)} # ${MARKER}`;
+}
+
+/**
+ * The `hooks` object to merge into a Claude Code settings.json.
+ * @param {string} [dir]
+ */
+export function claudeHooksConfig(dir = defaultStateDir()) {
+ const command = hookCommand(dir);
+ const hooks = {};
+ for (const ev of HOOK_EVENTS) {
+ hooks[ev] = [{ matcher: '', hooks: [{ type: 'command', command }] }];
+ }
+ return { hooks };
+}
+
+/**
+ * Merge the hook config into a settings file (default ~/.claude/settings.json),
+ * replacing any earlier tty-avatar entries and leaving every other hook alone.
+ *
+ * @param {{ settingsPath?: string, dir?: string }} [opts]
+ * @returns {Promise<{ settingsPath: string, added: string[] }>}
+ */
+export async function installClaudeHooks({ settingsPath, dir } = {}) {
+ const path = settingsPath || join(homedir(), '.claude', 'settings.json');
+ let settings = {};
+ try {
+ settings = JSON.parse(await readFile(path, 'utf8'));
+ } catch (err) {
+ if (err.code !== 'ENOENT') throw new Error(`cannot parse ${path}: ${err.message}`);
+ }
+ const mine = claudeHooksConfig(dir).hooks;
+ settings.hooks = settings.hooks && typeof settings.hooks === 'object' ? settings.hooks : {};
+ const added = [];
+ for (const ev of HOOK_EVENTS) {
+ const existing = Array.isArray(settings.hooks[ev]) ? settings.hooks[ev] : [];
+ const kept = existing.filter((group) => !isMine(group));
+ settings.hooks[ev] = [...kept, ...mine[ev]];
+ added.push(ev);
+ }
+ await mkdir(dirname(path), { recursive: true });
+ await writeFile(path, `${JSON.stringify(settings, null, 2)}\n`);
+ return { settingsPath: path, added };
+}
+
+function isMine(group) {
+ const list = Array.isArray(group?.hooks) ? group.hooks : [];
+ return list.some((h) => typeof h?.command === 'string' && (h.command.includes(MARKER) || h.command.includes('@three-ws/tty-avatar hook')));
+}
diff --git a/packages/tty-avatar/src/index.js b/packages/tty-avatar/src/index.js
new file mode 100644
index 000000000..0e5d90d3e
--- /dev/null
+++ b/packages/tty-avatar/src/index.js
@@ -0,0 +1,24 @@
+// @three-ws/tty-avatar: a live 3D avatar in the terminal.
+//
+// The typical path is resolveSource (id, URL or file to bytes), parseGlb
+// (bytes to a render-ready mesh), then either a TtyAvatar viewer that owns the
+// terminal or snapshot() for one frame as a string. The README shows both.
+// Lower-level pieces are exported too, so a custom encoder or a headless
+// render in a test never needs the viewer.
+
+export { parseGlb, loadGlbFile, finishMesh } from './load.js';
+export { createFrame, render } from './raster.js';
+export { encode, encodeBlocks, encodeBraille, encodeAscii, stripAnsi, MODES } from './encode.js';
+export { MOODS, MOOD_NAMES, isMood, poseAt } from './moods.js';
+export { TtyAvatar } from './terminal.js';
+export { resolveSource } from './resolve.js';
+export {
+ defaultStateDir,
+ statePaths,
+ writeState,
+ writeEvent,
+ moodForHookEvent,
+ pollState,
+} from './state.js';
+export { claudeHooksConfig, installClaudeHooks, hookCommand } from './hooks.js';
+export { snapshot } from './snapshot.js';
diff --git a/packages/tty-avatar/src/load.js b/packages/tty-avatar/src/load.js
new file mode 100644
index 000000000..a7134bbc7
--- /dev/null
+++ b/packages/tty-avatar/src/load.js
@@ -0,0 +1,188 @@
+// GLB → flat triangle buffers with a per-triangle tint.
+//
+// Everything downstream (the rasterizer, the encoders) works on typed arrays:
+// one Float32Array of world-space positions (9 floats per triangle), one of
+// face normals (3 per triangle), one of linear RGB tints (3 per triangle).
+// Node transforms are baked in, so a multi-mesh avatar arrives as one soup.
+//
+// Colour comes from the material's baseColorFactor and, when a primitive
+// carries COLOR_0, the per-vertex colour averaged over the face. Textures are
+// not sampled: a terminal cell is far too coarse for texel detail, and a flat
+// tint plus lighting reads better at 80 columns than a smeared albedo would.
+
+import { readFile } from 'node:fs/promises';
+import { NodeIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
+import { MeshoptDecoder } from 'meshoptimizer';
+
+let ioPromise;
+
+async function getIO() {
+ ioPromise ??= (async () => {
+ const io = new NodeIO().registerExtensions(ALL_EXTENSIONS);
+ await MeshoptDecoder.ready;
+ const deps = { 'meshopt.decoder': MeshoptDecoder };
+ try {
+ const draco3d = (await import('draco3dgltf')).default;
+ deps['draco3d.decoder'] = await draco3d.createDecoderModule();
+ } catch {
+ // draco3dgltf is optional: only Draco-compressed inputs need it, and
+ // gltf-transform raises its own clear error for those when it is absent.
+ }
+ return io.registerDependencies(deps);
+ })();
+ return ioPromise;
+}
+
+const TRIANGLES = 4;
+
+/**
+ * @typedef {object} Mesh
+ * @property {Float32Array} positions 9 floats per triangle, unit-sphere normalised, Y-up
+ * @property {Float32Array} normals 3 floats per triangle (face normal)
+ * @property {Float32Array} tints 3 floats per triangle, linear RGB in [0,1]
+ * @property {number} count triangle count
+ * @property {{ min: number[], max: number[] }} bounds bounds AFTER normalisation
+ * @property {number} sourceCount triangle count before any stride reduction
+ */
+
+/**
+ * Parse GLB/glTF bytes into a render-ready mesh.
+ *
+ * @param {Uint8Array|ArrayBuffer} bytes
+ * @param {{ maxTriangles?: number }} [opts] cap the soup by uniform stride so a
+ * 500k-triangle scan still renders at interactive rates; default 240000
+ * @returns {Promise<Mesh>}
+ */
+export async function parseGlb(bytes, { maxTriangles = 240_000 } = {}) {
+ const io = await getIO();
+ const doc = await io.readBinary(bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes));
+ const soup = [];
+ const tints = [];
+ for (const scene of doc.getRoot().listScenes()) {
+ scene.traverse((node) => {
+ const mesh = node.getMesh();
+ if (!mesh) return;
+ const m = node.getWorldMatrix();
+ for (const prim of mesh.listPrimitives()) {
+ if (prim.getMode() !== TRIANGLES) continue;
+ const pos = prim.getAttribute('POSITION');
+ if (!pos) continue;
+ const col = prim.getAttribute('COLOR_0');
+ const base = materialTint(prim.getMaterial());
+ const idx = prim.getIndices();
+ const count = idx ? idx.getCount() : pos.getCount();
+ const p = [];
+ const c = [];
+ for (let i = 0; i + 2 < count; i += 3) {
+ let r = 0, g = 0, b = 0;
+ for (let j = 0; j < 3; j++) {
+ const vi = idx ? idx.getScalar(i + j) : i + j;
+ pos.getElement(vi, p);
+ soup.push(
+ m[0] * p[0] + m[4] * p[1] + m[8] * p[2] + m[12],
+ m[1] * p[0] + m[5] * p[1] + m[9] * p[2] + m[13],
+ m[2] * p[0] + m[6] * p[1] + m[10] * p[2] + m[14],
+ );
+ if (col) {
+ col.getElement(vi, c);
+ r += c[0]; g += c[1]; b += c[2];
+ }
+ }
+ if (col) tints.push((r / 3) * base[0], (g / 3) * base[1], (b / 3) * base[2]);
+ else tints.push(base[0], base[1], base[2]);
+ }
+ }
+ });
+ }
+ return finishMesh(new Float32Array(soup), new Float32Array(tints), maxTriangles);
+}
+
+/**
+ * Load a GLB from disk.
+ * @param {string} path
+ * @param {{ maxTriangles?: number }} [opts]
+ */
+export async function loadGlbFile(path, opts) {
+ return parseGlb(await readFile(path), opts);
+}
+
+function materialTint(mat) {
+ if (!mat) return [0.82, 0.82, 0.86];
+ const f = mat.getBaseColorFactor();
+ // A pure-white factor on a textured material carries no colour information;
+ // lean on a warm neutral so lit skin and cloth do not read as chalk.
+ if (mat.getBaseColorTexture() && f[0] > 0.98 && f[1] > 0.98 && f[2] > 0.98) return [0.86, 0.78, 0.72];
+ return [f[0], f[1], f[2]];
+}
+
+/**
+ * Normalise to the unit sphere, drop to a triangle budget, and compute face
+ * normals. Exported so tests can feed a synthetic soup without a GLB.
+ *
+ * @param {Float32Array} positions 9 floats per triangle
+ * @param {Float32Array} tints 3 floats per triangle
+ * @param {number} maxTriangles
+ * @returns {Mesh}
+ */
+export function finishMesh(positions, tints, maxTriangles = 240_000) {
+ const sourceCount = positions.length / 9;
+ let pos = positions;
+ let tint = tints;
+ if (sourceCount > maxTriangles) {
+ const stride = Math.ceil(sourceCount / maxTriangles);
+ const keep = Math.floor(sourceCount / stride);
+ pos = new Float32Array(keep * 9);
+ tint = new Float32Array(keep * 3);
+ for (let i = 0; i < keep; i++) {
+ pos.set(positions.subarray(i * stride * 9, i * stride * 9 + 9), i * 9);
+ tint.set(tints.subarray(i * stride * 3, i * stride * 3 + 3), i * 3);
+ }
+ }
+ const count = pos.length / 9;
+ const min = [Infinity, Infinity, Infinity];
+ const max = [-Infinity, -Infinity, -Infinity];
+ for (let i = 0; i < pos.length; i += 3) {
+ for (let a = 0; a < 3; a++) {
+ const v = pos[i + a];
+ if (v < min[a]) min[a] = v;
+ if (v > max[a]) max[a] = v;
+ }
+ }
+ const cx = (min[0] + max[0]) / 2;
+ const cy = (min[1] + max[1]) / 2;
+ const cz = (min[2] + max[2]) / 2;
+ let radius = 0;
+ for (let i = 0; i < pos.length; i += 3) {
+ const d = Math.hypot(pos[i] - cx, pos[i + 1] - cy, pos[i + 2] - cz);
+ if (d > radius) radius = d;
+ }
+ const s = radius > 1e-9 ? 1 / radius : 1;
+ const out = new Float32Array(pos.length);
+ for (let i = 0; i < pos.length; i += 3) {
+ out[i] = (pos[i] - cx) * s;
+ out[i + 1] = (pos[i + 1] - cy) * s;
+ out[i + 2] = (pos[i + 2] - cz) * s;
+ }
+ const normals = new Float32Array(count * 3);
+ for (let t = 0; t < count; t++) {
+ const o = t * 9;
+ const ux = out[o + 3] - out[o], uy = out[o + 4] - out[o + 1], uz = out[o + 5] - out[o + 2];
+ const wx = out[o + 6] - out[o], wy = out[o + 7] - out[o + 1], wz = out[o + 8] - out[o + 2];
+ let nx = uy * wz - uz * wy, ny = uz * wx - ux * wz, nz = ux * wy - uy * wx;
+ const len = Math.hypot(nx, ny, nz);
+ if (len > 1e-12) { nx /= len; ny /= len; nz /= len; } else { nx = 0; ny = 0; nz = 1; }
+ normals[t * 3] = nx; normals[t * 3 + 1] = ny; normals[t * 3 + 2] = nz;
+ }
+ return {
+ positions: out,
+ normals,
+ tints: tint,
+ count,
+ sourceCount,
+ bounds: {
+ min: [(min[0] - cx) * s, (min[1] - cy) * s, (min[2] - cz) * s],
+ max: [(max[0] - cx) * s, (max[1] - cy) * s, (max[2] - cz) * s],
+ },
+ };
+}
diff --git a/packages/tty-avatar/src/moods.js b/packages/tty-avatar/src/moods.js
new file mode 100644
index 000000000..370014368
--- /dev/null
+++ b/packages/tty-avatar/src/moods.js
@@ -0,0 +1,117 @@
+// Moods are procedural motion: a pure function of time that returns a pose.
+//
+// No rig is required. A triangle soup cannot play a skinned clip, so every
+// mood is expressed with whole-body motion the eye already reads as intent:
+// a slow sway is idle, a tilt is thinking, a bounce is joy, a rapid shake is
+// an error. Each function takes seconds since the mood began and returns the
+// pose delta the rasterizer applies on top of the base yaw.
+
+/** @typedef {(t: number) => import('./raster.js').Pose} Motion */
+
+/** @type {Record<string, { motion: Motion, label: string }>} */
+export const MOODS = {
+ idle: {
+ label: 'idle',
+ motion: (t) => ({
+ yaw: 0.22 * Math.sin(t * 0.6),
+ y: 0.012 * Math.sin(t * 2.1),
+ scale: 1 + 0.006 * Math.sin(t * 2.1),
+ }),
+ },
+ spin: {
+ label: 'turntable',
+ motion: (t) => ({ yaw: t * 0.9, y: 0.01 * Math.sin(t * 2) }),
+ },
+ think: {
+ label: 'thinking',
+ motion: (t) => ({
+ yaw: 0.35 * Math.sin(t * 0.45) + 0.18,
+ pitch: -0.08 + 0.04 * Math.sin(t * 0.9),
+ roll: 0.11 * Math.sin(t * 0.5),
+ y: 0.02 * Math.sin(t * 1.3),
+ }),
+ },
+ work: {
+ label: 'working',
+ motion: (t) => ({
+ yaw: 0.06 * Math.sin(t * 3.2),
+ pitch: 0.05 + 0.03 * Math.sin(t * 9.5),
+ y: 0.018 * Math.sin(t * 9.5),
+ }),
+ },
+ talk: {
+ label: 'talking',
+ motion: (t) => ({
+ yaw: 0.1 * Math.sin(t * 1.7),
+ pitch: 0.07 * Math.sin(t * 3.4),
+ y: 0.03 * Math.abs(Math.sin(t * 6.5)),
+ scale: 1 + 0.01 * Math.sin(t * 6.5),
+ }),
+ },
+ happy: {
+ label: 'happy',
+ motion: (t) => ({
+ yaw: 0.3 * Math.sin(t * 3.6),
+ roll: 0.07 * Math.sin(t * 3.6),
+ y: 0.13 * Math.abs(Math.sin(t * 3.6)),
+ scale: 1 + 0.03 * Math.abs(Math.sin(t * 3.6)),
+ }),
+ },
+ attention: {
+ label: 'needs you',
+ motion: (t) => ({
+ yaw: 0.12 * Math.sin(t * 2.4),
+ y: 0.05 * Math.abs(Math.sin(t * 4.8)),
+ scale: 1 + 0.07 * (0.5 + 0.5 * Math.sin(t * 6)),
+ }),
+ },
+ error: {
+ label: 'error',
+ motion: (t) => ({
+ yaw: 0.16 * Math.sin(t * 22),
+ roll: 0.05 * Math.sin(t * 19),
+ pitch: 0.05,
+ }),
+ },
+ sleep: {
+ label: 'asleep',
+ motion: (t) => ({
+ pitch: 0.28 + 0.02 * Math.sin(t * 1.1),
+ y: -0.06 + 0.012 * Math.sin(t * 1.1),
+ scale: 1 + 0.008 * Math.sin(t * 1.1),
+ }),
+ },
+};
+
+export const MOOD_NAMES = Object.keys(MOODS);
+
+export function isMood(name) {
+ return Object.prototype.hasOwnProperty.call(MOODS, name);
+}
+
+/**
+ * Blend from one mood to another over `blendMs` so a hook-driven switch never
+ * pops. Returns a pose for the given wall-clock time.
+ *
+ * @param {{ name: string, since: number }} current
+ * @param {{ name: string, since: number } | null} previous
+ * @param {number} now ms
+ * @param {number} [blendMs]
+ */
+export function poseAt(current, previous, now, blendMs = 450) {
+ const cur = MOODS[current.name] ? MOODS[current.name].motion((now - current.since) / 1000) : {};
+ if (!previous || !MOODS[previous.name]) return cur;
+ const k = Math.min(1, (now - current.since) / blendMs);
+ if (k >= 1) return cur;
+ const prev = MOODS[previous.name].motion((now - previous.since) / 1000);
+ const e = k * k * (3 - 2 * k);
+ const mix = (key, def = 0) => (prev[key] ?? def) * (1 - e) + (cur[key] ?? def) * e;
+ return {
+ yaw: mix('yaw'),
+ pitch: mix('pitch'),
+ roll: mix('roll'),
+ x: mix('x'),
+ y: mix('y'),
+ scale: mix('scale', 1),
+ };
+}
diff --git a/packages/tty-avatar/src/raster.js b/packages/tty-avatar/src/raster.js
new file mode 100644
index 000000000..8d82a320b
--- /dev/null
+++ b/packages/tty-avatar/src/raster.js
@@ -0,0 +1,147 @@
+// A tiny perspective rasterizer over a subpixel grid.
+//
+// The terminal is the framebuffer. Each character cell is split into subpixels
+// by the encoder (1x2 for half-blocks, 2x4 for braille), so the rasterizer
+// only ever sees a W x H grid of square-ish pixels and writes RGB + coverage
+// into it. Z-buffered scanline fill, back-face culling, a three-light shading
+// model (key, fill, rim) tuned to read on both dark and light terminals.
+//
+// Everything is allocation-free per frame: buffers are reused across calls.
+
+/**
+ * @typedef {object} Frame
+ * @property {number} width
+ * @property {number} height
+ * @property {Uint8Array} hit 1 where a triangle covered the subpixel
+ * @property {Float32Array} rgb 3 floats per subpixel, linear [0,1]
+ * @property {Float32Array} depth view-space depth per subpixel (smaller = nearer)
+ */
+
+/**
+ * @typedef {object} Pose
+ * @property {number} [yaw] radians around Y (turntable)
+ * @property {number} [pitch] radians around X
+ * @property {number} [roll] radians around Z
+ * @property {number} [x] translation in model units (unit sphere)
+ * @property {number} [y]
+ * @property {number} [scale]
+ */
+
+const KEY = norm([-0.45, 0.65, 0.62]);
+const FILL = norm([0.7, -0.15, 0.55]);
+const AMBIENT = 0.22;
+
+function norm(v) {
+ const l = Math.hypot(v[0], v[1], v[2]);
+ return [v[0] / l, v[1] / l, v[2] / l];
+}
+
+/** Allocate a frame for the given subpixel size. */
+export function createFrame(width, height) {
+ return {
+ width,
+ height,
+ hit: new Uint8Array(width * height),
+ rgb: new Float32Array(width * height * 3),
+ depth: new Float32Array(width * height),
+ };
+}
+
+/**
+ * Render a mesh into a frame. The frame is cleared first.
+ *
+ * @param {import('./load.js').Mesh} mesh
+ * @param {Frame} frame
+ * @param {Pose} [pose]
+ * @param {{ fov?: number, distance?: number, zoom?: number }} [camera]
+ * @returns {Frame} the same frame, filled
+ */
+export function render(mesh, frame, pose = {}, camera = {}) {
+ const { width: W, height: H, hit, rgb, depth } = frame;
+ hit.fill(0);
+ depth.fill(Infinity);
+
+ const yaw = pose.yaw || 0, pitch = pose.pitch || 0, roll = pose.roll || 0;
+ const scale = pose.scale ?? 1;
+ const tx = pose.x || 0, ty = pose.y || 0;
+ const cy = Math.cos(yaw), sy = Math.sin(yaw);
+ const cp = Math.cos(pitch), sp = Math.sin(pitch);
+ const cr = Math.cos(roll), sr = Math.sin(roll);
+ // Rotation = Rz(roll) * Rx(pitch) * Ry(yaw), applied to model then camera looks down -Z.
+ const r00 = cr * cy + sr * sp * sy, r01 = -sr * cp, r02 = -cr * sy + sr * sp * cy;
+ const r10 = sr * cy - cr * sp * sy, r11 = cr * cp, r12 = -sr * sy - cr * sp * cy;
+ const r20 = cp * sy, r21 = sp, r22 = cp * cy;
+
+ const distance = camera.distance ?? 3.1;
+ const fov = camera.fov ?? 0.62;
+ const zoom = camera.zoom ?? 1;
+ // Focal length in subpixels: fit the unit sphere vertically with a margin.
+ const f = (Math.min(W, H) / 2) / Math.tan(fov / 2) * zoom;
+ const cxs = W / 2, cys = H / 2;
+
+ const P = mesh.positions, N = mesh.normals, T = mesh.tints;
+ const v = new Float32Array(9); // projected: sx, sy, z per vertex
+ for (let t = 0; t < mesh.count; t++) {
+ const o = t * 9;
+ // Face normal in view space (rotation only).
+ const nx0 = N[t * 3], ny0 = N[t * 3 + 1], nz0 = N[t * 3 + 2];
+ const nx = r00 * nx0 + r01 * ny0 + r02 * nz0;
+ const ny = r10 * nx0 + r11 * ny0 + r12 * nz0;
+ const nz = r20 * nx0 + r21 * ny0 + r22 * nz0;
+ if (nz <= 0) continue; // facing away from the camera at +Z
+
+ let minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
+ for (let j = 0; j < 3; j++) {
+ const x0 = P[o + j * 3] * scale, y0 = P[o + j * 3 + 1] * scale, z0 = P[o + j * 3 + 2] * scale;
+ const x = r00 * x0 + r01 * y0 + r02 * z0 + tx;
+ const y = r10 * x0 + r11 * y0 + r12 * z0 + ty;
+ const z = distance - (r20 * x0 + r21 * y0 + r22 * z0);
+ const inv = f / z;
+ const sx = cxs + x * inv;
+ const sy2 = cys - y * inv;
+ v[j * 3] = sx; v[j * 3 + 1] = sy2; v[j * 3 + 2] = z;
+ if (sx < minX) minX = sx; if (sx > maxX) maxX = sx;
+ if (sy2 < minY) minY = sy2; if (sy2 > maxY) maxY = sy2;
+ }
+ if (maxX < 0 || minX >= W || maxY < 0 || minY >= H) continue;
+
+ // Shade once per face: key + fill lambert, rim from the view vector.
+ const kd = Math.max(0, nx * KEY[0] + ny * KEY[1] + nz * KEY[2]);
+ const fd = Math.max(0, nx * FILL[0] + ny * FILL[1] + nz * FILL[2]);
+ const rim = Math.pow(1 - Math.min(1, nz), 3) * 0.35;
+ const light = AMBIENT + kd * 0.78 + fd * 0.22;
+ const tr = Math.min(1, T[t * 3] * light + rim);
+ const tg = Math.min(1, T[t * 3 + 1] * light + rim);
+ const tb = Math.min(1, T[t * 3 + 2] * light + rim * 1.15);
+
+ fillTriangle(v, W, H, minX, maxX, minY, maxY, hit, rgb, depth, tr, tg, tb);
+ }
+ return frame;
+}
+
+function fillTriangle(v, W, H, minX, maxX, minY, maxY, hit, rgb, depth, r, g, b) {
+ const x0 = v[0], y0 = v[1], z0 = v[2];
+ const x1 = v[3], y1 = v[4], z1 = v[5];
+ const x2 = v[6], y2 = v[7], z2 = v[8];
+ const area = (x1 - x0) * (y2 - y0) - (x2 - x0) * (y1 - y0);
+ if (Math.abs(area) < 1e-9) return;
+ const invArea = 1 / area;
+ const ys = Math.max(0, Math.floor(minY)), ye = Math.min(H - 1, Math.ceil(maxY));
+ const xs = Math.max(0, Math.floor(minX)), xe = Math.min(W - 1, Math.ceil(maxX));
+ for (let py = ys; py <= ye; py++) {
+ const cy = py + 0.5;
+ for (let px = xs; px <= xe; px++) {
+ const cx = px + 0.5;
+ let w0 = ((x1 - cx) * (y2 - cy) - (x2 - cx) * (y1 - cy)) * invArea;
+ let w1 = ((x2 - cx) * (y0 - cy) - (x0 - cx) * (y2 - cy)) * invArea;
+ let w2 = 1 - w0 - w1;
+ if (w0 < 0 || w1 < 0 || w2 < 0) continue;
+ const z = w0 * z0 + w1 * z1 + w2 * z2;
+ const i = py * W + px;
+ if (z >= depth[i]) continue;
+ depth[i] = z;
+ hit[i] = 1;
+ rgb[i * 3] = r; rgb[i * 3 + 1] = g; rgb[i * 3 + 2] = b;
+ }
+ }
+}
diff --git a/packages/tty-avatar/src/resolve.js b/packages/tty-avatar/src/resolve.js
new file mode 100644
index 000000000..42c3f3860
--- /dev/null
+++ b/packages/tty-avatar/src/resolve.js
@@ -0,0 +1,108 @@
+// Turn whatever the user typed into GLB bytes plus a display name.
+//
+// Accepted sources, tried in this order:
+// a local file path ./hero.glb
+// an http(s) URL to a GLB https://…/model.glb
+// a three.ws avatar id (uuid) 81a076b6-55ff-…
+// a three.ws agent id (uuid) bd1b56b0-5494-… (its bound body)
+// a three.ws page URL https://three.ws/avatars/<id>, /agents/<id>
+// Ids are looked up against the live API (`/api/avatars/:id`, then
+// `/api/agents/:id`), which is the same resolution the web studio performs.
+
+import { access, readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DEFAULT_ORIGIN = 'https://three.ws';
+
+/**
+ * @typedef {object} Resolved
+ * @property {Uint8Array} bytes
+ * @property {string} name
+ * @property {string} source file | url | avatar | agent
+ * @property {string} [url]
+ * @property {string} [page] the three.ws page for this entity, when known
+ */
+
+/**
+ * @param {string} input
+ * @param {{ origin?: string, fetch?: typeof fetch, timeoutMs?: number }} [opts]
+ * @returns {Promise<Resolved>}
+ */
+export async function resolveSource(input, opts = {}) {
+ const origin = (opts.origin || process.env.THREE_WS_ORIGIN || DEFAULT_ORIGIN).replace(/\/$/, '');
+ const doFetch = opts.fetch || fetch;
+ const timeoutMs = opts.timeoutMs ?? 30_000;
+ const raw = String(input || '').trim();
+ if (!raw) throw new Error('no source given: pass a .glb path, a URL, or a three.ws avatar/agent id');
+
+ if (await exists(raw)) {
+ return { bytes: new Uint8Array(await readFile(raw)), name: basename(raw), source: 'file' };
+ }
+
+ let url = null;
+ if (/^https?:\/\//i.test(raw)) {
+ url = new URL(raw);
+ const m = url.pathname.match(/^\/(avatars|agents)\/([0-9a-f-]{36})(?:\/|$)/i);
+ if (m) return resolveId(m[2], m[1] === 'agents' ? ['agent', 'avatar'] : ['avatar', 'agent'], url.origin, doFetch, timeoutMs);
+ const bytes = await fetchBytes(url.href, doFetch, timeoutMs);
+ return { bytes, name: basename(url.pathname) || url.hostname, source: 'url', url: url.href };
+ }
+
+ const id = raw.replace(/^(avatar|agent):/i, '');
+ const kindFirst = /^agent:/i.test(raw) ? ['agent', 'avatar'] : ['avatar', 'agent'];
+ if (UUID.test(id)) return resolveId(id, kindFirst, origin, doFetch, timeoutMs);
+
+ throw new Error(`"${raw}" is not a file, a URL, or a three.ws avatar/agent id`);
+}
+
+async function resolveId(id, order, origin, doFetch, timeoutMs) {
+ const errors = [];
+ for (const kind of order) {
+ try {
+ if (kind === 'avatar') {
+ const res = await fetchJson(`${origin}/api/avatars/${id}`, doFetch, timeoutMs);
+ const a = res.avatar || res;
+ const glb = a.model_url || a.url;
+ if (!glb) throw new Error('avatar record has no model_url');
+ return {
+ bytes: await fetchBytes(glb, doFetch, timeoutMs),
+ name: a.name || a.slug || id,
+ source: 'avatar',
+ url: glb,
+ page: `${origin}/avatars/${id}`,
+ };
+ }
+ const res = await fetchJson(`${origin}/api/agents/${id}`, doFetch, timeoutMs);
+ const a = res.data || res.agent || res;
+ const glb = a.avatar_model_url;
+ if (!glb) throw new Error(`agent "${a.name || id}" has no 3D body attached yet`);
+ return {
+ bytes: await fetchBytes(glb, doFetch, timeoutMs),
+ name: a.name || id,
+ source: 'agent',
+ url: glb,
+ page: `${origin}/agents/${id}`,
+ };
+ } catch (err) {
+ errors.push(`${kind}: ${err.message}`);
+ }
+ }
+ throw new Error(`could not resolve ${id} on ${origin} (${errors.join('; ')})`);
+}
+
+async function fetchJson(url, doFetch, timeoutMs) {
+ const res = await doFetch(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(timeoutMs) });
+ if (!res.ok) throw new Error(`${res.status} from ${url}`);
+ return res.json();
+}
+
+async function fetchBytes(url, doFetch, timeoutMs) {
+ const res = await doFetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+ if (!res.ok) throw new Error(`${res.status} fetching ${url}`);
+ return new Uint8Array(await res.arrayBuffer());
+}
+
+async function exists(p) {
+ try { await access(p); return true; } catch { return false; }
+}
diff --git a/packages/tty-avatar/src/snapshot.js b/packages/tty-avatar/src/snapshot.js
new file mode 100644
index 000000000..cdd273d12
--- /dev/null
+++ b/packages/tty-avatar/src/snapshot.js
@@ -0,0 +1,26 @@
+// One frame as a string. For READMEs, CI logs, screenshots-in-text, and tests.
+
+import { createFrame, render } from './raster.js';
+import { encode, MODES } from './encode.js';
+import { MOODS } from './moods.js';
+
+/**
+ * @param {import('./load.js').Mesh} mesh
+ * @param {{ mode?: 'blocks'|'braille'|'ascii', columns?: number, rows?: number, yaw?: number, pitch?: number, zoom?: number, mood?: string, t?: number }} [opts]
+ * @returns {string}
+ */
+export function snapshot(mesh, opts = {}) {
+ const mode = opts.mode && MODES[opts.mode] ? opts.mode : 'blocks';
+ const geom = MODES[mode];
+ const columns = opts.columns || 60;
+ const rows = opts.rows || 30;
+ const frame = createFrame(columns * geom.sx, rows * geom.sy);
+ const motion = opts.mood && MOODS[opts.mood] ? MOODS[opts.mood].motion(opts.t ?? 0) : {};
+ const pose = {
+ ...motion,
+ yaw: (motion.yaw || 0) + (opts.yaw || 0),
+ pitch: (motion.pitch || 0) + (opts.pitch || 0),
+ };
+ render(mesh, frame, pose, { zoom: opts.zoom || 1 });
+ return encode(frame, { mode }).join('\n');
+}
diff --git a/packages/tty-avatar/src/state.js b/packages/tty-avatar/src/state.js
new file mode 100644
index 000000000..33a35eb4d
--- /dev/null
+++ b/packages/tty-avatar/src/state.js
@@ -0,0 +1,169 @@
+// The bridge between the running viewer and everything else on the machine.
+//
+// One directory (default ~/.three-ws/tty-avatar) holds two files:
+// state.json the mood/caption a person or script set explicitly
+// (`tty-avatar mood happy`, `tty-avatar say "deploying"`)
+// event.json the last raw hook payload an agent runtime delivered
+// (Claude Code hooks pipe their JSON here with a single `cat`)
+// The viewer polls both by mtime and applies whichever changed most recently,
+// so a hook never has to know about the viewer and the viewer never has to
+// know about the hook runner. Zero startup cost on the hook side: the command
+// installed into Claude Code is `cat > event.json`, not a Node process.
+
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { isMood } from './moods.js';
+
+export function defaultStateDir() {
+ return process.env.TTY_AVATAR_DIR || join(homedir(), '.three-ws', 'tty-avatar');
+}
+
+export function statePaths(dir = defaultStateDir()) {
+ return { dir, state: join(dir, 'state.json'), event: join(dir, 'event.json') };
+}
+
+/**
+ * Write an explicit mood and/or caption.
+ * @param {{ mood?: string, say?: string, ttlMs?: number }} patch
+ * @param {string} [dir]
+ */
+export async function writeState(patch, dir = defaultStateDir()) {
+ const paths = statePaths(dir);
+ await mkdir(paths.dir, { recursive: true });
+ let prev = {};
+ try { prev = JSON.parse(await readFile(paths.state, 'utf8')); } catch { prev = {}; }
+ if (patch.mood !== undefined && !isMood(patch.mood)) {
+ throw new Error(`unknown mood "${patch.mood}"`);
+ }
+ const next = {
+ mood: patch.mood ?? prev.mood ?? 'idle',
+ say: patch.say ?? (patch.mood !== undefined ? '' : prev.say ?? ''),
+ until: patch.ttlMs ? Date.now() + patch.ttlMs : null,
+ at: Date.now(),
+ };
+ await writeFile(paths.state, JSON.stringify(next));
+ return next;
+}
+
+/**
+ * Store a raw hook payload for the viewer to interpret.
+ * @param {string} rawJson
+ * @param {string} [dir]
+ */
+export async function writeEvent(rawJson, dir = defaultStateDir()) {
+ const paths = statePaths(dir);
+ await mkdir(paths.dir, { recursive: true });
+ await writeFile(paths.event, rawJson);
+}
+
+/**
+ * Map a Claude Code hook payload (https://docs.claude.com/en/docs/claude-code/hooks)
+ * to a mood and a one-line caption. Unknown events return null so the viewer
+ * keeps its current mood. Transient moods carry a ttl so the avatar settles
+ * back to idle on its own.
+ *
+ * @param {object} ev
+ * @returns {{ mood: string, say: string, ttlMs: number|null } | null}
+ */
+export function moodForHookEvent(ev) {
+ if (!ev || typeof ev !== 'object') return null;
+ const name = ev.hook_event_name;
+ const tool = typeof ev.tool_name === 'string' ? ev.tool_name : '';
+ switch (name) {
+ case 'SessionStart':
+ return { mood: 'happy', say: 'session started', ttlMs: 2500 };
+ case 'UserPromptSubmit':
+ return { mood: 'think', say: 'reading your prompt', ttlMs: null };
+ case 'PreToolUse':
+ return { mood: 'work', say: describeTool(tool, ev.tool_input), ttlMs: null };
+ case 'PostToolUse': {
+ const failed = looksFailed(ev.tool_response);
+ return failed
+ ? { mood: 'error', say: `${tool || 'tool'} failed`, ttlMs: 2500 }
+ : { mood: 'think', say: `${tool || 'tool'} done`, ttlMs: null };
+ }
+ case 'PostToolUseFailure':
+ return { mood: 'error', say: `${tool || 'tool'} failed`, ttlMs: 2500 };
+ case 'Notification':
+ return { mood: 'attention', say: shorten(ev.message || 'needs your input'), ttlMs: 30_000 };
+ case 'Stop':
+ case 'SubagentStop':
+ return { mood: 'happy', say: 'done', ttlMs: 4000 };
+ case 'PreCompact':
+ return { mood: 'think', say: 'compacting memory', ttlMs: 4000 };
+ case 'SessionEnd':
+ return { mood: 'sleep', say: 'session ended', ttlMs: null };
+ default:
+ return null;
+ }
+}
+
+function looksFailed(resp) {
+ if (!resp) return false;
+ if (typeof resp === 'string') return /\b(error|failed|exception)\b/i.test(resp.slice(0, 200));
+ if (typeof resp === 'object') {
+ if (resp.success === false || resp.is_error === true || resp.isError === true) return true;
+ if (typeof resp.error === 'string' && resp.error) return true;
+ }
+ return false;
+}
+
+function describeTool(tool, input) {
+ if (!tool) return 'working';
+ const i = input && typeof input === 'object' ? input : {};
+ const file = typeof i.file_path === 'string' ? i.file_path.split('/').slice(-1)[0] : '';
+ switch (tool) {
+ case 'Read': return file ? `reading ${file}` : 'reading';
+ case 'Edit':
+ case 'Write':
+ case 'MultiEdit': return file ? `editing ${file}` : 'editing';
+ case 'Bash': return typeof i.command === 'string' ? shorten(`$ ${i.command}`) : 'running a command';
+ case 'Grep':
+ case 'Glob': return 'searching';
+ case 'WebFetch':
+ case 'WebSearch': return 'browsing';
+ case 'Agent':
+ case 'Task': return 'delegating';
+ default: return shorten(tool.replace(/^mcp__/, ''));
+ }
+}
+
+function shorten(s, n = 56) {
+ const one = String(s).replace(/\s+/g, ' ').trim();
+ return one.length > n ? `${one.slice(0, n - 1)}…` : one;
+}
+
+/**
+ * Poll both files and return the newest instruction since `sinceMs`, or null.
+ * @param {string} dir
+ * @param {number} sinceMs
+ */
+export async function pollState(dir, sinceMs) {
+ const paths = statePaths(dir);
+ const [s, e] = await Promise.all([mtime(paths.state), mtime(paths.event)]);
+ const newest = Math.max(s, e);
+ if (newest <= sinceMs) return null;
+ try {
+ if (e >= s) {
+ const ev = JSON.parse(await readFile(paths.event, 'utf8'));
+ const mapped = moodForHookEvent(ev);
+ return mapped ? { ...mapped, at: newest, source: 'hook' } : { at: newest, source: 'hook', mood: null };
+ }
+ const st = JSON.parse(await readFile(paths.state, 'utf8'));
+ return {
+ mood: st.mood,
+ say: st.say || '',
+ ttlMs: st.until ? Math.max(0, st.until - Date.now()) : null,
+ at: newest,
+ source: 'state',
+ };
+ } catch {
+ // A partially written file (the writer is mid-`cat`) parses on the next tick.
+ return null;
+ }
+}
+
+async function mtime(p) {
+ try { return (await stat(p)).mtimeMs; } catch { return 0; }
+}
diff --git a/packages/tty-avatar/src/terminal.js b/packages/tty-avatar/src/terminal.js
new file mode 100644
index 000000000..fdc350ce3
--- /dev/null
+++ b/packages/tty-avatar/src/terminal.js
@@ -0,0 +1,177 @@
+// The viewer: a frame loop that owns the terminal while it runs.
+//
+// Responsibilities: size the subpixel grid to the terminal, render + encode a
+// frame at a fixed cadence, redraw in place, poll the state directory for
+// mood changes, and hand the terminal back exactly as it was found (alt
+// screen, cursor) on exit or on any signal.
+
+import { EventEmitter } from 'node:events';
+import { createFrame, render } from './raster.js';
+import { encode, MODES } from './encode.js';
+import { MOODS, isMood, poseAt } from './moods.js';
+import { defaultStateDir, pollState } from './state.js';
+
+const ESC = '\x1b[';
+const DIM = `${ESC}2m`;
+const BOLD = `${ESC}1m`;
+const RESET = `${ESC}0m`;
+
+/**
+ * @typedef {object} ViewerOptions
+ * @property {'blocks'|'braille'|'ascii'} [mode]
+ * @property {number} [fps]
+ * @property {number} [columns] override terminal width in cells
+ * @property {number} [rows] override terminal height in cells
+ * @property {string} [mood] starting mood
+ * @property {number} [yaw] base yaw in radians, added to the mood's motion
+ * @property {number} [zoom]
+ * @property {boolean} [altScreen] default true when stdout is a TTY
+ * @property {boolean} [caption] default true
+ * @property {string} [name]
+ * @property {string} [stateDir] default ~/.three-ws/tty-avatar; null disables polling
+ * @property {NodeJS.WriteStream} [out]
+ */
+
+export class TtyAvatar extends EventEmitter {
+ /**
+ * @param {import('./load.js').Mesh} mesh
+ * @param {ViewerOptions} [opts]
+ */
+ constructor(mesh, opts = {}) {
+ super();
+ this.mesh = mesh;
+ this.mode = opts.mode && MODES[opts.mode] ? opts.mode : 'blocks';
+ this.fps = Math.max(1, Math.min(60, opts.fps || 24));
+ this.out = opts.out || process.stdout;
+ this.isTTY = Boolean(this.out.isTTY);
+ this.columns = opts.columns || null;
+ this.rows = opts.rows || null;
+ this.baseYaw = opts.yaw || 0;
+ this.zoom = opts.zoom || 1;
+ this.altScreen = opts.altScreen ?? this.isTTY;
+ this.caption = opts.caption ?? true;
+ this.name = opts.name || 'avatar';
+ this.stateDir = opts.stateDir === null ? null : (opts.stateDir || defaultStateDir());
+ this.say = '';
+ this.current = { name: isMood(opts.mood) ? opts.mood : 'idle', since: Date.now() };
+ this.previous = null;
+ this.until = null;
+ this.lastStateAt = Date.now();
+ this.frames = 0;
+ this.timer = null;
+ this.poller = null;
+ this.frame = null;
+ this._onResize = () => { this.frame = null; };
+ this._onSignal = () => this.stop().then(() => process.exit(0));
+ }
+
+ /** Switch mood with a cross-fade; `ttlMs` returns to idle afterwards. */
+ setMood(name, { say, ttlMs } = {}) {
+ if (!isMood(name)) throw new Error(`unknown mood "${name}" (one of ${Object.keys(MOODS).join(', ')})`);
+ if (name !== this.current.name) {
+ this.previous = this.current;
+ this.current = { name, since: Date.now() };
+ }
+ if (say !== undefined) this.say = say;
+ this.until = ttlMs ? Date.now() + ttlMs : null;
+ this.emit('mood', { mood: name, say: this.say });
+ }
+
+ setCaption(text) {
+ this.say = text || '';
+ }
+
+ /** Cell geometry currently in use. */
+ size() {
+ const cols = this.columns || this.out.columns || 80;
+ const rows = this.rows || this.out.rows || 24;
+ const captionRows = this.caption ? 1 : 0;
+ const drawRows = Math.max(4, rows - captionRows - (this.altScreen ? 0 : 1));
+ const geom = MODES[this.mode];
+ return { cols, rows, drawRows, width: cols * geom.sx, height: drawRows * geom.sy };
+ }
+
+ /** Render one frame to lines (no terminal writes). */
+ renderLines(now = Date.now()) {
+ const { width, height } = this.size();
+ if (!this.frame || this.frame.width !== width || this.frame.height !== height) {
+ this.frame = createFrame(width, height);
+ }
+ const pose = poseAt(this.current, this.previous, now);
+ pose.yaw = (pose.yaw || 0) + this.baseYaw;
+ render(this.mesh, this.frame, pose, { zoom: this.zoom });
+ const lines = encode(this.frame, { mode: this.mode });
+ if (this.caption) lines.push(this.captionLine());
+ return lines;
+ }
+
+ captionLine() {
+ const { cols } = this.size();
+ const mood = MOODS[this.current.name]?.label || this.current.name;
+ const left = `${BOLD}${this.name}${RESET} ${DIM}· ${mood}${RESET}`;
+ const leftLen = this.name.length + 3 + mood.length;
+ const say = this.say ? ` ${this.say}` : '';
+ const room = Math.max(0, cols - leftLen - 1);
+ const shown = say.length > room ? `${say.slice(0, Math.max(0, room - 1))}…` : say;
+ return `${left}${DIM}${shown}${RESET}`;
+ }
+
+ async tick() {
+ const now = Date.now();
+ if (this.until && now >= this.until) {
+ this.until = null;
+ this.setMood('idle', { say: '' });
+ }
+ const lines = this.renderLines(now);
+ const body = lines.join(`${ESC}0K\n`);
+ this.out.write(`${ESC}H${body}${ESC}0K${ESC}0J`);
+ this.frames++;
+ this.emit('frame', this.frames);
+ }
+
+ async pollOnce() {
+ if (!this.stateDir) return;
+ const next = await pollState(this.stateDir, this.lastStateAt);
+ if (!next) return;
+ this.lastStateAt = next.at;
+ if (next.mood) this.setMood(next.mood, { say: next.say ?? '', ttlMs: next.ttlMs ?? undefined });
+ }
+
+ /** Start the loop. Resolves when `stop()` is called (or after `frames` frames). */
+ start({ frames = Infinity } = {}) {
+ if (this.timer) return this.done;
+ if (this.altScreen) this.out.write(`${ESC}?1049h`);
+ if (this.isTTY) this.out.write(`${ESC}?25l`);
+ this.out.write(`${ESC}2J${ESC}H`);
+ this.out.on?.('resize', this._onResize);
+ process.on('SIGINT', this._onSignal);
+ process.on('SIGTERM', this._onSignal);
+ this.done = new Promise((resolve) => { this._resolve = resolve; });
+ let busy = false;
+ this.timer = setInterval(async () => {
+ if (busy) return;
+ busy = true;
+ try {
+ await this.tick();
+ if (this.frames >= frames) await this.stop();
+ } finally { busy = false; }
+ }, Math.round(1000 / this.fps));
+ if (this.stateDir) this.poller = setInterval(() => this.pollOnce().catch(() => {}), 200);
+ return this.done;
+ }
+
+ async stop() {
+ if (!this.timer) return;
+ clearInterval(this.timer);
+ this.timer = null;
+ if (this.poller) { clearInterval(this.poller); this.poller = null; }
+ this.out.off?.('resize', this._onResize);
+ process.off('SIGINT', this._onSignal);
+ process.off('SIGTERM', this._onSignal);
+ if (this.isTTY) this.out.write(`${ESC}?25h`);
+ if (this.altScreen) this.out.write(`${ESC}?1049l`);
+ else this.out.write('\n');
+ this.emit('stop');
+ this._resolve?.();
+ }
+}
diff --git a/packages/tty-avatar/test/_fixture.js b/packages/tty-avatar/test/_fixture.js
new file mode 100644
index 000000000..7973f9848
--- /dev/null
+++ b/packages/tty-avatar/test/_fixture.js
@@ -0,0 +1,27 @@
+// Builds a small real GLB in memory with @gltf-transform so the tests exercise
+// the actual loader, not a hand-made triangle array.
+
+import { Document, NodeIO } from '@gltf-transform/core';
+
+/** A unit cube (12 triangles) with a coloured material, as GLB bytes. */
+export async function cubeGlb({ color = [0.9, 0.3, 0.2, 1] } = {}) {
+ const doc = new Document();
+ const buffer = doc.createBuffer();
+ const p = [];
+ const faces = [
+ [[-1, -1, 1], [1, -1, 1], [1, 1, 1], [-1, 1, 1]], // +z
+ [[1, -1, -1], [-1, -1, -1], [-1, 1, -1], [1, 1, -1]], // -z
+ [[1, -1, 1], [1, -1, -1], [1, 1, -1], [1, 1, 1]], // +x
+ [[-1, -1, -1], [-1, -1, 1], [-1, 1, 1], [-1, 1, -1]], // -x
+ [[-1, 1, 1], [1, 1, 1], [1, 1, -1], [-1, 1, -1]], // +y
+ [[-1, -1, -1], [1, -1, -1], [1, -1, 1], [-1, -1, 1]], // -y
+ ];
+ for (const [a, b, c, d] of faces) p.push(...a, ...b, ...c, ...a, ...c, ...d);
+ const position = doc.createAccessor().setType('VEC3').setArray(new Float32Array(p)).setBuffer(buffer);
+ const material = doc.createMaterial('paint').setBaseColorFactor(color);
+ const prim = doc.createPrimitive().setAttribute('POSITION', position).setMaterial(material);
+ const mesh = doc.createMesh('cube').addPrimitive(prim);
+ const node = doc.createNode('cube').setMesh(mesh).setTranslation([0.5, 0, 0]);
+ doc.createScene('scene').addChild(node);
+ return new NodeIO().writeBinary(doc);
+}
diff --git a/packages/tty-avatar/test/cli.test.js b/packages/tty-avatar/test/cli.test.js
new file mode 100644
index 000000000..5fefbe7e7
--- /dev/null
+++ b/packages/tty-avatar/test/cli.test.js
@@ -0,0 +1,59 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { cubeGlb } from './_fixture.js';
+
+const run = promisify(execFile);
+const BIN = fileURLToPath(new URL('../bin/tty-avatar.js', import.meta.url));
+
+async function fixture() {
+ const dir = await mkdtemp(join(tmpdir(), 'tty-avatar-cli-'));
+ const glb = join(dir, 'cube.glb');
+ await writeFile(glb, await cubeGlb());
+ return { dir, glb };
+}
+
+test('snapshot renders a local GLB to plain text', async () => {
+ const { glb } = await fixture();
+ const { stdout } = await run(process.execPath, [BIN, 'snapshot', glb, '--mode', 'ascii', '--columns', '40', '--rows', '20', '--yaw', '35', '--pitch', '20']);
+ const lines = stdout.replace(/\n$/, '').split('\n');
+ assert.equal(lines.length, 20);
+ assert.ok(lines.some((l) => l.trim().length > 5), 'something was drawn');
+ assert.ok(!stdout.includes('\x1b['), 'ascii mode has no escapes');
+});
+
+test('the viewer runs for N frames when stdout is a pipe and exits cleanly', async () => {
+ const { dir, glb } = await fixture();
+ const { stdout } = await run(process.execPath, [
+ BIN, glb, '--frames', '3', '--fps', '30', '--columns', '30', '--rows', '12', '--state-dir', join(dir, 'state'),
+ ]);
+ assert.ok(stdout.includes('\x1b[H'), 'redraws from the home position');
+ assert.ok(stdout.includes('cube.glb'), 'caption names the model');
+});
+
+test('mood, say, and hook write the files the viewer polls', async () => {
+ const { dir } = await fixture();
+ const stateDir = join(dir, 'state');
+ const { stdout: a } = await run(process.execPath, [BIN, 'mood', 'happy', '--say', 'deploy landed', '--state-dir', stateDir]);
+ assert.equal(a.trim(), 'happy · deploy landed');
+ const { stdout: b } = await run(process.execPath, [BIN, 'say', 'hello', 'there', '--state-dir', stateDir]);
+ assert.equal(b.trim(), 'hello there');
+ const child = execFile(process.execPath, [BIN, 'hook', '--state-dir', stateDir]);
+ child.stdin.end(JSON.stringify({ hook_event_name: 'Stop' }));
+ await new Promise((resolve, reject) => child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`exit ${code}`)))));
+ const { readFile } = await import('node:fs/promises');
+ assert.equal(JSON.parse(await readFile(join(stateDir, 'event.json'), 'utf8')).hook_event_name, 'Stop');
+ await assert.rejects(run(process.execPath, [BIN, 'mood', 'bogus', '--state-dir', stateDir]), /unknown mood/);
+});
+
+test('install-hooks --json prints a settings fragment; a bad source fails with a sentence', async () => {
+ const { stdout } = await run(process.execPath, [BIN, 'install-hooks', '--json', '--state-dir', '/tmp/s']);
+ const cfg = JSON.parse(stdout);
+ assert.ok(cfg.hooks.PreToolUse[0].hooks[0].command.includes('event.json'));
+ await assert.rejects(run(process.execPath, [BIN, 'snapshot', 'not-a-thing']), /not a file, a URL, or a three\.ws/);
+});
diff --git a/packages/tty-avatar/test/render.test.js b/packages/tty-avatar/test/render.test.js
new file mode 100644
index 000000000..c71d170b3
--- /dev/null
+++ b/packages/tty-avatar/test/render.test.js
@@ -0,0 +1,103 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseGlb, finishMesh } from '../src/load.js';
+import { createFrame, render } from '../src/raster.js';
+import { encode, stripAnsi, MODES } from '../src/encode.js';
+import { MOODS, MOOD_NAMES, poseAt } from '../src/moods.js';
+import { snapshot } from '../src/snapshot.js';
+import { cubeGlb } from './_fixture.js';
+
+test('parseGlb bakes node transforms, normalises to the unit sphere, and keeps the material tint', async () => {
+ const mesh = await parseGlb(await cubeGlb());
+ assert.equal(mesh.count, 12);
+ assert.equal(mesh.sourceCount, 12);
+ // Translated by +0.5 on x before normalisation; centred afterwards.
+ assert.ok(Math.abs(mesh.bounds.min[0] + mesh.bounds.max[0]) < 1e-6);
+ let maxR = 0;
+ for (let i = 0; i < mesh.positions.length; i += 3) {
+ maxR = Math.max(maxR, Math.hypot(mesh.positions[i], mesh.positions[i + 1], mesh.positions[i + 2]));
+ }
+ assert.ok(Math.abs(maxR - 1) < 1e-5, `unit sphere radius, got ${maxR}`);
+ assert.ok(Math.abs(mesh.tints[0] - 0.9) < 1e-6 && Math.abs(mesh.tints[1] - 0.3) < 1e-6);
+ for (let t = 0; t < mesh.count; t++) {
+ const n = Math.hypot(mesh.normals[t * 3], mesh.normals[t * 3 + 1], mesh.normals[t * 3 + 2]);
+ assert.ok(Math.abs(n - 1) < 1e-5, 'unit normals');
+ }
+});
+
+test('finishMesh decimates by stride above the triangle budget', () => {
+ const tris = 1000;
+ const positions = new Float32Array(tris * 9);
+ for (let i = 0; i < positions.length; i++) positions[i] = (i % 7) - 3;
+ const mesh = finishMesh(positions, new Float32Array(tris * 3).fill(1), 100);
+ assert.equal(mesh.sourceCount, 1000);
+ assert.equal(mesh.count, 100);
+});
+
+test('render covers the centre, culls back faces, and lights faces differently', async () => {
+ const mesh = await parseGlb(await cubeGlb());
+ const frame = createFrame(64, 64);
+ render(mesh, frame, { yaw: 0.6, pitch: 0.4 });
+ const centre = 32 * 64 + 32;
+ assert.equal(frame.hit[centre], 1, 'centre subpixel is covered');
+ assert.equal(frame.hit[0], 0, 'corner subpixel is empty');
+ const shades = new Set();
+ for (let i = 0; i < frame.hit.length; i++) {
+ if (frame.hit[i]) shades.add(frame.rgb[i * 3].toFixed(3));
+ }
+ // Three visible faces of a cube at this angle, three distinct lit shades.
+ assert.ok(shades.size >= 3, `expected 3+ shades, got ${shades.size}`);
+ let covered = 0;
+ for (const h of frame.hit) covered += h;
+ assert.ok(covered > 64 * 64 * 0.15 && covered < 64 * 64 * 0.9, `coverage ${covered}`);
+});
+
+test('every encoder emits one line per row and blank cells for empty space', async () => {
+ const mesh = await parseGlb(await cubeGlb());
+ for (const mode of Object.keys(MODES)) {
+ const cols = 40, rows = 20;
+ const frame = createFrame(cols * MODES[mode].sx, rows * MODES[mode].sy);
+ render(mesh, frame, { yaw: 0.5, pitch: 0.3 });
+ const lines = encode(frame, { mode });
+ assert.equal(lines.length, rows, `${mode}: rows`);
+ const plain = lines.map(stripAnsi);
+ assert.ok(plain.every((l) => l.length <= cols), `${mode}: width`);
+ assert.equal(plain[0].trim(), '', `${mode}: top row empty`);
+ assert.ok(plain[Math.floor(rows / 2)].trim().length > 0, `${mode}: middle row drawn`);
+ if (mode !== 'ascii') assert.ok(lines.some((l) => l.includes('\x1b[38;2;')), `${mode}: truecolor`);
+ else assert.ok(!lines.some((l) => l.includes('\x1b[')), 'ascii: no escapes');
+ }
+});
+
+test('braille packs 2x4 subpixels into the right code points', () => {
+ const frame = createFrame(2, 4);
+ frame.hit.fill(0);
+ frame.hit[0] = 1; // (0,0) → dot 1
+ frame.hit[3 * 2 + 1] = 1; // (1,3) → dot 8 (0x80)
+ frame.rgb.fill(0.5);
+ const [line] = encode(frame, { mode: 'braille' });
+ assert.equal(stripAnsi(line), String.fromCharCode(0x2800 + 0x01 + 0x80));
+});
+
+test('moods are pure functions of time and blend without popping', () => {
+ for (const name of MOOD_NAMES) {
+ const a = MOODS[name].motion(1.25);
+ const b = MOODS[name].motion(1.25);
+ assert.deepEqual(a, b, `${name} deterministic`);
+ }
+ const now = 10_000;
+ const prev = { name: 'sleep', since: now - 5000 };
+ const cur = { name: 'happy', since: now };
+ const start = poseAt(cur, prev, now);
+ const end = poseAt(cur, prev, now + 1000);
+ assert.ok(Math.abs((start.pitch || 0) - MOODS.sleep.motion(5).pitch) < 1e-9, 'starts at the previous pose');
+ assert.deepEqual(end, MOODS.happy.motion(1), 'lands on the new mood after the blend');
+});
+
+test('snapshot returns a multi-line string in each mode', async () => {
+ const mesh = await parseGlb(await cubeGlb());
+ const text = snapshot(mesh, { mode: 'ascii', columns: 30, rows: 15, yaw: 0.4, pitch: 0.3 });
+ const lines = text.split('\n');
+ assert.equal(lines.length, 15);
+ assert.ok(text.trim().length > 20);
+});
diff --git a/packages/tty-avatar/test/state.test.js b/packages/tty-avatar/test/state.test.js
new file mode 100644
index 000000000..3a8d175dc
--- /dev/null
+++ b/packages/tty-avatar/test/state.test.js
@@ -0,0 +1,74 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { moodForHookEvent, pollState, writeEvent, writeState, statePaths } from '../src/state.js';
+import { claudeHooksConfig, installClaudeHooks, HOOK_EVENTS, hookCommand } from '../src/hooks.js';
+
+test('hook events map to moods with captions that name the work', () => {
+ assert.deepEqual(
+ moodForHookEvent({ hook_event_name: 'PreToolUse', tool_name: 'Edit', tool_input: { file_path: '/a/b/index.js' } }),
+ { mood: 'work', say: 'editing index.js', ttlMs: null },
+ );
+ assert.equal(moodForHookEvent({ hook_event_name: 'PreToolUse', tool_name: 'Bash', tool_input: { command: 'npm test' } }).say, '$ npm test');
+ assert.equal(moodForHookEvent({ hook_event_name: 'PostToolUse', tool_name: 'Bash', tool_response: { success: false } }).mood, 'error');
+ assert.equal(moodForHookEvent({ hook_event_name: 'PostToolUse', tool_name: 'Read', tool_response: 'ok' }).mood, 'think');
+ assert.equal(moodForHookEvent({ hook_event_name: 'Notification', message: 'Claude needs your permission' }).mood, 'attention');
+ assert.equal(moodForHookEvent({ hook_event_name: 'Stop' }).mood, 'happy');
+ assert.equal(moodForHookEvent({ hook_event_name: 'SessionEnd' }).mood, 'sleep');
+ assert.equal(moodForHookEvent({ hook_event_name: 'SomethingNew' }), null);
+ assert.equal(moodForHookEvent('garbage'), null);
+});
+
+test('writeState / writeEvent round-trip through pollState, newest wins', async () => {
+ const dir = await mkdtemp(join(tmpdir(), 'tty-avatar-'));
+ assert.equal(await pollState(dir, 0), null, 'nothing yet');
+ const t0 = Date.now() - 1;
+ const st = await writeState({ mood: 'happy', say: 'shipped', ttlMs: 5000 }, dir);
+ assert.equal(st.mood, 'happy');
+ const a = await pollState(dir, t0);
+ assert.equal(a.source, 'state');
+ assert.equal(a.mood, 'happy');
+ assert.equal(a.say, 'shipped');
+ assert.ok(a.ttlMs > 4000 && a.ttlMs <= 5000);
+ assert.equal(await pollState(dir, a.at), null, 'nothing newer');
+
+ await new Promise((r) => setTimeout(r, 15));
+ await writeEvent(JSON.stringify({ hook_event_name: 'UserPromptSubmit' }), dir);
+ const b = await pollState(dir, a.at);
+ assert.equal(b.source, 'hook');
+ assert.equal(b.mood, 'think');
+
+ await new Promise((r) => setTimeout(r, 15));
+ await writeFile(statePaths(dir).event, '{"hook_event_name": "PreToo', 'utf8');
+ assert.equal(await pollState(dir, b.at), null, 'a half-written payload is skipped, not fatal');
+
+ await assert.rejects(() => writeState({ mood: 'nope' }, dir), /unknown mood/);
+});
+
+test('claudeHooksConfig covers every event with the cat bridge', () => {
+ const cfg = claudeHooksConfig('/tmp/x');
+ assert.deepEqual(Object.keys(cfg.hooks), HOOK_EVENTS);
+ for (const ev of HOOK_EVENTS) {
+ const cmd = cfg.hooks[ev][0].hooks[0].command;
+ assert.equal(cmd, hookCommand('/tmp/x'));
+ if (process.platform !== 'win32') assert.match(cmd, /cat > '\/tmp\/x\/event\.json'/);
+ }
+});
+
+test('installClaudeHooks merges into an existing settings file and is idempotent', async () => {
+ const dir = await mkdtemp(join(tmpdir(), 'tty-avatar-settings-'));
+ const settingsPath = join(dir, 'settings.json');
+ await writeFile(settingsPath, JSON.stringify({
+ permissions: { allow: ['Bash(npm test)'] },
+ hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'echo keep-me' }] }] },
+ }));
+ await installClaudeHooks({ settingsPath, dir: '/tmp/state' });
+ await installClaudeHooks({ settingsPath, dir: '/tmp/state' });
+ const out = JSON.parse(await readFile(settingsPath, 'utf8'));
+ assert.deepEqual(out.permissions, { allow: ['Bash(npm test)'] }, 'unrelated settings survive');
+ assert.equal(out.hooks.PreToolUse.length, 2, 'one foreign group + one of ours, not duplicated');
+ assert.equal(out.hooks.PreToolUse[0].hooks[0].command, 'echo keep-me');
+ assert.equal(out.hooks.Stop.length, 1);
+});