@doan-labs/peek 0.1.0

package/src/identity.ts

@@ -0,0 +1,147 @@
+/*
+ * A name in, an identity out. Every axis hashes on its own seed, so changing
+ * one list never moves another axis:
+ *
+ *   seed(axis) = fnv1a(`peek@${version}:${axis}:${tidy(name)}`)
+ *
+ * The persona (continuous proportions and habits) is transcribed from
+ * faceFor() in the v1.2 page: same ranges, same draw order.
+ */
+
+import {
+  type Axis,
+  type Brows,
+  type Cheeks,
+  COLORS,
+  type Color,
+  type Eyes,
+  FACES,
+  type Face,
+  LATEST,
+  type Mouth,
+  PARTS,
+  type Trait,
+  VERSIONS,
+} from './tables'
+
+export const STYLE = 'peek'
+
+export const tidy = (s: string) =>
+  s.normalize('NFC').trim().replace(/\s+/g, ' ').toLowerCase()
+
+/** FNV-1a over the UTF-8 bytes. */
+export function fnv1a(str: string) {
+  let h = 0x811c9dc5
+  for (const b of new TextEncoder().encode(str)) {
+    h ^= b
+    h = Math.imul(h, 0x01000193) >>> 0
+  }
+  return h >>> 0
+}
+
+export function mulberry32(a: number) {
+  return () => {
+    a = (a + 0x6d2b79f5) | 0
+    let t = Math.imul(a ^ (a >>> 15), 1 | a)
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+}
+
+export type Persona = {
+  /** Eye gap offset, in frame units, per side. */
+  spread: number
+  /** Blink interval factor (animation only). */
+  blink: number
+  add: {
+    browY: number
+    browTilt: number
+    browArch: number
+    rot: number
+    hair: number
+    gx: number
+    my: number
+  }
+  mul: { eyeS: number; pupil: number; browW: number; mw: number }
+}
+
+/** The axes a caller may override. Everything a face is. */
+export type Axes = {
+  face: Face
+  color: Color
+  eyes: Eyes
+  brows: Brows
+  mouth: Mouth
+  cheeks: Cheeks
+  trait: Trait
+}
+
+export type Identity = Axes & {
+  /** The tidied name. */
+  key: string
+  /** fnv1a of the tidied name, version-free: a fingerprint for display. */
+  hash: number
+  version: number
+  persona: Persona
+}
+
+/** What each axis picks from, in list order. Append-only. */
+export const LISTS: { readonly [A in Axis]: readonly Axes[A][] } = {
+  face: Object.keys(FACES) as Face[],
+  color: Object.keys(COLORS) as Color[],
+  ...PARTS,
+}
+/** The axes in readout order. */
+export const AXES = Object.keys(LISTS) as Axis[]
+
+export function seed(name: string, axis: string, version = LATEST) {
+  return fnv1a(`${STYLE}@${version}:${axis}:${tidy(name)}`)
+}
+
+export function identify(
+  name: string,
+  { version = LATEST }: { version?: number } = {},
+): Identity {
+  const lengths = VERSIONS[version]
+  if (!lengths) throw new Error(`peek@${version} does not exist`)
+  const pick = <A extends Axis>(axis: A) =>
+    LISTS[axis][seed(name, axis, version) % lengths[axis]] as Identity[A]
+
+  const rnd = mulberry32(seed(name, 'persona', version))
+  const r = (a: number, b: number) =>
+    Math.round((a + rnd() * (b - a)) * 100) / 100
+  // object literal order is the draw order: never reorder these lines
+  const persona: Persona = {
+    spread: r(-7, 7),
+    blink: r(0.75, 1.4),
+    add: {
+      browY: r(-4, 4),
+      browTilt: r(-5, 5),
+      browArch: r(-0.2, 0.3),
+      rot: r(-3, 3),
+      hair: r(-0.2, 0.35),
+      gx: r(-0.12, 0.12),
+      my: r(-2, 3),
+    },
+    mul: {
+      eyeS: r(0.92, 1.08),
+      pupil: r(0.9, 1.12),
+      browW: r(0.85, 1.2),
+      mw: r(0.85, 1.18),
+    },
+  }
+  const key = tidy(name)
+  return {
+    key,
+    hash: fnv1a(key),
+    version,
+    face: pick('face'),
+    color: pick('color'),
+    eyes: pick('eyes'),
+    brows: pick('brows'),
+    mouth: pick('mouth'),
+    cheeks: pick('cheeks'),
+    trait: pick('trait'),
+    persona,
+  }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+export type { Frame, Gaze } from './draw'
+export type { Axes, Identity, Persona } from './identity'
+export { AXES, identify, LISTS, tidy } from './identity'
+export type { PeekProps } from './peek'
+export { Peek } from './peek'
+export type { PeekOptions } from './svg'
+export { toSvg } from './svg'
+export type {
+  Axis,
+  Brows,
+  Channel,
+  Cheeks,
+  Color,
+  Expression,
+  Eyes,
+  Face,
+  Mouth,
+  Trait,
+} from './tables'
+export {
+  COLORS,
+  EXPRESSIONS,
+  FACES,
+  GROUPS,
+  LATEST,
+  PARTS,
+  VERSIONS,
+} from './tables'

package/src/peek.tsx

@@ -0,0 +1,98 @@
+/*
+ * <Peek name="Ada" />: the same tree as toSvg, rendered through React. ids
+ * come from useId, so the server and the client agree.
+ *
+ * A name decides identity unless the caller overrides an axis: pass `face`,
+ * `color`, `eyes`, `brows`, `mouth`, `cheeks` or `trait` and that axis wins
+ * over the hash while every other axis stays as the name made it.
+ *
+ * With `animate`, the first paint (server and hydration) is still the static
+ * pose of `expression`; after mount the shared loop takes over and writes
+ * straight to the DOM. The tree React renders stays in the pose the
+ * component mounted with, so a change of expression or gaze never reaches
+ * React's diff and React never fights the loop.
+ */
+
+import {
+  type CSSProperties,
+  createElement,
+  type ReactElement,
+  type Ref,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+} from 'react'
+import { Live } from './animate'
+import { draw, type Gaze, type Node, restPose } from './draw'
+import { type PeekOptions, settle } from './svg'
+
+export type PeekProps = Omit<PeekOptions, 'gaze' | 'id'> & {
+  name: string
+  /** x and y in -1..1, or 'pointer' to follow the pointer (animate only). */
+  gaze?: Gaze | 'pointer'
+  /** Bring it to life after mount. Off under prefers-reduced-motion. */
+  animate?: boolean
+  className?: string
+  style?: CSSProperties
+}
+
+const camel = (k: string) =>
+  k.startsWith('aria-') ? k : k.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
+
+function toReact(
+  node: Node,
+  root?: { ref: Ref<SVGSVGElement>; className?: string; style?: CSSProperties },
+): ReactElement {
+  const props: Record<string, unknown> = { key: node.key, ...root }
+  for (const k in node.attrs) props[camel(k)] = node.attrs[k]
+  return createElement(node.tag, props, ...node.children.map((c) => toReact(c)))
+}
+
+export function Peek({
+  name,
+  gaze,
+  animate = false,
+  className,
+  style,
+  ...rest
+}: PeekProps) {
+  const id = `peek${useId().replace(/[^\w-]/g, '')}`
+  const fixed = Array.isArray(gaze) ? (gaze as Gaze) : undefined
+  const { who, pose, opts } = settle(
+    name,
+    { ...rest, gaze: fixed, id },
+    animate,
+  )
+  const svg = useRef<SVGSVGElement>(null)
+  const live = useRef<Live | null>(null)
+  const expression = rest.expression ?? 'normal'
+  const [first] = useState(() => ({ expression, gaze: fixed }))
+
+  // live: the tree only changes when what the face is changes
+  const sig = JSON.stringify([who, opts])
+  const tree = draw(
+    who,
+    animate ? restPose(who, first.expression, first.gaze) : pose,
+    opts,
+  )
+
+  const gazeKey = String(gaze ?? '')
+  useEffect(() => {
+    if (!animate || !svg.current) return
+    const l = new Live(svg.current, tree, who, opts, expression, gaze)
+    live.current = l
+    return () => {
+      l.destroy()
+      live.current = null
+    }
+  }, [animate, sig])
+  useEffect(() => {
+    live.current?.setExpression(expression)
+  }, [expression])
+  useEffect(() => {
+    live.current?.setGaze(gaze)
+  }, [gazeKey])
+
+  return toReact(tree, { ref: svg, className, style })
+}

package/src/svg.ts

@@ -0,0 +1,94 @@
+/*
+ * toSvg: a name in, a standalone SVG string out. Same input, same bytes, on
+ * any machine. Shares its defaults with <Peek> through settle().
+ */
+
+import {
+  type DrawOptions,
+  draw,
+  type Frame,
+  type Gaze,
+  type Node,
+  type Pose,
+  restPose,
+} from './draw'
+import { type Axes, fnv1a, type Identity, identify } from './identity'
+import type { Expression } from './tables'
+
+export type PeekOptions = Partial<Axes> & {
+  /** px. Drives the stroke ramp (thicker below 96) and the riso print. */
+  size?: number
+  expression?: Expression
+  /** Where the eyes look, x and y in -1..1. */
+  gaze?: Gaze
+  frame?: Frame
+  /** false clips the frame to a circle. Default true. */
+  square?: boolean
+  /** Accessible name, default the name; false marks it decorative. */
+  title?: string | false
+  /** Riso plates and grain, visible from 120px up. Default off. */
+  riso?: boolean
+  /** Pin a style version. Default the latest. */
+  version?: number
+  /** Prefix for ids inside the SVG. Default derived from everything drawn,
+   * so two different avatars inlined in one page never share defs. */
+  id?: string
+}
+
+/**
+ * A name decides identity unless the caller overrides an axis: an explicit
+ * face, color or part wins over the hash, and every other axis stays put.
+ */
+export function settle(
+  name: string,
+  o: PeekOptions,
+  live = false,
+): { who: Identity; pose: Pose; opts: DrawOptions } {
+  const base = identify(name, { version: o.version })
+  const who: Identity = {
+    ...base,
+    face: o.face ?? base.face,
+    color: o.color ?? base.color,
+    eyes: o.eyes ?? base.eyes,
+    brows: o.brows ?? base.brows,
+    mouth: o.mouth ?? base.mouth,
+    cheeks: o.cheeks ?? base.cheeks,
+    trait: o.trait ?? base.trait,
+  }
+  const pose = restPose(who, o.expression ?? 'normal', o.gaze)
+  const look = {
+    size: o.size ?? 64,
+    frame: o.frame ?? 'ink',
+    square: o.square ?? true,
+    riso: o.riso ?? false,
+    live,
+  }
+  const id =
+    o.id ?? `peek-${fnv1a(JSON.stringify([who, pose, look])).toString(36)}`
+  return { who, pose, opts: { ...look, id, title: o.title ?? name } }
+}
+
+// characters XML 1.0 cannot hold at all: C0 controls and lone surrogates
+const ILLEGAL =
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: matching them is the point
+  /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g
+
+const esc = (s: string) =>
+  s
+    .replace(ILLEGAL, '\uFFFD')
+    .replace(
+      /[&<>"]/g,
+      (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]!,
+    )
+
+export function serialize(node: Node): string {
+  let a = ''
+  for (const k in node.attrs) a += ` ${k}="${esc(node.attrs[k]!)}"`
+  if (!node.children.length) return `<${node.tag}${a}/>`
+  return `<${node.tag}${a}>${node.children.map(serialize).join('')}</${node.tag}>`
+}
+
+export function toSvg(name: string, props: PeekOptions = {}): string {
+  const { who, pose, opts } = settle(name, props)
+  return serialize(draw(who, pose, opts))
+}