termlings 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,47 @@
+<p align="center">
+  <img src="banner.png" alt="termlings — Open-source pixel creatures for web and the terminal" width="800" />
+</p>
+
 # termlings
 
-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.
+Open-source pixel creatures for web and the terminal.
+
+<p align="center">
+  <img src="demo.gif" alt="Animated termlings walking, talking, and waving" />
+</p>
+
+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.
+
+## CLI
+
+No install required — just use `npx`:
+
+```bash
+# Render a DNA
+npx termlings 0a3f201
+
+# Render by name (deterministic)
+npx termlings my-agent
+
+# Random termling
+npx termlings
+
+# Animated (Ctrl+C to stop)
+npx termlings 0a3f201 --walk
+npx termlings 0a3f201 --talk --wave
+
+# Compact half-height mode
+npx termlings 0a3f201 --compact
+
+# Output SVG to stdout
+npx termlings 0a3f201 --svg > avatar.svg
+
+# SVG options
+npx termlings 0a3f201 --svg --size=20 --bg=#000 --padding=2
+
+# Animated SVG with CSS keyframes
+npx termlings 0a3f201 --svg --animated --walk --talk
+```
 
 ## Install
 
@@ -100,7 +141,52 @@ const grid = generateGrid(traits, walkFrame, talkFrame, waveFrame);
 <Avatar dna="0a3f201" waving />
 ```
 
-Props:
+### React
+
+```tsx
+import { Avatar } from 'termlings/react';
+
+function App() {
+  return (
+    <>
+      <Avatar dna="0a3f201" />
+      <Avatar name="my-agent" size="xl" />
+      <Avatar dna="0a3f201" walking />
+      <Avatar dna="0a3f201" talking />
+      <Avatar dna="0a3f201" waving />
+    </>
+  );
+}
+```
+
+### Vue
+
+```vue
+<script setup>
+  import { Avatar } from 'termlings/vue';
+</script>
+
+<template>
+  <Avatar dna="0a3f201" />
+  <Avatar name="my-agent" size="xl" />
+  <Avatar dna="0a3f201" walking />
+  <Avatar dna="0a3f201" talking />
+  <Avatar dna="0a3f201" waving />
+</template>
+```
+
+### Ink (terminal React)
+
+```tsx
+import { render } from 'ink';
+import { Avatar } from 'termlings/ink';
+
+render(<Avatar dna="0a3f201" />);
+render(<Avatar dna="0a3f201" compact />);
+render(<Avatar dna="0a3f201" walking />);
+```
+
+### Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -151,27 +237,14 @@ The avatar is a 9-column grid with variable height (depends on hat). Each cell i
 | `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
 
 ```
 termlings          — Core TypeScript (DNA, grid, SVG, terminal, colors)
-termlings/svelte   — Svelte 5 component (Avatar)
+termlings/svelte   — Svelte 5 component
+termlings/react    — React component
+termlings/vue      — Vue component
+termlings/ink      — Ink (terminal React) component
 ```
 
 ## License