@flamingo-stack/openframe-frontend-core 0.0.319 → 0.0.321

package/src/components/chat/chat-message-enhanced.tsx

@@ -25,7 +25,7 @@ import type { MessageSegment, MessageContent, ChatMessageEnhancedProps } from ".
  *  item would be stripped from the chip strip yet never rendered inline — lost
  *  from display entirely. The id is capture group 2 (group 1 is the boundary).
  *  Marker lowercase; id is the mention-token charset. */
-const MENTION_MARKER_REGEX = /(^|\s)@[a-z]+:([A-Za-z0-9_.+/=-]+)/g
+const MENTION_MARKER_REGEX = /(^|[^\w@])@[a-z]+:([A-Za-z0-9_.+/=-]*[A-Za-z0-9_+/=])/g
 
 /**
  * Same regex shape as `remarkCardLinks` — kept in lockstep so the
@@ -43,7 +43,7 @@ function normalizeContent(content: MessageContent): MessageSegment[] {
 }
 
 const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>(
-  ({ className, role, content, name, avatar, isTyping = false, timestamp, showAvatar = true, assistantType, authorType: authorTypeProp, assistantIcon, chatRefs, contextItems, resolveContextIcon, renderMention, renderEntityCard, NavLinkAnchor, ...props }, ref) => {
+  ({ className, role, content, name, avatar, isTyping = false, timestamp, showAvatar = true, assistantType, authorType: authorTypeProp, assistantIcon, chatRefs, contextItems, resolveContextIcon, renderContextItem, renderMention, renderEntityCard, NavLinkAnchor, ...props }, ref) => {
     const isUser = role === 'user'
     const isError = role === 'error'
     const authorType = authorTypeProp ?? (isUser ? 'user' : assistantType === 'mingo' ? 'mingo' : 'fae')
@@ -595,6 +595,7 @@ const ChatMessageEnhanced = forwardRef<HTMLDivElement, ChatMessageEnhancedProps>
             <ChatContextChipStrip
               items={stripContextItems}
               resolveIcon={resolveContextIcon}
+              renderItem={renderContextItem}
               className="mt-2"
             />
           )}
@@ -628,6 +629,7 @@ const MemoizedChatMessageEnhanced = memo(ChatMessageEnhanced, (prevProps, nextPr
     // message (it's set once on the optimistic send and never mutated).
     prevProps.contextItems === nextProps.contextItems &&
     prevProps.resolveContextIcon === nextProps.resolveContextIcon &&
+    prevProps.renderContextItem === nextProps.renderContextItem &&
     // Host keeps this stable (module const / useCallback), so reference
     // equality holds across streaming chunks.
     prevProps.renderMention === nextProps.renderMention &&

package/src/components/chat/chat-message-list.tsx

@@ -107,6 +107,7 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
       onLoadMore,
       renderEntityCard,
       resolveContextIcon,
+      renderContextItem,
       renderMention,
       NavLinkAnchor,
       ...props
@@ -539,6 +540,7 @@ const ChatMessageList = forwardRef<HTMLDivElement, ChatMessageListProps>(
                   chatRefs={message.chatRefs}
                   contextItems={message.contextItems}
                   resolveContextIcon={resolveContextIcon}
+                  renderContextItem={renderContextItem}
                   renderMention={renderMention}
                   renderEntityCard={renderEntityCard}
                   NavLinkAnchor={NavLinkAnchor}

package/src/components/chat/context-items-list.tsx

@@ -141,7 +141,15 @@ export function ContextItemsList({
   }
 
   return (
-    <div role="listbox" aria-label="Items" onScroll={onScroll} className={cn('max-h-[340px] overflow-y-auto', className)}>
+    <div
+      role="listbox"
+      aria-label="Items"
+      onScroll={onScroll}
+      // Cap to 340px but never exceed ~half the viewport, so on short screens the
+      // results list (inside the bottom-anchored picker popover) still fits and
+      // scrolls instead of overflowing past the top edge.
+      className={cn('max-h-[min(340px,45vh)] overflow-y-auto', className)}
+    >
       {items.map(item => {
         const selected = selectedKeys.has(itemKey(item))
         return (

package/src/components/chat/embeddable-chat.tsx

@@ -271,6 +271,16 @@ export interface EmbeddableChatProps {
    * marker the host can't render → the lib falls back to the bare token.
    */
   renderMention?: (reference: { marker: string; id: string }) => React.ReactNode
+  /**
+   * Host renderer that REPLACES the default label-only context chip on a sent
+   * user bubble with a self-fetching entity chip — so a user's manually
+   * attached context (`contextItems`) renders IDENTICALLY to an inline
+   * `@marker:id` mention (same live name resolution + link). Mirror of
+   * `renderMention`, for the attached-chip strip instead of inline tokens.
+   * Return null for an item the host can't render → the lib falls back to the
+   * label pill. Keep the identity stable (module const / `useCallback`).
+   */
+  renderContextItem?: (item: ChatContextItem) => React.ReactNode
 }
 
 // =============================================================================
@@ -691,6 +701,7 @@ function EmbeddableChatInner({
   guideWelcome,
   contextPicker,
   renderMention,
+  renderContextItem,
 }: EmbeddableChatProps) {
   // `shell === 'none'` means the consumer hosts us inside their own panel
   // (e.g. AppLayoutDrawer in openframe-frontend). Several drawer-shell
@@ -986,9 +997,10 @@ function EmbeddableChatInner({
   useEffect(() => {
     mentionActiveRef.current = mentionQuery !== null
   }, [mentionQuery])
-  // The one mention reference currently in the draft (`"<type>:<id>"`), or null.
-  // Source of truth = the input text: deleting the `@type:id` token drops it.
-  const mentionKeyRef = useRef<string | null>(null)
+  // Keys (`"<type>:<id>"`) of context items that were committed via `@` and so
+  // have a `@type:id` token in the draft text. MULTI-mention: several coexist.
+  // Source of truth = the input text — deleting a token's chip drops its item.
+  const mentionKeysRef = useRef<Set<string>>(new Set())
 
   // Staged picker selection is per-conversation and Mingo-only. Clear it (and the
   // mention bookkeeping) whenever the active dialog changes or the mode toggles,
@@ -998,7 +1010,7 @@ function EmbeddableChatInner({
   useEffect(() => {
     setContextItems([])
     setMentionQuery(null)
-    mentionKeyRef.current = null
+    mentionKeysRef.current.clear()
   }, [activeDialogId, activeMode])
 
   // Map each entity type to its backend mention marker (host-declared on the
@@ -1010,35 +1022,35 @@ function EmbeddableChatInner({
     return m
   }, [contextPicker?.entityTypes])
 
+  // Stable type → icon resolver (entity-type glyph). Used both for the inline
+  // composer chips (`commitMention` meta) and the message-bubble context chips.
+  // Keyed on `entityTypes` only so an inline `contextPicker={{…}}` doesn't
+  // rebuild it every render (its identity flows into the message memo).
+  const contextEntityTypes = contextPicker?.entityTypes
+  const resolveContextIcon = useMemo(() => {
+    const byType = new Map<string, React.ReactNode>()
+    for (const t of contextEntityTypes ?? []) byType.set(t.type, t.icon)
+    return (item: ChatContextItem) => byType.get(item.type)
+  }, [contextEntityTypes])
+
   const toggleContextItem = useCallback(
     (item: ChatContextItem) => {
       const key = `${item.type}:${item.id}`
-      // `@`-mention flow → SINGLE-SELECT: commit `@type:id` into the draft
-      // (which also strips any prior mention token) so the picked entity stays
-      // visible in the input AND rides out in the context. Exactly one mention
-      // item is kept. The `+` flow (mention inactive) stays multi-select.
+      // `@`-mention flow → MULTI-select: commit a `@type:id` chip into the draft
+      // (prior mentions left in place) so each picked entity stays visible inline
+      // AND rides out in the context. The `+` flow (mention inactive) is the same
+      // multi-select on the chip strip.
       if (mentionActiveRef.current) {
-        // Single-select replaces any prior mention item and dedupes, so it only
-        // grows the selection when adding a brand-new item with no prior mention
-        // to swap out. Honour `maxItems` in that one growth case (parity with
-        // the `+` branch) so the `@` flow can't push past the cap — and don't
-        // commit the `@type:id` token into the draft if we're going to ignore it.
-        const alreadySelected = contextItems.some(
-          (p) => `${p.type}:${p.id}` === key,
-        )
-        const grows = !alreadySelected && !mentionKeyRef.current
-        if (grows && contextItems.length >= contextMaxItems) return
-        chatInputRef.current?.commitMention(mentionTokenOf(key, mentionMarkerByType))
-        setContextItems((prev) => {
-          const withoutPrevMention = mentionKeyRef.current
-            ? prev.filter((p) => `${p.type}:${p.id}` !== mentionKeyRef.current)
-            : prev
-          const deduped = withoutPrevMention.filter(
-            (p) => `${p.type}:${p.id}` !== key,
-          )
-          return [...deduped, item]
+        // Already attached → no-op (the picker's `@` flow is add-then-close; the
+        // chip already lives in the draft). Honour `maxItems` on growth.
+        if (contextItems.some((p) => `${p.type}:${p.id}` === key)) return
+        if (contextItems.length >= contextMaxItems) return
+        chatInputRef.current?.commitMention(mentionTokenOf(key, mentionMarkerByType), {
+          label: item.label,
+          icon: resolveContextIcon(item),
         })
-        mentionKeyRef.current = key
+        setContextItems((prev) => [...prev, item])
+        mentionKeysRef.current.add(key)
         return
       }
       setContextItems((prev) => {
@@ -1048,32 +1060,32 @@ function EmbeddableChatInner({
         return [...prev, item]
       })
     },
-    [contextMaxItems, contextItems, mentionMarkerByType],
+    [contextMaxItems, contextItems, mentionMarkerByType, resolveContextIcon],
   )
 
   const removeContextItem = useCallback((item: ChatContextItem) => {
     const key = `${item.type}:${item.id}`
     setContextItems((prev) => prev.filter((p) => `${p.type}:${p.id}` !== key))
-    // Removing the mention chip must also strip its `@type:id` token from the
-    // draft, keeping text and context in lockstep (the inverse of deleting the
-    // token text, which drops the chip via `handleContextValueChange`).
-    if (mentionKeyRef.current === key) {
-      mentionKeyRef.current = null
+    // Removing a mention-backed chip must also strip its `@type:id` token from
+    // the draft, keeping text and context in lockstep (the inverse of deleting
+    // the chip in the input, which drops the item via `handleContextValueChange`).
+    if (mentionKeysRef.current.has(key)) {
+      mentionKeysRef.current.delete(key)
       const cur = chatInputRef.current?.getValue() ?? ''
       const next = cur.replace(`@${mentionTokenOf(key, mentionMarkerByType)}`, '').replace(/\s{2,}/g, ' ').trimStart()
       chatInputRef.current?.setValue(next)
     }
   }, [mentionMarkerByType])
 
-  // Draft → context reconciliation: when the user deletes the `@type:id` token
-  // text, drop the matching mention item. `+`-added items have no token in the
-  // text and are never touched here.
+  // Draft → context reconciliation: when the user deletes a `@type:id` chip from
+  // the input, drop the matching mention item. Checks EVERY token-backed key
+  // (multi-mention). `+`-added items have no token in the text and are untouched.
   const handleContextValueChange = useCallback((value: string) => {
-    const key = mentionKeyRef.current
-    if (!key) return
-    if (!value.includes(`@${mentionTokenOf(key, mentionMarkerByType)}`)) {
-      setContextItems((prev) => prev.filter((p) => `${p.type}:${p.id}` !== key))
-      mentionKeyRef.current = null
+    for (const key of Array.from(mentionKeysRef.current)) {
+      if (!value.includes(`@${mentionTokenOf(key, mentionMarkerByType)}`)) {
+        mentionKeysRef.current.delete(key)
+        setContextItems((prev) => prev.filter((p) => `${p.type}:${p.id}` !== key))
+      }
     }
   }, [mentionMarkerByType])
 
@@ -1102,20 +1114,6 @@ function EmbeddableChatInner({
     setContextPickerOpen(query !== null)
   }, [])
 
-  // Stable type → icon resolver for the message-bubble context chips. Built
-  // from the host's `contextPicker.entityTypes`; null-safe when the feature
-  // is off. Keyed on `entityTypes` (NOT the whole `contextPicker` object) so an
-  // inline `contextPicker={{…}}` on the host doesn't rebuild this resolver every
-  // render — that identity flows into the `ChatMessageEnhanced` memo, and a new
-  // function each render would force a full markdown re-render of every message
-  // on each keystroke.
-  const contextEntityTypes = contextPicker?.entityTypes
-  const resolveContextIcon = useMemo(() => {
-    const byType = new Map<string, React.ReactNode>()
-    for (const t of contextEntityTypes ?? []) byType.set(t.type, t.icon)
-    return (item: ChatContextItem) => byType.get(item.type)
-  }, [contextEntityTypes])
-
   // `renderMention` is HOST-provided (see the prop doc): the per-type renderer
   // for inline AI mentions `@marker:id` (mirror of `renderEntityCard`). The lib
   // forwards it verbatim to the message list and calls it from the `mention://`
@@ -1580,6 +1578,7 @@ function EmbeddableChatInner({
                       assistantIcon={mingoAssistantIcon}
                       renderEntityCard={renderEntityCard}
                       resolveContextIcon={resolveContextIcon}
+                      renderContextItem={renderContextItem}
                       renderMention={renderMention}
                       NavLinkAnchor={NavLinkAnchorViaRuntime}
                       className="flex-1"

package/src/components/chat/remark-mention-chips.ts

@@ -18,18 +18,24 @@
  *   - marker: `[a-z]+` — the backend `ContextItemType.marker()` short form
  *     (`device`, `script`, `ticket`, `organization`, `user`, `kb`, `policy`,
  *     `query`, …). Always lowercase.
- *   - id: `[A-Za-z0-9_.+/=-]+` — the mention-token charset (UUIDs with hyphens,
- *     fleet numeric ids, etc.). Matches the composer's `MENTION_TOKEN`.
- *   - A LEFT boundary (start-of-text or whitespace) keeps `@marker:` from
- *     matching inside emails / mid-word (`user@host:1234` never starts a token
- *     because the `@` isn't at a boundary).
+ *   - id: charset `[A-Za-z0-9_.+/=-]` (UUIDs with hyphens, fleet numeric ids,
+ *     base64 global ids, etc.; matches the composer's `MENTION_TOKEN`) — but the
+ *     id may NOT END in `.` or `-`, so a trailing SENTENCE period/dash isn't
+ *     swallowed into the id (`@script:38.` → id `38`, with the `.` left as text).
+ *     Base64 padding `=` and `+`/`/` are still valid final chars.
+ *   - A LEFT boundary (start-of-text or any non-word, non-`@` character) keeps
+ *     `@marker:` from matching inside emails / mid-word (`user@host:1234` never
+ *     starts a token because the `@` is preceded by a word char), while still
+ *     firing when the agent wraps a mention in punctuation — parentheses,
+ *     brackets, quotes — e.g. `(@device:64f0a1)`. The boundary character (if
+ *     any) is captured as `lead` and re-emitted as text, so it is preserved.
  */
 
 import type { Plugin } from 'unified'
 import type { Root, Text, Link } from 'mdast'
 import { visit, SKIP } from 'unist-util-visit'
 
-const MENTION_REGEX = /(^|\s)@([a-z]+):([A-Za-z0-9_.+/=-]+)/g
+const MENTION_REGEX = /(^|[^\w@])@([a-z]+):([A-Za-z0-9_.+/=-]*[A-Za-z0-9_+/=])/g
 
 export const remarkMentionChips: Plugin<[], Root> = () => {
   return (tree: Root) => {
@@ -43,7 +49,7 @@ export const remarkMentionChips: Plugin<[], Root> = () => {
       MENTION_REGEX.lastIndex = 0
       let match: RegExpExecArray | null
       while ((match = MENTION_REGEX.exec(text)) !== null) {
-        const lead = match[1] // '' or the whitespace char before '@'
+        const lead = match[1] // '' or the boundary char before '@' (space, '(', etc.)
         const marker = match[2]
         const id = match[3]
         const tokenStart = match.index + lead.length // position of '@'

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

@@ -132,6 +132,17 @@ export interface ChatMessageEnhancedProps extends Omit<HTMLAttributes<HTMLDivEle
    * glyph). Optional — chips render label-only when omitted.
    */
   resolveContextIcon?: (item: ChatContextItem) => ReactNode
+  /**
+   * Host renderer that REPLACES the default label-only context chip for an
+   * attached item with a self-fetching entity chip — so a user's manually
+   * attached context renders IDENTICALLY to an inline `@marker:id` mention
+   * (same live name resolution, same link). Mirror of `renderMention`, but for
+   * the `contextItems` strip instead of inline tokens. Return `null` for an
+   * item the host can't render → the lib falls back to the label pill. Keep the
+   * function identity stable (module const / `useCallback`) so the message memo
+   * holds across streaming chunks.
+   */
+  renderContextItem?: (item: ChatContextItem) => ReactNode
   /**
    * Host renderer for inline AI mentions `@marker:id` — the ASSISTANT echoing
    * `@device:<machineId>` (etc.) in its reply. DIRECT MIRROR of
@@ -215,6 +226,10 @@ export interface ChatMessageListProps extends HTMLAttributes<HTMLDivElement> {
   /** Lead-icon resolver for per-message context chips (maps a context item to
    *  its entity-type glyph). Forwarded to every message's ChatMessageEnhanced. */
   resolveContextIcon?: (item: ChatContextItem) => ReactNode
+  /** Host renderer that REPLACES the default context chip with a self-fetching
+   *  entity chip (so attached context renders like an inline mention).
+   *  Forwarded verbatim to every message's ChatMessageEnhanced. */
+  renderContextItem?: (item: ChatContextItem) => ReactNode
   /** Host renderer for inline AI mentions `@marker:id` (mirror of
    *  `renderEntityCard`). Forwarded verbatim to every message's
    *  ChatMessageEnhanced; returns a self-fetching chip per entity type. */
@@ -408,13 +423,22 @@ export interface ChatInputRef {
    *  context item / closes the picker so the `@query` scaffolding doesn't get
    *  sent as literal text. No-op when no mention token is active. */
   removeMentionTrigger: () => void
-  /** Commit a SINGLE-SELECT mention: replace the trailing `@query` being typed
-   *  with the literal `@<type>:<id>` token (`token` = `"<type>:<id>"`, plus a
-   *  trailing space) and strip any previously committed token so only one
-   *  mention reference lives in the draft. Used by the composer's `@`-mention
-   *  flow so the picked entity stays visible in the input AND rides out in the
-   *  context — deleting the token text removes it from context. */
-  commitMention: (token: string) => void
+  /** Commit a mention: replace the trailing `@query` being typed with the
+   *  literal `@<type>:<id>` token (`token` = `"<type>:<id>"`, plus a trailing
+   *  space). MULTIPLE mentions coexist — prior committed tokens are left in
+   *  place. The optional `meta` gives the inline chip its display name + icon
+   *  (the contenteditable renders the token as a chip); without it the chip
+   *  falls back to the id. Used by the composer's `@`-mention flow so the picked
+   *  entity rides out in the context — deleting the chip removes it from context. */
+  commitMention: (token: string, meta?: MentionMeta) => void
+}
+
+/** Display metadata for an inline mention chip rendered inside the composer. */
+export interface MentionMeta {
+  /** Resolved entity name shown in the chip (e.g. `'ELK-PROD-07'`). */
+  label: string
+  /** Optional lead icon (entity-type glyph). */
+  icon?: ReactNode
 }
 
 // ========== Chat Typing Indicator Props ==========

package/src/components/features/index.ts

@@ -48,6 +48,7 @@ export * from './social-links-manager'
 export * from './start-with-openframe-button'
 export * from './status-filter-component'
 export * from './tags-selector'
+export * from './warning-block'
 // Unified video primitives — single source of truth across all platforms.
 // `<Video>` replaces the deleted `<VideoPlayer>` + `<YouTubeEmbed>` pair;
 // `<EntityVideoSection>` + `<VideoBitesDisplay>` are the public detail-page

package/src/components/features/paths-display.tsx

@@ -39,6 +39,13 @@ export interface PathsDisplayProps {
    * Size of the copy icon (default: 'w-6 h-6')
    */
   copyIconSize?: string
+
+  /**
+   * Optional icon rendered at the start of every row, before the path text.
+   * Useful for showing a platform logo next to a command (e.g. the Windows
+   * logo beside "Run PowerShell as Local Administrator").
+   */
+  leadingIcon?: React.ReactNode
 }
 
 /**
@@ -77,7 +84,8 @@ export function PathsDisplay({
   description,
   className,
   showCopyButtons = true,
-  copyIconSize = 'w-6 h-6'
+  copyIconSize = 'w-6 h-6',
+  leadingIcon
 }: PathsDisplayProps) {
   if (!paths || paths.length === 0) {
     return null
@@ -101,6 +109,9 @@ export function PathsDisplay({
             key={path}
             className="flex items-center gap-4 p-4 border-b border-ods-border last:border-b-0"
           >
+            {leadingIcon && (
+              <span className="shrink-0 text-ods-text-primary">{leadingIcon}</span>
+            )}
             <span className="flex-1 min-w-0 text-h4 text-ods-text-primary truncate">
               {path}
             </span>
@@ -152,3 +163,23 @@ export type OpenFramePathsPlatform = keyof typeof OPENFRAME_PATHS
 export function getOpenFramePaths(platform: OpenFramePathsPlatform): string[] {
   return [...OPENFRAME_PATHS[platform]]
 }
+
+/**
+ * Doctor command per platform. Run to diagnose installation issues and repair
+ * the agent (works even if the agent didn't install correctly).
+ */
+export const OPENFRAME_DOCTOR_COMMANDS: Record<OpenFramePathsPlatform, string> = {
+  // PowerShell: Invoke-WebRequest / .\openframe-client.exe, mirroring the
+  // Windows install command pattern.
+  windows:
+    "Set-Location ~; Invoke-WebRequest -Uri 'github.com/openframe-client' -OutFile 'openframe-client.exe'; .\\openframe-client.exe doctor",
+  darwin: 'cd ~; wget github.com/openframe-client; openframe-client doctor',
+  linux: 'cd ~; wget github.com/openframe-client; openframe-client doctor'
+} as const
+
+/**
+ * Get the OpenFrame doctor command for a specific platform
+ */
+export function getOpenFrameDoctorCommand(platform: OpenFramePathsPlatform): string {
+  return OPENFRAME_DOCTOR_COMMANDS[platform]
+}

package/src/components/features/warning-block.tsx

@@ -0,0 +1,54 @@
+'use client'
+
+import { AlertTriangle } from 'lucide-react'
+import React from 'react'
+import { cn } from '../../utils/cn'
+
+export interface WarningBlockProps {
+  /** Text rendered inside the highlighted warning banner header. */
+  title: React.ReactNode
+  /**
+   * Icon shown at the start of the banner. Defaults to a triangle alert icon.
+   * Pass `null` to hide the icon entirely.
+   */
+  icon?: React.ReactNode
+  /**
+   * Body content rendered below the banner — description paragraphs, one or more
+   * `PathsDisplay` lists, command rows, etc. Fully composable so a single block
+   * can mix text and multiple path groups (see the New Device warning blocks).
+   */
+  children?: React.ReactNode
+  /** Extra classes for the outer card container. */
+  className?: string
+}
+
+const DEFAULT_ICON = <AlertTriangle className="h-6 w-6" />
+
+/**
+ * WarningBlock - a card with a highlighted "attention / warning" banner header
+ * followed by arbitrary body content.
+ *
+ * The banner reproduces the ODS warning callout (warning color on a muted
+ * warning background). Body content is fully composable: pass description
+ * paragraphs, one or more `PathsDisplay` lists, command rows, etc. as children.
+ *
+ * Spacing follows the ODS scale: card padding 16px / gap 12px, banner padding
+ * 12px / gap 16px. Typography uses `text-h3`, which is responsive (14px on
+ * mobile, 18px from `md` up) and bold by design-token default.
+ */
+export function WarningBlock({ title, icon = DEFAULT_ICON, children, className }: WarningBlockProps) {
+  return (
+    <div
+      className={cn(
+        'flex flex-col gap-3 rounded-[6px] border border-ods-border bg-ods-card p-4',
+        className
+      )}
+    >
+      <div className="flex items-start gap-4 overflow-hidden rounded-[6px] bg-ods-warning-secondary p-3 text-ods-warning">
+        {icon != null && <span className="shrink-0">{icon}</span>}
+        <p className="min-w-0 flex-1 text-h3">{title}</p>
+      </div>
+      {children}
+    </div>
+  )
+}

package/src/stories/WarningBlock.stories.tsx

@@ -0,0 +1,167 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite';
+import { OSTypeIcon } from '../components/features/os-type-badge';
+import { OPENFRAME_DOCTOR_COMMANDS, PathsDisplay } from '../components/features/paths-display';
+import { WarningBlock } from '../components/features/warning-block';
+
+const meta = {
+  title: 'Features/WarningBlock',
+  component: WarningBlock,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A card with a highlighted "attention / warning" banner header followed by composable body content. Body is passed as children, so a single block can mix description paragraphs with one or more `PathsDisplay` lists (see the New Device warning blocks). Typography is responsive via ODS tokens (14px on mobile, 18px from `md` up).',
+      },
+    },
+  },
+  argTypes: {
+    title: { control: 'text' },
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ maxWidth: 720 }}>
+        <Story />
+      </div>
+    ),
+  ],
+} satisfies Meta<typeof WarningBlock>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const copyPath = (path: string) => {
+  if (typeof navigator !== 'undefined' && navigator.clipboard) {
+    void navigator.clipboard.writeText(path);
+  }
+};
+
+/** Minimal usage — a banner title with a single description paragraph. */
+export const Default: Story = {
+  args: {
+    title: 'Administrator privileges are required to install the OpenFrame agent.',
+    children: (
+      <p className="text-h4 text-ods-text-primary">
+        Run the command with the appropriate permissions for your platform.
+      </p>
+    ),
+  },
+};
+
+/**
+ * Antivirus warning from the New Device screen — description, a `PathsDisplay`
+ * list of exclusion folders, then a closing paragraph.
+ */
+export const AntivirusWarning: Story = {
+  args: {
+    title: 'Your antivirus may block OpenFrame installation. This is a false positive.',
+    children: (
+      <>
+        <PathsDisplay
+          title="If blocked, add these folders to your antivirus exclusions list:"
+          paths={['C:\\Program Files\\OpenFrame\\', 'C:\\Users\\[Username]\\AppData\\Local\\OpenFrame\\']}
+          onCopyPath={copyPath}
+        />
+        <p className="text-h4 text-ods-text-primary">
+          Or temporarily disable protection during installation. OpenFrame is safe open-source software.
+          Blocks happen because new software needs time to build reputation with security vendors.
+        </p>
+      </>
+    ),
+  },
+};
+
+/**
+ * Doctor mode warning from the New Device screen — description plus a single
+ * copyable command row.
+ */
+export const DoctorMode: Story = {
+  args: {
+    title: 'Device not appearing or stuck pending?',
+    children: (
+      <>
+        <p className="text-h4 text-ods-text-primary">
+          Run the doctor command to diagnose installation issues and repair the agent. It works even if
+          the agent didn&apos;t install correctly.
+        </p>
+        <PathsDisplay
+          paths={[OPENFRAME_DOCTOR_COMMANDS.windows]}
+          onCopyPath={copyPath}
+        />
+      </>
+    ),
+  },
+};
+
+/**
+ * Administrator privileges warning — a platform-specific instruction row (no
+ * copy button) framed by description paragraphs.
+ */
+export const AdministratorPrivileges: Story = {
+  args: {
+    title: 'Administrator privileges are required to install the OpenFrame agent.',
+    children: (
+      <>
+        <p className="text-h4 text-ods-text-primary">
+          Run the command with the appropriate permissions for your platform:
+        </p>
+        <PathsDisplay
+          paths={['Run PowerShell as Local Administrator']}
+          showCopyButtons={false}
+          leadingIcon={<OSTypeIcon osType="windows" size="w-6 h-6" />}
+        />
+        <p className="text-h4 text-ods-text-primary">
+          Without elevated privileges, the installation will fail silently. Right-click PowerShell and
+          select &quot;Run as administrator,&quot; or contact your IT admin if you don&apos;t have local
+          admin rights.
+        </p>
+      </>
+    ),
+  },
+};
+
+/** All three New Device warning blocks stacked, matching the Figma layout. */
+export const NewDeviceBlocks: Story = {
+  args: { title: '' },
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <WarningBlock title="Administrator privileges are required to install the OpenFrame agent.">
+        <p className="text-h4 text-ods-text-primary">
+          Run the command with the appropriate permissions for your platform:
+        </p>
+        <PathsDisplay
+          paths={['Run PowerShell as Local Administrator']}
+          showCopyButtons={false}
+          leadingIcon={<OSTypeIcon osType="windows" size="w-6 h-6" />}
+        />
+        <p className="text-h4 text-ods-text-primary">
+          Without elevated privileges, the installation will fail silently. Right-click PowerShell and
+          select &quot;Run as administrator,&quot; or contact your IT admin if you don&apos;t have local
+          admin rights.
+        </p>
+      </WarningBlock>
+
+      <WarningBlock title="Your antivirus may block OpenFrame installation. This is a false positive.">
+        <PathsDisplay
+          title="If blocked, add these folders to your antivirus exclusions list:"
+          paths={['C:\\Program Files\\OpenFrame\\', 'C:\\Users\\[Username]\\AppData\\Local\\OpenFrame\\']}
+          onCopyPath={copyPath}
+        />
+        <p className="text-h4 text-ods-text-primary">
+          Or temporarily disable protection during installation. OpenFrame is safe open-source software.
+          Blocks happen because new software needs time to build reputation with security vendors.
+        </p>
+      </WarningBlock>
+
+      <WarningBlock title="Device not appearing or stuck pending?">
+        <p className="text-h4 text-ods-text-primary">
+          Run the doctor command to diagnose installation issues and repair the agent. It works even if
+          the agent didn&apos;t install correctly.
+        </p>
+        <PathsDisplay
+          paths={[OPENFRAME_DOCTOR_COMMANDS.windows]}
+          onCopyPath={copyPath}
+        />
+      </WarningBlock>
+    </div>
+  ),
+};