@doan-labs/peek 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# Peek
+
+A name in, a face out. Deterministic SVG avatars by Doan Labs.
+
+```sh
+npm install @doan-labs/peek
+```
+
+## React 19
+
+Install React 19 or newer in your app, then render a face:
+
+```tsx
+import { Peek } from '@doan-labs/peek'
+
+<Peek name='Linh' size={96} expression='happy' />
+```
+
+Use `animate` for blinking and expression transitions, and
+`gaze='pointer'` to follow the pointer. Animation respects reduced motion.
+
+## Plain SVG, without React
+
+The SVG and identity entry points have no runtime dependencies:
+
+```js
+import { toSvg } from '@doan-labs/peek/svg'
+import { identify } from '@doan-labs/peek/identity'
+
+const svg = toSvg('Linh', { size: 96, expression: 'happy' })
+const identity = identify('Linh')
+```
+
+The root entry point also exports `toSvg` and `identify` for React apps.
+The same normalized name and options produce the same SVG every time.
+
+See the [documentation](https://peek.doan-labs.com/docs) for options,
+expressions, identity axes and versioned styles.

package/dist/animate.d.ts

@@ -0,0 +1,58 @@
+import { type Drawable, type DrawOptions, type Gaze, type Node } from './draw.js';
+import { type Expression } from './tables.js';
+/**
+ * One live avatar bound to an SVG that already shows `tree`. Starts settled
+ * in `expression`, the same pose the server painted.
+ */
+export declare class Live {
+    private svg;
+    private who;
+    private opts;
+    visible: boolean;
+    private state;
+    private reduced;
+    private nodes;
+    private prev;
+    private io;
+    private clock;
+    private enteredAt;
+    private val;
+    private vel;
+    private base;
+    private spr;
+    private out;
+    private queue;
+    private bumps;
+    private blinkAt;
+    private blinkT;
+    private blinkDur;
+    private blinkV;
+    private doubleBlink;
+    private saccAt;
+    private sacc;
+    private nodAt;
+    private lookThing;
+    private lag;
+    private fixed;
+    private watch;
+    private rect;
+    constructor(svg: SVGSVGElement, tree: Node, who: Drawable, opts: DrawOptions, expression: Expression, gaze?: Gaze | 'pointer');
+    destroy(): void;
+    /** Reduced motion turned on or off while the page is open. */
+    setReduced(reduced: boolean): void;
+    /** Read before any face writes this frame; see tick(). */
+    measure(): void;
+    /**
+     * Pairs every node in the tree with the element React rendered for it,
+     * and remembers what that element shows now, which is not always `node`.
+     */
+    private bind;
+    private write;
+    setGaze(gaze?: Gaze | 'pointer'): void;
+    setExpression(name: Expression): void;
+    /** Straight to the rest pose of the current state, no motion. */
+    private snap;
+    private bump;
+    step(dt: number): void;
+    private paint;
+}

package/dist/draw.d.ts

@@ -0,0 +1,69 @@
+import type { Axes, Persona } from './identity.js';
+import { type Channels, type Expression, type FaceGeom } from './tables.js';
+export type Node = {
+    tag: string;
+    key: string;
+    attrs: Record<string, string>;
+    children: Node[];
+};
+export type Frame = 'ink' | 'bone' | 'paper' | 'none';
+export type Gaze = readonly [x: number, y: number];
+export type Pose = Channels & {
+    /** 0..1, the blink closing both lids. */
+    blink: number;
+    /** The trait's lag behind the body, frame units, clamped to 16. */
+    lag: number;
+    /** The ring thickens when angry: the one place a state is read by name. */
+    expression: Expression;
+};
+export type DrawOptions = {
+    /** Prefix for every id in the tree. Unique per avatar on a page. */
+    id: string;
+    /** Rendered size in px: drives the stroke ramp and the riso print. */
+    size: number;
+    frame: Frame;
+    /** false clips the frame to a circle. */
+    square: boolean;
+    /** Riso plates, misregistration and grain. Fades out below 120px. */
+    riso: boolean;
+    /** The accessible name; false marks the avatar decorative. */
+    title: string | false;
+    /** Keep invisible nodes so an animator can write into them. */
+    live?: boolean;
+};
+export type Drawable = Axes & {
+    persona: Persona;
+};
+export declare const VB: readonly [-30, -30, 400, 400];
+export declare const clamp: (v: number, a: number, b: number) => number;
+export declare const smooth: (a: number, b: number, v: number) => number;
+/** Where a face rests: the body offset, the eye line, one altitude unit. */
+export declare function frameOf(face: FaceGeom): {
+    baseY: number;
+    eyeY: number;
+    R: number;
+};
+/** The eyes' aim at the thing in the corner, from wherever they are. */
+export declare function thingGaze(face: FaceGeom, x: number, alt: number): Gaze;
+/**
+ * The pose an expression settles to. A curious face ends up looking at the
+ * thing in the corner; an explicit gaze wins over both.
+ */
+export declare function restPose(who: Pick<Axes, 'face'>, expression: Expression, gaze?: Gaze): Pose;
+/**
+ * A point on the crown outline grown by `d`, reached by walking `u` along it
+ * from the top (where the outward normal points straight up); u > 0 walks
+ * right. Returns the point and the normal's bearing in degrees.
+ */
+export declare function seat(crown: FaceGeom['crown'], d: number, u: number): {
+    x: number;
+    y: number;
+    a: number;
+};
+/** Signed distance from a point to the crown outline, negative inside. */
+export declare function depth(crown: FaceGeom['crown'], x: number, y: number): number;
+export declare function ringWalk(sh: FaceGeom): {
+    rest: number;
+    min: number;
+};
+export declare function draw(who: Drawable, pose: Pose, o: DrawOptions): Node;

package/dist/identity.d.ts

@@ -0,0 +1,55 @@
+import { type Axis, type Brows, type Cheeks, type Color, type Eyes, type Face, type Mouth, type Trait } from './tables.js';
+export declare const STYLE = "peek";
+export declare const tidy: (s: string) => string;
+/** FNV-1a over the UTF-8 bytes. */
+export declare function fnv1a(str: string): number;
+export declare function mulberry32(a: number): () => number;
+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 declare const LISTS: {
+    readonly [A in Axis]: readonly Axes[A][];
+};
+/** The axes in readout order. */
+export declare const AXES: Axis[];
+export declare function seed(name: string, axis: string, version?: number): number;
+export declare function identify(name: string, { version }?: {
+    version?: number;
+}): Identity;

package/dist/identity.js

@@ -0,0 +1,398 @@
+// src/tables.ts
+var FACES = {
+  diamond: {
+    body: { d: "M170 20L320 170L170 320L20 170Z" },
+    bottom: 320,
+    sink: 30,
+    eyes: [
+      [132.5, 155],
+      [207.5, 155]
+    ],
+    rx: 20,
+    ry: 27.5,
+    pr: 10,
+    brow: { y: 102.5, hw: 18.75, arch: 15, w: 5.62 },
+    cheeks: [
+      [117.5, 200],
+      [222.5, 200]
+    ],
+    crx: 11.25,
+    cry: 5.62,
+    mouth: { x: 170, y: 218.75, w: 15, d: 16.25, sw: 4.38 },
+    crown: {
+      poly: [
+        [170, 20],
+        [320, 170],
+        [170, 320],
+        [20, 170]
+      ],
+      r: 0
+    }
+  },
+  semicircle: {
+    body: { d: "M0 255A170 170 0 0 1 340 255Z" },
+    bottom: 255,
+    sink: 0,
+    eyes: [
+      [102.5, 175],
+      [237.5, 175]
+    ],
+    rx: 30,
+    ry: 25,
+    pr: 11.25,
+    brow: { y: 127.5, hw: 25, arch: 15, w: 5.62 },
+    cheeks: [
+      [55, 212.5],
+      [285, 212.5]
+    ],
+    crx: 11.25,
+    cry: 5.62,
+    mouth: { x: 170, y: 221.25, w: 16.25, d: 16.25, sw: 4.38 },
+    crown: { poly: [[170, 255]], r: 170 }
+  },
+  circle: {
+    body: { circle: [170, 170, 150] },
+    bottom: 320,
+    sink: 20,
+    eyes: [
+      [112.8, 162.2],
+      [227.2, 162.2]
+    ],
+    rx: 29.9,
+    ry: 29.9,
+    pr: 13,
+    brow: { y: 110.2, hw: 23.4, arch: 15.6, w: 5.85 },
+    cheeks: [
+      [84.2, 203.8],
+      [255.8, 203.8]
+    ],
+    crx: 11.7,
+    cry: 5.85,
+    mouth: { x: 170, y: 223.3, w: 16.9, d: 16.9, sw: 4.55 },
+    crown: { poly: [[170, 170]], r: 150 }
+  },
+  triangle: {
+    body: { d: "M170 40.8L312.8 299.2L27.2 299.2Z", stroke: 27.2 },
+    bottom: 312.8,
+    sink: 0,
+    eyes: [
+      [132.6, 210.8],
+      [207.4, 210.8]
+    ],
+    rx: 20.4,
+    ry: 27.2,
+    pr: 10,
+    brow: { y: 166.6, hw: 18.7, arch: 15.3, w: 5.62 },
+    cheeks: [
+      [98.6, 238],
+      [241.4, 238]
+    ],
+    crx: 11.5,
+    cry: 5.75,
+    mouth: { x: 170, y: 254, w: 17, d: 16.25, sw: 4.38 },
+    crown: {
+      poly: [
+        [170, 40.8],
+        [312.8, 299.2],
+        [27.2, 299.2]
+      ],
+      r: 13.6
+    }
+  }
+};
+var COLORS = {
+  lavender: { body: "#D8CDF0", deep: "#BDAEE6" },
+  fog: { body: "#C8D6E8", deep: "#A8BCDC" },
+  clay: { body: "#F1CDBF", deep: "#E2A893" },
+  mint: { body: "#CFE7D6", deep: "#A5CDB1" },
+  butter: { body: "#ECE2B9", deep: "#D9C284" },
+  rose: { body: "#EFCAD7", deep: "#DFA4BA" },
+  aqua: { body: "#BDE1E5", deep: "#8FC7D1" }
+};
+var PARTS = {
+  eyes: ["oval", "bead", "ring"],
+  brows: ["arch", "bar", "wedge", "dash"],
+  mouth: ["poly", "round", "line", "box"],
+  cheeks: ["oval", "dots", "lines"],
+  trait: ["square", "fin", "ring", "dot", "peak"]
+};
+var VERSIONS = {
+  1: { face: 4, color: 7, eyes: 3, brows: 4, mouth: 4, cheeks: 3, trait: 5 }
+};
+var LATEST = 1;
+var BASE = {
+  alt: 0,
+  rot: 0,
+  x: 0,
+  sx: 1,
+  sy: 1,
+  lid: 0.1,
+  lower: 0,
+  lidTilt: 0,
+  eyeS: 1,
+  lidAsym: 0,
+  pupil: 1,
+  gx: 0,
+  gy: 0,
+  shine: 0.7,
+  browY: 0,
+  browTilt: 0,
+  browArch: 0.4,
+  browW: 1,
+  browAsym: 0,
+  mw: 0.72,
+  mt: 0,
+  mb: 0.5,
+  mx: 0,
+  my: 0,
+  mk: 0,
+  blush: 0,
+  hair: 0,
+  dim: 0,
+  thing: 0
+};
+var S = (o) => ({ ...BASE, ...o });
+var EXPRESSIONS = {
+  normal: S({}),
+  happy: S({
+    lid: 0,
+    lower: 0.42,
+    shine: 1,
+    gy: -0.05,
+    browY: -5,
+    browArch: 1,
+    mw: 1,
+    mb: 1,
+    blush: 1,
+    hair: 0.45,
+    alt: 0.05
+  }),
+  sad: S({
+    lid: 0.42,
+    lidTilt: 16,
+    pupil: 0.95,
+    gy: 0.8,
+    shine: 0,
+    browY: 3,
+    browTilt: 14,
+    browArch: 0,
+    mw: 0.8,
+    mt: -0.55,
+    mb: -0.55,
+    my: 6,
+    alt: -0.16,
+    sy: 0.985,
+    hair: -0.75
+  }),
+  angry: S({
+    lid: 0.34,
+    lidTilt: -22,
+    lower: 0.12,
+    pupil: 0.82,
+    gy: 0.1,
+    shine: 0,
+    browY: 5,
+    browTilt: -21,
+    browArch: 0,
+    browW: 1.3,
+    mw: 0.8,
+    mt: -0.08,
+    mb: -0.08,
+    my: 3,
+    sx: 1.02,
+    sy: 0.98,
+    hair: 0.25
+  }),
+  sleepy: S({
+    lid: 1,
+    lidTilt: 4,
+    pupil: 0.9,
+    gy: 0.5,
+    shine: 0,
+    browY: 6,
+    browTilt: 3,
+    browArch: 0.15,
+    browW: 0.9,
+    mw: 0.35,
+    mt: -0.3,
+    mb: 0.3,
+    my: 2,
+    alt: -1.12,
+    rot: -3,
+    hair: -1
+  }),
+  curious: S({
+    lid: 0,
+    eyeS: 1.06,
+    pupil: 1.05,
+    shine: 1,
+    browY: -3,
+    browAsym: 9,
+    browArch: 0.8,
+    mw: 0.38,
+    mt: -0.36,
+    mb: 0.36,
+    rot: 6,
+    alt: -0.32,
+    hair: 0.3,
+    thing: 1
+  }),
+  surprised: S({
+    lid: 0,
+    eyeS: 1.2,
+    pupil: 0.66,
+    shine: 0.8,
+    browY: -13,
+    browArch: 1,
+    mw: 0.55,
+    mt: -0.62,
+    mb: 0.62,
+    alt: 0.36,
+    hair: 1
+  }),
+  excited: S({
+    lid: 0,
+    lower: 0.5,
+    eyeS: 1.08,
+    pupil: 1.08,
+    shine: 1,
+    browY: -9,
+    browArch: 1,
+    mw: 1.15,
+    mb: 1.3,
+    blush: 1,
+    hair: 1,
+    alt: 0.12
+  }),
+  confused: S({
+    lid: 0.22,
+    lidAsym: 0.28,
+    lidTilt: -4,
+    pupil: 0.92,
+    gx: -0.35,
+    gy: -0.45,
+    shine: 0.3,
+    browY: -2,
+    browAsym: 11,
+    browTilt: -5,
+    browArch: 0.3,
+    mw: 0.6,
+    mt: -0.1,
+    mb: 0.12,
+    mx: 5,
+    mk: 13,
+    rot: -7,
+    alt: -0.05,
+    hair: 0.1
+  }),
+  bored: S({
+    lid: 0.5,
+    pupil: 0.9,
+    gx: -0.55,
+    gy: 0.25,
+    shine: 0,
+    browY: 3,
+    browArch: 0.1,
+    mw: 0.55,
+    mt: 0,
+    mb: 0.04,
+    mx: -5,
+    alt: -0.34,
+    hair: -0.45,
+    dim: 1
+  }),
+  attentive: S({
+    lid: 0,
+    eyeS: 1.1,
+    pupil: 0.8,
+    gy: -0.1,
+    shine: 1,
+    browY: -7,
+    browArch: 0.7,
+    mw: 0.55,
+    mb: 0.4,
+    alt: 0.15,
+    sy: 1.03,
+    hair: 0.65
+  })
+};
+
+// src/identity.ts
+var STYLE = "peek";
+var tidy = (s) => s.normalize("NFC").trim().replace(/\s+/g, " ").toLowerCase();
+function fnv1a(str) {
+  let h = 2166136261;
+  for (const b of new TextEncoder().encode(str)) {
+    h ^= b;
+    h = Math.imul(h, 16777619) >>> 0;
+  }
+  return h >>> 0;
+}
+function mulberry32(a) {
+  return () => {
+    a = a + 1831565813 | 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;
+  };
+}
+var LISTS = {
+  face: Object.keys(FACES),
+  color: Object.keys(COLORS),
+  ...PARTS
+};
+var AXES = Object.keys(LISTS);
+function seed(name, axis, version = LATEST) {
+  return fnv1a(`${STYLE}@${version}:${axis}:${tidy(name)}`);
+}
+function identify(name, { version = LATEST } = {}) {
+  const lengths = VERSIONS[version];
+  if (!lengths)
+    throw new Error(`peek@${version} does not exist`);
+  const pick = (axis) => LISTS[axis][seed(name, axis, version) % lengths[axis]];
+  const rnd = mulberry32(seed(name, "persona", version));
+  const r = (a, b) => Math.round((a + rnd() * (b - a)) * 100) / 100;
+  const 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
+  };
+}
+export {
+  AXES,
+  LISTS,
+  STYLE,
+  fnv1a,
+  identify,
+  mulberry32,
+  seed,
+  tidy
+};

package/dist/index.d.ts

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