@signalflare-ai/ui 0.5.0 → 1.0.0

package/ai/component-registry.json

@@ -30,10 +30,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "text-sf-default",
-        "text-sf-subtle"
-      ]
+      "colors": ["text-sf-default", "text-sf-subtle"]
     },
     "AiAgentCard": {
       "name": "AiAgentCard",
@@ -55,12 +52,7 @@
           "type": "enum",
           "optional": true,
           "description": "Current status.",
-          "values": [
-            "idle",
-            "running",
-            "completed",
-            "error"
-          ],
+          "values": ["idle", "running", "completed", "error"],
           "descriptions": {
             "idle": "Agent is idle, not yet started",
             "running": "Agent is actively working",
@@ -103,10 +95,7 @@
           "type": "enum",
           "optional": true,
           "description": "Card size.",
-          "values": [
-            "sm",
-            "md"
-          ],
+          "values": ["sm", "md"],
           "descriptions": {
             "sm": "Compact card for dense grids",
             "md": "Default card size"
@@ -120,11 +109,7 @@
         "type": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "submit",
-            "reset",
-            "button"
-          ]
+          "values": ["submit", "reset", "button"]
         },
         "value": {
           "type": "string | string[] | number",
@@ -177,10 +162,7 @@
           "type": "enum",
           "optional": true,
           "description": "Approval kind — `\"tool\"` for individual tool calls, `\"plan\"` for multi-step plans.",
-          "values": [
-            "tool",
-            "plan"
-          ],
+          "values": ["tool", "plan"],
           "descriptions": {
             "tool": "Tool call approval",
             "plan": "Plan approval"
@@ -191,11 +173,7 @@
           "type": "enum",
           "optional": true,
           "description": "Current approval status.",
-          "values": [
-            "pending",
-            "approved",
-            "rejected"
-          ],
+          "values": ["pending", "approved", "rejected"],
           "descriptions": {
             "pending": "Awaiting user decision",
             "approved": "Approved by user",
@@ -364,11 +342,7 @@
           "type": "enum",
           "optional": true,
           "description": "Banner level controls icon and color treatment.",
-          "values": [
-            "info",
-            "error",
-            "change"
-          ],
+          "values": ["info", "error", "change"],
           "descriptions": {
             "info": "Informational notice",
             "error": "Error notice",
@@ -412,60 +386,6 @@
         "text-sf-subtle"
       ]
     },
-    "AiLoader": {
-      "name": "AiLoader",
-      "type": "component",
-      "description": "Spinning radial loader for AI streaming states.",
-      "importPath": "@signalflare-ai/ui",
-      "category": "Other",
-      "props": {
-        "children": {
-          "type": "ReactNode",
-          "optional": true
-        },
-        "className": {
-          "type": "string",
-          "optional": true
-        },
-        "id": {
-          "type": "string",
-          "optional": true
-        },
-        "lang": {
-          "type": "string",
-          "optional": true
-        },
-        "title": {
-          "type": "string",
-          "optional": true
-        },
-        "size": {
-          "type": "enum",
-          "optional": true,
-          "description": "Icon size.\n- `\"sm\"` — 12px\n- `\"base\"` — 16px (default)\n- `\"lg\"` — 20px",
-          "values": [
-            "sm",
-            "base",
-            "lg"
-          ],
-          "descriptions": {
-            "sm": "Small — 12px",
-            "base": "Default — 16px",
-            "lg": "Large — 20px"
-          },
-          "classes": {
-            "sm": "size-3",
-            "base": "size-4",
-            "lg": "size-5"
-          },
-          "default": "base"
-        }
-      },
-      "examples": [],
-      "colors": [
-        "text-sf-subtle"
-      ]
-    },
     "AiMessage": {
       "name": "AiMessage",
       "type": "component",
@@ -477,11 +397,7 @@
           "type": "enum",
           "required": true,
           "description": "Message sender role — controls layout and group class.",
-          "values": [
-            "user",
-            "assistant",
-            "system"
-          ],
+          "values": ["user", "assistant", "system"],
           "descriptions": {
             "user": "User message — right-aligned with max width",
             "assistant": "Assistant message — full width left-aligned",
@@ -575,10 +491,7 @@
           "type": "enum",
           "optional": true,
           "description": "Display variant.",
-          "values": [
-            "default",
-            "compact"
-          ],
+          "values": ["default", "compact"],
           "descriptions": {
             "default": "Full header with all stats",
             "compact": "Single-row compact header"
@@ -617,6 +530,55 @@
         "text-sf-success"
       ]
     },
+    "AiPartGroup": {
+      "name": "AiPartGroup",
+      "type": "component",
+      "description": "Groups streaming ephemeral activity (tool calls + reasoning) into a single rolling window during streaming, then collapses to a frozen summary line once the parent message completes.  Behavior: - **Streaming:** shows the most recent `max` (default 3) ephemeral children. Pinned rows (errors / user-expanded) sit above the live window. - **Completed:** writes a snapshot keyed by `groupKey`, unmounts ephemeral children entirely, and renders a static `▸ {title} · N steps` line. - **Re-mount after completion:** always renders the cached snapshot — no animations, no `useEffect` re-runs, no tool re-execution risk.",
+      "importPath": "@signalflare-ai/ui",
+      "category": "Other",
+      "props": {
+        "groupKey": {
+          "type": "string",
+          "required": true,
+          "description": "Stable identifier — usually the parent message id. Required so the group can persist its frozen snapshot across re-mounts (scroll-back into a virtualized list re-renders without restarting animations)."
+        },
+        "complete": {
+          "type": "boolean",
+          "optional": true,
+          "description": "Set to `true` once the parent stream has finished. Triggers the group to snapshot its current children and from then on render only the static collapsed summary — ephemeral children never re-mount."
+        },
+        "title": {
+          "type": "string",
+          "optional": true,
+          "description": "Title shown in the collapsed summary line. Falls back to the first reasoning text snippet, then to a step count."
+        },
+        "children": {
+          "type": "ReactNode",
+          "optional": true
+        },
+        "className": {
+          "type": "string",
+          "optional": true
+        },
+        "id": {
+          "type": "string",
+          "optional": true
+        },
+        "lang": {
+          "type": "string",
+          "optional": true
+        }
+      },
+      "examples": [],
+      "colors": [
+        "bg-sf-tint",
+        "border-sf-line",
+        "text-sf-danger",
+        "text-sf-default",
+        "text-sf-subtle",
+        "text-sf-success"
+      ]
+    },
     "AiQuestion": {
       "name": "AiQuestion",
       "type": "component",
@@ -643,10 +605,7 @@
           "type": "enum",
           "optional": true,
           "description": "Current status.",
-          "values": [
-            "pending",
-            "answered"
-          ],
+          "values": ["pending", "answered"],
           "descriptions": {
             "pending": "Waiting for answer",
             "answered": "User has answered"
@@ -717,15 +676,12 @@
           "type": "enum",
           "optional": true,
           "description": "Display variant.",
-          "values": [
-            "default",
-            "inline",
-            "minimal"
-          ],
+          "values": ["default", "inline", "minimal", "ephemeral"],
           "descriptions": {
             "default": "Expandable card with collapsible reasoning text and duration",
             "inline": "Compact single-line display with left accent border",
-            "minimal": "Pill-shaped status badge"
+            "minimal": "Pill-shaped status badge",
+            "ephemeral": "Single-status row that auto-dismisses after streaming ends. Persists when the user expands it."
           },
           "default": "default"
         },
@@ -769,6 +725,16 @@
           "optional": true,
           "description": "Custom streaming label. When provided, used instead of `label` while `isStreaming` is true. Falls back to `label`, then to the default `\"Thinking...\"`."
         },
+        "dismissDelay": {
+          "type": "number",
+          "optional": true,
+          "description": "For `variant=\"ephemeral\"`: ms to keep the completed row visible before fading out. Set to `0` to disable auto-dismiss."
+        },
+        "persist": {
+          "type": "boolean",
+          "optional": true,
+          "description": "For `variant=\"ephemeral\"`: when `true`, the row never auto-dismisses. User-expanded rows are pinned automatically."
+        },
         "className": {
           "type": "string",
           "optional": true
@@ -794,7 +760,8 @@
       "colors": [
         "bg-sf-tint",
         "border-sf-line",
-        "text-sf-subtle"
+        "text-sf-subtle",
+        "text-sf-success"
       ]
     },
     "AiResponse": {
@@ -814,9 +781,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "text-sf-default"
-      ]
+      "colors": ["text-sf-default"]
     },
     "AiShimmer": {
       "name": "AiShimmer",
@@ -875,12 +840,7 @@
           "type": "enum",
           "optional": true,
           "description": "Current status — determines the status icon on the right.",
-          "values": [
-            "idle",
-            "running",
-            "success",
-            "error"
-          ],
+          "values": ["idle", "running", "success", "error"],
           "descriptions": {
             "idle": "Default idle state — no status icon shown",
             "running": "Actively running — spinner icon shown",
@@ -964,11 +924,7 @@
           "type": "enum",
           "optional": true,
           "description": "Current status.",
-          "values": [
-            "running",
-            "completed",
-            "error"
-          ],
+          "values": ["running", "completed", "error"],
           "descriptions": {
             "running": "Subagent is actively processing",
             "completed": "Subagent finished successfully",
@@ -1112,12 +1068,11 @@
         "bg-sf-brand",
         "bg-sf-danger",
         "bg-sf-subtle",
+        "bg-sf-success",
         "bg-sf-tint",
         "bg-sf-warning",
-        "text-sf-brand",
         "text-sf-default",
-        "text-sf-subtle",
-        "text-sf-success"
+        "text-sf-subtle"
       ]
     },
     "AiTimeline": {
@@ -1151,10 +1106,7 @@
           "type": "enum",
           "optional": true,
           "description": "Lane density variant.",
-          "values": [
-            "comfortable",
-            "compact"
-          ],
+          "values": ["comfortable", "compact"],
           "descriptions": {
             "comfortable": "Taller lanes with more padding",
             "compact": "Tight lanes for dense views"
@@ -1217,15 +1169,12 @@
           "type": "enum",
           "optional": true,
           "description": "Display variant.",
-          "values": [
-            "default",
-            "inline",
-            "minimal"
-          ],
+          "values": ["default", "inline", "minimal", "ephemeral"],
           "descriptions": {
             "default": "Expandable card with collapsible input/output sections",
             "inline": "Compact single-line display with left accent border",
-            "minimal": "Pill-shaped status badge"
+            "minimal": "Pill-shaped status badge",
+            "ephemeral": "Single-status row that auto-dismisses after the call completes. Persists on error or when the user expands it."
           },
           "default": "default"
         },
@@ -1248,17 +1197,23 @@
           "type": "enum",
           "optional": true,
           "description": "Approval state for tools requiring confirmation.",
-          "values": [
-            "awaiting",
-            "approved",
-            "declined"
-          ]
+          "values": ["awaiting", "approved", "declined"]
         },
         "defaultExpanded": {
           "type": "boolean",
           "optional": true,
           "description": "Default expanded state for the collapsible."
         },
+        "dismissDelay": {
+          "type": "number",
+          "optional": true,
+          "description": "For `variant=\"ephemeral\"`: ms to keep the completed row visible before fading out. Set to `0` to disable auto-dismiss."
+        },
+        "persist": {
+          "type": "boolean",
+          "optional": true,
+          "description": "For `variant=\"ephemeral\"`: when `true`, the row never auto-dismisses. Errors and user-expanded rows are pinned automatically."
+        },
         "className": {
           "type": "string",
           "optional": true
@@ -1286,6 +1241,7 @@
         "bg-sf-danger",
         "bg-sf-line",
         "bg-sf-recessed",
+        "bg-sf-subtle",
         "bg-sf-success",
         "bg-sf-tint",
         "bg-sf-warning",
@@ -1357,10 +1313,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "text-sf-inactive",
-        "text-sf-subtle"
-      ]
+      "colors": ["text-sf-inactive", "text-sf-subtle"]
     },
     "Badge": {
       "name": "Badge",
@@ -1427,10 +1380,7 @@
           "type": "enum",
           "optional": true,
           "description": "Position of the icon relative to the text.",
-          "values": [
-            "left",
-            "right"
-          ]
+          "values": ["left", "right"]
         },
         "loading": {
           "type": "boolean",
@@ -1441,13 +1391,7 @@
           "type": "enum",
           "optional": true,
           "description": "Renders a small colored status dot before the text.",
-          "values": [
-            "green",
-            "red",
-            "yellow",
-            "blue",
-            "gray"
-          ]
+          "values": ["green", "red", "yellow", "blue", "gray"]
         },
         "tooltip": {
           "type": "ReactNode",
@@ -1505,11 +1449,7 @@
           "type": "enum",
           "optional": true,
           "description": "Visual style of the banner.\n- `\"default\"` — Informational blue banner for general messages\n- `\"alert\"` — Warning yellow banner for cautionary messages\n- `\"error\"` — Error red banner for critical issues",
-          "values": [
-            "default",
-            "alert",
-            "error"
-          ],
+          "values": ["default", "alert", "error"],
           "descriptions": {
             "default": "Informational banner for general messages",
             "alert": "Warning banner for cautionary messages",
@@ -1556,10 +1496,7 @@
           "type": "enum",
           "optional": true,
           "description": "Size of the breadcrumbs.\n- `\"sm\"` — Compact breadcrumbs for dense UIs\n- `\"base\"` — Default breadcrumbs size",
-          "values": [
-            "sm",
-            "base"
-          ],
+          "values": ["sm", "base"],
           "descriptions": {
             "sm": "Compact breadcrumbs for dense UIs",
             "base": "Default breadcrumbs size"
@@ -1581,11 +1518,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "text-sf-inactive",
-        "text-sf-subtle",
-        "text-sf-success"
-      ],
+      "colors": ["text-sf-inactive", "text-sf-subtle", "text-sf-success"],
       "subComponents": {
         "Link": {
           "name": "Link",
@@ -1642,11 +1575,7 @@
         "shape": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "base",
-            "square",
-            "circle"
-          ],
+          "values": ["base", "square", "circle"],
           "descriptions": {
             "base": "Default rectangular button shape",
             "square": "Square button for icon-only actions",
@@ -1661,12 +1590,7 @@
         "size": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "xs",
-            "sm",
-            "base",
-            "lg"
-          ],
+          "values": ["xs", "sm", "base", "lg"],
           "descriptions": {
             "xs": "Extra small button for compact UIs",
             "sm": "Small button for secondary actions",
@@ -1774,11 +1698,7 @@
         "type": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "submit",
-            "reset",
-            "button"
-          ]
+          "values": ["submit", "reset", "button"]
         },
         "value": {
           "type": "string | string[] | number",
@@ -1811,10 +1731,7 @@
           "type": "enum",
           "optional": true,
           "description": "Visual variant: \"default\" or \"error\" for validation failures (visual only, no error text)",
-          "values": [
-            "default",
-            "error"
-          ],
+          "values": ["default", "error"],
           "descriptions": {
             "default": "Default checkbox appearance",
             "error": "Error state for validation failures"
@@ -1888,7 +1805,7 @@
         "border-sf-line",
         "ring-sf-contrast",
         "ring-sf-danger",
-        "ring-sf-line",
+        "ring-sf-interact",
         "ring-sf-ring",
         "text-sf-danger",
         "text-sf-default",
@@ -1947,32 +1864,14 @@
       "styling": {
         "dimensions": "h-4 w-4",
         "borderRadius": "rounded-sm",
-        "baseTokens": [
-          "bg-sf-base",
-          "ring-sf-line"
-        ],
+        "baseTokens": ["bg-sf-base", "ring-sf-line"],
         "states": {
-          "checked": [
-            "bg-sf-contrast",
-            "text-sf-inverse"
-          ],
-          "indeterminate": [
-            "bg-sf-contrast",
-            "text-sf-inverse"
-          ],
-          "error": [
-            "ring-sf-danger"
-          ],
-          "hover": [
-            "ring-sf-ring"
-          ],
-          "focus": [
-            "ring-sf-ring"
-          ],
-          "disabled": [
-            "opacity-50",
-            "cursor-not-allowed"
-          ]
+          "checked": ["bg-sf-contrast", "text-sf-inverse"],
+          "indeterminate": ["bg-sf-contrast", "text-sf-inverse"],
+          "error": ["ring-sf-danger"],
+          "hover": ["ring-sf-ring"],
+          "focus": ["ring-sf-ring"],
+          "disabled": ["opacity-50", "cursor-not-allowed"]
         },
         "icons": [
           {
@@ -1999,11 +1898,7 @@
           "type": "enum",
           "optional": true,
           "description": "Size of the clipboard text field.\n- `\"sm\"` — Small clipboard text for compact UIs\n- `\"base\"` — Default clipboard text size\n- `\"lg\"` — Large clipboard text for prominent display",
-          "values": [
-            "sm",
-            "base",
-            "lg"
-          ],
+          "values": ["sm", "base", "lg"],
           "descriptions": {
             "sm": "Small clipboard text for compact UIs",
             "base": "Default clipboard text size",
@@ -2052,18 +1947,9 @@
           "border-sf-fill"
         ],
         "states": {
-          "input": [
-            "bg-sf-control",
-            "text-sf-default",
-            "ring-sf-line"
-          ],
-          "text": [
-            "bg-sf-base",
-            "font-mono"
-          ],
-          "button": [
-            "border-sf-fill"
-          ]
+          "input": ["bg-sf-control", "text-sf-default", "ring-sf-line"],
+          "text": ["bg-sf-base", "font-mono"],
+          "button": ["border-sf-fill"]
         },
         "inputStyles": {
           "base": "bg-sf-control text-sf-default ring ring-sf-line",
@@ -2134,13 +2020,7 @@
           "type": "enum",
           "optional": true,
           "description": "Language hint for the code content.\n- `\"ts\"` — TypeScript code\n- `\"tsx\"` — TypeScript JSX code\n- `\"jsonc\"` — JSON with comments\n- `\"bash\"` — Shell/Bash commands\n- `\"css\"` — CSS styles",
-          "values": [
-            "ts",
-            "tsx",
-            "jsonc",
-            "bash",
-            "css"
-          ],
+          "values": ["ts", "tsx", "jsonc", "bash", "css"],
           "descriptions": {
             "ts": "TypeScript code",
             "tsx": "TypeScript JSX code",
@@ -2167,11 +2047,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "bg-sf-recessed",
-        "border-sf-line",
-        "text-sf-default"
-      ],
+      "colors": ["bg-sf-recessed", "border-sf-line", "text-sf-default"],
       "subComponents": {
         "Block": {
           "name": "Block",
@@ -2188,26 +2064,7 @@
           }
         }
       },
-      "styling": {
-        "baseTokens": [
-          "text-sf-default"
-        ],
-        "typography": {
-          "fontFamily": "font-mono",
-          "fontSize": "text-sm",
-          "lineHeight": "leading-[20px]"
-        },
-        "dimensions": {
-          "margin": "m-0",
-          "padding": "p-0",
-          "width": "w-auto"
-        },
-        "appearance": {
-          "borderRadius": "rounded-none",
-          "border": "border-none",
-          "background": "bg-transparent"
-        }
-      }
+      "styling": {}
     },
     "Collapsible": {
       "name": "Collapsible",
@@ -2241,10 +2098,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "border-sf-fill",
-        "text-sf-link"
-      ]
+      "colors": ["border-sf-fill", "text-sf-link"]
     },
     "Combobox": {
       "name": "Combobox",
@@ -2257,10 +2111,7 @@
           "type": "enum",
           "optional": true,
           "description": "Position of the text input relative to chips in multi-select mode.\n- `\"right\"` — Input inline to the right of chips\n- `\"top\"` — Input above chips",
-          "values": [
-            "right",
-            "top"
-          ],
+          "values": ["right", "top"],
           "descriptions": {
             "right": "Input positioned inline to the right of chips",
             "top": "Input positioned above chips"
@@ -2468,10 +2319,7 @@
       "props": {
         "layout": {
           "type": "enum",
-          "values": [
-            "auto",
-            "fixed"
-          ],
+          "values": ["auto", "fixed"],
           "default": "auto",
           "descriptions": {
             "auto": "Auto column sizing - columns resize based on content",
@@ -2529,7 +2377,7 @@
     "DatePicker": {
       "name": "DatePicker",
       "type": "component",
-      "description": "DatePicker — a date selection calendar.  Built on [react-day-picker](https://daypicker.dev) with SF styling. Supports three selection modes: single, multiple, and range.",
+      "description": "DatePicker — a date selection calendar.  Built on [react-day-picker](https://daypicker.dev) with SignalFlare styling. Supports three selection modes: single, multiple, and range.",
       "importPath": "@signalflare-ai/ui",
       "category": "Other",
       "props": {
@@ -2543,9 +2391,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "bg-sf-base"
-      ]
+      "colors": ["bg-sf-base"]
     },
     "DateRangePicker": {
       "name": "DateRangePicker",
@@ -2558,11 +2404,7 @@
           "type": "enum",
           "optional": true,
           "description": "Calendar size.\n- `\"sm\"` — Compact calendar for tight spaces\n- `\"base\"` — Default calendar size\n- `\"lg\"` — Large calendar for prominent date selection",
-          "values": [
-            "sm",
-            "base",
-            "lg"
-          ],
+          "values": ["sm", "base", "lg"],
           "descriptions": {
             "sm": "Compact calendar for tight spaces",
             "base": "Default calendar size",
@@ -2579,10 +2421,7 @@
           "type": "enum",
           "optional": true,
           "description": "Visual variant.\n- `\"default\"` — Standard appearance with overlay background\n- `\"subtle\"` — Minimal background",
-          "values": [
-            "default",
-            "subtle"
-          ],
+          "values": ["default", "subtle"],
           "descriptions": {
             "default": "Default calendar appearance",
             "subtle": "Subtle calendar with minimal background"
@@ -2689,12 +2528,7 @@
           "type": "enum",
           "optional": true,
           "description": "Dialog width.\n- `\"sm\"` — Small (min 288px) for simple confirmations\n- `\"base\"` — Default (min 384px)\n- `\"lg\"` — Large (min 512px) for complex content\n- `\"xl\"` — Extra large (min 768px) for detailed views",
-          "values": [
-            "base",
-            "sm",
-            "lg",
-            "xl"
-          ],
+          "values": ["base", "sm", "lg", "xl"],
           "descriptions": {
             "base": "Default dialog width",
             "sm": "Small dialog for simple confirmations",
@@ -2827,10 +2661,7 @@
           "type": "enum",
           "optional": true,
           "description": "Visual style of the dropdown item.\n- `\"default\"` — Standard item appearance\n- `\"danger\"` — Destructive action with red text",
-          "values": [
-            "default",
-            "danger"
-          ],
+          "values": ["default", "danger"],
           "descriptions": {
             "default": "Default dropdown item appearance",
             "danger": "Destructive action item"
@@ -2949,11 +2780,7 @@
           "type": "enum",
           "optional": true,
           "description": "Size of the empty state container.\n- `\"sm\"` — Compact empty state for smaller containers\n- `\"base\"` — Default empty state size\n- `\"lg\"` — Large empty state for prominent placement",
-          "values": [
-            "sm",
-            "base",
-            "lg"
-          ],
+          "values": ["sm", "base", "lg"],
           "descriptions": {
             "sm": "Compact empty state for smaller containers",
             "base": "Default empty state size",
@@ -3054,11 +2881,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "text-sf-danger",
-        "text-sf-default",
-        "text-sf-subtle"
-      ]
+      "colors": ["text-sf-danger", "text-sf-default", "text-sf-subtle"]
     },
     "Filters": {
       "name": "Filters",
@@ -3081,11 +2904,7 @@
           "type": "enum",
           "optional": true,
           "description": "Size variant for filter pills",
-          "values": [
-            "sm",
-            "default",
-            "lg"
-          ],
+          "values": ["sm", "default", "lg"],
           "descriptions": {
             "sm": "Small filter items",
             "default": "Default filter items",
@@ -3196,12 +3015,7 @@
           "type": "enum",
           "optional": true,
           "description": "Gap size between grid items.\n- `\"none\"` — No gap\n- `\"sm\"` — 12px gap\n- `\"base\"` — Responsive gap (8px → 24px → 32px)\n- `\"lg\"` — 32px gap",
-          "values": [
-            "none",
-            "sm",
-            "base",
-            "lg"
-          ],
+          "values": ["none", "sm", "base", "lg"],
           "descriptions": {
             "none": "No gap between grid items",
             "sm": "Small gap between grid items",
@@ -3256,9 +3070,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "border-sf-line"
-      ]
+      "colors": ["border-sf-line"]
     },
     "Input": {
       "name": "Input",
@@ -3291,12 +3103,7 @@
           "type": "enum",
           "optional": true,
           "description": "Input size.\n- `\"xs\"` — Extra small for compact UIs\n- `\"sm\"` — Small for secondary fields\n- `\"base\"` — Default size\n- `\"lg\"` — Large for prominent fields",
-          "values": [
-            "xs",
-            "sm",
-            "base",
-            "lg"
-          ],
+          "values": ["xs", "sm", "base", "lg"],
           "descriptions": {
             "xs": "Extra small input for compact UIs",
             "sm": "Small input for secondary fields",
@@ -3315,10 +3122,7 @@
           "type": "enum",
           "optional": true,
           "description": "Visual variant.\n- `\"default\"` — Standard input\n- `\"error\"` — Error state for validation failures",
-          "values": [
-            "default",
-            "error"
-          ],
+          "values": ["default", "error"],
           "descriptions": {
             "default": "Default input appearance",
             "error": "Error state for validation failures"
@@ -3437,10 +3241,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "text-sf-default",
-        "text-sf-strong"
-      ]
+      "colors": ["text-sf-default", "text-sf-strong"]
     },
     "LayerCard": {
       "name": "LayerCard",
@@ -3513,11 +3314,7 @@
           "type": "enum",
           "optional": true,
           "description": "Visual style of the link.\n- `\"inline\"` — Inline text link that flows with content\n- `\"current\"` — Link that inherits color from parent text\n- `\"plain\"` — Link without underline decoration",
-          "values": [
-            "inline",
-            "current",
-            "plain"
-          ],
+          "values": ["inline", "current", "plain"],
           "descriptions": {
             "inline": "Inline text link that flows with content",
             "current": "Link that inherits color from parent text",
@@ -3605,7 +3402,7 @@
         "render": {
           "type": "ReactNode",
           "optional": true,
-          "description": "Allows you to replace the component’s HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+          "description": "Allows you to replace the component's HTML element with a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
         }
       },
       "examples": [],
@@ -3634,11 +3431,7 @@
           "type": "enum",
           "optional": true,
           "description": "Size of the spinner. Use a preset name or a custom pixel number.\n- `\"sm\"` — 16px, for inline use\n- `\"base\"` — 24px, default size\n- `\"lg\"` — 32px, for prominent loading states",
-          "values": [
-            "sm",
-            "base",
-            "lg"
-          ],
+          "values": ["sm", "base", "lg"],
           "descriptions": {
             "sm": "Small loader for inline use",
             "base": "Default loader size",
@@ -3679,11 +3472,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "bg-sf-base",
-        "bg-sf-fill",
-        "border-sf-fill"
-      ],
+      "colors": ["bg-sf-base", "bg-sf-fill", "border-sf-fill"],
       "styling": {
         "container": {
           "height": 32,
@@ -3744,11 +3533,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "bg-sf-fill",
-        "text-sf-default",
-        "text-sf-strong"
-      ]
+      "colors": ["bg-sf-fill", "text-sf-default", "text-sf-strong"]
     },
     "Pagination": {
       "name": "Pagination",
@@ -3760,10 +3545,7 @@
         "controls": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "full",
-            "simple"
-          ],
+          "values": ["full", "simple"],
           "descriptions": {
             "full": "Full pagination controls with first, previous, page input, next, and last buttons",
             "simple": "Simple pagination controls with only previous and next buttons"
@@ -3797,9 +3579,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "text-sf-strong"
-      ],
+      "colors": ["text-sf-strong"],
       "styling": {
         "layout": {
           "height": 36,
@@ -3822,12 +3602,7 @@
           "type": "enum",
           "optional": true,
           "description": "Which side of the trigger the popover appears on.\n- `\"top\"` — Above the trigger\n- `\"bottom\"` — Below the trigger\n- `\"left\"` — Left of the trigger\n- `\"right\"` — Right of the trigger",
-          "values": [
-            "top",
-            "bottom",
-            "left",
-            "right"
-          ],
+          "values": ["top", "bottom", "left", "right"],
           "descriptions": {
             "top": "Popover appears above the trigger",
             "bottom": "Popover appears below the trigger",
@@ -3941,6 +3716,7 @@
       "examples": [],
       "colors": [
         "bg-sf-base",
+        "bg-sf-control",
         "bg-sf-elevated",
         "bg-sf-overlay",
         "bg-sf-tint",
@@ -3973,10 +3749,7 @@
           "type": "enum",
           "optional": true,
           "description": "Layout direction of the radio items",
-          "values": [
-            "vertical",
-            "horizontal"
-          ]
+          "values": ["vertical", "horizontal"]
         },
         "error": {
           "type": "string",
@@ -4002,10 +3775,7 @@
           "type": "enum",
           "optional": true,
           "description": "Position of radio control relative to label: \"start\" (default) puts radio before label, \"end\" puts label before radio",
-          "values": [
-            "start",
-            "end"
-          ]
+          "values": ["start", "end"]
         },
         "name": {
           "type": "string",
@@ -4024,7 +3794,7 @@
         "bg-sf-contrast",
         "border-sf-line",
         "ring-sf-danger",
-        "ring-sf-line",
+        "ring-sf-interact",
         "ring-sf-ring",
         "text-sf-danger",
         "text-sf-default",
@@ -4125,13 +3895,9 @@
       "styling": {
         "trigger": {
           "height": 36,
-          "paddingX": 12,
-          "borderRadius": 8,
-          "background": "color-secondary",
           "text": "text-color-surface",
           "ring": "color-border",
-          "fontSize": 16,
-          "fontWeight": 400
+          "fontSize": 16
         },
         "stateTokens": {
           "focus": {
@@ -4154,15 +3920,10 @@
         "popup": {
           "background": "color-secondary",
           "ring": "color-border",
-          "borderRadius": 8,
-          "padding": 6
+          "borderRadius": 8
         },
         "option": {
-          "paddingX": 8,
-          "paddingY": 6,
-          "borderRadius": 4,
-          "fontSize": 16,
-          "highlightBackground": "color-surface-secondary"
+          "paddingX": 8
         }
       }
     },
@@ -4246,22 +4007,14 @@
           "type": "enum",
           "optional": true,
           "description": "Size of the input.\n- `\"xs\"` — Extra small for compact UIs\n- `\"sm\"` — Small for secondary fields\n- `\"base\"` — Default input size\n- `\"lg\"` — Large for prominent fields",
-          "values": [
-            "xs",
-            "sm",
-            "base",
-            "lg"
-          ],
+          "values": ["xs", "sm", "base", "lg"],
           "default": "base"
         },
         "variant": {
           "type": "enum",
           "optional": true,
           "description": "Style variant of the input.\n- `\"default\"` — Default input appearance\n- `\"error\"` — Error state for validation failures",
-          "values": [
-            "default",
-            "error"
-          ],
+          "values": ["default", "error"],
           "default": "default"
         },
         "label": {
@@ -4315,11 +4068,7 @@
           "type": "enum",
           "optional": true,
           "description": "Sidebar layout variant.",
-          "values": [
-            "sidebar",
-            "floating",
-            "inset"
-          ],
+          "values": ["sidebar", "floating", "inset"],
           "descriptions": {
             "sidebar": "Standard sidebar with border separator",
             "floating": "Floating sidebar with shadow and rounded corners",
@@ -4331,10 +4080,7 @@
           "type": "enum",
           "optional": true,
           "description": "Which side the sidebar is on.",
-          "values": [
-            "left",
-            "right"
-          ],
+          "values": ["left", "right"],
           "descriptions": {
             "left": "Left-aligned sidebar",
             "right": "Right-aligned sidebar"
@@ -4344,11 +4090,7 @@
         "collapsible": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "icon",
-            "offcanvas",
-            "none"
-          ],
+          "values": ["icon", "offcanvas", "none"],
           "descriptions": {
             "icon": "Collapses to show icons only",
             "offcanvas": "Slides off screen when collapsed",
@@ -4637,18 +4379,12 @@
         "accumulate": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "none",
-            "sum"
-          ]
+          "values": ["none", "sum"]
         },
         "additive": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "replace",
-            "sum"
-          ]
+          "values": ["replace", "sum"]
         },
         "alignmentBaseline": {
           "type": "enum",
@@ -4672,10 +4408,7 @@
         "allowReorder": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "no",
-            "yes"
-          ]
+          "values": ["no", "yes"]
         },
         "alphabetic": {
           "type": "number | string",
@@ -4688,12 +4421,7 @@
         "arabicForm": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "initial",
-            "medial",
-            "terminal",
-            "isolated"
-          ]
+          "values": ["initial", "medial", "terminal", "isolated"]
         },
         "ascent": {
           "type": "number | string",
@@ -4774,12 +4502,7 @@
         "colorInterpolationFilters": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "auto",
-            "sRGB",
-            "linearRGB",
-            "inherit"
-          ]
+          "values": ["auto", "sRGB", "linearRGB", "inherit"]
         },
         "colorProfile": {
           "type": "number | string",
@@ -4903,11 +4626,7 @@
         "fillRule": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "nonzero",
-            "evenodd",
-            "inherit"
-          ]
+          "values": ["nonzero", "evenodd", "inherit"]
         },
         "filter": {
           "type": "string",
@@ -5408,22 +5127,12 @@
         "strokeLinecap": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "butt",
-            "round",
-            "square",
-            "inherit"
-          ]
+          "values": ["butt", "round", "square", "inherit"]
         },
         "strokeLinejoin": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "miter",
-            "round",
-            "bevel",
-            "inherit"
-          ]
+          "values": ["miter", "round", "bevel", "inherit"]
         },
         "strokeMiterlimit": {
           "type": "number | string",
@@ -5460,12 +5169,7 @@
         "textAnchor": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "start",
-            "middle",
-            "end",
-            "inherit"
-          ]
+          "values": ["start", "middle", "end", "inherit"]
         },
         "textDecoration": {
           "type": "number | string",
@@ -5679,10 +5383,7 @@
           "type": "enum",
           "optional": true,
           "description": "Logo variant\n- `glyph`: Map pin icon only\n- `full`: Full logo with wordmark and decorative element",
-          "values": [
-            "glyph",
-            "full"
-          ],
+          "values": ["glyph", "full"],
           "descriptions": {
             "glyph": "Map pin icon only (logomark)",
             "full": "Full logo with icon, wordmark, and decorative element"
@@ -5691,10 +5392,86 @@
         }
       },
       "examples": [],
+      "colors": ["bg-sf-base", "ring-sf-line", "text-sf-default"]
+    },
+    "Sparkline": {
+      "name": "Sparkline",
+      "type": "component",
+      "description": "Sparkline — a tiny inline chart intended for embedding in cards, tables, or row-level cells. Renders without axes, grid, or legend by default.",
+      "importPath": "@signalflare-ai/ui",
+      "category": "Other",
+      "props": {
+        "className": {
+          "type": "string",
+          "description": "Additional CSS classes"
+        },
+        "children": {
+          "type": "ReactNode",
+          "description": "Child elements"
+        }
+      },
+      "examples": [],
+      "colors": []
+    },
+    "StatCard": {
+      "name": "StatCard",
+      "type": "component",
+      "description": "StatCard — compact KPI tile displaying a label, a primary value, and an optional delta + trend sparkline.",
+      "importPath": "@signalflare-ai/ui",
+      "category": "Other",
+      "props": {
+        "size": {
+          "type": "enum",
+          "optional": true,
+          "description": "Size of the card. Defaults to `\"base\"`.",
+          "values": ["sm", "base"],
+          "default": "base"
+        },
+        "label": {
+          "type": "ReactNode",
+          "optional": true,
+          "description": "Short descriptive label (e.g. `\"Active users\"`)."
+        },
+        "value": {
+          "type": "ReactNode",
+          "optional": true,
+          "description": "Primary value to emphasise (pre-formatted)."
+        },
+        "hint": {
+          "type": "ReactNode",
+          "optional": true,
+          "description": "Optional secondary text displayed under the value."
+        },
+        "delta": {
+          "type": "StatCardDelta",
+          "optional": true,
+          "description": "Optional change indicator (arrow + number + label)."
+        },
+        "trend": {
+          "type": "ReactNode",
+          "optional": true,
+          "description": "Optional content slot rendered on the right-hand side — typically a `Sparkline` showing the metric's trend."
+        },
+        "loading": {
+          "type": "boolean",
+          "optional": true,
+          "description": "When `true`, renders a skeleton placeholder in place of value + delta."
+        },
+        "className": {
+          "type": "string",
+          "optional": true,
+          "description": "Additional CSS classes merged via `cn()`."
+        }
+      },
+      "examples": [],
       "colors": [
-        "bg-sf-base",
-        "ring-sf-line",
-        "text-sf-default"
+        "bg-sf-elevated",
+        "bg-sf-fill",
+        "text-sf-danger",
+        "text-sf-default",
+        "text-sf-strong",
+        "text-sf-subtle",
+        "text-sf-success"
       ]
     },
     "Surface": {
@@ -5721,10 +5498,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "bg-sf-base",
-        "ring-sf-line"
-      ]
+      "colors": ["bg-sf-base", "ring-sf-line"]
     },
     "Switch": {
       "name": "Switch",
@@ -5737,10 +5511,7 @@
           "type": "enum",
           "optional": true,
           "description": "Visual variant: \"default\" or \"error\" for validation failures (visual only, no error text)",
-          "values": [
-            "default",
-            "error"
-          ],
+          "values": ["default", "error"],
           "descriptions": {
             "default": "Default switch appearance",
             "error": "Error state for validation failures"
@@ -5773,11 +5544,7 @@
         "size": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "sm",
-            "base",
-            "lg"
-          ],
+          "values": ["sm", "base", "lg"],
           "descriptions": {
             "sm": "Small switch for compact UIs",
             "base": "Default switch size",
@@ -5809,11 +5576,7 @@
         "type": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "submit",
-            "reset",
-            "button"
-          ]
+          "values": ["submit", "reset", "button"]
         },
         "value": {
           "type": "string | string[] | number",
@@ -5905,10 +5668,7 @@
       "props": {
         "layout": {
           "type": "enum",
-          "values": [
-            "auto",
-            "fixed"
-          ],
+          "values": ["auto", "fixed"],
           "default": "auto",
           "descriptions": {
             "auto": "Auto table layout - columns resize based on content",
@@ -5917,10 +5677,7 @@
         },
         "variant": {
           "type": "enum",
-          "values": [
-            "default",
-            "selected"
-          ],
+          "values": ["default", "selected"],
           "default": "default",
           "descriptions": {
             "default": "Default row variant",
@@ -6038,11 +5795,7 @@
           "type": "enum",
           "optional": true,
           "description": "Tab style.\n- `\"segmented\"` — Pill-shaped indicator on a filled track\n- `\"underline\"` — Underline indicator below tab text\n- `\"pill\"` — Fully rounded tabs, only selected has background",
-          "values": [
-            "segmented",
-            "underline",
-            "pill"
-          ],
+          "values": ["segmented", "underline", "pill"],
           "default": "segmented"
         },
         "onValueChange": {
@@ -6137,12 +5890,7 @@
           "type": "enum",
           "optional": true,
           "description": "Text size (only applies to body/secondary/success/error variants).\n- `\"xs\"` — 12px\n- `\"sm\"` — 14px\n- `\"base\"` — 16px\n- `\"lg\"` — 18px",
-          "values": [
-            "xs",
-            "sm",
-            "base",
-            "lg"
-          ],
+          "values": ["xs", "sm", "base", "lg"],
           "descriptions": {
             "xs": "Extra small text",
             "sm": "Small text",
@@ -6186,9 +5934,7 @@
           "sm": 14,
           "base": 16,
           "lg": 18,
-          "xl": 20,
-          "2xl": 24,
-          "3xl": 30
+          "xl": 20
         },
         "fontWeights": {
           "normal": 400,
@@ -6201,8 +5947,7 @@
           "secondary": "text-sf-subtle",
           "success": "text-sf-link",
           "error": "text-sf-danger",
-          "mono": "text-sf-default",
-          "mono-secondary": "text-sf-subtle"
+          "mono": "text-sf-default"
         },
         "fontFamilies": {
           "default": "sans-serif",
@@ -6210,6 +5955,52 @@
         }
       }
     },
+    "TextRoll": {
+      "name": "TextRoll",
+      "type": "component",
+      "description": "Letter-by-letter roll animation. Each character flips on the X axis: the current letter rolls up and out, the new letter rolls in from below. Good for title changes (e.g. a streaming activity group swapping its current-step label) where the text content is short and the change should register visually.  Wraps the string in an `aria-hidden` visual stack with a screen-reader-only copy of the full text so a11y tools always read the real content.",
+      "importPath": "@signalflare-ai/ui",
+      "category": "Other",
+      "props": {
+        "children": {
+          "type": "string",
+          "required": true,
+          "description": "Text to animate. Each character rolls in / out independently."
+        },
+        "duration": {
+          "type": "number",
+          "optional": true,
+          "description": "Duration (seconds) of each letter's enter and exit tween."
+        },
+        "getEnterDelay": {
+          "type": "object",
+          "optional": true,
+          "description": "Per-letter delay for the enter animation."
+        },
+        "getExitDelay": {
+          "type": "object",
+          "optional": true,
+          "description": "Per-letter delay for the exit animation."
+        },
+        "className": {
+          "type": "string",
+          "optional": true,
+          "description": "Additional CSS classes merged via `cn()`. Use sf semantic tokens only."
+        },
+        "transition": {
+          "type": "Transition",
+          "optional": true,
+          "description": "Shared transition for both enter and exit tweens."
+        },
+        "variants": {
+          "type": "TextRollVariants",
+          "optional": true,
+          "description": "Override the default rotate-X roll with custom enter/exit variants."
+        }
+      },
+      "examples": [],
+      "colors": []
+    },
     "ThemeToggle": {
       "name": "ThemeToggle",
       "type": "component",
@@ -6226,11 +6017,7 @@
           "type": "enum",
           "optional": true,
           "description": "Controlled mode. When provided the component acts as a controlled input — pair with `onModeChange`.",
-          "values": [
-            "light",
-            "dark",
-            "system"
-          ],
+          "values": ["light", "dark", "system"],
           "descriptions": {
             "light": "Light mode",
             "dark": "Dark mode",
@@ -6250,10 +6037,7 @@
         }
       },
       "examples": [],
-      "colors": [
-        "text-sf-default",
-        "text-sf-subtle"
-      ]
+      "colors": ["text-sf-default", "text-sf-subtle"]
     },
     "Toasty": {
       "name": "Toasty",
@@ -6264,11 +6048,7 @@
       "props": {
         "variant": {
           "type": "enum",
-          "values": [
-            "default",
-            "error",
-            "warning"
-          ],
+          "values": ["default", "error", "warning"],
           "default": "default",
           "descriptions": {
             "default": "Default toast style",
@@ -6335,12 +6115,7 @@
       "props": {
         "side": {
           "type": "enum",
-          "values": [
-            "top",
-            "bottom",
-            "left",
-            "right"
-          ],
+          "values": ["top", "bottom", "left", "right"],
           "default": "top",
           "descriptions": {
             "top": "Tooltip appears above the trigger",
@@ -6446,11 +6221,7 @@
           "type": "enum",
           "optional": true,
           "description": "Placement for interactive HITL elements (approvals, questions, plans).",
-          "values": [
-            "inline",
-            "back-layer",
-            "both"
-          ],
+          "values": ["inline", "back-layer", "both"],
           "descriptions": {
             "inline": "Render approval/question cards inline in the conversation stream",
             "back-layer": "Render approval/question cards in the PromptInput back layer",
@@ -6458,15 +6229,10 @@
           },
           "default": "inline"
         },
-        "showMode": {
+        "groupActivity": {
           "type": "boolean",
           "optional": true,
-          "description": "Show the mode badge in the header (mode name + color dot)."
-        },
-        "showModel": {
-          "type": "boolean",
-          "optional": true,
-          "description": "Show the model badge in the header."
+          "description": "Group ephemeral activity (reasoning, observations, tool calls) into a single rolling  {@link  AiPartGroup }  per assistant message. While streaming, the group shows a persistent title row with the latest few activity rows underneath. On completion (or scroll-back), the group collapses to a single frozen summary line."
         },
         "showUsage": {
           "type": "boolean",
@@ -6522,6 +6288,23 @@
           "type": "object[]",
           "optional": true,
           "description": "Available modes for the mode selector in the toolbar. When provided, a mode selector will be shown in the prompt input toolbar."
+        },
+        "availableModels": {
+          "type": "object[]",
+          "optional": true,
+          "description": "Available models for the model selector in the toolbar. When provided, a model selector will be shown in the prompt input toolbar."
+        },
+        "modeVariant": {
+          "type": "enum",
+          "optional": true,
+          "description": "Rendering style for the mode picker.\n- `\"select\"` (default): compact dropdown\n- `\"cycle\"`: single click-to-cycle button",
+          "values": ["select", "cycle"]
+        },
+        "modelVariant": {
+          "type": "enum",
+          "optional": true,
+          "description": "Rendering style for the model picker.\n- `\"select\"` (default): compact dropdown\n- `\"cycle\"`: single click-to-cycle button",
+          "values": ["select", "cycle"]
         }
       },
       "examples": [],
@@ -6532,12 +6315,12 @@
         "border-sf-line",
         "text-sf-brand",
         "text-sf-default",
-        "text-sf-inactive",
         "text-sf-strong",
         "text-sf-subtle"
       ],
       "files": [
-        "agent-harness/agent-harness.tsx"
+        "agent-harness/agent-harness.tsx",
+        "agent-harness/agent-harness.stories.tsx"
       ],
       "dependencies": [
         "createAgentHarnessState",
@@ -6587,11 +6370,7 @@
           "type": "enum",
           "optional": true,
           "description": "Layout variant.",
-          "values": [
-            "timeline-cards",
-            "timeline-only",
-            "cards-only"
-          ],
+          "values": ["timeline-cards", "timeline-only", "cards-only"],
           "descriptions": {
             "timeline-cards": "Mission header + timeline + agent card grid",
             "timeline-only": "Mission header + timeline, no agent cards grid",
@@ -6621,13 +6400,79 @@
         }
       },
       "examples": [],
-      "colors": [
-        "bg-sf-base",
-        "border-sf-line",
-        "text-sf-subtle"
-      ],
+      "colors": ["bg-sf-base", "border-sf-line", "text-sf-subtle"],
+      "files": ["commander/commander.tsx", "commander/commander.stories.tsx"],
+      "dependencies": []
+    },
+    "DashboardGrid": {
+      "name": "DashboardGrid",
+      "type": "block",
+      "description": "DashboardGrid — opinionated 12-column responsive grid for composing BI dashboards from KPI cards, charts, and tables.  Cells stack to a single column below `md` and fall into 12-column slots at `md` and above.",
+      "importPath": "@signalflare-ai/ui",
+      "category": "Other",
+      "props": {
+        "children": {
+          "type": "ReactNode",
+          "optional": true,
+          "description": "Children cells / rows."
+        },
+        "className": {
+          "type": "string",
+          "optional": true,
+          "description": "Additional CSS classes merged via `cn()`."
+        },
+        "id": {
+          "type": "string",
+          "optional": true
+        },
+        "lang": {
+          "type": "string",
+          "optional": true
+        },
+        "title": {
+          "type": "string",
+          "optional": true
+        }
+      },
+      "examples": [],
+      "colors": [],
+      "subComponents": {
+        "Row": {
+          "name": "Row",
+          "description": "Row sub-component",
+          "props": {
+            "children": {
+              "type": "ReactNode",
+              "optional": true
+            },
+            "className": {
+              "type": "string",
+              "optional": true
+            }
+          }
+        },
+        "Cell": {
+          "name": "Cell",
+          "description": "Cell sub-component",
+          "props": {
+            "span": {
+              "type": "DashboardCellSpan",
+              "optional": true
+            },
+            "children": {
+              "type": "ReactNode",
+              "optional": true
+            },
+            "className": {
+              "type": "string",
+              "optional": true
+            }
+          }
+        }
+      },
       "files": [
-        "commander/commander.tsx"
+        "dashboard-grid/dashboard-grid.tsx",
+        "dashboard-grid/dashboard-grid.stories.tsx"
       ],
       "dependencies": []
     },
@@ -6641,10 +6486,7 @@
         "size": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "sm",
-            "base"
-          ],
+          "values": ["sm", "base"],
           "descriptions": {
             "sm": "Small dialog for simple delete confirmations",
             "base": "Default delete confirmation dialog size"
@@ -6701,7 +6543,8 @@
         "text-sf-subtle"
       ],
       "files": [
-        "delete-resource/delete-resource.tsx"
+        "delete-resource/delete-resource.tsx",
+        "delete-resource/delete-resource.stories.tsx"
       ],
       "dependencies": [
         "Banner",
@@ -6738,15 +6581,64 @@
         "text-sf-default",
         "text-sf-subtle"
       ],
+      "files": ["map-block/map-block.tsx", "map-block/map-block.stories.tsx"],
+      "dependencies": ["Badge", "Button", "Loader", "Tooltip"]
+    },
+    "MetricsOverview": {
+      "name": "MetricsOverview",
+      "type": "block",
+      "description": "MetricsOverview — composed block that assembles a dashboard header, a strip of KPI tiles, and a primary chart area into one reusable layout.",
+      "importPath": "@signalflare-ai/ui",
+      "category": "Other",
+      "props": {
+        "title": {
+          "type": "ReactNode",
+          "optional": true,
+          "description": "Heading rendered in the top-left of the header row."
+        },
+        "description": {
+          "type": "ReactNode",
+          "optional": true,
+          "description": "Optional description or subtitle shown under the title."
+        },
+        "actions": {
+          "type": "ReactNode",
+          "optional": true,
+          "description": "Right-aligned slot for timeframe toggles, filters, or actions."
+        },
+        "kpis": {
+          "type": "MetricsOverviewKpi[]",
+          "required": true,
+          "description": "KPI tiles displayed in the strip under the header."
+        },
+        "chart": {
+          "type": "ReactNode",
+          "optional": true,
+          "description": "Primary chart slot. Typically a `<TimeseriesChart />` or `<BarChart />` configured by the consumer."
+        },
+        "loading": {
+          "type": "boolean",
+          "optional": true,
+          "description": "When `true`, renders skeleton placeholders on KPI tiles."
+        },
+        "emptyState": {
+          "type": "ReactNode",
+          "optional": true,
+          "description": "When `kpis` is empty and no chart is provided, this node is rendered in place of the overview."
+        },
+        "className": {
+          "type": "string",
+          "optional": true,
+          "description": "Additional CSS classes merged via `cn()`."
+        }
+      },
+      "examples": [],
+      "colors": ["bg-sf-elevated", "text-sf-strong", "text-sf-subtle"],
       "files": [
-        "map-block/map-block.tsx"
+        "metrics-overview/metrics-overview.tsx",
+        "metrics-overview/metrics-overview.stories.tsx"
       ],
-      "dependencies": [
-        "Badge",
-        "Button",
-        "Loader",
-        "Tooltip"
-      ]
+      "dependencies": ["StatCard"]
     },
     "PageHeader": {
       "name": "PageHeader",
@@ -6758,11 +6650,7 @@
         "spacing": {
           "type": "enum",
           "optional": true,
-          "values": [
-            "compact",
-            "base",
-            "relaxed"
-          ],
+          "values": ["compact", "base", "relaxed"],
           "descriptions": {
             "compact": "Compact spacing between header elements",
             "base": "Default spacing between header elements",
@@ -6805,17 +6693,12 @@
         }
       },
       "examples": [],
-      "colors": [
-        "border-sf-line",
-        "text-sf-default",
-        "text-sf-subtle"
-      ],
+      "colors": ["border-sf-line", "text-sf-default", "text-sf-subtle"],
       "files": [
-        "page-header/page-header.tsx"
+        "page-header/page-header.tsx",
+        "page-header/page-header.stories.tsx"
       ],
-      "dependencies": [
-        "Tabs"
-      ]
+      "dependencies": ["Tabs"]
     },
     "ResourceListPage": {
       "name": "ResourceListPage",
@@ -6854,12 +6737,10 @@
         }
       },
       "examples": [],
-      "colors": [
-        "bg-sf-overlay",
-        "text-sf-strong"
-      ],
+      "colors": ["bg-sf-overlay", "text-sf-strong"],
       "files": [
         "resource-list/resource-list.tsx",
+        "resource-list/resource-list.stories.tsx",
         "resource-list/resource-list.test.tsx"
       ],
       "dependencies": []
@@ -6874,9 +6755,9 @@
         "AiCodeBlock",
         "AiConversation",
         "AiInfoBanner",
-        "AiLoader",
         "AiMessage",
         "AiMissionHeader",
+        "AiPartGroup",
         "AiQuestion",
         "AiReasoning",
         "AiResponse",
@@ -6898,12 +6779,17 @@
         "SensitiveInput",
         "Sidebar",
         "SignalFlareAILogo",
+        "Sparkline",
+        "StatCard",
         "Table",
+        "TextRoll",
         "ThemeToggle",
         "AgentHarness",
         "Commander",
+        "DashboardGrid",
         "DeleteResource",
-        "Map"
+        "Map",
+        "MetricsOverview"
       ],
       "Display": [
         "Badge",
@@ -6915,15 +6801,8 @@
         "Meter",
         "Text"
       ],
-      "Feedback": [
-        "Banner",
-        "Loader",
-        "Toasty"
-      ],
-      "Action": [
-        "Button",
-        "ClipboardText"
-      ],
+      "Feedback": ["Banner", "Loader", "Toasty"],
+      "Action": ["Button", "ClipboardText"],
       "Input": [
         "Checkbox",
         "Combobox",
@@ -6934,24 +6813,9 @@
         "Select",
         "Switch"
       ],
-      "Navigation": [
-        "CommandPalette",
-        "MenuBar",
-        "Pagination",
-        "Tabs"
-      ],
-      "Overlay": [
-        "Dialog",
-        "DropdownMenu",
-        "Popover",
-        "Tooltip"
-      ],
-      "Layout": [
-        "Grid",
-        "Surface",
-        "PageHeader",
-        "ResourceListPage"
-      ]
+      "Navigation": ["CommandPalette", "MenuBar", "Pagination", "Tabs"],
+      "Overlay": ["Dialog", "DropdownMenu", "Popover", "Tooltip"],
+      "Layout": ["Grid", "Surface", "PageHeader", "ResourceListPage"]
     },
     "byName": [
       "AgentHarness",
@@ -6961,9 +6825,9 @@
       "AiCodeBlock",
       "AiConversation",
       "AiInfoBanner",
-      "AiLoader",
       "AiMessage",
       "AiMissionHeader",
+      "AiPartGroup",
       "AiQuestion",
       "AiReasoning",
       "AiResponse",
@@ -6987,6 +6851,7 @@
       "Combobox",
       "Commander",
       "CommandPalette",
+      "DashboardGrid",
       "DataGrid",
       "DatePicker",
       "DateRangePicker",
@@ -7005,6 +6870,7 @@
       "Map",
       "MenuBar",
       "Meter",
+      "MetricsOverview",
       "PageHeader",
       "Pagination",
       "Popover",
@@ -7015,11 +6881,14 @@
       "SensitiveInput",
       "Sidebar",
       "SignalFlareAILogo",
+      "Sparkline",
+      "StatCard",
       "Surface",
       "Switch",
       "Table",
       "Tabs",
       "Text",
+      "TextRoll",
       "ThemeToggle",
       "Toasty",
       "Tooltip"
@@ -7032,9 +6901,9 @@
         "AiCodeBlock",
         "AiConversation",
         "AiInfoBanner",
-        "AiLoader",
         "AiMessage",
         "AiMissionHeader",
+        "AiPartGroup",
         "AiQuestion",
         "AiReasoning",
         "AiResponse",
@@ -7081,11 +6950,14 @@
         "SensitiveInput",
         "Sidebar",
         "SignalFlareAILogo",
+        "Sparkline",
+        "StatCard",
         "Surface",
         "Switch",
         "Table",
         "Tabs",
         "Text",
+        "TextRoll",
         "ThemeToggle",
         "Toasty",
         "Tooltip"
@@ -7093,11 +6965,13 @@
       "block": [
         "AgentHarness",
         "Commander",
+        "DashboardGrid",
         "DeleteResource",
         "Map",
+        "MetricsOverview",
         "PageHeader",
         "ResourceListPage"
       ]
     }
   }
-}
+}