@hadoku/prefs-client 1.1.11 → 1.1.12

package/README.md

@@ -169,3 +169,43 @@ Rules for an app that renders avatars:
 - Resolve on join and on reconnect; avatars change rarely. `resolveAvatars` batches past 100 ids.
 - Source choice, character choice, linking (`linkInPopup`: no page navigation), uploads and
   removal all happen in the settings popout. Don't build your own.
+
+## Avatar cosmetics (`@wolffm/prefs-client/cosmetics`)
+
+What a person wears with their avatar: a name **effect**, a name **gradient**, a name **font**, an
+avatar **overlay** (an image the person can move, turn and resize, or a drawn ring or glow), and a
+**message** reveal for their chat lines. Items are earned or gifted, never bought; one per slot.
+People equip them in the settings popout's avatar dialog. Every resolved avatar carries what is
+worn as `cosmetics` (`ResolvedAvatar.cosmetics`, only items the person owns).
+
+```ts
+import {
+  ensureCosmeticsStyles,
+  colourStyle,
+  nameHtml,
+  avatarHtml,
+  messageHtml,
+} from '@wolffm/prefs-client/cosmetics';
+
+ensureCosmeticsStyles(); // once: the stylesheet, and the clean-up that ends a message reveal
+const worn = person.cosmetics; // from resolveAvatars() or the owner's settings
+row.style.cssText = colourStyle(character.color); // every text colour derives from this
+row.innerHTML =
+  avatarHtml({ src: pictureUrl, size: 40, worn }) +
+  nameHtml(person.name, worn) +
+  messageHtml(text, live ? worn : undefined); // reveal only messages arriving live
+```
+
+Rules for an app that renders them:
+
+- **Colour comes from the character.** Put the character's colour in `--hc-base` on the row
+  (`colourStyle`). Never give a name effect or gradient its own colour.
+- **Reveal live messages only**, never history or a scroll-back load. The reveal ends as plain text.
+- **Pause what is off screen**: toggle `hc-idle` on rows an IntersectionObserver reports hidden.
+- **Leave room for overlays.** An overlay may reach about a third of the avatar's size above it
+  and a quarter to each side (`PLACEMENT_ZONE`); don't clip the avatar's box.
+- Images and fonts load same-origin from `/cosmetics/` (hadoku_site `public/cosmetics`); a font
+  downloads only when someone wears it.
+- Adding an item: `COSMETICS` in `cosmetics-contract.ts`, its CSS in `cosmetics.ts`, an image in
+  `public/cosmetics/art/`. `test/cosmetics.test.ts` fails if any of the three is missing, and if a
+  loop animates anything but transform or opacity.

package/dist/avatar.d.ts

@@ -1,3 +1,6 @@
+import { A as AvatarCosmetics, C as CosmeticsView, L as LoadoutUpdate } from './cosmetics-contract-Cqim3RuG.js';
+export { a as CosmeticSlot, b as Loadout, P as Placement } from './cosmetics-contract-Cqim3RuG.js';
+
 /**
  * Avatars — the wire contract, shared by prefs-api and the client.
  *
@@ -7,6 +10,7 @@
  *
  * Design: hadoku_site docs/planning/avatars-2026-10-30.md
  */
+
 declare const AVATAR_SOURCES: readonly ["sprite", "discord", "steam", "upload"];
 type AvatarSource = (typeof AVATAR_SOURCES)[number];
 declare const LINK_PROVIDERS: readonly ["discord", "steam"];
@@ -32,6 +36,12 @@ interface ResolvedAvatar {
     source: AvatarSource;
     url?: string;
     sprite?: string;
+    /**
+     * What the person wears (effect, gradient, font, overlay, message reveal,
+     * and the overlay's placement): only items they own. Absent when nothing is
+     * worn. Render it with `@wolffm/prefs-client/cosmetics`.
+     */
+    cosmetics?: AvatarCosmetics;
 }
 /** PUT /api/v1/_avatar — either or both. */
 interface AvatarUpdate {
@@ -74,6 +84,8 @@ interface AvatarSettings {
     /** Whether each provider is configured on the server. A false one cannot be linked yet. */
     providers: Record<LinkProvider, boolean>;
     limits: AvatarUploadLimits;
+    /** What the owner has earned and what they wear. */
+    cosmetics: CosmeticsView;
 }
 interface AvatarUploadLimits {
     maxBytes: number;
@@ -158,6 +170,12 @@ declare function createAvatarClient(opts?: AvatarClientOptions): {
     /** Upload an image (PNG, JPEG, WebP or GIF). It is re-encoded and becomes the chosen source. */
     upload: (image: Blob) => Promise<AvatarSettings>;
     removeUpload: () => Promise<AvatarSettings>;
+    /**
+     * Equip or take off items and place overlays. 409 for an item the person
+     * does not own; a placement is fitted to the allowed area before it is
+     * stored, so the returned settings show where it really landed.
+     */
+    setCosmetics: (u: LoadoutUpdate) => Promise<AvatarSettings>;
 };
 type AvatarClient = ReturnType<typeof createAvatarClient>;
 interface ResolveAvatarsOptions extends AvatarClientOptions {
@@ -172,4 +190,4 @@ interface ResolveAvatarsOptions extends AvatarClientOptions {
  */
 declare function resolveAvatars(opts: ResolveAvatarsOptions, userIds: readonly string[]): Promise<Record<string, ResolvedPerson>>;
 
-export { AVATAR_SOURCES, type AvatarClient, type AvatarClientOptions, AvatarError, type AvatarSettings, type AvatarSource, type AvatarUpdate, type AvatarUploadLimits, LINK_CALLBACK_PATH, LINK_MESSAGE_TYPE, LINK_POPUP_MARK, LINK_PROVIDERS, type LinkMessage, type LinkProvider, type LinkStart, type LinkedAccountView, RESOLVE_MAX_IDS, type ResolveAvatarsOptions, type ResolveRequest, type ResolveResponse, type ResolvedAvatar, type ResolvedPerson, SPRITE_ID_PATTERN, type UploadView, createAvatarClient, resolveAvatars };
+export { AVATAR_SOURCES, type AvatarClient, type AvatarClientOptions, AvatarCosmetics, AvatarError, type AvatarSettings, type AvatarSource, type AvatarUpdate, type AvatarUploadLimits, CosmeticsView, LINK_CALLBACK_PATH, LINK_MESSAGE_TYPE, LINK_POPUP_MARK, LINK_PROVIDERS, type LinkMessage, type LinkProvider, type LinkStart, type LinkedAccountView, LoadoutUpdate, RESOLVE_MAX_IDS, type ResolveAvatarsOptions, type ResolveRequest, type ResolveResponse, type ResolvedAvatar, type ResolvedPerson, SPRITE_ID_PATTERN, type UploadView, createAvatarClient, resolveAvatars };

package/dist/avatar.js

@@ -110,7 +110,13 @@ function createAvatarClient(opts = {}) {
     unlink: (provider) => send(`/link/${provider}`, "DELETE"),
     /** Upload an image (PNG, JPEG, WebP or GIF). It is re-encoded and becomes the chosen source. */
     upload: (image) => call("/upload", { method: "POST", body: image }),
-    removeUpload: () => send("/upload", "DELETE")
+    removeUpload: () => send("/upload", "DELETE"),
+    /**
+     * Equip or take off items and place overlays. 409 for an item the person
+     * does not own; a placement is fitted to the allowed area before it is
+     * stored, so the returned settings show where it really landed.
+     */
+    setCosmetics: (u) => send("/cosmetics", "PUT", u)
   };
 }
 async function resolveAvatars(opts, userIds) {

package/dist/cosmetics-contract-Cqim3RuG.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Avatar cosmetics — the wire contract, shared by prefs-api and the client.
+ *
+ * Pure: no fetch, no DOM. prefs-api imports this file directly (as it does
+ * avatar-contract.ts), so the server validates with the very catalogue and
+ * placement rules the client renders with. The renderer lives in ./cosmetics.ts.
+ *
+ * Rules the catalogue keeps (operator, 2026-11-01; design:
+ * docs/planning/avatar-cosmetics-2026-11-02.md):
+ * - Earned by achievement or gifted by the operator, never bought; no levels.
+ * - One item per slot.
+ * - Name effects, gradients and message reveals derive every colour from the
+ *   person's character colour. Overlays may bring their own (the crown is gold).
+ * - Every loop animates only transform and opacity (cosmetics.test.ts).
+ */
+declare const COSMETIC_SLOTS: readonly ["effect", "gradient", "font", "overlay", "message"];
+type CosmeticSlot = (typeof COSMETIC_SLOTS)[number];
+/** `<slot>.<name>`, e.g. `overlay.crown`. */
+declare const COSMETIC_ID_PATTERN: RegExp;
+/** An overlay drawn from an image, which the person may move, turn and resize. */
+interface OverlayArt {
+    /** Image file under the cosmetics asset base, `art/<file>`. */
+    file: string;
+    /** Default box, in % of the avatar's size: top edge and width. The image is square. */
+    top: number;
+    width: number;
+    /** The image's own tilt, degrees. */
+    tilt: number;
+    /** Pixel art: scaled without smoothing. */
+    pixel: boolean;
+    /** The visible (opaque) part of the image, as fractions: left, top, right, bottom. */
+    visible: readonly [number, number, number, number];
+}
+interface CosmeticItem {
+    id: string;
+    slot: CosmeticSlot;
+    label: string;
+    /** How it is earned, as the inventory shows it to someone who has not. */
+    earn: string;
+    art?: OverlayArt;
+}
+/**
+ * Every item that exists. Adding one: add it here, give it CSS in
+ * cosmetics.ts, and (for an overlay image) put the file in
+ * public/cosmetics/art/. An id never changes once granted: it is stored in
+ * people's inventories.
+ */
+declare const COSMETICS: readonly CosmeticItem[];
+declare const COSMETICS_BY_ID: ReadonlyMap<string, CosmeticItem>;
+/**
+ * A person's adjustment of an overlay image, relative to its default spot:
+ * x/y in % of the avatar's size, r in degrees, s in % of the default size.
+ */
+interface Placement {
+    x: number;
+    y: number;
+    r: number;
+    s: number;
+    flip: boolean;
+    /** Drawn behind the avatar picture instead of over it. */
+    back: boolean;
+}
+declare const PLACEMENT_DEFAULT: Placement;
+/** Hard ranges, before the zone. */
+declare const PLACEMENT_LIMITS: {
+    readonly x: readonly [-60, 60];
+    readonly y: readonly [-60, 100];
+    readonly r: readonly [-45, 45];
+    readonly s: readonly [70, 140];
+};
+interface Box {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/**
+ * Where the visible part of an overlay image lands, in % of the avatar
+ * (0..100 is the avatar's own box), after its tilt and the person's
+ * placement. The renderer applies the same transforms in the same order:
+ * the image tilts about its centre; the placement box then scales and turns
+ * about 50% / 60% of the image and moves.
+ */
+declare function overlayBounds(art: OverlayArt, p: Placement): Box;
+/**
+ * Where an overlay's visible edges may go, in % of the avatar. The ceiling is
+ * the highest any image sits by default (the crown): higher bleeds into the
+ * chat message above. Down to just below the character is fine. Sideways a
+ * quarter of the avatar, which keeps it off the name and the message text.
+ */
+declare const PLACEMENT_ZONE: Box;
+/**
+ * Bring any placement inside the limits and the zone: clamp each value, shrink
+ * the image if it cannot fit at all, then slide it back in. Integers out.
+ * The editor calls this on every move and the server on every write, so what
+ * one accepts the other renders.
+ */
+declare function fitPlacement(art: OverlayArt, raw: Partial<Placement>): Placement;
+/** What is equipped in each slot (null = nothing), and where each overlay image sits. */
+interface Loadout {
+    equipped: Record<CosmeticSlot, string | null>;
+    /** By overlay item id. Kept for items not currently equipped, so swapping back keeps the spot. */
+    placement: Record<string, Placement>;
+}
+declare function emptyLoadout(): Loadout;
+/**
+ * What a person wears, as every app renders it (ResolvedAvatar.cosmetics):
+ * the equipped item ids by slot, and the placement of the equipped overlay
+ * when it is an image. Only items the person owns; absent when nothing is worn.
+ */
+interface AvatarCosmetics {
+    effect?: string;
+    gradient?: string;
+    font?: string;
+    overlay?: string;
+    message?: string;
+    placement?: Placement;
+}
+/** In AvatarSettings: what the owner has earned and what they wear. */
+interface CosmeticsView {
+    /** Item ids, in catalogue order. */
+    owned: string[];
+    loadout: Loadout;
+}
+/** PUT /api/v1/_avatar/cosmetics. Either or both. */
+interface LoadoutUpdate {
+    /** Per slot: an owned item id of that slot, or null to take it off. */
+    equip?: Partial<Record<CosmeticSlot, string | null>>;
+    /** Per owned overlay image id. Fitted to the zone before it is stored. */
+    placement?: Record<string, Partial<Placement>>;
+}
+/**
+ * A stored loadout made safe to serve: unknown or unowned items dropped (an
+ * item can be revoked), every placement refitted. Run on every read, so a
+ * catalogue or zone change applies to rows already stored.
+ */
+declare function cleanLoadout(raw: unknown, owned: ReadonlySet<string>): Loadout;
+/** The public half of a clean loadout. Undefined when nothing is worn. */
+declare function wornCosmetics(loadout: Loadout): AvatarCosmetics | undefined;
+/** Admin: POST /api/v1/admin/cosmetics/grant and /revoke. */
+interface CosmeticGrantRequest {
+    /** The person's registry name (resolved by the registry; a raw userId is never accepted, R5). */
+    name: string;
+    items: string[];
+    /** Why, for the record (e.g. "won the October Major"). Grant only. */
+    note?: string;
+}
+/** Admin: GET /api/v1/admin/cosmetics?name= */
+interface CosmeticGrantList {
+    grants: {
+        item: string;
+        source: 'gift' | 'achievement';
+        note: string | null;
+        grantedAt: number;
+    }[];
+}
+
+export { type AvatarCosmetics as A, type Box as B, type CosmeticsView as C, type LoadoutUpdate as L, type OverlayArt as O, type Placement as P, type CosmeticSlot as a, type Loadout as b, COSMETICS as c, COSMETICS_BY_ID as d, COSMETIC_ID_PATTERN as e, COSMETIC_SLOTS as f, type CosmeticGrantList as g, type CosmeticGrantRequest as h, type CosmeticItem as i, PLACEMENT_DEFAULT as j, PLACEMENT_LIMITS as k, PLACEMENT_ZONE as l, cleanLoadout as m, emptyLoadout as n, fitPlacement as o, overlayBounds as p, wornCosmetics as w };

package/dist/cosmetics.d.ts

@@ -0,0 +1,63 @@
+import { A as AvatarCosmetics, P as Placement } from './cosmetics-contract-Cqim3RuG.js';
+export { B as Box, c as COSMETICS, d as COSMETICS_BY_ID, e as COSMETIC_ID_PATTERN, f as COSMETIC_SLOTS, g as CosmeticGrantList, h as CosmeticGrantRequest, i as CosmeticItem, a as CosmeticSlot, C as CosmeticsView, b as Loadout, L as LoadoutUpdate, O as OverlayArt, j as PLACEMENT_DEFAULT, k as PLACEMENT_LIMITS, l as PLACEMENT_ZONE, m as cleanLoadout, n as emptyLoadout, o as fitPlacement, p as overlayBounds, w as wornCosmetics } from './cosmetics-contract-Cqim3RuG.js';
+
+/**
+ * Avatar cosmetics — the renderer every app uses, so a name, an avatar and a
+ * chat line look the same in watchparty, the games and the settings dialog.
+ *
+ * Framework-free: builders return HTML strings, and one stylesheet does the
+ * rest. Call `ensureCosmeticsStyles()` once, then put the strings in the page
+ * (React: `dangerouslySetInnerHTML`; every user-supplied string is escaped).
+ *
+ * The person's character colour goes in `--hc-base` on the element or an
+ * ancestor (`colourStyle(hex)`); every text colour is derived from it.
+ *
+ * Performance rules (cosmetics.test.ts enforces the first two):
+ * - Loops animate only transform and opacity, so they run on the compositor.
+ * - A message reveal fills `backwards` only, and the page swaps its letter
+ *   spans back to plain text when it ends: a chat history holds no animations.
+ * - Pause what is off screen: add `hc-idle` to an ancestor (an
+ *   IntersectionObserver per row is enough) and every loop under it stops.
+ *
+ * Assets (images, fonts) are served same-origin from `/cosmetics/`
+ * (hadoku_site public/cosmetics). A font downloads only when an item uses it.
+ */
+
+declare const COSMETICS_ASSET_BASE = "/cosmetics";
+/** `--hc-base:<hex>` for a style attribute, or '' when the colour is not a 6-digit hex. */
+declare function colourStyle(hex: string | null | undefined): string;
+/** The CSS transform for a person's placement of an overlay image. */
+declare function placementTransform(p: Placement): string;
+/**
+ * A display name with its effect, gradient and font. `large` is the profile
+ * card size; the default fits a chat line.
+ */
+declare function nameHtml(text: string, worn?: AvatarCosmetics, opts?: {
+    large?: boolean;
+}): string;
+/**
+ * The decoration layers for an avatar: put them inside the avatar's box
+ * (`avatarHtml` does), which must be `position: relative` and carry `--hc-sz`.
+ */
+declare function decorHtml(worn?: AvatarCosmetics, assetBase?: string): string;
+/** A round avatar picture with its decorations. `size` in px. */
+declare function avatarHtml(o: {
+    src: string | null;
+    size: number;
+    worn?: AvatarCosmetics;
+    assetBase?: string;
+}): string;
+/**
+ * A chat line with the sender's message reveal. Play it only for a message
+ * arriving live, never for history. Screen readers get the whole line at once.
+ * Pass `keep` for a preview that should keep its spans (to replay it).
+ */
+declare function messageHtml(text: string, worn?: AvatarCosmetics, opts?: {
+    keep?: boolean;
+}): string;
+/** The whole stylesheet, with asset URLs under `assetBase`. */
+declare function cosmeticsCss(assetBase?: string): string;
+/** Add the stylesheet and the reveal clean-up to a document, once. */
+declare function ensureCosmeticsStyles(doc?: Document, assetBase?: string): void;
+
+export { AvatarCosmetics, COSMETICS_ASSET_BASE, Placement, avatarHtml, colourStyle, cosmeticsCss, decorHtml, ensureCosmeticsStyles, messageHtml, nameHtml, placementTransform };

package/dist/cosmetics.js

@@ -0,0 +1,499 @@
+// src/cosmetics-contract.ts
+var COSMETIC_SLOTS = ["effect", "gradient", "font", "overlay", "message"];
+var COSMETIC_ID_PATTERN = /^(effect|gradient|font|overlay|message)\.[a-z0-9-]{1,32}$/;
+var item = (slot, name, label, earn, art) => ({ id: `${slot}.${name}`, slot, label, earn, ...art ? { art } : {} });
+var COSMETICS = [
+  item("effect", "glint", "Glint", "Win a cardtable match"),
+  item("effect", "aura", "Aura", "Attend 10 watchparties"),
+  item("effect", "hop", "Hop", "Win 25 bomberman rounds"),
+  item("effect", "outline", "Outline", "Finish 3 tournaments"),
+  item("effect", "twinkle", "Twinkle", "Top four in a Major"),
+  item("gradient", "gild", "Gilded", "Your first win in any game"),
+  item("gradient", "gloss", "Gloss", "Win 10 games"),
+  item("gradient", "split", "Split", "Finish 5 tournaments"),
+  item("gradient", "brushed", "Brushed", "Play 100 games"),
+  item("gradient", "lumen", "Lumen", "Host 5 watchparties"),
+  item("font", "caps", "Small caps", "Finish a tournament"),
+  item("font", "wide", "Wide", "Finish 5 tournaments"),
+  item("font", "script", "Script", "Attend 25 watchparties"),
+  item("font", "surf", "Surf", "Attend a summer watchparty"),
+  item("font", "gothic", "Gothic", "Win an arcane-set game"),
+  item("font", "runic", "Runic", "Win a fantasy-set game"),
+  item("font", "corsair", "Corsair", "Win 3 matches in one night"),
+  item("font", "metal", "Metal", "Win a Major final"),
+  item("font", "comic", "Comic", "Win from behind"),
+  item("font", "circuit", "Circuit", "Play 25 cyber-set games"),
+  item("font", "hover", "Hover", "Win a race"),
+  item("font", "retro", "Retro", "Play for a year"),
+  item("font", "arcade", "Arcade", "Play 50 bomberman games"),
+  item("font", "pixel", "Pixel", "Win 10 bomberman rounds"),
+  item("overlay", "crown", "Crown", "Win a Major", {
+    file: "crown.webp",
+    top: -40,
+    width: 70,
+    tilt: -8,
+    pixel: false,
+    visible: [0.027, 0.137, 0.973, 0.863]
+  }),
+  item("overlay", "halo", "Halo", "Help a new player (gift)", {
+    file: "halo.webp",
+    top: -34,
+    width: 76,
+    tilt: 0,
+    pixel: true,
+    visible: [0.023, 0.316, 0.969, 0.684]
+  }),
+  item("overlay", "horns", "Horns", "Win 10 games as the villain", {
+    file: "horns.webp",
+    top: -26,
+    width: 100,
+    tilt: 0,
+    pixel: true,
+    visible: [0.023, 0.129, 0.969, 0.871]
+  }),
+  item("overlay", "flowers", "Flower crown", "The anniversary of joining", {
+    file: "flowers.webp",
+    top: -22,
+    width: 96,
+    tilt: 0,
+    pixel: false,
+    visible: [0.027, 0.258, 0.969, 0.746]
+  }),
+  item("overlay", "runes", "Runes", "Finish a Major"),
+  item("overlay", "comet", "Comet", "A 10-game win streak"),
+  item("overlay", "shine", "Shine", "Win a cardtable match"),
+  item("overlay", "glow", "Glow", "Attend 25 watchparties"),
+  item("overlay", "petals", "Petals", "The anniversary of joining"),
+  item("message", "type", "Typewriter", "Send 1000 chat messages"),
+  item("message", "decode", "Decode", "Win 25 cyber-set games"),
+  item("message", "cascade", "Cascade", "Win 3 games in a row"),
+  item("message", "words", "Word by word", "Send 100 chat messages"),
+  item("message", "bubble", "Bubble", "Host 3 watchparties"),
+  item("message", "drift", "Drift", "Attend 20 watchparties")
+];
+var COSMETICS_BY_ID = new Map(
+  COSMETICS.map((i) => [i.id, i])
+);
+var PLACEMENT_DEFAULT = { x: 0, y: 0, r: 0, s: 100, flip: false, back: false };
+var PLACEMENT_LIMITS = {
+  x: [-60, 60],
+  y: [-60, 100],
+  r: [-45, 45],
+  s: [70, 140]
+};
+function overlayBounds(art, p) {
+  const [a, b, c, d] = art.visible;
+  const x0 = p.flip ? 1 - c : a;
+  const x1 = p.flip ? 1 - a : c;
+  const L = 50 - art.width / 2;
+  const T = art.top;
+  const W = art.width;
+  const ox = L + W * 0.5;
+  const oy = T + W * 0.6;
+  const cx = L + W / 2;
+  const cy = T + W / 2;
+  const t = art.tilt * Math.PI / 180;
+  const r = p.r * Math.PI / 180;
+  const sc = p.s / 100;
+  const xs = [];
+  const ys = [];
+  for (const [fx, fy] of [
+    [x0, b],
+    [x1, b],
+    [x0, d],
+    [x1, d]
+  ]) {
+    const px = L + fx * W;
+    const py = T + fy * W;
+    const tx = cx + (px - cx) * Math.cos(t) - (py - cy) * Math.sin(t);
+    const ty = cy + (px - cx) * Math.sin(t) + (py - cy) * Math.cos(t);
+    const dx = (tx - ox) * sc;
+    const dy = (ty - oy) * sc;
+    xs.push(ox + p.x + dx * Math.cos(r) - dy * Math.sin(r));
+    ys.push(oy + p.y + dx * Math.sin(r) + dy * Math.cos(r));
+  }
+  return {
+    left: Math.min(...xs),
+    top: Math.min(...ys),
+    right: Math.max(...xs),
+    bottom: Math.max(...ys)
+  };
+}
+var ART_ITEMS = COSMETICS.filter((i) => !!i.art);
+var PLACEMENT_ZONE = {
+  left: -25,
+  top: Math.floor(Math.min(...ART_ITEMS.map((i) => overlayBounds(i.art, PLACEMENT_DEFAULT).top))),
+  right: 125,
+  bottom: 110
+};
+var clamp = (v, [lo, hi]) => Math.min(hi, Math.max(lo, v));
+function fitPlacement(art, raw) {
+  const num = (v, fallback) => typeof v === "number" && Number.isFinite(v) ? v : fallback;
+  const p = {
+    x: Math.round(clamp(num(raw.x, 0), PLACEMENT_LIMITS.x)),
+    y: Math.round(clamp(num(raw.y, 0), PLACEMENT_LIMITS.y)),
+    r: Math.round(clamp(num(raw.r, 0), PLACEMENT_LIMITS.r)),
+    s: Math.round(clamp(num(raw.s, 100), PLACEMENT_LIMITS.s)),
+    flip: raw.flip === true,
+    back: raw.back === true
+  };
+  const z = PLACEMENT_ZONE;
+  let box = overlayBounds(art, p);
+  const room = Math.min(
+    (z.right - z.left - 2) / (box.right - box.left),
+    (z.bottom - z.top - 2) / (box.bottom - box.top)
+  );
+  if (room < 1) {
+    p.s = Math.max(PLACEMENT_LIMITS.s[0], Math.floor(p.s * room));
+    box = overlayBounds(art, p);
+  }
+  p.x += Math.ceil(Math.max(0, z.left - box.left)) - Math.ceil(Math.max(0, box.right - z.right));
+  p.y += Math.ceil(Math.max(0, z.top - box.top)) - Math.ceil(Math.max(0, box.bottom - z.bottom));
+  return p;
+}
+function emptyLoadout() {
+  return {
+    equipped: { effect: null, gradient: null, font: null, overlay: null, message: null },
+    placement: {}
+  };
+}
+function cleanLoadout(raw, owned) {
+  const out = emptyLoadout();
+  const src = raw && typeof raw === "object" ? raw : {};
+  for (const slot of COSMETIC_SLOTS) {
+    const id = src.equipped?.[slot];
+    if (typeof id === "string" && owned.has(id) && COSMETICS_BY_ID.get(id)?.slot === slot) {
+      out.equipped[slot] = id;
+    }
+  }
+  for (const [id, p] of Object.entries(src.placement ?? {})) {
+    const art = COSMETICS_BY_ID.get(id)?.art;
+    if (art && owned.has(id) && p && typeof p === "object") {
+      out.placement[id] = fitPlacement(art, p);
+    }
+  }
+  return out;
+}
+function wornCosmetics(loadout) {
+  const worn = {};
+  for (const slot of COSMETIC_SLOTS) {
+    const id = loadout.equipped[slot];
+    if (id) worn[slot] = id;
+  }
+  const overlay = loadout.equipped.overlay;
+  if (overlay && COSMETICS_BY_ID.get(overlay)?.art && loadout.placement[overlay]) {
+    worn.placement = loadout.placement[overlay];
+  }
+  return Object.keys(worn).length ? worn : void 0;
+}
+
+// src/cosmetics.ts
+var COSMETICS_ASSET_BASE = "/cosmetics";
+var STYLE_ID = "hadoku-cosmetics";
+var esc = (s) => s.replace(
+  /[&<>"']/g,
+  (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]
+);
+var nameOf = (id) => id ? id.slice(id.indexOf(".") + 1) : "none";
+function colourStyle(hex) {
+  return hex && /^#[0-9a-f]{6}$/i.test(hex) ? `--hc-base:${hex}` : "";
+}
+function placementTransform(p) {
+  const sx = p.s / 100 * (p.flip ? -1 : 1);
+  return `translate(calc(var(--hc-sz) * ${(p.x / 100).toFixed(3)}),calc(var(--hc-sz) * ${(p.y / 100).toFixed(3)})) rotate(${p.r}deg) scale(${sx.toFixed(3)},${(p.s / 100).toFixed(3)})`;
+}
+var SPLIT_EFFECTS = /* @__PURE__ */ new Set(["hop"]);
+function nameHtml(text, worn, opts = {}) {
+  const fx = nameOf(worn?.effect);
+  const gr = nameOf(worn?.gradient);
+  const font = nameOf(worn?.font);
+  const t = esc(text);
+  const split = SPLIT_EFFECTS.has(fx);
+  const tx = split ? `<span class="hc-tx">${[...text].map(
+    (c, i) => `<span class="hc-ch" style="--hc-i:${i}"><span class="hc-c">${c === " " ? "&nbsp;" : esc(c)}</span></span>`
+  ).join("")}</span>` : `<span class="hc-tx">${t}</span>`;
+  const layer = (cls2) => `<span class="hc-lyr${cls2}" aria-hidden="true">${t}</span>`;
+  let back = "";
+  let front = "";
+  if (fx === "aura" || fx === "outline") back += layer(" hc-g");
+  if (fx === "glint") front += `<span class="hc-win" aria-hidden="true">${layer("")}</span>`;
+  if (fx === "twinkle") {
+    front += [
+      [-6, -25, 0],
+      [52, 55, 0.95],
+      [94, -15, 1.9]
+    ].map(
+      ([x, y, d]) => `<i class="hc-tw" aria-hidden="true" style="left:${x}%;top:${y}%;animation-delay:${d}s"></i>`
+    ).join("");
+  }
+  const cls = `hc-name hc-fx-${fx} hc-gr-${gr} hc-font-${font}${split ? " hc-split" : ""}${opts.large ? " hc-large" : ""}`;
+  return `<span class="${cls}">${back}${tx}${front}</span>`;
+}
+var RUNES_SVG = (() => {
+  let marks = "";
+  for (let i = 0; i < 12; i++) {
+    marks += `<g transform="rotate(${i * 30} 50 50)"><path d="M50 3 l2.5 4 -2.5 4 -2.5 -4z" fill="currentColor" opacity="${i % 3 ? 0.55 : 1}"/></g>`;
+  }
+  return `<svg viewBox="0 0 100 100" aria-hidden="true"><circle cx="50" cy="50" r="44" fill="none" stroke="currentColor" stroke-width="1" stroke-dasharray="3 5" opacity=".7"/>${marks}</svg>`;
+})();
+function decorHtml(worn, assetBase = COSMETICS_ASSET_BASE) {
+  const id = worn?.overlay;
+  if (!id) return "";
+  const art = COSMETICS_BY_ID.get(id)?.art;
+  if (art) {
+    const p = worn?.placement ?? PLACEMENT_DEFAULT;
+    return `<span class="hc-ol hc-art${art.pixel ? " hc-px" : ""}" data-hc-art="${esc(id)}" style="left:${50 - art.width / 2}%;top:${art.top}%;width:${art.width}%;z-index:${p.back ? 0 : 3}"><span class="hc-adj" style="transform:${placementTransform(p)}"><img alt="" draggable="false" style="--hc-tilt:${art.tilt}deg" src="${esc(`${assetBase}/art/${art.file}`)}"></span></span>`;
+  }
+  switch (nameOf(id)) {
+    case "runes":
+      return `<span class="hc-ol hc-runes">${RUNES_SVG}</span>`;
+    case "comet":
+      return `<span class="hc-ol hc-comet"></span>`;
+    case "shine":
+      return `<span class="hc-ol hc-clip"><span class="hc-band"></span></span>`;
+    case "glow":
+      return `<span class="hc-ol hc-glow"></span>`;
+    case "petals":
+      return [15, 40, 62, 85].map(
+        (l, i) => `<i class="hc-ol hc-petal" style="left:${l}%;animation-delay:${(i * 0.85).toFixed(2)}s"></i>`
+      ).join("");
+    default:
+      return "";
+  }
+}
+function avatarHtml(o) {
+  const pic = o.src ? `<img alt="" src="${esc(o.src)}">` : "";
+  return `<span class="hc-av" style="--hc-sz:${o.size}px"><span class="hc-pic">${pic}</span>${decorHtml(o.worn, o.assetBase)}</span>`;
+}
+var GLYPHS = "!<>-_/[]{}=+*^?#%&01";
+var LETTER_MODES = /* @__PURE__ */ new Set(["type", "decode", "cascade"]);
+var REVEAL_MS = 1400;
+var LETTER_LIMIT = 160;
+function messageHtml(text, worn, opts = {}) {
+  let mode = nameOf(worn?.message);
+  if (mode === "none") return `<span class="hc-msg">${esc(text)}</span>`;
+  const words = text.split(/\s+/).filter(Boolean);
+  if (LETTER_MODES.has(mode) && text.length > LETTER_LIMIT) mode = "words";
+  const keep = opts.keep ? " data-hc-keep" : "";
+  let body;
+  let step;
+  if (LETTER_MODES.has(mode)) {
+    step = Math.min(38, REVEAL_MS / Math.max(1, text.length));
+    let n = 0;
+    const rnd = () => GLYPHS[Math.floor(Math.random() * GLYPHS.length)];
+    body = words.map(
+      (w) => `<span class="hc-w">${[...w].map((c) => {
+        const i = n++;
+        return mode === "decode" ? `<span class="hc-ch" style="--hc-i:${i}" data-g="${esc(rnd())}" data-h="${esc(rnd())}"><span class="hc-r">${esc(c)}</span></span>` : `<span class="hc-ch" style="--hc-i:${i}">${esc(c)}</span>`;
+      }).join("")}</span>`
+    ).join(" ");
+    if (mode === "type") body += `<span class="hc-caret" style="--hc-i:${n}"></span>`;
+    const lastClass = mode === "type" ? "hc-caret" : mode === "decode" ? "hc-r" : "hc-ch";
+    const at = body.lastIndexOf(`<span class="${lastClass}"`);
+    body = `${body.slice(0, at)}<span data-hc-last class="${lastClass}"${body.slice(at + `<span class="${lastClass}"`.length)}`;
+  } else {
+    step = Math.min(90, REVEAL_MS / Math.max(1, words.length));
+    body = words.map(
+      (w, i) => `<span class="hc-w" style="--hc-i:${i}"${i === words.length - 1 ? " data-hc-last" : ""}>${esc(w)}</span>`
+    ).join(" ");
+  }
+  return `<span class="hc-msg hc-mt-${mode}" style="--hc-step:${step.toFixed(1)}ms" data-text="${esc(text)}"${keep}><span class="hc-sr">${esc(text)}</span><span aria-hidden="true">${body}</span></span>`;
+}
+function finishReveal(e) {
+  const t = e.target;
+  if (e.pseudoElement || !t?.hasAttribute?.("data-hc-last")) return;
+  const msg = t.closest(".hc-msg");
+  if (!msg || msg.hasAttribute("data-hc-keep")) return;
+  msg.className = "hc-msg";
+  msg.removeAttribute("style");
+  msg.textContent = msg.getAttribute("data-text") ?? "";
+}
+var FONTS = {
+  script: {
+    file: "caveat",
+    family: "Caveat",
+    generic: "cursive",
+    css: "font-weight:700;font-size:1.3em;line-height:1"
+  },
+  surf: {
+    file: "pacifico",
+    family: "Pacifico",
+    generic: "cursive",
+    css: "font-weight:400;font-size:1.02em;line-height:1.1"
+  },
+  gothic: {
+    file: "gothic",
+    family: "Grenze Gotisch",
+    generic: "serif",
+    css: "font-weight:600;font-size:1.15em"
+  },
+  runic: { file: "uncial", family: "Uncial Antiqua", generic: "serif", css: "font-weight:400" },
+  corsair: {
+    file: "pirata",
+    family: "Pirata One",
+    generic: "serif",
+    css: "font-weight:400;font-size:1.12em;letter-spacing:.02em"
+  },
+  metal: {
+    file: "metal",
+    family: "Metal Mania",
+    generic: "cursive",
+    css: "font-weight:400;font-size:1.12em;letter-spacing:.02em"
+  },
+  comic: {
+    file: "bangers",
+    family: "Bangers",
+    generic: "cursive",
+    css: "font-weight:400;font-size:1.15em;letter-spacing:.05em"
+  },
+  circuit: {
+    file: "orbitron",
+    family: "Orbitron",
+    generic: "sans-serif",
+    css: "font-weight:700;letter-spacing:.03em"
+  },
+  hover: {
+    file: "audiowide",
+    family: "Audiowide",
+    generic: "sans-serif",
+    css: "font-weight:400;font-size:.92em"
+  },
+  retro: { file: "righteous", family: "Righteous", generic: "sans-serif", css: "font-weight:400" },
+  arcade: {
+    file: "bungee",
+    family: "Bungee",
+    generic: "sans-serif",
+    css: "font-weight:400;font-size:.9em"
+  },
+  pixel: {
+    file: "pixel",
+    family: "Press Start 2P",
+    generic: "monospace",
+    css: "font-weight:400;font-size:.62em;line-height:1.6"
+  }
+};
+function cosmeticsCss(assetBase = COSMETICS_ASSET_BASE) {
+  const fontFaces = Object.entries(FONTS).map(
+    ([k, f]) => `@font-face{font-family:"hc-${k}";src:url("${assetBase}/fonts/${f.file}.woff2") format("woff2");font-display:swap}`
+  ).join("\n");
+  const fontRules = Object.entries(FONTS).map(([k, f]) => `.hc-font-${k}{font-family:"hc-${k}","${f.family}",${f.generic};${f.css}}`).join("\n");
+  return `${fontFaces}
+/* Colours: everything derives from the character colour. */
+.hc-name,.hc-av,.hc-msg{--hc-b:var(--hc-base,currentColor);--hc-hi:color-mix(in oklch,var(--hc-b),white 50%);--hc-lo:color-mix(in oklch,var(--hc-b),black 50%);--hc-glow:color-mix(in oklch,var(--hc-b) 75%,transparent)}
+
+/* --- name ---
+   Bleed: a gradient is a background clipped to the letters, and a background covers only the box; script
+   swashes reach outside it. So the text box and every layer over it get room on all sides, cancelled by a
+   negative margin so nothing moves. */
+.hc-name{--hc-bx:.4em;--hc-by:.3em;--hc-grad:none;position:relative;display:inline-block;white-space:nowrap;color:var(--hc-b);font-weight:700;line-height:1.25}
+.hc-name.hc-large{font-size:1.6em}
+.hc-name .hc-tx{position:relative;z-index:1;display:inline-block;padding:var(--hc-by) var(--hc-bx);margin:calc(-1 * var(--hc-by)) calc(-1 * var(--hc-bx))}
+.hc-name .hc-lyr{position:absolute;left:calc(-1 * var(--hc-bx));top:calc(-1 * var(--hc-by));padding:var(--hc-by) var(--hc-bx);pointer-events:none;white-space:nowrap}
+.hc-name .hc-win{position:absolute;inset:calc(-1 * var(--hc-by)) calc(-1 * var(--hc-bx));overflow:hidden}
+.hc-name .hc-win .hc-lyr{left:0;top:0}
+.hc-name .hc-ch,.hc-name .hc-c{display:inline-block}
+.hc-gr-gild{--hc-grad:linear-gradient(180deg,var(--hc-hi) 0%,var(--hc-b) 55%,var(--hc-lo) 100%)}
+.hc-gr-gloss{--hc-grad:linear-gradient(180deg,color-mix(in oklch,var(--hc-hi),white 35%) 0%,var(--hc-hi) 36%,color-mix(in oklch,var(--hc-hi),var(--hc-b)) 48%,var(--hc-b) 60%,var(--hc-lo) 100%)}
+.hc-gr-split{--hc-grad:linear-gradient(180deg,var(--hc-hi) 0 52%,var(--hc-b) 52% 100%)}
+.hc-gr-brushed{--hc-grad:repeating-linear-gradient(90deg,transparent 0 1px,color-mix(in oklch,var(--hc-hi) 40%,transparent) 1px 2px),linear-gradient(180deg,var(--hc-hi),var(--hc-b) 55%,var(--hc-lo))}
+.hc-gr-lumen{--hc-grad:radial-gradient(ellipse 60% 90% at 50% 35%,var(--hc-hi),var(--hc-b) 55%,var(--hc-lo) 100%)}
+.hc-name:not(.hc-gr-none) .hc-tx{background:var(--hc-grad);-webkit-background-clip:text;background-clip:text;color:transparent}
+.hc-name.hc-split:not(.hc-gr-none) .hc-tx{background:none}
+.hc-name.hc-split:not(.hc-gr-none) .hc-tx .hc-c{padding:var(--hc-by) var(--hc-bx);margin:calc(-1 * var(--hc-by)) calc(-1 * var(--hc-bx));background:var(--hc-grad);-webkit-background-clip:text;background-clip:text;color:transparent}
+.hc-fx-glint .hc-win{z-index:3;animation:hc-win-go 4.5s cubic-bezier(.4,0,.2,1) infinite;-webkit-mask-image:linear-gradient(100deg,transparent 35%,#000 50%,transparent 65%);mask-image:linear-gradient(100deg,transparent 35%,#000 50%,transparent 65%)}
+.hc-fx-glint .hc-win .hc-lyr{color:var(--hc-hi);animation:hc-win-back 4.5s cubic-bezier(.4,0,.2,1) infinite}
+@keyframes hc-win-go{0%{transform:translateX(-100%)}55%,100%{transform:translateX(100%)}}
+@keyframes hc-win-back{0%{transform:translateX(100%)}55%,100%{transform:translateX(-100%)}}
+.hc-fx-aura .hc-lyr.hc-g{color:transparent;text-shadow:0 0 6px var(--hc-glow),0 0 14px var(--hc-glow);animation:hc-breathe 3s ease-in-out infinite}
+.hc-fx-outline .hc-lyr.hc-g{color:transparent;-webkit-text-stroke:3px var(--hc-hi);animation:hc-breathe 3.6s ease-in-out infinite}
+@keyframes hc-breathe{0%,100%{opacity:.25}50%{opacity:1}}
+.hc-fx-hop .hc-c{animation:hc-hop 3.6s ease-in-out calc(var(--hc-i) * 45ms) infinite}
+@keyframes hc-hop{0%,14%,100%{transform:none}5%{transform:translateY(-4px)}10%{transform:translateY(.5px)}}
+.hc-fx-twinkle .hc-tw{position:absolute;width:7px;height:7px;z-index:3;pointer-events:none;background:linear-gradient(var(--hc-hi),var(--hc-hi)) center/1.4px 100% no-repeat,linear-gradient(90deg,var(--hc-hi),var(--hc-hi)) center/100% 1.4px no-repeat;animation:hc-star 2.8s ease-in-out infinite both}
+@keyframes hc-star{0%,100%{opacity:0;transform:scale(.3) rotate(0deg)}25%{opacity:1;transform:scale(1) rotate(45deg)}50%{opacity:0;transform:scale(.3) rotate(90deg)}}
+.hc-font-caps{font-variant:small-caps;letter-spacing:.08em}
+.hc-font-wide{letter-spacing:.22em;font-weight:600;text-transform:uppercase;font-size:.82em}
+${fontRules}
+
+/* --- avatar --- */
+.hc-av{--hc-sz:40px;position:relative;display:inline-block;width:var(--hc-sz);height:var(--hc-sz);flex:none;isolation:isolate;vertical-align:middle}
+.hc-av .hc-pic{position:absolute;inset:0;border-radius:50%;overflow:hidden;z-index:1;background:color-mix(in oklch,var(--hc-b) 30%,transparent)}
+.hc-av .hc-pic img{width:100%;height:100%;display:block;object-fit:cover;image-rendering:pixelated}
+.hc-av .hc-ol{position:absolute;pointer-events:none}
+.hc-ol.hc-art{display:block}
+.hc-ol.hc-art .hc-adj{display:block;position:relative;transform-origin:50% 60%}
+.hc-ol.hc-art img{display:block;width:100%;height:auto;filter:drop-shadow(0 1px 1px rgba(0,0,0,.45));animation:hc-art-bob 3.4s ease-in-out infinite;-webkit-user-drag:none;user-select:none}
+.hc-ol.hc-art.hc-px img{image-rendering:pixelated}
+@keyframes hc-art-bob{0%,100%{transform:rotate(var(--hc-tilt,0deg)) translateY(0)}50%{transform:rotate(var(--hc-tilt,0deg)) translateY(-2px)}}
+.hc-ol.hc-runes{inset:-9px;z-index:2;color:var(--hc-hi);animation:hc-turn 14s linear infinite}
+.hc-ol.hc-runes svg{width:100%;height:100%;display:block}
+@keyframes hc-turn{to{transform:rotate(360deg)}}
+.hc-ol.hc-comet{inset:-6px;z-index:2;border-radius:50%;background:conic-gradient(from 0deg,transparent 0 270deg,color-mix(in oklch,var(--hc-hi) 10%,transparent) 300deg,var(--hc-hi) 358deg,transparent 360deg);-webkit-mask:radial-gradient(farthest-side,transparent calc(100% - 3px),#000 calc(100% - 3px));mask:radial-gradient(farthest-side,transparent calc(100% - 3px),#000 calc(100% - 3px));animation:hc-turn 2.4s linear infinite}
+.hc-ol.hc-clip{inset:0;border-radius:50%;overflow:hidden;z-index:2}
+.hc-ol .hc-band{position:absolute;top:-30%;left:0;width:45%;height:160%;background:linear-gradient(90deg,transparent,color-mix(in oklch,var(--hc-hi) 70%,transparent),transparent);transform:translateX(-130%) rotate(20deg);animation:hc-band 5s ease-in-out infinite}
+@keyframes hc-band{0%{transform:translateX(-130%) rotate(20deg)}45%,100%{transform:translateX(260%) rotate(20deg)}}
+.hc-ol.hc-glow{inset:-30%;border-radius:50%;z-index:0;background:radial-gradient(circle,var(--hc-glow) 0,transparent 65%);animation:hc-glowp 3.2s ease-in-out infinite}
+@keyframes hc-glowp{0%,100%{opacity:.35;transform:scale(.92)}50%{opacity:.9;transform:scale(1.04)}}
+.hc-ol.hc-petal{top:-8%;height:100%;width:5px;z-index:2;animation:hc-fall 3.4s linear infinite both}
+.hc-ol.hc-petal::after{content:"";position:absolute;left:0;top:0;width:5px;height:7px;border-radius:5px 0;background:#f7b6c8;transform:rotate(35deg)}
+@keyframes hc-fall{0%{transform:translate(0,0);opacity:0}12%{opacity:.9}100%{transform:translate(-6px,100%);opacity:0}}
+
+/* --- message reveal: fill backwards only; the page swaps back to plain text when it ends --- */
+.hc-sr{position:absolute;width:1px;height:1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap}
+.hc-msg .hc-w{display:inline-block;white-space:nowrap}
+.hc-msg .hc-ch{display:inline-block}
+.hc-mt-type .hc-ch{animation:hc-in .01s linear calc(var(--hc-i) * var(--hc-step)) backwards}
+.hc-mt-type .hc-caret{display:inline-block;width:2px;height:1em;margin-left:2px;vertical-align:-2px;background:var(--hc-b);opacity:0;animation:hc-caret 1.5s steps(1) calc(var(--hc-i) * var(--hc-step)) backwards}
+@keyframes hc-caret{0%{opacity:0}1%{opacity:1}20%{opacity:0}40%{opacity:1}60%{opacity:0}80%{opacity:1}100%{opacity:0}}
+.hc-mt-cascade .hc-ch{animation:hc-drop .35s cubic-bezier(.3,1.5,.5,1) calc(var(--hc-i) * var(--hc-step)) backwards}
+.hc-mt-decode .hc-ch{position:relative}
+.hc-mt-decode .hc-ch .hc-r{display:inline-block;animation:hc-in .01s linear calc(var(--hc-i) * var(--hc-step) + 260ms) backwards}
+.hc-mt-decode .hc-ch::before,.hc-mt-decode .hc-ch::after{position:absolute;left:0;top:0;color:var(--hc-b);opacity:0;animation:hc-dec-a .26s steps(1) calc(var(--hc-i) * var(--hc-step)) backwards}
+.hc-mt-decode .hc-ch::before{content:attr(data-g)}
+.hc-mt-decode .hc-ch::after{content:attr(data-h);animation-name:hc-dec-b}
+@keyframes hc-dec-a{0%{opacity:.85}50%,100%{opacity:0}}
+@keyframes hc-dec-b{0%{opacity:0}50%{opacity:.85}100%{opacity:0}}
+.hc-mt-words .hc-w{animation:hc-rise .4s ease-out calc(var(--hc-i) * var(--hc-step)) backwards}
+.hc-mt-bubble .hc-w{animation:hc-pop .35s cubic-bezier(.3,1.6,.5,1) calc(var(--hc-i) * var(--hc-step)) backwards}
+.hc-mt-drift .hc-w{animation:hc-slide .45s cubic-bezier(.2,.8,.2,1) calc(var(--hc-i) * var(--hc-step)) backwards}
+@keyframes hc-in{from{opacity:0}to{opacity:1}}
+@keyframes hc-drop{0%{transform:translateY(-10px);opacity:0}100%{transform:none;opacity:1}}
+@keyframes hc-rise{0%{transform:translateY(10px);opacity:0}100%{transform:none;opacity:1}}
+@keyframes hc-pop{0%{transform:scale(.6);opacity:0}100%{transform:scale(1);opacity:1}}
+@keyframes hc-slide{0%{transform:translateX(-18px);opacity:0}100%{transform:none;opacity:1}}
+
+.hc-idle .hc-name,.hc-idle .hc-name *,.hc-idle .hc-av *,.hc-idle .hc-av *::after{animation-play-state:paused!important}
+@media (prefers-reduced-motion:reduce){.hc-name *,.hc-av *,.hc-av *::after,.hc-msg *,.hc-msg *::before,.hc-msg *::after{animation:none!important}}
+`;
+}
+function ensureCosmeticsStyles(doc = document, assetBase = COSMETICS_ASSET_BASE) {
+  if (doc.getElementById(STYLE_ID)) return;
+  const style = doc.createElement("style");
+  style.id = STYLE_ID;
+  style.textContent = cosmeticsCss(assetBase);
+  doc.head.appendChild(style);
+  doc.addEventListener("animationend", finishReveal);
+}
+export {
+  COSMETICS,
+  COSMETICS_ASSET_BASE,
+  COSMETICS_BY_ID,
+  COSMETIC_ID_PATTERN,
+  COSMETIC_SLOTS,
+  PLACEMENT_DEFAULT,
+  PLACEMENT_LIMITS,
+  PLACEMENT_ZONE,
+  avatarHtml,
+  cleanLoadout,
+  colourStyle,
+  cosmeticsCss,
+  decorHtml,
+  emptyLoadout,
+  ensureCosmeticsStyles,
+  fitPlacement,
+  messageHtml,
+  nameHtml,
+  overlayBounds,
+  placementTransform,
+  wornCosmetics
+};

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@hadoku/prefs-client",
-  "version": "1.1.11",
-  "description": "Client SDK for the hadoku unified preferences store. Wraps /prefs/api/v1/* with localStorage caching, debounced writes, Zod-validated reads, and a usePrefs() React hook, plus match history, ratings and leaderboards for every game (./games), and the one resolved avatar per user (./avatar).",
+  "version": "1.1.12",
+  "gitHead": "c159fe6d0b90efa7e3cc65c00bde50b3f17529fe",
+  "description": "Client SDK for the hadoku unified preferences store. Wraps /prefs/api/v1/* with localStorage caching, debounced writes, Zod-validated reads, and a usePrefs() React hook, plus match history, ratings and leaderboards for every game (./games), the one resolved avatar per user (./avatar), and the avatar cosmetics renderer (./cosmetics).",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -33,6 +34,10 @@
     "./items": {
       "types": "./dist/items.d.ts",
       "default": "./dist/items.js"
+    },
+    "./cosmetics": {
+      "types": "./dist/cosmetics.d.ts",
+      "default": "./dist/cosmetics.js"
     }
   },
   "files": [
@@ -62,7 +67,8 @@
     "prefs",
     "sdk",
     "game-stats",
-    "avatar"
+    "avatar",
+    "cosmetics"
   ],
   "license": "ISC"
 }