npm package: @iconoma-icons/core
Description: Core generation engine for Iconoma — deterministic SVG icon generator.
Author: 0xnocap
Latest version: 1.0.0

# @iconoma-icons/core

Core engine for [Iconoma](https://github.com/0xnocap/iconoma) — deterministic SVG icon generation from any string.

## Install

```bash
npm install @iconoma-icons/core
```

You'll also want `@iconoma-icons/collection` for the built-in styles, unless you're writing your own.

## API

### `createIcon(style, options?)`

Generates a deterministic SVG icon from a style function and options.

```js
import { createIcon } from '@iconoma-icons/core';
import { pixel } from '@iconoma-icons/collection';

const icon = createIcon(pixel, {
  seed: 'user@example.com',
  size: 128,
  colors: ['#FF006E', '#8338EC', '#3A86FF', '#FFBE0B', '#FB5607'],
  isCircle: false,
  borderRadius: 0,
});

icon.toString();   // '<svg xmlns="http://www.w3.org/2000/svg" ...>...</svg>'
icon.toDataUri();  // 'data:image/svg+xml;charset=utf-8,%3Csvg...'
```

**Returns:** `Result` — an object with two methods:

| Method | Returns | Description |
|--------|---------|-------------|
| `toString()` | `string` | Raw SVG markup. Use with `innerHTML`, `fs.writeFileSync()`, etc. |
| `toDataUri()` | `string` | Data URI string. Use with `<img src="...">` or CSS `background-image`. |

**Options:**

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `seed` | `string` | random | Any string. Determines the icon appearance. Same seed = same icon. |
| `size` | `number` | `128` | Width & height in pixels. |
| `colors` | `string[]` | `['#FF006E', '#8338EC', '#3A86FF', '#FFBE0B', '#FB5607']` | Array of hex color strings (e.g. `'#FF006E'`). 3-5 colors recommended. |
| `isCircle` | `boolean` | `false` | Clip to circle via SVG `<clipPath>`. |
| `borderRadius` | `number` | `0` | Rounded corner radius in px. Ignored if `isCircle` is true. |
| `styleOptions` | `Record<string, any>` | style defaults | Style-specific tuning params. See `@iconoma-icons/collection` docs for options per style. |

### `SeededRandom`

Deterministic pseudo-random number generator. Used internally and exposed for custom styles.

```ts
import { SeededRandom } from '@iconoma-icons/core';

const rng = new SeededRandom(42);

rng.random();              // float in [0, 1)
rng.randomInt(0, 10);      // integer in [0, 10] inclusive
rng.randomElement(array);  // picks one element
rng.shuffle(array);        // Fisher-Yates shuffle, returns the shuffled array
```

### `Style` type

A style is a function with this signature:

```ts
type Style = (rng: SeededRandom, options: Options) => string;
```

It receives a seeded RNG and the resolved options, and returns an **SVG body string** (the markup *inside* the `<svg>` tag — rects, paths, polygons, etc). The `createIcon` function wraps this in a proper SVG element with viewBox, clipping, etc.

### Writing a custom style

```ts
import { createIcon, SeededRandom } from '@iconoma-icons/core';
import type { Style, Options } from '@iconoma-icons/core';

const myStyle: Style = (rng: SeededRandom, options: Options): string => {
  const size = options.size || 128;
  const colors = options.colors || ['#000', '#fff'];
  const bg = rng.randomElement(colors);
  const fg = rng.randomElement(colors);

  // Return SVG body markup (everything inside <svg>)
  return `
    <rect width="${size}" height="${size}" fill="${bg}"/>
    <circle cx="${size/2}" cy="${size/2}" r="${size/3}" fill="${fg}"/>
  `;
};

const icon = createIcon(myStyle, { seed: 'hello', size: 256 });
console.log(icon.toString());
```

## License

[MIT](../../LICENSE)