solfaces 2.0.0 → 2.1.1

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 (69) hide show
  1. package/README.md +155 -14
  2. package/SKILL.md +180 -0
  3. package/dist/agent/index.cjs +14 -13
  4. package/dist/agent/index.js +4 -3
  5. package/dist/agent/mcp-server.cjs +2248 -13
  6. package/dist/{chunk-HCEE4K4T.js → chunk-3CE7Q44S.js} +6 -5
  7. package/dist/chunk-3CE7Q44S.js.map +1 -0
  8. package/dist/{chunk-23XJ5VDX.cjs → chunk-4YFZ4W2Y.cjs} +47 -16
  9. package/dist/chunk-4YFZ4W2Y.cjs.map +1 -0
  10. package/dist/{chunk-LRHYF5QN.js → chunk-5DT27HMT.js} +3 -3
  11. package/dist/{chunk-LRHYF5QN.js.map → chunk-5DT27HMT.js.map} +1 -1
  12. package/dist/{chunk-TTGJZEPV.js → chunk-66PSL4YO.js} +43 -12
  13. package/dist/chunk-66PSL4YO.js.map +1 -0
  14. package/dist/{chunk-JS527VKL.js → chunk-CKHLRORB.js} +6 -5
  15. package/dist/chunk-CKHLRORB.js.map +1 -0
  16. package/dist/{chunk-6UWILY7E.cjs → chunk-F54WHRCE.cjs} +6 -5
  17. package/dist/chunk-F54WHRCE.cjs.map +1 -0
  18. package/dist/chunk-N5DDJ3WQ.js +2242 -0
  19. package/dist/chunk-N5DDJ3WQ.js.map +1 -0
  20. package/dist/{chunk-46ZEFA6R.cjs → chunk-TYTBYDQU.cjs} +10 -9
  21. package/dist/chunk-TYTBYDQU.cjs.map +1 -0
  22. package/dist/{chunk-546TBMAR.cjs → chunk-WIXGHS77.cjs} +6 -6
  23. package/dist/{chunk-546TBMAR.cjs.map → chunk-WIXGHS77.cjs.map} +1 -1
  24. package/dist/chunk-XXJJH56O.cjs +2251 -0
  25. package/dist/chunk-XXJJH56O.cjs.map +1 -0
  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.d.cts +2 -2
  30. package/dist/core/index.d.ts +2 -2
  31. package/dist/core/index.js +3 -3
  32. package/dist/index.cjs +63 -34
  33. package/dist/index.d.cts +3 -1
  34. package/dist/index.d.ts +3 -1
  35. package/dist/index.js +5 -4
  36. package/dist/names/index.cjs +40 -0
  37. package/dist/names/index.cjs.map +1 -0
  38. package/dist/names/index.d.cts +48 -0
  39. package/dist/names/index.d.ts +48 -0
  40. package/dist/names/index.js +3 -0
  41. package/dist/names/index.js.map +1 -0
  42. package/dist/react/index.cjs +45 -22
  43. package/dist/react/index.cjs.map +1 -1
  44. package/dist/react/index.d.cts +16 -3
  45. package/dist/react/index.d.ts +16 -3
  46. package/dist/react/index.js +30 -8
  47. package/dist/react/index.js.map +1 -1
  48. package/dist/solfaces.cdn.global.js +2 -2
  49. package/dist/solfaces.cdn.global.js.map +1 -1
  50. package/dist/themes/index.d.cts +1 -1
  51. package/dist/themes/index.d.ts +1 -1
  52. package/dist/{traits-QlWuxZDD.d.cts → traits-sfe7rM9C.d.cts} +1 -0
  53. package/dist/{traits-QlWuxZDD.d.ts → traits-sfe7rM9C.d.ts} +1 -0
  54. package/dist/vanilla/index.cjs +5 -5
  55. package/dist/vanilla/index.d.cts +1 -1
  56. package/dist/vanilla/index.d.ts +1 -1
  57. package/dist/vanilla/index.js +2 -2
  58. package/package.json +22 -5
  59. package/python/solfaces.py +274 -3
  60. package/reference/integrations.md +211 -0
  61. package/reference/react.md +108 -0
  62. package/reference/themes.md +124 -0
  63. package/dist/chunk-23XJ5VDX.cjs.map +0 -1
  64. package/dist/chunk-46ZEFA6R.cjs.map +0 -1
  65. package/dist/chunk-6UWILY7E.cjs.map +0 -1
  66. package/dist/chunk-HCEE4K4T.js.map +0 -1
  67. package/dist/chunk-JS527VKL.js.map +0 -1
  68. package/dist/chunk-TTGJZEPV.js.map +0 -1
  69. 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](assets/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,114 @@ 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 }
126
197
  ```
127
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
+ }
209
+ ```
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
+ ### Custom Word Lists
232
+
233
+ Both `deriveName` and `deriveIdentity` accept an optional `DeriveOptions` parameter to fully customize name generation:
234
+
235
+ ```ts
236
+ import { deriveName, deriveIdentity } from "solfaces";
237
+ import type { DeriveOptions } from "solfaces";
238
+
239
+ const opts: DeriveOptions = {
240
+ adjectives: ["Fast", "Bold", "Calm", "Keen", "Wise"],
241
+ nouns: ["Tiger", "Eagle", "Bear", "Wolf", "Hawk"],
242
+ domain: "my-app-v1", // Custom domain prefix (default: "solnames-v1")
243
+ blockedCombos: new Set(["BoldBear"]), // Custom blocked pairs
244
+ };
245
+
246
+ deriveName("7xKXqR...", "display", opts); // Uses custom word lists
247
+ deriveIdentity("7xKXqR...", opts); // Full identity with custom lists
248
+ ```
249
+
250
+ All fields are optional — omit any to use the built-in defaults.
251
+
252
+ - **1000 adjectives + 1000 nouns** — curated positive/neutral PascalCase words (customizable via `DeriveOptions`)
253
+ - **Same name everywhere** — TypeScript, Python, CDN, and server all produce identical output
254
+ - **Blocked combinations** — offensive adjective+noun pairs are automatically skipped (customizable via `DeriveOptions`)
255
+
128
256
  ---
129
257
 
130
258
  ## Rendering Modes
@@ -188,7 +316,7 @@ import { glassTheme, glassDarkTheme } from "solfaces/themes";
188
316
 
189
317
  ## AI Agent Identity
190
318
 
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.
319
+ 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
320
 
193
321
  ### System Prompt Integration
194
322
 
@@ -487,9 +615,10 @@ const result = await handleToolCall("generate_solface_svg", {
487
615
  |------|-------------|
488
616
  | `generate_solface_svg` | Render SVG avatar from wallet address |
489
617
  | `describe_solface` | Natural language description of an avatar |
490
- | `get_solface_traits` | Raw trait data with labels and hash |
618
+ | `get_solface_traits` | Raw trait data with labels, hash, and name |
491
619
  | `get_agent_identity` | System prompt snippet for AI agent identity |
492
620
  | `list_solface_themes` | List available preset themes |
621
+ | `derive_solname` | Deterministic name from wallet via SHA-256 |
493
622
 
494
623
  ### MCP Server (Claude Code / Cursor)
495
624
 
@@ -518,7 +647,7 @@ import {
518
647
 
519
648
  ### Skill File for AI Agents
520
649
 
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.
650
+ 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
651
 
523
652
  ---
524
653
 
@@ -543,11 +672,12 @@ Templates included for: **Next.js App Router**, **Express**, **Hono (Cloudflare
543
672
  Full Python implementation with identical trait generation to JavaScript. Zero dependencies. Includes gradient-rich rendering matching the TypeScript renderer.
544
673
 
545
674
  ```python
546
- from solfaces import generate_traits, render_svg, describe_appearance
675
+ from solfaces import generate_traits, render_svg, describe_appearance, derive_name
547
676
 
548
677
  traits = generate_traits("7xKXqR...")
549
678
  svg = render_svg("7xKXqR...", size=256)
550
679
  desc = describe_appearance("7xKXqR...")
680
+ name = derive_name("7xKXqR...")
551
681
  prompt = agent_appearance_prompt("7xKXqR...", "Atlas")
552
682
  ```
553
683
 
@@ -586,6 +716,7 @@ For sites without a build step — Webflow, Notion embeds, plain HTML, WordPress
586
716
  SolFaces.setImg("#pfp", "7xKXqR...");
587
717
  const svg = SolFaces.renderSVG("7xKXqR...");
588
718
  const desc = SolFaces.describe("7xKXqR...");
719
+ const name = SolFaces.deriveName("7xKXqR...");
589
720
  const prompt = SolFaces.agentPrompt("7xKXqR...", "Atlas");
590
721
  </script>
591
722
  ```
@@ -596,6 +727,8 @@ For sites without a build step — Webflow, Notion embeds, plain HTML, WordPress
596
727
 
597
728
  | Function | Returns | Description |
598
729
  |----------|---------|-------------|
730
+ | `deriveName(wallet, format?, options?)` | `string` | Deterministic name from wallet (SHA-256) |
731
+ | `deriveIdentity(wallet, options?)` | `SolNameIdentity` | Full identity bundle from wallet |
599
732
  | `generateTraits(wallet, overrides?)` | `SolFaceTraits` | Deterministic traits from wallet |
600
733
  | `getTraitLabels(traits)` | `Record<string, string>` | Human-readable trait names |
601
734
  | `traitHash(wallet)` | `string` | 8-char hex hash |
@@ -619,7 +752,7 @@ For sites without a build step — Webflow, Notion embeds, plain HTML, WordPress
619
752
  | `blend(a, b, t)` | `string` | Blend two colors |
620
753
  | `luminance(hex)` | `number` | Perceived luminance (0-255) |
621
754
  | `deriveSkinColors(skinHex)` | `DerivedColors` | Full skin-luminance color derivation |
622
- | `SOLFACE_TOOLS` | `SolFaceTool[]` | All 5 agent tool definitions |
755
+ | `SOLFACE_TOOLS` | `SolFaceTool[]` | All 6 agent tool definitions |
623
756
  | `handleToolCall(name, params)` | `unknown` | Universal agent tool dispatcher |
624
757
 
625
758
  ### React Component Props
@@ -693,11 +826,12 @@ Available keys: `skin`, `eyes`, `hair`, `bg`, `mouth`, `eyebrow`, `accessory`, `
693
826
 
694
827
  | Path | Contents | React? |
695
828
  |------|----------|--------|
696
- | `solfaces` | Core + colors + themes + describe + rasterize + agent tools | No |
829
+ | `solfaces` | Core + colors + themes + names + describe + rasterize + agent tools | No |
697
830
  | `solfaces/core` | Engine only (traits, renderer, colors, describe) | No |
698
831
  | `solfaces/react` | React component (base + pixel + glass modes) | Yes |
699
832
  | `solfaces/vanilla` | DOM helpers (mount, setImg, autoInit) | No |
700
833
  | `solfaces/themes` | 11 preset themes | No |
834
+ | `solfaces/names` | SolNames derivation + validation | No |
701
835
  | `solfaces/agent` | AI agent tool definitions + framework adapters | No |
702
836
  | `solfaces/cdn` | IIFE for `<script>` tags | No |
703
837
 
@@ -738,11 +872,18 @@ solfaces/
738
872
  │ │ ├── colors.ts # Color math: darken, lighten, blend, deriveSkinColors
739
873
  │ │ ├── traits.ts # Types, palettes, theme system, trait generation
740
874
  │ │ ├── renderer.ts # SVG string renderer (gradient-rich, detail levels)
741
- │ │ ├── describe.ts # Natural language descriptions for AI agents
875
+ │ │ ├── describe.ts # (no names.ts moved to names/)
742
876
  │ │ ├── rasterize.ts # PNG output (sharp / resvg / canvas)
743
877
  │ │ └── index.ts
878
+ │ ├── names/
879
+ │ │ ├── constants.ts # 1000 adjectives, 1000 nouns, blocked combos
880
+ │ │ ├── sha256.ts # Pure-JS SHA-256 (sync, zero deps)
881
+ │ │ ├── derive.ts # deriveName(), deriveIdentity()
882
+ │ │ ├── validate.ts # isValidSolName(), parseSolName()
883
+ │ │ └── index.ts
744
884
  │ ├── react/
745
885
  │ │ ├── SolFace.tsx # React component (base + pixel art + liquid glass)
886
+ │ │ ├── useSolName.ts # useSolName() hook
746
887
  │ │ └── index.ts
747
888
  │ ├── vanilla/
748
889
  │ │ └── index.ts # mountSolFace, setSolFaceImg, autoInit
@@ -750,7 +891,7 @@ solfaces/
750
891
  │ │ ├── presets.ts # 11 preset themes
751
892
  │ │ └── index.ts
752
893
  │ ├── agent/
753
- │ │ ├── tools.ts # 5 canonical tool definitions + handlers
894
+ │ │ ├── tools.ts # 6 canonical tool definitions + handlers
754
895
  │ │ ├── index.ts # Format adapters (MCP, OpenAI, Anthropic, Vercel AI)
755
896
  │ │ └── mcp-server.ts # Standalone MCP server (npx solfaces)
756
897
  │ ├── cdn.ts # IIFE bundle for <script> tag
package/SKILL.md ADDED
@@ -0,0 +1,180 @@
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
+ Returns: description string. Auto-populates `name` from `deriveName(wallet, "display")` if no name provided.
42
+
43
+ ### `get_solface_traits`
44
+ Raw trait data with human-readable labels and hash.
45
+
46
+ | Parameter | Type | Required | Description |
47
+ |-----------|------|----------|-------------|
48
+ | `wallet` | string | Yes | Solana wallet address |
49
+
50
+ Returns: `{ traits: SolFaceTraits, labels: Record<string, string>, hash: string, name: string }`. Name is auto-populated from `deriveName(wallet, "display")`.
51
+
52
+ ### `get_agent_identity`
53
+ System prompt snippet giving an AI agent a visual identity.
54
+
55
+ | Parameter | Type | Required | Description |
56
+ |-----------|------|----------|-------------|
57
+ | `wallet` | string | Yes | Agent's wallet address |
58
+ | `agentName` | string | No | Agent name for personalization |
59
+
60
+ Returns: First-person identity prompt string. Auto-populates agent name from `deriveName(wallet, "display")` if no `agentName` provided.
61
+
62
+ ### `derive_solname`
63
+ Derive a deterministic name from a wallet via SHA-256 hashing and curated word lists.
64
+
65
+ **When to use:** User needs a name for a wallet, wants to label a wallet, or needs an identity name.
66
+
67
+ | Parameter | Type | Required | Default | Description |
68
+ |-----------|------|----------|---------|-------------|
69
+ | `wallet` | string | Yes | -- | Solana wallet address (base58) |
70
+ | `format` | string | No | -- | "short", "display", "tag", or "full". Omit for full identity object. |
71
+
72
+ Returns: Without format: `SolNameIdentity` object (short/name/tag/full/adjective/noun/hash/discriminator). With format: formatted string.
73
+
74
+ ### `list_solface_themes`
75
+ List available preset themes with descriptions.
76
+
77
+ No parameters. Returns: Array of `{ name, description, reactOnly }`.
78
+
79
+ ---
80
+
81
+ ## Installation
82
+
83
+ ```bash
84
+ npm install solfaces
85
+ ```
86
+ ```html
87
+ <script src="https://unpkg.com/solfaces/dist/solfaces.cdn.global.js"></script>
88
+ ```
89
+ ```bash
90
+ curl -O https://raw.githubusercontent.com/jorger3301/solfaces/main/python/solfaces.py
91
+ ```
92
+
93
+ ---
94
+
95
+ ## Import Paths
96
+
97
+ | Project Type | Import Path | What You Get |
98
+ |---|---|---|
99
+ | React / Next.js | `solfaces/react` | `<SolFace>` component with pixel art and glass modes |
100
+ | Vanilla JS / Vue / Svelte | `solfaces/vanilla` | `mountSolFace()`, `setSolFaceImg()`, `autoInit()` |
101
+ | Node.js server / API | `solfaces` | `renderSolFaceSVG()`, `renderSolFacePNG()`, descriptions, colors |
102
+ | No build step / CDN | `<script>` tag | `window.SolFaces` global |
103
+ | AI agent framework | `solfaces/agent` | Tool schemas + format adapters |
104
+ | Theme presets only | `solfaces/themes` | 11 preset theme objects |
105
+ | Names only | `solfaces/names` | `deriveName()`, `deriveIdentity()`, validation |
106
+ | Python backend | `from solfaces import ...` | Full Python port |
107
+
108
+ ---
109
+
110
+ ## Quick Examples
111
+
112
+ ### React
113
+ ```tsx
114
+ import { SolFace } from "solfaces/react";
115
+ <SolFace walletAddress="7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU" size={48} enableBlink showName />
116
+ ```
117
+
118
+ ### Server-side
119
+ ```ts
120
+ import { renderSolFaceSVG } from "solfaces";
121
+ const svg = renderSolFaceSVG("7xKXtg...", { size: 256 });
122
+ ```
123
+
124
+ ### Name derivation
125
+ ```ts
126
+ import { deriveName, deriveIdentity } from "solfaces";
127
+ deriveName("7xKXtg..."); // "SunnyIcon"
128
+ deriveName("7xKXtg...", "tag"); // "SunnyIcon#2f95"
129
+ const id = deriveIdentity("7xKXtg..."); // full identity object
130
+ ```
131
+
132
+ ### CDN
133
+ ```html
134
+ <div data-solface="7xKXtg..." data-solface-size="48"></div>
135
+ <script src="https://unpkg.com/solfaces/dist/solfaces.cdn.global.js"></script>
136
+ <script>
137
+ const name = SolFaces.deriveName("7xKXtg...");
138
+ SolFaces.mount("#avatar", "7xKXtg...", { size: 64 });
139
+ </script>
140
+ ```
141
+
142
+ ### Python
143
+ ```python
144
+ from solfaces import render_svg, describe_appearance, derive_name
145
+ svg = render_svg("7xKXtg...", size=256)
146
+ name = derive_name("7xKXtg...")
147
+ ```
148
+
149
+ ---
150
+
151
+ ## Rendering Modes
152
+
153
+ - **Full detail** (size >= 48): Gradients, specular highlights, cheek blush, chin shadow, glow.
154
+ - **Simplified** (size < 48): Flat shapes, no gradients. Override with `detail: "full"` or `"simplified"`.
155
+ - **Flat mode**: `theme: { flat: true }` disables all gradients.
156
+ - **Pixel art** (React only): `pixelTheme`, `pixelRetroTheme`, `pixelCleanTheme`.
157
+ - **Liquid glass** (React only): `glassTheme`, `glassDarkTheme`.
158
+
159
+ ---
160
+
161
+ ## Detailed Reference
162
+
163
+ For comprehensive documentation on specific topics:
164
+
165
+ - **React component**: Full props interface, all rendering modes, `useSolName` hook, `showName` prop, color overrides, blink timing. See [reference/react.md](reference/react.md)
166
+ - **Themes**: All theme fields, pixel art and glass customization, theme recommendations, custom theme examples. See [reference/themes.md](reference/themes.md)
167
+ - **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)
168
+
169
+ ---
170
+
171
+ ## Key Facts
172
+
173
+ - **Deterministic**: Same wallet = same face + same name. djb2 + mulberry32 PRNG (traits), SHA-256 + mulberry32 PRNG (names).
174
+ - **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.
175
+ - **SolNames**: 1000 adjectives + 1000 nouns, SHA-256 derived. Formats: short, display (~1M), tag (~65.5B), full (~1T). Custom word lists supported via `DeriveOptions`.
176
+ - **Earring suppression**: Long and bob hairstyles suppress earring accessories.
177
+ - **Cross-language parity**: JS and Python produce identical output.
178
+ - **Zero dependencies**: Core engine has no runtime deps.
179
+ - **SVG viewBox**: All avatars use 64x64 viewBox, scaled by `size`.
180
+ - **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 chunk4YFZ4W2Y_cjs = require('../chunk-4YFZ4W2Y.cjs');
4
+ require('../chunk-TYTBYDQU.cjs');
5
+ require('../chunk-F54WHRCE.cjs');
6
6
  require('../chunk-6QRDULAO.cjs');
7
+ require('../chunk-XXJJH56O.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 chunk4YFZ4W2Y_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 chunk4YFZ4W2Y_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 chunk4YFZ4W2Y_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 chunk4YFZ4W2Y_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 chunk4YFZ4W2Y_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 chunk4YFZ4W2Y_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 chunk4YFZ4W2Y_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 chunk4YFZ4W2Y_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 chunk4YFZ4W2Y_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 chunk4YFZ4W2Y_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-66PSL4YO.js';
2
+ import '../chunk-CKHLRORB.js';
3
+ import '../chunk-3CE7Q44S.js';
4
4
  import '../chunk-DRUSCLEF.js';
5
+ import '../chunk-N5DDJ3WQ.js';
5
6
  //# sourceMappingURL=index.js.map
6
7
  //# sourceMappingURL=index.js.map