# Planet Avatar LLM Context

Planet Avatar is a TypeScript library for deterministic planet-style SVG avatars.

Package name: planet-avatar
Version: 0.1.0
License: MIT
Website: http://planet-avatar.vikingz.me/
Docs: http://planet-avatar.vikingz.me/getting-started/
LLM context URL: http://planet-avatar.vikingz.me/llm.txt
Primary language: TypeScript
Docs: Astro + Starlight
Tests: Vitest
Build: tsup

## What It Does

Planet Avatar converts a string or number seed into a stable, self-contained SVG planet. The same seed and options produce the same avatar. It supports vanilla JavaScript, React, and Vue.

## Public Exports

Core import:

```ts
import {
  createPlanetAvatar,
  createPlanetAvatarDataUri,
  mountPlanetAvatar,
  VARIANT_NAMES,
  VARIANTS
} from 'planet-avatar'
```

React import:

```tsx
import { PlanetAvatar, usePlanetAvatar } from 'planet-avatar/react'
```

Vue import:

```vue
import { PlanetAvatar, usePlanetAvatar } from 'planet-avatar/vue'
```

## Options

```ts
type PlanetAvatarOptions = {
  seed: string | number
  size?: number
  variant?: 'auto' | 'void' | 'drift' | 'mira' | 'flux' | 'luna' | 'orbit' | 'sol'
  palette?: 'auto' | string[]
  rings?: boolean | 'auto'
  background?: 'transparent' | string
  title?: string
}
```

Defaults:

- `size`: `128`
- `variant`: `auto`
- `background`: `transparent`
- `rings`: based on selected variant unless explicitly set

Accessibility:

- If `title` is set, SVG includes `<title>` and `aria-labelledby`.
- If `title` is omitted, SVG is marked `aria-hidden="true"`.

## Key Files

- `src/core/svg.ts`: core SVG generation and DOM mounting.
- `src/core/palettes.ts`: named variants and palettes.
- `src/core/random.ts`: deterministic seed hashing and PRNG.
- `src/core/types.ts`: public TypeScript types.
- `src/react/index.tsx`: React component and hook.
- `src/vue/index.ts`: Vue component and composable.
- `docs/src/pages/index.astro`: custom landing page.
- `docs/src/content/docs`: Starlight docs.
- `tests`: core and adapter tests.

## Common Commands

```bash
npm install
npm run typecheck
npm run test
npm run build
npm run docs:build
npm run check
```

Release:

```bash
npm run release:pack
npm run release:dry
npm run release:publish
```

Cloudflare Pages:

```bash
npm run pages:preview
npm run pages:deploy
```

## Development Rules

- Edit source files, not generated `dist` output.
- Keep React and Vue optional peer dependencies.
- Keep generated SVG self-contained.
- Do not change public option names or variant names without updating tests and docs.
- Run `npm run check` before release-level changes.