@heyramzi/ui 8.0.0 → 8.1.0

package/README.md

@@ -129,7 +129,7 @@ Inspired by [shadcn-svelte](https://github.com/huntabyte/shadcn-svelte).
 The reveal, marquee and beam effects are inspired by
 [motion-primitives](https://github.com/ibelick/motion-primitives), and the
 motion vocabulary by [transitions-dev](https://transitions.dev). The agent avatars
-vendor [bot-avatars](https://github.com/jakubantalik/bot-avatars); its licence is in
+port [bot-avatars](https://github.com/Jakubantalik/Libraries.dev/tree/main/packages/bot-avatars) 0.2.2; its licence is in
 `src/agents/vendor/LICENSE`.
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heyramzi/ui",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "description": "Svelte 5 UI primitives: effects, animations, and shared component CSS.",
   "license": "MIT",
   "repository": {

package/src/agents/agent-avatar.svelte

@@ -1,55 +1,5 @@
-<script module lang="ts">
-  /* The batching shown-gate and the path caches are shared by every avatar
-     on the page, so a row of them comes in together. Engine: ./vendor. */
-  import { bakesPending as bakesPendingGlobal } from './vendor/plastic';
-
-  const SHOW_WITHIN = 4000;
-  const waiters = new Map<object, { ready: () => boolean; show: () => void }>();
-
-  function showReady() {
-    if (bakesPendingGlobal()) return;
-    for (const w of waiters.values()) if (!w.ready()) return;
-    const all = [...waiters.values()];
-    waiters.clear();
-    for (const w of all) w.show();
-  }
-
-  const pathCache = new Map<string, Path2D>();
-  function bodyPath(d: string): Path2D {
-    let p = pathCache.get(d);
-    if (!p) {
-      p = new Path2D(d);
-      pathCache.set(d, p);
-    }
-    return p;
-  }
-
-  const partsCache = new Map<string, Path2D[]>();
-  function partPaths(d: string): Path2D[] {
-    let p = partsCache.get(d);
-    if (!p) {
-      p = d
-        .split(/(?=M)/)
-        .filter((s) => s.trim())
-        .map((s) => new Path2D(s));
-      partsCache.set(d, p);
-    }
-    return p;
-  }
-
-  let uidSeq = 0;
-  function hashSeed(id: string): number {
-    let h = 2166136261;
-    for (let i = 0; i < id.length; i++) h = Math.imul(h ^ id.charCodeAt(i), 16777619);
-    return ((h >>> 0) % 1000) / 1000;
-  }
-
-  export const reducedMotion = (): boolean =>
-    typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
-</script>
-
 <script lang="ts">
-  import { onMount } from 'svelte';
+  import { onMount, untrack } from 'svelte';
   import type {
     BotAvatarShading,
     BotAvatarState,
@@ -61,16 +11,29 @@
   import { autoInk, richer, shade } from './vendor/color';
   import { Sim, restPose } from './vendor/engine';
   import { draw, LIGHT_DEFAULTS, OVERSCAN, RISE, type DrawConfig } from './vendor/draw';
-  import {
-    bakesPending,
-    hurry,
-    onLanded,
-    stockLights,
-    takeMissed,
-    warmPlastic,
-    type FurStyle,
-  } from './vendor/plastic';
+  import { bakesPending, hurry, onLanded, takeMissed, warmPlastic, type FurStyle } from './vendor/plastic';
   import { subscribe, pointer } from './vendor/ticker';
+  import {
+    SHOW_WITHIN,
+    bodyPath,
+    nextUid,
+    onThemeChange,
+    partPaths,
+    showReady,
+    waiters,
+  } from './page-state';
+  import {
+    clamp,
+    clampOpt,
+    deviceDpr,
+    hashSeed,
+    lightsFor,
+    pointerStrength,
+    q,
+    reducedMotion,
+    resolveTheme as themeOf,
+    warmIdle,
+  } from './helpers';
 
   type Props = AgentAvatarProps;
 
@@ -83,7 +46,7 @@
     state: botState = 'default',
     size,
     color,
-    ink = '#1E1A33',
+    ink,
     brightness: brightnessProp,
     saturation: saturationProp,
     speed = 1,
@@ -140,20 +103,14 @@
     class: className,
     style,
     'aria-label': ariaLabel,
+    'aria-hidden': ariaHidden,
     onclick: userClick,
     ...rest
   }: Props = $props();
 
-  const clamp = (v: number, lo: number, hi: number) =>
-    Math.min(hi, Math.max(lo, Number.isFinite(v) ? v : 1));
-  const q = (v: number, lo: number, hi: number) => Math.round(clamp(v, lo, hi) * 20) / 20;
-  const clampOpt = (v: number | undefined, d: number, lo: number, hi: number) =>
-    clamp(v ?? d, lo, hi);
   const shapePath = (t: BotAvatarType) => SHAPE_PATHS[t] ?? SHAPE_PATHS.clover;
-  const deviceDpr = () =>
-    Math.min(2, (typeof devicePixelRatio === 'number' && devicePixelRatio) || 1);
 
-  const uid = `ba-${++uidSeq}`;
+  const uid = nextUid();
 
   /* The avatar draws at 75% of its slot so an idle jump has room in the box
      and never clips. A numeric `size` overrides the measurement. */
@@ -205,6 +162,10 @@
   } satisfies FurStyle);
   const material = $derived(shadingMode === 'plastic' || shadingMode === 'fabric');
   const lookKey = $derived(`${shadingMode}|${outlineKey}|${Math.round(drawnSize)}`);
+  /* What the bakes depend on, as strings, so the warm effect re-runs only
+     when one of them changes, not on every prop or every resized pixel. */
+  const warmSize = $derived(Math.round(drawnSize));
+  const furKey = $derived(`${fur.length}|${fur.density}|${fur.fuzz}|${fur.clumps}|${fur.curl}|${fur.gravity}`);
   const interactiveNow = $derived(interactive && !heldPose);
 
   /* Captured once, on purpose: `shown` never returns to false, so a later
@@ -278,19 +239,7 @@
   let holding: (() => void) | null = null;
   const meRef = {};
 
-  function resolveTheme(el: HTMLElement | null): 'dark' | 'light' {
-    if (theme !== 'auto') return theme;
-    const host = el?.closest('[data-theme], .dark, .light') as HTMLElement | null;
-    if (host) {
-      const v = host.getAttribute('data-theme');
-      if (v === 'dark' || v === 'light') return v;
-      if (host.classList.contains('dark')) return 'dark';
-      if (host.classList.contains('light')) return 'light';
-    }
-    return typeof matchMedia === 'function' && matchMedia('(prefers-color-scheme: light)').matches
-      ? 'light'
-      : 'dark';
-  }
+  const resolveTheme = (el: HTMLElement | null) => themeOf(theme, el);
 
   function layoutPx(canvas: HTMLCanvasElement) {
     return canvas.clientWidth / OVERSCAN || cssSize || drawnSize || 64;
@@ -365,6 +314,9 @@
 
   function showWhenBaked(paintNow: () => void) {
     showPaint = paintNow;
+    /* No canvas means nothing was drawn, so nothing could report a missed
+       bake. Calling that ready would skip the fade. */
+    if (!canvasEl) return;
     takeMissed();
     paintNow();
     ready = !takeMissed();
@@ -381,30 +333,13 @@
       });
   }
 
-  function lightsFor(lightAt: number) {
-    const a = (lightAt * Math.PI) / 180;
-    const b = ((backLight ?? 0) * Math.PI) / 180;
-    const lights = stockLights(Math.sin(a), -Math.cos(a));
-    if (backLight !== undefined) [lights.bx, lights.by] = [Math.sin(b), -Math.cos(b)];
-    if (lightFront !== undefined) lights.front = (Math.min(85, Math.max(0, lightFront)) * Math.PI) / 180;
-    return lights;
-  }
-
   function warm() {
     if (!material || !cfg?.path) return;
     const c = cfg;
     const dev = (drawnSize || 64) * deviceDpr();
     const lightAt = c.light ?? 295;
-    warmPlastic(outlineKey, c.path, dev, depth, shadingMode === 'fabric', fur, lightAt, lightsFor(lightAt));
-  }
-
-  function warmIdle(fn: () => void): () => void {
-    if (typeof requestIdleCallback === 'function') {
-      const id = requestIdleCallback(fn);
-      return () => cancelIdleCallback(id);
-    }
-    const id = setTimeout(fn, 1);
-    return () => clearTimeout(id);
+    const lights = lightsFor(lightAt, backLight, lightFront);
+    warmPlastic(outlineKey, c.path, dev, depth, shadingMode === 'fabric', fur, lightAt, lights);
   }
 
   function hold() {
@@ -415,7 +350,7 @@
       if (!holding) return;
       holding();
       holding = null;
-      paint();
+      applyPose();
     };
     const off = onLanded(() => {
       if (!bakesPending()) release();
@@ -471,6 +406,8 @@
   /* Sync the rig with the props on every meaningful change: this is the
      React `useLayoutEffect` (which ran each render) made reactive. */
   $effect(() => {
+    /* Until the slot is measured there's no canvas to draw on. */
+    if (drawnSize <= 0) return;
     if (!sim) sim = new Sim(seedValue, stateKey);
     else sim.setState(stateKey);
     sim.setTurn(clamp(turn, 0, 2));
@@ -513,25 +450,36 @@
     };
   });
 
+  /* Once shown, a paused or reduced-motion avatar draws only when asked, so
+     it repaints here and keeps repainting as its bakes land. */
+  $effect(() => {
+    if (!shown) return;
+    untrack(() => {
+      if (canvasEl && drawnSize > 0) applyPose();
+    });
+  });
+
+  $effect(() => {
+    if (theme !== 'auto') return;
+    return onThemeChange(() => {
+      if (canvasEl && drawnSize > 0) applyPose();
+    });
+  });
+
   /* Start the material's bakes on idle time as soon as the shape is known. */
   $effect(() => {
     void shadingMode;
     void outlineKey;
-    void drawnSize;
+    void warmSize;
     void depth;
     void light;
     void backLight;
     void lightFront;
-    if (!material || !cfg?.path) return;
+    void furKey;
+    if (!material || !warmSize || !untrack(() => cfg?.path)) return;
     return warmIdle(warm);
   });
 
-  function pointerStrength(d: number) {
-    if (d < 1) return 1;
-    if (d > 3) return 0;
-    return 1 - (d - 1) / 2;
-  }
-
   function updatePointer(s: Sim, canvas: HTMLCanvasElement) {
     if (!interactiveNow || Number.isNaN(pointer.x)) {
       s.setPointer(0, 0, 0);
@@ -604,8 +552,10 @@
 
   onMount(() => {
     if (!hostEl) return;
+    /* A hidden parent (a closed tab or panel) reports 0. Keep the last width
+       so the canvas, its picture and its gate survive being hidden. */
     const observer = new ResizeObserver(([entry]) => {
-      if (entry) hostWidth = entry.contentRect.width;
+      if (entry && entry.contentRect.width > 0) hostWidth = entry.contentRect.width;
     });
     observer.observe(hostEl);
     return () => observer.disconnect();
@@ -628,9 +578,12 @@
       data-bot-avatar={type}
       data-face={faceKind}
       data-state={stateKey}
-      role="img"
-      aria-label={ariaLabel ??
-        (name ? `${name}${role ? `, ${role}` : ''}` : `${preset.label} agent, ${stateLabels[stateKey]}`)}
+      role={ariaHidden ? undefined : 'img'}
+      aria-hidden={ariaHidden ? 'true' : undefined}
+      aria-label={ariaHidden
+        ? undefined
+        : (ariaLabel ??
+          (name ? `${name}${role ? `, ${role}` : ''}` : `${preset.label} agent, ${stateLabels[stateKey]}`))}
       style={canvasStyle}
       onclick={handleClick}
       {...rest}

package/src/agents/agent-cast.svelte

@@ -1,6 +1,6 @@
 <script lang="ts">
   import AgentAvatar from './agent-avatar.svelte';
-  import type { Agent } from './types';
+  import type { Agent, AgentState } from './types';
 
   type Props = {
     /** The cast to lay out. */
@@ -32,6 +32,12 @@
 
   const keyOf = (agent: Agent) => agent.id ?? agent.name;
 
+  /* The card under the pointer or focus wakes up and works; the rest idle.
+     A `state` in avatarProps wins. */
+  let awake = $state<string | null>(null);
+  const stateFor = (id: string) =>
+    (avatarProps.state as AgentState | undefined) ?? (awake === id ? 'working' : 'default');
+
   /* Group when any agent asks for one, otherwise a single flat grid. */
   const sections = $derived.by(() => {
     const anyGroup = agents.some((agent) => agent.group);
@@ -72,8 +78,12 @@
             <button
               type="button"
               class="agent-cast__card"
-              aria-current={id === selectedId ? 'true' : undefined}
+              aria-pressed={onSelect ? id === selectedId : undefined}
               onclick={() => onSelect?.(agent)}
+              onpointerenter={() => (awake = id)}
+              onpointerleave={() => awake === id && (awake = null)}
+              onfocus={() => (awake = id)}
+              onblur={() => awake === id && (awake = null)}
             >
               <span class="agent-cast__slot">
                 <AgentAvatar
@@ -81,7 +91,9 @@
                   role={agent.role}
                   shape={agent.shape ?? 'clover'}
                   color={agent.color}
+                  aria-hidden
                   {...avatarProps}
+                  state={stateFor(id)}
                 />
               </span>
               <span class="agent-cast__meta">
@@ -133,11 +145,21 @@
     border-radius: 0.75rem;
     cursor: pointer;
     transition:
-      border-color 0.15s ease,
-      transform 0.15s ease;
+      border-color var(--duration-quick, 150ms) var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1)),
+      transform var(--duration-quick, 150ms) var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
   }
-  .agent-cast__card:hover {
-    border-color: color-mix(in oklab, var(--color-foreground, #18181b) 25%, transparent);
+  @media (prefers-reduced-motion: reduce) {
+    .agent-cast__card {
+      transition: border-color var(--duration-quick, 150ms) linear;
+    }
+    .agent-cast__card:active {
+      transform: none;
+    }
+  }
+  @media (hover: hover) and (pointer: fine) {
+    .agent-cast__card:hover {
+      border-color: color-mix(in oklab, var(--color-foreground, #18181b) 25%, transparent);
+    }
   }
   .agent-cast__card:active {
     transform: scale(0.985);
@@ -146,13 +168,15 @@
     outline: 2px solid var(--color-ring, #6366f1);
     outline-offset: 2px;
   }
-  .agent-cast__card[aria-current='true'] {
+  .agent-cast__card[aria-pressed='true'] {
     border-color: var(--color-accent, #6366f1);
     box-shadow: 0 0 0 1px var(--color-accent, #6366f1);
   }
+  /* Room above the head, so a hop or a hat never meets the card's edge. */
   .agent-cast__slot {
     display: block;
     width: 100%;
+    padding: 0.5rem 0.5rem 0;
   }
   .agent-cast__meta {
     display: flex;

package/src/agents/demo.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
   import AgentAvatar from './agent-avatar.svelte';
   import AgentCast from './agent-cast.svelte';
-  import type { Agent } from './types';
+  import type { Agent, AgentState } from './types';
 
   const cast: Agent[] = [
     { id: 'ada', name: 'Ada', role: 'Researcher', shape: 'clover', color: '#41C4FF', group: 'Research' },
@@ -14,7 +14,14 @@
     { id: 'hal', name: 'Hal', role: 'Watcher', shape: 'star', group: 'Craft' },
   ];
 
+  const states: { value: AgentState; label: string }[] = [
+    { value: 'default', label: 'Idle' },
+    { value: 'working', label: 'Working' },
+    { value: 'sleeping', label: 'Sleeping' },
+  ];
+
   let selected = $state<string | null>('ada');
+  let leadState = $state<AgentState>('working');
   let lead = $derived(cast.find((agent) => agent.id === selected) ?? cast[0]);
 </script>
 
@@ -26,14 +33,25 @@
         role={lead.role}
         shape={lead.shape}
         color={lead.color}
-        state="working"
-        theme="light"
+        state={leadState}
       />
     </div>
     <div class="demo__intro">
       <p class="demo__eyebrow">AgentCast</p>
       <h1 class="demo__title">{lead.name}</h1>
       <p class="demo__role">{lead.role}</p>
+      <div class="demo__states" role="radiogroup" aria-label="State">
+        {#each states as s (s.value)}
+          <button
+            type="button"
+            role="radio"
+            aria-checked={leadState === s.value}
+            onclick={() => (leadState = s.value)}
+          >
+            {s.label}
+          </button>
+        {/each}
+      </div>
     </div>
   </header>
 
@@ -45,9 +63,8 @@
     max-width: 56rem;
     margin: 0 auto;
     padding: 2rem 1.5rem 4rem;
-    font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
-    color: #18181b;
-    background: #fafafa;
+    color: var(--color-foreground, #18181b);
+    background: var(--color-background, #fafafa);
   }
   .demo__hero {
     display: flex;
@@ -64,7 +81,7 @@
     font-size: 0.75rem;
     letter-spacing: 0.14em;
     text-transform: uppercase;
-    color: #71717a;
+    color: var(--color-muted-foreground, #71717a);
   }
   .demo__title {
     margin: 0.25rem 0 0;
@@ -73,6 +90,36 @@
   }
   .demo__role {
     margin: 0.25rem 0 0;
-    color: #52525b;
+    color: var(--color-muted-foreground, #52525b);
+  }
+  .demo__states {
+    display: inline-flex;
+    gap: 0.25rem;
+    margin-top: 0.875rem;
+    padding: 0.1875rem;
+    border-radius: 0.625rem;
+    background: color-mix(in oklab, var(--color-foreground, #18181b) 6%, transparent);
+  }
+  .demo__states button {
+    padding: 0.3125rem 0.75rem;
+    font: inherit;
+    font-size: 0.8125rem;
+    color: var(--color-muted-foreground, #71717a);
+    background: transparent;
+    border: 0;
+    border-radius: 0.4375rem;
+    cursor: pointer;
+    transition:
+      color var(--duration-quick, 150ms) var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1)),
+      background-color var(--duration-quick, 150ms) var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+  }
+  .demo__states button[aria-checked='true'] {
+    color: var(--color-foreground, #18181b);
+    background: var(--color-card, #fff);
+    box-shadow: var(--elev-hairline, 0 0 0 1px rgb(0 0 0 / 0.06));
+  }
+  .demo__states button:focus-visible {
+    outline: 2px solid var(--color-ring, #6366f1);
+    outline-offset: 1px;
   }
 </style>

package/src/agents/helpers.ts

@@ -0,0 +1,58 @@
+/* Pure helpers for the avatar: numbers, theme, lights, idle scheduling. */
+import { stockLights } from './vendor/plastic';
+
+export const clamp = (v: number, lo: number, hi: number) =>
+  Math.min(hi, Math.max(lo, Number.isFinite(v) ? v : 1));
+export const q = (v: number, lo: number, hi: number) => Math.round(clamp(v, lo, hi) * 20) / 20;
+export const clampOpt = (v: number | undefined, d: number, lo: number, hi: number) =>
+  clamp(v ?? d, lo, hi);
+export const deviceDpr = () =>
+  Math.min(2, (typeof devicePixelRatio === 'number' && devicePixelRatio) || 1);
+
+export function hashSeed(id: string): number {
+  let h = 2166136261;
+  for (let i = 0; i < id.length; i++) h = Math.imul(h ^ id.charCodeAt(i), 16777619);
+  return ((h >>> 0) % 1000) / 1000;
+}
+
+export const reducedMotion = (): boolean =>
+  typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+export function resolveTheme(theme: 'auto' | 'dark' | 'light', el: HTMLElement | null): 'dark' | 'light' {
+  if (theme !== 'auto') return theme;
+  const host = el?.closest('[data-theme], .dark, .light') as HTMLElement | null;
+  if (host) {
+    const v = host.getAttribute('data-theme');
+    if (v === 'dark' || v === 'light') return v;
+    if (host.classList.contains('dark')) return 'dark';
+    if (host.classList.contains('light')) return 'light';
+  }
+  return typeof matchMedia === 'function' && matchMedia('(prefers-color-scheme: light)').matches
+    ? 'light'
+    : 'dark';
+}
+
+export function lightsFor(lightAt: number, backLight?: number, lightFront?: number) {
+  const a = (lightAt * Math.PI) / 180;
+  const b = ((backLight ?? 0) * Math.PI) / 180;
+  const lights = stockLights(Math.sin(a), -Math.cos(a));
+  if (backLight !== undefined) [lights.bx, lights.by] = [Math.sin(b), -Math.cos(b)];
+  if (lightFront !== undefined) lights.front = (Math.min(85, Math.max(0, lightFront)) * Math.PI) / 180;
+  return lights;
+}
+
+export function warmIdle(fn: () => void): () => void {
+  if (typeof requestIdleCallback === 'function') {
+    const id = requestIdleCallback(fn);
+    return () => cancelIdleCallback(id);
+  }
+  const id = setTimeout(fn, 1);
+  return () => clearTimeout(id);
+}
+
+/* Full pull up close, fading to nothing by 3 head widths. */
+export function pointerStrength(d: number) {
+  if (d < 1) return 1;
+  if (d > 3) return 0;
+  return 1 - (d - 1) / 2;
+}

package/src/agents/page-state.ts

@@ -0,0 +1,70 @@
+/* What every avatar on the page shares: the batching shown-gate, so a row of
+   them comes in together, the path caches, and one theme watcher. */
+import { bakesPending } from './vendor/plastic';
+
+export const SHOW_WITHIN = 4000;
+export const waiters = new Map<object, { ready: () => boolean; show: () => void }>();
+
+export function showReady() {
+  if (bakesPending()) return;
+  for (const w of waiters.values()) if (!w.ready()) return;
+  const all = [...waiters.values()];
+  waiters.clear();
+  for (const w of all) w.show();
+}
+
+const pathCache = new Map<string, Path2D>();
+export function bodyPath(d: string): Path2D {
+  let p = pathCache.get(d);
+  if (!p) {
+    p = new Path2D(d);
+    pathCache.set(d, p);
+  }
+  return p;
+}
+
+const partsCache = new Map<string, Path2D[]>();
+export function partPaths(d: string): Path2D[] {
+  let p = partsCache.get(d);
+  if (!p) {
+    p = d
+      .split(/(?=M)/)
+      .filter((s) => s.trim())
+      .map((s) => new Path2D(s));
+    partsCache.set(d, p);
+  }
+  return p;
+}
+
+let uidSeq = 0;
+export const nextUid = () => `ba-${++uidSeq}`;
+
+/* One observer for the whole page: a `.dark` or `data-theme` flip on
+   <html> or <body>, or the OS scheme changing, repaints every auto avatar. */
+const themeListeners = new Set<() => void>();
+let themeWatch: (() => void) | null = null;
+export function onThemeChange(fn: () => void): () => void {
+  themeListeners.add(fn);
+  if (!themeWatch && typeof MutationObserver === 'function' && typeof document !== 'undefined') {
+    const fire = () => {
+      for (const l of themeListeners) l();
+    };
+    const mo = new MutationObserver(fire);
+    const opts = { attributes: true, attributeFilter: ['class', 'data-theme'] };
+    mo.observe(document.documentElement, opts);
+    if (document.body) mo.observe(document.body, opts);
+    const mq = typeof matchMedia === 'function' ? matchMedia('(prefers-color-scheme: dark)') : null;
+    mq?.addEventListener('change', fire);
+    themeWatch = () => {
+      mo.disconnect();
+      mq?.removeEventListener('change', fire);
+    };
+  }
+  return () => {
+    themeListeners.delete(fn);
+    if (themeListeners.size === 0 && themeWatch) {
+      themeWatch();
+      themeWatch = null;
+    }
+  };
+}

package/src/agents/types.ts

@@ -61,7 +61,7 @@ export type AgentAvatarProps = Omit<
   shape?: AgentShape;
   /** Face kind. Default `eyes`. */
   face?: BotAvatarFace;
-  /** Face ink. Default `#1E1A33`. */
+  /** Face ink. Default: dark on a light body, light on a dark one. */
   ink?: string;
   /** Rendered size in px. Omit to fill 75% of the slot. */
   size?: number;
@@ -69,4 +69,6 @@ export type AgentAvatarProps = Omit<
   style?: string;
   onclick?: (event: MouseEvent) => void;
   'aria-label'?: string;
+  /** Hide the canvas from assistive tech when a parent already names the agent. */
+  'aria-hidden'?: boolean | 'true' | 'false';
 };