@heyramzi/ui 0.0.0-stage → 1.53.1

package/src/agents/agent-cast.svelte

@@ -0,0 +1,197 @@
+<script lang="ts">
+  import AgentAvatar from './agent-avatar.svelte';
+  import type { Agent, AgentState } from './types.js';
+
+  interface Props {
+    /** The cast to lay out. */
+    agents: Agent[];
+    /** Selected agent id, when the cast is a picker. */
+    selectedId?: string | null;
+    /** Called with the agent that was picked. */
+    onSelect?: (agent: Agent) => void;
+    /** Hide the role line under each name. */
+    showRole?: boolean;
+    /** Extra props forwarded to every `<AgentAvatar>`. */
+    avatarProps?: Record<string, unknown>;
+    /** Minimum card width, any CSS length. Controls the column count. */
+    minColumn?: string;
+    class?: string;
+    style?: string;
+  };
+
+  let {
+    agents,
+    selectedId = null,
+    onSelect,
+    showRole = true,
+    avatarProps = {},
+    minColumn = '8.5rem',
+    class: className,
+    style,
+  }: Props = $props();
+
+  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);
+    if (!anyGroup) return [{ label: '', items: agents }];
+    const order: string[] = [];
+    const byGroup = new Map<string, Agent[]>();
+    for (const agent of agents) {
+      const label = agent.group ?? '';
+      let list = byGroup.get(label);
+      if (!list) {
+        list = [];
+        byGroup.set(label, list);
+        order.push(label);
+      }
+      list.push(agent);
+    }
+    return order.map((label) => ({ label, items: byGroup.get(label) ?? [] }));
+  });
+
+  const rootStyle = $derived(
+    `--agent-cast-min:${minColumn};${style ?? ''}`,
+  );
+</script>
+
+<div
+  class={className ? `agent-cast ${className}` : 'agent-cast'}
+  style={rootStyle}
+>
+  {#each sections as section, s (section.label || `flat-${s}`)}
+    <section class="agent-cast__section">
+      {#if section.label}
+        <h3 class="agent-cast__heading">{section.label}</h3>
+      {/if}
+      <ul class="agent-cast__grid">
+        {#each section.items as agent (keyOf(agent))}
+          {@const id = keyOf(agent)}
+          <li>
+            <button
+              type="button"
+              class="agent-cast__card"
+              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
+                  name={agent.name}
+                  role={agent.role}
+                  shape={agent.shape ?? 'clover'}
+                  color={agent.color}
+                  aria-hidden
+                  {...avatarProps}
+                  state={stateFor(id)}
+                />
+              </span>
+              <span class="agent-cast__meta">
+                <span class="agent-cast__name">{agent.name}</span>
+                {#if showRole && agent.role}
+                  <span class="agent-cast__role">{agent.role}</span>
+                {/if}
+              </span>
+            </button>
+          </li>
+        {/each}
+      </ul>
+    </section>
+  {/each}
+</div>
+
+<style>
+  .agent-cast {
+    width: 100%;
+    color: var(--color-foreground, #18181b);
+  }
+  .agent-cast__section + .agent-cast__section {
+    margin-top: 2rem;
+  }
+  .agent-cast__heading {
+    margin: 0 0 0.75rem;
+    font-size: 0.9375rem;
+    font-weight: 600;
+    letter-spacing: -0.015em;
+  }
+  .agent-cast__grid {
+    display: grid;
+    gap: 0.75rem;
+    grid-template-columns: repeat(auto-fill, minmax(var(--agent-cast-min, 8.5rem), 1fr));
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .agent-cast__card {
+    display: flex;
+    flex-direction: column;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    padding: 0;
+    text-align: left;
+    background: var(--color-card, #fff);
+    border: 1px solid var(--color-border, #e4e4e7);
+    border-radius: 0.75rem;
+    cursor: pointer;
+    transition:
+      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));
+  }
+  @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);
+  }
+  .agent-cast__card:focus-visible {
+    outline: 2px solid var(--color-ring, #6366f1);
+    outline-offset: 2px;
+  }
+  .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;
+    flex-direction: column;
+    gap: 0.125rem;
+    padding: 0.625rem;
+  }
+  .agent-cast__name {
+    font-size: 0.8125rem;
+    font-weight: 500;
+    line-height: 1.2;
+  }
+  .agent-cast__role {
+    font-size: 0.75rem;
+    line-height: 1.3;
+    color: var(--color-muted-foreground, #71717a);
+  }
+</style>

package/src/agents/demo.svelte

@@ -0,0 +1,125 @@
+<script lang="ts">
+  import AgentAvatar from './agent-avatar.svelte';
+  import AgentCast from './agent-cast.svelte';
+  import type { Agent, AgentState } from './types.js';
+
+  const cast: Agent[] = [
+    { id: 'ada', name: 'Ada', role: 'Researcher', shape: 'clover', color: '#41C4FF', group: 'Research' },
+    { id: 'bo', name: 'Bo', role: 'Analyst', shape: 'flower', group: 'Research' },
+    { id: 'cy', name: 'Cy', role: 'Planner', shape: 'mech', group: 'Planning' },
+    { id: 'dia', name: 'Dia', role: 'Scheduler', shape: 'droid', group: 'Planning' },
+    { id: 'eli', name: 'Eli', role: 'Writer', shape: 'cat', group: 'Craft' },
+    { id: 'fen', name: 'Fen', role: 'Editor', shape: 'pill', group: 'Craft' },
+    { id: 'gus', name: 'Gus', role: 'Runner', shape: 'ghost', group: 'Craft' },
+    { 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>
+
+<div class="demo">
+  <header class="demo__hero">
+    <div class="demo__portrait">
+      <AgentAvatar
+        name={lead.name}
+        role={lead.role}
+        shape={lead.shape}
+        color={lead.color}
+        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>
+
+  <AgentCast agents={cast} selectedId={selected} onSelect={(agent) => (selected = agent.id ?? agent.name)} />
+</div>
+
+<style>
+  .demo {
+    max-width: 56rem;
+    margin: 0 auto;
+    padding: 2rem 1.5rem 4rem;
+    color: var(--color-foreground, #18181b);
+    background: var(--color-background, #fafafa);
+  }
+  .demo__hero {
+    display: flex;
+    align-items: center;
+    gap: 1.5rem;
+    margin-bottom: 2.5rem;
+  }
+  .demo__portrait {
+    flex: none;
+    width: 9rem;
+  }
+  .demo__eyebrow {
+    margin: 0;
+    font-size: 0.75rem;
+    letter-spacing: 0.14em;
+    text-transform: uppercase;
+    color: var(--color-muted-foreground, #71717a);
+  }
+  .demo__title {
+    margin: 0.25rem 0 0;
+    font-size: 2.25rem;
+    letter-spacing: -0.03em;
+  }
+  .demo__role {
+    margin: 0.25rem 0 0;
+    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.js';
+
+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/index.ts

@@ -0,0 +1,11 @@
+export { default as AgentAvatar } from './agent-avatar.svelte';
+export { default as AgentCast } from './agent-cast.svelte';
+export type { Agent, AgentAvatarProps, AgentShape } from './types.js';
+export {
+  agentPresets,
+  agentShapes,
+  agentFaces,
+  agentStates,
+  agentPalette,
+  agentStateLabels,
+} from './types.js';

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.js';
+
+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

@@ -0,0 +1,74 @@
+import type { BotAvatarFace, BotAvatarProps, BotAvatarType } from './vendor/types.js';
+
+/** The body shapes an agent can be drawn as. */
+export type AgentShape = BotAvatarType;
+
+export type {
+  BotAvatarFace as AgentFace,
+  BotAvatarState as AgentState,
+  BotAvatarShading as AgentShading,
+  BotAvatarSquashEase as AgentSquashEase,
+  BotAvatarHat as AgentHat,
+  BotAvatarGlasses as AgentGlasses,
+  BotAvatarPreset as AgentPreset,
+} from './vendor/types.js';
+
+export {
+  botAvatarPresets as agentPresets,
+  botAvatarTypes as agentShapes,
+  botAvatarFaces as agentFaces,
+  botAvatarStates as agentStates,
+  botAvatarPalette as agentPalette,
+  stateLabels as agentStateLabels,
+} from './vendor/presets.js';
+
+/** One member of a cast: a name, a role, and the face they draw. */
+export type Agent = {
+  /** Stable key. Falls back to `name` when missing. */
+  id?: string;
+  /** Display name. */
+  name: string;
+  /** What they do. Shown under the name, read out with it. */
+  role?: string;
+  /** Body shape. Defaults to the avatar's own. */
+  shape?: AgentShape;
+  /** Body colour. Defaults to the shape's palette colour. */
+  color?: string;
+  /** Optional section heading. Agents sharing a group render together. */
+  group?: string;
+};
+
+/* The vendored props carry an open `Record<string, unknown>` index signature
+   so the canvas can forward loose attributes. Strip it before Omit, otherwise
+   every named prop collapses to `unknown`. */
+type KnownProps<T> = {
+  [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
+};
+
+/**
+ * Props for `<AgentAvatar>`. Every engine prop from the bot avatar is
+ * available; `shape`, `color`, `name` and `role` are the plain ones.
+ */
+export type AgentAvatarProps = Omit<
+  KnownProps<BotAvatarProps>,
+  'type' | 'face' | 'ink' | 'size' | 'className' | 'style'
+> & {
+  /** Display name, for the default aria-label. */
+  name?: string;
+  /** What the agent does, read out with the name. */
+  role?: string;
+  /** Body shape. Default `clover`. */
+  shape?: AgentShape;
+  /** Face kind. Default `eyes`. */
+  face?: BotAvatarFace;
+  /** 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;
+  class?: string;
+  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';
+};

package/src/agents/vendor/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jakub Antalik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.