@diffenderfer-games/hub 2.0.0-next.1 → 2.0.0-next.11

package/src/avatar/adapters/pixi-types.ts

@@ -0,0 +1,84 @@
+/**
+ * The slice of PixiJS the adapters use, typed structurally so the hub has no
+ * dependency on pixi. Pixi 8 is the target; Pixi 7 works through the same
+ * calls where they exist (`Texture.from(canvas)`, `texture.update()`).
+ */
+
+/** A canvas-like source Pixi can upload. */
+export type PixiSource = HTMLCanvasElement | OffscreenCanvas;
+
+/** A texture's uploadable source (Pixi 8). */
+export interface PixiTextureSource {
+  update(): void;
+}
+
+/** A texture (Pixi 8: `source.update()`; Pixi 7: `update()`). */
+export interface PixiTexture {
+  readonly source?: PixiTextureSource;
+  update?(): void;
+  destroy(destroySource?: boolean): void;
+}
+
+/** A display object's shared fields. */
+export interface PixiDisplay {
+  x: number;
+  y: number;
+  visible: boolean;
+  alpha: number;
+  zIndex: number;
+  readonly scale: { x: number; y: number; set(x: number, y?: number): void };
+  destroy(options?: { children?: boolean }): void;
+}
+
+/** A sprite showing a `TTexture`. */
+export interface PixiSprite<TTexture extends PixiTexture = PixiTexture> extends PixiDisplay {
+  texture: TTexture;
+  readonly anchor: { set(x: number, y?: number): void };
+}
+
+/** A container that takes `TChild` sprites. */
+export interface PixiContainer<TChild extends PixiDisplay = PixiSprite> extends PixiDisplay {
+  sortableChildren: boolean;
+  addChild(child: TChild): void;
+  removeChild(child: TChild): void;
+}
+
+/** A frame rectangle. */
+export interface PixiRectangle {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * The PIXI namespace, as passed in by the game (`import * as PIXI from
+ * 'pixi.js'`, or an object of the named imports). It is generic over the
+ * game's own classes, inferred from what is passed, so the sprites and
+ * textures that come back are pixi's own types and go straight into a
+ * `Container` with no cast.
+ */
+export interface PixiNs<
+  TTexture extends PixiTexture = PixiTexture,
+  TSprite extends PixiSprite<TTexture> = PixiSprite<TTexture>,
+  TRectangle extends PixiRectangle = PixiRectangle,
+> {
+  readonly Texture: {
+    from(source: PixiSource): TTexture;
+    new (options: { source: NonNullable<TTexture['source']>; frame: TRectangle }): TTexture;
+  };
+  readonly Sprite: new (texture?: TTexture) => TSprite;
+  /** Not used by the adapters; accepted so an object of the named imports can include it. */
+  readonly Container?: new () => PixiDisplay;
+  readonly Rectangle: new (x: number, y: number, width: number, height: number) => TRectangle;
+}
+
+/** Re-uploads a texture after its canvas changed (Pixi 8 and 7). */
+export function refresh(texture: PixiTexture): void {
+  if (texture.source) {
+    texture.source.update();
+  } else {
+    texture.update?.();
+  }
+}
+

package/src/avatar/adapters/three.ts

@@ -0,0 +1,126 @@
+/**
+ * three.js helpers (§3.8): an avatar on a `CanvasTexture` (redrawn only when
+ * the pose changes, at most 30 times a second) and a ready-made `Sprite`.
+ * Pass the game's three namespace; the hub never imports three. A 3D head is
+ * out of scope (§14.4, Q11).
+ */
+import type { Animator } from '../animator/animator';
+import { liveCanvas } from '../outputs/live-canvas';
+import type { LookLike, Pose, RenderOptions } from '../render/types';
+
+/**
+ * The slice of three.js {@link avatarCanvasTexture} uses: `import * as THREE
+ * from 'three'`, or an object of the named imports. Generic over the game's
+ * own `CanvasTexture`, inferred from what is passed, so the texture that comes
+ * back is three's own type.
+ */
+export interface ThreeTextureNs<TTexture extends ThreeTexture = ThreeTexture> {
+  readonly CanvasTexture: new (canvas: HTMLCanvasElement | OffscreenCanvas) => TTexture;
+  readonly SRGBColorSpace?: string;
+}
+
+/**
+ * The slice of three.js {@link avatarSprite} uses (the namespace, or the named
+ * imports). The sprite that comes back is three's own `Sprite`, so
+ * `scene.add(sprite)` needs no cast. `TMap` is what the game's
+ * `SpriteMaterial` takes as its `map` (three's `Texture`); it is inferred on
+ * its own so an inline object of the named imports infers too.
+ */
+export interface ThreeNs<
+  TTexture extends ThreeTexture = ThreeTexture,
+  TMaterial extends ThreeMaterial = ThreeMaterial,
+  TSprite extends ThreeSprite = ThreeSprite,
+  TMap = TTexture,
+> extends ThreeTextureNs<TTexture> {
+  readonly SpriteMaterial: new (params: { map: TMap; transparent: boolean }) => TMaterial;
+  readonly Sprite: new (material: TMaterial) => TSprite;
+}
+
+/** A texture. */
+export interface ThreeTexture {
+  needsUpdate: boolean;
+  colorSpace?: string;
+  dispose(): void;
+}
+
+/** A material. */
+export interface ThreeMaterial {
+  dispose(): void;
+}
+
+/** A sprite. */
+export interface ThreeSprite {
+  readonly scale: { set(x: number, y: number, z: number): void };
+}
+
+/** Options for the three.js helpers. */
+export interface ThreeAvatarOptions extends RenderOptions {
+  readonly animator?: Animator;
+  /** Texture pixels per `size` pixel (default 2). */
+  readonly resolution?: number;
+}
+
+/** A live avatar texture; `texture` is the game's own `CanvasTexture`. */
+export interface ThreeAvatarTexture<TTexture extends ThreeTexture = ThreeTexture> {
+  readonly texture: TTexture;
+  /** Redraws for the animator's pose at `t` (or a given pose), at most 30 times a second. */
+  update(t: number | Pose): void;
+  setLook(like: LookLike): void;
+  dispose(): void;
+}
+
+const MIN_FRAME_MS = 1000 / 30;
+
+/** A `CanvasTexture` showing the avatar. */
+export function avatarCanvasTexture<TTexture extends ThreeTexture>(
+  three: ThreeTextureNs<TTexture>,
+  like: LookLike,
+  opts: ThreeAvatarOptions = {},
+): ThreeAvatarTexture<TTexture> {
+  const live = liveCanvas(like, opts, opts.resolution ?? 2);
+  live.draw(opts.pose);
+  const texture = new three.CanvasTexture(live.canvas);
+  if (three.SRGBColorSpace) {
+    texture.colorSpace = three.SRGBColorSpace;
+  }
+  let last = -Infinity;
+  return {
+    texture,
+    update(t) {
+      if (typeof t === 'number') {
+        if (t - last < MIN_FRAME_MS) {
+          return;
+        }
+        last = t;
+      }
+      const pose = typeof t === 'number' ? opts.animator?.pose(t) : t;
+      if (live.draw(pose ?? opts.pose)) {
+        texture.needsUpdate = true;
+      }
+    },
+    setLook(next) {
+      live.setLook(next);
+      opts.animator?.setLook(next);
+      if (live.draw(opts.pose)) {
+        texture.needsUpdate = true;
+      }
+    },
+    dispose() {
+      texture.dispose();
+    },
+  };
+}
+
+/** A billboard `Sprite` of the avatar, `height` world units tall (default 1). */
+export function avatarSprite<TTexture extends ThreeTexture & TMap, TMaterial extends ThreeMaterial, TSprite extends ThreeSprite, TMap>(
+  three: ThreeNs<TTexture, TMaterial, TSprite, TMap>,
+  like: LookLike,
+  opts: ThreeAvatarOptions & { readonly height?: number } = {},
+): { readonly sprite: TSprite; readonly avatar: ThreeAvatarTexture<TTexture> } {
+  const avatar = avatarCanvasTexture(three, like, opts);
+  const sprite = new three.Sprite(new three.SpriteMaterial({ map: avatar.texture, transparent: true }));
+  const h = opts.height ?? 1;
+  const aspect = opts.frame === 'full' ? 172 / 206 : 1;
+  sprite.scale.set(h * aspect, h, 1);
+  return { sprite, avatar };
+}

package/src/avatar/animator/animator.ts

@@ -0,0 +1,285 @@
+/**
+ * The animator (avatars.md §3.7): a pure, time-based face and body driver.
+ * Every call (`express`, `lookAt`, `react`, …) appends to a timestamped
+ * schedule and `pose(t)` evaluates it, with no clock or animation frame of
+ * its own: the same schedule and `t` always give the same pose, so it suits
+ * game loops, Pixi tickers, three.js, CSS-driven DOM, tests and replays.
+ */
+import { hashSeed } from '@diffenderfer-games/hub-contract/avatar';
+import { EXPRESSIONS, faceOf, mix, type Expression, type FaceParams } from '../face';
+import type { BodyPose, LookDir, LookLike, Pose, StatusProp } from '../render/types';
+import { REACTIONS, STILL, type Reaction, type ReactionFrame } from './reactions';
+import { blinkAt, breathAt, microSmileAt, wanderAt } from './schedule';
+
+/** Options for {@link animator}. */
+export interface AnimatorOptions {
+  /** Seeds blinks and idle motion (a user id is ideal). */
+  readonly seed?: string | number;
+  /** `'auto'` reads `prefers-reduced-motion`; `true` forces it. */
+  readonly reducedMotion?: 'auto' | boolean;
+  /** Idle bob, sway, wandering gaze and micro expressions (default on). */
+  readonly idle?: boolean;
+  /** The resting expression (default `neutral`). */
+  readonly base?: Expression;
+  /** The time source for calls without `at` (default `performance.now()`). */
+  readonly clock?: () => number;
+}
+
+/** When a call happens; defaults to the animator's clock. */
+export interface At {
+  readonly at?: number;
+}
+
+/** Game events mapped to tuned faces, so every game feels the same. */
+export type Feeling = 'win' | 'lose' | 'bigPlay' | 'victim' | 'waiting' | 'yourTurn' | 'idle';
+
+interface ExpressEvent { readonly t: number; readonly face: FaceParams; readonly fade: number; readonly hold: number }
+interface BaseEvent { readonly t: number; readonly face: FaceParams; readonly fade: number }
+interface LookEvent { readonly t: number; readonly target: LookDir | null; readonly speed: number }
+interface TalkEvent { readonly t: number; readonly level: number; readonly until: number }
+interface ReactEvent { readonly t: number; readonly reaction: Reaction }
+interface BodyEvent { readonly t: number; readonly body: BodyPose; readonly cycleMs: number }
+interface StatusEvent { readonly t: number; readonly status: StatusProp | null }
+
+const KEEP = 48;
+const push = <T>(list: T[], item: T): void => {
+  list.push(item);
+  if (list.length > KEEP) {
+    list.shift();
+  }
+};
+/** The last event at or before t. */
+const latest = <T extends { readonly t: number }>(list: readonly T[], t: number): T | undefined => {
+  for (let i = list.length - 1; i >= 0; i -= 1) {
+    const e = list[i];
+    if (e && e.t <= t) {
+      return e;
+    }
+  }
+  return undefined;
+};
+const easeOut = (u: number): number => 1 - (1 - Math.min(1, Math.max(0, u))) ** 2;
+
+function prefersReducedMotion(): boolean {
+  return typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+}
+
+/** A face and body driver for one avatar. */
+export class Animator {
+  /** Reduced motion: no idle bob, sway or reaction movement; quick cross-fades; a static open mouth when talking. */
+  readonly reducedMotion: boolean;
+  private readonly seed: number;
+  private readonly idle: boolean;
+  private readonly clock: () => number;
+  private readonly bases: BaseEvent[] = [];
+  private readonly expresses: ExpressEvent[] = [];
+  private readonly looks: LookEvent[] = [];
+  private readonly talks: TalkEvent[] = [];
+  private readonly reacts: ReactEvent[] = [];
+  private readonly bodies: BodyEvent[] = [];
+  private readonly statuses: StatusEvent[] = [];
+  private current: LookLike;
+
+  constructor(look: LookLike, opts: AnimatorOptions = {}) {
+    this.current = look;
+    this.seed = hashSeed(opts.seed ?? (typeof look === 'string' ? look : 'dg'));
+    this.idle = opts.idle ?? true;
+    this.reducedMotion = opts.reducedMotion === 'auto' || opts.reducedMotion === undefined ? prefersReducedMotion() : opts.reducedMotion;
+    this.clock = opts.clock ?? (() => (typeof performance === 'undefined' ? Date.now() : performance.now()));
+    this.bases.push({ t: -Infinity, face: EXPRESSIONS[opts.base ?? 'neutral'], fade: 0 });
+  }
+
+  /** The look this animator drives (adapters render it with each pose). */
+  get look(): LookLike {
+    return this.current;
+  }
+
+  /** Swaps the look (an `ev:avatar` change) without resetting the schedule. */
+  setLook(look: LookLike): this {
+    this.current = look;
+    return this;
+  }
+
+  private now(o?: At): number {
+    return o?.at ?? this.clock();
+  }
+
+  private fade(ms: number): number {
+    return this.reducedMotion ? Math.min(ms, 120) : ms;
+  }
+
+  /** Shows an expression (or raw parameters), then returns to the base. */
+  express(e: Expression | FaceParams, o: At & { readonly fadeMs?: number; readonly holdMs?: number } = {}): this {
+    push(this.expresses, { t: this.now(o), face: faceOf(e), fade: this.fade(o.fadeMs ?? 180), hold: o.holdMs ?? 1500 });
+    return this;
+  }
+
+  /** Sets the resting expression. */
+  setBase(e: Expression | FaceParams, o: At & { readonly fadeMs?: number } = {}): this {
+    push(this.bases, { t: this.now(o), face: faceOf(e), fade: this.fade(o.fadeMs ?? 250) });
+    return this;
+  }
+
+  /** Eases the gaze toward a direction; `null` goes back to wandering (or the centre with `idle: false`). */
+  lookAt(target: LookDir | null, o: At & { readonly speed?: number } = {}): this {
+    push(this.looks, { t: this.now(o), target, speed: o.speed ?? 6 });
+    return this;
+  }
+
+  /** Flaps the mouth until `talk(false)`. */
+  talk(isOn: boolean, o: At = {}): this {
+    const t = this.now(o);
+    push(this.talks, { t, level: isOn ? 1 : 0, until: Infinity });
+    return this;
+  }
+
+  /** Talks for a duration. */
+  talkFor(ms: number, o: At = {}): this {
+    const t = this.now(o);
+    push(this.talks, { t, level: 1, until: t + ms });
+    return this;
+  }
+
+  /** Drives the mouth from audio amplitude (0 … 1). */
+  talkLevel(level: number, o: At = {}): this {
+    push(this.talks, { t: this.now(o), level: Math.max(0, Math.min(1, level)), until: Infinity });
+    return this;
+  }
+
+  /** Plays a one-shot reaction. */
+  react(reaction: Reaction, o: At = {}): this {
+    push(this.reacts, { t: this.now(o), reaction });
+    return this;
+  }
+
+  /** Sets the body pose; cycle poses (`walk`, `run`, `dance`) loop every `cycleMs`. */
+  setBody(body: BodyPose, o: At & { readonly cycleMs?: number } = {}): this {
+    push(this.bodies, { t: this.now(o), body, cycleMs: o.cycleMs ?? (body === 'run' ? 320 : 520) });
+    return this;
+  }
+
+  /** Sets or clears the status prop. */
+  setStatus(status: StatusProp | null, o: At = {}): this {
+    push(this.statuses, { t: this.now(o), status });
+    return this;
+  }
+
+  /** Plays the tuned face and reaction for a game event. */
+  feel(feeling: Feeling, o: At = {}): this {
+    const at = { at: this.now(o) };
+    switch (feeling) {
+      case 'win': return this.express('laugh', { ...at, holdMs: 1800 }).react('cheer', at);
+      case 'lose': return this.express('sad', { ...at, holdMs: 1800 });
+      case 'bigPlay': return this.express('grin', at).react('bounce', at);
+      case 'victim': return this.express('shocked', { ...at, holdMs: 900 }).react('flinch', at);
+      case 'waiting': return this.setBase('thinking', at);
+      case 'yourTurn': return this.express('determined', at).react('nod', at);
+      case 'idle': return this.setBase('neutral', at);
+    }
+  }
+
+  private faceAt(t: number): FaceParams {
+    const base = latest(this.bases, t);
+    const prior = base ? latest(this.bases.filter((b) => b.t < base.t), t) : undefined;
+    let face = base ? (prior && base.fade > 0 ? mix(prior.face, base.face, easeOut((t - base.t) / base.fade)) : base.face) : EXPRESSIONS.neutral;
+    if (this.idle) {
+      const smile = microSmileAt(this.seed, t);
+      if (smile > 0) {
+        face = mix(face, 'happy', smile);
+      }
+    }
+    const e = latest(this.expresses, t);
+    if (e) {
+      const dt = t - e.t;
+      const total = e.fade * 2 + e.hold;
+      if (dt < total) {
+        const w = dt < e.fade ? easeOut(dt / e.fade) : dt < e.fade + e.hold ? 1 : 1 - easeOut((dt - e.fade - e.hold) / e.fade);
+        face = mix(face, e.face, w);
+      }
+    }
+    const r = latest(this.reacts, t);
+    const track = r ? REACTIONS[r.reaction] : undefined;
+    if (r && track?.expression && t - r.t < track.ms) {
+      face = mix(face, track.expression, Math.min(1, ((t - r.t) / 120)));
+    }
+    return face;
+  }
+
+  private gazeAt(t: number): LookDir {
+    let from: LookDir = { x: 0, y: 0 };
+    let current: LookEvent | undefined;
+    for (const e of this.looks) {
+      if (e.t > t) {
+        break;
+      }
+      if (current) {
+        from = this.approach(from, current, e.t);
+      }
+      current = e;
+    }
+    if (!current || current.target === null) {
+      const wander = this.idle && !this.reducedMotion ? wanderAt(this.seed, t) : { x: 0, y: 0 };
+      return current ? this.approach(from, { ...current, target: wander }, t) : wander;
+    }
+    return this.approach(from, current, t);
+  }
+
+  private approach(from: LookDir, e: LookEvent, t: number): LookDir {
+    const target = e.target ?? { x: 0, y: 0 };
+    const k = this.reducedMotion ? 1 : 1 - Math.exp((-e.speed * Math.max(0, t - e.t)) / 1000);
+    return { x: from.x + (target.x - from.x) * k, y: from.y + (target.y - from.y) * k };
+  }
+
+  private talkAt(t: number): number {
+    const e = latest(this.talks, t);
+    if (!e || e.level === 0 || t > e.until) {
+      return 0;
+    }
+    if (this.reducedMotion) {
+      return 0.5 * e.level;
+    }
+    const flap = Math.abs(Math.sin((t - e.t) / 1000 * Math.PI * 5.5)) * (0.65 + 0.35 * Math.sin((t - e.t) / 1000 * 3.1));
+    return e.level * flap;
+  }
+
+  private reactionAt(t: number): { readonly frame: ReactionFrame; readonly body?: BodyPose } {
+    const r = latest(this.reacts, t);
+    if (!r) {
+      return { frame: STILL };
+    }
+    const track = REACTIONS[r.reaction];
+    const u = (t - r.t) / track.ms;
+    if (u >= 1) {
+      return { frame: STILL };
+    }
+    return { frame: this.reducedMotion ? STILL : track.at(u), ...(track.body ? { body: track.body } : {}) };
+  }
+
+  /** The pose at time `t` (same clock as the calls). Pure: the same schedule and `t` give the same pose. */
+  pose(t: number = this.clock()): Pose {
+    const face = this.faceAt(t);
+    const reaction = this.reactionAt(t);
+    const bodyEvent = latest(this.bodies, t);
+    const body = reaction.body ?? bodyEvent?.body ?? 'idle';
+    const cycle = bodyEvent ? ((t - bodyEvent.t) / bodyEvent.cycleMs) % 1 : 0;
+    const breath = this.idle && !this.reducedMotion ? breathAt(this.seed, t) : { bob: 0, sway: 0 };
+    const status = latest(this.statuses, t)?.status ?? null;
+    return {
+      face,
+      look: this.gazeAt(t),
+      blink: blinkAt(this.seed, t),
+      talk: this.talkAt(t),
+      body,
+      phase: reaction.body === 'cheer' ? (t / 467) % 1 : cycle,
+      status,
+      bob: { x: reaction.frame.bob.x, y: reaction.frame.bob.y + breath.bob },
+      tilt: reaction.frame.tilt + breath.sway,
+      squash: reaction.frame.squash,
+    };
+  }
+}
+
+/** A new animator for a look: `animator(look, { seed: userId })`. */
+export function animator(look: LookLike, opts: AnimatorOptions = {}): Animator {
+  return new Animator(look, opts);
+}

package/src/avatar/animator/reactions.ts

@@ -0,0 +1,44 @@
+/**
+ * One-shot reactions (§3.7): short keyframe tracks of head bob, tilt and
+ * squash layered on top of the face, with an optional expression and body
+ * pose while they play.
+ */
+import type { Expression } from '../face';
+import type { BodyPose, Point } from '../render/types';
+
+/** A reaction name. */
+export type Reaction = 'nod' | 'shake' | 'bounce' | 'cheer' | 'gasp' | 'flinch' | 'shrug' | 'sleep' | 'wave';
+
+/** What a reaction adds at a moment. */
+export interface ReactionFrame {
+  readonly bob: Point;
+  readonly tilt: number;
+  readonly squash: number;
+}
+
+/** A reaction's track. */
+export interface ReactionTrack {
+  readonly ms: number;
+  readonly expression?: Expression;
+  readonly body?: BodyPose;
+  readonly at: (u: number) => ReactionFrame;
+}
+
+const still: ReactionFrame = { bob: { x: 0, y: 0 }, tilt: 0, squash: 0 };
+const ease = (u: number): number => Math.sin(u * Math.PI);
+
+/** Every reaction's track; `u` runs 0 … 1 over `ms`. */
+export const REACTIONS: Readonly<Record<Reaction, ReactionTrack>> = {
+  nod: { ms: 700, at: (u) => ({ bob: { x: 0, y: Math.sin(u * Math.PI * 2) * 3 * (1 - u) }, tilt: 0, squash: 0 }) },
+  shake: { ms: 800, at: (u) => ({ bob: { x: Math.sin(u * Math.PI * 4) * 4 * (1 - u), y: 0 }, tilt: 0, squash: 0 }) },
+  bounce: { ms: 600, expression: 'happy', at: (u) => ({ bob: { x: 0, y: -ease(u) * 8 }, tilt: 0, squash: -ease(u) * 0.04 }) },
+  cheer: { ms: 1400, expression: 'laugh', body: 'cheer', at: (u) => ({ bob: { x: 0, y: -Math.abs(Math.sin(u * Math.PI * 3)) * 6 }, tilt: 0, squash: 0 }) },
+  gasp: { ms: 900, expression: 'surprised', at: (u) => ({ bob: { x: 0, y: -ease(Math.min(1, u * 2)) * 3 }, tilt: 0, squash: -ease(u) * 0.05 }) },
+  flinch: { ms: 600, expression: 'shocked', at: (u) => ({ bob: { x: -ease(u) * 5, y: ease(u) * 2 }, tilt: -ease(u) * 6, squash: ease(u) * 0.04 }) },
+  shrug: { ms: 900, expression: 'smug', at: (u) => ({ bob: { x: 0, y: -ease(u) * 3 }, tilt: Math.sin(u * Math.PI * 2) * 5, squash: 0 }) },
+  sleep: { ms: 3000, expression: 'sleepy', body: 'away', at: () => still },
+  wave: { ms: 1500, expression: 'happy', body: 'wave', at: (u) => ({ bob: { x: 0, y: 0 }, tilt: Math.sin(u * Math.PI * 4) * 3, squash: 0 }) },
+};
+
+/** No motion. */
+export const STILL = still;

package/src/avatar/animator/schedule.ts

@@ -0,0 +1,73 @@
+/**
+ * Seeded, stateless schedules: blinks, gaze wander, breathing and micro
+ * expressions are pure functions of (seed, t), so the same t always gives
+ * the same pose (snapshot tests, replays, many tabs agreeing).
+ */
+import { hashSeed, mulberry32 } from '@diffenderfer-games/hub-contract/avatar';
+
+/** A blink lasts this long (ms). */
+export const BLINK_MS = 150;
+const BLINK_BUCKET = 4000;
+
+/** A deterministic random in [0, 1) for (seed, channel, bucket). */
+function cell(seed: number, channel: number, bucket: number): () => number {
+  return mulberry32(hashSeed(`${String(seed)}:${String(channel)}:${String(bucket)}`));
+}
+
+/** One blink's closure at offset `dt` from its start: up then down. */
+function closure(dt: number): number {
+  if (dt < 0 || dt > BLINK_MS) {
+    return 0;
+  }
+  const half = BLINK_MS / 2;
+  return dt < half ? dt / half : 1 - (dt - half) / half;
+}
+
+/**
+ * Lid closure from blinking, 0 … 1: one blink per 4 s bucket at a seeded
+ * offset (so intervals fall between about 2 and 6 s), 10% of them doubled.
+ */
+export function blinkAt(seed: number, t: number): number {
+  const bucket = Math.floor(t / BLINK_BUCKET);
+  let out = 0;
+  for (const b of [bucket - 1, bucket]) {
+    const r = cell(seed, 1, b);
+    const start = b * BLINK_BUCKET + 1000 + r() * 2000;
+    const isDouble = r() < 0.1;
+    out = Math.max(out, closure(t - start), isDouble ? closure(t - start - BLINK_MS - 90) : 0);
+  }
+  return out;
+}
+
+/** An idle wandering gaze target: holds for 3–8 s, small amplitude. */
+export function wanderAt(seed: number, t: number): { readonly x: number; readonly y: number } {
+  const bucket = Math.floor(t / 5500);
+  const r = cell(seed, 2, bucket);
+  if (r() < 0.45) {
+    return { x: 0, y: 0 };
+  }
+  return { x: (r() * 2 - 1) * 0.6, y: (r() * 2 - 1) * 0.3 };
+}
+
+/** Breathing bob (rig units) and a slow sway (degrees). */
+export function breathAt(seed: number, t: number): { readonly bob: number; readonly sway: number } {
+  const phase = (seed % 1000) / 1000;
+  return {
+    bob: Math.sin((t / 2400 + phase) * Math.PI * 2) * 0.6,
+    sway: Math.sin((t / 5200 + phase) * Math.PI * 2) * 1.2,
+  };
+}
+
+/** An occasional micro smile while idle: its weight at t (0 most of the time). */
+export function microSmileAt(seed: number, t: number): number {
+  const bucket = Math.floor(t / 11000);
+  const r = cell(seed, 3, bucket);
+  if (r() < 0.6) {
+    return 0;
+  }
+  const dt = t - (bucket * 11000 + 2000 + r() * 6000);
+  if (dt < 0 || dt > 900) {
+    return 0;
+  }
+  return Math.sin((dt / 900) * Math.PI) * 0.35;
+}

package/src/avatar/art/beard.ts

@@ -0,0 +1,49 @@
+/** Facial hair (catalog `beard.*`): `beard` sits below the mouth, `moustache` above it. */
+import { blob, type Pt } from '../geom';
+import type { FacialHairPart } from './shape';
+
+const jaw: Pt[] = [[-45, 0], [-44, 22], [-30, 46], [0, 56], [30, 46], [44, 22], [45, 0]];
+
+/** Every facial-hair part by name. */
+export const BEARD_ART: Readonly<Record<string, FacialHairPart>> = {
+  none: {},
+  stubble: {
+    beard: [{ d: blob([[-45, -4], [-44, 22], [-30, 46], [0, 54], [30, 46], [44, 22], [45, -4], [36, 6], [22, 18], [10, 19], [0, 20], [-10, 19], [-22, 18], [-36, 6]]), fill: 'stubble', clip: 'head', stroke: 'none', opacity: 0.5 }],
+  },
+  moustache: {
+    moustache: [{ d: blob([[0, 21.5], [6, 19.5], [13, 21], [16, 26, 'c'], [9, 24.5], [0, 24.5], [-9, 24.5], [-16, 26, 'c'], [-13, 21], [-6, 19.5]]), fill: 'beard' }],
+  },
+  handlebar: {
+    moustache: [{ d: blob([[0, 21], [8, 19.5], [16, 22], [22, 22, 'c'], [24, 17], [26, 20], [22, 26], [14, 25], [0, 24.5], [-14, 25], [-22, 26], [-26, 20], [-24, 17], [-22, 22, 'c'], [-16, 22], [-8, 19.5]]), fill: 'beard' }],
+  },
+  goatee: {
+    beard: [{ d: blob([[-8, 34], [0, 33], [8, 34], [7, 43], [0, 50], [-7, 43]]), fill: 'beard' }],
+    moustache: [{ d: blob([[0, 21.5], [7, 20], [12, 21.5], [13, 25, 'c'], [6, 24.5], [0, 24.5], [-6, 24.5], [-13, 25, 'c'], [-12, 21.5], [-7, 20]]), fill: 'beard' }],
+  },
+  chinstrap: {
+    beard: [{ d: blob([...jaw, [40, 2], [38, 22], [26, 40], [0, 47], [-26, 40], [-38, 22], [-40, 2]]), fill: 'beard' }],
+  },
+  short: {
+    // Trimmed close along the jaw: thin sideburns, a little past the chin, the cheeks left clear.
+    beard: [{
+      d: blob([[-47, -1], [-45.5, 16], [-37.5, 34], [-21, 48.5], [0, 53.5], [21, 48.5], [37.5, 34], [45.5, 16], [47, -1], [42, 3], [39.5, 16], [32, 30], [18, 38.5], [0, 41], [-18, 38.5], [-32, 30], [-39.5, 16], [-42, 3]]),
+      fill: 'beard',
+    }, { d: blob([[-4, 47.5], [0, 49], [4, 47.5]], false), fill: 'none', line: true, stroke: 'beardShade', sw: 2 }],
+    moustache: [{ d: blob([[0, 21.5], [6.5, 20], [13, 21.5], [15.5, 25.5, 'c'], [8, 24.3], [0, 24.3], [-8, 24.3], [-15.5, 25.5, 'c'], [-13, 21.5], [-6.5, 20]]), fill: 'beard' }],
+  },
+  full: {
+    beard: [{
+      d: blob([[-46, -4], [-46, 22], [-34, 48], [-14, 60], [0, 62], [14, 60], [34, 48], [46, 22], [46, -4], [38, 4], [30, 14], [18, 20], [0, 20], [-18, 20], [-30, 14], [-38, 4]]),
+      fill: 'beard',
+    }, { d: blob([[-6, 49], [0, 52], [6, 49]], false), fill: 'none', line: true, stroke: 'beardShade', sw: 2 }],
+    moustache: [{ d: blob([[0, 21], [8, 19.5], [16, 22], [18, 27, 'c'], [10, 25], [0, 25], [-10, 25], [-18, 27, 'c'], [-16, 22], [-8, 19.5]]), fill: 'beard' }],
+  },
+  long: {
+    beard: [{
+      d: blob([[-46, -4], [-46, 24], [-36, 54], [-20, 74], [0, 82, 'c'], [20, 74], [36, 54], [46, 24], [46, -4], [38, 4], [30, 14], [18, 20], [0, 20], [-18, 20], [-30, 14], [-38, 4]]),
+      fill: 'beard',
+    }, { d: blob([[-10, 52], [-6, 66], [0, 76]], false), fill: 'none', line: true, stroke: 'beardShade', sw: 2 },
+    { d: blob([[10, 52], [6, 66]], false), fill: 'none', line: true, stroke: 'beardShade', sw: 2 }],
+    moustache: [{ d: blob([[0, 21], [8, 19.5], [16, 22], [18, 27, 'c'], [10, 25], [0, 25], [-10, 25], [-18, 27, 'c'], [-16, 22], [-8, 19.5]]), fill: 'beard' }],
+  },
+};