claude-petpet 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+
+MIT License
+
+Copyright (c) 2026 Rayhan Noufal Arayilakath
+
+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,90 @@
+# claude-petpet
+
+Find UUIDs that produce specific [Claude Code](https://docs.anthropic.com/en/docs/claude-code) buddy companions.
+
+Claude Code assigns each user a procedurally generated buddy based on their
+account UUID. This tool brute-force searches random UUIDs to find ones that
+produce a buddy matching your desired species, rarity, stats, and cosmetics.
+
+## Install
+
+```bash
+bun install
+```
+
+## Usage
+
+Interactive mode (recommended):
+
+```bash
+bun run start
+# or
+bun src/cli.ts
+```
+
+The CLI walks you through selecting filters (species, rarity, eyes, hat, shiny,
+peak/dump stats, minimum total) then searches for matching UUIDs.
+
+### As a library
+
+```ts
+import { rollFrom, search } from "claude-petpet";
+
+// Roll a specific UUID
+const buddy = rollFrom("your-uuid-here");
+console.log(buddy);
+
+// Search with filters
+const results = search({
+  species: "axolotl",
+  rarity: "legendary",
+  limit: 3,
+  max: 10_000_000,
+});
+```
+
+### Applying a result
+
+Once you find a UUID you like:
+
+1. Open `~/.claude/.config.json`
+2. Set `oauthAccount.accountUuid` to the UUID from the search results
+3. Restart Claude Code
+
+> **Note:** Re-authenticating will overwrite the UUID back to your real one.
+
+## How it works
+
+Claude Code's buddy system seeds a Mulberry32 PRNG with a hash of
+`userId + salt`, then rolls rarity, species, eyes, hat, shiny status, and stat
+distribution from that deterministic sequence. This tool replicates that
+algorithm to predict the buddy for any given UUID without running Claude Code.
+
+## Legal notice
+
+The companion generation algorithm in this project was derived from source maps
+that were inadvertently published alongside Claude Code's publicly distributed
+client-side JavaScript. No access controls, obfuscation, or technological
+protection measures were circumvented — the source maps were openly served to
+end users via NPM. No proprietary source code was copied verbatim; the algorithm
+was reimplemented from the observed logic.
+
+Reading publicly served files does not constitute unauthorized access, and
+reimplementing a functional algorithm from publicly available materials is
+well-established as lawful under:
+
+- **No DMCA §1201 issue** — no technological protection measure was bypassed;
+  the source maps were publicly accessible without authentication
+- **Fair use doctrine** — functional algorithms are not copyrightable expression
+  (see _Oracle v. Google_, 593 U.S. 1 (2021))
+- **DMCA §1201(f)** — reverse engineering for interoperability is independently
+  permitted even when protection measures are present (not applicable here)
+- **EU Software Directive (2009/24/EC) Art. 6** — permits analysis for
+  interoperability
+
+This project is not affiliated with or endorsed by Anthropic, PBC. "Claude" and
+"Claude Code" are trademarks of Anthropic.
+
+## License
+
+[MIT](LICENSE) — Copyright (c) 2026 Rayhan Noufal Arayilakath

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "claude-petpet",
+  "version": "1.0.0",
+  "description": "Find UUIDs that produce specific Claude Code buddy companions",
+  "keywords": [
+    "buddy",
+    "bun",
+    "claude",
+    "claude-code",
+    "companion",
+    "petpet"
+  ],
+  "homepage": "https://github.com/rayhanadev/claude-petpet#readme",
+  "bugs": {
+    "url": "https://github.com/rayhanadev/claude-petpet/issues"
+  },
+  "license": "MIT",
+  "author": "Rayhan Noufal Arayilakath",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rayhanadev/claude-petpet.git"
+  },
+  "bin": {
+    "claude-petpet": "src/cli.ts"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "start": "bun src/cli.ts",
+    "lint": "oxlint --type-aware",
+    "format": "oxfmt",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "oxfmt": "^0.43.0",
+    "oxlint": "^1.58.0",
+    "oxlint-tsgolint": "^0.18.1"
+  },
+  "peerDependencies": {
+    "typescript": "^6"
+  },
+  "engines": {
+    "bun": ">=1.2"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,286 @@
+#!/usr/bin/env bun
+// CLI for finding UUIDs that produce specific Claude Code buddy companions.
+
+import * as p from "@clack/prompts";
+
+import { RARITIES, SPECIES, EYES, HATS, STAT_NAMES } from "./enums.ts";
+import { STARS, YIELD_EVERY } from "./consts.ts";
+import { rollFrom, matchesFilters } from "./helpers.ts";
+import { renderSprite } from "./sprites.ts";
+import { c } from "./color.ts";
+import type { Rarity, StatName, SearchFilters, SearchResult } from "./types.ts";
+
+const NONE = "__none__";
+
+async function promptFilters() {
+  return p.group(
+    {
+      species: () =>
+        p.select({
+          message: "Species?",
+          options: [
+            { value: NONE, label: "Any", hint: "no filter" },
+            ...SPECIES.map((s) => ({ value: s, label: s })),
+          ],
+          initialValue: NONE,
+        }),
+
+      rarity: () =>
+        p.select({
+          message: "Rarity?",
+          options: [
+            { value: NONE, label: "Any", hint: "no filter" },
+            ...RARITIES.map((r) => ({ value: r, label: `${STARS[r]}  ${r}` })),
+          ],
+          initialValue: NONE,
+        }),
+
+      eye: () =>
+        p.select({
+          message: "Eye style?",
+          options: [
+            { value: NONE, label: "Any", hint: "no filter" },
+            ...EYES.map((e) => ({ value: e, label: e })),
+          ],
+          initialValue: NONE,
+        }),
+
+      hat: () =>
+        p.select({
+          message: "Hat?",
+          options: [
+            { value: NONE, label: "Any", hint: "no filter" },
+            ...HATS.map((h) => ({ value: h, label: h })),
+          ],
+          initialValue: NONE,
+        }),
+
+      shiny: () =>
+        p.confirm({
+          message: "Must be shiny?",
+          initialValue: false,
+        }),
+
+      peak: () =>
+        p.select({
+          message: "Peak stat?",
+          options: [
+            { value: NONE, label: "Any", hint: "no filter" },
+            ...STAT_NAMES.map((s) => ({ value: s, label: s })),
+          ],
+          initialValue: NONE,
+        }),
+
+      dump: ({ results }) =>
+        p.select({
+          message: "Dump stat?",
+          options: [
+            { value: NONE, label: "Any", hint: "no filter" },
+            ...STAT_NAMES.filter(
+              (s) => s !== results.peak || (results.peak as string) === NONE,
+            ).map((s) => ({
+              value: s,
+              label: s,
+            })),
+          ],
+          initialValue: NONE,
+        }),
+
+      minTotal: () =>
+        p.text({
+          message: "Minimum total stats? (0-500)",
+          placeholder: "none",
+          validate: (v) => {
+            if (!v) return;
+            const n = parseInt(v, 10);
+            if (isNaN(n) || n < 0 || n > 500) return "Must be a number between 0 and 500";
+          },
+        }),
+
+      limit: () =>
+        p.text({
+          message: "How many results?",
+          initialValue: "5",
+          validate: (v) => {
+            if (!v) return "Required";
+            const n = parseInt(v, 10);
+            if (isNaN(n) || n < 1 || n > 100) return "Must be a number between 1 and 100";
+          },
+        }),
+
+      max: () =>
+        p.text({
+          message: "Max seeds to search?",
+          initialValue: "100000000",
+          validate: (v) => {
+            if (!v) return "Required";
+            const n = parseInt(v, 10);
+            if (isNaN(n) || n < 1) return "Must be a positive number";
+          },
+        }),
+    },
+    {
+      onCancel: () => {
+        p.cancel("Search cancelled.");
+        process.exit(0);
+      },
+    },
+  );
+}
+
+function parseFilters(raw: Awaited<ReturnType<typeof promptFilters>>): SearchFilters {
+  return {
+    species: raw.species !== NONE ? raw.species : undefined,
+    rarity: (raw.rarity !== NONE ? raw.rarity : undefined) as Rarity | undefined,
+    eye: raw.eye !== NONE ? raw.eye : undefined,
+    hat: raw.hat !== NONE ? raw.hat : undefined,
+    shiny: raw.shiny || undefined,
+    peak: (raw.peak !== NONE ? raw.peak : undefined) as StatName | undefined,
+    dump: (raw.dump !== NONE ? raw.dump : undefined) as StatName | undefined,
+    minTotal: raw.minTotal ? parseInt(raw.minTotal, 10) : undefined,
+    limit: parseInt(raw.limit, 10),
+    max: parseInt(raw.max, 10),
+  };
+}
+
+function formatSummary(filters: SearchFilters): string {
+  const parts: string[] = [];
+  if (filters.species) parts.push(`species=${filters.species}`);
+  if (filters.rarity) parts.push(`rarity=${filters.rarity}`);
+  if (filters.eye) parts.push(`eye=${filters.eye}`);
+  if (filters.hat) parts.push(`hat=${filters.hat}`);
+  if (filters.shiny) parts.push("shiny=true");
+  if (filters.peak) parts.push(`peak=${filters.peak}`);
+  if (filters.dump) parts.push(`dump=${filters.dump}`);
+  if (filters.minTotal) parts.push(`min-total=${filters.minTotal}`);
+  return parts.join(", ") || "(any)";
+}
+
+async function searchWithProgress(
+  filters: SearchFilters,
+): Promise<{ results: SearchResult[]; searched: number }> {
+  const s = p.spinner({ indicator: "timer" });
+  s.start("Searching...");
+
+  const results: SearchResult[] = [];
+  let searched = 0;
+
+  for (let i = 0; i < filters.max; i++) {
+    if (i % YIELD_EVERY === 0 && i > 0) {
+      s.message(`Found ${results.length} match(es), ${i.toLocaleString()} searched`);
+      await Bun.sleep(0);
+    }
+
+    const uuid = crypto.randomUUID();
+    const roll = rollFrom(uuid);
+
+    if (!matchesFilters(roll, filters)) continue;
+
+    results.push({ ...roll, uuid });
+    results.sort((a, b) => b.total - a.total);
+    if (results.length > filters.limit) results.length = filters.limit;
+
+    searched = i + 1;
+    if (results.length >= filters.limit) break;
+  }
+
+  searched = searched || filters.max;
+  s.stop(`Searched ${searched.toLocaleString()} seeds`);
+
+  return { results, searched };
+}
+
+function padVisual(s: string, width: number): string {
+  return s + " ".repeat(Math.max(0, width - Bun.stringWidth(s)));
+}
+
+function printResult(r: SearchResult) {
+  const rarityColor =
+    r.rarity === "legendary"
+      ? c.yellow
+      : r.rarity === "epic"
+        ? c.magenta
+        : r.rarity === "rare"
+          ? c.blue
+          : r.rarity === "uncommon"
+            ? c.green
+            : c.dim;
+
+  const shinyColor = r.shiny ? c.yellow : (s: string) => s;
+
+  const header = [
+    rarityColor(STARS[r.rarity]),
+    rarityColor(r.rarity.toUpperCase()),
+    c.bold(r.species),
+    r.eye,
+    r.hat !== "none" ? c.cyan(`[${r.hat}]`) : "",
+    r.shiny ? c.yellow("✨SHINY") : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const statLine = STAT_NAMES.map((s) => {
+    const tag = s === r.peak ? c.green("↑") : s === r.dump ? c.red("↓") : " ";
+    return `${c.dim(s)}: ${String(r.stats[s]).padStart(3)}${tag}`;
+  }).join("  ");
+
+  const infoLines = [
+    header,
+    statLine,
+    `${c.dim("Total:")} ${r.total}/500`,
+    `${c.dim("UUID:")}  ${c.cyan(r.uuid)}`,
+  ];
+
+  // Render sprite and colorize it
+  const sprite = renderSprite(r).map((line) => shinyColor(line));
+  const spriteWidth = 14;
+
+  // Pad both sides to equal height
+  const height = Math.max(sprite.length, infoLines.length);
+  while (sprite.length < height) sprite.push(" ".repeat(12));
+  while (infoLines.length < height) infoLines.push("");
+
+  // Combine sprite + info side by side
+  const combined = sprite
+    .map((spriteLine, i) => {
+      const paddedSprite = padVisual(spriteLine, spriteWidth);
+      return `  ${paddedSprite}${infoLines[i]}`;
+    })
+    .join("\n");
+
+  console.log();
+  console.log(combined);
+}
+
+async function main() {
+  p.intro(c.bgCyanBlack(" claude-petpet "));
+
+  const raw = await promptFilters();
+  const filters = parseFilters(raw);
+
+  p.log.info(
+    `Searching for: ${c.cyan(formatSummary(filters))} ${c.dim(`(top ${filters.limit}, up to ${filters.max.toLocaleString()} seeds)`)}`,
+  );
+
+  const { results } = await searchWithProgress(filters);
+
+  if (results.length === 0) {
+    p.log.warn("No matches found. Try relaxing filters or increasing max seeds.");
+    p.outro("Done.");
+    return;
+  }
+
+  p.log.success(`Found ${c.green(String(results.length))} match${results.length > 1 ? "es" : ""}!`);
+
+  for (const r of results) {
+    printResult(r);
+  }
+
+  p.log.info(
+    "To use: edit ~/.claude/.config.json → set oauthAccount.accountUuid to the UUID above.",
+  );
+  p.log.warn("Re-authenticating will overwrite it back to your real UUID.");
+  p.outro(c.green("Happy hunting!"));
+}
+
+void main();

package/src/color.ts

@@ -0,0 +1,31 @@
+const RESET = "\x1b[0m";
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+
+function fg(cssColor: string) {
+  return (text: string) => {
+    const ansi = Bun.color(cssColor, "ansi");
+    return ansi ? `${ansi}${text}${RESET}` : text;
+  };
+}
+
+function bgFg(bgCss: string, fgCss: string) {
+  return (text: string) => {
+    const bgAnsi = Bun.color(bgCss, "ansi")?.replace("[38;", "[48;");
+    const fgAnsi = Bun.color(fgCss, "ansi");
+    if (!bgAnsi || !fgAnsi) return text;
+    return `${bgAnsi}${fgAnsi}${text}${RESET}`;
+  };
+}
+
+export const c = {
+  bold: (text: string) => `${BOLD}${text}${RESET}`,
+  dim: (text: string) => `${DIM}${text}${RESET}`,
+  red: fg("red"),
+  green: fg("lime"),
+  blue: fg("dodgerblue"),
+  yellow: fg("yellow"),
+  magenta: fg("magenta"),
+  cyan: fg("cyan"),
+  bgCyanBlack: bgFg("cyan", "black"),
+};

package/src/consts.ts

@@ -0,0 +1,29 @@
+import type { Rarity } from "./types.ts";
+
+export const SALT = "friend-2026-401";
+
+export const RARITY_WEIGHTS: Record<Rarity, number> = {
+  common: 60,
+  uncommon: 25,
+  rare: 10,
+  epic: 4,
+  legendary: 1,
+};
+
+export const RARITY_FLOOR: Record<Rarity, number> = {
+  common: 5,
+  uncommon: 15,
+  rare: 25,
+  epic: 35,
+  legendary: 50,
+};
+
+export const STARS: Record<Rarity, string> = {
+  common: "★",
+  uncommon: "★★",
+  rare: "★★★",
+  epic: "★★★★",
+  legendary: "★★★★★",
+};
+
+export const YIELD_EVERY = 50_000;

package/src/enums.ts

@@ -0,0 +1,37 @@
+export const RARITIES = ["common", "uncommon", "rare", "epic", "legendary"] as const;
+
+export const SPECIES = [
+  "duck",
+  "goose",
+  "blob",
+  "cat",
+  "dragon",
+  "octopus",
+  "owl",
+  "penguin",
+  "turtle",
+  "snail",
+  "ghost",
+  "axolotl",
+  "capybara",
+  "cactus",
+  "robot",
+  "rabbit",
+  "mushroom",
+  "chonk",
+] as const;
+
+export const EYES = ["·", "✦", "×", "◉", "@", "°"] as const;
+
+export const HATS = [
+  "none",
+  "crown",
+  "tophat",
+  "propeller",
+  "halo",
+  "wizard",
+  "beanie",
+  "tinyduck",
+] as const;
+
+export const STAT_NAMES = ["DEBUGGING", "PATIENCE", "CHAOS", "WISDOM", "SNARK"] as const;

package/src/helpers.ts

@@ -0,0 +1,104 @@
+import { RARITIES, SPECIES, HATS, EYES, STAT_NAMES } from "./enums.ts";
+import { SALT, RARITY_WEIGHTS, RARITY_FLOOR } from "./consts.ts";
+import type { Rarity, StatName, Roll, SearchFilters, SearchResult } from "./types.ts";
+
+// Mulberry32 PRNG — deterministic 32-bit PRNG matching the companion
+// generation algorithm used by Claude Code's buddy system.
+export function mulberry32(seed: number): () => number {
+  let a = seed >>> 0;
+  return function () {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export function hashString(s: string): number {
+  if (typeof Bun !== "undefined") {
+    return Number(BigInt(Bun.hash(s)) & 0xffffffffn);
+  }
+  // FNV-1a fallback for non-Bun runtimes
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+
+export function pick<T>(rng: () => number, arr: readonly T[]): T {
+  return arr[Math.floor(rng() * arr.length)]!;
+}
+
+export function rollRarity(rng: () => number): Rarity {
+  const total = Object.values(RARITY_WEIGHTS).reduce((a, b) => a + b, 0);
+  let roll = rng() * total;
+  for (const rarity of RARITIES) {
+    roll -= RARITY_WEIGHTS[rarity];
+    if (roll < 0) return rarity;
+  }
+  return "common";
+}
+
+export function rollStats(rng: () => number, rarity: Rarity) {
+  const floor = RARITY_FLOOR[rarity];
+  const peak = pick(rng, STAT_NAMES);
+  let dump = pick(rng, STAT_NAMES);
+  while (dump === peak) dump = pick(rng, STAT_NAMES);
+
+  const stats = {} as Record<StatName, number>;
+  for (const name of STAT_NAMES) {
+    if (name === peak) {
+      stats[name] = Math.min(100, floor + 50 + Math.floor(rng() * 30));
+    } else if (name === dump) {
+      stats[name] = Math.max(1, floor - 10 + Math.floor(rng() * 15));
+    } else {
+      stats[name] = floor + Math.floor(rng() * 40);
+    }
+  }
+  return { stats, peak, dump };
+}
+
+export function rollFrom(userId: string): Roll {
+  const rng = mulberry32(hashString(userId + SALT));
+  const rarity = rollRarity(rng);
+  const species = pick(rng, SPECIES);
+  const eye = pick(rng, EYES);
+  const hat = rarity === "common" ? "none" : pick(rng, HATS);
+  const shiny = rng() < 0.01;
+  const { stats, peak, dump } = rollStats(rng, rarity);
+  const total = Object.values(stats).reduce((a, b) => a + b, 0);
+  return { rarity, species, eye, hat, shiny, stats, peak, dump, total };
+}
+
+export function matchesFilters(roll: Roll, filters: SearchFilters): boolean {
+  if (filters.species && roll.species !== filters.species) return false;
+  if (filters.rarity && roll.rarity !== filters.rarity) return false;
+  if (filters.eye && roll.eye !== filters.eye) return false;
+  if (filters.hat && roll.hat !== filters.hat) return false;
+  if (filters.shiny && !roll.shiny) return false;
+  if (filters.peak && roll.peak !== filters.peak) return false;
+  if (filters.dump && roll.dump !== filters.dump) return false;
+  if (filters.minTotal && roll.total < filters.minTotal) return false;
+  return true;
+}
+
+export function search(filters: SearchFilters): SearchResult[] {
+  const results: SearchResult[] = [];
+
+  for (let i = 0; i < filters.max; i++) {
+    const uuid = crypto.randomUUID();
+    const roll = rollFrom(uuid);
+
+    if (!matchesFilters(roll, filters)) continue;
+
+    results.push({ ...roll, uuid });
+    results.sort((a, b) => b.total - a.total);
+    if (results.length > filters.limit) results.length = filters.limit;
+    if (results.length >= filters.limit) break;
+  }
+
+  return results;
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { RARITIES, SPECIES, EYES, HATS, STAT_NAMES } from "./enums.ts";
+export { SALT, RARITY_WEIGHTS, RARITY_FLOOR, STARS } from "./consts.ts";
+export {
+  mulberry32,
+  hashString,
+  pick,
+  rollRarity,
+  rollStats,
+  rollFrom,
+  matchesFilters,
+  search,
+} from "./helpers.ts";
+export { renderSprite } from "./sprites.ts";
+export type { Rarity, StatName, Roll, SearchFilters, SearchResult } from "./types.ts";

package/src/sprites.ts

@@ -0,0 +1,54 @@
+import type { Roll } from "./types.ts";
+
+// Sprite bodies — frame 0 only (static display).
+// Each sprite is 5 lines tall, 12 wide (after {E} → 1-char substitution).
+// Line 0 is the hat slot — blank unless a hat is applied.
+const BODIES: Record<string, string[]> = {
+  duck: ["            ", "    __      ", "  <({E} )___  ", "   (  ._>   ", "    `--´    "],
+  goose: ["            ", "     ({E}>    ", "     ||     ", "   _(__)_   ", "    ^^^^    "],
+  blob: ["            ", "   .----.   ", "  ( {E}  {E} )  ", "  (      )  ", "   `----´   "],
+  cat: ["            ", "   /\\_/\\    ", "  ( {E}   {E})  ", "  (  ω  )   ", '  (")_(")   '],
+  dragon: ["            ", "  /^\\  /^\\  ", " <  {E}  {E}  > ", " (   ~~   ) ", "  `-vvvv-´  "],
+  octopus: ["            ", "   .----.   ", "  ( {E}  {E} )  ", "  (______)  ", "  /\\/\\/\\/\\  "],
+  owl: ["            ", "   /\\  /\\   ", "  (({E})({E}))  ", "  (  ><  )  ", "   `----´   "],
+  penguin: ["            ", "  .---.     ", "  ({E}>{E})     ", " /(   )\\    ", "  `---´     "],
+  turtle: ["            ", "   _,--._   ", "  ( {E}  {E} )  ", " /[______]\\ ", "  ``    ``  "],
+  snail: ["            ", " {E}    .--.  ", "  \\  ( @ )  ", "   \\_`--´   ", "  ~~~~~~~   "],
+  ghost: ["            ", "   .----.   ", "  / {E}  {E} \\  ", "  |      |  ", "  ~`~``~`~  "],
+  axolotl: ["            ", "}~(______)~{", "}~({E} .. {E})~{", "  ( .--. )  ", "  (_/  \\_)  "],
+  capybara: ["            ", "  n______n  ", " ( {E}    {E} ) ", " (   oo   ) ", "  `------´  "],
+  cactus: ["            ", " n  ____  n ", " | |{E}  {E}| | ", " |_|    |_| ", "   |    |   "],
+  robot: ["            ", "   .[||].   ", "  [ {E}  {E} ]  ", "  [ ==== ]  ", "  `------´  "],
+  rabbit: ["            ", "   (\\__/)   ", "  ( {E}  {E} )  ", " =(  ..  )= ", '  (")__(")  '],
+  mushroom: ["            ", " .-o-OO-o-. ", "(__________)", "   |{E}  {E}|   ", "   |____|   "],
+  chonk: ["            ", "  /\\    /\\  ", " ( {E}    {E} ) ", " (   ..   ) ", "  `------´  "],
+};
+
+const HAT_LINES: Record<string, string> = {
+  none: "",
+  crown: "   \\^^^/    ",
+  tophat: "   [___]    ",
+  propeller: "    -+-     ",
+  halo: "   (   )    ",
+  wizard: "    /^\\     ",
+  beanie: "   (___)    ",
+  tinyduck: "    ,>      ",
+};
+
+export function renderSprite(roll: Roll): string[] {
+  const body = (BODIES[roll.species] ?? BODIES["blob"]!).map((line) =>
+    line.replaceAll("{E}", roll.eye),
+  );
+  const lines = [...body];
+
+  if (roll.hat !== "none" && !lines[0]!.trim()) {
+    lines[0] = HAT_LINES[roll.hat] ?? "";
+  }
+
+  // Drop blank hat row when no hat is present
+  if (!lines[0]!.trim()) {
+    lines.shift();
+  }
+
+  return lines;
+}

package/src/types.ts

@@ -0,0 +1,31 @@
+import type { RARITIES, STAT_NAMES } from "./enums.ts";
+
+export type Rarity = (typeof RARITIES)[number];
+export type StatName = (typeof STAT_NAMES)[number];
+
+export type Roll = {
+  rarity: Rarity;
+  species: string;
+  eye: string;
+  hat: string;
+  shiny: boolean;
+  stats: Record<StatName, number>;
+  peak: StatName;
+  dump: StatName;
+  total: number;
+};
+
+export type SearchFilters = {
+  species?: string;
+  rarity?: Rarity;
+  eye?: string;
+  hat?: string;
+  shiny?: boolean;
+  peak?: StatName;
+  dump?: StatName;
+  minTotal?: number;
+  limit: number;
+  max: number;
+};
+
+export type SearchResult = Roll & { uuid: string };