open-avatar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenAvatar contributors
+
+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,199 @@
+# OpenAvatar
+
+OpenAvatar is a TypeScript SVG avatar generator with deterministic hashes, a demo page, and framework wrappers for React and Vue.
+
+It generates head-focused SVG avatars from selectable parts, including background, hair, skin, expression, beard, and eyewear. The returned hash records the exact selected combination, so a saved avatar can be reproduced even if more options are added later.
+
+## Features
+
+- Deterministic SVG avatar generation from any string or saved OpenAvatar hash.
+- Stable snapshot hashes in the `op-xxx-xxx:xxxx~category:value` format.
+- Transparent, solid color, and patterned backgrounds.
+- `circle`, `rounded-square`, and `square` output shapes.
+- React and Vue component entry points.
+- Bilingual demo UI with random batches, option filters, hash loading, and integration examples.
+- MIT licensed.
+
+## Install
+
+```bash
+npm install open-avatar
+```
+
+For local development in this repository:
+
+```bash
+npm install
+npm run dev
+```
+
+## Core API
+
+```ts
+import {
+  generateAvatar,
+  generateAvatarSvg,
+  generateAvatarUrl,
+  generateRandomAvatar,
+  generateRandomAvatars,
+  getAvatarParts,
+  getTotalCombinations
+} from "open-avatar";
+
+const avatar = generateAvatar("user-42", {
+  shape: "rounded-square",
+  size: 160,
+  title: "User 42"
+});
+
+console.log(avatar.hash);
+console.log(avatar.svg);
+console.log(avatar.url);
+console.log(avatar.parts);
+```
+
+`generateAvatar()` returns:
+
+```ts
+type AvatarResult = {
+  hash: string;
+  svg: string;
+  url: string;
+  shape: "rounded-square" | "circle" | "square";
+  parts: AvatarParts;
+};
+```
+
+## Hashes
+
+OpenAvatar accepts any string as input. User-provided values are normalized into a short root hash, then the generated avatar returns a snapshot hash that stores the selected parts:
+
+```ts
+const draft = generateAvatar("customer:10086");
+
+// Save this value after the user is satisfied.
+const savedHash = draft.hash;
+
+// Later, the same hash reproduces the same avatar.
+const fixed = generateAvatar(savedHash);
+```
+
+Snapshot hashes are intentionally longer than a simple seed. They preserve the exact generated combination, so future option additions do not change existing saved avatars.
+
+## React
+
+```tsx
+import { Avatar } from "open-avatar/react";
+
+export function UserAvatar() {
+  return (
+    <Avatar
+      hash="op-user-42:1yf1e7~background:trianglify-blue~hair:bob-black~skin:peach~expression:happy-raisedExcited-smile~beard:none~clothing:shirtCrewNeck~eyewear:none"
+      shape="circle"
+      size={96}
+      title="User avatar"
+    />
+  );
+}
+```
+
+## Vue
+
+```vue
+<script setup lang="ts">
+import { Avatar } from "open-avatar/vue";
+</script>
+
+<template>
+  <Avatar
+    hash="op-user-42:1yf1e7~background:trianglify-blue~hair:bob-black~skin:peach~expression:happy-raisedExcited-smile~beard:none~clothing:shirtCrewNeck~eyewear:none"
+    shape="rounded-square"
+    :size="96"
+    title="User avatar"
+  />
+</template>
+```
+
+## Demo
+
+```bash
+npm run dev
+```
+
+The demo includes:
+
+- 9-avatar random preview grid.
+- Hash loading and fixed avatar preview.
+- Random-by-string workflow for choosing and saving a final hash.
+- Option filters with localized display names.
+- Light, dark, circular, rounded, square, navigation, menu, and dense stacked examples.
+- Collapsible React/Vue integration notes.
+
+## Examples
+
+Runnable examples live in `examples/`.
+
+```bash
+cd examples/react
+npm install
+npm run dev
+```
+
+```bash
+cd examples/vue
+npm install
+npm run dev
+```
+
+The examples use Vite aliases to import this repository during local development. In an external project, install `open-avatar` and remove the local aliases.
+
+## Development
+
+```bash
+npm test
+npm run build
+```
+
+Example builds:
+
+```bash
+cd examples/react
+npm run build
+```
+
+```bash
+cd examples/vue
+npm run build
+```
+
+## Publishing
+
+Before publishing, verify the package contents:
+
+```bash
+npm test
+npm run build
+npm pack --dry-run
+```
+
+Publish the current version:
+
+```bash
+npm login
+npm publish
+```
+
+For future releases, update the version first:
+
+```bash
+npm version patch
+npm publish
+```
+
+Use `npm version minor` for compatible feature releases and `npm version major` for breaking changes.
+
+## License
+
+OpenAvatar is released under the MIT License. See `LICENSE`.
+
+This project uses DiceBear Avataaars assets and APIs. See `THIRD_PARTY_NOTICES.md` for attribution details.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,11 @@
+# Third Party Notices
+
+OpenAvatar includes hair SVG path designs adapted from Avataaars by Pablo Stanley through
+DiceBear's `@dicebear/avataaars` package.
+
+- Avataaars: https://avataaars.com/
+- DiceBear Avataaars package: https://www.dicebear.com/styles/avataaars/
+- Source package: https://unpkg.com/@dicebear/avataaars@9.2.2/
+
+DiceBear code is distributed under the MIT License. Avataaars assets are published for
+personal and commercial use by Pablo Stanley.

package/dist/core/generator.d.ts

@@ -0,0 +1,11 @@
+import { AvatarOptions, AvatarParts, AvatarResult } from './types';
+
+export declare const MAX_RANDOM_AVATAR_BATCH = 1000;
+export declare function getAvatarParts(hash: string): AvatarParts;
+export declare function generateAvatarSvg(hash: string, options?: AvatarOptions): string;
+export declare function generateAvatarUrl(hash: string, options?: AvatarOptions): string;
+export declare function generateAvatar(hash: string, options?: AvatarOptions): AvatarResult;
+export declare function generateRandomAvatar(options?: AvatarOptions): AvatarResult;
+export declare function generateRandomAvatars(count: number, options?: AvatarOptions): ReadonlyArray<AvatarResult>;
+export declare function getTotalCombinations(): number;
+//# sourceMappingURL=generator.d.ts.map

package/dist/core/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../../src/core/generator.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,aAAa,EAGb,WAAW,EACX,YAAY,EAEb,MAAM,SAAS,CAAC;AAGjB,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAkI5C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAExD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAUnF;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CAEnF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY,CActF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,aAAkB,GAAG,YAAY,CAE9E;AAED,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,aAAkB,GAC1B,aAAa,CAAC,YAAY,CAAC,CA+B7B;AAED,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/core/hash.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizeHash(hash: string): string;
+export declare function hashToSeed(hash: string): number;
+export declare function indexFromSeed(seed: number, length: number, salt: number): number;
+export declare function createRandomHash(): string;
+//# sourceMappingURL=hash.d.ts.map

package/dist/core/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/core/hash.ts"],"names":[],"mappings":"AAEA,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQlD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAS/C;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAahF;AAYD,wBAAgB,gBAAgB,IAAI,MAAM,CAEzC"}

package/dist/core/parts.d.ts

@@ -0,0 +1,8 @@
+import { AvatarPart, AvatarPartCatalog, AvatarParts } from './types';
+
+export declare const avatarParts: AvatarPartCatalog;
+export declare function cloneAvatarPart(part: Readonly<AvatarPart>): AvatarPart;
+export declare function freezeAvatarParts(parts: AvatarParts): AvatarParts;
+export declare function getAvatarPartCatalog(): AvatarPartCatalog;
+export declare function getPartCombinationCount(): number;
+//# sourceMappingURL=parts.d.ts.map

package/dist/core/parts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parts.d.ts","sourceRoot":"","sources":["../../src/core/parts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAiB,WAAW,EAAE,MAAM,SAAS,CAAC;AAmWzF,eAAO,MAAM,WAAW,EAAE,iBAQxB,CAAC;AAEH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,UAAU,CAEtE;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAEjE;AAED,wBAAgB,oBAAoB,IAAI,iBAAiB,CAUxD;AAED,wBAAgB,uBAAuB,IAAI,MAAM,CAUhD"}

package/dist/core/svg.d.ts

@@ -0,0 +1,5 @@
+import { AvatarParts, AvatarShape } from './types';
+
+export declare function renderAvatarSvg(parts: AvatarParts, shape: AvatarShape, hash: string, title?: string, size?: number): string;
+export declare function svgToDataUrl(svg: string): string;
+//# sourceMappingURL=svg.d.ts.map

package/dist/core/svg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"svg.d.ts","sourceRoot":"","sources":["../../src/core/svg.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAqOxD,wBAAgB,eAAe,CAC7B,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,EACd,IAAI,GAAE,MAAqB,GAC1B,MAAM,CAQR;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/core/types.d.ts

@@ -0,0 +1,25 @@
+export type AvatarShape = "rounded-square" | "circle" | "square";
+export type AvatarPartCategory = "background" | "hair" | "skin" | "expression" | "beard" | "clothing" | "eyewear";
+export interface AvatarPart {
+    readonly id: string;
+    readonly label: string;
+    readonly labels?: Readonly<Record<"en" | "zh", string>>;
+    readonly svg: string;
+}
+export type AvatarPartMap = Readonly<Record<AvatarPartCategory, ReadonlyArray<AvatarPart>>>;
+export type AvatarParts = Readonly<Record<AvatarPartCategory, AvatarPart>>;
+export type ReadonlyAvatarPart = Readonly<AvatarPart>;
+export type AvatarPartCatalog = Readonly<Record<AvatarPartCategory, ReadonlyArray<ReadonlyAvatarPart>>>;
+export interface AvatarOptions {
+    shape?: AvatarShape;
+    size?: number;
+    title?: string;
+}
+export interface AvatarResult {
+    readonly hash: string;
+    readonly svg: string;
+    readonly url: string;
+    readonly shape: AvatarShape;
+    readonly parts: AvatarParts;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjE,MAAM,MAAM,kBAAkB,GAC1B,YAAY,GACZ,MAAM,GACN,MAAM,GACN,YAAY,GACZ,OAAO,GACP,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACxD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;AAC5F,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,UAAU,CAAC,CAAC,CAAC;AAC3E,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;AACtD,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;AAExG,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { AvatarOptions, AvatarPartCatalog, AvatarPart, AvatarPartCategory, AvatarPartMap, AvatarParts, ReadonlyAvatarPart, AvatarResult, AvatarShape } from './core/types';
+export { MAX_RANDOM_AVATAR_BATCH, generateAvatar, generateAvatarSvg, generateAvatarUrl, generateRandomAvatar, generateRandomAvatars, getAvatarParts, getTotalCombinations } from './core/generator';
+export { getAvatarPartCatalog } from './core/parts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACZ,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,oBAAoB,EACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC"}