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.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(tty): render an avatar and a GLB as real frames inside a terminal
nirholas0e52930decc0
diff --git a/api/tty.js b/api/tty.jsnew file mode 100644index 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.jsnew file mode 100755index 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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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/LICENSEnew file mode 100644index 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.mdnew file mode 100644index 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.jsnew file mode 100755index 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.jsonnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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.jsnew file mode 100644index 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);+});