@botharness/pixel-avatar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BotHarness
+
+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,22 @@
+# @botharness/pixel-avatar
+
+Seeded, editable 32×32 chibi pixel avatars with state symbols they can morph into.
+
+```ts
+import {
+  pixelAvatarSvg,
+  seededRecipe,
+  faceCells,
+  pixelSymbolCells,
+} from '@botharness/pixel-avatar';
+
+const recipe = seededRecipe('DeepSeekBot');
+const svg = pixelAvatarSvg(recipe); // 32×32 viewBox, crisp edges, no ids or scripts
+```
+
+- `seededRecipe(name)`: the same name always gives the same face. `createSeededRecipe(namespace)` makes a factory with its own set of faces.
+- `AVATAR_PARTS`, `AVATAR_SWATCHES`, `AVATAR_PRESETS`, `DEFAULT_RECIPE`: everything an editor needs.
+- `isPixelAvatarRecipe`, `canonicalRecipe`: validate and normalise saved recipes.
+- `AVATAR_HAIR_PARTS`, `AVATAR_RANGES`, `detailedRecipe(recipe)`: optional finer controls. A recipe may carry `bangs`, `sideHair`, `backHair`, `spacing`, `height` and `hairLength`, all six or none; `detailedRecipe` derives them from the plain `hair` so an editor can start from what is on screen. Recipes without them render exactly as before.
+- `faceCells`, `pixelSymbolCells`, `symbolArtCells`: pixels for [`@botharness/pixel-morph`](../morph).
+- `pixelAvatarSvg(recipe, { turns, classPrefix })`: optional pre-rendered head turns, and rig layer classes (`<prefix>-body`, `-head`, `-face`, `-gaze`, `-blink`) for CSS animation.

package/dist/index.d.ts

@@ -0,0 +1,114 @@
+import { PixelCell, PixelCell as PixelCell$1 } from "@botharness/pixel-morph";
+
+//#region src/recipe.d.ts
+declare const AVATAR_PARTS: {
+  readonly head: readonly ["round", "oval", "square", "long", "heart", "vchin", "chubby", "diamond"];
+  readonly pose: readonly ["front", "left", "right"];
+  readonly hair: readonly ["crop", "sweep", "spiky", "buzz", "curly", "mohawk", "bob", "long", "bun", "pigtails", "afro", "twintails", "drills", "ponytail", "sidetail", "hime", "odango", "messy", "wavy", "braids", "wolf", "ahoge", "none"];
+  readonly eyes: readonly ["round", "dot", "sparkle", "lashes", "sleepy", "happy", "wink", "sharp"];
+  readonly brows: readonly ["soft", "thick", "raised", "angry", "worried", "none"];
+  readonly nose: readonly ["button", "dot", "line", "none"];
+  readonly mouth: readonly ["smile", "grin", "open", "flat", "smirk", "cat", "tongue", "o"];
+  readonly cheeks: readonly ["blush", "freckles", "none"];
+  readonly glasses: readonly ["none", "round", "square", "shades", "monocle"];
+  readonly outfit: readonly ["tee", "shirttie", "hoodie", "turtleneck", "sailor", "blazer", "overalls", "dress", "kimono", "cardigan", "maid", "jacket"];
+  readonly backdrop: readonly ["sparkles", "hearts", "stars", "dots", "none"];
+  readonly accessory: readonly ["none", "beanie", "cap", "headphones", "flower", "bow", "earring", "crown", "halo", "catears", "hairclip", "horns", "beret", "ribbon", "headband", "bunnyears", "horseears", "flowercrown", "witch", "pins"];
+};
+declare const AVATAR_HAIR_PARTS: {
+  readonly bangs: readonly ["crop", "bob", "sweep", "spiky", "curly", "messy", "wolf", "wavy", "ahoge", "hime", "buzz", "mohawk", "none"];
+  readonly sideHair: readonly ["crop", "bun", "bob", "long", "hime", "curly", "braids", "none"];
+  readonly backHair: readonly ["none", "bob", "long", "wavy", "wolf", "bun", "odango", "pigtails", "twintails", "drills", "ponytail", "sidetail", "afro"];
+};
+declare const AVATAR_RANGES: {
+  readonly spacing: readonly [-1, 1];
+  readonly height: readonly [-1, 1];
+  readonly hairLength: readonly [-2, 2];
+};
+type AvatarHairPart = keyof typeof AVATAR_HAIR_PARTS;
+type AvatarRange = keyof typeof AVATAR_RANGES;
+type AvatarPart = keyof typeof AVATAR_PARTS;
+declare const AVATAR_COLORS: readonly ["skinColor", "hairColor", "eyeColor", "shirtColor"];
+type AvatarColor = (typeof AVATAR_COLORS)[number];
+type PixelAvatarRecipe = {
+  schemaVersion: 1;
+  family: 'illustrated';
+  assetVersion: 1;
+  rigVersion: 1;
+} & { [P in AvatarPart]: (typeof AVATAR_PARTS)[P][number] } & Record<AvatarColor, string> & { [P in AvatarHairPart]?: (typeof AVATAR_PARTS)['hair'][number] } & { [P in AvatarRange]?: number };
+declare const DEFAULT_RECIPE: PixelAvatarRecipe;
+declare function isPixelAvatarRecipe(value: unknown): value is PixelAvatarRecipe;
+declare function canonicalRecipe(recipe: PixelAvatarRecipe): PixelAvatarRecipe;
+declare function detailedRecipe(recipe: PixelAvatarRecipe): PixelAvatarRecipe;
+declare const AVATAR_SWATCHES: Record<AvatarColor, readonly string[]>;
+/**
+ * Returns a name-seeded recipe factory. Different namespaces give different faces for the same
+ * name; the factory takes the name only, so it is safe to pass straight to `Array.map`.
+ */
+declare function createSeededRecipe(namespace: string): (seed: string) => PixelAvatarRecipe;
+/** The same name always gives the same face (BotHarness's namespace). */
+declare const seededRecipe: (seed: string) => PixelAvatarRecipe;
+declare const AVATAR_PRESETS: readonly PixelAvatarRecipe[];
+//#endregion
+//#region src/figure.d.ts
+type Cell = string | undefined;
+type Grid = Cell[][];
+type PixelGrid = Grid;
+type Recipe = PixelAvatarRecipe;
+declare function pixelTileColor(hair: string): string;
+declare function pixelFigure(recipe: Recipe, yawDeg: number): {
+  tile: string;
+  body: string;
+  head: string;
+  cells: PixelCell$1[];
+};
+//#endregion
+//#region src/random.d.ts
+declare function seededRandom(seed: string): () => number;
+//#endregion
+//#region src/svg.d.ts
+/** Head-turn offsets (degrees) the thinking animation cycles through. */
+declare const AVATAR_TURNS: readonly [-14, -7, 7, 14];
+interface PixelAvatarSvgOptions {
+  /** Extra yaw offsets to pre-render as hidden `[data-avatar-turn]` layers. */
+  turns?: readonly number[];
+  /** Class prefix for the rig layers (`-body`, `-head`, `-face`, `-gaze`, `-blink`). */
+  classPrefix?: string;
+}
+/** Every visible pixel of the face at its pose, in paint order, for morphing. */
+declare function faceCells(recipe: PixelAvatarRecipe): PixelCell$1[];
+/** A 32×32 SVG of the avatar: tile, body, head rig, optional turn layers and an empty morph layer. */
+declare function pixelAvatarSvg(recipe: PixelAvatarRecipe, options?: PixelAvatarSvgOptions): string;
+//#endregion
+//#region src/symbols.d.ts
+declare const SYMBOLS: {
+  readonly thinking: readonly ["........................", "........................", "........................", "...........AAAA.........", "..........AAAAAA........", ".........AAAAAAAA.......", ".......AAAAAAAAAAA......", ".....AAAAAAAAAAAAA......", "....AAAAAAAAAAAAAAAA....", "....AAAAAAAAAAAAAAAAA...", "...AAAAAAAAAAAAAAAAAAA..", "...AAAAHHAAAHHAAAHHAAA..", "....AAAHHAAAHHAAAHHAAA..", "....AAAAAAAAAAAAAAAAAA..", ".....AAAAAAAAAAAAAAAA...", ".....AAAAAAAAAAAAAAA....", ".......AAAAAAAAAAA......", "........................", "....AA..................", "...AAAA.................", "...AAAA.................", "..A.AA..................", ".AAA....................", "..A....................."];
+  readonly ask: readonly ["........................", "........................", "...........AAA..........", "........AAAAAAAA........", ".......AAAAAAAAAA.......", ".......AAAAAAAAAA.......", "......AAAAA...AAAA......", "......AAAA....AAAA......", "......AAA.....AAAA......", "......AAA.....AAAA......", "..............AAAA......", ".............AAAAA......", "............AAAAA.......", "...........AAAAA........", "...........AAA..........", "..........AAAA..........", "..........AAAA..........", "...........AA...........", "........................", "..........AAAA..........", "..........AAAA..........", "..........AAAA..........", "...........AA...........", "........................"];
+  readonly read: readonly ["........................", "........................", "........................", "........................", "..AAAAAAA......AAAAAAA..", ".AAAAAAAAAA..AAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAHHHHHAAAAAAHHHHHAAA.", ".AAAHHHHHAAAAAAHHHHHAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAHHHHHAAAAAAHHHHHAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", "...........AA...........", "........................", "........................", "........................", "........................", "........................"];
+  readonly write: readonly ["........................", ".....AAAAAAAAAA.........", "....AAAAAAAAAAAA........", "....AAAAAAAAAAAAA.......", "....AAAAAAAAAAAAAA......", "....AAAAAAAAAAAAAAA.....", "....AAAAAAAAAAAAAAAA....", "....AAAAAAAAAAAAAAAA....", "....AAAAAAAAAAAAAAAA....", "....AAAAAAAHHAAAAAAA....", "....AAAAAAAHHAAAAAAA....", "....AAAAAAAHHAAAAAAA....", "....AAAAAAAHHAAAAAAA....", "....AAAHHHHHHHHHHAAA....", "....AAAAAAAHHAAAAAAA....", "....AAAAAAAHHAAAAAAA....", "....AAAAAAAHHAAAAAAA....", "....AAAAAAAHHAAAAAAA....", "....AAAAAAAAAAAAAAAA....", "....AAAAAAAAAAAAAAAA....", "....AAAAAAAAAAAAAAAA....", "....AAAAAAAAAAAAAAAA....", ".....AAAAAAAAAAAAAA.....", "........................"];
+  readonly edit: readonly ["........................", "........................", "........................", "...............AA.......", ".............HHAAA......", ".............HHHAAA.....", "............AAHHHAAA....", "...........AAAAHHHAAA...", "..........AAAAAAHHHAA...", ".........AAAAAAAAHHH....", "........AAAAAAAAAAHH....", ".......AAAAAAAAAAA......", "......AAAAAAAAAAA.......", ".....AAAAAAAAAAA........", "....AAAAAAAAAAA.........", "...AAAAAAAAAAA..........", "...AAHHAAAAAA...........", "...AAHHHAAAA............", "...AAAHHAAA.............", "...AAAAAAA..............", "...AAAAAA...............", "........................", "........................", "........................"];
+  readonly bash: readonly ["........................", "........................", "........................", "....AAAAAAAAAAAAAAAA....", "..AAAAAAAAAAAAAAAAAAAA..", "..AAAAAAAAAAAAAAAAAAAA..", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAHHAAAAAAAAAAAAAAAA.", ".AAAAHHHAAAAAAAAAAAAAAA.", ".AAAAAHHHAAAAAAAAAAAAAA.", ".AAAAAAHHHAAAAAAAAAAAAA.", ".AAAAAAHHHAAAAAAAAAAAAA.", ".AAAAAHHHAAAAAAAAAAAAAA.", ".AAAAHHHAAAAAAAAAAAAAAA.", ".AAAAHHAAAAHHHHHHHAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", "..AAAAAAAAAAAAAAAAAAAA..", "..AAAAAAAAAAAAAAAAAAAA..", "....AAAAAAAAAAAAAAAA....", "........................", "........................", "........................"];
+  readonly search: readonly ["........................", "........................", ".......AAAAAA...........", "......AAAAAAAA..........", "....AAAAAAAAAAAA........", "....AAAAAAAAAAAA........", "...AAAA......AAAA.......", "..AAAA........AAAA......", "..AAAA........AAAA......", "..AAAA........AAAA......", "..AAAA........AAAA......", "..AAAA........AAAA......", "..AAAA........AAAA......", "...AAAA......AAAA.......", "....AAAAAAAAAAAAA.......", "....AAAAAAAAAAAAAA......", "......AAAAAAAAAAAAA.....", ".......AAAAAA..AAAAA....", "................AAAAA...", ".................AAAAA..", "..................AAAAA.", "...................AAAA.", "....................AA..", "........................"];
+  readonly web: readonly ["........................", "........................", ".........AHHHHA.........", ".......AAHHHHHHAA.......", ".....AAAAHHAAHHAAAA.....", "....AAAAHHAAAAHHAAAA....", "....HHHHHHHHHHHHHHHH....", "...AHHHHHHHHHHHHHHHHA...", "...AAAAAHAAAAAAHAAAAA...", "..AAAAAHHAAAAAAHAAAAAA..", "..AAAAAHHAAAAAAHHAAAAA..", "..HHHHHHHHHHHHHHHHHHHH..", "..HHHHHHHHHHHHHHHHHHHH..", "..AAAAAHHAAAAAAHHAAAAA..", "..AAAAAHHAAAAAAHAAAAAA..", "...AAAAAHAAAAAAHAAAAA...", "...AHHHHHHHHHHHHHHHHA...", "....HHHHHHHHHHHHHHHH....", "....AAAAHHAAAAHHAAAA....", ".....AAAAHHAAHHAAAA.....", ".......AAHHHHHHAA.......", ".........AHHHHA.........", "........................", "........................"];
+  readonly fetch: readonly ["........................", "..........AAA...........", "..........AAAA..........", "..........AAAA..........", "..........AAAA..........", "..........AAAA..........", "..........AAAA..........", ".....AA...AAAA...AA.....", "....AAAA..AAAA..AAAA....", "....AAAAA.AAAA.AAAAA....", ".....AAAAAAAAAAAAAA.....", "......AAAAAAAAAAAA......", ".......AAAAAAAAAA.......", "........AAAAAAAA........", ".........AAAAAA.........", "..AAA.....AAAA.....AAA..", "..AAA......AA......AAA..", "..AAA..............AAA..", "..AAA..............AAA..", "..AAAAAAAAAAAAAAAAAAAA..", "..AAAAAAAAAAAAAAAAAAAA..", "..AAAAAAAAAAAAAAAAAAAA..", "...AAAAAAAAAAAAAAAAAA...", "........................"];
+  readonly todo: readonly ["........................", "........................", "....AAAAAAAAAAAAAAAA....", "....AAAAAAAAAAAAAAAA....", "...AAAAAAAAAAAAAAAAAA...", "...AAAAAAAAAAAAAAAAAA...", "...AAAAAAAAHAAAAAAAAA...", "...AAAAAAAHHAAAAAAAAA...", "...AAAHHAHHAAHHHHHAAA...", "...AAAAHHHAAAHHHHHAAA...", "...AAAAAHAAAAAAAAAAAA...", "...AAAAAAAAAAAAAAAAAA...", "...AAAAAAAAAAAAAAAAAA...", "...AAAAAAAAHAAAAAAAAA...", "...AAAAAAAHHAAAAAAAAA...", "...AAAHHAHHAAHHHHHAAA...", "...AAAAHHHAAAHHHHHAAA...", "...AAAAAHAAAAAAAAAAAA...", "...AAAAAAAAAAAAAAAAAA...", "...AAAAAAAAAAAAAAAAAA...", "...AAAAAAAAAAAAAAAAAA...", "....AAAAAAAAAAAAAAAA....", ".....AAAAAAAAAAAAAA.....", "........................"];
+  readonly subagent: readonly ["........................", "........................", "........................", "........................", ".....AAAA......AAAA.....", "....AAAAAA....AAAAAA....", "....AAAAAAA..AAAAAAA....", "....AAAAAAA..AAAAAAA....", "....AAAAAAA..AAAAAAA....", "....AAAAAA...AAAAAAA....", ".....AAAAA....AAAAA.....", "........................", "........................", "........................", ".......A................", "....AAAAAAA..AAAAAAA....", "...AAAAAAAAAAAAAAAAAA...", "..AAAAAAAAAAAAAAAAAAAA..", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", "........................", "........................", "........................"];
+  readonly workflow: readonly ["........................", "........................", "........................", "..AAAAAA.........AAAAA..", "..AAAAAA........AAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAA....AAA.AAAAAAA.", "..AAAAAA....AAA..AAAAA..", "............AAA.........", "............AAA.........", "............AAA.........", "............AAA.........", "............AAA..AAAAA..", "............AAA.AAAAAAA.", ".............AAAAAAAAAA.", ".............AAAAAAAAAA.", "...............AAAAAAAA.", "................AAAAAAA.", ".................AAAAA..", "........................", "........................", "........................"];
+  readonly goal: readonly ["........................", "....AA..................", "...AAAA.................", "...AAAAAAAAAAAAAAAAA....", "...AAAAAAAAAAAAAAAA.....", "...AAAAAAAAAAAAAAA......", "...AAAAAAAAAAAAAAA......", "...AAAAAAAAAAAAAA.......", "...AAAAAAAAAAAAAA.......", "...AAAAAAAAAAAAAAA......", "...AAAAAAAAAAAAAAAA.....", "...AAAAAAAAAAAAAAAAA....", "...AAAA.................", "...AAAA.................", "...AAAA.................", "...AAAA.................", "...AAAA.................", "...AAAA.................", "...AAAA.................", "...AAAA.................", "...AAAA.................", "...AAAA.................", "...AAAA.................", "....AA.................."];
+  readonly present: readonly ["........................", "........................", "...AAAAAAAAAAAAAAAAAA...", "..AAAAAAAAAAAAAAAAAAAA..", ".AAAAAAAAAAAAAAAAAAAAAA.", ".AAAAAAAAAAAAAAAAAHAAAA.", ".AAAAAAAAAAAAAAAAAHAAAA.", ".AAAAAAAAAHAAAAAAAHAAAA.", ".AAAAAAAAAHAAAHAAAHAAAA.", ".AAAAAHAAAHAAAHAAAHAAAA.", ".AAAAAHAAAHAAAHAAAHAAAA.", ".AAAAAHAAAHAAAHAAAHAAAA.", ".AAAAAHAAAHAAAHAAAHAAAA.", ".AAAAAHAAAHAAAHAAAHAAAA.", ".AAAAAAAAAAAAAAAAAAAAAA.", "..AAAAAAAAAAAAAAAAAAAA..", "...AAAAAAAAAAAAAAAAAA...", ".........AAAAAA.........", "........AAAAAAAA........", "........AAA..AAA........", ".......AAA....AAA.......", ".......AAA....AAA.......", ".......AA......AA.......", "........................"];
+  readonly approval: readonly ["........................", "........................", ".........AAAAAA.........", "......AAAAAAAAAAAA......", "....AAAAAAAAAAAAAAAA....", "...AAAAAAAAHHAAAAAAAA...", "...AAAAAAAAHHAAAAAAAA...", "...AAAAAAAAHHAAAAAAAA...", "...AAAAAAAAHHAAAAAAAA...", "...AAAAAAAAHHAAAAAAAA...", "...AAAAAAAAHHAAAAAAAA...", "...AAAAAAAAHHAAAAAAAA...", "...AAAAAAAAHHAAAAAAAA...", "....AAAAAAAHHAAAAAAA....", "....AAAAAAAAAAAAAAAA....", "....AAAAAAAAAAAAAAAA....", ".....AAAAAAHHAAAAAA.....", ".....AAAAAAHHAAAAAA.....", "......AAAAAAAAAAAA......", ".......AAAAAAAAAA.......", "........AAAAAAAA........", ".........AAAAA..........", "...........AA...........", "........................"];
+  readonly other: readonly ["........................", "........................", "........................", "...........AA...........", "...........AA...........", "..........AAAA..........", "..........AAAA..........", "..........AAAA..........", ".........AAAAAA.........", "........AAAAAAAA........", ".....AAAAAAAAAAAAAA.....", "...AAAAAAAAAAAAAAAAAA...", "...AAAAAAAAAAAAAAAAAA...", ".....AAAAAAAAAAAAAA.....", "........AAAAAAAA........", ".........AAAAAA.........", "..........AAAA..........", "..........AAAA..........", "..........AAAA..........", "...........AA...........", "...........AA...........", "........................", "........................", "........................"];
+};
+type PixelSymbol = keyof typeof SYMBOLS;
+declare const PIXEL_SYMBOLS: PixelSymbol[];
+declare function pixelSymbolCells(symbol: PixelSymbol, color: string): PixelCell$1[];
+/**
+ * Colours a 24×24 character-art symbol (`A` body, `H` highlight, anything else empty) into
+ * cells on the 32 grid: the body in `color`, highlights lighter, the lower-right edge darker,
+ * and a one-pixel ink outline. This is how every built-in symbol is drawn, so a host can add
+ * its own symbols in the same style without touching the package.
+ */
+declare function symbolArtCells(rows: readonly string[], color: string): PixelCell$1[];
+//#endregion
+export { AVATAR_COLORS, AVATAR_HAIR_PARTS, AVATAR_PARTS, AVATAR_PRESETS, AVATAR_RANGES, AVATAR_SWATCHES, AVATAR_TURNS, type AvatarColor, type AvatarHairPart, type AvatarPart, type AvatarRange, DEFAULT_RECIPE, PIXEL_SYMBOLS, type PixelAvatarRecipe, type PixelAvatarSvgOptions, type PixelCell, type PixelGrid, type PixelSymbol, canonicalRecipe, createSeededRecipe, detailedRecipe, faceCells, isPixelAvatarRecipe, pixelAvatarSvg, pixelFigure, pixelSymbolCells, pixelTileColor, seededRandom, seededRecipe, symbolArtCells };
+//# sourceMappingURL=index.d.ts.map