@flamingo-stack/openframe-frontend-core 0.0.219 → 0.0.220-snapshot.20260602171504

package/src/components/navigation/app-layout-drawer.tsx

@@ -105,16 +105,14 @@ const appLayoutDrawerVariants = cva(
       },
     },
     compoundVariants: [
-      { side: "right", flush: false, class: "pr-4 py-4" },
-      { side: "left", flush: false, class: "pl-4 py-4" },
-      { side: "top", flush: false, class: "pt-4 px-4" },
-      { side: "bottom", flush: false, class: "pb-4 px-4" },
-      // flush=true: keep wrapper padding on desktop (uniform 16px gap so the
-      // panel floats), drop on mobile for full-bleed — matches base Drawer.
-      { side: "right", flush: true, class: "md:pr-4 md:py-4" },
-      { side: "left", flush: true, class: "md:pl-4 md:py-4" },
-      { side: "top", flush: true, class: "md:pt-4 md:px-4" },
-      { side: "bottom", flush: true, class: "md:pb-4 md:px-4" },
+      { side: "right", flush: false, class: "pr-[var(--spacing-system-m)] py-[var(--spacing-system-m)]" },
+      { side: "left", flush: false, class: "pl-[var(--spacing-system-m)] py-[var(--spacing-system-m)]" },
+      { side: "top", flush: false, class: "pt-[var(--spacing-system-m)] px-[var(--spacing-system-m)]" },
+      { side: "bottom", flush: false, class: "pb-[var(--spacing-system-m)] px-[var(--spacing-system-m)]" },
+      { side: "right", flush: true, class: "md:pr-[var(--spacing-system-m)] md:py-[var(--spacing-system-m)]" },
+      { side: "left", flush: true, class: "md:pl-[var(--spacing-system-m)] md:py-[var(--spacing-system-m)]" },
+      { side: "top", flush: true, class: "md:pt-[var(--spacing-system-m)] md:px-[var(--spacing-system-m)]" },
+      { side: "bottom", flush: true, class: "md:pb-[var(--spacing-system-m)] md:px-[var(--spacing-system-m)]" },
     ],
     defaultVariants: {
       side: "right",
@@ -192,11 +190,11 @@ function useContainedResizableSize({
 
   const clampToContainer = React.useCallback(
     (value: number) => {
-      // Reserve 32px (16px outside-edge padding from the wrapper + 16px
-      // matching gap on the inside edge) so the panel sits symmetrically
+      // Reserve 40px (the `system-m` outside-edge padding from the wrapper
+      // plus a matching gap on the inside edge) so the panel sits symmetrically
       // inside the container. This also keeps the resize grip on-screen at
       // maximum extent.
-      const effectiveMax = available > 0 ? Math.min(maxSize, available - 32) : maxSize
+      const effectiveMax = available > 0 ? Math.min(maxSize, available - 40) : maxSize
       return clamp(value, minSize, Math.max(minSize, effectiveMax))
     },
     [available, minSize, maxSize],
@@ -547,13 +545,19 @@ const AppLayoutDrawerContent = React.forwardRef<
           aria-hidden
           data-state={open ? "open" : "closed"}
           className={cn(
-            "absolute inset-0 z-[40] bg-black/50 outline-none data-[state=open]:pointer-events-auto data-[state=closed]:pointer-events-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+            "absolute inset-0 z-[40] bg-[color-mix(in_srgb,var(--ods-system-greys-background)_50%,transparent)] outline-none data-[state=open]:pointer-events-auto data-[state=closed]:pointer-events-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
             overlayClassName,
           )}
         />
         <DialogPrimitive.Content
           ref={ref}
-          className={cn(appLayoutDrawerVariants({ side, flush }))}
+          className={cn(
+            appLayoutDrawerVariants({ side, flush }),
+            // Mobile: span the whole container and drop the outer gap so the
+            // panel renders edge-to-edge full-screen. (`p-0` overrides the
+            // variant's wrapper padding via tailwind-merge.)
+            isMobile && "inset-0 p-0",
+          )}
           style={style}
           onInteractOutside={(event) => {
             onInteractOutside?.(event)
@@ -585,6 +589,12 @@ const AppLayoutDrawerContent = React.forwardRef<
           <div
             className={cn(
               appLayoutDrawerPanelVariants({ side, flush }),
+              // Mobile: fill the container (the side already pins one axis) and
+              // drop the card chrome so the panel is edge-to-edge full-screen.
+              // Inner padding/gap is preserved so content isn't glued to the
+              // edges. tailwind-merge lets these override the variant classes.
+              isMobile && (isHorizontal ? "w-full" : "h-full"),
+              isMobile && "rounded-none border-0",
               className,
               panelClassName,
             )}

package/src/components/navigation/header-mingo-button.tsx

@@ -3,6 +3,7 @@
 import React from 'react'
 import { cn } from '../../utils/cn'
 import { MingoIcon } from '../icons'
+import { XmarkIcon } from '../icons-v2-generated'
 
 export interface HeaderMingoButtonProps
   extends React.ButtonHTMLAttributes<HTMLButtonElement> {
@@ -18,8 +19,10 @@ export interface HeaderMingoButtonProps
 /**
  * "Mingo AI" launcher button for `AppHeader`. Mirrors the `HeaderButton`
  * visual contract (sticky header height, `ods-card` rest / `ods-bg-hover`
- * hover / `ods-bg-active` active, divider via `AppHeader`'s `divide-x`), but
- * carries both the Mingo logo and the bold "Mingo AI" wordmark.
+ * hover, divider via `AppHeader`'s `divide-x`), but carries both the Mingo
+ * logo and the bold "Mingo AI" wordmark. The open/active state is exposed via
+ * `aria-pressed` (and, in `iconOnly` mode, by swapping the logo for a close
+ * "X"); there is no distinct active background.
  *
  * Figma: 7532:222103 — `button-full`.
  */
@@ -32,20 +35,32 @@ export function HeaderMingoButton({
   return (
     <button
       type="button"
-      aria-label="Mingo AI"
+      aria-label={iconOnly && isActive ? 'Close Mingo AI' : 'Mingo AI'}
       aria-pressed={isActive}
       className={cn(
         'flex items-center shrink-0 h-full gap-2 px-4',
         'transition-colors duration-200',
         'focus:outline-none focus-visible:ring-2 focus-visible:ring-ods-accent',
-        isActive
-          ? 'text-ods-text-primary bg-ods-bg-active'
-          : 'text-ods-text-primary bg-ods-card hover:bg-ods-bg-hover',
+        'text-ods-text-primary bg-ods-card hover:bg-ods-bg-hover',
         className,
       )}
       {...props}
     >
-      <MingoIcon className="w-6 h-6 shrink-0" />
+      {iconOnly && isActive ? (
+        // Mobile, drawer open: the icon-only button doubles as the close
+        // affordance, so swap the Mingo logo for an X. Match the other header
+        // icons (e.g. notifications): secondary color, w-4 h-4 → md:w-6 h-6.
+        <XmarkIcon className="w-4 h-4 md:w-6 md:h-6 shrink-0 text-ods-text-secondary" />
+      ) : (
+        // Outer frame follows the button's text color (currentColor); the eyes
+        // and corner block are ODS cyan.
+        <MingoIcon
+          color="currentColor"
+          eyesColor="var(--ods-flamingo-cyan-base)"
+          cornerColor="var(--ods-flamingo-cyan-base)"
+          className="w-4 h-4 md:w-6 md:h-6 shrink-0"
+        />
+      )}
       {!iconOnly && (
         <span className="text-h3 font-bold tracking-[-0.36px] whitespace-nowrap">
           Mingo AI

package/src/components/ui/dropdown-menu.tsx

@@ -5,6 +5,7 @@ import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu"
 import { Check, ChevronRight, Circle } from "lucide-react"
 
 import { cn } from "../../utils/cn"
+import { usePortalContainer } from "./portal-container"
 
 const DropdownMenu = DropdownMenuPrimitive.Root
 
@@ -59,8 +60,12 @@ DropdownMenuSubContent.displayName =
 const DropdownMenuContent = React.forwardRef<
   React.ElementRef<typeof DropdownMenuPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>
->(({ className, sideOffset = 4, ...props }, ref) => (
-  <DropdownMenuPrimitive.Portal>
+>(({ className, sideOffset = 4, ...props }, ref) => {
+  // Portal into the active container (e.g. a drawer) so the menu inherits its
+  // stacking context; falls back to `document.body` when none is provided.
+  const container = usePortalContainer()
+  return (
+  <DropdownMenuPrimitive.Portal container={container ?? undefined}>
     <DropdownMenuPrimitive.Content
       ref={ref}
       sideOffset={sideOffset}
@@ -71,7 +76,8 @@ const DropdownMenuContent = React.forwardRef<
       {...props}
     />
   </DropdownMenuPrimitive.Portal>
-))
+  )
+})
 DropdownMenuContent.displayName = DropdownMenuPrimitive.Content.displayName
 
 const DropdownMenuItem = React.forwardRef<

package/src/components/ui/modal-v2.tsx

@@ -1,10 +1,14 @@
 "use client"
 
 import * as React from "react"
-import { useEffect } from "react"
+import { useEffect, useState } from "react"
 import { XmarkIcon } from "../icons-v2-generated"
 import { cn } from "../../utils/cn"
 
+// Duration of the open/close animation in ms — keep in sync with the
+// `duration-200` utilities applied to the backdrop and panel below.
+const ANIMATION_DURATION = 200
+
 const ModalContext = React.createContext<{ onClose?: () => void }>({})
 
 interface ModalProps {
@@ -36,6 +40,18 @@ interface ModalFooterProps {
 
 const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
   ({ isOpen, onClose, children, className }, ref) => {
+    // Keep the modal mounted while the exit animation plays.
+    const [isMounted, setIsMounted] = useState(isOpen)
+
+    useEffect(() => {
+      if (isOpen) {
+        setIsMounted(true)
+        return
+      }
+      const timeout = setTimeout(() => setIsMounted(false), ANIMATION_DURATION)
+      return () => clearTimeout(timeout)
+    }, [isOpen])
+
     useEffect(() => {
       const handleKeyDown = (event: KeyboardEvent) => {
         if (event.key === 'Escape') {
@@ -54,17 +70,26 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
       }
     }, [isOpen, onClose])
 
-    if (!isOpen) return null
+    if (!isMounted) return null
+
+    const state = isOpen ? "open" : "closed"
 
     return (
       <div className="fixed inset-0 z-[1300] flex items-end md:items-center justify-center">
         <div
-          className="absolute inset-0 bg-black/50 backdrop-blur-[2px] md:backdrop-blur-none"
+          data-state={state}
+          className={cn(
+            "absolute inset-0 bg-black/50 backdrop-blur-[2px] md:backdrop-blur-none",
+            "duration-200",
+            "data-[state=open]:animate-in data-[state=open]:fade-in-0",
+            "data-[state=closed]:animate-out data-[state=closed]:fade-out-0"
+          )}
           onClick={onClose}
           aria-hidden="true"
         />
         <div
           ref={ref}
+          data-state={state}
           className={cn(
             "relative z-10 w-full max-w-md flex flex-col",
             "mx-4 mb-4 md:mb-0",
@@ -72,6 +97,11 @@ const Modal = React.forwardRef<HTMLDivElement, ModalProps>(
             "bg-ods-bg md:bg-ods-card",
             "border border-ods-border rounded-md shadow-xl",
             "p-[var(--spacing-system-xl)] gap-[var(--spacing-system-l)]",
+            "duration-200",
+            "data-[state=open]:animate-in data-[state=open]:fade-in-0",
+            "data-[state=open]:slide-in-from-bottom-4 md:data-[state=open]:slide-in-from-bottom-0 md:data-[state=open]:zoom-in-95",
+            "data-[state=closed]:animate-out data-[state=closed]:fade-out-0",
+            "data-[state=closed]:slide-out-to-bottom-4 md:data-[state=closed]:slide-out-to-bottom-0 md:data-[state=closed]:zoom-out-95",
             className
           )}
           role="dialog"

package/src/components/ui/more-actions-menu.tsx

@@ -31,6 +31,10 @@ export interface MoreActionsMenuProps {
   side?: 'top' | 'right' | 'bottom' | 'left'
   sideOffset?: number
   className?: string
+  /** Appended to the dropdown content. To render the menu above a high-z
+   *  surface (drawer, modal), prefer wrapping that surface in a
+   *  `PortalContainerContext` provider rather than escalating z-index here. */
+  contentClassName?: string
   ariaLabel?: string
   /** Custom trigger element. When provided, replaces the default ellipsis icon button. */
   trigger?: React.ReactNode
@@ -38,6 +42,9 @@ export interface MoreActionsMenuProps {
   open?: boolean
   /** Called when the open state changes — use together with `open`. */
   onOpenChange?: (open: boolean) => void
+  /** Forwarded to the dropdown content. Call `e.preventDefault()` to stop
+   *  Radix returning focus (and its focus ring) to the trigger on close. */
+  onCloseAutoFocus?: (event: Event) => void
 }
 
 /**
@@ -50,10 +57,12 @@ export function MoreActionsMenu({
   side = 'bottom',
   sideOffset = 6,
   className,
+  contentClassName,
   ariaLabel = 'More actions',
   trigger,
   open,
-  onOpenChange
+  onOpenChange,
+  onCloseAutoFocus
 }: MoreActionsMenuProps) {
   return (
     <DropdownMenu open={open} onOpenChange={onOpenChange}>
@@ -73,7 +82,11 @@ export function MoreActionsMenu({
         align={align}
         side={side}
         sideOffset={sideOffset}
-        className="bg-ods-card border border-ods-border p-0 rounded-[4px] min-w-[200px]"
+        onCloseAutoFocus={onCloseAutoFocus}
+        className={cn(
+          'bg-ods-card border border-ods-border p-0 rounded-[4px] min-w-[200px]',
+          contentClassName,
+        )}
       >
         {items.map((item, idx) => {
           const itemClassName =

package/src/components/ui/portal-container.tsx

@@ -0,0 +1,28 @@
+'use client'
+
+import * as React from 'react'
+
+/**
+ * The DOM node that Radix overlays (dropdown menus, tooltips) should portal
+ * into, instead of the default `document.body`.
+ *
+ * Portaling to `document.body` lifts content out of every local stacking
+ * context, which forces overlays opened *inside* a high-z surface (e.g. the
+ * chat drawer) to escalate their own z-index to compete at the document
+ * root. Pointing the portal at a node *inside* that surface instead
+ * lets the content inherit the surface's stacking context — small, local
+ * z-indices then "just work" and no escalation is needed. Radix positions
+ * content with `strategy: "fixed"`, so it still escapes ancestor
+ * `overflow: hidden` clipping regardless of where it is portaled.
+ *
+ * Default `null` → Radix falls back to `document.body` (unchanged behaviour
+ * everywhere a provider isn't present).
+ */
+export const PortalContainerContext = React.createContext<HTMLElement | null>(
+  null,
+)
+
+/** Read the active portal container (or `null` to use `document.body`). */
+export function usePortalContainer(): HTMLElement | null {
+  return React.useContext(PortalContainerContext)
+}

package/src/components/ui/tooltip.tsx

@@ -3,6 +3,7 @@
 import * as React from "react"
 import * as TooltipPrimitive from "@radix-ui/react-tooltip"
 import { cn } from "../../utils/cn"
+import { usePortalContainer } from "./portal-container"
 
 const TooltipProvider = TooltipPrimitive.Provider
 
@@ -13,8 +14,12 @@ const TooltipTrigger = TooltipPrimitive.Trigger
 const TooltipContent = React.forwardRef<
   React.ElementRef<typeof TooltipPrimitive.Content>,
   React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>
->(({ className, sideOffset = 4, ...props }, ref) => (
-  <TooltipPrimitive.Portal>
+>(({ className, sideOffset = 4, ...props }, ref) => {
+  // Portal into the active container (e.g. a drawer) so the tooltip inherits
+  // its stacking context; falls back to `document.body` when none is provided.
+  const container = usePortalContainer()
+  return (
+  <TooltipPrimitive.Portal container={container ?? undefined}>
     <TooltipPrimitive.Content
       ref={ref}
       sideOffset={sideOffset}
@@ -25,7 +30,8 @@ const TooltipContent = React.forwardRef<
       {...props}
     />
   </TooltipPrimitive.Portal>
-))
+  )
+})
 TooltipContent.displayName = TooltipPrimitive.Content.displayName
 
 export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }

package/src/stories/AppLayoutSidebar.stories.tsx

@@ -0,0 +1,184 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite'
+import { useState } from 'react'
+import { fn } from 'storybook/test'
+
+import {
+  BracketCurlyIcon,
+  ChartDonutIcon,
+  IdCardIcon,
+  MonitorIcon,
+  Settings02Icon,
+} from '../components/icons-v2-generated'
+import {
+  AppLayout,
+  AppLayoutDrawer,
+  AppLayoutDrawerBody,
+  AppLayoutDrawerContent,
+  AppLayoutDrawerDescription,
+  AppLayoutDrawerHeader,
+  AppLayoutDrawerTitle,
+} from '../components/navigation'
+import { NavigationSidebarConfig } from '../types/navigation'
+
+const navigationItems: NavigationSidebarConfig['items'] = [
+  { id: 'dashboard', label: 'Dashboard', icon: <ChartDonutIcon size={24} />, path: '/dashboard', isActive: true },
+  { id: 'customers', label: 'Customers', icon: <IdCardIcon size={24} />, path: '/customers' },
+  { id: 'devices', label: 'Devices', icon: <MonitorIcon size={24} />, path: '/devices' },
+  { id: 'scripts', label: 'Scripts', icon: <BracketCurlyIcon size={24} />, path: '/scripts' },
+  { id: 'settings', label: 'Settings', icon: <Settings02Icon size={24} />, path: '/settings', section: 'secondary' },
+]
+
+const meta = {
+  title: 'Navigation/AppLayoutSidebar',
+  component: AppLayout,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: `
+\`AppLayout\` wired so the **Mingo AI** header button toggles a right-side,
+in-layout sidebar (an \`AppLayoutDrawer\`). The sidebar renders inside the
+main content area — the navigation sidebar and header stay visible and
+interactive while it is open.
+
+The header button reflects the open state via \`isMingoAIActive\`, and the
+sidebar is persistent: clicks on the header/sidebar/overlay do not close it
+(use the X button or Escape).
+        `,
+      },
+    },
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof AppLayout>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+function DashboardChildren() {
+  return (
+    <div className="space-y-6 p-6">
+      <div>
+        <h1 className="text-2xl font-semibold text-ods-text-primary">Devices Overview</h1>
+        <p className="text-ods-text-secondary mt-1">8,250 Devices in Total</p>
+      </div>
+      <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+        {[
+          { label: 'Active Devices', value: '6,930' },
+          { label: 'Active Tickets', value: '136' },
+          { label: 'Resolved Tickets', value: '825' },
+        ].map((stat) => (
+          <div key={stat.label} className="p-4 bg-ods-card rounded-lg border border-ods-border">
+            <p className="text-sm text-ods-text-secondary">{stat.label}</p>
+            <p className="text-2xl font-semibold text-ods-text-primary mt-1">{stat.value}</p>
+          </div>
+        ))}
+      </div>
+      <p className="text-ods-text-secondary">
+        Click <span className="font-medium text-ods-text-primary">Mingo AI</span> in the header to open the chat sidebar.
+      </p>
+    </div>
+  )
+}
+
+/**
+ * Mingo AI header button toggles the right-side chat sidebar.
+ */
+export const Default: Story = {
+  render: function Render() {
+    const [open, setOpen] = useState(false)
+    return (
+      <AppLayout
+        sidebarConfig={{ items: navigationItems, onNavigate: fn(), onToggleMinimized: fn() }}
+        headerProps={{
+          showNotifications: true,
+          showMingoAI: true,
+          onMingoAI: () => setOpen((prev) => !prev),
+          isMingoAIActive: open,
+          showUser: true,
+          userName: 'Alex Developer',
+          userEmail: 'alex@openframe.dev',
+          onProfile: fn(),
+          onLogout: fn(),
+        }}
+        mobileBurgerMenuProps={{
+          user: {
+            userName: 'Alex Developer',
+            userEmail: 'alex@openframe.dev',
+            userRole: 'Admin',
+          },
+        }}
+        drawer={
+          <AppLayoutDrawer open={open} onOpenChange={setOpen}>
+            <AppLayoutDrawerContent side="right">
+              <AppLayoutDrawerHeader>
+                <AppLayoutDrawerTitle>Mingo AI</AppLayoutDrawerTitle>
+                <AppLayoutDrawerDescription>
+                  Ask Mingo about your devices, tickets, and scripts.
+                </AppLayoutDrawerDescription>
+              </AppLayoutDrawerHeader>
+              <AppLayoutDrawerBody>
+                <p className="text-sm text-ods-text-secondary">Chat content goes here.</p>
+              </AppLayoutDrawerBody>
+            </AppLayoutDrawerContent>
+          </AppLayoutDrawer>
+        }
+      >
+        <DashboardChildren />
+      </AppLayout>
+    )
+  },
+}
+
+/**
+ * Resizable chat sidebar — drag the inside edge to resize. Starts open.
+ */
+export const Resizable: Story = {
+  render: function Render() {
+    const [open, setOpen] = useState(true)
+    return (
+      <AppLayout
+        sidebarConfig={{ items: navigationItems, onNavigate: fn(), onToggleMinimized: fn() }}
+        headerProps={{
+          showNotifications: true,
+          showMingoAI: true,
+          onMingoAI: () => setOpen((prev) => !prev),
+          isMingoAIActive: open,
+          showUser: true,
+          userName: 'Alex Developer',
+          userEmail: 'alex@openframe.dev',
+          onProfile: fn(),
+          onLogout: fn(),
+        }}
+        mobileBurgerMenuProps={{
+          user: {
+            userName: 'Alex Developer',
+            userEmail: 'alex@openframe.dev',
+            userRole: 'Admin',
+          },
+        }}
+        drawer={
+          <AppLayoutDrawer open={open} onOpenChange={setOpen}>
+            <AppLayoutDrawerContent
+              side="right"
+              resizable
+              minSize={360}
+              defaultSize={560}
+              storageKey="storybook:app-layout-sidebar:mingo"
+            >
+              <AppLayoutDrawerHeader>
+                <AppLayoutDrawerTitle>Mingo AI</AppLayoutDrawerTitle>
+              </AppLayoutDrawerHeader>
+              <AppLayoutDrawerBody>
+                <p className="text-sm text-ods-text-secondary">
+                  Drag the grip on the left edge to resize the chat sidebar.
+                </p>
+              </AppLayoutDrawerBody>
+            </AppLayoutDrawerContent>
+          </AppLayoutDrawer>
+        }
+      >
+        <DashboardChildren />
+      </AppLayout>
+    )
+  },
+}

package/src/stories/EmbeddableChat.stories.tsx

@@ -8,6 +8,7 @@ import {
 import { EmbeddableChat } from '../components/chat/embeddable-chat'
 import type { UseNatsChatAdapterConfig } from '../components/chat/hooks/use-nats-chat-adapter'
 import type { SlashCommandSummary } from '../components/chat/hooks/use-slash-commands'
+import type { DialogItem } from '../components/chat/types/component.types'
 
 // =============================================================================
 // Stub commands endpoint — module-level constant referenced both by the
@@ -59,6 +60,92 @@ function createMockMingoConfig(): UseNatsChatAdapterConfig {
       // eslint-disable-next-line no-console
       console.log('[story] mingo publish', { text, options })
     },
+    // Selecting a dialog loads its history via this callback — without it
+    // `hasMessages` stays false and the panel never switches to the
+    // conversation view. Return a tiny canned thread so clicks "open" a chat.
+    fetchDialogMessages: ({ dialogId }) =>
+      Promise.resolve({
+        messages: [
+          {
+            id: `${dialogId}-u1`,
+            createdAt: new Date().toISOString(),
+            owner: { type: 'CLIENT' },
+            messageData: {
+              type: 'TEXT',
+              text: 'Which devices have not sent any logs in the last 24 hours?',
+            },
+          },
+          {
+            id: `${dialogId}-a1`,
+            createdAt: new Date().toISOString(),
+            owner: { type: 'ASSISTANT' },
+            messageData: {
+              type: 'TEXT',
+              text: 'Found 3 devices that have not reported in over 24 hours. Want me to run a full diagnostic?',
+            },
+          },
+        ],
+        nextCursor: null,
+      }),
+  }
+}
+
+// Sample dialog history (Figma node 7532:223950) — supplied via `fetchDialogs`
+// so EmbeddableChat reports `dialogs.length > 0` and renders MingoWelcome's
+// returning-user variation (outline "Start Guide Chat" chip, no promo).
+const SAMPLE_DIALOGS: ReadonlyArray<DialogItem> = [
+  { id: 'd1', title: 'PowerShell script for bulk user creation', unreadMessagesCount: 1 },
+  { id: 'd2', title: 'Setting up automated backup verification', unreadMessagesCount: 1 },
+  { id: 'd3', title: 'Network segmentation best practices for client' },
+  { id: 'd4', title: 'Creating GPO for software deployment' },
+  { id: 'd5', title: 'WSUS patching strategy optimization' },
+  { id: 'd6', title: 'Office 365 license assignment automation' },
+  { id: 'd7', title: 'Firewall rule configuration for new application' },
+  { id: 'd8', title: 'SQL Server maintenance plan troubleshooting' },
+]
+
+/** Mingo config whose `fetchDialogs` resolves a single page of history (with
+ *  timestamps so the list splits into Today / Yesterday) plus working
+ *  rename/archive callbacks — used by the returning-user story. */
+function createMockMingoConfigWithDialogs(): UseNatsChatAdapterConfig {
+  return {
+    ...createMockMingoConfig(),
+    fetchDialogs: () => {
+      const now = Date.now()
+      const day = 24 * 60 * 60 * 1000
+      // First six → Today, the rest → Yesterday.
+      const dialogs = SAMPLE_DIALOGS.map((d, i) => ({
+        ...d,
+        timestamp: new Date(now - (i < 6 ? 0 : day)),
+      }))
+      return Promise.resolve({ dialogs, nextCursor: null })
+    },
+    renameDialog: (id, title) => {
+      // eslint-disable-next-line no-console
+      console.log('[story] mingo rename', { id, title })
+      return Promise.resolve()
+    },
+    archiveDialog: (id) => {
+      // eslint-disable-next-line no-console
+      console.log('[story] mingo archive', { id })
+      return Promise.resolve()
+    },
+    fetchArchivedDialogs: () => {
+      const now = Date.now()
+      const day = 24 * 60 * 60 * 1000
+      const dialogs: DialogItem[] = [
+        { id: 'a1', title: 'Exchange hybrid migration planning', timestamp: new Date(now) },
+        { id: 'a2', title: 'VPN split-tunnel configuration review', timestamp: new Date(now) },
+        { id: 'a3', title: 'Decommissioning legacy file server', timestamp: new Date(now - day) },
+        { id: 'a4', title: 'Intune compliance policy rollout', timestamp: new Date(now - day) },
+      ]
+      return Promise.resolve({ dialogs, nextCursor: null })
+    },
+    unarchiveDialog: (id) => {
+      // eslint-disable-next-line no-console
+      console.log('[story] mingo unarchive', { id })
+      return Promise.resolve()
+    },
   }
 }
 
@@ -354,3 +441,30 @@ export const BothModes: Story = {
   ),
   args: {},
 }
+
+// =============================================================================
+// 4. Returning user — Mingo with existing chats (Figma node 7532:223950)
+// =============================================================================
+
+/**
+ * Returning-user variation. The mock `fetchDialogs` resolves a page of dialog
+ * history, so `dialogs.length > 0` and the empty state switches to its
+ * returning-user form: the "New to OpenFrame?" notification is hidden and the
+ * "Start Guide Chat" chip drops from the accent yellow to the muted outline
+ * style. The dialog list itself renders inline via MingoChatHistory.
+ */
+export const ReturningUser: Story = {
+  render: (args) => (
+    <EmbeddableChat
+      {...args}
+      modes={{
+        guide: {},
+        mingo: createMockMingoConfigWithDialogs(),
+      }}
+      defaultActiveMode="mingo"
+      defaultOpen
+      showInternalTrigger={false}
+    />
+  ),
+  args: {},
+}