termlings 0.1.0

package/README.md

@@ -0,0 +1,179 @@
+# @touchgrass/avatar
+
+Pixel-art avatar system for [touchgrass.sh](https://touchgrass.sh). Each avatar is encoded as a **7-character hex DNA string** (~32M combinations) that deterministically renders a unique character with hat, eyes, mouth, body, legs, and two independent color hues.
+
+## Install
+
+```bash
+npm install @touchgrass/avatar
+# or
+bun add @touchgrass/avatar
+```
+
+## Usage
+
+### Core (framework-agnostic)
+
+```ts
+import {
+  generateRandomDNA,
+  decodeDNA,
+  encodeDNA,
+  generateGrid,
+  traitsFromName,
+  renderSVG,
+  renderTerminal,
+  renderTerminalSmall,
+  hslToRgb,
+  SLOTS,
+  EYES, MOUTHS, HATS, BODIES, LEGS,
+} from '@touchgrass/avatar';
+```
+
+#### Generate a random avatar
+
+```ts
+const dna = generateRandomDNA(); // e.g. "0a3f201"
+```
+
+#### Decode / encode DNA
+
+```ts
+const traits = decodeDNA('0a3f201');
+// { eyes: 0, mouth: 2, hat: 5, body: 1, legs: 3, faceHue: 8, hatHue: 2 }
+
+const dna = encodeDNA(traits); // "0a3f201"
+```
+
+#### Derive avatar from a name (no DNA needed)
+
+```ts
+const traits = traitsFromName('my-agent');
+// Deterministic — same name always produces same traits
+```
+
+#### Render to SVG string
+
+```ts
+const svg = renderSVG('0a3f201');           // default 10px per pixel
+const svg = renderSVG('0a3f201', 20);       // 20px per pixel
+const svg = renderSVG('0a3f201', 10, 1);    // walking frame 1
+```
+
+Returns a complete `<svg>` string with transparent background. Use it as `innerHTML`, write to a `.svg` file, or embed in an `<img>` via data URI.
+
+#### Render to terminal (ANSI)
+
+```ts
+const ansi = renderTerminal('0a3f201');      // full size (██ per pixel)
+const ansi = renderTerminalSmall('0a3f201'); // compact (half-block ▀▄)
+
+console.log(ansi);
+```
+
+#### Generate the pixel grid directly
+
+```ts
+const grid = generateGrid(traits, walkFrame, talkFrame, waveFrame);
+// Pixel[][] — 9 columns wide, variable rows tall
+```
+
+### Svelte
+
+```svelte
+<script>
+  import { Avatar } from '@touchgrass/avatar/svelte';
+</script>
+
+<!-- From DNA string -->
+<Avatar dna="0a3f201" />
+
+<!-- From name (deterministic hash) -->
+<Avatar name="my-agent" />
+
+<!-- Sizes: sm (3px), lg (8px, default), xl (14px) -->
+<Avatar dna="0a3f201" size="xl" />
+
+<!-- Animations -->
+<Avatar dna="0a3f201" walking />
+<Avatar dna="0a3f201" talking />
+<Avatar dna="0a3f201" waving />
+```
+
+Props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `dna` | `string` | — | 7-char hex DNA string |
+| `name` | `string` | — | Fallback: derive traits from name hash |
+| `size` | `'sm' \| 'lg' \| 'xl'` | `'lg'` | Pixel size (3/8/14px per cell) |
+| `walking` | `boolean` | `false` | Animate legs |
+| `talking` | `boolean` | `false` | Animate mouth |
+| `waving` | `boolean` | `false` | Animate arms |
+
+Either `dna` or `name` should be provided. If both are set, `dna` takes priority.
+
+## DNA Encoding
+
+7 traits packed into a single integer using mixed-radix encoding with **fixed slot sizes** for forward compatibility:
+
+| Trait | Variants | Slot size | Description |
+|-------|----------|-----------|-------------|
+| eyes | 11 | 12 | normal, wide, close, big, squint, narrow, etc. |
+| mouths | 7 | 12 | smile, smirk, narrow, wide variants |
+| hats | 24 | 24 | none, tophat, beanie, crown, cap, horns, mohawk, etc. |
+| bodies | 6 | 8 | normal, narrow, tapered (each with/without arms) |
+| legs | 6 | 8 | biped, quad, tentacles, thin, wide stance |
+| faceHue | 12 | 12 | 0-330 degrees in 30-degree steps |
+| hatHue | 12 | 12 | independent from face hue |
+
+Total slot space: `12 x 12 x 24 x 8 x 8 x 12 x 12 = 31,850,496` (~32M, 7 hex chars).
+
+New variants can be added within slot limits without breaking existing DNA strings. Legacy 6-char DNAs decode identically (leading zero is implicit).
+
+## Pixel Grid
+
+The avatar is a 9-column grid with variable height (depends on hat). Each cell is a `Pixel` type:
+
+| Pixel | Meaning | Rendering |
+|-------|---------|-----------|
+| `f` | Face/body | Solid face color |
+| `e` | Eye | Solid dark color |
+| `s` | Squint eye | Face bg + dark bottom half |
+| `n` | Narrow eye | Face bg + dark center strip |
+| `m` | Mouth | Face bg + dark top half |
+| `q` | Smile corner left | Face bg + dark bottom-right quarter |
+| `r` | Smile corner right | Face bg + dark bottom-left quarter |
+| `d` | Dark accent | Solid dark (hat bands, etc.) |
+| `h` | Hat | Solid hat color |
+| `l` | Thin leg | Half-width face color |
+| `k` | Thin hat detail | Half-width hat color |
+| `a` | Arm | Half-height face color |
+| `_` | Transparent | Empty |
+
+## Colors
+
+Each avatar has 3 colors derived from two hue indices (0-11, mapped to 0-330 degrees):
+
+- **Face color**: `hsl(faceHue * 30, 50%, 50%)`
+- **Dark color**: `hsl(faceHue * 30, 50%, 28%)` — eyes, mouth
+- **Hat color**: `hsl(hatHue * 30, 50%, 50%)`
+
+## Animations
+
+The grid generator supports three animation types via frame parameters:
+
+- **Walking** (`frame`): Cycles through leg variant frames
+- **Talking** (`talkFrame`): 0 = normal mouth, 1+ = open mouth animation
+- **Waving** (`waveFrame`): 0 = normal body, 1+ = alternating arm positions
+
+## Exports
+
+```
+@touchgrass/avatar          — Core TypeScript (DNA, grid, SVG, terminal, colors)
+@touchgrass/avatar/svelte   — Svelte 5 component (Avatar)
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "termlings",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Pixel art avatar system. 32M+ unique characters from a 7-char hex DNA string.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tomtev/touchgrass",
+    "directory": "packages/avatar"
+  },
+  "keywords": ["avatar", "pixel-art", "svelte", "react", "vue", "terminal", "ink"],
+  "exports": {
+    ".": "./src/index.ts",
+    "./svelte": "./src/svelte/index.ts",
+    "./react": "./src/react/index.ts",
+    "./vue": "./src/vue/index.ts",
+    "./ink": "./src/ink/index.ts"
+  },
+  "files": ["src"]
+}

package/src/index.ts

@@ -0,0 +1,784 @@
+// Agent DNA avatar system
+// Encodes visual identity as a 6-hex-char string (~16M combinations)
+
+export type Pixel = "f" | "e" | "s" | "n" | "m" | "d" | "h" | "l" | "k" | "q" | "r" | "a" | "_";
+// f = face/body, e = eye (dark, full block), s = squint eye (dark, thin horizontal ▄▄),
+// n = narrow eye (dark, thin vertical ▐▌),
+// m = mouth (dark, thin ▀▀ in terminal),
+// d = dark accent (full-block dark, for hat bands etc.),
+// h = hat (secondary hue), l = thin leg (face color, ▌ in terminal),
+// k = thin hat (hat color, ▐▌ in terminal),
+// q = smile corner left (dark ▗ on face bg), r = smile corner right (dark ▖ on face bg),
+// a = arm (face color, thin horizontal ▄▄ in terminal),
+// _ = transparent
+
+// Face row template (7px wide head centered in 9-col grid)
+const F: Pixel[] = ["_", "f", "f", "f", "f", "f", "f", "f", "_"];
+
+// --- Eye variants (1 row each) ---
+export const EYES: Pixel[][] = [
+  ["_", "f", "e", "f", "f", "f", "e", "f", "_"], // normal
+  ["_", "e", "f", "f", "f", "f", "f", "e", "_"], // wide
+  ["_", "f", "f", "e", "f", "e", "f", "f", "_"], // close
+  ["_", "f", "e", "f", "f", "f", "e", "f", "_"], // normal-alt
+  ["_", "e", "e", "f", "f", "f", "e", "e", "_"], // big
+  ["_", "f", "e", "e", "f", "e", "e", "f", "_"], // big close
+  ["_", "f", "s", "f", "f", "f", "s", "f", "_"], // squint
+  ["_", "s", "f", "f", "f", "f", "f", "s", "_"], // squint wide
+  ["_", "f", "n", "f", "f", "f", "n", "f", "_"], // narrow
+  ["_", "n", "f", "f", "f", "f", "f", "n", "_"], // narrow wide
+  ["_", "f", "f", "n", "f", "n", "f", "f", "_"], // narrow close
+];
+
+// --- Mouth variants (2 rows: gap + mouth) ---
+// Uses thin half-block rendering: m=▀▀, q=▗ corner left, r=▖ corner right
+export const MOUTHS: Pixel[][][] = [
+  [
+    // smile (default)
+    ["_", "f", "q", "f", "f", "f", "r", "f", "_"],
+    ["_", "f", "f", "m", "m", "m", "f", "f", "_"],
+  ],
+  [
+    // smirk left
+    ["_", "f", "q", "f", "f", "f", "f", "f", "_"],
+    ["_", "f", "f", "m", "m", "m", "f", "f", "_"],
+  ],
+  [
+    // smirk right
+    ["_", "f", "f", "f", "f", "f", "r", "f", "_"],
+    ["_", "f", "f", "m", "m", "m", "f", "f", "_"],
+  ],
+  [
+    // narrow
+    ["_", "f", "f", "q", "f", "r", "f", "f", "_"],
+    ["_", "f", "f", "f", "m", "f", "f", "f", "_"],
+  ],
+  [
+    // wide smile
+    ["_", "q", "f", "f", "f", "f", "f", "r", "_"],
+    ["_", "f", "m", "m", "m", "m", "m", "f", "_"],
+  ],
+  [
+    // wide smirk left
+    ["_", "q", "f", "f", "f", "f", "f", "f", "_"],
+    ["_", "f", "m", "m", "m", "m", "m", "f", "_"],
+  ],
+  [
+    // wide smirk right
+    ["_", "f", "f", "f", "f", "f", "f", "r", "_"],
+    ["_", "f", "m", "m", "m", "m", "m", "f", "_"],
+  ],
+];
+
+// --- Hat variants (0-3 rows) ---
+export const HATS: Pixel[][][] = [
+  [], // none
+  [
+    // tophat
+    ["_", "_", "_", "h", "h", "h", "_", "_", "_"],
+    ["_", "_", "_", "h", "h", "h", "_", "_", "_"],
+    ["_", "h", "h", "h", "h", "h", "h", "h", "_"],
+  ],
+  [
+    // beanie
+    ["_", "_", "_", "h", "h", "h", "_", "_", "_"],
+    ["_", "_", "h", "h", "h", "h", "h", "_", "_"],
+  ],
+  [
+    // crown
+    ["_", "_", "h", "_", "h", "_", "h", "_", "_"],
+    ["_", "_", "h", "h", "h", "h", "h", "_", "_"],
+  ],
+  [
+    // cap
+    ["_", "_", "h", "h", "h", "h", "h", "_", "_"],
+    ["h", "h", "h", "h", "h", "h", "h", "_", "_"],
+  ],
+  [
+    // horns
+    ["_", "h", "_", "_", "_", "_", "_", "h", "_"],
+    ["_", "h", "h", "_", "_", "_", "h", "h", "_"],
+  ],
+  [
+    // mohawk
+    ["_", "_", "_", "_", "h", "_", "_", "_", "_"],
+    ["_", "_", "_", "h", "h", "h", "_", "_", "_"],
+  ],
+  [
+    // antenna
+    ["_", "_", "_", "_", "h", "_", "_", "_", "_"],
+    ["_", "_", "_", "_", "h", "_", "_", "_", "_"],
+  ],
+  [
+    // halo
+    ["_", "_", "_", "h", "h", "h", "_", "_", "_"],
+  ],
+  [
+    // bandage
+    ["_", "f", "f", "f", "f", "f", "f", "f", "_"],
+    ["_", "h", "h", "h", "h", "h", "h", "h", "_"],
+  ],
+  [
+    // wide brim
+    ["_", "_", "h", "h", "h", "h", "h", "_", "_"],
+    ["h", "h", "h", "h", "h", "h", "h", "h", "h"],
+  ],
+  [
+    // unicorn horn
+    ["_", "_", "_", "_", "k", "_", "_", "_", "_"],
+    ["_", "_", "_", "_", "h", "_", "_", "_", "_"],
+    ["_", "_", "_", "h", "h", "h", "_", "_", "_"],
+  ],
+  [
+    // ears
+    ["_", "h", "h", "_", "_", "_", "h", "h", "_"],
+  ],
+  [
+    // spikes
+    ["_", "h", "_", "h", "_", "h", "_", "h", "_"],
+    ["_", "h", "h", "h", "h", "h", "h", "h", "_"],
+  ],
+  [
+    // party hat
+    ["_", "_", "_", "_", "h", "_", "_", "_", "_"],
+    ["_", "_", "_", "h", "h", "h", "_", "_", "_"],
+    ["_", "_", "h", "h", "h", "h", "h", "_", "_"],
+  ],
+  [
+    // flat top
+    ["_", "h", "h", "h", "h", "h", "h", "h", "_"],
+    ["_", "h", "h", "h", "h", "h", "h", "h", "_"],
+  ],
+  [
+    // afro
+    ["_", "_", "k", "h", "h", "h", "k", "_", "_"],
+    ["_", "k", "h", "h", "h", "h", "h", "k", "_"],
+  ],
+  [
+    // side sweep
+    ["_", "_", "_", "_", "h", "h", "h", "k", "_"],
+    ["_", "h", "h", "h", "h", "h", "h", "h", "_"],
+  ],
+  [
+    // cowboy hat
+    ["_", "_", "h", "h", "h", "h", "h", "_", "_"],
+    ["_", "_", "h", "h", "h", "h", "h", "_", "_"],
+    ["h", "h", "h", "h", "h", "h", "h", "h", "h"],
+  ],
+  [
+    // knitted hat
+    ["_", "_", "_", "h", "h", "h", "_", "_", "_"],
+    ["_", "_", "h", "h", "h", "h", "h", "_", "_"],
+    ["_", "h", "f", "h", "f", "h", "f", "h", "_"],
+  ],
+  [
+    // clown hair
+    ["h", "h", "_", "_", "_", "_", "_", "h", "h"],
+    ["h", "h", "h", "_", "_", "_", "h", "h", "h"],
+  ],
+  [
+    // stovepipe
+    ["_", "h", "h", "h", "h", "h", "h", "h", "_"],
+    ["_", "h", "h", "h", "h", "h", "h", "h", "_"],
+    ["_", "h", "h", "h", "h", "h", "h", "h", "_"],
+    ["_", "d", "d", "d", "d", "d", "d", "d", "_"],
+    ["h", "h", "h", "h", "h", "h", "h", "h", "h"],
+  ],
+];
+
+// --- Body variants (flat, no animation frames) ---
+export const BODIES: Pixel[][][] = [
+  [
+    // normal
+    ["_", "f", "f", "f", "f", "f", "f", "f", "_"],
+    ["_", "f", "f", "f", "f", "f", "f", "f", "_"],
+  ],
+  [
+    // normal-arms
+    ["a", "f", "f", "f", "f", "f", "f", "f", "a"],
+    ["_", "f", "f", "f", "f", "f", "f", "f", "_"],
+  ],
+  [
+    // narrow
+    ["_", "_", "f", "f", "f", "f", "f", "_", "_"],
+    ["_", "_", "f", "f", "f", "f", "f", "_", "_"],
+  ],
+  [
+    // narrow-arms
+    ["_", "a", "f", "f", "f", "f", "f", "a", "_"],
+    ["_", "_", "f", "f", "f", "f", "f", "_", "_"],
+  ],
+  [
+    // tapered
+    ["_", "f", "f", "f", "f", "f", "f", "f", "_"],
+    ["_", "_", "f", "f", "f", "f", "f", "_", "_"],
+  ],
+  [
+    // tapered-arms
+    ["a", "f", "f", "f", "f", "f", "f", "f", "a"],
+    ["_", "_", "f", "f", "f", "f", "f", "_", "_"],
+  ],
+];
+
+// --- Leg variants (multi-frame for walking animation) ---
+// Each variant is an array of frames. Frame 0 = standing pose.
+export const LEGS: Pixel[][][] = [
+  [ // biped
+    ["_", "_", "f", "_", "_", "f", "_", "_", "_"],
+    ["_", "f", "_", "_", "_", "_", "f", "_", "_"],
+  ],
+  [ // outer (thin, alternating pairs)
+    ["_", "_", "l", "_", "_", "_", "_", "l", "_"],
+    ["_", "_", "_", "l", "_", "l", "_", "_", "_"],
+  ],
+  [ // tentacles (outer thick, inner stagger)
+    ["_", "f", "_", "l", "_", "l", "_", "f", "_"],
+    ["_", "f", "_", "f", "_", "l", "_", "f", "_"],
+    ["_", "f", "_", "l", "_", "f", "_", "f", "_"],
+  ],
+  [ // thin biped
+    ["_", "_", "l", "_", "_", "_", "l", "_", "_"],
+    ["_", "_", "_", "l", "_", "l", "_", "_", "_"],
+  ],
+  [ // wide stance
+    ["_", "f", "_", "_", "_", "_", "_", "f", "_"],
+    ["_", "_", "f", "_", "_", "_", "f", "_", "_"],
+  ],
+  [ // thin narrow
+    ["_", "_", "_", "l", "_", "l", "_", "_", "_"],
+    ["_", "_", "l", "_", "_", "_", "l", "_", "_"],
+  ],
+];
+
+// Fixed slot sizes for stable DNA encoding.
+// Adding new variants within these limits won't break existing DNA strings.
+// 12 * 12 * 24 * 8 * 8 * 12 * 12 = 15,925,248 (~16M, fits in 6 hex chars)
+export const SLOTS = {
+  eyes: 12,
+  mouths: 12,
+  hats: 24,
+  bodies: 8,
+  legs: 8,
+  hues: 12,
+};
+
+export interface DecodedDNA {
+  eyes: number;
+  mouth: number;
+  hat: number;
+  body: number;
+  legs: number;
+  faceHue: number; // 0-11 index -> multiply by 30 for degrees
+  hatHue: number; // 0-11 index -> multiply by 30 for degrees
+}
+
+/**
+ * Encode trait indices into a 7-character hex DNA string.
+ * Uses fixed slot sizes so adding traits doesn't break existing DNAs.
+ * Existing 6-char DNAs are decoded identically (leading zero is implicit).
+ */
+export function encodeDNA(traits: DecodedDNA): string {
+  let n = traits.hatHue;
+  n += traits.faceHue * SLOTS.hues;
+  n += traits.legs * SLOTS.hues * SLOTS.hues;
+  n += traits.body * SLOTS.legs * SLOTS.hues * SLOTS.hues;
+  n += traits.hat * SLOTS.bodies * SLOTS.legs * SLOTS.hues * SLOTS.hues;
+  n += traits.mouth * SLOTS.hats * SLOTS.bodies * SLOTS.legs * SLOTS.hues * SLOTS.hues;
+  n += traits.eyes * SLOTS.mouths * SLOTS.hats * SLOTS.bodies * SLOTS.legs * SLOTS.hues * SLOTS.hues;
+  return n.toString(16).padStart(7, "0");
+}
+
+/**
+ * Decode a hex DNA string (6-7 chars) into trait indices.
+ * Clamps to actual array lengths for forward compatibility.
+ */
+export function decodeDNA(hex: string): DecodedDNA {
+  let n = parseInt(hex, 16);
+  const hatHue = n % SLOTS.hues;
+  n = Math.floor(n / SLOTS.hues);
+  const faceHue = n % SLOTS.hues;
+  n = Math.floor(n / SLOTS.hues);
+  const legs = n % SLOTS.legs;
+  n = Math.floor(n / SLOTS.legs);
+  const body = n % SLOTS.bodies;
+  n = Math.floor(n / SLOTS.bodies);
+  const hat = n % SLOTS.hats;
+  n = Math.floor(n / SLOTS.hats);
+  const mouth = n % SLOTS.mouths;
+  n = Math.floor(n / SLOTS.mouths);
+  const eyes = n % SLOTS.eyes;
+  return {
+    eyes: eyes % EYES.length,
+    mouth: mouth % MOUTHS.length,
+    hat: hat % HATS.length,
+    body: body % BODIES.length,
+    legs: legs % LEGS.length,
+    faceHue: faceHue % SLOTS.hues,
+    hatHue: hatHue % SLOTS.hues,
+  };
+}
+
+/**
+ * Derive deterministic traits from a name string (hash-based fallback when no DNA is set).
+ */
+export function traitsFromName(name: string): DecodedDNA {
+  let hash = 0;
+  for (let i = 0; i < name.length; i++) {
+    hash = name.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  // Bit-mixing finalizer: spreads entropy across all 32 bits
+  // so even short strings produce varied upper-bit values (hues).
+  hash = Math.imul(hash ^ (hash >>> 16), 0x45d9f3b);
+  hash = Math.imul(hash ^ (hash >>> 13), 0x45d9f3b);
+  hash = hash ^ (hash >>> 16);
+  const h = Math.abs(hash);
+  return {
+    eyes:    h % EYES.length,
+    mouth:   (h >>> 4) % MOUTHS.length,
+    hat:     (h >>> 8) % HATS.length,
+    body:    (h >>> 14) % BODIES.length,
+    legs:    (h >>> 18) % LEGS.length,
+    faceHue: (h >>> 22) % 12,
+    hatHue:  (h >>> 26) % 12,
+  };
+}
+
+/**
+ * Generate a random valid DNA string.
+ */
+export function generateRandomDNA(): string {
+  return encodeDNA({
+    eyes: Math.floor(Math.random() * EYES.length),
+    mouth: Math.floor(Math.random() * MOUTHS.length),
+    hat: Math.floor(Math.random() * HATS.length),
+    body: Math.floor(Math.random() * BODIES.length),
+    legs: Math.floor(Math.random() * LEGS.length),
+    faceHue: Math.floor(Math.random() * SLOTS.hues),
+    hatHue: Math.floor(Math.random() * SLOTS.hues),
+  });
+}
+
+// --- Wave animation frames (override body when waving) ---
+export const WAVE_FRAMES: Pixel[][][] = [
+  [
+    // left up, right down
+    ["a", "f", "f", "f", "f", "f", "f", "f", "_"],
+    ["_", "f", "f", "f", "f", "f", "f", "f", "a"],
+  ],
+  [
+    // left down, right up
+    ["_", "f", "f", "f", "f", "f", "f", "f", "a"],
+    ["a", "f", "f", "f", "f", "f", "f", "f", "_"],
+  ],
+];
+
+// --- Talk animation frames (universal, override mouth when talking) ---
+// Cycle: agent's normal mouth (talkFrame=0) → open → repeat
+export const TALK_FRAMES: Pixel[][][] = [
+  [
+    // open mouth (full dark, no corners)
+    ["_", "f", "f", "f", "f", "f", "f", "f", "_"],
+    ["_", "f", "f", "d", "d", "d", "f", "f", "_"],
+  ],
+];
+
+/**
+ * Generate the pixel grid from decoded DNA traits.
+ * @param frame Walking animation frame index (0 = standing). Wraps automatically.
+ * @param talkFrame Talk animation frame (0 = normal mouth, 1+ = talk frames). Wraps automatically.
+ * @param waveFrame Wave animation frame (0 = normal body, 1+ = wave frames). Wraps automatically.
+ */
+export function generateGrid(traits: DecodedDNA, frame = 0, talkFrame = 0, waveFrame = 0): Pixel[][] {
+  const legFrames = LEGS[traits.legs];
+  const legRow = legFrames[frame % legFrames.length];
+  const mouthRows = talkFrame === 0
+    ? MOUTHS[traits.mouth]
+    : TALK_FRAMES[(talkFrame - 1) % TALK_FRAMES.length];
+  const bodyRows = waveFrame === 0
+    ? BODIES[traits.body]
+    : WAVE_FRAMES[(waveFrame - 1) % WAVE_FRAMES.length];
+  return [
+    ...HATS[traits.hat],
+    F,
+    EYES[traits.eyes],
+    ...mouthRows,
+    ...bodyRows,
+    legRow,
+  ];
+}
+
+/**
+ * Convert HSL to RGB. h in [0,360], s and l in [0,1]. Returns [r,g,b] each in [0,255].
+ */
+export function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+  const m = l - c / 2;
+  let r1: number, g1: number, b1: number;
+  if (h < 60) {
+    [r1, g1, b1] = [c, x, 0];
+  } else if (h < 120) {
+    [r1, g1, b1] = [x, c, 0];
+  } else if (h < 180) {
+    [r1, g1, b1] = [0, c, x];
+  } else if (h < 240) {
+    [r1, g1, b1] = [0, x, c];
+  } else if (h < 300) {
+    [r1, g1, b1] = [x, 0, c];
+  } else {
+    [r1, g1, b1] = [c, 0, x];
+  }
+  return [
+    Math.round((r1 + m) * 255),
+    Math.round((g1 + m) * 255),
+    Math.round((b1 + m) * 255),
+  ];
+}
+
+/**
+ * Render a DNA string as an SVG string with transparent background.
+ * Each pixel is rendered as a square rect. 1-cell padding around the grid.
+ */
+export function renderSVG(dna: string, pixelSize = 10, frame = 0, background: string | null = '#000'): string {
+  const traits = decodeDNA(dna);
+  const grid = generateGrid(traits, frame);
+
+  const faceHueDeg = traits.faceHue * 30;
+  const hatHueDeg = traits.hatHue * 30;
+
+  const faceRgb = hslToRgb(faceHueDeg, 0.5, 0.5);
+  const darkRgb = hslToRgb(faceHueDeg, 0.5, 0.28);
+  const hatRgb = hslToRgb(hatHueDeg, 0.5, 0.5);
+
+  const toHex = (r: number, g: number, b: number) =>
+    `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+
+  const faceHex = toHex(...faceRgb);
+  const darkHex = toHex(...darkRgb);
+  const hatHex = toHex(...hatRgb);
+
+  const cols = 9;
+  const rows = grid.length;
+  const pad = 1; // 1-cell padding
+  const w = (cols + pad * 2) * pixelSize;
+  const h = (rows + pad * 2) * pixelSize;
+
+  const half = Math.round(pixelSize / 2);
+  const quarter = Math.round(pixelSize / 4);
+  const rects: string[] = [];
+  for (let y = 0; y < rows; y++) {
+    for (let x = 0; x < cols; x++) {
+      const cell = grid[y][x];
+      const rx = (x + pad) * pixelSize;
+      const ry = (y + pad) * pixelSize;
+      if (cell === "f") {
+        rects.push(`<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${faceHex}"/>`);
+      } else if (cell === "l") {
+        rects.push(`<rect x="${rx}" y="${ry}" width="${half}" height="${pixelSize}" fill="${faceHex}"/>`);
+      } else if (cell === "a") {
+        rects.push(`<rect x="${rx}" y="${ry + half}" width="${pixelSize}" height="${half}" fill="${faceHex}"/>`);
+      } else if (cell === "e" || cell === "d") {
+        rects.push(`<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${darkHex}"/>`);
+      } else if (cell === "s") {
+        // Squint eye: face bg + dark bottom half
+        rects.push(`<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${faceHex}"/>`);
+        rects.push(`<rect x="${rx}" y="${ry + half}" width="${pixelSize}" height="${half}" fill="${darkHex}"/>`);
+      } else if (cell === "n") {
+        // Narrow eye: face bg + dark center half-width
+        rects.push(`<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${faceHex}"/>`);
+        rects.push(`<rect x="${rx + quarter}" y="${ry}" width="${half}" height="${pixelSize}" fill="${darkHex}"/>`);
+      } else if (cell === "m") {
+        // Thin mouth: face bg + dark top half
+        rects.push(`<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${faceHex}"/>`);
+        rects.push(`<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${half}" fill="${darkHex}"/>`);
+      } else if (cell === "q") {
+        // Corner left: face bg + dark bottom-right quarter
+        rects.push(`<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${faceHex}"/>`);
+        rects.push(`<rect x="${rx + half}" y="${ry + half}" width="${half}" height="${half}" fill="${darkHex}"/>`);
+      } else if (cell === "r") {
+        // Corner right: face bg + dark bottom-left quarter
+        rects.push(`<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${faceHex}"/>`);
+        rects.push(`<rect x="${rx}" y="${ry + half}" width="${half}" height="${half}" fill="${darkHex}"/>`);
+      } else if (cell === "h") {
+        rects.push(`<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${hatHex}"/>`);
+      } else if (cell === "k") {
+        rects.push(`<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${hatHex}"/>`);
+      }
+    }
+  }
+
+  const bg = background ? `<rect width="${w}" height="${h}" fill="${background}"/>\n` : '';
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}" shape-rendering="crispEdges">\n${bg}${rects.join("\n")}\n</svg>`;
+}
+
+/**
+ * Render a DNA string as ANSI colored pixel art for the terminal.
+ * Uses `██` per pixel (2 chars wide for square proportions).
+ */
+export function renderTerminal(dna: string, frame = 0): string {
+  const traits = decodeDNA(dna);
+  const grid = generateGrid(traits, frame);
+
+  const faceHueDeg = traits.faceHue * 30;
+  const hatHueDeg = traits.hatHue * 30;
+
+  const faceRgb = hslToRgb(faceHueDeg, 0.5, 0.5);
+  const darkRgb = hslToRgb(faceHueDeg, 0.5, 0.28);
+  const hatRgb = hslToRgb(hatHueDeg, 0.5, 0.5);
+
+  const faceAnsi = `\x1b[38;2;${faceRgb[0]};${faceRgb[1]};${faceRgb[2]}m`;
+  const darkAnsi = `\x1b[38;2;${darkRgb[0]};${darkRgb[1]};${darkRgb[2]}m`;
+  const hatAnsi = `\x1b[38;2;${hatRgb[0]};${hatRgb[1]};${hatRgb[2]}m`;
+  const reset = "\x1b[0m";
+
+  const faceBg = `\x1b[48;2;${faceRgb[0]};${faceRgb[1]};${faceRgb[2]}m`;
+
+  const lines: string[] = [];
+  for (const row of grid) {
+    let line = "";
+    for (const cell of row) {
+      if (cell === "_") {
+        line += "  ";
+      } else if (cell === "f") {
+        line += `${faceAnsi}██${reset}`;
+      } else if (cell === "l") {
+        line += `${faceAnsi}▌${reset} `;
+      } else if (cell === "e" || cell === "d") {
+        line += `${darkAnsi}██${reset}`;
+      } else if (cell === "s") {
+        line += `${darkAnsi}${faceBg}▄▄${reset}`;
+      } else if (cell === "n") {
+        line += `${darkAnsi}${faceBg}▐▌${reset}`;
+      } else if (cell === "m") {
+        line += `${darkAnsi}${faceBg}▀▀${reset}`;
+      } else if (cell === "q") {
+        line += `${darkAnsi}${faceBg} ▗${reset}`;
+      } else if (cell === "r") {
+        line += `${darkAnsi}${faceBg}▖ ${reset}`;
+      } else if (cell === "a") {
+        line += `${faceAnsi}▄▄${reset}`;
+      } else if (cell === "h") {
+        line += `${hatAnsi}██${reset}`;
+      } else if (cell === "k") {
+        line += `${hatAnsi}▐▌${reset}`;
+      }
+    }
+    lines.push(line);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Compact terminal renderer using half-block characters.
+ * Packs two pixel rows into one terminal line using ▀/▄ with fg/bg colors.
+ * Roughly half the height and width of renderTerminal.
+ */
+/**
+ * Render a DNA string as a layered SVG with separate groups for animated parts.
+ * Returns the SVG string, number of leg frames, and total row count.
+ * Used by framework components for CSS-only animation (no JS timers).
+ */
+export function renderLayeredSVG(dna: string, pixelSize = 10): {
+  svg: string;
+  legFrames: number;
+  rows: number;
+} {
+  const traits = decodeDNA(dna);
+
+  const faceHueDeg = traits.faceHue * 30;
+  const hatHueDeg = traits.hatHue * 30;
+
+  const faceRgb = hslToRgb(faceHueDeg, 0.5, 0.5);
+  const darkRgb = hslToRgb(faceHueDeg, 0.5, 0.28);
+  const hatRgb = hslToRgb(hatHueDeg, 0.5, 0.5);
+
+  const toHex = (r: number, g: number, b: number) =>
+    `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+
+  const faceHex = toHex(...faceRgb);
+  const darkHex = toHex(...darkRgb);
+  const hatHex = toHex(...hatRgb);
+
+  const half = Math.round(pixelSize / 2);
+  const quarter = Math.round(pixelSize / 4);
+  const cols = 9;
+
+  const hatRows = HATS[traits.hat];
+  const mouthNormal = MOUTHS[traits.mouth];
+  const mouthTalk = TALK_FRAMES[0];
+  const bodyNormal = BODIES[traits.body];
+  const waveF1 = WAVE_FRAMES[0];
+  const waveF2 = WAVE_FRAMES[1];
+  const legVariant = LEGS[traits.legs];
+  const legFrameCount = legVariant.length;
+
+  // hat + face + eyes + 2 mouth + 2 body + 1 legs
+  const totalRows = hatRows.length + 1 + 1 + 2 + 2 + 1;
+  const w = cols * pixelSize;
+  const h = totalRows * pixelSize;
+
+  function px(cell: Pixel, rx: number, ry: number): string {
+    if (cell === "_") return "";
+    if (cell === "f") return `<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${faceHex}"/>`;
+    if (cell === "l") return `<rect x="${rx}" y="${ry}" width="${half}" height="${pixelSize}" fill="${faceHex}"/>`;
+    if (cell === "a") return `<rect x="${rx}" y="${ry + half}" width="${pixelSize}" height="${half}" fill="${faceHex}"/>`;
+    if (cell === "e" || cell === "d") return `<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${darkHex}"/>`;
+    if (cell === "s") return `<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${faceHex}"/><rect x="${rx}" y="${ry + half}" width="${pixelSize}" height="${half}" fill="${darkHex}"/>`;
+    if (cell === "n") return `<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${faceHex}"/><rect x="${rx + quarter}" y="${ry}" width="${half}" height="${pixelSize}" fill="${darkHex}"/>`;
+    if (cell === "m") return `<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${faceHex}"/><rect x="${rx}" y="${ry}" width="${pixelSize}" height="${half}" fill="${darkHex}"/>`;
+    if (cell === "q") return `<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${faceHex}"/><rect x="${rx + half}" y="${ry + half}" width="${half}" height="${half}" fill="${darkHex}"/>`;
+    if (cell === "r") return `<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${faceHex}"/><rect x="${rx}" y="${ry + half}" width="${half}" height="${half}" fill="${darkHex}"/>`;
+    if (cell === "h" || cell === "k") return `<rect x="${rx}" y="${ry}" width="${pixelSize}" height="${pixelSize}" fill="${hatHex}"/>`;
+    return "";
+  }
+
+  function renderRows(rows: Pixel[][], startY: number): string {
+    let out = "";
+    for (let y = 0; y < rows.length; y++) {
+      for (let x = 0; x < cols; x++) {
+        out += px(rows[y][x], x * pixelSize, (startY + y) * pixelSize);
+      }
+    }
+    return out;
+  }
+
+  // Static rows: hat + face + eyes
+  const staticRects = renderRows([...hatRows, F, EYES[traits.eyes]], 0);
+
+  // Mouth starts after static rows
+  const mY = hatRows.length + 2;
+  const mouth0 = renderRows(mouthNormal, mY);
+  const mouth1 = renderRows(mouthTalk, mY);
+
+  // Body starts after mouth
+  const bY = mY + 2;
+  const body0 = renderRows(bodyNormal, bY);
+  const body1 = renderRows(waveF1, bY);
+  const body2 = renderRows(waveF2, bY);
+
+  // Legs start after body
+  const lY = bY + 2;
+  const legs0 = renderRows([legVariant[0]], lY);
+  const legs1 = legFrameCount > 1 ? renderRows([legVariant[1]], lY) : "";
+  const legs2 = legFrameCount > 2 ? renderRows([legVariant[2]], lY) : "";
+  const legs3 = legFrameCount > 3 ? renderRows([legVariant[3]], lY) : "";
+
+  const svg =
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}" shape-rendering="crispEdges">` +
+    `<g class="tg-bob">${staticRects}` +
+    `<g class="tg-mouth-0">${mouth0}</g>` +
+    `<g class="tg-mouth-1">${mouth1}</g>` +
+    `<g class="tg-body-0">${body0}</g>` +
+    `<g class="tg-body-1">${body1}</g>` +
+    `<g class="tg-body-2">${body2}</g>` +
+    `</g>` +
+    `<g class="tg-legs-0">${legs0}</g>` +
+    (legs1 ? `<g class="tg-legs-1">${legs1}</g>` : "") +
+    (legs2 ? `<g class="tg-legs-2">${legs2}</g>` : "") +
+    (legs3 ? `<g class="tg-legs-3">${legs3}</g>` : "") +
+    `</svg>`;
+
+  return { svg, legFrames: legFrameCount, rows: totalRows };
+}
+
+/**
+ * Shared CSS for layered SVG avatar animations.
+ * Inject once into the document head. Components use CSS classes
+ * (.idle, .walking, .talking, .waving, .walk-3f) on the wrapper div.
+ */
+export function getAvatarCSS(): string {
+  return `
+.tg-avatar .tg-mouth-1,
+.tg-avatar .tg-body-1,
+.tg-avatar .tg-body-2,
+.tg-avatar .tg-legs-1,
+.tg-avatar .tg-legs-2,
+.tg-avatar .tg-legs-3 { opacity: 0 }
+
+@keyframes tg-toggle {
+  0%, 49.99% { opacity: 1 }
+  50%, 100% { opacity: 0 }
+}
+@keyframes tg-toggle-3 {
+  0%, 33.32% { opacity: 1 }
+  33.33%, 100% { opacity: 0 }
+}
+@keyframes tg-toggle-4 {
+  0%, 24.99% { opacity: 1 }
+  25%, 100% { opacity: 0 }
+}
+@keyframes tg-idle-bob {
+  0%, 30%, 100% { transform: translateY(0) }
+  35%, 65% { transform: translateY(1px) }
+}
+
+.tg-avatar.idle .tg-bob {
+  animation: tg-idle-bob 3s steps(1) infinite;
+  animation-delay: var(--tg-idle-delay, 0s);
+}
+
+.tg-avatar.walking .tg-legs-0 { animation: tg-toggle 800ms steps(1) infinite }
+.tg-avatar.walking .tg-legs-1 { animation: tg-toggle 800ms steps(1) infinite; animation-delay: -400ms }
+.tg-avatar.walking.walk-3f .tg-legs-0 { animation: tg-toggle-3 1200ms steps(1) infinite }
+.tg-avatar.walking.walk-3f .tg-legs-1 { animation: tg-toggle-3 1200ms steps(1) infinite; animation-delay: -800ms }
+.tg-avatar.walking.walk-3f .tg-legs-2 { animation: tg-toggle-3 1200ms steps(1) infinite; animation-delay: -400ms }
+.tg-avatar.walking.walk-4f .tg-legs-0 { animation: tg-toggle-4 1200ms steps(1) infinite }
+.tg-avatar.walking.walk-4f .tg-legs-1 { animation: tg-toggle-4 1200ms steps(1) infinite; animation-delay: -900ms }
+.tg-avatar.walking.walk-4f .tg-legs-2 { animation: tg-toggle-4 1200ms steps(1) infinite; animation-delay: -600ms }
+.tg-avatar.walking.walk-4f .tg-legs-3 { animation: tg-toggle-4 1200ms steps(1) infinite; animation-delay: -300ms }
+
+.tg-avatar.talking .tg-mouth-0 { animation: tg-toggle 400ms steps(1) infinite }
+.tg-avatar.talking .tg-mouth-1 { animation: tg-toggle 400ms steps(1) infinite; animation-delay: -200ms }
+
+.tg-avatar.waving .tg-body-0 { opacity: 0 }
+.tg-avatar.waving .tg-body-1 { animation: tg-toggle 1200ms steps(1) infinite }
+.tg-avatar.waving .tg-body-2 { animation: tg-toggle 1200ms steps(1) infinite; animation-delay: -600ms }
+`;
+}
+
+export function renderTerminalSmall(dna: string, frame = 0): string {
+  const traits = decodeDNA(dna);
+  const grid = generateGrid(traits, frame);
+
+  const faceHueDeg = traits.faceHue * 30;
+  const hatHueDeg = traits.hatHue * 30;
+
+  const faceRgb = hslToRgb(faceHueDeg, 0.5, 0.5);
+  const darkRgb = hslToRgb(faceHueDeg, 0.5, 0.28);
+  const hatRgb = hslToRgb(hatHueDeg, 0.5, 0.5);
+
+  function cellRgb(cell: Pixel): [number, number, number] | null {
+    if (cell === "f" || cell === "l" || cell === "a" || cell === "q" || cell === "r") return faceRgb;
+    if (cell === "e" || cell === "s" || cell === "n" || cell === "d" || cell === "m") return darkRgb;
+    if (cell === "h" || cell === "k") return hatRgb;
+    return null; // transparent
+  }
+
+  const reset = "\x1b[0m";
+  const lines: string[] = [];
+
+  // Process two rows at a time using ▀ (upper half block)
+  for (let r = 0; r < grid.length; r += 2) {
+    const topRow = grid[r];
+    const botRow = r + 1 < grid.length ? grid[r + 1] : null;
+    let line = "";
+    for (let c = 0; c < topRow.length; c++) {
+      const top = cellRgb(topRow[c]);
+      const bot = botRow ? cellRgb(botRow[c]) : null;
+      if (top && bot) {
+        // ▀ with fg=top, bg=bot
+        line += `\x1b[38;2;${top[0]};${top[1]};${top[2]}m\x1b[48;2;${bot[0]};${bot[1]};${bot[2]}m▀${reset}`;
+      } else if (top) {
+        // ▀ with fg=top, no bg
+        line += `\x1b[38;2;${top[0]};${top[1]};${top[2]}m▀${reset}`;
+      } else if (bot) {
+        // ▄ with fg=bot, no bg
+        line += `\x1b[38;2;${bot[0]};${bot[1]};${bot[2]}m▄${reset}`;
+      } else {
+        line += " ";
+      }
+    }
+    lines.push(line);
+  }
+  return lines.join("\n");
+}

package/src/ink/Avatar.tsx

@@ -0,0 +1,129 @@
+import React, { useState, useEffect, useMemo, useRef } from 'react';
+import { Text, Box } from 'ink';
+import { decodeDNA, generateGrid, hslToRgb, traitsFromName } from '../index.js';
+import type { Pixel } from '../index.js';
+
+export interface AvatarProps {
+  dna?: string;
+  name?: string;
+  compact?: boolean;
+  walking?: boolean;
+  talking?: boolean;
+  waving?: boolean;
+}
+
+export function Avatar({ dna, name, compact = false, walking = false, talking = false, waving = false }: AvatarProps) {
+  const [walkFrame, setWalkFrame] = useState(0);
+  const [talkFrame, setTalkFrame] = useState(0);
+  const [waveFrame, setWaveFrame] = useState(0);
+
+  useEffect(() => {
+    if (!walking) { setWalkFrame(0); return; }
+    const id = setInterval(() => setWalkFrame(f => (f + 1) % 6), 400);
+    return () => clearInterval(id);
+  }, [walking]);
+
+  useEffect(() => {
+    if (!talking) { setTalkFrame(0); return; }
+    let timeout: ReturnType<typeof setTimeout>;
+    function tick() {
+      setTalkFrame(f => (f + 1) % 2);
+      timeout = setTimeout(tick, 100 + Math.random() * 200);
+    }
+    timeout = setTimeout(tick, 100 + Math.random() * 200);
+    return () => clearTimeout(timeout);
+  }, [talking]);
+
+  useEffect(() => {
+    if (!waving) { setWaveFrame(0); return; }
+    setWaveFrame(1);
+    const id = setInterval(() => setWaveFrame(f => f === 1 ? 2 : 1), 600);
+    return () => clearInterval(id);
+  }, [waving]);
+
+  const traits = useMemo(
+    () => dna ? decodeDNA(dna) : traitsFromName(name ?? 'agent'),
+    [dna, name]
+  );
+  const grid = useMemo(
+    () => generateGrid(traits, walkFrame, talkFrame, waveFrame),
+    [traits, walkFrame, talkFrame, waveFrame]
+  );
+
+  const faceHueDeg = traits.faceHue * 30;
+  const hatHueDeg = traits.hatHue * 30;
+  const faceRgb = hslToRgb(faceHueDeg, 0.5, 0.5);
+  const darkRgb = hslToRgb(faceHueDeg, 0.5, 0.28);
+  const hatRgb = hslToRgb(hatHueDeg, 0.5, 0.5);
+
+  const faceHex = rgbHex(faceRgb);
+  const darkHex = rgbHex(darkRgb);
+  const hatHex = rgbHex(hatRgb);
+
+  if (compact) {
+    // Half-block rendering: two rows per line using ▀/▄
+    const lines: React.ReactNode[] = [];
+    for (let r = 0; r < grid.length; r += 2) {
+      const topRow = grid[r];
+      const botRow = r + 1 < grid.length ? grid[r + 1] : null;
+      const spans: React.ReactNode[] = [];
+      for (let c = 0; c < topRow.length; c++) {
+        const top = cellHex(topRow[c], faceHex, darkHex, hatHex);
+        const bot = botRow ? cellHex(botRow[c], faceHex, darkHex, hatHex) : null;
+        if (top && bot) {
+          spans.push(<Text key={c} color={top} backgroundColor={bot}>▀</Text>);
+        } else if (top) {
+          spans.push(<Text key={c} color={top}>▀</Text>);
+        } else if (bot) {
+          spans.push(<Text key={c} color={bot}>▄</Text>);
+        } else {
+          spans.push(<Text key={c}> </Text>);
+        }
+      }
+      lines.push(<Box key={r}>{spans}</Box>);
+    }
+    return <Box flexDirection="column">{lines}</Box>;
+  }
+
+  // Full-size rendering: ██ per pixel
+  return (
+    <Box flexDirection="column">
+      {grid.map((row, y) => (
+        <Box key={y}>
+          {row.map((cell, x) => {
+            const ch = cellChar(cell, faceHex, darkHex, hatHex);
+            return ch;
+          }).map((node, x) => <React.Fragment key={x}>{node}</React.Fragment>)}
+        </Box>
+      ))}
+    </Box>
+  );
+}
+
+function rgbHex(rgb: [number, number, number]): string {
+  return `#${rgb[0].toString(16).padStart(2, '0')}${rgb[1].toString(16).padStart(2, '0')}${rgb[2].toString(16).padStart(2, '0')}`;
+}
+
+function cellHex(cell: Pixel, face: string, dark: string, hat: string): string | null {
+  if (cell === 'f' || cell === 'l' || cell === 'a' || cell === 'q' || cell === 'r' || cell === 'm') return face;
+  if (cell === 'e' || cell === 's' || cell === 'n' || cell === 'd') return dark;
+  if (cell === 'h' || cell === 'k') return hat;
+  return null;
+}
+
+function cellChar(cell: Pixel, face: string, dark: string, hat: string): React.ReactNode {
+  switch (cell) {
+    case 'f': return <Text color={face}>██</Text>;
+    case 'e': case 'd': return <Text color={dark}>██</Text>;
+    case 'h': return <Text color={hat}>██</Text>;
+    case 'k': return <Text color={hat}>▐▌</Text>;
+    case 'l': return <Text color={face}>▌ </Text>;
+    case 'a': return <Text color={face}>▄▄</Text>;
+    case 's': return <Text color={dark} backgroundColor={face}>▄▄</Text>;
+    case 'n': return <Text color={dark} backgroundColor={face}>▐▌</Text>;
+    case 'm': return <Text color={dark} backgroundColor={face}>▀▀</Text>;
+    case 'q': return <Text color={dark} backgroundColor={face}> ▗</Text>;
+    case 'r': return <Text color={dark} backgroundColor={face}>▖ </Text>;
+    default: return <Text>  </Text>;
+  }
+}

package/src/ink/index.ts

@@ -0,0 +1,2 @@
+export { Avatar } from './Avatar.js';
+export type { AvatarProps } from './Avatar.js';

package/src/react/Avatar.tsx

@@ -0,0 +1,57 @@
+import { useMemo, useRef } from 'react';
+import { encodeDNA, traitsFromName, renderLayeredSVG, getAvatarCSS } from '../index.js';
+
+export interface AvatarProps {
+  dna?: string;
+  name?: string;
+  size?: 'sm' | 'lg' | 'xl';
+  walking?: boolean;
+  talking?: boolean;
+  waving?: boolean;
+}
+
+let cssInjected = false;
+
+function injectCSS() {
+  if (cssInjected || typeof document === 'undefined') return;
+  cssInjected = true;
+  const style = document.createElement('style');
+  style.id = 'tg-avatar-css';
+  style.textContent = getAvatarCSS();
+  document.head.appendChild(style);
+}
+
+const PX_SIZES = { sm: 3, lg: 8, xl: 14 } as const;
+
+export function Avatar({ dna, name, size = 'lg', walking = false, talking = false, waving = false }: AvatarProps) {
+  injectCSS();
+  const idleDelay = useRef(Math.random() * 3);
+  const resolvedDna = useMemo(() => dna ?? encodeDNA(traitsFromName(name ?? 'agent')), [dna, name]);
+  const { svg, legFrames } = useMemo(() => renderLayeredSVG(resolvedDna, PX_SIZES[size]), [resolvedDna, size]);
+  const idle = !walking && !talking && !waving;
+
+  const cls = [
+    'tg-avatar',
+    idle && 'idle',
+    walking && 'walking',
+    talking && 'talking',
+    waving && 'waving',
+    legFrames === 3 && 'walk-3f',
+    legFrames === 4 && 'walk-4f',
+    size === 'sm' && 'tg-avatar-sm',
+  ].filter(Boolean).join(' ');
+
+  return (
+    <div
+      className={cls}
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        '--tg-idle-delay': `${idleDelay.current}s`,
+        ...(size === 'sm' ? { width: 27, height: 27, overflow: 'hidden' } : {}),
+      } as React.CSSProperties}
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  );
+}

package/src/react/index.ts

@@ -0,0 +1,2 @@
+export { Avatar } from './Avatar.js';
+export type { AvatarProps } from './Avatar.js';

package/src/svelte/Avatar.svelte

@@ -0,0 +1,52 @@
+<script lang="ts">
+  import { encodeDNA, traitsFromName, renderLayeredSVG, getAvatarCSS } from '../index.js';
+
+  interface Props {
+    dna?: string;
+    name?: string;
+    size?: 'sm' | 'lg' | 'xl';
+    walking?: boolean;
+    talking?: boolean;
+    waving?: boolean;
+  }
+
+  let { dna, name, size = 'lg', walking = false, talking = false, waving = false }: Props = $props();
+
+  const resolvedDna = $derived(dna ?? encodeDNA(traitsFromName(name ?? 'agent')));
+  const rendered = $derived(renderLayeredSVG(resolvedDna, size === 'xl' ? 14 : size === 'sm' ? 3 : 8));
+  const idle = $derived(!walking && !talking && !waving);
+  const idleDelay = Math.random() * 3;
+</script>
+
+<svelte:head>{@html `<style>${getAvatarCSS()}</style>`}</svelte:head>
+
+<div
+  class="tg-avatar"
+  class:idle
+  class:walking
+  class:talking
+  class:waving
+  class:walk-3f={rendered.legFrames === 3}
+  class:walk-4f={rendered.legFrames === 4}
+  class:sm={size === 'sm'}
+  style:--tg-idle-delay="{idleDelay}s"
+>
+  {@html rendered.svg}
+</div>
+
+<style>
+  .tg-avatar {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+  }
+  .tg-avatar.sm {
+    width: 27px;
+    height: 27px;
+    overflow: hidden;
+  }
+  .tg-avatar.sm :global(svg) {
+    width: 27px;
+    height: 27px;
+  }
+</style>

package/src/svelte/index.ts

@@ -0,0 +1 @@
+export { default as Avatar } from './Avatar.svelte';

package/src/vue/Avatar.vue

@@ -0,0 +1,74 @@
+<script setup lang="ts">
+import { computed, onMounted } from 'vue';
+import { encodeDNA, traitsFromName, renderLayeredSVG, getAvatarCSS } from '../index.js';
+
+const props = withDefaults(defineProps<{
+  dna?: string;
+  name?: string;
+  size?: 'sm' | 'lg' | 'xl';
+  walking?: boolean;
+  talking?: boolean;
+  waving?: boolean;
+}>(), {
+  size: 'lg',
+  walking: false,
+  talking: false,
+  waving: false,
+});
+
+const PX_SIZES = { sm: 3, lg: 8, xl: 14 } as const;
+
+let cssInjected = false;
+onMounted(() => {
+  if (cssInjected || typeof document === 'undefined') return;
+  cssInjected = true;
+  const style = document.createElement('style');
+  style.id = 'tg-avatar-css';
+  style.textContent = getAvatarCSS();
+  document.head.appendChild(style);
+});
+
+const idleDelay = Math.random() * 3;
+
+const resolvedDna = computed(() =>
+  props.dna ?? encodeDNA(traitsFromName(props.name ?? 'agent'))
+);
+const rendered = computed(() =>
+  renderLayeredSVG(resolvedDna.value, PX_SIZES[props.size])
+);
+const idle = computed(() => !props.walking && !props.talking && !props.waving);
+</script>
+
+<template>
+  <div
+    class="tg-avatar"
+    :class="{
+      idle: idle,
+      walking: props.walking,
+      talking: props.talking,
+      waving: props.waving,
+      'walk-3f': rendered.legFrames === 3,
+      'walk-4f': rendered.legFrames === 4,
+      'tg-avatar-sm': props.size === 'sm',
+    }"
+    :style="{ '--tg-idle-delay': `${idleDelay}s` }"
+    v-html="rendered.svg"
+  />
+</template>
+
+<style scoped>
+.tg-avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+.tg-avatar-sm {
+  width: 27px;
+  height: 27px;
+  overflow: hidden;
+}
+.tg-avatar-sm :deep(svg) {
+  width: 27px;
+  height: 27px;
+}
+</style>

package/src/vue/index.ts

@@ -0,0 +1 @@
+export { default as Avatar } from './Avatar.vue';