solfaces 2.0.0 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/README.md +134 -14
  2. package/SKILL.md +171 -0
  3. package/dist/agent/index.cjs +14 -13
  4. package/dist/agent/index.js +4 -3
  5. package/dist/agent/mcp-server.cjs +2240 -10
  6. package/dist/{chunk-TTGJZEPV.js → chunk-77SPWQU5.js} +43 -12
  7. package/dist/chunk-77SPWQU5.js.map +1 -0
  8. package/dist/{chunk-JS527VKL.js → chunk-CQWXUU7P.js} +6 -5
  9. package/dist/chunk-CQWXUU7P.js.map +1 -0
  10. package/dist/{chunk-46ZEFA6R.cjs → chunk-CXRVPOTI.cjs} +10 -9
  11. package/dist/chunk-CXRVPOTI.cjs.map +1 -0
  12. package/dist/{chunk-23XJ5VDX.cjs → chunk-F244Q4KC.cjs} +47 -16
  13. package/dist/chunk-F244Q4KC.cjs.map +1 -0
  14. package/dist/{chunk-6UWILY7E.cjs → chunk-HVPGR6G5.cjs} +2 -2
  15. package/dist/{chunk-6UWILY7E.cjs.map → chunk-HVPGR6G5.cjs.map} +1 -1
  16. package/dist/{chunk-LRHYF5QN.js → chunk-MGP7F65H.js} +3 -3
  17. package/dist/{chunk-LRHYF5QN.js.map → chunk-MGP7F65H.js.map} +1 -1
  18. package/dist/chunk-R3MC2AJZ.cjs +2247 -0
  19. package/dist/chunk-R3MC2AJZ.cjs.map +1 -0
  20. package/dist/{chunk-HCEE4K4T.js → chunk-SWML743U.js} +2 -2
  21. package/dist/{chunk-HCEE4K4T.js.map → chunk-SWML743U.js.map} +1 -1
  22. package/dist/chunk-SX3FQDKM.js +2238 -0
  23. package/dist/chunk-SX3FQDKM.js.map +1 -0
  24. package/dist/{chunk-546TBMAR.cjs → chunk-WTCXTXTV.cjs} +6 -6
  25. package/dist/{chunk-546TBMAR.cjs.map → chunk-WTCXTXTV.cjs.map} +1 -1
  26. package/dist/constants-Bi5uTRp5.d.cts +17 -0
  27. package/dist/constants-Bi5uTRp5.d.ts +17 -0
  28. package/dist/core/index.cjs +31 -31
  29. package/dist/core/index.js +3 -3
  30. package/dist/index.cjs +63 -34
  31. package/dist/index.d.cts +2 -0
  32. package/dist/index.d.ts +2 -0
  33. package/dist/index.js +5 -4
  34. package/dist/names/index.cjs +40 -0
  35. package/dist/names/index.cjs.map +1 -0
  36. package/dist/names/index.d.cts +36 -0
  37. package/dist/names/index.d.ts +36 -0
  38. package/dist/names/index.js +3 -0
  39. package/dist/names/index.js.map +1 -0
  40. package/dist/react/index.cjs +45 -22
  41. package/dist/react/index.cjs.map +1 -1
  42. package/dist/react/index.d.cts +15 -2
  43. package/dist/react/index.d.ts +15 -2
  44. package/dist/react/index.js +30 -8
  45. package/dist/react/index.js.map +1 -1
  46. package/dist/solfaces.cdn.global.js +2 -2
  47. package/dist/solfaces.cdn.global.js.map +1 -1
  48. package/dist/vanilla/index.cjs +5 -5
  49. package/dist/vanilla/index.js +2 -2
  50. package/package.json +22 -5
  51. package/python/solfaces.py +274 -3
  52. package/reference/integrations.md +166 -0
  53. package/reference/react.md +108 -0
  54. package/reference/themes.md +124 -0
  55. package/dist/chunk-23XJ5VDX.cjs.map +0 -1
  56. package/dist/chunk-46ZEFA6R.cjs.map +0 -1
  57. package/dist/chunk-JS527VKL.js.map +0 -1
  58. package/dist/chunk-TTGJZEPV.js.map +0 -1
  59. package/skill.md +0 -608
package/README.md CHANGED
@@ -1,11 +1,20 @@
1
1
  # SolFaces
2
2
 
3
- **Deterministic wallet avatars for the Solana ecosystem.**
3
+ [![npm version](https://img.shields.io/npm/v/solfaces)](https://www.npmjs.com/package/solfaces)
4
+ [![npm downloads](https://img.shields.io/npm/dw/solfaces)](https://www.npmjs.com/package/solfaces)
5
+ [![license](https://img.shields.io/npm/l/solfaces)](https://github.com/jorger3301/SolFaces/blob/main/LICENSE)
6
+ [![bundle size](https://img.shields.io/bundlephobia/minzip/solfaces)](https://bundlephobia.com/package/solfaces)
4
7
 
5
- Every Solana wallet address generates a unique, consistent face — no API calls, no storage, no randomness. Same wallet = same face, everywhere, forever.
8
+ **Deterministic wallet avatars and names for the Solana ecosystem.**
9
+
10
+ Every Solana wallet address generates a unique, consistent face and a deterministic name — no API calls, no storage, no randomness. Same wallet = same face, same name, everywhere, forever.
6
11
 
7
12
  Built for dApps, AI agents, social features, leaderboards, and anywhere a wallet needs a visual identity.
8
13
 
14
+ ![SolFaces theme showcase showing Default, Light, Dark, and Mono rendering modes](solfaces-themes-labeled.png)
15
+
16
+ *Default, Light, Dark, and Mono — four of the 11 built-in themes. Each row shows the same 10 wallets rendered in a different theme.*
17
+
9
18
  ---
10
19
 
11
20
  ## Why SolFaces?
@@ -13,15 +22,15 @@ Built for dApps, AI agents, social features, leaderboards, and anywhere a wallet
13
22
  - **Deterministic** — Same wallet always produces the same avatar. No database needed.
14
23
  - **Zero dependencies** — Core engine has no runtime dependencies.
15
24
  - **~2.56B unique faces** — 11 traits with expanded ranges = massive combination space.
25
+ - **SolNames** — Every wallet gets a deterministic, human-friendly name derived via SHA-256 (e.g. "SunnyIcon"). ~1M display names, ~65.5B unique tags.
26
+ - **11 built-in themes** — Default, Dark, Light, Mono, Flat, Transparent, plus 3 Pixel and 2 Glass themes (React).
16
27
  - **Gradient-rich rendering** — Skin-luminance-driven colors, specular highlights, cheek blush, gradient hair, glow overlays.
17
28
  - **Works everywhere** — React, vanilla JS, Node, Python, CDN script tag, edge functions.
18
- - **Pixel art mode** — Retro pixelated rendering with optional scanlines (React).
19
- - **Liquid glass mode** — Backdrop-blur glass effect with rim lighting (React).
20
29
  - **Flat mode** — Disable all gradients for simplified rendering.
21
30
  - **Detail levels** — Full detail (gradients, specular, cheeks) at size >= 48, simplified below.
22
31
  - **Fully customizable** — Every visual element is customizable: 4 color palettes, 8 individual color overrides, 9 per-instance color keys, rendering toggles, layout controls, blink timing, and 30+ React-only pixel/glass fields. No visual element is locked — if you can see it, you can theme it.
23
32
  - **Eliminates dead space** — No more blank avatars or generic placeholders. Every wallet gets a unique face instantly.
24
- - **AI-agent ready** — Natural language self-descriptions for agent system prompts.
33
+ - **AI-agent ready** — AI trading bots and autonomous agents are becoming on-chain users. SolFaces gives every agent a recognizable face and a natural language self-description for system prompts and bios.
25
34
  - **PNG rasterization** — Serve real image files for bots, Discord, Telegram, OG images.
26
35
  - **SSR-ready** — String renderer works server-side with zero browser APIs.
27
36
 
@@ -106,6 +115,24 @@ mountSolFace("#avatar", "7xKXqR...", { size: 48 });
106
115
  </script>
107
116
  ```
108
117
 
118
+ ### Name Derivation (SolNames)
119
+
120
+ ```ts
121
+ import { deriveName, deriveIdentity } from "solfaces";
122
+
123
+ deriveName("7xKXqR...");
124
+ // → "SunnyIcon" (deterministic, SHA-256 derived)
125
+
126
+ deriveName("7xKXqR...", "tag");
127
+ // → "SunnyIcon#2f95" (unique identifier)
128
+
129
+ deriveName("7xKXqR...", "full");
130
+ // → "SunnyIcon-InfiniteOre" (formal contexts)
131
+
132
+ const id = deriveIdentity("7xKXqR...");
133
+ // → { short, name, tag, full, adjective, noun, hash, discriminator }
134
+ ```
135
+
109
136
  ### Node / SSR / Edge
110
137
 
111
138
  ```ts
@@ -118,13 +145,93 @@ const svg = renderSolFaceSVG("7xKXqR...", { size: 128 });
118
145
  ### Python
119
146
 
120
147
  ```python
121
- from solfaces import generate_traits, render_svg, describe_appearance
148
+ from solfaces import generate_traits, render_svg, describe_appearance, derive_name
122
149
 
123
150
  traits = generate_traits("7xKXqR...")
124
151
  svg = render_svg("7xKXqR...", size=256)
125
152
  desc = describe_appearance("7xKXqR...")
153
+ name = derive_name("7xKXqR...")
154
+ ```
155
+
156
+ ---
157
+
158
+ ## SolNames — Deterministic Name Derivation
159
+
160
+ Every wallet gets a deterministic, human-friendly name derived via SHA-256 hashing and curated word lists. Nothing like this exists on any blockchain — every other naming system (SNS, ENS, Unstoppable Domains) requires purchase. SolNames derives names automatically — zero registration, zero storage, just math.
161
+
162
+ ```
163
+ Wallet: 7PjJ2AHq9BMXWYjt3qqeKwZVLXHYFPmHRYrMF6PpRySD
164
+
165
+
166
+ SHA-256("solnames-v1:" + wallet) → 32 bytes
167
+
168
+ ├─→ Bytes 0-3: seed PRNG → adjective + noun
169
+ └─→ Bytes 8-9: hex discriminator → "2f95"
170
+
171
+ Display: WavingMistral
172
+ Tag: WavingMistral#2f95
173
+ ```
174
+
175
+ ### Name Formats
176
+
177
+ | Format | Example | Unique Names | Use Case |
178
+ |---------|------------------------------|-------------|-----------------------------|
179
+ | short | "Waving" | 1,000 | Tight UIs, badges |
180
+ | display | "WavingMistral" | ~1,000,000 | Default — profiles, feeds |
181
+ | tag | "WavingMistral#2f95" | ~65.5B | Unique identifier |
182
+ | full | "WavingMistral-InfiniteOre" | ~1T | Formal contexts |
183
+
184
+ ### Usage
185
+
186
+ ```ts
187
+ import { deriveName, deriveIdentity } from "solfaces";
188
+ // or: import { deriveName } from "solfaces/names";
189
+
190
+ deriveName("7xKXqR..."); // → "SunnyIcon" (display format)
191
+ deriveName("7xKXqR...", "short"); // → "Sunny"
192
+ deriveName("7xKXqR...", "tag"); // → "SunnyIcon#2f95"
193
+ deriveName("7xKXqR...", "full"); // → "SunnyIcon-InfiniteOre"
194
+
195
+ const id = deriveIdentity("7xKXqR...");
196
+ // → { short, name, tag, full, adjective, noun, hash, discriminator }
197
+ ```
198
+
199
+ ### React Hook
200
+
201
+ ```tsx
202
+ import { useSolName } from "solfaces/react";
203
+
204
+ function Profile({ wallet }) {
205
+ const name = useSolName(wallet, "display"); // string
206
+ const identity = useSolName(wallet); // full SolNameIdentity
207
+ return <span>{name}</span>;
208
+ }
126
209
  ```
127
210
 
211
+ ### Show Name with Avatar
212
+
213
+ ```tsx
214
+ import { SolFace } from "solfaces/react";
215
+
216
+ <SolFace walletAddress="7xKXqR..." showName />
217
+ <SolFace walletAddress="7xKXqR..." showName namePosition="above" nameFormat="tag" />
218
+ ```
219
+
220
+ ### Validation
221
+
222
+ ```ts
223
+ import { isValidSolName, parseSolName } from "solfaces/names";
224
+
225
+ isValidSolName("SunnyIcon"); // true
226
+ isValidSolName("SunnyIcon#2f95"); // true
227
+ parseSolName("SunnyIcon#2f95");
228
+ // → { adjective: "Sunny", noun: "Icon", discriminator: "2f95" }
229
+ ```
230
+
231
+ - **1000 adjectives + 1000 nouns** — curated positive/neutral PascalCase words
232
+ - **Same name everywhere** — TypeScript, Python, CDN, and server all produce identical output
233
+ - **Blocked combinations** — offensive adjective+noun pairs are automatically skipped
234
+
128
235
  ---
129
236
 
130
237
  ## Rendering Modes
@@ -188,7 +295,7 @@ import { glassTheme, glassDarkTheme } from "solfaces/themes";
188
295
 
189
296
  ## AI Agent Identity
190
297
 
191
- SolFaces gives AI agents a visual identity tied to their wallet. The `describeAppearance()` function generates natural language descriptions agents can use in system prompts to know and reference what they look like.
298
+ 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.
192
299
 
193
300
  ### System Prompt Integration
194
301
 
@@ -487,9 +594,10 @@ const result = await handleToolCall("generate_solface_svg", {
487
594
  |------|-------------|
488
595
  | `generate_solface_svg` | Render SVG avatar from wallet address |
489
596
  | `describe_solface` | Natural language description of an avatar |
490
- | `get_solface_traits` | Raw trait data with labels and hash |
597
+ | `get_solface_traits` | Raw trait data with labels, hash, and name |
491
598
  | `get_agent_identity` | System prompt snippet for AI agent identity |
492
599
  | `list_solface_themes` | List available preset themes |
600
+ | `derive_solname` | Deterministic name from wallet via SHA-256 |
493
601
 
494
602
  ### MCP Server (Claude Code / Cursor)
495
603
 
@@ -518,7 +626,7 @@ import {
518
626
 
519
627
  ### Skill File for AI Agents
520
628
 
521
- SolFaces includes a comprehensive `skill.md` that teaches AI agents how to integrate, customize, and use SolFaces. Feed it to any agent (Claude, GPT, custom bots) as context.
629
+ SolFaces includes a comprehensive `SKILL.md` (with 3 reference files in `reference/`) that teaches AI agents how to integrate, customize, and use SolFaces. Feed it to any agent (Claude, GPT, custom bots) as context.
522
630
 
523
631
  ---
524
632
 
@@ -543,11 +651,12 @@ Templates included for: **Next.js App Router**, **Express**, **Hono (Cloudflare
543
651
  Full Python implementation with identical trait generation to JavaScript. Zero dependencies. Includes gradient-rich rendering matching the TypeScript renderer.
544
652
 
545
653
  ```python
546
- from solfaces import generate_traits, render_svg, describe_appearance
654
+ from solfaces import generate_traits, render_svg, describe_appearance, derive_name
547
655
 
548
656
  traits = generate_traits("7xKXqR...")
549
657
  svg = render_svg("7xKXqR...", size=256)
550
658
  desc = describe_appearance("7xKXqR...")
659
+ name = derive_name("7xKXqR...")
551
660
  prompt = agent_appearance_prompt("7xKXqR...", "Atlas")
552
661
  ```
553
662
 
@@ -586,6 +695,7 @@ For sites without a build step — Webflow, Notion embeds, plain HTML, WordPress
586
695
  SolFaces.setImg("#pfp", "7xKXqR...");
587
696
  const svg = SolFaces.renderSVG("7xKXqR...");
588
697
  const desc = SolFaces.describe("7xKXqR...");
698
+ const name = SolFaces.deriveName("7xKXqR...");
589
699
  const prompt = SolFaces.agentPrompt("7xKXqR...", "Atlas");
590
700
  </script>
591
701
  ```
@@ -596,6 +706,8 @@ For sites without a build step — Webflow, Notion embeds, plain HTML, WordPress
596
706
 
597
707
  | Function | Returns | Description |
598
708
  |----------|---------|-------------|
709
+ | `deriveName(wallet, format?)` | `string` | Deterministic name from wallet (SHA-256) |
710
+ | `deriveIdentity(wallet)` | `SolNameIdentity` | Full identity bundle from wallet |
599
711
  | `generateTraits(wallet, overrides?)` | `SolFaceTraits` | Deterministic traits from wallet |
600
712
  | `getTraitLabels(traits)` | `Record<string, string>` | Human-readable trait names |
601
713
  | `traitHash(wallet)` | `string` | 8-char hex hash |
@@ -619,7 +731,7 @@ For sites without a build step — Webflow, Notion embeds, plain HTML, WordPress
619
731
  | `blend(a, b, t)` | `string` | Blend two colors |
620
732
  | `luminance(hex)` | `number` | Perceived luminance (0-255) |
621
733
  | `deriveSkinColors(skinHex)` | `DerivedColors` | Full skin-luminance color derivation |
622
- | `SOLFACE_TOOLS` | `SolFaceTool[]` | All 5 agent tool definitions |
734
+ | `SOLFACE_TOOLS` | `SolFaceTool[]` | All 6 agent tool definitions |
623
735
  | `handleToolCall(name, params)` | `unknown` | Universal agent tool dispatcher |
624
736
 
625
737
  ### React Component Props
@@ -693,11 +805,12 @@ Available keys: `skin`, `eyes`, `hair`, `bg`, `mouth`, `eyebrow`, `accessory`, `
693
805
 
694
806
  | Path | Contents | React? |
695
807
  |------|----------|--------|
696
- | `solfaces` | Core + colors + themes + describe + rasterize + agent tools | No |
808
+ | `solfaces` | Core + colors + themes + names + describe + rasterize + agent tools | No |
697
809
  | `solfaces/core` | Engine only (traits, renderer, colors, describe) | No |
698
810
  | `solfaces/react` | React component (base + pixel + glass modes) | Yes |
699
811
  | `solfaces/vanilla` | DOM helpers (mount, setImg, autoInit) | No |
700
812
  | `solfaces/themes` | 11 preset themes | No |
813
+ | `solfaces/names` | SolNames derivation + validation | No |
701
814
  | `solfaces/agent` | AI agent tool definitions + framework adapters | No |
702
815
  | `solfaces/cdn` | IIFE for `<script>` tags | No |
703
816
 
@@ -738,11 +851,18 @@ solfaces/
738
851
  │ │ ├── colors.ts # Color math: darken, lighten, blend, deriveSkinColors
739
852
  │ │ ├── traits.ts # Types, palettes, theme system, trait generation
740
853
  │ │ ├── renderer.ts # SVG string renderer (gradient-rich, detail levels)
741
- │ │ ├── describe.ts # Natural language descriptions for AI agents
854
+ │ │ ├── describe.ts # (no names.ts moved to names/)
742
855
  │ │ ├── rasterize.ts # PNG output (sharp / resvg / canvas)
743
856
  │ │ └── index.ts
857
+ │ ├── names/
858
+ │ │ ├── constants.ts # 1000 adjectives, 1000 nouns, blocked combos
859
+ │ │ ├── sha256.ts # Pure-JS SHA-256 (sync, zero deps)
860
+ │ │ ├── derive.ts # deriveName(), deriveIdentity()
861
+ │ │ ├── validate.ts # isValidSolName(), parseSolName()
862
+ │ │ └── index.ts
744
863
  │ ├── react/
745
864
  │ │ ├── SolFace.tsx # React component (base + pixel art + liquid glass)
865
+ │ │ ├── useSolName.ts # useSolName() hook
746
866
  │ │ └── index.ts
747
867
  │ ├── vanilla/
748
868
  │ │ └── index.ts # mountSolFace, setSolFaceImg, autoInit
@@ -750,7 +870,7 @@ solfaces/
750
870
  │ │ ├── presets.ts # 11 preset themes
751
871
  │ │ └── index.ts
752
872
  │ ├── agent/
753
- │ │ ├── tools.ts # 5 canonical tool definitions + handlers
873
+ │ │ ├── tools.ts # 6 canonical tool definitions + handlers
754
874
  │ │ ├── index.ts # Format adapters (MCP, OpenAI, Anthropic, Vercel AI)
755
875
  │ │ └── mcp-server.ts # Standalone MCP server (npx solfaces)
756
876
  │ ├── cdn.ts # IIFE bundle for <script> tag
package/SKILL.md ADDED
@@ -0,0 +1,171 @@
1
+ ---
2
+ name: solfaces
3
+ description: Generates deterministic avatars and names for Solana wallet addresses. Use when the user mentions wallet avatars, profile pictures, visual identity, SolFaces, or needs to represent a Solana wallet visually. Provides SVG rendering, natural language descriptions, SHA-256 name derivation, and AI agent identity prompts. 6 tools available.
4
+ ---
5
+
6
+ # SolFaces
7
+
8
+ 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.
9
+
10
+ ---
11
+
12
+ ## Available Tools
13
+
14
+ ### `generate_solface_svg`
15
+ Render an SVG avatar from a wallet address.
16
+
17
+ **When to use:** User wants to see an avatar, embed one in a page, or display a wallet's face.
18
+
19
+ | Parameter | Type | Required | Default | Description |
20
+ |-----------|------|----------|---------|-------------|
21
+ | `wallet` | string | Yes | -- | Solana wallet address (base58) |
22
+ | `size` | number | No | 64 | Width/height in pixels. >= 48 uses full detail. |
23
+ | `theme` | string | No | -- | Preset: default, dark, light, mono, flat, transparent, glass, glassDark, pixel, pixelRetro, pixelClean |
24
+ | `enableBlink` | boolean | No | false | CSS eye-blink animation |
25
+ | `detail` | string | No | auto | "full", "simplified", or "auto" (full if size >= 48) |
26
+
27
+ Returns: SVG string. Note: glass/pixel themes are React-only.
28
+
29
+ ### `describe_solface`
30
+ Natural language description of a wallet's avatar.
31
+
32
+ **When to use:** User wants alt text, a profile bio, or to know what a face looks like.
33
+
34
+ | Parameter | Type | Required | Default | Description |
35
+ |-----------|------|----------|---------|-------------|
36
+ | `wallet` | string | Yes | -- | Solana wallet address |
37
+ | `format` | string | No | paragraph | paragraph, structured, or compact |
38
+ | `perspective` | string | No | third | third or first |
39
+ | `name` | string | No | -- | Name to use instead of "This SolFace" |
40
+
41
+ ### `get_solface_traits`
42
+ Raw trait data with human-readable labels and hash.
43
+
44
+ | Parameter | Type | Required | Description |
45
+ |-----------|------|----------|-------------|
46
+ | `wallet` | string | Yes | Solana wallet address |
47
+
48
+ Returns: `{ traits, labels, hash, name }`
49
+
50
+ ### `get_agent_identity`
51
+ System prompt snippet giving an AI agent a visual identity.
52
+
53
+ | Parameter | Type | Required | Description |
54
+ |-----------|------|----------|-------------|
55
+ | `wallet` | string | Yes | Agent's wallet address |
56
+ | `agentName` | string | No | Agent name for personalization |
57
+
58
+ Returns: First-person identity prompt string.
59
+
60
+ ### `derive_solname`
61
+ Derive a deterministic name from a wallet via SHA-256 hashing and curated word lists.
62
+
63
+ **When to use:** User needs a name for a wallet, wants to label a wallet, or needs an identity name.
64
+
65
+ | Parameter | Type | Required | Default | Description |
66
+ |-----------|------|----------|---------|-------------|
67
+ | `wallet` | string | Yes | -- | Solana wallet address (base58) |
68
+ | `format` | string | No | -- | "short", "display", "tag", or "full". Omit for full identity object. |
69
+
70
+ Returns: Without format: `SolNameIdentity` object (short/name/tag/full/adjective/noun/hash/discriminator). With format: formatted string.
71
+
72
+ ### `list_solface_themes`
73
+ List available preset themes with descriptions.
74
+
75
+ No parameters. Returns: Array of `{ name, description, reactOnly }`.
76
+
77
+ ---
78
+
79
+ ## Installation
80
+
81
+ ```bash
82
+ npm install solfaces
83
+ ```
84
+ ```html
85
+ <script src="https://unpkg.com/solfaces/dist/solfaces.cdn.global.js"></script>
86
+ ```
87
+ ```bash
88
+ curl -O https://raw.githubusercontent.com/jorger3301/solfaces/main/python/solfaces.py
89
+ ```
90
+
91
+ ---
92
+
93
+ ## Import Paths
94
+
95
+ | Project Type | Import Path | What You Get |
96
+ |---|---|---|
97
+ | React / Next.js | `solfaces/react` | `<SolFace>` component with pixel art and glass modes |
98
+ | Vanilla JS / Vue / Svelte | `solfaces/vanilla` | `mountSolFace()`, `setSolFaceImg()`, `autoInit()` |
99
+ | Node.js server / API | `solfaces` | `renderSolFaceSVG()`, `renderSolFacePNG()`, descriptions, colors |
100
+ | No build step / CDN | `<script>` tag | `window.SolFaces` global |
101
+ | AI agent framework | `solfaces/agent` | Tool schemas + format adapters |
102
+ | Theme presets only | `solfaces/themes` | 11 preset theme objects |
103
+ | Names only | `solfaces/names` | `deriveName()`, `deriveIdentity()`, validation |
104
+ | Python backend | `from solfaces import ...` | Full Python port |
105
+
106
+ ---
107
+
108
+ ## Quick Examples
109
+
110
+ ### React
111
+ ```tsx
112
+ import { SolFace } from "solfaces/react";
113
+ <SolFace walletAddress="7xKXtg..." size={48} enableBlink showName />
114
+ ```
115
+
116
+ ### Server-side
117
+ ```ts
118
+ import { renderSolFaceSVG } from "solfaces";
119
+ const svg = renderSolFaceSVG("7xKXtg...", { size: 256 });
120
+ ```
121
+
122
+ ### Name derivation
123
+ ```ts
124
+ import { deriveName, deriveIdentity } from "solfaces";
125
+ deriveName("7xKXtg..."); // "SunnyIcon"
126
+ deriveName("7xKXtg...", "tag"); // "SunnyIcon#2f95"
127
+ const id = deriveIdentity("7xKXtg..."); // full identity object
128
+ ```
129
+
130
+ ### CDN
131
+ ```html
132
+ <div data-solface="7xKXtg..." data-solface-size="48"></div>
133
+ <script src="https://unpkg.com/solfaces/dist/solfaces.cdn.global.js"></script>
134
+ <script>
135
+ const name = SolFaces.deriveName("7xKXtg...");
136
+ SolFaces.mount("#avatar", "7xKXtg...", { size: 64 });
137
+ </script>
138
+ ```
139
+
140
+ ---
141
+
142
+ ## Rendering Modes
143
+
144
+ - **Full detail** (size >= 48): Gradients, specular highlights, cheek blush, chin shadow, glow.
145
+ - **Simplified** (size < 48): Flat shapes, no gradients. Override with `detail: "full"` or `"simplified"`.
146
+ - **Flat mode**: `theme: { flat: true }` disables all gradients.
147
+ - **Pixel art** (React only): `pixelTheme`, `pixelRetroTheme`, `pixelCleanTheme`.
148
+ - **Liquid glass** (React only): `glassTheme`, `glassDarkTheme`.
149
+
150
+ ---
151
+
152
+ ## Detailed Reference
153
+
154
+ For comprehensive documentation on specific topics:
155
+
156
+ - **React component**: Full props interface, all rendering modes, `useSolName` hook, `showName` prop, color overrides, blink timing. See [reference/react.md](reference/react.md)
157
+ - **Themes**: All theme fields, pixel art and glass customization, theme recommendations, custom theme examples. See [reference/themes.md](reference/themes.md)
158
+ - **Integrations**: Agent framework adapters (OpenAI, Anthropic, Vercel AI, MCP), server-side routes, bot integration, full API reference, color math utilities, accessibility. See [reference/integrations.md](reference/integrations.md)
159
+
160
+ ---
161
+
162
+ ## Key Facts
163
+
164
+ - **Deterministic**: Same wallet = same face + same name. djb2 + mulberry32 PRNG (traits), SHA-256 + mulberry32 PRNG (names).
165
+ - **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.
166
+ - **SolNames**: 1000 adjectives + 1000 nouns, SHA-256 derived. Formats: short, display (~1M), tag (~65.5B), full (~1T).
167
+ - **Earring suppression**: Long and bob hairstyles suppress earring accessories.
168
+ - **Cross-language parity**: JS and Python produce identical output.
169
+ - **Zero dependencies**: Core engine has no runtime deps.
170
+ - **SVG viewBox**: All avatars use 64x64 viewBox, scaled by `size`.
171
+ - **Alt text**: `solFaceAltText(wallet)` provides accessible descriptions.
@@ -1,51 +1,52 @@
1
1
  'use strict';
2
2
 
3
- var chunk23XJ5VDX_cjs = require('../chunk-23XJ5VDX.cjs');
4
- require('../chunk-46ZEFA6R.cjs');
5
- require('../chunk-6UWILY7E.cjs');
3
+ var chunkF244Q4KC_cjs = require('../chunk-F244Q4KC.cjs');
4
+ require('../chunk-CXRVPOTI.cjs');
5
+ require('../chunk-HVPGR6G5.cjs');
6
6
  require('../chunk-6QRDULAO.cjs');
7
+ require('../chunk-R3MC2AJZ.cjs');
7
8
 
8
9
 
9
10
 
10
11
  Object.defineProperty(exports, "SOLFACE_TOOLS", {
11
12
  enumerable: true,
12
- get: function () { return chunk23XJ5VDX_cjs.SOLFACE_TOOLS; }
13
+ get: function () { return chunkF244Q4KC_cjs.SOLFACE_TOOLS; }
13
14
  });
14
15
  Object.defineProperty(exports, "allToolsAnthropic", {
15
16
  enumerable: true,
16
- get: function () { return chunk23XJ5VDX_cjs.allToolsAnthropic; }
17
+ get: function () { return chunkF244Q4KC_cjs.allToolsAnthropic; }
17
18
  });
18
19
  Object.defineProperty(exports, "allToolsMCP", {
19
20
  enumerable: true,
20
- get: function () { return chunk23XJ5VDX_cjs.allToolsMCP; }
21
+ get: function () { return chunkF244Q4KC_cjs.allToolsMCP; }
21
22
  });
22
23
  Object.defineProperty(exports, "allToolsOpenAI", {
23
24
  enumerable: true,
24
- get: function () { return chunk23XJ5VDX_cjs.allToolsOpenAI; }
25
+ get: function () { return chunkF244Q4KC_cjs.allToolsOpenAI; }
25
26
  });
26
27
  Object.defineProperty(exports, "allToolsVercelAI", {
27
28
  enumerable: true,
28
- get: function () { return chunk23XJ5VDX_cjs.allToolsVercelAI; }
29
+ get: function () { return chunkF244Q4KC_cjs.allToolsVercelAI; }
29
30
  });
30
31
  Object.defineProperty(exports, "handleToolCall", {
31
32
  enumerable: true,
32
- get: function () { return chunk23XJ5VDX_cjs.handleToolCall; }
33
+ get: function () { return chunkF244Q4KC_cjs.handleToolCall; }
33
34
  });
34
35
  Object.defineProperty(exports, "toAnthropic", {
35
36
  enumerable: true,
36
- get: function () { return chunk23XJ5VDX_cjs.toAnthropic; }
37
+ get: function () { return chunkF244Q4KC_cjs.toAnthropic; }
37
38
  });
38
39
  Object.defineProperty(exports, "toMCP", {
39
40
  enumerable: true,
40
- get: function () { return chunk23XJ5VDX_cjs.toMCP; }
41
+ get: function () { return chunkF244Q4KC_cjs.toMCP; }
41
42
  });
42
43
  Object.defineProperty(exports, "toOpenAI", {
43
44
  enumerable: true,
44
- get: function () { return chunk23XJ5VDX_cjs.toOpenAI; }
45
+ get: function () { return chunkF244Q4KC_cjs.toOpenAI; }
45
46
  });
46
47
  Object.defineProperty(exports, "toVercelAI", {
47
48
  enumerable: true,
48
- get: function () { return chunk23XJ5VDX_cjs.toVercelAI; }
49
+ get: function () { return chunkF244Q4KC_cjs.toVercelAI; }
49
50
  });
50
51
  //# sourceMappingURL=index.cjs.map
51
52
  //# sourceMappingURL=index.cjs.map
@@ -1,6 +1,7 @@
1
- export { SOLFACE_TOOLS, allToolsAnthropic, allToolsMCP, allToolsOpenAI, allToolsVercelAI, handleToolCall, toAnthropic, toMCP, toOpenAI, toVercelAI } from '../chunk-TTGJZEPV.js';
2
- import '../chunk-JS527VKL.js';
3
- import '../chunk-HCEE4K4T.js';
1
+ export { SOLFACE_TOOLS, allToolsAnthropic, allToolsMCP, allToolsOpenAI, allToolsVercelAI, handleToolCall, toAnthropic, toMCP, toOpenAI, toVercelAI } from '../chunk-77SPWQU5.js';
2
+ import '../chunk-CQWXUU7P.js';
3
+ import '../chunk-SWML743U.js';
4
4
  import '../chunk-DRUSCLEF.js';
5
+ import '../chunk-SX3FQDKM.js';
5
6
  //# sourceMappingURL=index.js.map
6
7
  //# sourceMappingURL=index.js.map