seedmark
Dependency-free ESM library for small, deterministic SVG avatars. Give it opaque text; get a mask, strange creature, plant, orbital composition, landscape, geometric glyph, weave, or machine. No initials, fonts, external assets, or DOM required.
import { avatar, recipe, createRng, FAMILIES, VERSION } from './src/index.js';
const svg = avatar('any opaque seed — or a full Nostr pubkey', { size: 32 });
const visual = recipe('any opaque seed — or a full Nostr pubkey');
// visual.family, visual.palette, visual.layout, visual.silhouette,
// visual.features, visual.textureThe playground has a contact sheet, family filters, chat-size previews, square/circle crops, light/dark backgrounds, SVG export and shareable seeds. It does not change tinyrelay's current avatars.
API
avatar(seed, {size = 64, version = 1} = {})returns a standalone SVG string with a fixed0 0 64 64viewBox.sizemust be an integer from 1 through 4096; only root width/height change, never geometry. Designed for 24–48 px chat avatars.recipe(seed, {version = 1} = {})returns deeply frozen, plain JSON-serializable data. Palette is an array of four hex colors: background, light, warm/accent, cool/accent. Some compositions use fewer colors. Recipes never include the seed.createRng(seed, namespace = 'default')returns a fresh independent object withnext()in[0, 1),int(min, max)with inclusive safe-integer bounds and a safe span, andpick(nonemptyArray). Namespace must be a string. Helpers are noncryptographic and not intended for statistically exact sampling over enormous ranges.FAMILIESis a frozen, ordered array:masks,creatures,botanical,orbital,landscapes,glyphs,woven,machines.VERSIONis1. Unsupported versions and invalid sizes/ranges throwRangeError; nonstring seeds/namespaces throwTypeError.
All seeds must be primitive strings. Empty strings, Unicode, case, whitespace, embedded nulls, and arbitrarily long input are accepted as-is. There is no hex validation, trimming, Unicode normalization, or truncation. Runtime is linear in seed length.
Determinism and versioning
Version 1 length-frames the full JavaScript UTF-16 seed, version, and namespace into a four-word cyrb128-derived hash state, then uses sfc32. No randomness, clock, persistent shared state, or runtime-specific APIs are used. Same exact seed and namespace produce the same sequence regardless of calls or draws elsewhere.
The visual layers use separate public namespaces: family, layout, palette, silhouette, features, and texture. In v1, createRng(seed, 'family').pick(FAMILIES) reproduces family selection. Consuming texture draws cannot perturb palette, silhouette, or family selection. Geometry is pure recipe data rendered with bounded internal primitives, never seed interpolation. SVGs have no IDs, definitions, scripts, links, or external references, so inline grids do not collide.
Visual version covers hashing, stream usage, family ordering, palette choices, recipe interpretation, and rendering. Preserve v1 when adding future visual versions: do not silently change existing identities. The tests pin PRNG values, a complete recipe, and SVG hashes for all families. Package releases and visual versions are separate concepts.
Not cryptographic. Not an authentication, public-key verification, or fingerprint scheme. Different seeds can produce the same or similar avatar; a matching picture proves nothing about identity. Do not use secret seeds if their derived appearance would expose sensitive information. Sampled variety tests measure different geometry strings, not perceptual uniqueness.
Development
Requires Node.js 18+ for the native test runner; the library itself is browser-compatible ESM.
npm test
npm startNo installation or build step is needed. npm start uses the repository's separately supplied server.js playground; the distributed library includes only source, README, and license. Browser visual QA is separate from the dependency-free tests, which check deterministic streams, validation, SVG structure/safety, layer axes, fixtures, and sampled geometry variety.
MIT — Hermes contributors.