mode: how-to
Made by Anuna Research.
Turn an input string into a deterministic avatar: the same string and recipe version produce the same shape, colors, and traits. Changing its expression does not change its identity.
Six locally drawn silhouettes, nine silent presentation states, and a complete square LifeHash version2 fingerprint. Generation stays in the browser; no framework runtime is required.
Collect all 2²⁵⁶ of them!
What strings can I use?
The input string is called the seed. Use any valid Unicode string:
| Input | Example |
|---|
| A name | "alice" |
| A stable user or agent ID | "user:42" |
| An email address | "[email protected]" |
| A URL | "https://example.com/alice" |
| Emoji | "🌱" |
| Spaces or an empty string | " " or "" |
Case and spaces matter: "Alice", "alice", and "alice " produce different avatars. Nothing is trimmed, case-folded, or Unicode-normalized. To keep an avatar consistent, reuse the exact string and recipe version.
The SDK accepts primitive strings, including Unicode control characters such as NUL. It rejects numbers, objects, null, and malformed Unicode strings containing unpaired surrogates. Calling generateAvatar() or omitting the component's seed uses the empty string. The demo starts with researcher:42 when no URL seed is supplied.
<lifehash-avatar seed="user:42" state="idle" size="128"></lifehash-avatar>
For a shared link, pass the URL-encoded string as ?seed=, or use the demo's Copy avatar link button.
Example avatars
These avatars were generated by the library from the seeds shown below.
| Pebble | Droplet | Capsule | Bloom | Comet |
|---|
| | | | |
example:6 | example:10 | example:5 | example:1 | example:0 |
Sprout
Sprout adds an egg silhouette to the original five shapes.
The first and only recipe is kawaii-lifehash-v5. It selects from pebble, droplet, capsule, bloom, comet, and egg, with a soft coat by default.
Coat textures
The default kawaii-lifehash-v5 recipe uses a soft coat, between smooth and fluffy. Smooth, fluffy, and shaggy remain available as presentation overrides. It uses the six-shape family and the same LifeHash fingerprint. Smooth coats have a subtle soft edge rather than a perfectly clean outline. Texture becomes subtler at small sizes.
| Smooth | Soft (default) | Fluffy | Shaggy |
|---|
| | | |
These examples use example:0, the pebble silhouette, and a presentation override to compare coats on the same identity.
const identity = await generateAvatar('example:0', {
recipe: 'kawaii-lifehash-v5',
});
const svg = avatarSVG(identity, { coat: 'fluffy' });
<lifehash-avatar seed="example:0" recipe="kawaii-lifehash-v5"
state="idle" size="256"></lifehash-avatar>
Expressions
The same avatar (seed="example:6") in each presentation state. Expressions change while its identity and LifeHash coat stay the same.
Set the expression with the component's state attribute:
<lifehash-avatar seed="example:6" state="success" size="256"></lifehash-avatar>
Run the local demo
The demo focuses on identity and activity: change the seed, select an expression, compare the same companion at 24–256 px, and copy the component markup. The visible status label explains each expression. Names are carried in data-name; the component includes the name and activity in its accessible label and uses the name when exporting SVG.
The audio prototype is preserved under experiments/audio/ and in the optional source modules. Its interface and local speech endpoint are not part of the active demo. Archived tests are historical snapshots, not part of the current test suite.
npm ci
npm run dev
Open the local URL printed by Vite. Type a seed, change the mood, and download the neutral SVG. Build the separate static demo with npm run build:demo; its relative assets support hosting beneath a nested path.
Open an avatar by URL
Pass a string as the seed query parameter to prefill the input and render its avatar:
Render researcher:42
const url = new URL('https://kawaii-lifehash.anuna.io/');
url.searchParams.set('seed', 'hello world 😀');
An omitted parameter uses the demo's default seed. ?seed= uses the empty string. URL encoding preserves spaces, emoji, and punctuation; encode a literal plus as %2B. You can still edit the seed and change expressions after opening the link. Use Copy avatar link to update the URL with your current input and copy it to the clipboard.
Install the local archive
npm run pack:local
npm install /absolute/path/to/artifacts/kawaii-lifehash-0.1.0.tgz
Generate and export in a secure-context browser with Canvas, Web Crypto and WebAssembly:
import { generateAvatar, avatarSVG } from 'kawaii-lifehash';
const identity = await generateAvatar('researcher:42');
const svg = avatarSVG(identity, { size: 256, label: 'Research companion' });
The root imports safely during SSR and does not register an element. Generation is browser-only. The bundled WASM initializes automatically, without fetches or manual asset copying. identity.fingerprint.dataURI displays the complete 32×32 square; use image-rendering: pixelated when enlarging it. Its pixels match the licensed LifeHash reference engine.
Web Component SDK example
The live demo includes highlighted HTML and JavaScript examples. Its markup updates as you change the seed or expression.
After installing the local package, import the component and styles once in your browser app:
import 'kawaii-lifehash/component';
import 'kawaii-lifehash/styles.css';
Then add the component to your HTML:
<lifehash-avatar seed="researcher:42" data-name="Momo"
state="curious" size="128"></lifehash-avatar>
The avatar generates and displays itself automatically. Change seed to generate another identity, or state to change its expression. The default uses the six-shape family and soft coat.
Display name (data-name)
data-name is an optional display-name attribute supplied by your application. It is used in the component's accessible label (for example, “Momo, Exploring”) and as the default label/title in exportSVG(). It does not render visible text inside the avatar; display it alongside the component when needed.
const agent = document.querySelector('lifehash-avatar');
console.log(agent.dataset.name); // 'Momo'
agent.dataset.name = 'Pip'; // Updates the accessible label and future exports.
document.querySelector('#agent-name').textContent = agent.dataset.name;
Changing data-name leaves the seed, appearance, digest and identity.name unchanged. It is not automatically regenerated when the seed changes; the demo generates kawaii names separately and assigns this attribute. If omitted, the component falls back to identity.name. An explicit aria-label overrides the accessible name portion, and exportSVG({label: 'Custom label'}) overrides the export label.
State values: idle, thinking, speaking, listening, success, error, sleepy, curious, confused. Speaking is silent. Reduced motion disables decorative animation and pointer response. Set aria-hidden="true" for decorative instances. The accessible label combines aria-label, data-name, or the default character name (in that order) with the current activity.
identity is the last successfully resolved immutable identity. status is pending, resolved, or failed. ready represents the current generation; a new seed or disconnection rejects the earlier promise. identity-resolved carries the identity; generation-error carries {kind, error}, where kind distinguishes input from initialization. Invalid attributes or properties emit an input error and retain the last valid values. There is no unhandled rejection from declarative markup alone.
Connect a companion to actual work
Use seed for stable identity, data-name for the display name, and state for activity. State changes preserve the identity and neutral SVG export. STATE_LABELS from kawaii-lifehash/component supplies readable activity labels; show a visible label alongside the face. The component also updates its SVG accessible name as the state changes. An explicit aria-label overrides the name portion; activity is still included.
const agent = document.querySelector('lifehash-avatar');
async function runWithAgent(task) {
agent.state = 'thinking';
try {
const result = await task();
agent.state = 'success';
return result;
} catch (error) {
agent.state = 'error';
throw error;
}
}
Use listening when waiting for user input and confused when clarification is required. Expressions are presentation; the host application decides when work starts, finishes, or fails.
Input and rendering rules
See What strings can I use? for seed examples and exact input behavior. Invalid seed arguments passed to generateAvatar() reject with a TypeError; invalid component inputs emit generation-error and retain the last valid value.
SVG options accept only size (positive finite pixels), label (scalar string), coat (smooth, soft, fluffy, shaggy), and shape (pebble, droplet, capsule, bloom, comet, egg). Invalid options throw TypeError or RangeError. XML-forbidden control characters in labels serialize as U+FFFD; seed hashing is unaffected. Native aria-label retains browser semantics; ill-formed UTF-16 is replaced only in the rendered text alternative.
Identity traits derive from the SHA-256 digest; moods and pointer position do not affect identity or neutral export. Static SVG is byte-stable for identical identity/options and browser engine/version. Fingerprint data URIs are canonical SVG images built from the RGBA pixels, and the renderer rejects mismatched image/pixel data. Externally supplied identity records are syntax-checked; the package does not claim that an untrusted caller's pixels prove a digest. Use generateAvatar for authentic identities. Cropped artwork is not an authentication fingerprint.
Verify and review
npx playwright install chromium firefox webkit
npm test
npm run typecheck
node scripts/mutation.mjs
node scripts/consumer.mjs
npm test builds an independent C++ reference oracle using a C++17 compiler, then runs Chromium, Firefox and WebKit acceptance tests.
Inspired by the idea of expressive agent avatars in Kawaii-Dots by Jérôme Massot. The implementation is authored locally; its shapes and expressions were informed by the owner's authorized hosted visual reference. Attribution-only reference: https://github.com/jeromemassot/Kawaii-Dots. LifeHash is by Wolf McNally, Christopher Allen and Blockchain Commons. Full dependency licenses and pinned sources accompany NOTICE.md.
License
Repository-authored code and assets are licensed under Apache License 2.0. Third-party dependencies retain their own licenses; see NOTICE.md and the included dependency license files.
