@flamingo-stack/openframe-frontend-core 0.0.222 → 0.0.223

package/src/components/chat/mingo-chat-history.tsx

@@ -2,7 +2,8 @@
 
 import * as React from 'react'
 import { cn } from '../../utils/cn'
-import { MoreActionsMenu } from '../ui/more-actions-menu'
+import { ActionsMenuDropdown, type ActionsMenuItem } from '../ui/actions-menu'
+import { Button } from '../ui/button'
 import { Ellipsis01Icon } from '../icons-v2-generated'
 import type { DialogItem } from './types/component.types'
 
@@ -106,71 +107,91 @@ function MingoChatHistoryRow({
 
   const menuItems = [
     onRequestRename && {
+      id: 'rename',
       label: 'Rename chat',
       onClick: () => onRequestRename(dialog),
     },
     onRequestArchive && {
+      id: 'archive',
       label: 'Archive chat',
       onClick: () => onRequestArchive(dialog),
     },
-  ].filter(Boolean) as { label: string; onClick: () => void }[]
+  ].filter(Boolean) as ActionsMenuItem[]
 
+  // The item is the full-width row (inside the group's bordered box). Padding
+  // lives on the inner content button (badge + title) only — the `⋯` is a
+  // SIBLING of that padded content, so it sits at the item's right edge, inside
+  // the item but outside its padded content area.
   return (
     <div
-      role="button"
-      tabIndex={0}
-      onClick={() => onSelect?.(dialog.id)}
-      onKeyDown={(e) => {
-        if (e.key === 'Enter' || e.key === ' ') {
-          e.preventDefault()
-          onSelect?.(dialog.id)
-        }
-      }}
       className={cn(
-        'group/row flex h-12 items-center gap-[var(--spacing-system-xsf)] px-[var(--spacing-system-s)]',
-        'bg-ods-bg border-b border-ods-border last:border-b-0',
-        'cursor-pointer transition-colors hover:bg-ods-bg-hover focus:outline-none focus-visible:bg-ods-bg-hover',
+        'group/row flex h-12 items-center bg-ods-bg border-b border-ods-border last:border-b-0',
+        'transition-colors hover:bg-ods-bg-hover',
         isActive && 'bg-ods-bg-hover',
       )}
     >
-      {unread > 0 ? (
-        <span className="flex h-8 min-w-8 shrink-0 items-center justify-center rounded-md bg-ods-accent px-[var(--spacing-system-xsf)] text-h5 text-ods-text-on-accent">
-          {unread > 99 ? '99+' : unread}
-        </span>
-      ) : null}
-      <span
-        className="min-w-0 flex-1 truncate text-h4 text-ods-text-primary"
-        title={title}
+      <div
+        role="button"
+        tabIndex={0}
+        onClick={() => onSelect?.(dialog.id)}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault()
+            onSelect?.(dialog.id)
+          }
+        }}
+        className="flex min-w-0 flex-1 items-center gap-[var(--spacing-system-xsf)] p-[var(--spacing-system-s)] cursor-pointer focus:outline-none focus-visible:bg-ods-bg-hover"
       >
-        {title}
-      </span>
+        {unread > 0 ? (
+          <span className="flex h-8 min-w-8 shrink-0 items-center justify-center rounded-md bg-ods-accent px-[var(--spacing-system-xsf)] text-h5 text-ods-text-on-accent">
+            {unread > 99 ? '99+' : unread}
+          </span>
+        ) : null}
+        <span
+          className="min-w-0 flex-1 truncate text-h4 text-ods-text-primary"
+          title={title}
+        >
+          {title}
+        </span>
+      </div>
       {hasMenu ? (
-        // Stop propagation so opening the menu doesn't also select the dialog.
-        // Hidden until the row is hovered/focused (or its menu is open).
+        // Sibling of the padded content (not inside it): sits at the item's
+        // right edge, free of the content's left padding. Revealed on row
+        // hover/focus; kept visible while its menu is open. Hidden on mobile —
+        // it's a hover affordance (no hover on touch).
         <span
           onClick={(e) => e.stopPropagation()}
           className={cn(
-            'shrink-0 transition-opacity',
+            // `self-stretch` so the wrapper fills the row height — gives the
+            // button's `h-full` a definite parent to resolve against (under the
+            // row's `items-center` the wrapper would otherwise collapse to its
+            // content and `h-full` on the button would no-op).
+            'self-stretch shrink-0 transition-opacity max-md:hidden',
             menuOpen
               ? 'opacity-100'
               : 'opacity-0 group-hover/row:opacity-100 focus-within:opacity-100',
           )}
         >
-          <MoreActionsMenu
-            ariaLabel="Chat actions"
-            items={menuItems}
+          <ActionsMenuDropdown
+            triggerAriaLabel="Chat actions"
+            groups={[{ items: menuItems }]}
             open={menuOpen}
             onOpenChange={setMenuOpen}
             // Don't return focus (and its ring) to the `⋯` trigger on close.
             onCloseAutoFocus={(e) => e.preventDefault()}
-            trigger={
-              <button
-                type="button"
+            customTrigger={
+              <Button
+                variant="transparent"
+                size="icon"
                 aria-label="Chat actions"
-                className="flex size-6 items-center justify-center rounded-md text-ods-text-secondary transition-colors hover:text-ods-text-primary focus:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent"
+                // Square, grey icon → white on hover. `h-full` matches the row
+                // height exactly (no breakpoint poke from `size="icon"`'s
+                // responsive `md:h-12`); `w-9` keeps it compact; `p-0` drops the
+                // icon-size padding. tailwind-merge so these win over defaults.
+                className="h-full md:h-full rounded-none p-0 text-ods-text-secondary hover:text-ods-text-primary"
               >
-                <Ellipsis01Icon size={24} />
-              </button>
+                <Ellipsis01Icon />
+              </Button>
             }
           />
         </span>
@@ -179,6 +200,67 @@ function MingoChatHistoryRow({
   )
 }
 
+// =============================================================================
+// Skeleton
+// =============================================================================
+
+/**
+ * Loading placeholder for the dialog history, shaped like the grouped row list
+ * above. Shown while the FIRST page of dialogs is in flight so the Mingo empty
+ * state doesn't flash the new-user greeting+grid before the list arrives (the
+ * two layouts are mutually exclusive — swapping between them mid-load reads as
+ * a flicker). Pure ODS tokens, `animate-pulse`.
+ */
+export function MingoChatHistorySkeleton({ className }: { className?: string }) {
+  // Mirror the real grouped list: a group label, then a bordered container of
+  // `h-12` rows. `withBadge` adds the leading unread-badge square on the first
+  // N rows; `widths` varies the title-bar length so the placeholder reads like
+  // a list of differing-length chat titles, not identical bars. `bg-ods-border`
+  // (not `bg-ods-bg-secondary`) so the placeholders are actually visible on the
+  // dark surface.
+  const groups: ReadonlyArray<{ withBadge: number; widths: ReadonlyArray<string> }> = [
+    { withBadge: 2, widths: ['w-3/5', 'w-4/5', 'w-2/5', 'w-3/4'] },
+    { withBadge: 0, widths: ['w-1/2', 'w-3/5', 'w-2/3'] },
+  ]
+  return (
+    <div
+      aria-hidden
+      // `overflow-hidden` clips the placeholder rows to the flex-1 box (the real
+      // list scrolls; the skeleton just needs to stay within bounds). Without it
+      // the rows bleed past their allotment and render under the pinned composer
+      // — which has no surface of its own — so the input appears to overlap them.
+      className={cn(
+        'flex flex-1 min-h-0 flex-col gap-[var(--spacing-system-m)] overflow-hidden',
+        className,
+      )}
+    >
+      {groups.map((group, g) => (
+        <div key={g} className="flex shrink-0 flex-col gap-[var(--spacing-system-xxs)]">
+          {/* Group label (Today / Yesterday). */}
+          <div className="h-3 w-16 animate-pulse rounded bg-ods-border" />
+          <div className="overflow-hidden rounded-md border border-ods-border">
+            {group.widths.map((w, i) => (
+              <div
+                key={i}
+                // Match the real row surface: `bg-ods-bg` (#161616) sits darker
+                // than the `bg-ods-card` (#212121) panel, which is what makes
+                // the `bg-ods-border` (#3a3a3a) placeholders read clearly. On
+                // the bare card they'd be muddy (too close in value).
+                className="flex h-12 items-center gap-[var(--spacing-system-xsf)] bg-ods-bg border-b border-ods-border px-[var(--spacing-system-s)] last:border-b-0"
+              >
+                {i < group.withBadge && (
+                  <div className="h-8 w-8 shrink-0 animate-pulse rounded-md bg-ods-border" />
+                )}
+                <div className={cn('h-4 animate-pulse rounded bg-ods-border', w)} />
+              </div>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  )
+}
+
 // =============================================================================
 // Component
 // =============================================================================

package/src/components/chat/mingo-info-card.tsx

@@ -0,0 +1,214 @@
+'use client'
+
+import * as React from 'react'
+import { cn } from '../../utils/cn'
+import { tagVariants, type TagProps } from '../ui/tag'
+import { ActionsMenuDropdown, type ActionsMenuGroup } from '../ui/actions-menu'
+import { Ellipsis01Icon } from '../icons-v2-generated'
+import { getFirstLastInitials } from '../../utils/format'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** A coloured status pill rendered to the right of the title/description. */
+export interface MingoInfoCardStatus {
+  /** Pill text — rendered uppercase via the `success`/`warning`/… Tag palette. */
+  label: React.ReactNode
+  /** Tag colour. Defaults to `success` (green) to match the Figma sample. */
+  variant?: TagProps['variant']
+}
+
+export interface MingoInfoCardProps {
+  /** Card title — DM Sans Medium 18px (`text-h4`), white. Truncates on overflow. */
+  title: React.ReactNode
+  /** Optional secondary line below the title — 14px (`text-h6`), grey. Truncates. */
+  description?: React.ReactNode
+  /**
+   * Leading 40px avatar image (`img="image"` variant in Figma). Takes
+   * precedence over `icon` when both are supplied. Falls back to initials
+   * derived from `imageAlt` if the image fails to load.
+   */
+  imageSrc?: string
+  /** Alt text / initials fallback for `imageSrc`. */
+  imageAlt?: string
+  /**
+   * Leading 24px glyph rendered inside a 40px box (`img="icon"` variant).
+   * Ignored when `imageSrc` is set. Pass an `icons-v2-generated` icon — it
+   * inherits `currentColor` from the box's `text-ods-text-primary`.
+   */
+  icon?: React.ReactNode
+  /** Optional status pill (e.g. `{ label: 'Online' }`). */
+  status?: MingoInfoCardStatus
+  /**
+   * Overflow-menu groups. When non-empty, a trailing "⋯" button opens an
+   * `ActionsMenuDropdown`. Omit to hide the button entirely.
+   */
+  menuGroups?: ReadonlyArray<ActionsMenuGroup>
+  /** Aria-label for the "⋯" trigger. Defaults to `"More actions"`. */
+  menuAriaLabel?: string
+  /**
+   * Renders the main content region as an `<a>` (for navigation) instead of a
+   * `<button>`. Takes precedence over `onClick`. The "⋯" button stays a sibling
+   * of the anchor — not nested inside it — so the markup stays valid.
+   */
+  anchorProps?: MingoInfoCardAnchorProps
+  /**
+   * Click handler for the main content region. When set (and `anchorProps` is
+   * not), the title/description region becomes a `<button>` with hover/focus
+   * affordances. The "⋯" button keeps its own independent click target.
+   */
+  onClick?: () => void
+  /** Appended to the root element. */
+  className?: string
+}
+
+/** Anchor-prop bundle for the content region — mirrors the `*AnchorProps`
+ *  shape the chat entity-cards pass (`{ href, target?, rel?, onClick? }`). */
+export interface MingoInfoCardAnchorProps {
+  href: string
+  target?: '_blank'
+  rel?: string
+  onClick?: (e: React.MouseEvent<HTMLAnchorElement>) => void
+}
+
+// =============================================================================
+// Span-only markup
+//
+// This card renders inline inside chat message paragraphs (the `[card://]`
+// marker is replaced in-place, landing the card inside a `<p>`). To stay
+// valid there, EVERY element is phrasing content — `<span>` / `<a>` / `<img>`
+// / `<button>` only, never `<div>`. Layout comes from `display` utilities, so
+// the visual is identical to a block card.
+// =============================================================================
+
+/** 40px leading media — avatar image (with initials fallback) or boxed glyph. */
+function CardMedia({
+  imageSrc,
+  imageAlt,
+  icon,
+}: Pick<MingoInfoCardProps, 'imageSrc' | 'imageAlt' | 'icon'>) {
+  if (imageSrc) {
+    return (
+      <span className="relative block size-10 shrink-0">
+        {/* Initials fallback sits BEHIND the image. The image is the framed
+            element itself — `rounded-sm` + `border` live on the `<img>` so the
+            picture and its 1px frame share one radius (no corner gap from
+            clipping a separate absolutely-positioned child). On a 404 the
+            image's `onError` hides it and the initials show through. */}
+        <span className="absolute inset-0 flex items-center justify-center rounded-sm border border-ods-border bg-ods-bg text-xs font-medium text-ods-text-primary">
+          {getFirstLastInitials(imageAlt) || '?'}
+        </span>
+        <img
+          src={imageSrc}
+          alt={imageAlt || ''}
+          className="relative block size-10 rounded-sm border border-ods-border object-cover"
+          onError={(e) => {
+            e.currentTarget.style.display = 'none'
+          }}
+        />
+      </span>
+    )
+  }
+  if (icon) {
+    return (
+      <span className="flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-md border border-ods-border bg-ods-bg text-ods-text-secondary">
+        <span className="flex size-6 items-center justify-center">{icon}</span>
+      </span>
+    )
+  }
+  return null
+}
+
+export function MingoInfoCard({
+  title,
+  description,
+  imageSrc,
+  imageAlt,
+  icon,
+  status,
+  menuGroups,
+  menuAriaLabel = 'More actions',
+  anchorProps,
+  onClick,
+  className,
+}: MingoInfoCardProps) {
+  const hasMedia = !!imageSrc || !!icon
+  const hasMenu = !!menuGroups && menuGroups.length > 0
+  const isAnchor = !!anchorProps
+  const isInteractive = isAnchor || !!onClick
+
+  // The content region: leading media, text column, status pill. Owns the
+  // `border-r` divider that sits before the "⋯" button.
+  const content = (
+    <>
+      {hasMedia && (
+        <CardMedia imageSrc={imageSrc} imageAlt={imageAlt} icon={icon} />
+      )}
+      <span className="flex min-w-0 flex-1 flex-col justify-center">
+        <span className="truncate text-h4 font-medium text-ods-text-primary">
+          {title}
+        </span>
+        {description ? (
+          <span className="truncate text-h6 text-ods-text-secondary">
+            {description}
+          </span>
+        ) : null}
+      </span>
+      {status ? (
+        // Reuse the shared Tag palette (single source of truth for colours)
+        // without rendering Tag's `<div>` — span-only for `<p>` validity.
+        <span className={cn(tagVariants({ variant: status.variant ?? 'success' }), 'shrink-0')}>
+          <span className="truncate uppercase tracking-[-0.28px]">{status.label}</span>
+        </span>
+      ) : null}
+    </>
+  )
+
+  const contentClass = cn(
+    'flex min-w-0 flex-1 items-center gap-[var(--spacing-system-s)] overflow-hidden p-[var(--spacing-system-s)] text-left',
+    hasMenu && 'border-r border-ods-border',
+    isInteractive &&
+      'transition-colors hover:bg-ods-bg-hover active:bg-ods-bg-active focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ods-accent cursor-pointer',
+  )
+
+  return (
+    <span
+      className={cn(
+        'flex w-full items-center overflow-hidden rounded-md border border-ods-border bg-ods-card',
+        className,
+      )}
+    >
+      {isAnchor ? (
+        <a {...anchorProps} className={cn(contentClass, 'no-underline')}>
+          {content}
+        </a>
+      ) : onClick ? (
+        <button type="button" onClick={onClick} className={contentClass}>
+          {content}
+        </button>
+      ) : (
+        <span className={contentClass}>{content}</span>
+      )}
+
+      {hasMenu && (
+        <ActionsMenuDropdown
+          groups={menuGroups as ActionsMenuGroup[]}
+          triggerAriaLabel={menuAriaLabel}
+          onCloseAutoFocus={(e) => e.preventDefault()}
+          customTrigger={
+            <button
+              type="button"
+              aria-label={menuAriaLabel}
+              // Press feedback mirrors `Button` (transparent variant):
+              // `hover:bg-ods-bg-hover` → `active:bg-ods-bg-active`.
+              className="flex w-[56px] md:w-[68px] shrink-0 items-center justify-center self-stretch text-ods-text-secondary transition-colors hover:bg-ods-bg-hover hover:text-ods-text-primary active:bg-ods-bg-active active:text-ods-text-primary focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ods-accent"
+            >
+              <Ellipsis01Icon size={24} />
+            </button>
+          }
+        />
+      )}
+    </span>
+  )
+}

package/src/components/chat/mingo-welcome.tsx

@@ -3,7 +3,10 @@
 import * as React from 'react'
 import { cn } from '../../utils/cn'
 import { MingoIcon } from '../icons'
+import { MingoChatHistorySkeleton } from './mingo-chat-history'
+import { ChatQuickActionRow } from './chat-quick-action-row'
 import { Tag } from '../ui/tag'
+import { Button } from '../ui/button'
 import { XmarkIcon } from '../icons-v2-generated/signs-and-symbols/xmark-icon'
 import {
   Rocket01Icon,
@@ -12,6 +15,8 @@ import {
   LayersIcon,
   CompassIcon,
   Arrow01DownIcon,
+  AlertCircleIcon,
+  Refresh01RightIcon,
 } from '../icons-v2-generated'
 
 // =============================================================================
@@ -74,6 +79,19 @@ export interface MingoWelcomeProps {
    *  `<MingoChatHistory>`), it replaces the greeting + feature grid and owns
    *  its own scroll region. The chips below stay pinned. */
   dialogHistory?: React.ReactNode
+  /** True while the FIRST page of dialogs is still loading and we don't yet
+   *  know if the user is new or returning. Renders a history skeleton in place
+   *  of both the greeting+grid and the history, so the empty state doesn't
+   *  flash the new-user layout before the list arrives. Ignored once
+   *  `dialogHistory` is provided. */
+  isLoadingHistory?: boolean
+  /** The dialog-list load FAILED (e.g. backend down) and there's nothing
+   *  cached. Renders an error + retry block in place of the new-user empty
+   *  state (which would otherwise misleadingly advertise Guide). Takes
+   *  priority over `isLoadingHistory`. Ignored once `dialogHistory` is set. */
+  loadError?: boolean
+  /** Retry handler for the `loadError` state. */
+  onRetry?: () => void
   /** When provided, renders the "Start Guide Chat" chip (the only wired
    *  action — switches the host chat to Guide mode) and enables the default
    *  promo notification. When omitted, both are suppressed. */
@@ -149,6 +167,9 @@ export function MingoWelcome({
   quickActions,
   hasExistingChats = false,
   dialogHistory,
+  isLoadingHistory = false,
+  loadError = false,
+  onRetry,
   onStartGuideChat,
   className,
 }: MingoWelcomeProps) {
@@ -222,6 +243,14 @@ export function MingoWelcome({
   // Last row's first index — used to drop the bottom divider on the final row.
   const lastRowStart = cellCount - ((cellCount % 2) || 2)
 
+  // While we don't yet know whether the user is new or returning (first page
+  // loading, or it errored with nothing cached), suppress the pinned region —
+  // the "New to OpenFrame?" promo + quick-action chips. Showing them over the
+  // history skeleton both clutters the loading frame and pre-judges the user as
+  // new. They return once a resolved state (history, or the new-user greeting)
+  // renders. `dialogHistory` always wins — a returning user keeps the chips.
+  const showPinnedRegion = !!dialogHistory || (!isLoadingHistory && !loadError)
+
   return (
     <div
       className={cn(
@@ -233,8 +262,33 @@ export function MingoWelcome({
       )}
     >
       {/* Returning users see their dialog history (its own scroll region) in
-          place of the greeting + grid. */}
-      {dialogHistory ?? (
+          place of the greeting + grid. Precedence: load error (retry) → first-
+          page loading (skeleton) → new-user greeting+grid. The error branch
+          stops a failed fetch from masquerading as "no chats" (which would
+          otherwise show the Guide promo). */}
+      {dialogHistory ?? (loadError ? (
+        <div className="flex flex-1 min-h-0 flex-col items-center justify-center gap-[var(--spacing-system-m)] text-center">
+          <AlertCircleIcon className="h-8 w-8 text-ods-text-secondary shrink-0" />
+          <div className="flex flex-col gap-[var(--spacing-system-xxs)]">
+            <p className="text-h4 text-ods-text-primary">Couldn’t load your chats</p>
+            <p className="text-body-sm text-ods-text-secondary">
+              Something went wrong reaching the server. Check your connection and try again.
+            </p>
+          </div>
+          {onRetry && (
+            <Button
+              variant="outline"
+              size="small"
+              leftIcon={<Refresh01RightIcon />}
+              onClick={onRetry}
+            >
+              Try again
+            </Button>
+          )}
+        </div>
+      ) : isLoadingHistory ? (
+        <MingoChatHistorySkeleton />
+      ) : (
       <>
       {/* Scrollable region — only the greeting + grid scroll; the notification
           and chips below stay pinned so they're always visible above the
@@ -321,9 +375,11 @@ export function MingoWelcome({
       />
       </div>
       </>
-      )}
+      ))}
 
-      {/* Pinned region — always visible above the input. */}
+      {/* Pinned region — visible above the input once the new/returning-user
+          state is known (hidden during first-page load / error). */}
+      {showPinnedRegion && (
       <div className="flex shrink-0 flex-col gap-[var(--spacing-system-m)]">
       {/* "New to OpenFrame?" — a one-time informational notification (no
           action). The leading down-arrow (Figma node 7532:317130) only shows
@@ -356,41 +412,38 @@ export function MingoWelcome({
         </div>
       )}
 
-      {/* Quick-action chips. Only "Start Guide Chat" is wired by default; the
-          chip and any `quickActions` use the design-system <Tag>, wrapped in a
-          real <button> so each chip gets keyboard focus + a focus ring. */}
+      {/* Quick-action chips. "Start Guide Chat" stays pinned (the `leading`
+          slot — never collapses); any caller `quickActions` fit inline and the
+          rest collapse under a "⋯" overflow menu, width-measured like the
+          Autocomplete tag row. */}
       {(onStartGuideChat || (quickActions && quickActions.length > 0)) && (
-        <div className="flex shrink-0 flex-wrap items-center gap-1">
-          {onStartGuideChat && (
-            <button
-              type="button"
-              onClick={onStartGuideChat}
-              className="rounded-md focus:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent"
-            >
-              <Tag
-                variant={hasExistingChats ? 'outline' : 'primary'}
-                icon={<CompassIcon size={16} />}
-                label="Start Guide Chat"
-              />
-            </button>
-          )}
-          {quickActions?.map((action) => (
-            <button
-              key={action.id}
-              type="button"
-              onClick={action.onClick}
-              className="rounded-md focus:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent"
-            >
-              <Tag
-                variant={action.variant ?? 'outline'}
-                icon={action.icon}
-                label={action.label}
-              />
-            </button>
-          ))}
-        </div>
+        <ChatQuickActionRow
+          leading={
+            onStartGuideChat && (
+              <button
+                type="button"
+                onClick={onStartGuideChat}
+                className="shrink-0 rounded-md focus:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent"
+              >
+                <Tag
+                  variant={hasExistingChats ? 'outline' : 'primary'}
+                  icon={<CompassIcon size={16} />}
+                  label="Start Guide Chat"
+                />
+              </button>
+            )
+          }
+          chips={(quickActions ?? []).map((action) => ({
+            id: action.id,
+            label: action.label,
+            icon: action.icon,
+            variant: action.variant,
+            onSelect: action.onClick,
+          }))}
+        />
       )}
       </div>
+      )}
     </div>
   )
 }

package/src/components/chat/types/chat.types.ts

@@ -87,6 +87,10 @@ export interface MessageOwner {
     id: string
     firstName?: string
     lastName?: string
+    /** Optional author avatar. Host queries it on the message owner (e.g.
+     *  GraphQL `User.image`); `imageUrl` may be relative — the host is
+     *  responsible for resolving it to an absolute/proxied URL. */
+    image?: { imageUrl?: string | null } | null
   }
 }
 

package/src/components/chat/types/unified-chat-state.types.ts

@@ -18,6 +18,7 @@
 
 import type { MessageSegment } from './message.types'
 import type { ScrollAnchor } from './message.types'
+import type { AuthorType } from './chat.types'
 import type { ChatRef } from '../chat-ref.types'
 import type { ChatSource } from '../hooks/use-sse-chat-adapter'
 import type { ChatAttachment } from '../utils/chat-attachment-markdown'
@@ -108,6 +109,32 @@ export interface UnifiedChatMessage {
   id: string
   role: 'user' | 'assistant'
 
+  /**
+   * Optional host-supplied display name for the message author. When set, the
+   * chat renders it verbatim (e.g. the signed-in user's full name for a
+   * `user` bubble, or a per-message admin name from history); when omitted the
+   * UI falls back to the role default (`'Mingo'` / `'You'`).
+   */
+  name?: string
+
+  /**
+   * Optional host-supplied avatar URL for the message author. Used by the
+   * panel to render an inline avatar on the author row (proxied via
+   * `useProxiedImageUrl`). Omit/`null` to fall back to initials. For `user`
+   * bubbles the avatar only renders when this is set, so consumers that don't
+   * supply one keep the name-only layout.
+   */
+  avatar?: string | null
+
+  /**
+   * Optional host-supplied author type — drives the name-row accent color in
+   * `<ChatMessageEnhanced>` (e.g. `'admin'` renders the name in the accent
+   * color, matching the standalone `/mingo` page). When omitted the panel
+   * falls back to the role default (`'user'` for user bubbles, the assistant
+   * type otherwise).
+   */
+  authorType?: AuthorType
+
   /**
    * Flat string form for legacy/simple callers. The structured `segments`
    * form is preferred — it carries thinking blocks, tool calls, approval
@@ -296,6 +323,14 @@ export interface UnifiedChatState {
   /** True while the dialog list is being fetched for the first time. */
   isDialogsLoading: boolean
 
+  /** True when the initial dialog-list load FAILED (e.g. backend down).
+   *  Lets the UI distinguish a load error from a genuinely empty list and
+   *  show a retry affordance instead of the new-user empty state. */
+  dialogsError: boolean
+
+  /** Re-run the initial dialog-list load — retry after `dialogsError`. */
+  reloadDialogs: () => void
+
   /** True while message history for the active dialog is being fetched. */
   isMessagesLoading: boolean