solfaces 2.1.2 → 2.3.0

package/README.md

@@ -21,10 +21,10 @@ Built for dApps, AI agents, social features, leaderboards, and anywhere a wallet
 
 ## Why SolFaces?
 
-- **Deterministic** — Same wallet always produces the same avatar. No database needed.
+- **Deterministic** — Same wallet address always produces a unique avatar and name. No database needed.
 - **Zero dependencies** — Core engine has no runtime dependencies.
-- **~2.56B unique faces** — 11 traits with expanded ranges = massive combination space.
-- **SolNames** — Every wallet gets a deterministic, human-friendly name derived via SHA-256 (e.g. "SunnyIcon"). ~1M display names, ~65.5B unique tags.
+- **~53M unique avatars** — 10 visual traits deterministically sampled = massive combination space.
+- **SolNames** — Every wallet gets a deterministic, human-friendly name derived via SHA-256 (e.g. "Sunny Icon"). ~1M display names, ~65.5B unique tags.
 - **11 built-in themes** — Default, Dark, Light, Mono, Flat, Transparent, plus 3 Pixel and 2 Glass themes (React).
 - **Gradient-rich rendering** — Skin-luminance-driven colors, specular highlights, cheek blush, gradient hair, glow overlays.
 - **Works everywhere** — React, vanilla JS, Node, Python, CDN script tag, edge functions.
@@ -123,13 +123,13 @@ mountSolFace("#avatar", "7xKXqR...", { size: 48 });
 import { deriveName, deriveIdentity } from "solfaces";
 
 deriveName("7xKXqR...");
-// → "SunnyIcon" (deterministic, SHA-256 derived)
+// → "Sunny Icon" (deterministic, SHA-256 derived)
 
 deriveName("7xKXqR...", "tag");
-// → "SunnyIcon#2f95" (unique identifier)
+// → "Sunny Icon#2f95" (unique identifier)
 
 deriveName("7xKXqR...", "full");
-// → "SunnyIcon-InfiniteOre" (formal contexts)
+// → "Sunny Icon-Infinite Ore" (formal contexts)
 
 const id = deriveIdentity("7xKXqR...");
 // → { short, name, tag, full, adjective, noun, hash, discriminator }
@@ -170,8 +170,8 @@ SHA-256("solnames-v1:" + wallet) → 32 bytes
         ├─→ Bytes 0-3: seed PRNG → adjective + noun
         └─→ Bytes 8-9: hex discriminator → "2f95"
 
-Display:  WavingMistral
-Tag:      WavingMistral#2f95
+Display:  Waving Mistral
+Tag:      Waving Mistral#2f95
 ```
 
 ### Name Formats
@@ -179,9 +179,9 @@ Tag:      WavingMistral#2f95
 | Format  | Example                      | Unique Names | Use Case                    |
 |---------|------------------------------|-------------|-----------------------------|
 | short   | "Waving"                     | 1,000       | Tight UIs, badges           |
-| display | "WavingMistral"              | ~1,000,000  | Default — profiles, feeds   |
-| tag     | "WavingMistral#2f95"         | ~65.5B      | Unique identifier           |
-| full    | "WavingMistral-InfiniteOre"  | ~1T         | Formal contexts             |
+| display | "Waving Mistral"             | ~1,000,000  | Default — profiles, feeds   |
+| tag     | "Waving Mistral#2f95"        | ~65.5B      | Unique identifier           |
+| full    | "Waving Mistral-Infinite Ore" | ~1T        | Formal contexts             |
 
 ### Usage
 
@@ -189,10 +189,10 @@ Tag:      WavingMistral#2f95
 import { deriveName, deriveIdentity } from "solfaces";
 // or: import { deriveName } from "solfaces/names";
 
-deriveName("7xKXqR...");           // → "SunnyIcon" (display format)
+deriveName("7xKXqR...");           // → "Sunny Icon" (display format)
 deriveName("7xKXqR...", "short");  // → "Sunny"
-deriveName("7xKXqR...", "tag");    // → "SunnyIcon#2f95"
-deriveName("7xKXqR...", "full");   // → "SunnyIcon-InfiniteOre"
+deriveName("7xKXqR...", "tag");    // → "Sunny Icon#2f95"
+deriveName("7xKXqR...", "full");   // → "Sunny Icon-Infinite Ore"
 
 const id = deriveIdentity("7xKXqR...");
 // → { short, name, tag, full, adjective, noun, hash, discriminator }
@@ -224,9 +224,9 @@ import { SolFace } from "solfaces/react";
 ```ts
 import { isValidSolName, parseSolName } from "solfaces/names";
 
-isValidSolName("SunnyIcon");         // true
-isValidSolName("SunnyIcon#2f95");    // true
-parseSolName("SunnyIcon#2f95");
+isValidSolName("Sunny Icon");         // true
+isValidSolName("Sunny Icon#2f95");    // true
+parseSolName("Sunny Icon#2f95");
 // → { adjective: "Sunny", noun: "Icon", discriminator: "2f95" }
 ```
 
@@ -243,6 +243,7 @@ const opts: DeriveOptions = {
   nouns: ["Tiger", "Eagle", "Bear", "Wolf", "Hawk"],
   domain: "my-app-v1",                  // Custom domain prefix (default: "solnames-v1")
   blockedCombos: new Set(["BoldBear"]), // Custom blocked pairs
+  separator: "-",                       // Custom separator (default: " ")
 };
 
 deriveName("7xKXqR...", "display", opts);   // Uses custom word lists
@@ -251,6 +252,24 @@ deriveIdentity("7xKXqR...", opts);          // Full identity with custom lists
 
 All fields are optional — omit any to use the built-in defaults.
 
+### Custom Separator
+
+Names default to space-separated (`"Fierce Sortie"`). Customize with the `separator` option:
+
+```ts
+deriveName("7xKXqR...");                                    // "Fierce Sortie" (default)
+deriveName("7xKXqR...", "display", { separator: "" });      // "FierceSortie" (legacy PascalCase)
+deriveName("7xKXqR...", "display", { separator: "-" });     // "Fierce-Sortie" (hyphenated)
+deriveName("7xKXqR...", "display", { separator: "_" });     // "Fierce_Sortie" (underscored)
+```
+
+The separator applies to all formats — display, tag, and full:
+
+```ts
+deriveName("7xKXqR...", "tag", { separator: "-" });   // "Fierce-Sortie#be71"
+deriveName("7xKXqR...", "full", { separator: "-" });   // "Fierce-Sortie-Cherry-Pegasus"
+```
+
 - **1000 adjectives + 1000 nouns** — curated positive/neutral PascalCase words (customizable via `DeriveOptions`)
 - **Same name everywhere** — TypeScript, Python, CDN, and server all produce identical output
 - **Blocked combinations** — offensive adjective+noun pairs are automatically skipped (customizable via `DeriveOptions`)
@@ -318,7 +337,13 @@ import { glassTheme, glassDarkTheme } from "solfaces/themes";
 
 ## AI Agent Identity
 
-AI trading bots, autonomous agents, and on-chain programs are becoming users — they need a visual identity, a personality, and a recognizable presence. SolFaces gives every agent a deterministic face tied to their wallet, plus natural language self-descriptions they can use in system prompts to know and reference what they look like.
+Any Solana trading bot or autonomous agent just needs its wallet address and it instantly gets:
+
+- **A face** — unique, deterministic SVG avatar (~53M unique combinations)
+- **A name** — `"Fierce Sortie"`, `"Waving Mistral"`, etc. — like a real first/last name
+- **Self-awareness** — a first-person description it can use in its system prompt to know what it looks like and introduce itself
+
+No registration, no storage, no API calls. Just math from the wallet address. Every bot on Solana can have a recognizable identity that's consistent everywhere — on-chain, in Discord, Telegram, dashboards, leaderboards.
 
 ### System Prompt Integration
 
@@ -328,8 +353,8 @@ import { agentAppearancePrompt } from "solfaces";
 const appearance = agentAppearancePrompt("7xKXqR...", "Atlas");
 // → "My visual identity is a SolFace avatar (ID: a3f2b1c0) derived from
 //    my wallet address. I'm Atlas. I have a squircle face with warm golden skin,
-//    almond-shaped hazel eyes with gently curved eyebrows, and flowing
-//    auburn wavy hair. I'm wearing aviator sunglasses. I have a playful grin.
+//    almond-shaped hazel eyes, natural eyebrows, and am bald.
+//    I'm wearing aviator sunglasses. I have a playful grin.
 //    This appearance is deterministic — anyone who looks up my wallet will
 //    see the same face."
 
@@ -629,7 +654,7 @@ const result = await handleToolCall("generate_solface_svg", {
   "mcpServers": {
     "solfaces": {
       "command": "npx",
-      "args": ["-y", "solfaces"]
+      "args": ["-y", "solfaces-mcp"]
     }
   }
 }
@@ -736,7 +761,7 @@ For sites without a build step — Webflow, Notion embeds, plain HTML, WordPress
 | `traitHash(wallet)` | `string` | 8-char hex hash |
 | `resolveTheme(name?, themes?)` | `SolFaceTheme \| undefined` | Look up theme by name from a map |
 | `mergeTheme(base, overrides)` | `SolFaceTheme` | Merge two themes |
-| `effectiveAccessory(traits)` | `number` | Accessory index (earring suppressed for long/bob hair) |
+| `effectiveAccessory(traits)` | `number` | Resolved accessory index (0–11) |
 | `renderSolFaceSVG(wallet, options?)` | `string` | Raw SVG markup |
 | `renderSolFaceDataURI(wallet, options?)` | `string` | Data URI for `<img>` tags |
 | `renderSolFaceBase64(wallet, options?)` | `string` | Base64 data URI |
@@ -843,19 +868,20 @@ Available keys: `skin`, `eyes`, `hair`, `bg`, `mouth`, `eyebrow`, `accessory`, `
 
 | Trait | Variants | Options |
 |-------|----------|---------|
-| Face Shape | 4 | Squircle (all — preserved for PRNG ordering) |
 | Skin Color | 10 | Porcelain, Ivory, Fair, Light, Sand, Golden, Warm, Caramel, Brown, Deep |
-| Eye Style | 8 | Round, Minimal, Almond, Wide, Relaxed, Joyful, Bright, Gentle |
-| Eye Color | 5 | Chocolate, Sky, Emerald, Hazel, Storm |
-| Eyebrows | 5 | Wispy, Straight, Natural, Arched, Angled |
-| Nose | 4 | Shadow, Button, Soft, Nostrils |
+| Eye Style | 9 | Round, Minimal, Almond, Wide, Relaxed, Joyful, Bright, Gentle, Side-look |
+| Eye Color | 8 | Chocolate, Sky, Emerald, Hazel, Storm, Amber, Violet, Gray |
+| Eyebrows | 8 | Wispy, Straight, Natural, Arched, Angled, Worried, Bushy, Thin |
+| Nose | 8 | Shadow, Button, Soft, Nostrils, Pointed, Wide, Bridge, Snub |
 | Mouth | 8 | Smile, Calm, Happy, Oh, Smirk, Grin, Flat, Pout |
-| Hair Style | 10 | Bald, Short, Curly, Side Sweep, Puff, Long, Bob, Buzz, Wavy, Topknot |
-| Hair Color | 10 | Black, Espresso, Walnut, Honey, Copper, Silver, Charcoal, Burgundy, Strawberry, Ginger |
-| Accessory | 10 | None, Beauty Mark, Round Glasses, Rect Glasses, Earring, Headband, Freckles, Stud Earrings, Aviators, Band-Aid |
-| Background | 10 | Rose, Olive, Sage, Fern, Mint, Ocean, Sky, Lavender, Orchid, Blush |
+| Hair Style | 10 | Sampled for PRNG ordering; all render as bald |
+| Hair Color | 10 | Sampled for PRNG ordering; used for headband color derivation |
+| Accessory | 12 | None, Beauty Mark, Round Glasses, Rect Glasses, Earring, Headband, Freckles, Stud Earrings, Aviators, Band-Aid, Left Eyebrow Slit, Right Eyebrow Slit |
+| Background | 12 | Rose, Olive, Sage, Fern, Mint, Ocean, Sky, Lavender, Orchid, Blush, Lilac, Seafoam |
+
+**Unique visual combinations: ~53,084,160**
 
-**Total unique combinations: ~2,560,000,000**
+> 10 skin × 9 eyes × 8 eye colors × 8 brows × 8 noses × 8 mouths × 12 accessories × 12 backgrounds ≈ 53M. Hair style and hair color are sampled for PRNG determinism but don't produce visible output (all render bald).
 
 Algorithm: **djb2 hash** → **mulberry32 PRNG** → sequential trait sampling. Sub-millisecond. Deterministic across JS and Python.
 
@@ -895,7 +921,7 @@ solfaces/
 │   ├── agent/
 │   │   ├── tools.ts        # 6 canonical tool definitions + handlers
 │   │   ├── index.ts        # Format adapters (MCP, OpenAI, Anthropic, Vercel AI)
-│   │   └── mcp-server.ts   # Standalone MCP server (npx solfaces)
+│   │   └── mcp-server.ts   # Standalone MCP server (npx solfaces-mcp)
 │   ├── cdn.ts              # IIFE bundle for <script> tag
 │   ├── api-templates.ts    # Copy-paste route handlers
 │   └── index.ts
@@ -908,7 +934,7 @@ solfaces/
 ### Key Design Decisions
 
 - **`colors.ts` is the single source of truth** for all color math. Both `renderer.ts` and `SolFace.tsx` import from it, preventing renderer drift.
-- **`effectiveAccessory()`** handles earring suppression: long and bob hairstyles suppress earring accessories.
+- **`effectiveAccessory()`** resolves the final accessory index (0–11) from the trait set.
 - **`_` prefix** on theme fields marks React-only features (pixel, glass). The string renderer ignores these.
 - **Detail levels** are resolved at render time: `"auto"` → full if size >= 48, simplified otherwise.
 
@@ -918,7 +944,7 @@ solfaces/
 
 v2.0.0 is a breaking release:
 
-- **All faces change.** Trait ranges expanded (skin 6→10, mouth 6→8, hair 8→10, accessories 6→10, bg 5→10), so every wallet generates a different face than in v1.
+- **All faces change.** Trait ranges expanded (skin 6→10, mouth 6→8, hair 10, accessories 6→12, bg 5→12, eyes 8→9), so every wallet generates a different face than in v1. Hair is sampled but no longer rendered (all faces are bald).
 - **Old themes removed.** `solana`, `neon`, `jupiter`, `phantom`, `circle` themes are gone. Use `dark`, `light`, `mono`, `flat`, `transparent`, or the new `glass`/`pixel` themes.
 - **New rendering engine.** Gradient-rich rendering with skin-luminance-driven colors, ears, hair-back layers, and face overlays.
 - **New theme fields.** `flat`, `cheekEnabled`, `shadowEnabled`, `glowIntensity`, and React-only `_glass*`/`_pixel*` fields.

package/SKILL.md

@@ -5,7 +5,7 @@ description: Generates deterministic avatars and names for Solana wallet address
 
 # SolFaces
 
-Deterministic avatar and name generator for Solana wallets. Every wallet address produces a unique, consistent face and name. ~2.56B unique faces, ~1M display names (~65.5B unique tags). Zero dependencies, sub-millisecond, works everywhere.
+Deterministic avatar and name generator for Solana wallets. Every wallet address produces a unique, consistent face and name. ~53M unique avatars, ~1M display names (~65.5B unique tags). Zero dependencies, sub-millisecond, works everywhere.
 
 ---
 
@@ -130,8 +130,8 @@ const svg = renderSolFaceSVG("7xKXtg...", { size: 256 });
 ### Name derivation
 ```ts
 import { deriveName, deriveIdentity } from "solfaces";
-deriveName("7xKXtg...");           // "SunnyIcon"
-deriveName("7xKXtg...", "tag");    // "SunnyIcon#2f95"
+deriveName("7xKXtg...");           // "Sunny Icon"
+deriveName("7xKXtg...", "tag");    // "Sunny Icon#2f95"
 const id = deriveIdentity("7xKXtg...");  // full identity object
 ```
 
@@ -177,9 +177,8 @@ For comprehensive documentation on specific topics:
 ## Key Facts
 
 - **Deterministic**: Same wallet = same face + same name. djb2 + mulberry32 PRNG (traits), SHA-256 + mulberry32 PRNG (names).
-- **11 traits**: Face shape (4), skin (10), eye style (8), eye color (5), eyebrows (5), nose (4), mouth (8), hair style (10), hair color (10), accessory (10), background (10) = ~2.56B unique faces.
+- **10 visual traits**: Skin (10), eye style (9), eye color (8), eyebrows (8), nose (8), mouth (8), hair style (10), hair color (10), accessory (12), background (12) = ~53M unique avatars. Hair style and color are sampled for PRNG ordering but all render as bald. (faceShape field exists for PRNG ordering but all faces render as squircle.)
 - **SolNames**: 1000 adjectives + 1000 nouns, SHA-256 derived. Formats: short, display (~1M), tag (~65.5B), full (~1T). Custom word lists supported via `DeriveOptions`.
-- **Earring suppression**: Long and bob hairstyles suppress earring accessories.
 - **Cross-language parity**: JS and Python produce identical output.
 - **Zero dependencies**: Core engine has no runtime deps.
 - **SVG viewBox**: All avatars use 64x64 viewBox, scaled by `size`.

package/dist/agent/index.cjs

@@ -1,52 +1,51 @@
 'use strict';
 
-var chunk4YFZ4W2Y_cjs = require('../chunk-4YFZ4W2Y.cjs');
-require('../chunk-TYTBYDQU.cjs');
-require('../chunk-F54WHRCE.cjs');
-require('../chunk-6QRDULAO.cjs');
-require('../chunk-XXJJH56O.cjs');
+var chunkBI3GHRKQ_cjs = require('../chunk-BI3GHRKQ.cjs');
+require('../chunk-W2U6ITMR.cjs');
+require('../chunk-PCSRDAWQ.cjs');
+require('../chunk-YGD7EQEX.cjs');
 
 
 
 Object.defineProperty(exports, "SOLFACE_TOOLS", {
   enumerable: true,
-  get: function () { return chunk4YFZ4W2Y_cjs.SOLFACE_TOOLS; }
+  get: function () { return chunkBI3GHRKQ_cjs.SOLFACE_TOOLS; }
 });
 Object.defineProperty(exports, "allToolsAnthropic", {
   enumerable: true,
-  get: function () { return chunk4YFZ4W2Y_cjs.allToolsAnthropic; }
+  get: function () { return chunkBI3GHRKQ_cjs.allToolsAnthropic; }
 });
 Object.defineProperty(exports, "allToolsMCP", {
   enumerable: true,
-  get: function () { return chunk4YFZ4W2Y_cjs.allToolsMCP; }
+  get: function () { return chunkBI3GHRKQ_cjs.allToolsMCP; }
 });
 Object.defineProperty(exports, "allToolsOpenAI", {
   enumerable: true,
-  get: function () { return chunk4YFZ4W2Y_cjs.allToolsOpenAI; }
+  get: function () { return chunkBI3GHRKQ_cjs.allToolsOpenAI; }
 });
 Object.defineProperty(exports, "allToolsVercelAI", {
   enumerable: true,
-  get: function () { return chunk4YFZ4W2Y_cjs.allToolsVercelAI; }
+  get: function () { return chunkBI3GHRKQ_cjs.allToolsVercelAI; }
 });
 Object.defineProperty(exports, "handleToolCall", {
   enumerable: true,
-  get: function () { return chunk4YFZ4W2Y_cjs.handleToolCall; }
+  get: function () { return chunkBI3GHRKQ_cjs.handleToolCall; }
 });
 Object.defineProperty(exports, "toAnthropic", {
   enumerable: true,
-  get: function () { return chunk4YFZ4W2Y_cjs.toAnthropic; }
+  get: function () { return chunkBI3GHRKQ_cjs.toAnthropic; }
 });
 Object.defineProperty(exports, "toMCP", {
   enumerable: true,
-  get: function () { return chunk4YFZ4W2Y_cjs.toMCP; }
+  get: function () { return chunkBI3GHRKQ_cjs.toMCP; }
 });
 Object.defineProperty(exports, "toOpenAI", {
   enumerable: true,
-  get: function () { return chunk4YFZ4W2Y_cjs.toOpenAI; }
+  get: function () { return chunkBI3GHRKQ_cjs.toOpenAI; }
 });
 Object.defineProperty(exports, "toVercelAI", {
   enumerable: true,
-  get: function () { return chunk4YFZ4W2Y_cjs.toVercelAI; }
+  get: function () { return chunkBI3GHRKQ_cjs.toVercelAI; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/agent/index.js

@@ -1,7 +1,6 @@
-export { SOLFACE_TOOLS, allToolsAnthropic, allToolsMCP, allToolsOpenAI, allToolsVercelAI, handleToolCall, toAnthropic, toMCP, toOpenAI, toVercelAI } from '../chunk-66PSL4YO.js';
-import '../chunk-CKHLRORB.js';
-import '../chunk-3CE7Q44S.js';
-import '../chunk-DRUSCLEF.js';
-import '../chunk-N5DDJ3WQ.js';
+export { SOLFACE_TOOLS, allToolsAnthropic, allToolsMCP, allToolsOpenAI, allToolsVercelAI, handleToolCall, toAnthropic, toMCP, toOpenAI, toVercelAI } from '../chunk-O2IIBSQH.js';
+import '../chunk-N5GDLCCL.js';
+import '../chunk-MYUSB4LA.js';
+import '../chunk-UTT764K6.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map