@adea-ai/ui 0.84.0 → 0.87.0

package/dist/r/src/components/layout/floating-preview/model.ts

@@ -0,0 +1,285 @@
+/*
+ * Copyright (c) 2026 Adea contributors
+ * SPDX-License-Identifier: MIT
+ * Geometry translated from t3code apps/web/src/components/preview/
+ * previewMiniPlayerLayout.ts, issue #422, revision
+ * 77bca8b2d76a1f42552e5eee7d277fcb1160347a (MIT). Runtime and device
+ * behavior are excluded. See NOTICE.
+ */
+
+export const PREVIEW_MINI_PLAYER_EDGE_GAP = 12
+export const PREVIEW_MINI_PLAYER_CORNER_RADIUS = 12
+export interface PreviewMiniPlayerSize {
+  readonly width: number
+  readonly height: number
+}
+export interface PreviewMiniPlayerPosition {
+  readonly x: number
+  readonly y: number
+}
+export interface PreviewMiniPlayerFrame extends PreviewMiniPlayerPosition, PreviewMiniPlayerSize {}
+
+export type BrowserViewportResizeDirection =
+  | 'north'
+  | 'south'
+  | 'east'
+  | 'west'
+  | 'northwest'
+  | 'northeast'
+  | 'southwest'
+  | 'southeast'
+
+const PREVIEW_MINI_PLAYER_DEFAULT_BOX = { width: 320, height: 320 } as const
+const PREVIEW_MINI_PLAYER_MIN_SIZE = { width: 240, height: 150 } as const
+
+interface HorizontalSpan {
+  readonly left: number
+  readonly right: number
+}
+
+/**
+ * The composer stack docked to the bottom edge, in container coordinates. It
+ * only reserves the columns it covers, so the margins beside it stay open all
+ * the way down.
+ */
+export interface PreviewMiniPlayerObstacles {
+  readonly composer: (HorizontalSpan & { readonly height: number }) | null
+}
+
+export const NO_PREVIEW_MINI_PLAYER_OBSTACLES: PreviewMiniPlayerObstacles = { composer: null }
+
+const spanOf = (x: number, width: number): HorizontalSpan => ({ left: x, right: x + width })
+
+const spansOverlap = (a: HorizontalSpan, b: HorizontalSpan) => a.left < b.right && a.right > b.left
+
+/** The lowest row (before the edge gap) open to a player covering these columns. */
+function floorFor(
+  span: HorizontalSpan,
+  container: PreviewMiniPlayerSize,
+  obstacles: PreviewMiniPlayerObstacles
+): number {
+  const { composer } = obstacles
+  return composer && spansOverlap(span, composer)
+    ? container.height - Math.max(0, composer.height)
+    : container.height
+}
+
+/**
+ * The box a stored size is fitted into. A player with a position keeps the
+ * rows its own columns have, so a tall frame parked beside the composer
+ * survives the next layout pass; without one it takes the rows above the
+ * composer, which every column has.
+ */
+const availableArea = (
+  container: PreviewMiniPlayerSize,
+  obstacles: PreviewMiniPlayerObstacles,
+  span: HorizontalSpan | null
+): PreviewMiniPlayerSize => ({
+  width: container.width - PREVIEW_MINI_PLAYER_EDGE_GAP * 2,
+  height:
+    (span
+      ? floorFor(span, container, obstacles)
+      : container.height - Math.max(0, obstacles.composer?.height ?? 0)) -
+    PREVIEW_MINI_PLAYER_EDGE_GAP * 2,
+})
+
+/**
+ * Width is the player's only free dimension; height always follows the source
+ * aspect ratio so the content fills the box without letterboxing. The player
+ * never grows past the source's own size, and a tight container wins over the
+ * minimum.
+ */
+function fitPreviewMiniPlayerWidth(
+  desiredWidth: number,
+  source: PreviewMiniPlayerSize,
+  max: PreviewMiniPlayerSize
+): PreviewMiniPlayerSize {
+  const aspectRatio = source.width / source.height
+  const width = Math.min(
+    Math.max(
+      desiredWidth,
+      PREVIEW_MINI_PLAYER_MIN_SIZE.width,
+      PREVIEW_MINI_PLAYER_MIN_SIZE.height * aspectRatio
+    ),
+    source.width,
+    Math.max(1, max.width),
+    Math.max(1, max.height * aspectRatio)
+  )
+  return { width: Math.round(width), height: Math.round(width / aspectRatio) }
+}
+
+function defaultPreviewMiniPlayerWidth(source: PreviewMiniPlayerSize): number {
+  return Math.min(
+    PREVIEW_MINI_PLAYER_DEFAULT_BOX.width,
+    (PREVIEW_MINI_PLAYER_DEFAULT_BOX.height * source.width) / source.height
+  )
+}
+
+const clampToContainer = (
+  position: PreviewMiniPlayerPosition,
+  container: PreviewMiniPlayerSize,
+  player: PreviewMiniPlayerSize,
+  bottom = container.height
+): PreviewMiniPlayerPosition => ({
+  x: Math.min(
+    Math.max(position.x, PREVIEW_MINI_PLAYER_EDGE_GAP),
+    Math.max(
+      PREVIEW_MINI_PLAYER_EDGE_GAP,
+      container.width - player.width - PREVIEW_MINI_PLAYER_EDGE_GAP
+    )
+  ),
+  y: Math.min(
+    Math.max(position.y, PREVIEW_MINI_PLAYER_EDGE_GAP),
+    Math.max(PREVIEW_MINI_PLAYER_EDGE_GAP, bottom - player.height - PREVIEW_MINI_PLAYER_EDGE_GAP)
+  ),
+})
+
+const overlapsObstacle = (
+  position: PreviewMiniPlayerPosition,
+  player: PreviewMiniPlayerSize,
+  container: PreviewMiniPlayerSize,
+  obstacles: PreviewMiniPlayerObstacles
+): boolean =>
+  position.y + player.height > floorFor(spanOf(position.x, player.width), container, obstacles)
+
+/**
+ * Keeps the player inside the container and off the composer. An overlapping
+ * player is pushed out along whichever side needs the smaller move, so a drag
+ * slides along the composer into the margin beside it instead of stopping at
+ * its top edge; when no side leaves it fully clear it sits above the composer.
+ */
+export function clampPreviewMiniPlayerPosition(
+  position: PreviewMiniPlayerPosition,
+  container: PreviewMiniPlayerSize,
+  player: PreviewMiniPlayerSize,
+  obstacles: PreviewMiniPlayerObstacles = NO_PREVIEW_MINI_PLAYER_OBSTACLES
+): PreviewMiniPlayerPosition {
+  const inside = clampToContainer(position, container, player)
+  const { composer } = obstacles
+  if (!composer || !overlapsObstacle(inside, player, container, obstacles)) return inside
+  const gap = PREVIEW_MINI_PLAYER_EDGE_GAP
+  const above = { x: inside.x, y: container.height - composer.height - gap - player.height }
+  const beside = [
+    { x: composer.left - gap - player.width, y: inside.y },
+    { x: composer.right + gap, y: inside.y },
+  ]
+  let best = clampToContainer(above, container, player)
+  let bestDistance = Math.abs(best.y - inside.y)
+  for (const candidate of beside) {
+    const clamped = clampToContainer(candidate, container, player)
+    if (clamped.x !== candidate.x || overlapsObstacle(candidate, player, container, obstacles)) {
+      continue
+    }
+    const distance = Math.abs(candidate.x - inside.x)
+    if (distance < bestDistance) {
+      best = candidate
+      bestDistance = distance
+    }
+  }
+  return best
+}
+
+/**
+ * Resolves the on-screen frame from the stored width and position. Clamping
+ * happens here on every layout pass instead of being written back to the
+ * store, so a temporarily narrow container never destroys the user's chosen
+ * width. A player without a position sits in the top-right corner.
+ */
+export function resolvePreviewMiniPlayerFrame(input: {
+  readonly width: number | null
+  readonly position: PreviewMiniPlayerPosition | null
+  readonly source: PreviewMiniPlayerSize
+  readonly container: PreviewMiniPlayerSize
+  readonly obstacles?: PreviewMiniPlayerObstacles
+}): PreviewMiniPlayerFrame {
+  const { width, position, source, container, obstacles = NO_PREVIEW_MINI_PLAYER_OBSTACLES } = input
+  const size = fitPreviewMiniPlayerWidth(
+    width ?? defaultPreviewMiniPlayerWidth(source),
+    source,
+    availableArea(container, obstacles, position && width ? spanOf(position.x, width) : null)
+  )
+  const anchored = position ?? {
+    x: container.width - PREVIEW_MINI_PLAYER_EDGE_GAP - size.width,
+    y: PREVIEW_MINI_PLAYER_EDGE_GAP,
+  }
+  return { ...clampPreviewMiniPlayerPosition(anchored, container, size, obstacles), ...size }
+}
+
+/**
+ * Resizes from any edge or corner while holding the aspect ratio. The edge
+ * opposite the dragged one stays anchored, so growth stops at the container
+ * on that axis and the pointer keeps tracking the grabbed edge.
+ */
+export function resizePreviewMiniPlayer(input: {
+  readonly start: PreviewMiniPlayerFrame
+  readonly direction: BrowserViewportResizeDirection
+  readonly delta: PreviewMiniPlayerPosition
+  readonly source: PreviewMiniPlayerSize
+  readonly container: PreviewMiniPlayerSize
+  readonly obstacles?: PreviewMiniPlayerObstacles
+}): PreviewMiniPlayerFrame {
+  const {
+    start,
+    direction,
+    delta,
+    source,
+    container,
+    obstacles = NO_PREVIEW_MINI_PLAYER_OBSTACLES,
+  } = input
+  const east = direction.includes('east')
+  const west = direction.includes('west')
+  const north = direction.includes('north')
+  const south = direction.includes('south')
+  const right = start.x + start.width
+  const bottom = start.y + start.height
+  const floor = floorFor(spanOf(start.x, start.width), container, obstacles)
+  const max = {
+    width: west
+      ? right - PREVIEW_MINI_PLAYER_EDGE_GAP
+      : east
+        ? container.width - PREVIEW_MINI_PLAYER_EDGE_GAP - start.x
+        : container.width - PREVIEW_MINI_PLAYER_EDGE_GAP * 2,
+    height: north
+      ? bottom - PREVIEW_MINI_PLAYER_EDGE_GAP
+      : south
+        ? floor - PREVIEW_MINI_PLAYER_EDGE_GAP - start.y
+        : floor - PREVIEW_MINI_PLAYER_EDGE_GAP * 2,
+  }
+  const desiredWidth = start.width + (east ? delta.x : west ? -delta.x : 0)
+  const desiredHeight = start.height + (south ? delta.y : north ? -delta.y : 0)
+  const horizontal = east || west
+  const vertical = north || south
+  const widthLeads =
+    horizontal && !vertical
+      ? true
+      : vertical && !horizontal
+        ? false
+        : Math.abs(desiredWidth - start.width) / start.width >=
+          Math.abs(desiredHeight - start.height) / start.height
+  const size = fitPreviewMiniPlayerWidth(
+    widthLeads ? desiredWidth : (desiredHeight * source.width) / source.height,
+    source,
+    max
+  )
+  const position = clampPreviewMiniPlayerPosition(
+    { x: west ? right - size.width : start.x, y: north ? bottom - size.height : start.y },
+    container,
+    size,
+    obstacles
+  )
+  return { ...position, ...size }
+}
+
+// Product-neutral names for new consumers. The PreviewMiniPlayer names stay
+// exported for Adea Dev Runtime's existing browser model API.
+export type FloatingPreviewSize = PreviewMiniPlayerSize
+export type FloatingPreviewPosition = PreviewMiniPlayerPosition
+export type FloatingPreviewFrame = PreviewMiniPlayerFrame
+export type FloatingPreviewResizeDirection = BrowserViewportResizeDirection
+export type FloatingPreviewObstacles = PreviewMiniPlayerObstacles
+export const FLOATING_PREVIEW_EDGE_GAP = PREVIEW_MINI_PLAYER_EDGE_GAP
+export const FLOATING_PREVIEW_CORNER_RADIUS = PREVIEW_MINI_PLAYER_CORNER_RADIUS
+export const NO_FLOATING_PREVIEW_OBSTACLES = NO_PREVIEW_MINI_PLAYER_OBSTACLES
+export const resolveFloatingPreviewFrame = resolvePreviewMiniPlayerFrame
+export const resizeFloatingPreview = resizePreviewMiniPlayer
+export const clampFloatingPreviewPosition = clampPreviewMiniPlayerPosition

package/dist/r/src/components/theme/index.ts

@@ -20,3 +20,4 @@ export {
   type ThemeSelection,
 } from './theme-provider'
 export { ThemeToggle, type ThemeToggleProps } from './theme-toggle'
+export { ThemeModeToggle, type ThemeModeToggleProps } from './theme-mode-toggle'

package/dist/r/src/components/theme/theme-mode-toggle.tsx

@@ -0,0 +1,56 @@
+import { Monitor, Moon, Sun } from 'lucide-solid'
+import type { ComponentProps } from 'solid-js'
+import { For, splitProps } from 'solid-js'
+import { ToggleGroup, ToggleGroupItem } from '../ui/toggle-group/toggle-group'
+import { Tooltip, TooltipContent, TooltipTrigger } from '../ui/tooltip'
+
+const APPEARANCES = [
+  { value: 'light', label: 'Light', icon: Sun },
+  { value: 'dark', label: 'Dark', icon: Moon },
+  { value: 'system', label: 'System', icon: Monitor },
+] as const
+
+/** Controlled appearance selection for hosts that own their preference storage. */
+export type ThemeModeToggleProps = Omit<
+  ComponentProps<typeof ToggleGroup>,
+  'children' | 'value' | 'onChange' | 'multiple'
+> & {
+  mode: 'light' | 'dark' | 'system'
+  onModeChange: (mode: 'light' | 'dark' | 'system') => void
+  withLabels?: boolean
+}
+
+export function ThemeModeToggle(props: ThemeModeToggleProps) {
+  const [local, rest] = splitProps(props, ['mode', 'onModeChange', 'withLabels'])
+  return (
+    <ToggleGroup
+      {...rest}
+      attached
+      multiple={false}
+      value={local.mode}
+      onChange={(value: string | null) => {
+        const option = APPEARANCES.find((candidate) => candidate.value === value)
+        if (option) local.onModeChange(option.value)
+      }}
+      aria-label={rest['aria-label'] ?? 'Appearance'}
+    >
+      <For each={APPEARANCES}>
+        {(appearance) => (
+          <Tooltip>
+            <TooltipTrigger
+              as={ToggleGroupItem}
+              value={appearance.value}
+              variant="outline"
+              size={local.withLabels ? 'sm' : 'icon-sm'}
+              aria-label={appearance.label}
+            >
+              <appearance.icon aria-hidden="true" />
+              {local.withLabels ? <span>{appearance.label}</span> : null}
+            </TooltipTrigger>
+            <TooltipContent>Use {appearance.label.toLowerCase()} appearance</TooltipContent>
+          </Tooltip>
+        )}
+      </For>
+    </ToggleGroup>
+  )
+}

package/dist/r/src/components/ui/checkbox/checkbox.tsx

@@ -2,6 +2,7 @@ import { Checkbox as KobalteCheckbox } from '@kobalte/core/checkbox'
 import { Check, Minus } from 'lucide-solid'
 import type { ComponentProps, JSX } from 'solid-js'
 import { splitProps } from 'solid-js'
+import { useFormFieldControl } from '../../../lib/form-field'
 import { cn } from '../../../lib/utils'
 
 /**
@@ -18,6 +19,8 @@ import { cn } from '../../../lib/utils'
  * the ring lives on the control and reads the input's focus state.
  */
 export type CheckboxProps = Omit<ComponentProps<typeof KobalteCheckbox>, 'children'> & {
+  /** ID for the hidden native checkbox input; useful with an external label. */
+  inputId?: string
   controlClass?: string
   labelClass?: string
   descriptionClass?: string
@@ -44,12 +47,24 @@ export function Checkbox(props: CheckboxProps) {
     'aria-labelledby',
     'aria-describedby',
     'aria-invalid',
+    'aria-errormessage',
     'aria-busy',
+    'id',
+    'inputId',
     'title',
   ])
+  const field = useFormFieldControl('control', {
+    id: local.inputId ?? local.id,
+    'aria-label': local['aria-label'],
+    'aria-labelledby': local['aria-labelledby'],
+    'aria-describedby': local['aria-describedby'],
+    'aria-invalid': local['aria-invalid'],
+    'aria-errormessage': local['aria-errormessage'],
+  })
 
   return (
     <KobalteCheckbox
+      id={field ? undefined : local.id}
       title={local.title}
       class={cn('group/checkbox flex items-start gap-2.5', local.class)}
       {...rest}
@@ -60,10 +75,12 @@ export function Checkbox(props: CheckboxProps) {
        * box would announce its state with no subject.
        */}
       <KobalteCheckbox.Input
+        id={field?.id ?? local.inputId}
         aria-label={local['aria-label']}
-        aria-labelledby={local['aria-labelledby']}
-        aria-describedby={local['aria-describedby']}
-        aria-invalid={local['aria-invalid']}
+        aria-labelledby={field?.['aria-labelledby'] ?? local['aria-labelledby']}
+        aria-describedby={field?.['aria-describedby'] ?? local['aria-describedby']}
+        aria-invalid={field?.['aria-invalid'] ?? local['aria-invalid']}
+        aria-errormessage={field?.['aria-errormessage'] ?? local['aria-errormessage']}
         aria-busy={local['aria-busy']}
         title={local.title}
       />

package/dist/r/src/components/ui/combobox/combobox.tsx

@@ -3,6 +3,7 @@ import { Check, ChevronDown, X } from 'lucide-solid'
 import type { ComponentProps } from 'solid-js'
 import { Show, splitProps } from 'solid-js'
 import { menuContentPadding, menuItem, popoverArrow } from '../../../lib/overlay'
+import { useFormFieldControl } from '../../../lib/form-field'
 import { cn } from '../../../lib/utils'
 
 /**
@@ -43,10 +44,32 @@ export function ComboboxControl(props: ComponentProps<typeof KobalteCombobox.Con
 }
 
 export function ComboboxInput(props: ComponentProps<typeof KobalteCombobox.Input>) {
-  const [local, rest] = splitProps(props, ['class'])
+  const [local, rest] = splitProps(props, [
+    'class',
+    'id',
+    'aria-label',
+    'aria-labelledby',
+    'aria-describedby',
+    'aria-invalid',
+    'aria-errormessage',
+  ])
+  const field = useFormFieldControl('control', {
+    id: local.id,
+    'aria-label': local['aria-label'],
+    'aria-labelledby': local['aria-labelledby'],
+    'aria-describedby': local['aria-describedby'],
+    'aria-invalid': local['aria-invalid'],
+    'aria-errormessage': local['aria-errormessage'],
+  })
 
   return (
     <KobalteCombobox.Input
+      id={field?.id ?? local.id}
+      aria-label={local['aria-label']}
+      aria-labelledby={field?.['aria-labelledby'] ?? local['aria-labelledby']}
+      aria-describedby={field?.['aria-describedby'] ?? local['aria-describedby']}
+      aria-invalid={field?.['aria-invalid'] ?? local['aria-invalid']}
+      aria-errormessage={field?.['aria-errormessage'] ?? local['aria-errormessage']}
       class={cn(
         'h-full flex-1 bg-transparent text-sm outline-none placeholder:text-muted-foreground',
         'disabled:cursor-not-allowed',

package/dist/r/src/components/ui/combobox/index.ts

@@ -8,3 +8,4 @@ export {
   ComboboxSection,
   ComboboxTrigger,
 } from './combobox'
+export { ValueCombobox, type ValueComboboxProps } from './value-combobox'

package/dist/r/src/components/ui/combobox/value-combobox.tsx

@@ -0,0 +1,38 @@
+import { splitProps, type ComponentProps, type JSX } from 'solid-js'
+import { Combobox, ComboboxContent, ComboboxInput, ComboboxItem } from './combobox'
+
+export type ValueComboboxChoice =
+  | { value: string; label: string | number; textValue?: string }
+  | { value: string; label: JSX.Element; textValue: string }
+
+export type ValueComboboxProps = Omit<ComponentProps<typeof ComboboxInput>, 'value'> & {
+  value: string
+  choices: ValueComboboxChoice[]
+  onValueChange: (value: string) => void
+}
+
+/** A single-choice combobox for a controlled string value and labelled choices. */
+export function ValueCombobox(props: ValueComboboxProps) {
+  const [local, rest] = splitProps(props, ['value', 'choices', 'onValueChange'])
+
+  return (
+    <Combobox
+      options={local.choices}
+      optionValue="value"
+      optionTextValue={(choice) => choice.textValue ?? textFromLabel(choice.label)}
+      optionLabel={(choice) => choice.textValue ?? textFromLabel(choice.label)}
+      value={local.choices.find((choice) => String(choice.value) === local.value) ?? null}
+      onChange={(option) => option && local.onValueChange(String(option.value))}
+      itemComponent={(itemProps) => (
+        <ComboboxItem item={itemProps.item}>{itemProps.item.rawValue.label}</ComboboxItem>
+      )}
+    >
+      <ComboboxInput {...rest} />
+      <ComboboxContent />
+    </Combobox>
+  )
+}
+
+function textFromLabel(label: JSX.Element) {
+  return typeof label === 'string' || typeof label === 'number' ? String(label) : ''
+}

package/dist/r/src/components/ui/empty/empty-state.tsx

@@ -0,0 +1,71 @@
+import { Search } from 'lucide-solid'
+import type { ComponentProps, JSX } from 'solid-js'
+import { Show, splitProps } from 'solid-js'
+import { ActionButton } from '../../composites/action-button'
+import { Spinner } from '../spinner'
+import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyMedia, EmptyTitle } from './empty'
+
+export type EmptyStateProps = Omit<ComponentProps<'div'>, 'children' | 'role' | 'aria-live'> & {
+  title: string
+  detail: string
+  busy?: boolean
+  icon?: JSX.Element
+  announceAs?: 'alert' | 'status'
+  headingLevel?: 1 | 2 | 3 | 4 | 5 | 6
+  action?: () => void
+  actionLabel?: string
+  actionTooltip?: string
+}
+
+/** A semantic empty, loading, or error state built from the shared empty parts. */
+export function EmptyState(props: EmptyStateProps) {
+  const [local, rest] = splitProps(props, [
+    'title',
+    'detail',
+    'busy',
+    'icon',
+    'announceAs',
+    'headingLevel',
+    'action',
+    'actionLabel',
+    'actionTooltip',
+    'class',
+  ])
+
+  return (
+    <Empty
+      {...rest}
+      class={local.class}
+      role={local.announceAs}
+      aria-live={local.announceAs === 'status' ? 'polite' : undefined}
+      aria-busy={local.busy || undefined}
+    >
+      <EmptyHeader>
+        <Show when={local.busy || local.icon}>
+          <EmptyMedia variant="icon">
+            {local.busy ? (
+              <Spinner label={false} aria-hidden="true" />
+            ) : (
+              (local.icon ?? <Search aria-hidden="true" />)
+            )}
+          </EmptyMedia>
+        </Show>
+        <EmptyTitle role="heading" aria-level={local.headingLevel ?? 1}>
+          {local.title}
+        </EmptyTitle>
+        <EmptyDescription>{local.detail}</EmptyDescription>
+      </EmptyHeader>
+      <Show when={local.action}>
+        <EmptyContent>
+          <ActionButton
+            tooltip={local.actionTooltip ?? local.actionLabel ?? 'Try again'}
+            aria-label={local.actionLabel ?? 'Try again'}
+            onClick={local.action}
+          >
+            {local.actionLabel ?? 'Try again'}
+          </ActionButton>
+        </EmptyContent>
+      </Show>
+    </Empty>
+  )
+}

package/dist/r/src/components/ui/empty/index.ts

@@ -8,3 +8,4 @@ export {
   type EmptyMediaProps,
   type EmptyProps,
 } from './empty'
+export { EmptyState, type EmptyStateProps } from './empty-state'

package/dist/r/src/components/ui/entity-icon/entity-icon.tsx

@@ -1,4 +1,11 @@
-import { Show, splitProps, type Component, type ComponentProps, type JSX } from 'solid-js'
+import {
+  createSignal,
+  Show,
+  splitProps,
+  type Component,
+  type ComponentProps,
+  type JSX,
+} from 'solid-js'
 import { Dynamic } from 'solid-js/web'
 import { cva, type VariantProps } from '../../../lib/variants'
 import { cn } from '../../../lib/utils'
@@ -16,7 +23,8 @@ import { cn } from '../../../lib/utils'
  *
  * 1. **A glyph is always present.** A brand with no logo gets a monogram, not an
  *    empty box. `fallback` takes the name and returns the glyph, so a caller can
- *    choose initials, a domain letter, or a kind icon.
+ *    choose initials, a domain letter, or a kind icon. When `src` is supplied,
+ *    its contained image overlays that glyph and failure reveals the glyph below.
  * 2. **The tile owns its own contrast.** `tone` tints the background while
  *    monogram text keeps the body foreground; vector glyphs retain the status
  *    colour. A caller never picks a colour pair or ships a glyph that disappears.
@@ -67,6 +75,8 @@ export type EntityIconProps = Omit<ComponentProps<'span'>, 'children'> &
   EntityIconVariantProps & {
     /** The entity's name. Used for the accessible label and, via `fallback`, the monogram. */
     name: string
+    /** Optional image URL. The image is decorative; `name` remains the accessible label. */
+    src?: string
     /**
      * A logo or icon — a Lucide icon reference (`icon={Wrench}`) or an element
      * (`icon={<Wrench />}`). Both are accepted because both are what a caller
@@ -108,9 +118,27 @@ function Glyph(props: { glyph: Glyph }) {
   )
 }
 
+function EntityIconImage(props: { src: string }) {
+  const [failed, setFailed] = createSignal(false)
+
+  return (
+    <Show when={!failed()}>
+      <img
+        data-slot="entity-icon-image"
+        src={props.src}
+        alt=""
+        aria-hidden="true"
+        class="pointer-events-none absolute inset-0 size-full object-contain"
+        onError={() => setFailed(true)}
+      />
+    </Show>
+  )
+}
+
 export function EntityIcon(props: EntityIconProps) {
   const [local, rest] = splitProps(props, [
     'name',
+    'src',
     'icon',
     'fallback',
     'badge',
@@ -146,6 +174,9 @@ export function EntityIcon(props: EntityIconProps) {
       >
         {(value) => <Glyph glyph={value()} />}
       </Show>
+      <Show when={local.src} keyed>
+        {(src) => <EntityIconImage src={src} />}
+      </Show>
       <Show when={local.badge}>
         <span class="absolute right-0 bottom-0 translate-x-1/4 translate-y-1/4">{local.badge}</span>
       </Show>