# On-Chain Icons

ChainRender ships a curated set of **~500 icons stored on-chain** (from the public-domain-spirited Lucide set),
available to any app through the `icon` node. Icons are a shared, reusable on-chain library \u2014 fetched by name,
decompressed natively, injected once, and rendered as SVG that inherits the app's theme colour.

## Using an icon

An `icon` node takes a name:

```json
{ "type": "icon", "name": "wallet" }
```

The interpreter emits `<svg class="icon icon-wallet"><use href="#icon-wallet"/></svg>`, and the icon sprite (the
`<symbol>` definitions) is provided on-chain. Because icons use `currentColor`, they automatically match the active
theme (light/dark/custom) \u2014 no per-icon styling.

## Where the icons live

The 500-icon sprite is a **library in the DependencyRegistry** (like p5 and three.js), gzip-compressed into a single
chunk. The viewer discovers it by name (`"icons"`, newest-wins), fetches the chunks via `eth_call`, decompresses with
the browser's native `DecompressionStream` (no CDN, CSP-safe), and injects the `<symbol>` sheet so every
`<use href="#icon-*">` resolves. An embedded copy is the instant fail-open fallback; the on-chain copy is the source
of truth once loaded.

## Regenerating / extending the set

`scripts/build-icon-sprite.mjs` ingests the real Lucide data (`lucide-static`) and builds the sprite at a dialable
count (default 500; `all` for the full ~2000). At ~41 gzipped bytes/icon, ~500 icons fit in one 24 KiB chunk, and even
the full set fits in one upload part. The set is extensible: the icon library can be regenerated at a larger count and re-uploaded on-chain, and newest-wins discovery makes the latest version the one apps use.

## Available names

The manifest (`assets/icons/icon-manifest.json`) lists every available name \u2014 navigation, arrows, actions, status,
crypto/web3 (wallet, coins, bitcoin, credit-card, qr-code), media, files, user/social, layout, data/charts, dev, and
commerce. The AI builder is given the full list, so AI-generated apps use real icon names.

## Ethos note

Icons are **on-chain, content-addressed, immutable** \u2014 same as every ChainRender library. Rendering is a `view`;
the icon set is deterministic SVG the interpreter references. Nothing is server-hosted in the deployed app.


## Related
- **[The Render Pipeline](./render-pipeline.md)** — how the interpreter emits the icon references.
- **[Rich Media](./rich-media-p5-three.md)** — icons load the same CSP-safe on-chain way as p5/three.
- **[Theming](./theming.md)** — icons inherit theme colour via `currentColor`.
- **[Visual & Media Capabilities](./visual-media.md)** — the broader on-chain media surface.