@heyramzi/ui 7.0.0 → 8.1.0

package/COMPONENTS.md

@@ -23,12 +23,12 @@ The style layer lives in [`src/tokens.css`](./src/tokens.css) and the motion CSS
 - `checkbox` — Checkbox
 - `code-block` — CodeBlock. Highlight with `useHighlightedCode` from `@heyramzi/ui/shadcn/hooks/use-highlighted-code.svelte` (Shiki, ANSI too)
 - `collapsible` — Collapsible
-- `command` — Command
+- `command` — Command, computeCommandScore (the scorer, for a custom `filter`)
 - `context-menu` — ContextMenu
 - `dialog` — Dialog
 - `dropdown-menu` — CheckboxGroup, CheckboxItem, Content, Portal, DropdownMenu, DropdownMenuCheckboxGroup
 - `empty` — Empty
-- `field` — Field
+- `field` — Field and its parts, plus SimpleField: label, hint or error and the control, with the message linked by `aria-describedby`
 - `hover-card` — HoverCard
 - `input` — Input
 - `input-otp` — InputOtp
@@ -57,54 +57,66 @@ The style layer lives in [`src/tokens.css`](./src/tokens.css) and the motion CSS
 - `tooltip` — Tooltip
 - `trace` — Trace, an agent's steps: reasoning, tool calls and sources as status rows that can expand
 
+## Components (`src/components`)
+
+Generic pieces built on the primitives, imported from `@heyramzi/ui/components/<name>`.
+
+- `copy` — CopyButton, copyText, copyRichText, htmlToPlainText, Copied
+- `data-table` — SortableHead, Pagination, InfiniteScroll, RowContextMenu, TableSkeleton, and the sort, page and filter helpers
+- `hold-to-confirm` — HoldToConfirm, press and hold to confirm
+- `icon` — Icon, a Phosphor component at a size
+- `language-flag` — LanguageFlag
+- `list-page` — ListPageShell, MasterDetail, GroupedList, RailRow and the rest of the master-detail page kit, NoticeBar, EmptyState, FilterPopover, setSectionHost
+- `locale-switch` — LocaleSwitch, a language switch on SegmentedFilter
+- `mark` — Mark, a logo or photo glyph with an initial fallback
+- `open-in` — OpenIn, a link out to a tool that takes the tool's name, label and mark as a prop
+- `picker` — Picker, MarkPicker, pickerTriggerClass, a command palette at popover scale
+- `segmented` — AnimatedTabs (pill or underline), SegmentedFilter, SegmentedNav, SectionRuns, one bordered track with a sliding pill, a badge note and an overflow menu
+- `star-rating-input` — StarRatingInput
+- `svg` — Svg, an SVG file imported with `?raw`
+
 ## Effects (`src/effects`)
 
+- `interactive-hover-button` — InteractiveHoverButton, a dot that grows into the fill
+
 - `animated-beam` — AnimatedBeam, AnimatedBeamProps, AnchorPosition
 - `border-beam` — BorderBeam
-- `image-comparison` — ImageComparison
+- `image-comparison` — ImageComparison, a before/after wipe with a bindable position, side badges and a hint sweep
 - `image-reveal` — ImageReveal, ImageRevealProps, ImageRevealHandle
 - `magnetic` — magnetic
+- `magic-card` — MagicCard. Props: `glow`, `radius`, `class`, `contentClass`; the glow colour is `--magic-card-glow` set on `class`.
 - `marquee` — Marquee
 - `progressive-blur` — ProgressiveBlur
 - `reveal` — InView, AnimatedGroup, TextEffect, observeInView, RevealPreset, RevealPer
 - `shader-gradient` — ShaderGradient, ShaderGradientProps, ShaderGradientUniforms
 - `spotlight` — Spotlight
-- `theme-toggle` — ThemeToggle, revealTheme. Props: `isDark`, `mode` (`light`, `dark`, `system`; swaps in the Monitor icon), `onToggle`, `variant` (`outline`, `ghost`, `inverted`; `inverted` boolean is an alias), `size`, `label`, `title`, `skipTransition`, `class`. `revealTheme(event, apply, { skip, duration, easing })` is the circular wipe on its own: `import { revealTheme } from "@heyramzi/ui"` (the `./lib/*` subpath points at `.js` and the source is `.ts`).
+- `theme-toggle` — ThemeToggle, revealTheme. Props: `isDark`, `mode` (`light`, `dark`, `system`; swaps in the Monitor icon), `onToggle`, `variant` (`outline`, `ghost`, `inverted`, `slide`; `inverted` boolean is an alias; `slide` is a pill with a moving thumb, coloured by `--theme-toggle-thumb-light`, `--theme-toggle-thumb-dark`, `--theme-toggle-track`, `--theme-toggle-glow` and friends set on `class`), `size`, `label`, `title`, `skipTransition`, `class`. `revealTheme(event, apply, { skip, duration, easing })` is the circular wipe on its own: `import { revealTheme } from "@heyramzi/ui"` (the `./lib/*` subpath points at `.js` and the source is `.ts`).
 
 ## Animations (`src/animations`)
 
-- `accordion` — keyframe utilities
 - `avatar-group-hover` — keyframe utilities
 - `card-tilt` — keyframe utilities
 - `digit-pop-in` — keyframe utilities
 - `dropdown` — keyframe utilities
-- `icon-swap` — keyframe utilities
 - `input-clear-dissolve` — keyframe utilities
 - `input-shake` — keyframe utilities
 - `learn-more-hover` — keyframe utilities
 - `like-button` — keyframe utilities
 - `modal` — keyframe utilities
-- `notification-badge` — keyframe utilities
 - `page-side-by-side` — keyframe utilities
-- `panel` — keyframe utilities
 - `plus-menu-morph` — keyframe utilities
-- `reasoning-stream` — keyframe utilities
 - `resize` — keyframe utilities
 - `shimmer-text` — keyframe utilities
-- `skeleton-reveal` — keyframe utilities
 - `spinning-counter` — keyframe utilities
-- `streaming-text` — keyframe utilities
 - `success-check` — keyframe utilities
-- `tabs-sliding` — keyframe utilities
 - `text-swap` — keyframe utilities
-- `texts-reveal` — keyframe utilities
 - `thinking-states` — keyframe utilities
-- `tooltip` — keyframe utilities
 
 ## AI and chat (`src/ai`)
 
-- `composer` — Composer, ComposerProps
+- `ai-button` — AiButton
 - `confirmation` — Confirmation, ConfirmationTitle, ConfirmationRequest, ConfirmationAccepted, ConfirmationRejected, ConfirmationActions, ConfirmationAction
+- `generation-progress` — GenerationProgress
 - `loading-state` — PixelLoader
 - `prompt-input` — PromptInput, PromptInputBody, PromptInputToolbar, PromptInputTextarea, PromptInputSubmit
 - `reasoning` — Reasoning, ReasoningTrigger, ReasoningContent
@@ -116,7 +128,6 @@ The style layer lives in [`src/tokens.css`](./src/tokens.css) and the motion CSS
 
 ---
 
-Skipped on purpose: brand assets (logos, marks, brand renderer, language flags,
-locale switch), kanban, list, gantt and status (they live in `@heyramzi/tasks`), and charts
+Skipped on purpose: brand assets (logos, marks, brand renderer), kanban, list, gantt and status (they live in `@heyramzi/tasks`), and charts
 (they live in `@heyramzi/charts`). The bot avatars
 are in `src/agents`, imported from `@heyramzi/ui/agents`.

package/README.md

@@ -11,11 +11,12 @@ only a convenience.
 ## What is inside
 
 - `src/shadcn` shadcn-svelte primitives, generalized.
+- `src/components` generic pieces on the primitives: segmented control, picker, copy button, data table, list page, hold to confirm and more.
 - `src/effects` animated borders, beams, marquee, spotlight, image reveal,
   image comparison, shimmer gradients and a theme toggle.
 - `src/animations` keyframe CSS for dropdowns, modals, tooltips, text swaps,
   success checks and the rest of the motion vocabulary.
-- `src/ai` chat and AI surfaces: composer, prompt input, response, reasoning, confirmation and loaders.
+- `src/ai` chat and AI surfaces: prompt input, response, reasoning, confirmation and loaders.
 - `src/agents` bot avatars and a cast grid, imported from `@heyramzi/ui/agents`:
   `AgentAvatar` draws an eyes-only face from a name, role, shape and colour, and
   `AgentCast` lays a list of agents out as cards you can pick from.
@@ -41,6 +42,9 @@ Retheme by overriding any variable on `:root`, for example
 `--color-brand-indigo` or `--radius-lg`. Dark mode keys off a `.dark`
 class on `html`.
 
+Rich text lives in [`@heyramzi/rich-editor`](https://github.com/heyramzi/ui/tree/main/packages/rich-editor),
+so the kit doesn't pull Tiptap into every app.
+
 Charts live in their own package now,
 [`@heyramzi/charts`](https://github.com/heyramzi/ui/tree/main/packages/charts). It reads
 the same tokens, so import `tokens.css` once and both work.
@@ -125,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": "7.0.0",
+  "version": "8.1.0",
   "description": "Svelte 5 UI primitives: effects, animations, and shared component CSS.",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,16 @@
       "default": "./src/index.ts"
     },
     "./tokens.css": "./src/tokens.css",
-    "./lib/*": "./src/lib/*",
+    "./lib/*.js": {
+      "svelte": "./src/lib/*.ts",
+      "types": "./src/lib/*.ts",
+      "default": "./src/lib/*.ts"
+    },
+    "./lib/*": {
+      "svelte": "./src/lib/*.ts",
+      "types": "./src/lib/*.ts",
+      "default": "./src/lib/*.ts"
+    },
     "./border-beam": {
       "svelte": "./src/effects/border-beam/BorderBeam.svelte",
       "default": "./src/effects/border-beam/BorderBeam.svelte"
@@ -55,6 +64,10 @@
       "svelte": "./src/effects/spotlight/Spotlight.svelte",
       "default": "./src/effects/spotlight/Spotlight.svelte"
     },
+    "./effects/magic-card": {
+      "svelte": "./src/effects/magic-card/MagicCard.svelte",
+      "default": "./src/effects/magic-card/MagicCard.svelte"
+    },
     "./effects/marquee": {
       "svelte": "./src/effects/marquee/Marquee.svelte",
       "default": "./src/effects/marquee/Marquee.svelte"
@@ -78,6 +91,10 @@
       "svelte": "./src/effects/progressive-blur/ProgressiveBlur.svelte",
       "default": "./src/effects/progressive-blur/ProgressiveBlur.svelte"
     },
+    "./effects/interactive-hover-button": {
+      "svelte": "./src/effects/interactive-hover-button/InteractiveHoverButton.svelte",
+      "default": "./src/effects/interactive-hover-button/InteractiveHoverButton.svelte"
+    },
     "./effects/image-comparison": {
       "svelte": "./src/effects/image-comparison/ImageComparison.svelte",
       "default": "./src/effects/image-comparison/ImageComparison.svelte"
@@ -115,16 +132,6 @@
     "./animations/*": {
       "default": "./src/animations/*"
     },
-    "./showcase": {
-      "svelte": "./src/showcase/index.ts",
-      "types": "./src/showcase/index.ts",
-      "default": "./src/showcase/index.ts"
-    },
-    "./showcase/kit": {
-      "svelte": "./src/showcase/kit.ts",
-      "types": "./src/showcase/kit.ts",
-      "default": "./src/showcase/kit.ts"
-    },
     "./shadcn/hooks/*": {
       "svelte": "./src/shadcn/hooks/*.ts",
       "types": "./src/shadcn/hooks/*.ts",
@@ -135,6 +142,11 @@
       "types": "./src/shadcn/*/index.ts",
       "default": "./src/shadcn/*/index.ts"
     },
+    "./components/*": {
+      "svelte": "./src/components/*/index.ts",
+      "types": "./src/components/*/index.ts",
+      "default": "./src/components/*/index.ts"
+    },
     "./shadcn/utilities.css": {
       "style": "./src/shadcn/utilities.css",
       "default": "./src/shadcn/utilities.css"
@@ -158,18 +170,16 @@
   },
   "dependencies": {
     "@heyramzi/utils": "^1.3.3",
-    "@lucide/svelte": "^1.52.0",
     "@shadcn-svelte/primitives": "^0.0.1",
-    "clsx": "^2.1.1",
     "marked": "^18.1.0",
     "phosphor-svelte": "^3.1.0",
     "shiki": "^4.5.0",
-    "tailwind-merge": "^3.7.0",
     "tailwind-variants": "^3.3.1"
   },
   "devDependencies": {
     "@internationalized/date": "^3.12.4",
     "@sveltejs/vite-plugin-svelte": "^7.3.1",
+    "@types/node": "^26.6.4",
     "bits-ui": "^2.19.5",
     "jsdom": "^30.1.2",
     "mode-watcher": "^1.1.0",

package/scripts/sync-shadcn.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/* Sync shadcn-svelte into src/shadcn and its demos into the showcase, three-way
+/* Sync shadcn-svelte into src/shadcn and its demos into the site, three-way
  * per file against `.upstream/`. The rules and why: ../docs/decisions.md. */
 
 //   pnpm sync:shadcn          fetch, vendor, apply, report
@@ -8,7 +8,7 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { basename, dirname, resolve } from "node:path";
+import { basename, dirname, relative, resolve } from "node:path";
 import {
   CHECK,
   classify,
@@ -56,16 +56,16 @@ const REROUTE = {
 
 const DOCS = "https://raw.githubusercontent.com/huntabyte/shadcn-svelte/main/docs";
 const DEMO_VENDOR = `${PKG}/.upstream/shadcn-demos`;
-const DEMO_LOCAL = `${PKG}/src/showcase/demos/shadcn`;
+const DEMO_LOCAL = `${ROOT}/site/src/lib/shadcn-demos`;
 const DEMO_MANIFEST = `${DEMO_LOCAL}/index.ts`;
 
 /* The docs site's aliases. A demo is a docs file, not a registry payload, so it
  * carries `$lib/...` rather than the registry's `$UI$`. */
 const DEMO_ALIASES = [
-  ["$lib/registry/ui/", "../src/shadcn"],
+  ["$lib/registry/ui/", "@heyramzi/ui/shadcn/"],
   // A handful reach their neighbour by relative path instead of the alias.
-  ["../ui/", "../src/shadcn"],
-  ["$lib/registry/hooks/", "../src/shadcn/hooks"],
+  ["../ui/", "@heyramzi/ui/shadcn/"],
+  ["$lib/registry/hooks/", "@heyramzi/ui/shadcn/hooks/"],
   ["$lib/utils.js", "@heyramzi/utils"],
   // The peer here is the runes build, published under its own name.
   ["@tabler/icons-svelte/", "@tabler/icons-svelte-runes/"],
@@ -107,12 +107,16 @@ const NO_DEMO = new Set([
 ]);
 
 const adapt = (text) => ALIASES.reduce((acc, [from, to]) => acc.replaceAll(from, to), text);
+/* The site imports the kit the way a consumer does, so the exports map names a
+ * primitive without its `/index.js` and a hook without its `.js`. */
 const adaptDemo = (text) =>
-  DEMO_ALIASES.reduce((acc, [from, to]) => acc.replaceAll(from, to), text);
+  DEMO_ALIASES.reduce((acc, [from, to]) => acc.replaceAll(from, to), text)
+    .replace(/(@heyramzi\/ui\/shadcn\/[a-z-]+)\/index\.js/g, "$1")
+    .replace(/(@heyramzi\/ui\/shadcn\/hooks\/[a-z-]+(?:\.svelte)?)\.js/g, "$1");
 const readIf = (path) => (existsSync(path) ? readFileSync(path, "utf8") : null);
 const route = (name, target) => `${PKG}/${REROUTE[`${name}/${target}`] ?? `src/shadcn/${target}`}`;
 /** Report a file by where it lives here, not by its upstream target. */
-const label = (path) => path.slice(PKG.length + 1);
+const label = (path) => (path.startsWith(`${PKG}/`) ? path.slice(PKG.length + 1) : relative(ROOT, path));
 
 const pascal = (name) => name.replace(/(^|-)([a-z])/g, (_, __, c) => c.toUpperCase());
 
@@ -127,10 +131,10 @@ const meta = (doc, name) => {
   return { title: field("title") ?? pascal(name), note: field("description") ?? "" };
 };
 
-/** The demo's own shadcn imports, respelled as a consumer writes them. */
+/** The demo's own shadcn imports, as it spells them for a consumer. */
 const publicImports = (demo) =>
-  [...demo.matchAll(/import[^;]*?from\s+"#src\/shadcn\/([^"]+?)(?:\/index\.js)?";/g)]
-    .map((m) => m[0].replace(/"[^"]+"/, `"@heyramzi/ui/shadcn/${m[1]}"`))
+  [...demo.matchAll(/import[^;]*?from\s+"@heyramzi\/ui\/shadcn\/[^"]+";/g)]
+    .map((m) => m[0])
     .join("\n");
 
 /* The section's list, generated: a primitive reaches the page by being synced,
@@ -145,7 +149,7 @@ async function writeManifest(demos) {
     " * own, and the sync rewrites this list. */",
     'import type { Component } from "svelte";',
     ...demos.map(
-      (d) => `import ${pascal(d.name)}Demo from "../src/showcase/demos/shadcn/${d.name}.svelte";`,
+      (d) => `import ${pascal(d.name)}Demo from "./${d.name}.svelte";`,
     ),
     "",
     "export type ShadcnDemo = {",
@@ -267,7 +271,7 @@ const ours = readdirSync(LOCAL, { withFileTypes: true })
 for (const name of ours) buckets.unported.push(`${name} — in src/shadcn, not in the registry`);
 
 /* The docs site's own demo for each primitive, vendored on the same three-way
- * rule. Upstream writes them; the showcase renders them. */
+ * rule. Upstream writes them; the site renders them. */
 const demoNames = [...Object.keys(entries), ...LOCAL_ONLY]
   .filter((name) => !NO_DEMO.has(name))
   .toSorted();

package/scripts/sync-transitions.mjs

@@ -46,7 +46,7 @@ const SRC = `${PKG}/src`;
  */
 
 /*
- * Most land in src/animations. Five do not, because a component already did the job and one behaviour gets one implementation: the last five entries name where each went instead.
+ * Fourteen of these name the component that owns the motion instead of a file in src/animations.
  */
 
 /*
@@ -55,31 +55,31 @@ const SRC = `${PKG}/src`;
 const PORTED = {
   "card-resize": "animations/resize.css",
   "number-pop-in": "animations/digit-pop-in.css",
-  "notification-badge": "animations/notification-badge.css",
+  "notification-badge": "shadcn/badge/badge.svelte",
   "text-states-swap": "animations/text-swap.css",
   "menu-dropdown": "animations/dropdown.css",
   "modal-open-close": "animations/modal.css",
-  "panel-reveal": "animations/panel.css",
+  "panel-reveal": "shadcn/sheet/sheet-content.svelte",
   "page-side-by-side": "animations/page-side-by-side.css",
-  "icon-swap": "animations/icon-swap.css",
+  "icon-swap": "effects/theme-toggle/ThemeToggle.svelte",
   "success-check": "animations/success-check.css",
   "avatar-group-hover": "animations/avatar-group-hover.css",
   "error-state-shake": "animations/input-shake.css",
   "input-clear-with-dissolve": "animations/input-clear-dissolve.css",
-  "skeleton-loader-and-reveal": "animations/skeleton-reveal.css",
-  "texts-reveal": "animations/texts-reveal.css",
-  "tabs-sliding": "animations/tabs-sliding.css",
+  "skeleton-loader-and-reveal": "shadcn/skeleton/skeleton.svelte",
+  "texts-reveal": "effects/reveal/TextEffect.svelte",
+  "tabs-sliding": "shadcn/tabs/tabs-list.svelte",
   "shimmer-text": "animations/shimmer-text.css",
-  "tooltip-open-close": "animations/tooltip.css",
+  "tooltip-open-close": "shadcn/tooltip/tooltip-content.svelte",
   "3d-tilt": "animations/card-tilt.css",
   "dropdown-menu-morph": "animations/plus-menu-morph.css",
-  accordion: "animations/accordion.css",
+  accordion: "shadcn/accordion/accordion-content.svelte",
   "like-button": "animations/like-button.css",
   "learn-more-hover": "animations/learn-more-hover.css",
   "spinning-counter": "animations/spinning-counter.css",
   "thinking-states": "animations/thinking-states.css",
-  "reasoning-stream": "animations/reasoning-stream.css",
-  "streaming-text": "animations/streaming-text.css",
+  "reasoning-stream": "ai/reasoning/ReasoningContent.svelte",
+  "streaming-text": "effects/reveal/TextEffect.svelte",
   toggle: "shadcn/switch/switch.svelte",
   "checkbox-check": "shadcn/checkbox/checkbox.svelte",
   "toast-open-close": "shadcn/sonner/sonner.svelte",

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}