@datatechsolutions/tympan 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@datatechsolutions/tympan",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Tympan: accessible React components (React 18.3 or 19) on React Aria Components, styled with --ty-* CSS custom properties in @layer tympan. The flow and provenance canvas (graph viewer, DAG editor, run inspection) ships as the @datatechsolutions/tympan/flow subpath. Generated avatars (DiceBear, CC0/MIT styles only) ship as the /avatars subpath and country and region flags as the /flags subpath.",
   "license": "FSL-1.1-ALv2",
   "author": "Natalia Mesquita",
@@ -55,29 +55,42 @@
       "types": "./dist/flags.d.ts",
       "default": "./dist/flags.js"
     },
+    "./elements": {
+      "tympan-source": "./src/elements/index.ts",
+      "types": "./dist/elements.d.ts",
+      "default": "./dist/elements.js"
+    },
+    "./elements/react": {
+      "tympan-source": "./src/elements/react/index.ts",
+      "types": "./dist/elements-react.d.ts",
+      "default": "./dist/elements-react.js"
+    },
+    "./elements.bundle.js": "./dist/elements.bundle.js",
     "./styles.css": "./dist/styles.css",
     "./flow.css": "./dist/flow.css",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
+    "docs",
     "LICENSE",
+    "README.md",
     "THIRD_PARTY_NOTICES.md"
   ],
   "scripts": {
     "prebuild": "npm run build -w @datatechsolutions/tympan-tokens && node scripts/build-flags.mjs",
-    "build": "tsdown && node scripts/build-css.mjs && node scripts/prune-flag-maps.mjs",
+    "build": "tsdown && tsdown -c tsdown.elements.config.ts && node scripts/build-css.mjs && node scripts/prune-flag-maps.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
     "gallery": "npm run build -w @datatechsolutions/tympan-tokens && node scripts/build-flags.mjs && vite --config gallery/vite.config.ts",
     "gallery:build": "npm run build -w @datatechsolutions/tympan-tokens && node scripts/build-flags.mjs && vite build --config gallery/vite.config.ts",
     "pretest": "npm run build -w @datatechsolutions/tympan-tokens && node scripts/build-flags.mjs",
-    "pretypecheck": "npm run build -w @datatechsolutions/tympan-tokens && node scripts/build-flags.mjs"
+    "pretypecheck": "npm run build -w @datatechsolutions/tympan-tokens && node scripts/build-flags.mjs",
+    "prepack": "npm run build"
   },
   "peerDependencies": {
-    "@dagrejs/dagre": "^3.1.1",
-    "@dicebear/core": "^9.4.3",
     "@dicebear/glass": "^9.4.3",
     "@dicebear/icons": "^9.4.3",
     "@dicebear/identicon": "^9.4.3",
@@ -96,12 +109,6 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
-    "@dagrejs/dagre": {
-      "optional": true
-    },
-    "@dicebear/core": {
-      "optional": true
-    },
     "@dicebear/glass": {
       "optional": true
     },
@@ -146,7 +153,9 @@
     }
   },
   "dependencies": {
-    "@datatechsolutions/tympan-tokens": "0.3.0",
+    "@dagrejs/dagre": "^3.1.1",
+    "@datatechsolutions/tympan-tokens": "^0.3.1",
+    "@dicebear/core": "^9.4.3",
     "@internationalized/date": "^3.12.4",
     "@types/d3-array": "^3.2.2",
     "@types/d3-path": "^3.1.1",
@@ -165,8 +174,6 @@
     "topojson-client": "^3.1.0"
   },
   "devDependencies": {
-    "@dagrejs/dagre": "^3.1.1",
-    "@dicebear/core": "^9.4.3",
     "@dicebear/glass": "^9.4.3",
     "@dicebear/icons": "^9.4.3",
     "@dicebear/identicon": "^9.4.3",
@@ -185,6 +192,10 @@
     "axe-core": "^4.13.0",
     "flag-icons": "7.5.0"
   },
+  "homepage": "https://github.com/datatechsolutionsbr/tympan#readme",
+  "bugs": {
+    "url": "https://github.com/datatechsolutionsbr/tympan/issues"
+  },
   "publishConfig": {
     "access": "public"
   }

package/src/avatars/GeneratedAvatar.tsx

@@ -0,0 +1,41 @@
+import { useId, useMemo } from 'react'
+import { Avatar, type AvatarProps } from '../components/avatar/Avatar'
+import { devWarning } from '../internal/dev'
+import { avatarSvg, type AvatarPalette, type AvatarStyle } from './avatarSvg'
+
+export interface GeneratedAvatarProps extends Omit<AvatarProps, 'artwork'> {
+  /** Any stable string (user id, agent key): the same seed always draws the same avatar. */
+  seed: string
+  /** An allowed DiceBear style module, e.g. `import * as shapes from '@dicebear/shapes'`. */
+  avatarStyle: AvatarStyle
+  /** Fixed colours (see `avatarPalette`); by default the avatar follows the theme in scope. */
+  palette?: AvatarPalette
+}
+
+/**
+ * Avatar with generated artwork (DiceBear, CC0 or MIT styles only) in the
+ * active theme's colours. Everything else is Avatar: an image wins when it
+ * loads, the frame carries the accessible name (or is hidden when
+ * `decorative`), agents keep the rounded, dashed frame and take abstract
+ * styles only. If the artwork cannot be drawn (a style outside the
+ * allow-list, a face style for an agent) the Avatar fallback shows: initials
+ * for a person, the bot icon for an agent.
+ */
+export function GeneratedAvatar({ seed, avatarStyle, palette, actorKind = 'person', ...rest }: GeneratedAvatarProps) {
+  const uid = useId()
+  const svg = useMemo(() => {
+    try {
+      return avatarSvg({ seed, style: avatarStyle, theme: palette ?? 'css', kind: actorKind, idPrefix: `ty-av${uid}` })
+    } catch (error) {
+      devWarning(true, `GeneratedAvatar: ${(error as Error).message} Showing the fallback.`)
+      return null
+    }
+  }, [seed, avatarStyle, palette, actorKind, uid])
+  return (
+    <Avatar
+      {...rest}
+      actorKind={actorKind}
+      artwork={svg ? <span className="ty-avatar__artwork" data-generated="" aria-hidden="true" dangerouslySetInnerHTML={{ __html: svg }} /> : null}
+    />
+  )
+}

package/src/avatars/avatarSvg.ts

@@ -0,0 +1,252 @@
+// Deterministic generated avatars: DiceBear draws the artwork from a seed,
+// Tympan supplies the colours. By default the colours are CSS custom
+// properties, so an inline avatar follows the active theme and mode with no
+// re-render; `avatarPalette()` resolves them to hex for contexts without the
+// Tympan stylesheet (images, e-mail, server rendering to a file).
+import { createAvatar, type Style } from '@dicebear/core'
+import { oklchToRgb, presets, printThemePresets, resolveTheme, rgbToOklch, toHex, type Rgba, type ThemeConfig } from '@datatechsolutions/tympan-tokens'
+import { ALLOWED_AVATAR_LICENSES, ALLOWED_AVATAR_STYLES, type AllowedAvatarStyle } from './styles'
+
+/**
+ * A DiceBear style module (`import * as shapes from '@dicebear/shapes'`).
+ * Only the styles in `ALLOWED_AVATAR_STYLES` are accepted.
+ */
+export interface AvatarStyle {
+  meta?: { title?: string; creator?: string; source?: string; license?: { name?: string; url?: string } }
+  create: (...args: never[]) => unknown
+  schema?: unknown
+}
+
+export type AvatarKind = 'person' | 'agent'
+
+/**
+ * Colour slots the styles draw with: soft backgrounds (follow the mode), ink
+ * shapes, solid fills that carry white artwork, and light paper behind the
+ * black line art of figure styles (light in both modes, so faces stay legible).
+ */
+export const AVATAR_SLOTS = ['soft-1', 'soft-2', 'soft-3', 'ink-1', 'ink-2', 'ink-3', 'solid-1', 'solid-2', 'solid-3', 'paper-1', 'paper-2', 'paper-3'] as const
+export type AvatarSlot = (typeof AVATAR_SLOTS)[number]
+/** One CSS colour per slot. */
+export type AvatarPalette = Record<AvatarSlot, string>
+
+/** Thrown for a style outside the licence allow-list, or a people-only style drawn for an agent. */
+export class AvatarStyleError extends Error {
+  override name = 'AvatarStyleError'
+}
+
+// Sentinel colours handed to DiceBear and swapped for the palette afterwards.
+// They are valid hex (DiceBear's option schema) and appear in no allowed style.
+const SENTINEL: Record<AvatarSlot, string> = {
+  'soft-1': 'fe01a1',
+  'soft-2': 'fe01a2',
+  'soft-3': 'fe01a3',
+  'ink-1': 'fe01b1',
+  'ink-2': 'fe01b2',
+  'ink-3': 'fe01b3',
+  'solid-1': 'fe01c1',
+  'solid-2': 'fe01c2',
+  'solid-3': 'fe01c3',
+  'paper-1': 'fe01d1',
+  'paper-2': 'fe01d2',
+  'paper-3': 'fe01d3',
+}
+const s = (...slots: AvatarSlot[]) => slots.map((slot) => SENTINEL[slot])
+const SOFT = s('soft-1', 'soft-2', 'soft-3')
+const INK = s('ink-1', 'ink-2', 'ink-3')
+const SOLID = s('solid-1', 'solid-2', 'solid-3')
+const PAPER = s('paper-1', 'paper-2', 'paper-3')
+
+/**
+ * Which DiceBear colour options each style gets. Figure styles only get a
+ * background: skin, hair and eye colours stay the artist's, never the brand.
+ */
+const COLOR_OPTIONS: Record<string, Record<string, string[]>> = {
+  Glass: { backgroundColor: SOLID },
+  'Bootstrap Icons': { backgroundColor: SOLID },
+  Identicon: { backgroundColor: s('soft-1', 'soft-3'), rowColor: INK },
+  Initials: { backgroundColor: s('soft-1', 'soft-2'), textColor: s('ink-2') },
+  Lorelei: { backgroundColor: PAPER },
+  'Lorelei Neutral': { backgroundColor: PAPER },
+  Notionists: { backgroundColor: PAPER },
+  'Open Peeps': { backgroundColor: PAPER },
+  'Pixel Art': { backgroundColor: PAPER },
+  'Pixel Art Neutral': { backgroundColor: PAPER },
+  Rings: { backgroundColor: s('soft-1', 'soft-3'), ringColor: INK },
+  Shapes: { backgroundColor: SOFT, shape1Color: INK, shape2Color: SOLID, shape3Color: s('ink-3', 'solid-1') },
+  Thumbs: { backgroundColor: SOFT, shapeColor: INK },
+}
+
+const mix = (a: string, pct: number, b: string) => `color-mix(in oklch, ${a} ${pct}%, ${b})`
+
+/** The theme expressions behind each slot; people draw from the brand, agents from the neutral ink. */
+const CSS_SOURCES: Record<AvatarKind, AvatarPalette> = {
+  person: {
+    'soft-1': mix('var(--ty-brand)', 14, 'var(--ty-bg)'),
+    'soft-2': mix('var(--ty-brand)', 28, 'var(--ty-bg)'),
+    'soft-3': mix('var(--ty-ink)', 10, 'var(--ty-bg)'),
+    'ink-1': 'var(--ty-brand)',
+    'ink-2': 'var(--ty-brand-strong)',
+    'ink-3': mix('var(--ty-brand)', 55, 'var(--ty-ink)'),
+    'solid-1': 'var(--ty-brand-600)',
+    'solid-2': 'var(--ty-brand-700)',
+    'solid-3': 'var(--ty-brand-800)',
+    'paper-1': 'var(--ty-brand-100)',
+    'paper-2': 'var(--ty-brand-200)',
+    'paper-3': 'var(--ty-neutral-100)',
+  },
+  agent: {
+    'soft-1': mix('var(--ty-ink)', 8, 'var(--ty-bg)'),
+    'soft-2': mix('var(--ty-ink)', 14, 'var(--ty-bg)'),
+    'soft-3': mix('var(--ty-ink)', 20, 'var(--ty-bg)'),
+    'ink-1': 'var(--ty-actor-agent)',
+    'ink-2': 'var(--ty-ink-3)',
+    'ink-3': mix('var(--ty-ink)', 70, 'var(--ty-bg)'),
+    'solid-1': 'var(--ty-neutral-600)',
+    'solid-2': 'var(--ty-neutral-700)',
+    'solid-3': 'var(--ty-neutral-800)',
+    'paper-1': 'var(--ty-neutral-50)',
+    'paper-2': 'var(--ty-neutral-100)',
+    'paper-3': 'var(--ty-neutral-200)',
+  },
+}
+
+/**
+ * The palette as CSS: each slot is `var(--ty-avatar-<slot>, <theme expression>)`,
+ * so a host can repaint one slot with a custom property and everything else
+ * follows the Tympan theme and colour mode in scope.
+ */
+export function avatarCssPalette(kind: AvatarKind = 'person'): AvatarPalette {
+  const out = {} as AvatarPalette
+  for (const slot of AVATAR_SLOTS) out[slot] = `var(--ty-avatar-${slot}, ${CSS_SOURCES[kind][slot]})`
+  return out
+}
+
+function mixRgb(a: Rgba, pct: number, b: Rgba): Rgba {
+  // OKLCH interpolation like CSS color-mix(in oklch): shorter hue arc, an achromatic side takes the other's hue.
+  const p = pct / 100
+  const x = rgbToOklch(a)
+  const y = rgbToOklch(b)
+  const hx = x.c < 0.02 ? y.h : x.h
+  const hy = y.c < 0.02 ? x.h : y.h
+  let dh = hy - hx
+  if (dh > 180) dh -= 360
+  if (dh < -180) dh += 360
+  return oklchToRgb({ l: x.l * p + y.l * (1 - p), c: x.c * p + y.c * (1 - p), h: (hx + dh * (1 - p) + 360) % 360 })
+}
+
+/** Finds a built-in or print theme preset by name. */
+function presetByName(name: string): ThemeConfig {
+  const found = [...presets, ...printThemePresets].find((p) => p.name === name)
+  if (!found) throw new Error(`Unknown Tympan theme "${name}".`)
+  return found
+}
+
+/**
+ * The palette resolved to hex for one theme (a preset name or a
+ * `ThemeConfig`) in one mode: the same recipe as the CSS palette.
+ */
+export function avatarPalette(theme: string | ThemeConfig, mode: 'light' | 'dark', kind: AvatarKind = 'person'): AvatarPalette {
+  const r = resolveTheme(typeof theme === 'string' ? presetByName(theme) : theme, mode)
+  const c = (role: string): Rgba => r.colors[role] ?? { r: 0.5, g: 0.5, b: 0.5, a: 1 }
+  const hex = (x: Rgba) => toHex(x)
+  if (kind === 'agent') {
+    return {
+      'soft-1': hex(mixRgb(c('ink'), 8, c('bg'))),
+      'soft-2': hex(mixRgb(c('ink'), 14, c('bg'))),
+      'soft-3': hex(mixRgb(c('ink'), 20, c('bg'))),
+      'ink-1': hex(c('actor-agent')),
+      'ink-2': hex(c('ink-3')),
+      'ink-3': hex(mixRgb(c('ink'), 70, c('bg'))),
+      'solid-1': hex(r.ramps.neutral[600]),
+      'solid-2': hex(r.ramps.neutral[700]),
+      'solid-3': hex(r.ramps.neutral[800]),
+      'paper-1': hex(r.ramps.neutral[50]),
+      'paper-2': hex(r.ramps.neutral[100]),
+      'paper-3': hex(r.ramps.neutral[200]),
+    }
+  }
+  return {
+    'soft-1': hex(mixRgb(c('brand'), 14, c('bg'))),
+    'soft-2': hex(mixRgb(c('brand'), 28, c('bg'))),
+    'soft-3': hex(mixRgb(c('ink'), 10, c('bg'))),
+    'ink-1': hex(c('brand')),
+    'ink-2': hex(c('brand-strong')),
+    'ink-3': hex(mixRgb(c('brand'), 55, c('ink'))),
+    'solid-1': hex(r.ramps.brand[600]),
+    'solid-2': hex(r.ramps.brand[700]),
+    'solid-3': hex(r.ramps.brand[800]),
+    'paper-1': hex(r.ramps.brand[100]),
+    'paper-2': hex(r.ramps.brand[200]),
+    'paper-3': hex(r.ramps.neutral[100]),
+  }
+}
+
+/**
+ * The allow-list entry of a style, or an `AvatarStyleError` when the style's
+ * artwork licence is not CC0 1.0 or MIT, or the style is not on the list.
+ */
+export function allowedAvatarStyle(style: AvatarStyle): AllowedAvatarStyle {
+  const title = style?.meta?.title
+  const license = style?.meta?.license?.name
+  if (!license || !(ALLOWED_AVATAR_LICENSES as readonly string[]).includes(license)) {
+    throw new AvatarStyleError(`Avatar style "${title ?? 'unknown'}" has artwork licence "${license ?? 'unknown'}"; only CC0 1.0 and MIT styles are allowed.`)
+  }
+  const entry = ALLOWED_AVATAR_STYLES.find((e) => e.title === title && e.designLicense === license)
+  if (!entry) throw new AvatarStyleError(`Avatar style "${title ?? 'unknown'}" is not on the Tympan allow-list.`)
+  return entry
+}
+
+/** FNV-1a, for short deterministic id prefixes. */
+function hash(text: string): string {
+  let h = 0x811c9dc5
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i)
+    h = Math.imul(h, 0x01000193)
+  }
+  return (h >>> 0).toString(36)
+}
+
+const escapeAttr = (v: string) => v.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;')
+
+export interface AvatarSvgOptions {
+  /** Any stable string (user id, e-mail hash, agent key): same seed, same avatar. */
+  seed: string
+  /** An allowed DiceBear style module. */
+  style: AvatarStyle
+  /** Width and height in px; omitted, the SVG fills its container. */
+  size?: number
+  /** `'css'` (default): colours follow the theme in scope. A palette (see `avatarPalette`): fixed colours. */
+  theme?: 'css' | AvatarPalette
+  /** People draw from the brand; agents from the neutral ink, and only with abstract styles. */
+  kind?: AvatarKind
+  /** Prefix for the SVG's internal ids (masks, gradients); defaults to a hash of seed, style and kind. */
+  idPrefix?: string
+  /** Accessible name: the SVG becomes role="img". Without it the SVG is aria-hidden (decorative). */
+  title?: string
+}
+
+/**
+ * A generated avatar as an SVG string, deterministic from the seed. Throws
+ * `AvatarStyleError` for a style outside the licence allow-list, and for a
+ * face or initials style drawn for an agent.
+ */
+export function avatarSvg({ seed, style, size, theme = 'css', kind = 'person', idPrefix, title }: AvatarSvgOptions): string {
+  const entry = allowedAvatarStyle(style)
+  if (kind === 'agent' && entry.subject !== 'abstract') {
+    throw new AvatarStyleError(`Avatar style "${entry.title}" draws ${entry.subject === 'text' ? 'initials' : 'a face'}; agents take an abstract style (Glass, Bootstrap Icons, Identicon, Rings, Shapes).`)
+  }
+  const colors = COLOR_OPTIONS[entry.title] ?? { backgroundColor: SOFT }
+  const extra: Record<string, unknown> =
+    entry.title === 'Initials' ? { fontFamily: [theme === 'css' ? 'var(--ty-font-sans, system-ui, sans-serif)' : 'system-ui, sans-serif'], fontWeight: 600, fontSize: 42 } : {}
+  let svg = createAvatar(style as unknown as Style<object>, { seed, ...(size ? { size } : {}), ...colors, ...extra }).toString()
+
+  const palette = theme === 'css' ? avatarCssPalette(kind) : theme
+  for (const slot of AVATAR_SLOTS) svg = svg.replace(new RegExp(`#${SENTINEL[slot]}`, 'gi'), escapeAttr(palette[slot]))
+
+  // Scope internal ids so several avatars on one page never share a mask or gradient.
+  const prefix = (idPrefix ?? `ty-av-${hash(`${entry.title}\u0000${kind}\u0000${seed}`)}`).replace(/[^\w-]/g, '')
+  svg = svg.replace(/(\bid="|url\(#|href="#)([\w-]+)([")])/g, (_m, a: string, id: string, b: string) => `${a}${prefix}-${id}${b}`)
+
+  const a11y = title ? `role="img" aria-label="${escapeAttr(title)}"` : 'aria-hidden="true" focusable="false"'
+  return svg.replace(/^<svg /, `<svg ${a11y} `)
+}

package/src/avatars/avatars.test.tsx

@@ -0,0 +1,268 @@
+import { createAvatar, type Style } from '@dicebear/core'
+import * as glass from '@dicebear/glass'
+import * as icons from '@dicebear/icons'
+import * as identicon from '@dicebear/identicon'
+import * as initials from '@dicebear/initials'
+import * as lorelei from '@dicebear/lorelei'
+import * as loreleiNeutral from '@dicebear/lorelei-neutral'
+import * as notionists from '@dicebear/notionists'
+import * as notionistsNeutral from '@dicebear/notionists-neutral'
+import * as openPeeps from '@dicebear/open-peeps'
+import * as pixelArt from '@dicebear/pixel-art'
+import * as pixelArtNeutral from '@dicebear/pixel-art-neutral'
+import * as rings from '@dicebear/rings'
+import * as shapes from '@dicebear/shapes'
+import * as thumbs from '@dicebear/thumbs'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+import { expectNoAxeViolations } from '../../test/axe'
+import { renderRtl } from '../../test/rtl'
+import {
+  ALLOWED_AVATAR_LICENSES,
+  ALLOWED_AVATAR_STYLES,
+  AVATAR_SLOTS,
+  AvatarStyleError,
+  EXCLUDED_AVATAR_STYLES,
+  GeneratedAvatar,
+  avatarPalette,
+  avatarSvg,
+  type AvatarStyle,
+} from './index'
+
+const MODULES: Record<string, AvatarStyle> = {
+  '@dicebear/glass': glass,
+  '@dicebear/icons': icons,
+  '@dicebear/identicon': identicon,
+  '@dicebear/initials': initials,
+  '@dicebear/lorelei': lorelei,
+  '@dicebear/lorelei-neutral': loreleiNeutral,
+  '@dicebear/notionists': notionists,
+  '@dicebear/notionists-neutral': notionistsNeutral,
+  '@dicebear/open-peeps': openPeeps,
+  '@dicebear/pixel-art': pixelArt,
+  '@dicebear/pixel-art-neutral': pixelArtNeutral,
+  '@dicebear/rings': rings,
+  '@dicebear/shapes': shapes,
+  '@dicebear/thumbs': thumbs,
+}
+
+const SEEDS = Array.from({ length: 24 }, (_, i) => `sample-person-${i}`)
+
+describe('avatarSvg', () => {
+  it('is deterministic: same seed, same SVG; another seed, another SVG', () => {
+    for (const style of Object.values(MODULES)) {
+      const a = avatarSvg({ seed: 'Iris Calder', style })
+      expect(avatarSvg({ seed: 'Iris Calder', style })).toBe(a)
+      expect(avatarSvg({ seed: 'Tomas Reyna', style })).not.toBe(a)
+    }
+  })
+
+  it('draws every allowed style and replaces every colour it hands to DiceBear', () => {
+    for (const [pkg, style] of Object.entries(MODULES)) {
+      for (const seed of SEEDS) {
+        // The sentinels never occur in the artwork itself...
+        expect(createAvatar(style as unknown as Style<object>, { seed }).toString(), pkg).not.toMatch(/fe01[a-d][123]/i)
+        // ...and none survives in the output.
+        const svg = avatarSvg({ seed, style })
+        expect(svg, pkg).not.toMatch(/fe01[a-d][123]/i)
+        expect(svg.startsWith('<svg '), pkg).toBe(true)
+      }
+    }
+  })
+
+  it('takes its colours from the theme in scope through CSS custom properties', () => {
+    const person = avatarSvg({ seed: 'Iris Calder', style: shapes })
+    expect(person).toMatch(/fill="var\(--ty-avatar-soft-[123], color-mix\(in oklch, var\(--ty-(brand|ink)\)/)
+    expect(person).toContain('var(--ty-brand')
+    const agent = avatarSvg({ seed: 'summary-agent', style: shapes, kind: 'agent' })
+    expect(agent).toMatch(/var\(--ty-(actor-agent|ink|neutral-[678]00)/)
+    expect(agent).not.toContain('--ty-brand')
+  })
+
+  it('resolves the palette per theme and mode for fixed-colour output', () => {
+    const tympanLight = avatarPalette('tympan', 'light')
+    const tympanDark = avatarPalette('tympan', 'dark')
+    const printLight = avatarPalette('print-cartao-postal', 'light')
+    for (const slot of AVATAR_SLOTS) expect(tympanLight[slot]).toMatch(/^#[0-9a-f]{6}$/)
+    expect(tympanLight['soft-1']).not.toBe(tympanDark['soft-1'])
+    expect(tympanLight['ink-1']).not.toBe(printLight['ink-1'])
+    expect(tympanLight['soft-1']).not.toBe(printLight['soft-1'])
+    expect(avatarPalette('tympan', 'light', 'agent')['ink-1']).not.toBe(tympanLight['ink-1'])
+
+    const svg = avatarSvg({ seed: 'Iris Calder', style: identicon, theme: tympanLight })
+    expect(svg).not.toContain('var(')
+    expect(svg.toLowerCase()).toMatch(new RegExp(`${tympanLight['ink-1']}|${tympanLight['ink-2']}|${tympanLight['ink-3']}`))
+  })
+
+  it('keeps figure art in the artist colours and only paints the background, on light paper', () => {
+    const svg = avatarSvg({ seed: 'Iris Calder', style: lorelei })
+    expect((svg.match(/var\(--ty-avatar-/g) ?? []).length).toBe(1)
+    expect(svg).toMatch(/var\(--ty-avatar-paper-[123], var\(--ty-(brand|neutral)-[12]00\)\)/)
+  })
+
+  it('scopes internal ids and sets the size and accessible name when asked', () => {
+    const svg = avatarSvg({ seed: 'Iris Calder', style: glass, size: 48, idPrefix: 'demo', title: 'Iris Calder' })
+    expect(svg).toMatch(/^<svg role="img" aria-label="Iris Calder" /)
+    expect(svg).toContain('width="48"')
+    expect(svg).toContain('id="demo-viewboxMask"')
+    expect(svg).not.toMatch(/id="viewboxMask"/)
+    expect(avatarSvg({ seed: 'x', style: glass })).toMatch(/^<svg aria-hidden="true" focusable="false" /)
+  })
+
+  it('rejects a style whose artwork licence is not CC0 or MIT', () => {
+    const ccBy: AvatarStyle = { meta: { title: 'Adventurer', license: { name: 'CC BY 4.0' } }, create: () => ({}) }
+    const custom: AvatarStyle = { meta: { title: 'Avataaars', license: { name: 'Free for personal and commercial use' } }, create: () => ({}) }
+    const unlisted: AvatarStyle = { meta: { title: 'Home Made', license: { name: 'MIT' } }, create: () => ({}) }
+    expect(() => avatarSvg({ seed: 'x', style: ccBy })).toThrow(AvatarStyleError)
+    expect(() => avatarSvg({ seed: 'x', style: custom })).toThrow(/only CC0 1.0 and MIT/)
+    expect(() => avatarSvg({ seed: 'x', style: unlisted })).toThrow(/not on the Tympan allow-list/)
+  })
+
+  it('never draws a face or initials for an agent', () => {
+    expect(() => avatarSvg({ seed: 'x', style: lorelei, kind: 'agent' })).toThrow(/agents take an abstract style/)
+    expect(() => avatarSvg({ seed: 'x', style: initials, kind: 'agent' })).toThrow(/initials/)
+    expect(() => avatarSvg({ seed: 'x', style: rings, kind: 'agent' })).not.toThrow()
+  })
+})
+
+describe('licence allow-list', () => {
+  // Vitest runs in packages/ui.
+  const root = new URL(`file://${process.cwd()}/`)
+  const fs = () => import('node:fs')
+
+  it('matches the artwork licence each installed package declares', async () => {
+    const { readFileSync } = await fs()
+    const { createRequire } = await import('node:module')
+    const require = createRequire(import.meta.url)
+    expect(Object.keys(MODULES).sort()).toEqual(ALLOWED_AVATAR_STYLES.map((s) => s.package).sort())
+    for (const entry of ALLOWED_AVATAR_STYLES) {
+      // The packages export only lib/index.js; LICENSE sits one level above it.
+      const license = readFileSync(new URL('../LICENSE', `file://${require.resolve(entry.package, { paths: [process.cwd()] })}`), 'utf8')
+      const design = /# Design[\s\S]*?License:\s*([^(\n]+?)\s*\(/.exec(license)?.[1]
+      // A package without a design section is MIT as a whole (Initials, Bootstrap Icons).
+      const declared = design ?? (/^MIT License/.test(license.trim()) ? 'MIT' : 'unknown')
+      expect((ALLOWED_AVATAR_LICENSES as readonly string[]).includes(declared), `${entry.package}: ${declared}`).toBe(true)
+      expect(MODULES[entry.package]!.meta?.license?.name, entry.package).toBe(entry.designLicense)
+      expect(MODULES[entry.package]!.meta?.title, entry.package).toBe(entry.title)
+    }
+  })
+
+  it('fails when source, gallery or package.json names a style outside the allow-list', async () => {
+    const { readdirSync, readFileSync, statSync } = await fs()
+    const allowed = new Set(['@dicebear/core', ...ALLOWED_AVATAR_STYLES.map((s) => s.package)])
+    const found: string[] = []
+    const walk = (dir: URL) => {
+      for (const name of readdirSync(dir)) {
+        if (name === 'node_modules' || name === 'dist' || name === 'art') continue
+        const file = new URL(name, dir)
+        if (statSync(file).isDirectory()) walk(new URL(`${name}/`, dir))
+        else if (/\.(tsx?|mjs|json)$/.test(name)) {
+          const text = readFileSync(file, 'utf8')
+          for (const m of text.matchAll(/(?:from\s+|import\s*\(\s*)['"](@dicebear\/[\w-]+)/g)) found.push(`${name}: ${m[1]}`)
+        }
+      }
+    }
+    walk(new URL('src/', root))
+    walk(new URL('gallery/', root))
+    const pkg = JSON.parse(readFileSync(new URL('package.json', root), 'utf8')) as Record<string, Record<string, string> | undefined>
+    for (const field of ['dependencies', 'devDependencies', 'peerDependencies']) {
+      for (const name of Object.keys(pkg[field] ?? {})) if (name.startsWith('@dicebear/')) found.push(`package.json ${field}: ${name}`)
+    }
+    const outside = found.filter((f) => !allowed.has(f.split(': ')[1]!))
+    expect(outside).toEqual([])
+    expect(found.length).toBeGreaterThan(0)
+    // Every excluded package is really outside the list.
+    for (const e of EXCLUDED_AVATAR_STYLES) expect(allowed.has(e.package)).toBe(false)
+  })
+})
+
+describe('GeneratedAvatar', () => {
+  it('draws the artwork inline and names the frame', () => {
+    const { container } = render(<GeneratedAvatar seed="Iris Calder" avatarStyle={notionists} name="Iris Calder" fallbackText="IC" />)
+    const frame = screen.getByRole('img', { name: 'Iris Calder' })
+    expect(frame).toHaveAttribute('data-artwork')
+    const svg = container.querySelector('.ty-avatar__artwork svg')!
+    expect(svg).toHaveAttribute('aria-hidden', 'true')
+    expect(screen.queryByText('IC')).toBeNull()
+  })
+
+  it('draws the same artwork for the same seed', () => {
+    const { container } = render(
+      <>
+        <GeneratedAvatar seed="Iris Calder" avatarStyle={rings} decorative />
+        <GeneratedAvatar seed="Iris Calder" avatarStyle={rings} decorative />
+      </>,
+    )
+    const [a, b] = [...container.querySelectorAll('.ty-avatar__artwork')].map((n) => n.innerHTML.replace(/ty-av[^"#)]*-/g, 'ID-'))
+    expect(a).toBe(b)
+  })
+
+  it('keeps people and agents apart: frame, palette and style', () => {
+    const { container } = render(
+      <>
+        <GeneratedAvatar seed="Iris Calder" avatarStyle={shapes} name="Iris Calder" />
+        <GeneratedAvatar seed="summary-agent" avatarStyle={shapes} name="Summary agent" actorKind="agent" />
+      </>,
+    )
+    const [person, agent] = [...container.querySelectorAll('.ty-avatar')]
+    expect(person).toHaveAttribute('data-kind', 'person')
+    expect(agent).toHaveAttribute('data-kind', 'agent')
+    expect(person!.innerHTML).toContain('--ty-brand')
+    expect(agent!.innerHTML).not.toContain('--ty-brand')
+  })
+
+  it('falls back to initials (person) or the bot icon (agent) when the style is refused', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const ccBy: AvatarStyle = { meta: { title: 'Adventurer', license: { name: 'CC BY 4.0' } }, create: () => ({}) }
+    const { container } = render(
+      <>
+        <GeneratedAvatar seed="Iris Calder" avatarStyle={ccBy} name="Iris Calder" fallbackText="IC" />
+        <GeneratedAvatar seed="summary-agent" avatarStyle={lorelei} name="Summary agent" actorKind="agent" />
+      </>,
+    )
+    expect(screen.getByText('IC')).toBeInTheDocument()
+    expect(container.querySelectorAll('.ty-avatar__artwork')).toHaveLength(0)
+    expect(container.querySelector('[data-kind="agent"] .ty-avatar__icon')).not.toBeNull()
+    expect(warn).toHaveBeenCalled()
+    warn.mockRestore()
+  })
+
+  it('prefers a loaded image over the artwork', () => {
+    render(<GeneratedAvatar seed="Iris Calder" avatarStyle={shapes} src="/photo.png" name="Iris Calder" />)
+    expect(screen.getByRole('img', { name: 'Iris Calder' }).tagName).toBe('IMG')
+  })
+
+  it('uses fixed colours when given a palette', () => {
+    const palette = avatarPalette('neutral', 'dark')
+    const { container } = render(<GeneratedAvatar seed="Iris Calder" avatarStyle={identicon} palette={palette} decorative />)
+    expect(container.innerHTML).not.toContain('var(--ty-avatar')
+  })
+
+  it('is hidden when decorative and has no axe violations', async () => {
+    const { container } = render(
+      <div>
+        <GeneratedAvatar seed="Iris Calder" avatarStyle={lorelei} decorative />
+        <GeneratedAvatar seed="Tomas Reyna" avatarStyle={glass} name="Tomas Reyna" size="large" />
+        <GeneratedAvatar seed="summary-agent" avatarStyle={identicon} name="Summary agent" actorKind="agent" onPress={() => {}} />
+      </div>,
+    )
+    expect(container.querySelector('.ty-avatar')).toHaveAttribute('aria-hidden', 'true')
+    await expectNoAxeViolations(container)
+  })
+})
+
+describe('GeneratedAvatar in right-to-left (ar)', () => {
+  it('renders the same artwork (avatars do not mirror) and passes axe', async () => {
+    const { container } = renderRtl(
+      <>
+        <GeneratedAvatar seed="Iris Calder" avatarStyle={pixelArt} name="نور الهدى" fallbackText="نه" />
+        <GeneratedAvatar seed="summary-agent" avatarStyle={rings} name="وكيل الملخص" actorKind="agent" />
+      </>,
+    )
+    expect(screen.getByRole('img', { name: 'نور الهدى' })).toHaveAttribute('data-artwork')
+    const ltr = render(<GeneratedAvatar seed="Iris Calder" avatarStyle={pixelArt} decorative />)
+    const strip = (html: string) => html.replace(/ty-av[^"#)]*-/g, 'ID-')
+    expect(strip(container.querySelector('.ty-avatar__artwork')!.innerHTML)).toBe(strip(ltr.container.querySelector('.ty-avatar__artwork')!.innerHTML))
+    await expectNoAxeViolations(container)
+  })
+})