@doan-labs/peek 1.0.0 → 2.0.0

package/src/identity.ts

@@ -9,16 +9,20 @@
  */
 
 import {
+  ACCESSORIES,
   type Axis,
   type Brows,
   type Cheeks,
   COLORS,
   type Color,
   type Eyes,
+  type Eyewear,
   FACES,
   type Face,
+  type Headwear,
   LATEST,
   type Mouth,
+  type Neckwear,
   PARTS,
   type Trait,
   VERSIONS,
@@ -74,6 +78,9 @@ export type Axes = {
   mouth: Mouth
   cheeks: Cheeks
   trait: Trait
+  eyewear: Eyewear
+  headwear: Headwear
+  neckwear: Neckwear
 }
 
 export type Identity = Axes & {
@@ -90,6 +97,7 @@ export const LISTS: { readonly [A in Axis]: readonly Axes[A][] } = {
   face: Object.keys(FACES) as Face[],
   color: Object.keys(COLORS) as Color[],
   ...PARTS,
+  ...ACCESSORIES,
 }
 /** The axes in readout order. */
 export const AXES = Object.keys(LISTS) as Axis[]
@@ -142,6 +150,9 @@ export function identify(
     mouth: pick('mouth'),
     cheeks: pick('cheeks'),
     trait: pick('trait'),
+    eyewear: pick('eyewear'),
+    headwear: pick('headwear'),
+    neckwear: pick('neckwear'),
     persona,
   }
 }

package/src/index.ts

@@ -1,28 +1,3 @@
-export type { Frame, Gaze } from './draw'
-export type { Axes, Identity, Persona } from './identity'
-export { AXES, identify, LISTS, tidy } from './identity'
+export * from './core'
 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.svelte

@@ -0,0 +1,75 @@
+<!--
+  <Peek name="Ada" /> for Svelte 5: the same tree and the same rules as the
+  React component in peek.tsx. ids come from $props.id(), so the server and
+  the client agree. The inside of the svg is the exact markup toSvg writes.
+
+  With `animate`, the markup stays in the pose the component mounted with and
+  the shared loop writes every frame straight to the DOM, so a change of
+  expression or gaze never reaches Svelte.
+-->
+<script lang="ts">
+import { untrack } from 'svelte'
+import {
+  draw,
+  Live,
+  type PeekProps,
+  restPose,
+  serialize,
+  settle,
+} from './svelte-peek'
+
+let {
+  name,
+  gaze,
+  animate = false,
+  class: className,
+  style,
+  ...rest
+}: PeekProps = $props()
+const uid = $props.id()
+const id = `peek${uid.replace(/[^\w-]/g, '')}`
+const fixedOf = (g: PeekProps['gaze']) =>
+  Array.isArray(g) ? (g as readonly [number, number]) : undefined
+const first = untrack(() => ({
+  expression: rest.expression ?? 'normal',
+  gaze: fixedOf(gaze),
+}))
+
+const s = $derived(settle(name, { ...rest, gaze: fixedOf(gaze), id }, animate))
+const tree = $derived(
+  draw(
+    s.who,
+    animate ? restPose(s.who, first.expression, first.gaze) : s.pose,
+    s.opts,
+  ),
+)
+const inner = $derived(tree.children.map(serialize).join(''))
+const expression = $derived(rest.expression ?? 'normal')
+// live: the face only restarts when what the face is changes
+const sig = $derived(JSON.stringify([s.who, s.opts]))
+const gazeKey = $derived(String(gaze ?? ''))
+
+let svg: SVGSVGElement | undefined
+let live: Live | null = null
+
+$effect(() => {
+  void sig
+  if (!animate || !svg) return
+  const l = untrack(() => new Live(svg!, tree, s.who, s.opts, expression, gaze))
+  live = l
+  return () => {
+    l.destroy()
+    live = null
+  }
+})
+$effect(() => {
+  live?.setExpression(expression)
+})
+$effect(() => {
+  void gazeKey
+  untrack(() => live?.setGaze(gaze))
+})
+</script>
+
+<!-- spread, so an unset class is no attribute rather than class="" -->
+<svg bind:this={svg} {...tree.attrs} {...{ class: className, style }}>{@html inner}</svg>

package/src/peek.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { Component } from 'svelte'
+import type { PeekProps } from './svelte-peek'
+
+declare const Peek: Component<PeekProps>
+export default Peek

package/src/peek.tsx

@@ -3,7 +3,7 @@
  * 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
+ * `color`, a part, or a wardrobe slot 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

package/src/svelte-peek.ts

@@ -0,0 +1,18 @@
+/* What peek.svelte imports. Built as its own file, since the component ships
+ * as source and the app's bundler compiles it. */
+import type { Gaze } from './draw'
+import type { PeekOptions } from './svg'
+
+export { Live } from './animate'
+export { draw, restPose } from './draw'
+export { serialize, 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
+  class?: string
+  style?: string
+}

package/src/svelte.ts

@@ -0,0 +1,3 @@
+export * from './core'
+export { default as Peek } from './peek.svelte'
+export type { PeekProps } from './svelte-peek'

package/src/svg.ts

@@ -13,7 +13,13 @@ import {
   restPose,
 } from './draw'
 import { type Axes, fnv1a, type Identity, identify } from './identity'
-import type { Expression } from './tables'
+import {
+  ACCESSORIES,
+  type AccessorySlot,
+  type Expression,
+  VARIANTS,
+  type Variant,
+} from './tables'
 
 export type PeekOptions = Partial<Axes> & {
   /** px. Drives the stroke ramp (thicker below 96) and the riso print. */
@@ -30,11 +36,19 @@ export type PeekOptions = Partial<Axes> & {
   riso?: boolean
   /** Pin a style version. Default the latest. */
   version?: number
+  /** How the face is drawn: 'peek', 'haze' or 'bloc'. Never who it is. */
+  variant?: Variant
   /** Prefix for ids inside the SVG. Default derived from everything drawn,
    * so two different avatars inlined in one page never share defs. */
   id?: string
 }
 
+// an unknown item from untyped callers keeps what the name picked
+const wear = <S extends AccessorySlot>(o: PeekOptions, base: Identity, s: S) =>
+  (ACCESSORIES[s] as readonly string[]).includes(o[s] as string)
+    ? (o[s] as Identity[S])
+    : base[s]
+
 /**
  * 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.
@@ -54,17 +68,31 @@ export function settle(
     mouth: o.mouth ?? base.mouth,
     cheeks: o.cheeks ?? base.cheeks,
     trait: o.trait ?? base.trait,
+    eyewear: wear(o, base, 'eyewear'),
+    headwear: wear(o, base, 'headwear'),
+    neckwear: wear(o, base, 'neckwear'),
   }
   const pose = restPose(who, o.expression ?? 'normal', o.gaze)
+  // an unknown variant from untyped callers draws peek
+  const variant = VARIANTS.includes(o.variant as Variant)
+    ? (o.variant as Variant)
+    : 'peek'
   const look = {
     size: o.size ?? 64,
     frame: o.frame ?? 'ink',
     square: o.square ?? true,
     riso: o.riso ?? false,
     live,
+    // left out for peek, so its ids and bytes stay as they were
+    ...(variant !== 'peek' && { variant }),
   }
+  // Keep the byte-level peek@1 contract for faces without accessories.
+  const { eyewear, headwear, neckwear, ...legacy } = who
+  const wardrobe =
+    eyewear !== 'none' || headwear !== 'none' || neckwear !== 'none'
   const id =
-    o.id ?? `peek-${fnv1a(JSON.stringify([who, pose, look])).toString(36)}`
+    o.id ??
+    `peek-${fnv1a(JSON.stringify([wardrobe ? who : legacy, pose, look])).toString(36)}`
   return { who, pose, opts: { ...look, id, title: o.title ?? name } }
 }
 

package/src/tables.ts

@@ -175,6 +175,53 @@ export const COLORS = {
   aqua: { body: '#BDE1E5', deep: '#8FC7D1' },
 } as const
 
+/*
+ * Variants: how a face is drawn, never who it is. Every variant reads the
+ * same identity, so a name keeps its face, color and parts in all of them.
+ */
+export const VARIANTS = ['peek', 'haze', 'bloc'] as const
+export type Variant = (typeof VARIANTS)[number]
+
+/**
+ * Haze, transcribed from the Haze sheet (01.3). Each ink has a glow and a
+ * tint; a body is hazed by the tint of one of its two neighbors on the hue
+ * wheel, so the tint is never picked by hand.
+ */
+export const HAZE = {
+  lavender: { tint: '#C8B1F5', glow: '#F2EDFD' },
+  fog: { tint: '#9EC3F2', glow: '#E6F1FF' },
+  clay: { tint: '#F4AE93', glow: '#FEECE5' },
+  mint: { tint: '#A3DAB5', glow: '#E5F5EA' },
+  butter: { tint: '#E1CC7A', glow: '#F4F0E0' },
+  rose: { tint: '#F0A9C4', glow: '#FDEAF1' },
+  aqua: { tint: '#85D3DC', glow: '#E0F5F7' },
+} as const satisfies Record<keyof typeof COLORS, unknown>
+/** The hue wheel, warm to cool: a body's warm side is the entry before it. */
+export const WHEEL = [
+  'clay',
+  'butter',
+  'mint',
+  'aqua',
+  'fog',
+  'lavender',
+  'rose',
+] as const satisfies readonly (keyof typeof COLORS)[]
+
+/**
+ * Bloc's strong inks, palette P2 of the Bloc sheet (02.4): the same hue at
+ * OKLCH L 0.72 and C 0.12, butter, mint and aqua held lighter so none goes
+ * olive. The strong ink fills the dark half and the trait.
+ */
+export const BLOC = {
+  lavender: '#B093E5',
+  fog: '#7BA8DF',
+  clay: '#E38A66',
+  mint: '#82CB9B',
+  butter: '#E2CA6A',
+  rose: '#DF84A8',
+  aqua: '#5EC3CD',
+} as const satisfies Record<keyof typeof COLORS, string>
+
 /** Discrete anatomy. Each part reads every channel its feature owns. */
 export const PARTS = {
   eyes: ['oval', 'bead', 'ring'],
@@ -184,6 +231,20 @@ export const PARTS = {
   trait: ['square', 'fin', 'ring', 'dot', 'peak'],
 } as const
 
+// The bow's single warm accent, transcribed from the accessory sheet.
+export const ACCESSORY_INK = { knot: '#E5412D' } as const
+
+/** Independent wardrobe slots. peek@1 picks none; callers can dress it. */
+export const ACCESSORIES = {
+  eyewear: ['none', 'glasses', 'sunglasses'],
+  headwear: ['none', 'bow', 'cap', 'sprout'],
+  neckwear: ['none', 'tie'],
+} as const
+export type Eyewear = (typeof ACCESSORIES.eyewear)[number]
+export type Headwear = (typeof ACCESSORIES.headwear)[number]
+export type Neckwear = (typeof ACCESSORIES.neckwear)[number]
+export type AccessorySlot = keyof typeof ACCESSORIES
+
 export type Face = keyof typeof FACES
 export type Color = keyof typeof COLORS
 export type Part = keyof typeof PARTS
@@ -192,11 +253,22 @@ export type Brows = (typeof PARTS.brows)[number]
 export type Mouth = (typeof PARTS.mouth)[number]
 export type Cheeks = (typeof PARTS.cheeks)[number]
 export type Trait = (typeof PARTS.trait)[number]
-export type Axis = 'face' | 'color' | Part
+export type Axis = 'face' | 'color' | Part | AccessorySlot
 
 /** How much of each list a version may pick from. Append-only too. */
 export const VERSIONS: Record<number, Record<Axis, number>> = {
-  1: { face: 4, color: 7, eyes: 3, brows: 4, mouth: 4, cheeks: 3, trait: 5 },
+  1: {
+    face: 4,
+    color: 7,
+    eyes: 3,
+    brows: 4,
+    mouth: 4,
+    cheeks: 3,
+    trait: 5,
+    eyewear: 1,
+    headwear: 1,
+    neckwear: 1,
+  },
 }
 export const LATEST = 1
 

package/src/vue.ts

@@ -0,0 +1,133 @@
+/*
+ * <Peek name="Ada" /> for Vue 3.5+: the same tree and the same rules as the
+ * React component in peek.tsx. ids come from Vue's useId, so the server and
+ * the client agree; `class` and `style` fall through to the <svg>.
+ *
+ * With `animate`, the tree Vue renders stays in the pose the component
+ * mounted with and the shared loop writes every frame straight to the DOM,
+ * so a change of expression or gaze never reaches Vue's patch.
+ */
+
+import {
+  computed,
+  defineComponent,
+  h,
+  onBeforeUnmount,
+  onMounted,
+  type PropType,
+  ref,
+  useId,
+  type VNode,
+  type VNodeRef,
+  watch,
+} from 'vue'
+import { Live } from './animate'
+import { draw, type Gaze, type Node, restPose } from './draw'
+import { type PeekOptions, settle } from './svg'
+
+export * from './core'
+
+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
+}
+
+function toVue(node: Node, ref?: VNodeRef): VNode {
+  return h(
+    node.tag,
+    { key: node.key, ...node.attrs, ref },
+    node.children.map((c) => toVue(c)),
+  )
+}
+
+// Every prop unset stays undefined so the name decides it, as in React.
+// Booleans need their type, or `<Peek animate />` would arrive as ''.
+const any = { type: null, default: undefined }
+const flag = { type: Boolean, default: undefined }
+
+export const Peek = defineComponent(
+  (props: PeekProps) => {
+    const id = `peek${useId().replace(/[^\w-]/g, '')}`
+    const svg = ref<SVGSVGElement>()
+    let live: Live | null = null
+    const fixedOf = (g: PeekProps['gaze']) =>
+      Array.isArray(g) ? (g as Gaze) : undefined
+    const first = {
+      expression: props.expression ?? 'normal',
+      gaze: fixedOf(props.gaze),
+    }
+
+    const view = computed(() => {
+      const { name, gaze, animate, ...rest } = props
+      const { who, pose, opts } = settle(
+        name,
+        { ...rest, gaze: fixedOf(gaze), id },
+        animate,
+      )
+      const tree = draw(
+        who,
+        animate ? restPose(who, first.expression, first.gaze) : pose,
+        opts,
+      )
+      // live: the tree only changes when what the face is changes
+      return { who, opts, tree, sig: JSON.stringify([who, opts]) }
+    })
+    const expression = () => props.expression ?? 'normal'
+
+    onMounted(() => {
+      watch(
+        [() => props.animate, () => view.value.sig],
+        () => {
+          live?.destroy()
+          live = null
+          if (!props.animate || !svg.value) return
+          const { tree, who, opts } = view.value
+          live = new Live(svg.value, tree, who, opts, expression(), props.gaze)
+        },
+        { immediate: true, flush: 'post' },
+      )
+      watch(expression, (e) => live?.setExpression(e), { flush: 'post' })
+      watch(
+        () => String(props.gaze ?? ''),
+        () => live?.setGaze(props.gaze),
+        { flush: 'post' },
+      )
+    })
+    onBeforeUnmount(() => live?.destroy())
+
+    return () => toVue(view.value.tree, svg)
+  },
+  {
+    // biome-ignore lint/style/useVueMultiWordComponentNames: <Peek> in every framework
+    name: 'Peek',
+    props: {
+      name: { type: String, required: true },
+      gaze: any,
+      animate: { type: Boolean, default: false },
+      size: { type: Number, default: undefined },
+      expression: any,
+      frame: any,
+      square: flag,
+      title: {
+        type: [String, Boolean] as PropType<string | false>,
+        default: undefined,
+      },
+      riso: flag,
+      version: { type: Number, default: undefined },
+      variant: any,
+      face: any,
+      color: any,
+      eyes: any,
+      brows: any,
+      mouth: any,
+      cheeks: any,
+      trait: any,
+      eyewear: any,
+      headwear: any,
+      neckwear: any,
+    },
+  },
+)