@iconoma-icons/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 0xnocap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @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)

package/dist/index.d.mts

@@ -0,0 +1,35 @@
+declare class SeededRandom {
+    private seed;
+    constructor(seed: number);
+    random(): number;
+    randomInt(min: number, max: number): number;
+    randomElement<T>(array: T[]): T;
+    shuffle<T>(array: T[]): T[];
+}
+
+interface Options {
+    /** Unique string seed — same seed always produces the same icon */
+    seed?: string;
+    /** Icon size in pixels (default: 128) */
+    size?: number;
+    /** Color palette to use. Falls back to a built-in default if omitted */
+    colors?: string[];
+    /** Clip to a circle */
+    isCircle?: boolean;
+    /** Rounded corner radius (ignored if isCircle is true) */
+    borderRadius?: number;
+    /** Style-specific parameters (e.g. blockSize, waveCount, etc.) */
+    styleOptions?: Record<string, any>;
+}
+interface Result {
+    /** Returns the raw SVG markup string */
+    toString: () => string;
+    /** Returns a data URI suitable for <img src="..."> */
+    toDataUri: () => string;
+}
+type Style = {
+    (rng: SeededRandom, options: Options): string;
+};
+declare function createIcon(style: Style, options?: Options): Result;
+
+export { type Options, type Result, SeededRandom, type Style, createIcon };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+declare class SeededRandom {
+    private seed;
+    constructor(seed: number);
+    random(): number;
+    randomInt(min: number, max: number): number;
+    randomElement<T>(array: T[]): T;
+    shuffle<T>(array: T[]): T[];
+}
+
+interface Options {
+    /** Unique string seed — same seed always produces the same icon */
+    seed?: string;
+    /** Icon size in pixels (default: 128) */
+    size?: number;
+    /** Color palette to use. Falls back to a built-in default if omitted */
+    colors?: string[];
+    /** Clip to a circle */
+    isCircle?: boolean;
+    /** Rounded corner radius (ignored if isCircle is true) */
+    borderRadius?: number;
+    /** Style-specific parameters (e.g. blockSize, waveCount, etc.) */
+    styleOptions?: Record<string, any>;
+}
+interface Result {
+    /** Returns the raw SVG markup string */
+    toString: () => string;
+    /** Returns a data URI suitable for <img src="..."> */
+    toDataUri: () => string;
+}
+type Style = {
+    (rng: SeededRandom, options: Options): string;
+};
+declare function createIcon(style: Style, options?: Options): Result;
+
+export { type Options, type Result, SeededRandom, type Style, createIcon };

package/dist/index.js

@@ -0,0 +1,103 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SeededRandom: () => SeededRandom,
+  createIcon: () => createIcon
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/seededRandom.ts
+var SeededRandom = class {
+  seed;
+  constructor(seed) {
+    this.seed = seed;
+  }
+  // Returns a random number between 0 and 1
+  random() {
+    let t = this.seed += 1831565813;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  }
+  // Returns a random integer between min (inclusive) and max (inclusive)
+  randomInt(min, max) {
+    return Math.floor(this.random() * (max - min + 1)) + min;
+  }
+  // Returns a random element from an array
+  randomElement(array) {
+    return array[Math.floor(this.random() * array.length)];
+  }
+  // Shuffles an array
+  shuffle(array) {
+    const shuffled = [...array];
+    for (let i = shuffled.length - 1; i > 0; i--) {
+      const j = Math.floor(this.random() * (i + 1));
+      [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    return shuffled;
+  }
+};
+
+// src/index.ts
+var FALLBACK_COLORS = ["#FF006E", "#8338EC", "#3A86FF", "#FFBE0B", "#FB5607"];
+function hashSeed(seedString) {
+  let hash = 0;
+  for (let i = 0; i < seedString.length; i++) {
+    hash = Math.imul(31, hash) + seedString.charCodeAt(i) | 0;
+  }
+  return hash;
+}
+function createIcon(style, options = {}) {
+  const seedString = options.seed !== void 0 ? String(options.seed) : Math.random().toString();
+  const rngSeed = hashSeed(seedString);
+  const rng = new SeededRandom(rngSeed);
+  const size = options.size || 128;
+  const resolvedOptions = {
+    ...options,
+    size,
+    colors: options.colors && options.colors.length > 0 ? options.colors : FALLBACK_COLORS
+  };
+  const svgBody = style(rng, resolvedOptions);
+  let clipPathDef = "";
+  let clipGroupStart = '<g stroke="none" stroke-width="0">';
+  const clipGroupEnd = "</g>";
+  if (options.isCircle) {
+    const clipPathId = "circle-clip-" + rngSeed;
+    clipPathDef = `<clipPath id="${clipPathId}"><circle cx="${size / 2}" cy="${size / 2}" r="${size / 2}"/></clipPath>`;
+    clipGroupStart = `<g clip-path="url(#${clipPathId})" stroke="none" stroke-width="0">`;
+  } else if (options.borderRadius && options.borderRadius > 0) {
+    const clipPathId = "rounded-clip-" + rngSeed;
+    const r = Math.min(options.borderRadius, size / 2);
+    clipPathDef = `<clipPath id="${clipPathId}"><rect width="${size}" height="${size}" rx="${r}"/></clipPath>`;
+    clipGroupStart = `<g clip-path="url(#${clipPathId})" stroke="none" stroke-width="0">`;
+  }
+  const svgString = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${size} ${size}" width="${size}" height="${size}" shape-rendering="crispEdges">${clipPathDef ? `<defs>${clipPathDef}</defs>` : ""}${clipGroupStart}${svgBody}${clipGroupEnd}</svg>`;
+  return {
+    toString: () => svgString,
+    toDataUri: () => `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svgString)}`
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SeededRandom,
+  createIcon
+});

package/dist/index.mjs

@@ -0,0 +1,75 @@
+// src/seededRandom.ts
+var SeededRandom = class {
+  seed;
+  constructor(seed) {
+    this.seed = seed;
+  }
+  // Returns a random number between 0 and 1
+  random() {
+    let t = this.seed += 1831565813;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  }
+  // Returns a random integer between min (inclusive) and max (inclusive)
+  randomInt(min, max) {
+    return Math.floor(this.random() * (max - min + 1)) + min;
+  }
+  // Returns a random element from an array
+  randomElement(array) {
+    return array[Math.floor(this.random() * array.length)];
+  }
+  // Shuffles an array
+  shuffle(array) {
+    const shuffled = [...array];
+    for (let i = shuffled.length - 1; i > 0; i--) {
+      const j = Math.floor(this.random() * (i + 1));
+      [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    return shuffled;
+  }
+};
+
+// src/index.ts
+var FALLBACK_COLORS = ["#FF006E", "#8338EC", "#3A86FF", "#FFBE0B", "#FB5607"];
+function hashSeed(seedString) {
+  let hash = 0;
+  for (let i = 0; i < seedString.length; i++) {
+    hash = Math.imul(31, hash) + seedString.charCodeAt(i) | 0;
+  }
+  return hash;
+}
+function createIcon(style, options = {}) {
+  const seedString = options.seed !== void 0 ? String(options.seed) : Math.random().toString();
+  const rngSeed = hashSeed(seedString);
+  const rng = new SeededRandom(rngSeed);
+  const size = options.size || 128;
+  const resolvedOptions = {
+    ...options,
+    size,
+    colors: options.colors && options.colors.length > 0 ? options.colors : FALLBACK_COLORS
+  };
+  const svgBody = style(rng, resolvedOptions);
+  let clipPathDef = "";
+  let clipGroupStart = '<g stroke="none" stroke-width="0">';
+  const clipGroupEnd = "</g>";
+  if (options.isCircle) {
+    const clipPathId = "circle-clip-" + rngSeed;
+    clipPathDef = `<clipPath id="${clipPathId}"><circle cx="${size / 2}" cy="${size / 2}" r="${size / 2}"/></clipPath>`;
+    clipGroupStart = `<g clip-path="url(#${clipPathId})" stroke="none" stroke-width="0">`;
+  } else if (options.borderRadius && options.borderRadius > 0) {
+    const clipPathId = "rounded-clip-" + rngSeed;
+    const r = Math.min(options.borderRadius, size / 2);
+    clipPathDef = `<clipPath id="${clipPathId}"><rect width="${size}" height="${size}" rx="${r}"/></clipPath>`;
+    clipGroupStart = `<g clip-path="url(#${clipPathId})" stroke="none" stroke-width="0">`;
+  }
+  const svgString = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${size} ${size}" width="${size}" height="${size}" shape-rendering="crispEdges">${clipPathDef ? `<defs>${clipPathDef}</defs>` : ""}${clipGroupStart}${svgBody}${clipGroupEnd}</svg>`;
+  return {
+    toString: () => svgString,
+    toDataUri: () => `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svgString)}`
+  };
+}
+export {
+  SeededRandom,
+  createIcon
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@iconoma-icons/core",
+	"version": "1.0.0",
+	"description": "Core generation engine for Iconoma — deterministic SVG icon generator.",
+	"license": "MIT",
+	"author": "0xnocap",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/0xnocap/iconoma.git",
+		"directory": "packages/core"
+	},
+	"keywords": [
+		"icon",
+		"svg",
+		"avatar",
+		"deterministic",
+		"identicon",
+		"generator",
+		"seed"
+	],
+	"main": "dist/index.js",
+	"module": "dist/index.mjs",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"import": {
+				"types": "./dist/index.d.mts",
+				"default": "./dist/index.mjs"
+			},
+			"require": {
+				"types": "./dist/index.d.ts",
+				"default": "./dist/index.js"
+			}
+		}
+	},
+	"files": [
+		"dist",
+		"README.md",
+		"LICENSE"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"build": "tsup src/index.ts --format cjs,esm --dts"
+	},
+	"devDependencies": {
+		"tsup": "^8.0.2",
+		"typescript": "^5.2.2"
+	}
+}