@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.10

package/src/avatar/outputs/custom-element.ts

@@ -0,0 +1,140 @@
+/**
+ * `<dg-avatar>` (§3.8), registered by `defineAvatarElement()` (never as a
+ * side effect of importing). For DOM and React games and static pages:
+ *
+ * ```html
+ * <dg-avatar look="AV1…" size="48" expression="happy" look-x="-1" animate title="Sam's avatar"></dg-avatar>
+ * ```
+ *
+ * With `animate` it runs its own animator (blinks, idle motion) at up to
+ * 30 fps while visible; its `animator` property gives full control.
+ */
+import { animator, type Animator } from '../animator/animator';
+import { ready } from '../art-store';
+import { isExpression } from '../face';
+import type { BodyPose, Facing, Frame, Pose, RenderOptions, StatusProp } from '../render/types';
+import { renderElement, type AvatarElement } from './element';
+
+const FACINGS: readonly Facing[] = ['S', 'SE', 'E', 'NE', 'N', 'NW', 'W', 'SW'];
+const FRAMES: readonly Frame[] = ['head', 'bust', 'full'];
+const BODIES: readonly BodyPose[] = ['idle', 'walk', 'run', 'sit', 'play', 'wave', 'cheer', 'jump', 'dance', 'away'];
+const STATUSES: readonly StatusProp[] = ['goggles', 'headset', 'cards', 'controller', 'trophy', 'crown', 'book'];
+const FRAME_MS = 1000 / 30;
+
+/** The list member equal to `value`, if any (attribute values are untrusted). */
+const oneOf = <T extends string>(list: readonly T[], value: string | null): T | undefined => list.find((item) => item === value);
+
+const toNumber = (value: string | null): number | undefined => {
+  const parsed = value === null ? Number.NaN : Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+};
+
+/** The attributes `<dg-avatar>` watches. */
+export const AVATAR_ATTRIBUTES = ['look', 'size', 'frame', 'facing', 'expression', 'look-x', 'look-y', 'animate', 'title', 'background', 'body', 'status'] as const;
+
+/**
+ * Registers `<dg-avatar>` (or another tag). Safe to call more than once;
+ * a no-op outside a browser.
+ */
+export function defineAvatarElement(tag = 'dg-avatar'): void {
+  if (typeof customElements === 'undefined' || customElements.get(tag)) {
+    return;
+  }
+
+  class DgAvatar extends HTMLElement {
+    static readonly observedAttributes = AVATAR_ATTRIBUTES;
+    private view: AvatarElement | null = null;
+    private anim: Animator | null = null;
+    private raf = 0;
+    private last = 0;
+    private base = 'neutral';
+
+    /** The animator driving this element (created on first use). */
+    get animator(): Animator {
+      this.anim ??= animator(this.getAttribute('look') ?? '', { seed: this.getAttribute('look') ?? 'dg' });
+      return this.anim;
+    }
+
+    private options(): RenderOptions {
+      const background = this.getAttribute('background');
+      const frame = oneOf(FRAMES, this.getAttribute('frame'));
+      const facing = oneOf(FACINGS, this.getAttribute('facing'));
+      const title = this.getAttribute('title');
+      return {
+        size: toNumber(this.getAttribute('size')) ?? 48,
+        ...(frame ? { frame } : {}),
+        ...(facing ? { facing } : {}),
+        ...(title ? { title } : {}),
+        ...(background === 'none' || background === 'badge' ? { background } : background?.startsWith('#') ? { background: `#${background.slice(1)}` } : {}),
+      };
+    }
+
+    private stillPose(): Pose {
+      const expression = this.getAttribute('expression') ?? '';
+      const body = oneOf(BODIES, this.getAttribute('body'));
+      const status = oneOf(STATUSES, this.getAttribute('status'));
+      return {
+        ...(isExpression(expression) ? { expression } : {}),
+        look: { x: toNumber(this.getAttribute('look-x')) ?? 0, y: toNumber(this.getAttribute('look-y')) ?? 0 },
+        ...(body ? { body } : {}),
+        ...(status ? { status } : {}),
+      };
+    }
+
+    connectedCallback(): void {
+      this.style.display ||= 'inline-block';
+      this.style.lineHeight ||= '0';
+      this.view = renderElement(this.getAttribute('look') ?? '', this.options(), this.ownerDocument);
+      this.replaceChildren(this.view.el);
+      this.view.update(this.stillPose());
+      void ready();
+      this.loop();
+    }
+
+    disconnectedCallback(): void {
+      cancelAnimationFrame(this.raf);
+      this.raf = 0;
+    }
+
+    attributeChangedCallback(name: string): void {
+      if (!this.view) {
+        return;
+      }
+      if (name === 'look') {
+        const look = this.getAttribute('look') ?? '';
+        this.view.setLook(look);
+        this.anim?.setLook(look);
+      } else {
+        this.view.setOptions(this.options());
+      }
+      this.view.update(this.stillPose());
+      this.loop();
+    }
+
+    private loop(): void {
+      if (!this.hasAttribute('animate') || this.raf !== 0 || !this.isConnected) {
+        return;
+      }
+      const tick = (t: number): void => {
+        this.raf = 0;
+        if (!this.isConnected || !this.hasAttribute('animate')) {
+          return;
+        }
+        if (t - this.last >= FRAME_MS) {
+          this.last = t;
+          const expression = this.getAttribute('expression') ?? 'neutral';
+          if (expression !== this.base && isExpression(expression)) {
+            this.base = expression;
+            this.animator.setBase(expression, { at: t });
+          }
+          const still = this.stillPose();
+          this.view?.update({ ...this.animator.pose(t), ...(still.body ? { body: still.body } : {}), ...(still.status ? { status: still.status } : {}) });
+        }
+        this.raf = requestAnimationFrame(tick);
+      };
+      this.raf = requestAnimationFrame(tick);
+    }
+  }
+
+  customElements.define(tag, DgAvatar);
+}

package/src/avatar/outputs/element.ts

@@ -0,0 +1,58 @@
+/**
+ * `render.element`: a live DOM avatar. `update(pose)` re-renders only when
+ * the quantised pose changes, which is cheap enough for a dozen avatars at
+ * 30 fps in DOM games.
+ */
+import { onArtReady } from '../art-store';
+import { toCode } from '../look-like';
+import type { LookLike, Pose, RenderOptions } from '../render/types';
+import { renderKey } from './pose-key';
+import { renderSvg } from './svg';
+
+/** A live avatar element. */
+export interface AvatarElement {
+  /** The element to insert (an inline-block `<span>` holding the `<svg>`). */
+  readonly el: HTMLElement;
+  /** Shows a new pose (an animator's `pose(t)`). */
+  update(pose: Pose): void;
+  /** Swaps the look (a player changed their avatar). */
+  setLook(like: LookLike): void;
+  /** Changes size, frame, facing or other options. */
+  setOptions(opts: RenderOptions): void;
+}
+
+/** A live avatar element; it upgrades itself from the silhouette when the art loads. */
+export function renderElement(like: LookLike, opts: RenderOptions = {}, doc: Document = document): AvatarElement {
+  const el = doc.createElement('span');
+  el.className = 'dg-avatar';
+  el.style.display = 'inline-block';
+  el.style.lineHeight = '0';
+  let look = like;
+  let options = opts;
+  let key = '';
+  const draw = (isForced = false): void => {
+    const next = renderKey(toCode(look), options);
+    if (!isForced && next === key) {
+      return;
+    }
+    key = next;
+    el.innerHTML = renderSvg(look, options);
+  };
+  draw(true);
+  onArtReady(() => { draw(true); });
+  return {
+    el,
+    update(pose) {
+      options = { ...options, pose };
+      draw();
+    },
+    setLook(next) {
+      look = next;
+      draw(true);
+    },
+    setOptions(next) {
+      options = { ...next, ...(options.pose ? { pose: options.pose } : {}) };
+      draw(true);
+    },
+  };
+}

package/src/avatar/outputs/live-canvas.ts

@@ -0,0 +1,57 @@
+/**
+ * A canvas that holds one avatar and redraws only when the quantised pose,
+ * look or options change. The Pixi and three.js adapters upload it as a
+ * texture after each redraw.
+ */
+import { toCode } from '../look-like';
+import { pixelSize } from '../render/frame';
+import type { LookLike, Pose, RenderOptions } from '../render/types';
+import { renderCanvas } from './canvas';
+import type { Ctx2D } from './canvas-paint';
+import { renderKey } from './pose-key';
+
+/** A live avatar canvas. */
+export interface LiveCanvas {
+  readonly canvas: HTMLCanvasElement | OffscreenCanvas;
+  /** Redraws for a pose; `true` when the pixels changed (upload the texture). */
+  draw(pose: Pose | undefined): boolean;
+  setLook(like: LookLike): void;
+}
+
+function makeCanvas(w: number, h: number): { canvas: HTMLCanvasElement | OffscreenCanvas; ctx: Ctx2D | null } {
+  if (typeof document !== 'undefined') {
+    const canvas = document.createElement('canvas');
+    canvas.width = w;
+    canvas.height = h;
+    return { canvas, ctx: canvas.getContext('2d') };
+  }
+  const canvas = new OffscreenCanvas(w, h);
+  return { canvas, ctx: canvas.getContext('2d') };
+}
+
+/** A live canvas at `opts.size` × `resolution` device pixels. */
+export function liveCanvas(like: LookLike, opts: RenderOptions, resolution = 2): LiveCanvas {
+  const scaled = { ...opts, size: (opts.size ?? 64) * resolution };
+  const { width, height } = pixelSize(scaled);
+  const { canvas, ctx } = makeCanvas(Math.ceil(width), Math.ceil(height));
+  let look = like;
+  let key = '';
+  return {
+    canvas,
+    draw(pose) {
+      const options = { ...scaled, ...(pose ? { pose } : {}) };
+      const next = renderKey(toCode(look), options);
+      if (next === key || !ctx) {
+        return false;
+      }
+      key = next;
+      ctx.clearRect(0, 0, canvas.width, canvas.height);
+      renderCanvas(ctx, look, { ...options, x: 0, y: 0 });
+      return true;
+    },
+    setLook(next) {
+      look = next;
+      key = '';
+    },
+  };
+}

package/src/avatar/outputs/overlay-svg.ts

@@ -0,0 +1,22 @@
+/** An overlay as a standalone `<svg>` (for DOM surfaces) or painted on a canvas at its anchor. */
+import { n } from '../geom';
+import type { Overlay } from '../overlays';
+import { paintNodes, type Ctx2D } from './canvas-paint';
+import { sceneToSvg } from './svg-markup';
+import { nextPrefix } from './svg';
+
+/** The overlay as an `<svg>` of its own size (decorative). */
+export function overlaySvg(overlay: Overlay, scale = 1): string {
+  const [left, top, w, h] = overlay.box;
+  const { body, defs } = sceneToSvg(overlay.nodes, nextPrefix({}));
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${n(left)} ${n(top)} ${n(w)} ${n(h)}" width="${n(w * scale)}" height="${n(h * scale)}" aria-hidden="true">${defs ? `<defs>${defs}</defs>` : ''}${body}</svg>`;
+}
+
+/** Paints an overlay with its anchor at (x, y). */
+export function paintOverlay(ctx: Ctx2D, overlay: Overlay, atX: number, atY: number, scale = 1): void {
+  ctx.save();
+  ctx.translate(atX, atY);
+  ctx.scale(scale, scale);
+  paintNodes(ctx, overlay.nodes);
+  ctx.restore();
+}

package/src/avatar/outputs/pose-key.ts

@@ -0,0 +1,30 @@
+/** A compact key for a pose and options, quantised so tiny changes don't re-render or re-cache. */
+import type { FaceParams } from '../face';
+import type { Pose, RenderOptions } from '../render/types';
+
+const q = (v: number | undefined, step: number): string => (v === undefined ? '' : String(Math.round(v / step)));
+
+function faceKey(face: FaceParams | undefined): string {
+  if (!face) {
+    return '';
+  }
+  const m = face.mouth;
+  return [face.lidL, face.lidR, face.lowL, face.lowR, face.browL.dy, face.browL.tilt, face.browR.dy, face.browR.tilt, m.open, m.sL, m.sR, m.w, m.round, face.cheeks, face.headTilt]
+    .map((v) => q(v, 0.05)).join(',') + face.extras.join('');
+}
+
+/** The pose part of a cache key. */
+export function poseKey(pose: Pose | undefined): string {
+  if (!pose) {
+    return '-';
+  }
+  return [
+    pose.expression ?? '', faceKey(pose.face), q(pose.look?.x, 0.05), q(pose.look?.y, 0.05), q(pose.blink, 0.1), q(pose.talk, 0.1),
+    pose.body ?? '', q(pose.phase, 0.125), pose.status ?? '', q(pose.bob?.x, 0.25), q(pose.bob?.y, 0.25), q(pose.tilt, 0.5), q(pose.squash, 0.005),
+  ].join('|');
+}
+
+/** The full render key for caches: code, pose bucket, size, frame, facing and background. */
+export function renderKey(code: string, opts: RenderOptions): string {
+  return [code, poseKey(opts.pose), String(opts.size ?? 48), opts.frame ?? 'head', opts.facing ?? opts.view ?? 'S', opts.background ?? '', opts.rim ? 'r' : '', opts.stool ? 's' : '', opts.shadow === undefined ? '' : String(opts.shadow)].join('~');
+}

package/src/avatar/outputs/svg-markup.ts

@@ -0,0 +1,113 @@
+/**
+ * Scene → SVG markup. Ids for clips and the rim filter are prefixed per call,
+ * so many avatars can be inlined on one page. The output holds only numbers,
+ * derived colours and escaped overlay text, so it is safe to insert as HTML.
+ */
+import { n } from '../geom';
+import type { Clip, Paint, SceneNode, TfOp } from '../scene';
+
+/** The rim filter: a dilated, soft light edge behind the silhouette. */
+export const RIM_COLOUR = '#aab3c7';
+
+const FONTS = { mono: "'Space Mono', monospace", pixel: "'VT323', monospace" } as const;
+
+/** Three decimals, for scales and opacities. */
+const fine = (v: number): string => String(Math.round(v * 1000) / 1000);
+
+/** Escapes text for SVG content. */
+export function escapeXml(text: string): string {
+  return text.replace(/[&<>"']/g, (c) => `&#${String(c.charCodeAt(0))};`);
+}
+
+/** A transform list as an SVG `transform` attribute (empty for none). */
+export function tfAttr(tf: readonly TfOp[] | undefined): string {
+  if (!tf || tf.length === 0) {
+    return '';
+  }
+  const parts = tf.map((op) => {
+    switch (op.k) {
+      case 't': return `translate(${n(op.x)} ${n(op.y)})`;
+      case 's': return `scale(${fine(op.x)} ${fine(op.y)})`;
+      case 'r': return `rotate(${n(op.a)})`;
+      case 'skx': return `skewX(${n(op.a)})`;
+    }
+  });
+  return ` transform="${parts.join(' ')}"`;
+}
+
+function paintAttrs(p: Paint): string {
+  let out = ` fill="${p.fill ?? 'none'}"`;
+  if (p.evenOdd) {
+    out += ' fill-rule="evenodd"';
+  }
+  if (p.fillOpacity !== undefined) {
+    out += ` fill-opacity="${fine(p.fillOpacity)}"`;
+  }
+  if (p.stroke && p.stroke !== 'none') {
+    out += ` stroke="${p.stroke}" stroke-width="${n(p.sw ?? 1)}" stroke-linejoin="round" stroke-linecap="${p.cap ?? 'round'}"`;
+  }
+  if (p.opacity !== undefined && p.opacity < 1) {
+    out += ` opacity="${fine(p.opacity)}"`;
+  }
+  return out;
+}
+
+/** Collects `<defs>` while serialising. */
+class Writer {
+  readonly defs: string[] = [];
+  private count = 0;
+  usesRim = false;
+  private readonly prefix: string;
+
+  constructor(prefix: string) {
+    this.prefix = prefix;
+  }
+
+  id(kind: string): string {
+    this.count += 1;
+    return `${this.prefix}${kind}${this.count.toString(36)}`;
+  }
+
+  clip(clip: Clip): string {
+    const id = this.id('c');
+    const rule = clip.evenOdd ? ' clip-rule="evenodd"' : '';
+    this.defs.push(`<clipPath id="${id}">${clip.shapes.map((s) => this.node(s).replace('<path ', `<path${rule} `)).join('')}</clipPath>`);
+    return id;
+  }
+
+  node(node: SceneNode): string {
+    switch (node.k) {
+      case 'g': {
+        let attrs = tfAttr(node.tf);
+        if (node.clip) {
+          attrs += ` clip-path="url(#${this.clip(node.clip)})"`;
+        }
+        if (node.opacity !== undefined && node.opacity < 1) {
+          attrs += ` opacity="${fine(node.opacity)}"`;
+        }
+        if (node.rim) {
+          this.usesRim = true;
+          attrs += ` filter="url(#${this.prefix}rim)"`;
+        }
+        const inner = node.children.map((child) => this.node(child)).join('');
+        return attrs === '' ? inner : `<g${attrs}>${inner}</g>`;
+      }
+      case 'path': return `<path d="${node.d}"${tfAttr(node.tf)}${paintAttrs(node)}/>`;
+      case 'ellipse': return node.rx === node.ry
+        ? `<circle cx="${n(node.cx)}" cy="${n(node.cy)}" r="${n(node.rx)}"${tfAttr(node.tf)}${paintAttrs(node)}/>`
+        : `<ellipse cx="${n(node.cx)}" cy="${n(node.cy)}" rx="${n(node.rx)}" ry="${n(node.ry)}"${tfAttr(node.tf)}${paintAttrs(node)}/>`;
+      case 'rect': return `<rect x="${n(node.x)}" y="${n(node.y)}" width="${n(node.w)}" height="${n(node.h)}"${node.r ? ` rx="${n(node.r)}"` : ''}${tfAttr(node.tf)}${paintAttrs(node)}/>`;
+      case 'text': return `<text x="${n(node.x)}" y="${n(node.y)}" font-family="${FONTS[node.font]}" font-size="${n(node.size)}"${node.bold ? ' font-weight="700"' : ''}${node.anchor === 'middle' ? ' text-anchor="middle"' : ''} paint-order="stroke"${paintAttrs(node)}>${escapeXml(node.text)}</text>`;
+    }
+  }
+}
+
+/** A scene as SVG markup plus the `<defs>` it needs. */
+export function sceneToSvg(nodes: readonly SceneNode[], prefix: string): { readonly body: string; readonly defs: string } {
+  const writer = new Writer(prefix);
+  const body = nodes.map((node) => writer.node(node)).join('');
+  if (writer.usesRim) {
+    writer.defs.push(`<filter id="${prefix}rim" x="-20%" y="-20%" width="140%" height="140%"><feMorphology in="SourceAlpha" operator="dilate" radius="2.8" result="d"/><feFlood flood-color="${RIM_COLOUR}" flood-opacity=".48"/><feComposite in2="d" operator="in"/><feMerge><feMergeNode/><feMergeNode in="SourceGraphic"/></feMerge></filter>`);
+  }
+  return { body, defs: writer.defs.join('') };
+}

package/src/avatar/outputs/svg.ts

@@ -0,0 +1,41 @@
+/**
+ * `render.svg`: a complete `<svg>` string. Decorative (`aria-hidden`) unless
+ * a `title` is given, then `role="img"` with that accessible name (§3.9).
+ * Safe to insert as HTML: only catalog paths, derived colours and escaped
+ * text.
+ */
+import type { AvatarLook } from '@diffenderfer-games/hub-contract/avatar';
+import { n } from '../geom';
+import { toLook } from '../look-like';
+import { composeAvatar, type Composed } from '../render/compose';
+import { frameBox, framed, pixelSize } from '../render/frame';
+import type { LookLike, RenderOptions } from '../render/types';
+import { escapeXml, sceneToSvg } from './svg-markup';
+
+let calls = 0;
+
+/** The id prefix for one render: the caller's `idPrefix` as given (deterministic), else a fresh one per call. */
+export function nextPrefix(opts: RenderOptions): string {
+  if (opts.idPrefix !== undefined) {
+    return opts.idPrefix.replace(/[^a-zA-Z0-9_-]/g, '');
+  }
+  calls += 1;
+  return `dga${calls.toString(36)}-`;
+}
+
+/** The `<svg>` for an already composed avatar. */
+export function svgFromComposed(composed: Composed, look: AvatarLook | null, opts: RenderOptions): string {
+  const [left, top, w, h] = frameBox(opts);
+  const { width, height } = pixelSize(opts);
+  const { body, defs } = sceneToSvg(framed(composed.nodes, look, opts), nextPrefix(opts));
+  const a11y = opts.title ? ` role="img" aria-label="${escapeXml(opts.title)}"` : ' aria-hidden="true"';
+  const title = opts.title ? `<title>${escapeXml(opts.title)}</title>` : '';
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${String(left)} ${String(top)} ${String(w)} ${String(h)}" width="${n(width)}" height="${n(height)}"${a11y}>`
+    + `${title}${defs ? `<defs>${defs}</defs>` : ''}${body}</svg>`;
+}
+
+/** An avatar as SVG markup. */
+export function renderSvg(like: LookLike, opts: RenderOptions = {}): string {
+  const look = toLook(like);
+  return svgFromComposed(composeAvatar(look, opts), look, opts);
+}

package/src/avatar/overlays.ts

@@ -0,0 +1,128 @@
+/**
+ * Overlays drawn above an avatar (§3.11, §14.3), as scene nodes in screen
+ * pixels with the origin at the anchor they sit on (`nameplate`, `bubble`,
+ * `shadow`). Every surface draws them the same way. Text is a username or a
+ * catalog title, never player-typed bubble text, and is escaped on output.
+ */
+import { ellipse, g, line, path, rect, rot, tr, type SceneNode } from './scene';
+
+/** An overlay: nodes around its anchor, plus its size for culling and layout. */
+export interface Overlay {
+  readonly nodes: readonly SceneNode[];
+  readonly width: number;
+  readonly height: number;
+  /** Its bounds around the anchor: x, y, width, height. */
+  readonly box: readonly [number, number, number, number];
+}
+
+const INK = '#0d0f14';
+const PAPER = '#e8e6df';
+const MONO_ADVANCE = 0.6;
+
+const textWidth = (text: string, size: number): number => Array.from(text).length * size * MONO_ADVANCE;
+
+/** A name tag: the username in a pill; friends get a green dot and a ★ (never colour alone), you get an accent outline. */
+export function nameTag(o: { readonly name: string; readonly friend?: boolean; readonly you?: boolean; readonly muted?: boolean }): Overlay {
+  const size = 12;
+  const lead = o.friend ? 22 : 0;
+  const w = textWidth(o.name, size) + 16 + lead;
+  const h = 19;
+  const nodes: SceneNode[] = [
+    rect(-w / 2, -h, w, h, { fill: INK, fillOpacity: 0.86, stroke: o.you ? '#ff5f3b' : '#2a3142', sw: o.you ? 2 : 1.2 }, h / 2),
+  ];
+  if (o.friend) {
+    nodes.push(
+      ellipse(-w / 2 + 10, -h / 2, 3.6, 3.6, { fill: '#4ade80' }),
+      { k: 'text', x: -w / 2 + 19, y: -5, text: '★', size: 11, font: 'mono', anchor: 'middle', fill: '#ffd23f' },
+    );
+  }
+  nodes.push({ k: 'text', x: lead / 2, y: -5.5, text: o.name, size, font: 'mono', bold: true, anchor: 'middle', fill: o.muted ? '#6f7787' : PAPER });
+  return { nodes, width: w, height: h, box: [-w / 2, -h, w, h] };
+}
+
+/** A small game glyph for the activity bubble. */
+export type ActivityIcon = 'cards' | 'controller' | 'puzzle' | 'race';
+
+function icon(kind: ActivityIcon): SceneNode {
+  switch (kind) {
+    case 'cards':
+      return g([
+        rect(-6, -8, 12, 16, { fill: '#ff5f3b', stroke: INK, sw: 1.6 }, 2.5),
+        g([rect(-1, -11, 12, 16, { fill: '#3d7bff', stroke: INK, sw: 1.6 }, 2.5)], { tf: [rot(18)] }),
+      ], { tf: [rot(-10)] });
+    case 'controller':
+      return path('M-9 -2C-9 -7 9 -7 9 -2C11 6 6 8 3 4L-3 4C-6 8 -11 6 -9 -2Z', { fill: '#2a3142', stroke: INK, sw: 1.6 });
+    case 'puzzle':
+      return path('M-7 -7H-1C-1 -11 4 -11 4 -7H7V-1C11 -1 11 4 7 4V7H-7Z', { fill: '#4ade80', stroke: INK, sw: 1.6 });
+    case 'race':
+      return path('M-7 -8V8M-7 -8H7L4 -4L7 0H-7', { fill: '#ffd23f', stroke: INK, sw: 1.6 });
+  }
+}
+
+/** "Playing Uno": the game's catalog title in a light bubble with a tail. */
+export function activityBubble(o: { readonly game: string; readonly icon?: ActivityIcon; readonly verb?: string }): Overlay {
+  const text = `${o.verb ?? 'Playing'} ${o.game}`;
+  const w = textWidth(text, 12) + 40;
+  const h = 26;
+  return {
+    nodes: [
+      rect(-w / 2, -h - 7, w, h, { fill: PAPER, stroke: INK, sw: 2 }, 8),
+      path('M-6 -7.5L0 0L6 -7.5Z', { fill: PAPER, stroke: INK, sw: 2 }),
+      rect(-7, -10, 14, 4, { fill: PAPER }),
+      g([icon(o.icon ?? 'cards')], { tf: [tr(-w / 2 + 16, -h / 2 - 7)] }),
+      { k: 'text', x: 10, y: -h / 2 - 2.5, text, size: 12, font: 'mono', bold: true, anchor: 'middle', fill: INK },
+    ],
+    width: w,
+    height: h + 7,
+    box: [-w / 2, -h - 7, w, h + 7],
+  };
+}
+
+/** An emote popping above the head (the hub's quick-chat emotes). */
+export function emoteBubble(emote: string): Overlay {
+  const glyph = emote.startsWith('e:') ? emote.slice(2) : emote;
+  return {
+    nodes: [
+      ellipse(0, -24, 20, 17, { fill: PAPER, stroke: INK, sw: 2 }),
+      path('M-5 -9L0 0L5 -9Z', { fill: PAPER, stroke: INK, sw: 2 }),
+      ellipse(0, -10, 5, 2.4, { fill: PAPER }),
+      { k: 'text', x: 0, y: -17, text: glyph, size: 20, font: 'mono', anchor: 'middle', fill: INK },
+    ],
+    width: 40,
+    height: 42,
+    box: [-21, -42, 42, 42],
+  };
+}
+
+/** Small state glyphs: `!`, `?`, `…` (typing), `zzz`, `♥`. */
+export type ReactionGlyph = '!' | '?' | '…' | 'zzz' | '♥';
+
+/** A reaction glyph in a small bubble. */
+export function reactionBubble(glyph: ReactionGlyph): Overlay {
+  const colour = glyph === '♥' ? '#ff5f8f' : glyph === '!' ? '#ff5f3b' : INK;
+  return {
+    nodes: [
+      rect(-15, -30, 30, 24, { fill: PAPER, stroke: INK, sw: 2 }, 9),
+      path('M-4 -6.5L0 0L4 -6.5Z', { fill: PAPER, stroke: INK, sw: 2 }),
+      rect(-5, -9, 10, 4, { fill: PAPER }),
+      { k: 'text', x: 0, y: -12, text: glyph, size: glyph === 'zzz' ? 12 : 17, font: 'mono', bold: true, anchor: 'middle', fill: colour },
+    ],
+    width: 30,
+    height: 30,
+    box: [-16, -31, 32, 31],
+  };
+}
+
+/** The hover or selection ring at the feet (`radius` in px). */
+export function selectionRing(o: { readonly radius?: number; readonly selected?: boolean } = {}): Overlay {
+  const r = o.radius ?? 18;
+  return {
+    nodes: [ellipse(0, 0, r, r * 0.3, line(o.selected ? '#ff5f3b' : '#e8e6df', o.selected ? 2.4 : 1.6, 'round', 0.85))],
+    width: r * 2,
+    height: r * 0.6,
+    box: [-r - 2, -r * 0.3 - 2, r * 2 + 4, r * 0.6 + 4],
+  };
+}
+
+/** Every overlay builder, as the `overlays` namespace. */
+export const overlays = { nameTag, activityBubble, emoteBubble, reactionBubble, selectionRing };