@flamingo-stack/openframe-frontend-core 0.0.187 → 0.0.188

package/src/components/chat/tool-execution-display.tsx

@@ -3,14 +3,13 @@
 import { forwardRef, useMemo, useState } from "react"
 
 import { cn } from "../../utils/cn"
-import { CheckCircleIcon, XmarkCircleIcon } from "../icons-v2-generated"
+import { CheckCircleIcon, DotsLoaderIcon, XmarkCircleIcon } from "../icons-v2-generated"
 import { ToolType } from "../platform"
 import { ToolIcon } from "../tool-icon"
-import { PulseDots } from "../ui/pulse-dots"
 import { ExpandChevron } from "./expand-chevron"
 import { useCollapsible } from "./hooks/use-collapsible"
 import { ArgRow, ResultBlock } from "./tool-call-blocks"
-import { COMMAND_BODY_ARG_KEYS } from "./utils/tool-call-helpers"
+import { COMMAND_BODY_ARG_KEYS, getToolCallTitle } from "./utils/tool-call-helpers"
 import type { ToolExecutionDisplayProps } from "./types"
 
 const COMMAND_BODY_KEYS = new Set<string>(COMMAND_BODY_ARG_KEYS)
@@ -24,11 +23,15 @@ const ToolExecutionDisplay = forwardRef<HTMLDivElement, ToolExecutionDisplayProp
     const isExecuted = message.type === "EXECUTED_TOOL"
     const integratedToolType = (message.integratedToolType as ToolType) || ("OPENFRAME" as ToolType)
 
-    const previewText = useMemo(() => {
-      const command = message.parameters?.command ?? message.parameters?.query
-      if (command) return String(command)
-      return message.toolFunction ?? ""
-    }, [message.toolFunction, message.parameters])
+    const previewText = useMemo(
+      () =>
+        getToolCallTitle({
+          args: message.parameters,
+          title: message.toolTitle,
+          name: message.toolFunction,
+        }),
+      [message.parameters, message.toolTitle, message.toolFunction],
+    )
 
     const argEntries = useMemo<Array<[string, unknown]>>(() => {
       if (!message.parameters || typeof message.parameters !== "object") return []
@@ -41,7 +44,7 @@ const ToolExecutionDisplay = forwardRef<HTMLDivElement, ToolExecutionDisplayProp
     const hasBody = argEntries.length > 0 || hasResult || isExecuting
 
     const renderStatusIcon = () => {
-      if (isExecuting) return <PulseDots size="sm" />
+      if (isExecuting) return <DotsLoaderIcon size={16} className="text-ods-text-secondary" />
       if (isExecuted && message.success === true) return <CheckCircleIcon className="w-4 h-4 text-ods-success" />
       if (isExecuted && message.success === false) return <XmarkCircleIcon className="w-4 h-4 text-ods-error" />
       return null
@@ -72,7 +75,7 @@ const ToolExecutionDisplay = forwardRef<HTMLDivElement, ToolExecutionDisplayProp
                 : "text-ods-text-secondary line-clamp-2 max-h-10 break-all",
             )}
           >
-            {expanded ? message.toolFunction || previewText : previewText}
+            {previewText}
           </div>
           <div className="flex items-center justify-center shrink-0 w-5 h-5">{renderStatusIcon()}</div>
           <div className="flex items-center justify-center shrink-0 w-5 h-5">
@@ -91,7 +94,7 @@ const ToolExecutionDisplay = forwardRef<HTMLDivElement, ToolExecutionDisplayProp
                 {isExecuting && (
                   <div className="flex flex-col gap-1 items-start w-full">
                     <span className="text-ods-text-secondary">Result:</span>
-                    <PulseDots size="sm" />
+                    <DotsLoaderIcon size={16} className="text-ods-text-secondary" />
                   </div>
                 )}
               </div>

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

@@ -5,7 +5,7 @@
 
 import type { ChunkData, NatsMessageType, FetchChunksFunction } from './network.types'
 import type { ChatType, ChatApprovalStatus } from './chat.types'
-import type { MessageSegment, PendingToolCallData, TokenUsageData } from './message.types'
+import type { MessageSegment, PendingToolCallData, TokenUsageData, ExecutingToolState } from './message.types'
 
 // ========== Hook Options ==========
 
@@ -150,7 +150,7 @@ export interface UseRealtimeChunkProcessorOptions {
     /** Pending approvals that haven't been resolved */
     pendingApprovals?: Map<string, { command: string; explanation?: string; approvalType: string }>
     /** Executing tools waiting for completion */
-    executingTools?: Map<string, { integratedToolType: string; toolFunction: string; parameters?: Record<string, any> }>
+    executingTools?: Map<string, ExecutingToolState>
     /** Escalated approvals */
     escalatedApprovals?: Map<
       string,

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

@@ -35,6 +35,8 @@ export interface ToolExecutionData {
   type: 'EXECUTING_TOOL' | 'EXECUTED_TOOL'
   integratedToolType: string
   toolFunction: string
+  /** Backend-issued human-readable title (mirrors `PendingToolCallData.toolTitle`). */
+  toolTitle?: string
   parameters?: Record<string, any>
   result?: string
   success?: boolean
@@ -46,6 +48,21 @@ export interface ToolExecutionData {
   toolExecutionRequestId?: string
 }
 
+/**
+ * Snapshot of an in-flight tool kept between the `EXECUTING_TOOL` and
+ * `EXECUTED_TOOL` events. The backend only sends `toolTitle` on
+ * `EXECUTING_TOOL`; carrying this state lets the accumulator restore it onto
+ * the merged `EXECUTED_TOOL` segment instead of falling back to the raw
+ * `toolFunction`.
+ */
+export interface ExecutingToolState {
+  integratedToolType: string
+  toolFunction: string
+  /** Mirrors {@link ToolExecutionData.toolTitle}; absent on `EXECUTED_TOOL`. */
+  toolTitle?: string
+  parameters?: Record<string, any>
+}
+
 // ========== Approval Request Types ==========
 
 export interface ApprovalRequestData {
@@ -171,6 +188,8 @@ export interface ExecutingToolMessageData extends MessageDataBase {
   type: 'EXECUTING_TOOL'
   integratedToolType?: string
   toolFunction?: string
+  /** Backend-issued human-readable title (wire field, mirrors `ChunkData.title`). */
+  title?: string
   parameters?: Record<string, any>
   toolExecutionRequestId?: string
 }
@@ -179,6 +198,8 @@ export interface ExecutedToolMessageData extends MessageDataBase {
   type: 'EXECUTED_TOOL'
   integratedToolType?: string
   toolFunction?: string
+  /** Backend-issued human-readable title (wire field, mirrors `ChunkData.title`). */
+  title?: string
   parameters?: Record<string, any>
   result?: string
   success?: boolean

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

@@ -38,6 +38,8 @@ export interface ChunkData {
   text?: string
   integratedToolType?: string
   toolFunction?: string
+  /** Execution chunks carry the human-readable title as `title`. */
+  title?: string
   parameters?: Record<string, any>
   result?: string
   success?: boolean

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

@@ -3,7 +3,7 @@
  * Contains types for message parsing, accumulation, and processing
  */
 
-import type { MessageSegment, ProcessedMessage, ToolExecutionSegment, TokenUsageData, PendingToolCallData } from './message.types'
+import type { MessageSegment, ProcessedMessage, ToolExecutionSegment, TokenUsageData, PendingToolCallData, ExecutingToolState } from './message.types'
 import type { ChatApprovalStatus, AssistantType } from './chat.types'
 import type { ChunkData, NatsMessageType } from './network.types'
 
@@ -39,11 +39,7 @@ export interface PendingApproval {
 export interface AccumulatorState {
   segments: MessageSegment[]
   pendingApprovals: Map<string, PendingApproval>
-  executingTools: Map<string, {
-    integratedToolType: string
-    toolFunction: string
-    parameters?: Record<string, any>
-  }>
+  executingTools: Map<string, ExecutingToolState>
   escalatedApprovals?: Map<
     string,
     { command: string; explanation?: string; approvalType: string; toolCalls?: PendingToolCallData[] }

package/src/components/chat/utils/chunk-parser.ts

@@ -74,6 +74,7 @@ export function parseChunkToAction(chunk: unknown): ParsedChunkAction | null {
             type: 'EXECUTING_TOOL',
             integratedToolType: data.integratedToolType || '',
             toolFunction: data.toolFunction || '',
+            toolTitle: typeof data.title === 'string' ? data.title : undefined,
             parameters: data.parameters,
             toolExecutionRequestId: typeof data.toolExecutionRequestId === 'string' ? data.toolExecutionRequestId : undefined,
           }
@@ -89,6 +90,7 @@ export function parseChunkToAction(chunk: unknown): ParsedChunkAction | null {
             type: 'EXECUTED_TOOL',
             integratedToolType: data.integratedToolType || '',
             toolFunction: data.toolFunction || '',
+            toolTitle: typeof data.title === 'string' ? data.title : undefined,
             parameters: data.parameters,
             result: data.result,
             success: data.success,

package/src/components/chat/utils/extract-incomplete-message-state.ts

@@ -7,6 +7,7 @@ import type {
   ProcessedMessage,
   MessageSegment,
   PendingApproval,
+  ExecutingToolState,
 } from '../types'
 
 /**
@@ -18,7 +19,7 @@ export function extractIncompleteMessageState(
 ): {
   existingSegments?: MessageSegment[]
   pendingApprovals?: Map<string, PendingApproval>
-  executingTools?: Map<string, { integratedToolType: string; toolFunction: string; parameters?: Record<string, any> }>
+  executingTools?: Map<string, ExecutingToolState>
 } | undefined {
   if (!lastMessage || lastMessage.role !== 'assistant' || typeof lastMessage.content === 'string') {
     return undefined
@@ -26,7 +27,7 @@ export function extractIncompleteMessageState(
 
   const segments = lastMessage.content as MessageSegment[]
   const pendingApprovals = new Map<string, PendingApproval>()
-  const executingTools = new Map<string, { integratedToolType: string; toolFunction: string; parameters?: Record<string, any> }>()
+  const executingTools = new Map<string, ExecutingToolState>()
   let hasIncompleteState = false
 
   segments.forEach(segment => {
@@ -39,6 +40,7 @@ export function extractIncompleteMessageState(
           executingTools.set(toolKey, {
             integratedToolType: segment.data.integratedToolType,
             toolFunction: segment.data.toolFunction,
+            toolTitle: segment.data.toolTitle,
             parameters: segment.data.parameters,
           })
           hasIncompleteState = true

package/src/components/chat/utils/message-segment-accumulator.ts

@@ -20,6 +20,7 @@ import type {
   PendingToolCallData,
   AccumulatorState,
   ChatApprovalStatus,
+  ExecutingToolState,
 } from '../types'
 
 export interface AccumulatorCallbacks {
@@ -34,7 +35,7 @@ export interface AccumulatorCallbacks {
 export class MessageSegmentAccumulator {
   private segments: MessageSegment[] = []
   private pendingApprovals: Map<string, PendingApproval> = new Map()
-  private executingTools: Map<string, { integratedToolType: string; toolFunction: string; parameters?: Record<string, any> }> = new Map()
+  private executingTools: Map<string, ExecutingToolState> = new Map()
   private callbacks: AccumulatorCallbacks = {}
 
   constructor(callbacks?: AccumulatorCallbacks) {
@@ -57,7 +58,7 @@ export class MessageSegmentAccumulator {
   initializeWithState(state: {
     existingSegments?: MessageSegment[]
     pendingApprovals?: Map<string, PendingApproval>
-    executingTools?: Map<string, { integratedToolType: string; toolFunction: string; parameters?: Record<string, any> }>
+    executingTools?: Map<string, ExecutingToolState>
   }): void {
     if (state.existingSegments) {
       this.segments = [...state.existingSegments]
@@ -164,6 +165,7 @@ export class MessageSegmentAccumulator {
       this.executingTools.set(toolKey, {
         integratedToolType: toolData.integratedToolType,
         toolFunction: toolData.toolFunction,
+        toolTitle: toolData.toolTitle,
         parameters: toolData.parameters,
       })
       this.segments.push(segment)
@@ -179,10 +181,17 @@ export class MessageSegmentAccumulator {
       )
 
       const executingTool = this.executingTools.get(toolKey)
+      // The backend omits `toolTitle` on EXECUTED_TOOL; restore it from the
+      // paired EXECUTING segment (or its tracked state) so the completed
+      // segment keeps the human-readable title instead of falling back to the
+      // raw `toolFunction`.
+      const existingExecuting =
+        existingIndex !== -1 ? (this.segments[existingIndex] as ToolExecutionSegment) : undefined
       const mergedSegment: ToolExecutionSegment = {
         type: 'tool_execution',
         data: {
           ...toolData,
+          toolTitle: toolData.toolTitle ?? existingExecuting?.data.toolTitle ?? executingTool?.toolTitle,
           parameters: toolData.parameters || executingTool?.parameters,
         }
       }

package/src/components/chat/utils/process-historical-messages.ts

@@ -231,6 +231,7 @@ function processMessageData(
             type: 'EXECUTING_TOOL',
             integratedToolType: data.integratedToolType || '',
             toolFunction: data.toolFunction || '',
+            toolTitle: typeof data.title === 'string' ? data.title : undefined,
             parameters: data.parameters,
             toolExecutionRequestId: data.toolExecutionRequestId,
           },
@@ -246,6 +247,7 @@ function processMessageData(
             type: 'EXECUTED_TOOL',
             integratedToolType: data.integratedToolType || '',
             toolFunction: data.toolFunction || '',
+            toolTitle: typeof data.title === 'string' ? data.title : undefined,
             parameters: data.parameters,
             result: data.result,
             success: data.success,

package/src/components/chat/utils/tool-call-helpers.ts

@@ -8,19 +8,38 @@ import type { PendingToolCallData } from '../types'
 export const COMMAND_BODY_ARG_KEYS = ['command', 'query', 'script', 'scriptContent', 'code'] as const
 
 /**
- * Extract a human-readable command string from a tool call.
- * Order: command/query/script/scriptContent/code arg → toolTitle → toolName → fallback.
+ * Resolve the human-readable title/preview line for a tool call.
+ * Order: command/query/script/scriptContent/code arg → title → name → fallback.
+ *
+ * Shape-agnostic so both the approval card (`PendingToolCallData`:
+ * `toolCallArguments`/`toolName`) and the execution card (`ToolExecutionData`:
+ * `parameters`/`toolFunction`) can share one source of truth.
  */
-export function getCommandText(call: PendingToolCallData): string {
-  const args = call.toolCallArguments
+export function getToolCallTitle(opts: {
+  args?: Record<string, unknown> | null
+  title?: string | null
+  name?: string | null
+}): string {
+  const { args, title, name } = opts
   if (args && typeof args === 'object') {
-    const a = args as Record<string, unknown>
     for (const key of COMMAND_BODY_ARG_KEYS) {
-      const candidate = a[key]
+      const candidate = args[key]
       if (typeof candidate === 'string' && candidate.trim()) return candidate
     }
   }
-  return call.toolTitle || call.toolName || 'Tool call'
+  return title || name || 'Tool call'
+}
+
+/**
+ * Extract a human-readable command string from a batch tool call.
+ * Thin adapter over {@link getToolCallTitle}.
+ */
+export function getCommandText(call: PendingToolCallData): string {
+  return getToolCallTitle({
+    args: call.toolCallArguments,
+    title: call.toolTitle,
+    name: call.toolName,
+  })
 }
 
 export type FormattedArgValue =
@@ -29,6 +48,74 @@ export type FormattedArgValue =
 
 const INLINE_STRING_MAX = 80
 
+/**
+ * Pretty-print like `JSON.stringify(value, null, 2)`, but render multi-line
+ * string values across real lines instead of escaped `\n` sequences.
+ *
+ * Trade-off: the output is optimised for human reading, not for being
+ * re-parsed as JSON (multi-line string bodies lose their surrounding quotes
+ * and escaping). Single-line strings keep normal JSON quoting/escaping.
+ *
+ * `indent` is the nesting level of this value's content lines / closing
+ * bracket (matching the 2-space step of `JSON.stringify(_, null, 2)`).
+ */
+function expandJson(value: unknown, indent: number): string {
+  const pad = (n: number) => '  '.repeat(n)
+
+  if (value === null) return 'null'
+  const t = typeof value
+  if (t === 'number' || t === 'boolean' || t === 'bigint') return String(value)
+
+  if (t === 'string') {
+    const s = (value as string).replace(/\r\n/g, '\n').replace(/\r/g, '\n')
+    if (!s.includes('\n')) return JSON.stringify(s)
+    return s
+      .replace(/^\n+/, '')
+      .replace(/\n+$/, '')
+      .split('\n')
+      .map((line) => pad(indent) + line)
+      .join('\n')
+  }
+
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]'
+    const items = value.map((v) =>
+      typeof v === 'string' && /[\r\n]/.test(v)
+        ? expandJson(v, indent + 1)
+        : pad(indent + 1) + expandJson(v, indent + 1),
+    )
+    return '[\n' + items.join(',\n') + '\n' + pad(indent) + ']'
+  }
+
+  if (t === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>)
+    if (entries.length === 0) return '{}'
+    const items = entries.map(([k, v]) => {
+      const key = JSON.stringify(k)
+      if (typeof v === 'string' && /[\r\n]/.test(v)) {
+        return pad(indent + 1) + key + ':\n' + expandJson(v, indent + 2)
+      }
+      return pad(indent + 1) + key + ': ' + expandJson(v, indent + 1)
+    })
+    return '{\n' + items.join(',\n') + '\n' + pad(indent) + '}'
+  }
+
+  return JSON.stringify(value)
+}
+
+/**
+ * Entry point for {@link expandJson}: readable pretty-print where multi-line
+ * string fields (script bodies, command output, …) are shown with real line
+ * breaks instead of literal `\n`.
+ */
+export function expandedJsonStringify(value: unknown): string {
+  try {
+    return expandJson(value, 0)
+  } catch {
+    return String(value)
+  }
+}
+
 /**
  * Decide how to render a single `toolCallArguments` value:
  *  - objects/arrays → pretty-printed JSON block
@@ -50,7 +137,7 @@ export function formatToolArgValue(value: unknown): FormattedArgValue {
       (trimmed.startsWith('[') && trimmed.endsWith(']'))
     ) {
       try {
-        return { kind: 'block', text: JSON.stringify(JSON.parse(trimmed), null, 2), language: 'json' }
+        return { kind: 'block', text: expandedJsonStringify(JSON.parse(trimmed)), language: 'json' }
       } catch {
         // not valid JSON — fall through
       }
@@ -65,11 +152,7 @@ export function formatToolArgValue(value: unknown): FormattedArgValue {
 }
 
 function safeStringify(value: unknown): string {
-  try {
-    return JSON.stringify(value, null, 2)
-  } catch {
-    return String(value)
-  }
+  return expandedJsonStringify(value)
 }
 
 /**
@@ -92,7 +175,7 @@ export function formatToolResult(value: string | undefined | null): FormattedArg
     (trimmed.startsWith('[') && trimmed.endsWith(']'))
   ) {
     try {
-      return { kind: 'block', text: JSON.stringify(JSON.parse(trimmed), null, 2), language: 'json' }
+      return { kind: 'block', text: expandedJsonStringify(JSON.parse(trimmed)), language: 'json' }
     } catch {
       // fall through
     }

package/src/components/icons-v2/loaders/dots-loader.svg

@@ -0,0 +1 @@
+<svg fill="#888" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><circle cx="4" cy="12" r="3"><animate attributeName="r" dur="0.75s" values="3;.2;3" repeatCount="indefinite" begin="0s"/></circle><circle cx="12" cy="12" r="3"><animate attributeName="r" dur="0.75s" values="3;.2;3" repeatCount="indefinite" begin="0.15s"/></circle><circle cx="20" cy="12" r="3"><animate attributeName="r" dur="0.75s" values="3;.2;3" repeatCount="indefinite" begin="0.3s"/></circle></svg>

package/src/components/icons-v2-generated/index.ts

@@ -16,6 +16,7 @@ export * from './food-and-drinks';
 export * from './health';
 export * from './household';
 export * from './interface';
+export * from './loaders';
 export * from './map-and-travel';
 export * from './media-playback';
 export * from './number';

package/src/components/icons-v2-generated/loaders/dots-loader-icon.tsx

@@ -0,0 +1,53 @@
+import type { SVGProps } from "react";
+export interface DotsLoaderIconProps
+  extends Omit<SVGProps<SVGSVGElement>, "width" | "height"> {
+  className?: string;
+  size?: number;
+  color?: string;
+}
+export function DotsLoaderIcon({
+  className = "",
+  size = 24,
+  color = "currentColor",
+  ...props
+}: DotsLoaderIconProps) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      fill={color}
+      viewBox="0 0 24 24"
+      width={size}
+      height={size}
+      className={className}
+      {...props}
+    >
+      <circle cx={4} cy={12} r={3}>
+        <animate
+          attributeName="r"
+          dur="0.75s"
+          values="3;.2;3"
+          repeatCount="indefinite"
+          begin="0s"
+        />
+      </circle>
+      <circle cx={12} cy={12} r={3}>
+        <animate
+          attributeName="r"
+          dur="0.75s"
+          values="3;.2;3"
+          repeatCount="indefinite"
+          begin="0.15s"
+        />
+      </circle>
+      <circle cx={20} cy={12} r={3}>
+        <animate
+          attributeName="r"
+          dur="0.75s"
+          values="3;.2;3"
+          repeatCount="indefinite"
+          begin="0.3s"
+        />
+      </circle>
+    </svg>
+  );
+}

package/src/components/icons-v2-generated/loaders/index.ts

@@ -0,0 +1 @@
+export { DotsLoaderIcon } from './dots-loader-icon';

package/src/components/ui/index.ts

@@ -44,8 +44,6 @@ export * from './menubar'
 export * from './navigation-menu'
 export * from './tab-content'
 export * from './tab-navigation'
-// Animation components
-export * from './pulse-dots'
 // Feedback components
 export * from './alert'
 export * from './badge'

package/src/stories/DotsLoaderIcon.stories.tsx

@@ -0,0 +1,103 @@
+import type { Meta, StoryObj } from '@storybook/nextjs-vite';
+import { DotsLoaderIcon } from '../components/icons-v2-generated/loaders/dots-loader-icon';
+
+const meta = {
+  title: 'UI/DotsLoaderIcon',
+  component: DotsLoaderIcon,
+  argTypes: {
+    size: {
+      control: { type: 'number', min: 12, max: 128, step: 4 },
+    },
+    color: {
+      control: 'text',
+      description: 'CSS color. Defaults to `currentColor` — pass an ODS token like `var(--ods-accent)`.',
+    },
+    className: { control: 'text' },
+  },
+  parameters: {
+    layout: 'centered',
+  },
+} satisfies Meta<typeof DotsLoaderIcon>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Default — 24px, inherits text color via `currentColor`.
+ * The three dots animate in an infinite loop (SMIL chain).
+ */
+export const Default: Story = {
+  args: {
+    size: 24,
+  },
+};
+
+/**
+ * Large size for full-page / blocking loading states.
+ */
+export const Large: Story = {
+  args: {
+    size: 64,
+  },
+};
+
+/**
+ * Inherits the surrounding text color through `currentColor`.
+ */
+export const InheritsTextColor: Story = {
+  args: {
+    size: 40,
+  },
+  render: (args) => (
+    <div className="text-ods-accent">
+      <DotsLoaderIcon {...args} />
+    </div>
+  ),
+};
+
+/**
+ * Explicit ODS color tokens — never hardcode hex.
+ */
+export const OdsColors: Story = {
+  args: {
+    size: 40,
+  },
+  render: (args) => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '2rem' }}>
+      <DotsLoaderIcon {...args} color="var(--ods-text-primary)" />
+      <DotsLoaderIcon {...args} color="var(--ods-text-secondary)" />
+      <DotsLoaderIcon {...args} color="var(--ods-accent)" />
+      <DotsLoaderIcon {...args} color="var(--ods-error)" />
+    </div>
+  ),
+};
+
+/**
+ * Size scale.
+ */
+export const Sizes: Story = {
+  args: {},
+  render: () => (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '2rem' }}>
+      <DotsLoaderIcon size={16} />
+      <DotsLoaderIcon size={24} />
+      <DotsLoaderIcon size={40} />
+      <DotsLoaderIcon size={64} />
+      <DotsLoaderIcon size={96} />
+    </div>
+  ),
+};
+
+/**
+ * In context — centered inside a card, as used for inline loading.
+ */
+export const InCard: Story = {
+  args: {
+    size: 32,
+  },
+  render: (args) => (
+    <div className="flex items-center justify-center bg-ods-card border border-ods-border rounded-lg w-64 h-40 text-ods-text-secondary">
+      <DotsLoaderIcon {...args} />
+    </div>
+  ),
+};