invadrs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Goodwin
+
+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,58 @@
+# invadrs
+
+Deterministic space-invaders-style pixel avatars from any string. Zero
+dependencies. Same id in, same avatar out, forever.
+
+![invadrs sample avatars — the invadr() and spawn() primitives, shown across every built-in palette](assets/preview.png)
+
+```ts
+import { invadr, spawn, dataUri } from "invadrs";
+
+invadr("matt");                       // hand-drawn creature, SVG string
+spawn("matt");                        // procedural creature, SVG string
+invadr("matt", { palette: "sunset", size: 32 });
+dataUri(invadr("matt"));              // data:image/svg+xml,...
+```
+
+## Primitives
+
+- `invadr(id, options?)` — one of 16 hand-drawn creatures.
+- `spawn(id, options?)` — a unique procedural symmetric creature.
+
+## Options
+
+`{ size?, palette?, padding?, background?, title?, resolution? }`
+(`resolution` is `spawn`-only; when `size` is omitted no `width`/`height` is set,
+so host CSS controls the size.)
+
+## Palettes & theming
+
+Built-ins, each its own colour mood: `tokyoNight` (default, balanced rainbow),
+`neon` (electric, dark-bg), `sunset` (warm), `ocean` (cool), `forest`
+(greens/earth), `mono` (grayscale). Pass a name, your own `string[]`, a full
+`{ colors, background }` object, or `"css-vars"` to emit `var(--accent)`… fills
+that follow your theme.
+
+```ts
+import { palettes } from "invadrs";
+const brand = { colors: [...palettes.tokyoNight.colors, "#ff00aa"] };
+invadr("matt", { palette: brand });
+```
+
+## React
+
+```tsx
+import { Invadr, Spawn, InvadrsProvider } from "invadrs/react";
+
+<Invadr id="matt" palette="css-vars" />   {/* hand-drawn creature */}
+<Spawn id="matt" />                         {/* procedural creature */}
+
+{/* app-wide defaults; explicit props on a component win */}
+<InvadrsProvider palette="tokyoNight" size={20}>…</InvadrsProvider>
+```
+
+## Stability contract
+
+The hash, the order of the built-in creatures, the procedural generator, and the
+`css-vars` color order are **frozen**. Changing any of them alters existing
+avatars and is only ever done in a major release.

package/dist/chunk-5SOVCTHT.js

@@ -0,0 +1,166 @@
+// src/hash.ts
+function hashStr(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+
+// src/palettes.ts
+var palettes = {
+  // balanced rainbow (default) — the Tokyo Night editor colours
+  tokyoNight: { colors: ["#7aa2f7", "#9ece6a", "#e0af68", "#bb9af7", "#7dcfff", "#f7768e"] },
+  // electric high-saturation — reads best on dark backgrounds
+  neon: { colors: ["#ff2e97", "#00eaff", "#39ff14", "#b026ff", "#faff00", "#ff5900"] },
+  // warm only — crimson, vermilion, orange, gold, rose, deep red
+  sunset: { colors: ["#e5383b", "#ff6b35", "#f77f00", "#ffca3a", "#ff5c8a", "#c1121f"] },
+  // cool only — navy, teal, sky, seafoam, blue, aqua
+  ocean: { colors: ["#1d3557", "#2a9d8f", "#48cae4", "#56e39f", "#4361ee", "#7bdff2"] },
+  // greens and earth — pine, leaf, lime-olive, fern, bark, tan
+  forest: { colors: ["#386641", "#6a994e", "#a7c957", "#588157", "#b08968", "#dda15e"] },
+  // grayscale
+  mono: { colors: ["#e6e6e6", "#bdbdbd", "#9e9e9e", "#757575", "#bdbdbd", "#e6e6e6"] }
+};
+var CSS_VARS = {
+  colors: ["var(--accent)", "var(--green)", "var(--amber)", "var(--purple)", "var(--cyan)", "var(--red)"]
+};
+function resolvePalette(input) {
+  if (input === void 0) return palettes.tokyoNight;
+  if (input === "css-vars") return CSS_VARS;
+  if (typeof input === "string") return palettes[input];
+  if (Array.isArray(input)) return { colors: input };
+  return input;
+}
+function pickColor(seed, palette) {
+  return palette.colors[(seed >>> 4) % palette.colors.length];
+}
+
+// src/render.ts
+function escapeXml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function resolveCommon(seed, grid, options) {
+  const palette = resolvePalette(options?.palette);
+  return {
+    grid,
+    color: pickColor(seed, palette),
+    size: options?.size,
+    padding: options?.padding ?? 1,
+    background: options?.background ?? palette.background,
+    title: options?.title
+  };
+}
+function renderSvg(s) {
+  const n = s.grid.length;
+  const min = -s.padding;
+  const span = n + s.padding * 2;
+  const rects = [];
+  if (s.background) {
+    rects.push(`<rect x="${min}" y="${min}" width="${span}" height="${span}" fill="${s.background}"/>`);
+  }
+  for (let y = 0; y < n; y++) {
+    for (let x = 0; x < n; x++) {
+      if (s.grid[y][x]) rects.push(`<rect x="${x}" y="${y}" width="1" height="1"/>`);
+    }
+  }
+  const dims = s.size !== void 0 ? ` width="${s.size}" height="${s.size}"` : "";
+  const a11y = s.title ? `role="img"` : `aria-hidden="true"`;
+  const titleEl = s.title ? `<title>${escapeXml(s.title)}</title>` : "";
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${min} ${min} ${span} ${span}"${dims} shape-rendering="crispEdges" fill="${s.color}" ${a11y}>${titleEl}${rects.join("")}</svg>`;
+}
+function dataUri(svg) {
+  return "data:image/svg+xml," + encodeURIComponent(svg);
+}
+
+// src/invadr.ts
+var INVADR_SPRITES = [
+  [24, 60, 126, 219, 255, 36, 90, 165],
+  // invader
+  [36, 126, 219, 255, 255, 102, 36, 66],
+  // crab
+  [60, 126, 219, 255, 255, 255, 255, 165],
+  // ghost
+  [60, 66, 165, 129, 165, 153, 66, 60],
+  // smiley
+  [24, 24, 126, 255, 255, 102, 102, 231],
+  // mech
+  [66, 36, 126, 219, 255, 165, 36, 66],
+  // alien
+  [231, 60, 126, 219, 255, 219, 126, 102],
+  // robot
+  [129, 195, 255, 219, 255, 255, 255, 165],
+  // cat
+  [60, 126, 255, 219, 255, 126, 90, 36],
+  // skull
+  [153, 126, 255, 219, 255, 255, 126, 165],
+  // beetle
+  [195, 255, 219, 255, 126, 60, 24, 36],
+  // owl
+  [36, 126, 255, 231, 255, 126, 24, 24],
+  // flower
+  [24, 60, 126, 255, 255, 126, 60, 24],
+  // gem
+  [102, 255, 255, 255, 126, 126, 60, 24],
+  // heart
+  [60, 126, 255, 255, 90, 24, 24, 60],
+  // mushroom
+  [36, 90, 255, 189, 255, 90, 165, 66]
+  // amoeba
+];
+function byteRowsToGrid(rows) {
+  return rows.map((row) => {
+    const cells = [];
+    for (let x = 0; x < 8; x++) cells.push((row & 128 >> x) !== 0);
+    return cells;
+  });
+}
+function invadrGrid(seed) {
+  return byteRowsToGrid(INVADR_SPRITES[seed % INVADR_SPRITES.length]);
+}
+function resolveInvadr(id, options) {
+  const seed = hashStr(id);
+  return resolveCommon(seed, invadrGrid(seed), options);
+}
+function invadr(id, options) {
+  return renderSvg(resolveInvadr(id, options));
+}
+
+// src/spawn.ts
+var DENSITY = 0.5;
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function() {
+    a = a + 1831565813 | 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;
+  };
+}
+function spawnGrid(seed, resolution) {
+  const n = resolution;
+  const half = n / 2;
+  const rng = mulberry32(seed);
+  const grid = [];
+  for (let y = 0; y < n; y++) {
+    const row = new Array(n).fill(false);
+    for (let x = 0; x < half; x++) {
+      const on = rng() < DENSITY;
+      row[x] = on;
+      row[n - 1 - x] = on;
+    }
+    grid.push(row);
+  }
+  return grid;
+}
+function resolveSpawn(id, options) {
+  const seed = hashStr(id);
+  const resolution = options?.resolution ?? 8;
+  return resolveCommon(seed, spawnGrid(seed, resolution), options);
+}
+function spawn(id, options) {
+  return renderSvg(resolveSpawn(id, options));
+}
+
+export { CSS_VARS, INVADR_SPRITES, dataUri, hashStr, invadr, palettes, pickColor, renderSvg, resolveInvadr, resolvePalette, resolveSpawn, spawn };

package/dist/index.cjs

@@ -0,0 +1,179 @@
+'use strict';
+
+// src/hash.ts
+function hashStr(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+
+// src/palettes.ts
+var palettes = {
+  // balanced rainbow (default) — the Tokyo Night editor colours
+  tokyoNight: { colors: ["#7aa2f7", "#9ece6a", "#e0af68", "#bb9af7", "#7dcfff", "#f7768e"] },
+  // electric high-saturation — reads best on dark backgrounds
+  neon: { colors: ["#ff2e97", "#00eaff", "#39ff14", "#b026ff", "#faff00", "#ff5900"] },
+  // warm only — crimson, vermilion, orange, gold, rose, deep red
+  sunset: { colors: ["#e5383b", "#ff6b35", "#f77f00", "#ffca3a", "#ff5c8a", "#c1121f"] },
+  // cool only — navy, teal, sky, seafoam, blue, aqua
+  ocean: { colors: ["#1d3557", "#2a9d8f", "#48cae4", "#56e39f", "#4361ee", "#7bdff2"] },
+  // greens and earth — pine, leaf, lime-olive, fern, bark, tan
+  forest: { colors: ["#386641", "#6a994e", "#a7c957", "#588157", "#b08968", "#dda15e"] },
+  // grayscale
+  mono: { colors: ["#e6e6e6", "#bdbdbd", "#9e9e9e", "#757575", "#bdbdbd", "#e6e6e6"] }
+};
+var CSS_VARS = {
+  colors: ["var(--accent)", "var(--green)", "var(--amber)", "var(--purple)", "var(--cyan)", "var(--red)"]
+};
+function resolvePalette(input) {
+  if (input === void 0) return palettes.tokyoNight;
+  if (input === "css-vars") return CSS_VARS;
+  if (typeof input === "string") return palettes[input];
+  if (Array.isArray(input)) return { colors: input };
+  return input;
+}
+function pickColor(seed, palette) {
+  return palette.colors[(seed >>> 4) % palette.colors.length];
+}
+
+// src/render.ts
+function escapeXml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function resolveCommon(seed, grid, options) {
+  const palette = resolvePalette(options?.palette);
+  return {
+    grid,
+    color: pickColor(seed, palette),
+    size: options?.size,
+    padding: options?.padding ?? 1,
+    background: options?.background ?? palette.background,
+    title: options?.title
+  };
+}
+function renderSvg(s) {
+  const n = s.grid.length;
+  const min = -s.padding;
+  const span = n + s.padding * 2;
+  const rects = [];
+  if (s.background) {
+    rects.push(`<rect x="${min}" y="${min}" width="${span}" height="${span}" fill="${s.background}"/>`);
+  }
+  for (let y = 0; y < n; y++) {
+    for (let x = 0; x < n; x++) {
+      if (s.grid[y][x]) rects.push(`<rect x="${x}" y="${y}" width="1" height="1"/>`);
+    }
+  }
+  const dims = s.size !== void 0 ? ` width="${s.size}" height="${s.size}"` : "";
+  const a11y = s.title ? `role="img"` : `aria-hidden="true"`;
+  const titleEl = s.title ? `<title>${escapeXml(s.title)}</title>` : "";
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${min} ${min} ${span} ${span}"${dims} shape-rendering="crispEdges" fill="${s.color}" ${a11y}>${titleEl}${rects.join("")}</svg>`;
+}
+function dataUri(svg) {
+  return "data:image/svg+xml," + encodeURIComponent(svg);
+}
+
+// src/invadr.ts
+var INVADR_SPRITES = [
+  [24, 60, 126, 219, 255, 36, 90, 165],
+  // invader
+  [36, 126, 219, 255, 255, 102, 36, 66],
+  // crab
+  [60, 126, 219, 255, 255, 255, 255, 165],
+  // ghost
+  [60, 66, 165, 129, 165, 153, 66, 60],
+  // smiley
+  [24, 24, 126, 255, 255, 102, 102, 231],
+  // mech
+  [66, 36, 126, 219, 255, 165, 36, 66],
+  // alien
+  [231, 60, 126, 219, 255, 219, 126, 102],
+  // robot
+  [129, 195, 255, 219, 255, 255, 255, 165],
+  // cat
+  [60, 126, 255, 219, 255, 126, 90, 36],
+  // skull
+  [153, 126, 255, 219, 255, 255, 126, 165],
+  // beetle
+  [195, 255, 219, 255, 126, 60, 24, 36],
+  // owl
+  [36, 126, 255, 231, 255, 126, 24, 24],
+  // flower
+  [24, 60, 126, 255, 255, 126, 60, 24],
+  // gem
+  [102, 255, 255, 255, 126, 126, 60, 24],
+  // heart
+  [60, 126, 255, 255, 90, 24, 24, 60],
+  // mushroom
+  [36, 90, 255, 189, 255, 90, 165, 66]
+  // amoeba
+];
+function byteRowsToGrid(rows) {
+  return rows.map((row) => {
+    const cells = [];
+    for (let x = 0; x < 8; x++) cells.push((row & 128 >> x) !== 0);
+    return cells;
+  });
+}
+function invadrGrid(seed) {
+  return byteRowsToGrid(INVADR_SPRITES[seed % INVADR_SPRITES.length]);
+}
+function resolveInvadr(id, options) {
+  const seed = hashStr(id);
+  return resolveCommon(seed, invadrGrid(seed), options);
+}
+function invadr(id, options) {
+  return renderSvg(resolveInvadr(id, options));
+}
+
+// src/spawn.ts
+var DENSITY = 0.5;
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function() {
+    a = a + 1831565813 | 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;
+  };
+}
+function spawnGrid(seed, resolution) {
+  const n = resolution;
+  const half = n / 2;
+  const rng = mulberry32(seed);
+  const grid = [];
+  for (let y = 0; y < n; y++) {
+    const row = new Array(n).fill(false);
+    for (let x = 0; x < half; x++) {
+      const on = rng() < DENSITY;
+      row[x] = on;
+      row[n - 1 - x] = on;
+    }
+    grid.push(row);
+  }
+  return grid;
+}
+function resolveSpawn(id, options) {
+  const seed = hashStr(id);
+  const resolution = options?.resolution ?? 8;
+  return resolveCommon(seed, spawnGrid(seed, resolution), options);
+}
+function spawn(id, options) {
+  return renderSvg(resolveSpawn(id, options));
+}
+
+exports.CSS_VARS = CSS_VARS;
+exports.INVADR_SPRITES = INVADR_SPRITES;
+exports.dataUri = dataUri;
+exports.hashStr = hashStr;
+exports.invadr = invadr;
+exports.palettes = palettes;
+exports.pickColor = pickColor;
+exports.renderSvg = renderSvg;
+exports.resolveInvadr = resolveInvadr;
+exports.resolvePalette = resolvePalette;
+exports.resolveSpawn = resolveSpawn;
+exports.spawn = spawn;

package/dist/index.d.cts

@@ -0,0 +1,48 @@
+import { G as Grid, S as SpriteOptions, P as Palette, a as PaletteName, b as PaletteInput } from './types-C4QooPnZ.cjs';
+
+/** A fully-resolved sprite: geometry + paint + presentation, ready to render. */
+type ResolvedSprite = {
+    grid: Grid;
+    color: string;
+    size?: number;
+    padding: number;
+    background?: string;
+    title?: string;
+};
+/** Render a ResolvedSprite to a standalone SVG string. */
+declare function renderSvg(s: ResolvedSprite): string;
+/** Wrap an SVG string as a data: URI usable in `src`/`background-image`. */
+declare function dataUri(svg: string): string;
+
+/** Hand-designed 8x8 creatures (one byte per row, MSB = left pixel).
+    Curated so every id reads as a deliberate sprite; each is left-right
+    symmetric. ORDER IS FROZEN — reordering changes users' avatars. */
+declare const INVADR_SPRITES: number[][];
+/** Resolve a hand-drawn creature for an id (structured form). */
+declare function resolveInvadr(id: string, options?: SpriteOptions): ResolvedSprite;
+/** A hand-drawn creature for an id, as an SVG string. */
+declare function invadr(id: string, options?: SpriteOptions): string;
+
+/** Resolve a procedural creature for an id (structured form). */
+declare function resolveSpawn(id: string, options?: SpriteOptions): ResolvedSprite;
+/** A procedural symmetric creature for an id, as an SVG string. */
+declare function spawn(id: string, options?: SpriteOptions): string;
+
+/** Built-in palettes. `tokyoNight` is the default and matches mr-board.
+    Each palette is its own colour mood (not the same rainbow re-shaded), so a
+    given id looks distinct from one palette to the next. */
+declare const palettes: Record<PaletteName, Palette>;
+/** Palette that emits CSS custom properties instead of literal colors so the
+    host theme drives the sprite color. Order is frozen for mr-board parity. */
+declare const CSS_VARS: Palette;
+/** Resolve any PaletteInput to a concrete Palette. */
+declare function resolvePalette(input?: PaletteInput): Palette;
+/** Deterministically pick a color from the palette for a given seed.
+    Uses `seed >>> 4` so it is independent of the sprite index (`seed % n`). */
+declare function pickColor(seed: number, palette: Palette): string;
+
+/** FNV-1a string hash -> unsigned 32-bit seed. Frozen: changing this changes
+    every avatar, so it is a semver-major change. */
+declare function hashStr(s: string): number;
+
+export { CSS_VARS, Grid, INVADR_SPRITES, Palette, PaletteInput, PaletteName, type ResolvedSprite, SpriteOptions, dataUri, hashStr, invadr, palettes, pickColor, renderSvg, resolveInvadr, resolvePalette, resolveSpawn, spawn };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { G as Grid, S as SpriteOptions, P as Palette, a as PaletteName, b as PaletteInput } from './types-C4QooPnZ.js';
+
+/** A fully-resolved sprite: geometry + paint + presentation, ready to render. */
+type ResolvedSprite = {
+    grid: Grid;
+    color: string;
+    size?: number;
+    padding: number;
+    background?: string;
+    title?: string;
+};
+/** Render a ResolvedSprite to a standalone SVG string. */
+declare function renderSvg(s: ResolvedSprite): string;
+/** Wrap an SVG string as a data: URI usable in `src`/`background-image`. */
+declare function dataUri(svg: string): string;
+
+/** Hand-designed 8x8 creatures (one byte per row, MSB = left pixel).
+    Curated so every id reads as a deliberate sprite; each is left-right
+    symmetric. ORDER IS FROZEN — reordering changes users' avatars. */
+declare const INVADR_SPRITES: number[][];
+/** Resolve a hand-drawn creature for an id (structured form). */
+declare function resolveInvadr(id: string, options?: SpriteOptions): ResolvedSprite;
+/** A hand-drawn creature for an id, as an SVG string. */
+declare function invadr(id: string, options?: SpriteOptions): string;
+
+/** Resolve a procedural creature for an id (structured form). */
+declare function resolveSpawn(id: string, options?: SpriteOptions): ResolvedSprite;
+/** A procedural symmetric creature for an id, as an SVG string. */
+declare function spawn(id: string, options?: SpriteOptions): string;
+
+/** Built-in palettes. `tokyoNight` is the default and matches mr-board.
+    Each palette is its own colour mood (not the same rainbow re-shaded), so a
+    given id looks distinct from one palette to the next. */
+declare const palettes: Record<PaletteName, Palette>;
+/** Palette that emits CSS custom properties instead of literal colors so the
+    host theme drives the sprite color. Order is frozen for mr-board parity. */
+declare const CSS_VARS: Palette;
+/** Resolve any PaletteInput to a concrete Palette. */
+declare function resolvePalette(input?: PaletteInput): Palette;
+/** Deterministically pick a color from the palette for a given seed.
+    Uses `seed >>> 4` so it is independent of the sprite index (`seed % n`). */
+declare function pickColor(seed: number, palette: Palette): string;
+
+/** FNV-1a string hash -> unsigned 32-bit seed. Frozen: changing this changes
+    every avatar, so it is a semver-major change. */
+declare function hashStr(s: string): number;
+
+export { CSS_VARS, Grid, INVADR_SPRITES, Palette, PaletteInput, PaletteName, type ResolvedSprite, SpriteOptions, dataUri, hashStr, invadr, palettes, pickColor, renderSvg, resolveInvadr, resolvePalette, resolveSpawn, spawn };

package/dist/index.js

@@ -0,0 +1 @@
+export { CSS_VARS, INVADR_SPRITES, dataUri, hashStr, invadr, palettes, pickColor, renderSvg, resolveInvadr, resolvePalette, resolveSpawn, spawn } from './chunk-5SOVCTHT.js';

package/dist/react/index.cjs

@@ -0,0 +1,195 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/react/index.tsx
+
+// src/hash.ts
+function hashStr(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+
+// src/palettes.ts
+var palettes = {
+  // balanced rainbow (default) — the Tokyo Night editor colours
+  tokyoNight: { colors: ["#7aa2f7", "#9ece6a", "#e0af68", "#bb9af7", "#7dcfff", "#f7768e"] },
+  // electric high-saturation — reads best on dark backgrounds
+  neon: { colors: ["#ff2e97", "#00eaff", "#39ff14", "#b026ff", "#faff00", "#ff5900"] },
+  // warm only — crimson, vermilion, orange, gold, rose, deep red
+  sunset: { colors: ["#e5383b", "#ff6b35", "#f77f00", "#ffca3a", "#ff5c8a", "#c1121f"] },
+  // cool only — navy, teal, sky, seafoam, blue, aqua
+  ocean: { colors: ["#1d3557", "#2a9d8f", "#48cae4", "#56e39f", "#4361ee", "#7bdff2"] },
+  // greens and earth — pine, leaf, lime-olive, fern, bark, tan
+  forest: { colors: ["#386641", "#6a994e", "#a7c957", "#588157", "#b08968", "#dda15e"] },
+  // grayscale
+  mono: { colors: ["#e6e6e6", "#bdbdbd", "#9e9e9e", "#757575", "#bdbdbd", "#e6e6e6"] }
+};
+var CSS_VARS = {
+  colors: ["var(--accent)", "var(--green)", "var(--amber)", "var(--purple)", "var(--cyan)", "var(--red)"]
+};
+function resolvePalette(input) {
+  if (input === void 0) return palettes.tokyoNight;
+  if (input === "css-vars") return CSS_VARS;
+  if (typeof input === "string") return palettes[input];
+  if (Array.isArray(input)) return { colors: input };
+  return input;
+}
+function pickColor(seed, palette) {
+  return palette.colors[(seed >>> 4) % palette.colors.length];
+}
+
+// src/render.ts
+function resolveCommon(seed, grid, options) {
+  const palette = resolvePalette(options?.palette);
+  return {
+    grid,
+    color: pickColor(seed, palette),
+    size: options?.size,
+    padding: options?.padding ?? 1,
+    background: options?.background ?? palette.background,
+    title: options?.title
+  };
+}
+
+// src/invadr.ts
+var INVADR_SPRITES = [
+  [24, 60, 126, 219, 255, 36, 90, 165],
+  // invader
+  [36, 126, 219, 255, 255, 102, 36, 66],
+  // crab
+  [60, 126, 219, 255, 255, 255, 255, 165],
+  // ghost
+  [60, 66, 165, 129, 165, 153, 66, 60],
+  // smiley
+  [24, 24, 126, 255, 255, 102, 102, 231],
+  // mech
+  [66, 36, 126, 219, 255, 165, 36, 66],
+  // alien
+  [231, 60, 126, 219, 255, 219, 126, 102],
+  // robot
+  [129, 195, 255, 219, 255, 255, 255, 165],
+  // cat
+  [60, 126, 255, 219, 255, 126, 90, 36],
+  // skull
+  [153, 126, 255, 219, 255, 255, 126, 165],
+  // beetle
+  [195, 255, 219, 255, 126, 60, 24, 36],
+  // owl
+  [36, 126, 255, 231, 255, 126, 24, 24],
+  // flower
+  [24, 60, 126, 255, 255, 126, 60, 24],
+  // gem
+  [102, 255, 255, 255, 126, 126, 60, 24],
+  // heart
+  [60, 126, 255, 255, 90, 24, 24, 60],
+  // mushroom
+  [36, 90, 255, 189, 255, 90, 165, 66]
+  // amoeba
+];
+function byteRowsToGrid(rows) {
+  return rows.map((row) => {
+    const cells = [];
+    for (let x = 0; x < 8; x++) cells.push((row & 128 >> x) !== 0);
+    return cells;
+  });
+}
+function invadrGrid(seed) {
+  return byteRowsToGrid(INVADR_SPRITES[seed % INVADR_SPRITES.length]);
+}
+function resolveInvadr(id, options) {
+  const seed = hashStr(id);
+  return resolveCommon(seed, invadrGrid(seed), options);
+}
+
+// src/spawn.ts
+var DENSITY = 0.5;
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return function() {
+    a = a + 1831565813 | 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;
+  };
+}
+function spawnGrid(seed, resolution) {
+  const n = resolution;
+  const half = n / 2;
+  const rng = mulberry32(seed);
+  const grid = [];
+  for (let y = 0; y < n; y++) {
+    const row = new Array(n).fill(false);
+    for (let x = 0; x < half; x++) {
+      const on = rng() < DENSITY;
+      row[x] = on;
+      row[n - 1 - x] = on;
+    }
+    grid.push(row);
+  }
+  return grid;
+}
+function resolveSpawn(id, options) {
+  const seed = hashStr(id);
+  const resolution = options?.resolution ?? 8;
+  return resolveCommon(seed, spawnGrid(seed, resolution), options);
+}
+var InvadrsContext = react.createContext({});
+function InvadrsProvider({ children, ...defaults }) {
+  const inherited = react.useContext(InvadrsContext);
+  return /* @__PURE__ */ jsxRuntime.jsx(InvadrsContext.Provider, { value: { ...inherited, ...defaults }, children });
+}
+function renderCells(s) {
+  const nodes = [];
+  const n = s.grid.length;
+  if (s.background) {
+    nodes.push(
+      /* @__PURE__ */ jsxRuntime.jsx("rect", { x: -s.padding, y: -s.padding, width: n + s.padding * 2, height: n + s.padding * 2, fill: s.background }, "bg")
+    );
+  }
+  for (let y = 0; y < n; y++) {
+    for (let x = 0; x < n; x++) {
+      if (s.grid[y][x]) nodes.push(/* @__PURE__ */ jsxRuntime.jsx("rect", { x, y, width: 1, height: 1 }, `${x},${y}`));
+    }
+  }
+  return nodes;
+}
+function svgFrom(resolved, className) {
+  const n = resolved.grid.length;
+  const min = -resolved.padding;
+  const span = n + resolved.padding * 2;
+  const dims = resolved.size !== void 0 ? { width: resolved.size, height: resolved.size } : {};
+  const a11y = resolved.title ? { role: "img" } : { "aria-hidden": true };
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "svg",
+    {
+      className,
+      viewBox: `${min} ${min} ${span} ${span}`,
+      ...dims,
+      shapeRendering: "crispEdges",
+      fill: resolved.color,
+      ...a11y,
+      children: [
+        resolved.title ? /* @__PURE__ */ jsxRuntime.jsx("title", { children: resolved.title }) : null,
+        renderCells(resolved)
+      ]
+    }
+  );
+}
+function Invadr(props) {
+  const { id, className, ...options } = { ...react.useContext(InvadrsContext), ...props };
+  return svgFrom(resolveInvadr(id, options), className);
+}
+function Spawn(props) {
+  const { id, className, ...options } = { ...react.useContext(InvadrsContext), ...props };
+  return svgFrom(resolveSpawn(id, options), className);
+}
+
+exports.Invadr = Invadr;
+exports.InvadrsProvider = InvadrsProvider;
+exports.Spawn = Spawn;

package/dist/react/index.d.cts

@@ -0,0 +1,23 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { S as SpriteOptions } from '../types-C4QooPnZ.cjs';
+
+/** Props for the avatar components. `<Invadr>` and `<Spawn>` take the same
+    shape; the component you pick chooses the primitive (no `from` prop). */
+type InvadrProps = SpriteOptions & {
+    id: string;
+    className?: string;
+};
+type SpawnProps = InvadrProps;
+type Defaults = Partial<Omit<InvadrProps, "id">>;
+/** Supply default avatar props (palette, size, padding, …) to descendants.
+    Explicit props on an `<Invadr>`/`<Spawn>` override these. */
+declare function InvadrsProvider({ children, ...defaults }: {
+    children: ReactNode;
+} & Defaults): react.JSX.Element;
+/** A hand-drawn creature (one of 16) for an id, as inline SVG. */
+declare function Invadr(props: InvadrProps): ReactNode;
+/** A procedural, unique-per-id creature, as inline SVG. */
+declare function Spawn(props: SpawnProps): ReactNode;
+
+export { Invadr, type InvadrProps, InvadrsProvider, Spawn, type SpawnProps };

package/dist/react/index.d.ts

@@ -0,0 +1,23 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { S as SpriteOptions } from '../types-C4QooPnZ.js';
+
+/** Props for the avatar components. `<Invadr>` and `<Spawn>` take the same
+    shape; the component you pick chooses the primitive (no `from` prop). */
+type InvadrProps = SpriteOptions & {
+    id: string;
+    className?: string;
+};
+type SpawnProps = InvadrProps;
+type Defaults = Partial<Omit<InvadrProps, "id">>;
+/** Supply default avatar props (palette, size, padding, …) to descendants.
+    Explicit props on an `<Invadr>`/`<Spawn>` override these. */
+declare function InvadrsProvider({ children, ...defaults }: {
+    children: ReactNode;
+} & Defaults): react.JSX.Element;
+/** A hand-drawn creature (one of 16) for an id, as inline SVG. */
+declare function Invadr(props: InvadrProps): ReactNode;
+/** A procedural, unique-per-id creature, as inline SVG. */
+declare function Spawn(props: SpawnProps): ReactNode;
+
+export { Invadr, type InvadrProps, InvadrsProvider, Spawn, type SpawnProps };

package/dist/react/index.js

@@ -0,0 +1,56 @@
+import { resolveInvadr, resolveSpawn } from '../chunk-5SOVCTHT.js';
+import { createContext, useContext } from 'react';
+import { jsx, jsxs } from 'react/jsx-runtime';
+
+var InvadrsContext = createContext({});
+function InvadrsProvider({ children, ...defaults }) {
+  const inherited = useContext(InvadrsContext);
+  return /* @__PURE__ */ jsx(InvadrsContext.Provider, { value: { ...inherited, ...defaults }, children });
+}
+function renderCells(s) {
+  const nodes = [];
+  const n = s.grid.length;
+  if (s.background) {
+    nodes.push(
+      /* @__PURE__ */ jsx("rect", { x: -s.padding, y: -s.padding, width: n + s.padding * 2, height: n + s.padding * 2, fill: s.background }, "bg")
+    );
+  }
+  for (let y = 0; y < n; y++) {
+    for (let x = 0; x < n; x++) {
+      if (s.grid[y][x]) nodes.push(/* @__PURE__ */ jsx("rect", { x, y, width: 1, height: 1 }, `${x},${y}`));
+    }
+  }
+  return nodes;
+}
+function svgFrom(resolved, className) {
+  const n = resolved.grid.length;
+  const min = -resolved.padding;
+  const span = n + resolved.padding * 2;
+  const dims = resolved.size !== void 0 ? { width: resolved.size, height: resolved.size } : {};
+  const a11y = resolved.title ? { role: "img" } : { "aria-hidden": true };
+  return /* @__PURE__ */ jsxs(
+    "svg",
+    {
+      className,
+      viewBox: `${min} ${min} ${span} ${span}`,
+      ...dims,
+      shapeRendering: "crispEdges",
+      fill: resolved.color,
+      ...a11y,
+      children: [
+        resolved.title ? /* @__PURE__ */ jsx("title", { children: resolved.title }) : null,
+        renderCells(resolved)
+      ]
+    }
+  );
+}
+function Invadr(props) {
+  const { id, className, ...options } = { ...useContext(InvadrsContext), ...props };
+  return svgFrom(resolveInvadr(id, options), className);
+}
+function Spawn(props) {
+  const { id, className, ...options } = { ...useContext(InvadrsContext), ...props };
+  return svgFrom(resolveSpawn(id, options), className);
+}
+
+export { Invadr, InvadrsProvider, Spawn };

package/dist/types-C4QooPnZ.d.cts

@@ -0,0 +1,23 @@
+/** A square pixel grid, row-major; `grid[y][x]` true = filled. */
+type Grid = boolean[][];
+/** A color set (and optional background) used to paint a sprite. */
+type Palette = {
+    colors: string[];
+    background?: string;
+};
+/** Names of the built-in palettes. */
+type PaletteName = "tokyoNight" | "neon" | "sunset" | "ocean" | "forest" | "mono";
+/** Anything accepted for the `palette` option. `"css-vars"` emits
+    `var(--...)` fills so the host theme drives the color. */
+type PaletteInput = PaletteName | "css-vars" | string[] | Palette;
+/** Options shared by both primitives. `resolution` applies to `spawn` only. */
+type SpriteOptions = {
+    size?: number;
+    palette?: PaletteInput;
+    padding?: number;
+    background?: string;
+    title?: string;
+    resolution?: number;
+};
+
+export type { Grid as G, Palette as P, SpriteOptions as S, PaletteName as a, PaletteInput as b };

package/dist/types-C4QooPnZ.d.ts

@@ -0,0 +1,23 @@
+/** A square pixel grid, row-major; `grid[y][x]` true = filled. */
+type Grid = boolean[][];
+/** A color set (and optional background) used to paint a sprite. */
+type Palette = {
+    colors: string[];
+    background?: string;
+};
+/** Names of the built-in palettes. */
+type PaletteName = "tokyoNight" | "neon" | "sunset" | "ocean" | "forest" | "mono";
+/** Anything accepted for the `palette` option. `"css-vars"` emits
+    `var(--...)` fills so the host theme drives the color. */
+type PaletteInput = PaletteName | "css-vars" | string[] | Palette;
+/** Options shared by both primitives. `resolution` applies to `spawn` only. */
+type SpriteOptions = {
+    size?: number;
+    palette?: PaletteInput;
+    padding?: number;
+    background?: string;
+    title?: string;
+    resolution?: number;
+};
+
+export type { Grid as G, Palette as P, SpriteOptions as S, PaletteName as a, PaletteInput as b };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "invadrs",
+  "version": "0.1.0",
+  "description": "Deterministic space-invaders-style pixel avatars from any string.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Matthew Goodwin",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/m4ttheweric/invadrs.git"
+  },
+  "homepage": "https://github.com/m4ttheweric/invadrs#readme",
+  "bugs": "https://github.com/m4ttheweric/invadrs/issues",
+  "keywords": [
+    "avatar",
+    "identicon",
+    "pixel",
+    "pixel-art",
+    "sprite",
+    "space-invaders",
+    "svg",
+    "deterministic",
+    "generative",
+    "react"
+  ],
+  "sideEffects": false,
+  "files": ["dist"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./dist/react/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "bun test",
+    "prepare": "tsup"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true }
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}