@agent-ui-kit/web-components 0.0.14 → 0.0.15

package/dist/docs/components/agent-message.yaml

@@ -2,85 +2,70 @@ name: aui-agent-message
 tag: aui-agent-message
 type: component
 summary: Individual chat message bubble with action toolbar.
-description: >
-  Accepts slotted content: aui-agent-text, aui-agent-activity,
-  aui-agent-seeds, or any custom content. Provides a configurable
-  action toolbar (copy, retry, edit, feedback) that appears on hover
-  via CSS anchor positioning as a popover below the bubble.
-
+description: |
+  Accepts slotted content: aui-agent-text, aui-agent-activity, aui-agent-seeds, or any custom content. Provides a configurable action toolbar (copy, retry, edit, feedback) that appears on hover via CSS anchor positioning as a popover below the bubble.
 base: AgentElement
-
 attributes:
   role:
     syntax: key-value
     type: string
     default: assistant
     description: Message role — user, assistant, or system.
-
   message-id:
     syntax: key-value
     type: string
     default: ""
     description: Unique message identifier.
-
   timestamp:
     syntax: key-value
     type: string
     default: ""
     description: Epoch milliseconds.
-
   status:
     syntax: key-value
     type: string
     default: sent
-    description: >
+    description: |
       Message status — sending, sent, error, streaming, or partial.
-
   actions:
     syntax: key-value
     type: string
     default: ""
-    description: >
-      Comma-separated action list, or "none" to suppress.
-      Defaults per role — assistant: copy,retry,feedback-up,feedback-down;
-      user: edit,retry.
-
+    description: |
+      Comma-separated action list, or "none" to suppress. Defaults per role — assistant: copy,retry,feedback-up,feedback-down; user: edit,retry.
   actions-style:
     syntax: key-value
     type: string
     default: icon
     description: Action button style — icon, label, or icon-label.
-
   actions-position:
     syntax: key-value
     type: string
     default: below
     description: Toolbar placement — below (popover) or inside (inline).
-
 a11y:
   role: article
-
 events:
   aui:message-action:
-    description: >
-      Fired when an action button is clicked.
-      detail contains action and messageId.
-
+    description: |
+      Fired when an action button is clicked. detail contains action and messageId.
   aui:continue-request:
-    description: >
-      Fired when continue is requested for a partial message.
-      detail contains messageId.
-
+    description: |
+      Fired when continue is requested for a partial message. detail contains messageId.
 composition:
-  parents: [aui-agent-thread]
-  children: [aui-agent-text, aui-agent-activity, aui-agent-seeds, any]
-
+  parents:
+    - aui-agent-thread
+  children:
+    - aui-agent-text
+    - aui-agent-activity
+    - aui-agent-seeds
+    - any
 tokens:
   - name: --aui-agent-message-border-radius
     default: var(--aui-agent-bubble-radius, var(--aui-radius))
     description: Border radius for message bubbles.
   - name: --aui-agent-message-border-radius-tight
-    default: "calc(var(--aui-space) * 2)"
+    default: calc(var(--aui-space) * 2)
     description: Tighter radius for grouped bubble corners near the avatar.
   - name: --aui-agent-message-background
     default: var(--aui-agent-bubble-assistant, transparent)
@@ -122,10 +107,10 @@ tokens:
     default: var(--aui-ink-muted)
     description: Text color of action buttons.
   - name: --aui-agent-message-action-padding
-    default: "calc(var(--aui-space) * 0.5) calc(var(--aui-space) * 1)"
+    default: calc(var(--aui-space) * 0.5) calc(var(--aui-space) * 1)
     description: Padding of individual action buttons.
   - name: --aui-agent-message-action-gap
-    default: "calc(var(--aui-space) * 0.5)"
+    default: calc(var(--aui-space) * 0.5)
     description: Gap between icon and label within an action button.
   - name: --aui-agent-message-action-background-hover
     default: var(--aui-fill-hover, var(--aui-action-hover))
@@ -134,7 +119,7 @@ tokens:
     default: var(--aui-ink)
     description: Text color of action buttons on hover.
   - name: --aui-agent-message-popover-padding
-    default: "calc(var(--aui-space) * 0.5)"
+    default: calc(var(--aui-space) * 0.5)
     description: Padding inside the popover actions toolbar.
   - name: --aui-agent-message-popover-background
     default: var(--aui-modal, var(--aui-doc))
@@ -146,11 +131,11 @@ tokens:
     default: var(--aui-radius)
     description: Border radius of the popover actions toolbar.
   - name: --aui-agent-message-popover-shadow
-    default: "var(--aui-shadow-lg, 0 4px 16px oklch(0% 0 0 / 0.12))"
+    default: var(--aui-shadow-lg, 0 4px 16px oklch(0% 0 0 / 0.12))
     description: Box shadow of the popover actions toolbar.
-
 examples:
-  - html: |
+  - description: Assistant message with default actions (copy, retry, feedback). Hover reveals the action toolbar below
+    html: |-
       <aui-agent-message role="assistant" status="sent" message-id="msg-001">
         <aui-agent-text>Based on your project structure, I recommend using a **monorepo** with the following layout:
 
@@ -160,15 +145,13 @@ examples:
 
       This keeps dependencies clean and enables independent versioning for each package.</aui-agent-text>
       </aui-agent-message>
-    description: Assistant message with default actions (copy, retry, feedback). Hover reveals the action toolbar below.
-
-  - html: |
+  - description: User message with edit and retry actions
+    html: |-
       <aui-agent-message role="user" message-id="msg-002">
         <aui-agent-text format="plain">How do I set up path aliases in TypeScript so imports like @/components work across all packages?</aui-agent-text>
       </aui-agent-message>
-    description: User message with edit and retry actions.
-
-  - html: |
+  - description: Streaming message — content is still arriving. Actions are suppressed during streaming
+    html: |-
       <aui-agent-message role="assistant" status="streaming" message-id="msg-003" actions="none">
         <aui-agent-text>You'll need to configure `paths` in your root `tsconfig.json` and then extend it in each package. Here's the base config:
 
@@ -185,10 +168,8 @@ examples:
 
       Each package tsconfig extends this and...</aui-agent-text>
       </aui-agent-message>
-    description: Streaming message — content is still arriving. Actions are suppressed during streaming.
-
-  - html: |
+  - description: Error message — status="error" applies error styling and surfaces a retry action
+    html: |-
       <aui-agent-message role="assistant" status="error" message-id="msg-004">
         <aui-agent-text format="plain">Something went wrong while generating the response. Please try again.</aui-agent-text>
       </aui-agent-message>
-    description: Error message — status="error" applies error styling and surfaces a retry action.

package/dist/docs/components/agent-panel.yaml

@@ -2,44 +2,43 @@ name: aui-agent-panel
 tag: aui-agent-panel
 type: component
 summary: Top-level chat shell that composes header, feed, and input.
-description: >
-  Layout coordinator for agent chat interfaces. Discovers child
-  aui-agent-feed and aui-agent-input elements and provides focus
-  delegation via focusComposer(). Sets role="region" with an
-  aria-label derived from the panel-title attribute. Does not stamp
-  DOM — just discovers and coordinates existing children.
-
+description: |
+  Layout coordinator for agent chat interfaces. Discovers child aui-agent-feed and aui-agent-input elements and provides focus delegation via focusComposer(). Sets role="region" with an aria-label derived from the panel-title attribute. Does not stamp DOM — just discovers and coordinates existing children.
 base: AgentElement
-
 attributes:
   panel-title:
     syntax: string
     type: string
-    default: ''
+    default: ""
     description: Title for the panel, used as aria-label for the region.
-
   auto-focus:
     syntax: string
     type: string
     default: ready
-    description: >
-      When to auto-focus the composer. 'ready' focuses on activate,
-      'open-request' defers until an external signal, 'never' skips.
-
+    description: |
+      When to auto-focus the composer. 'ready' focuses on activate, 'open-request' defers until an external signal, 'never' skips.
 a11y:
   role: region
   aria-label: Derived from panel-title attribute
-
 methods:
   focusComposer:
     description: Delegates focus to the child aui-agent-input composer.
-
 composition:
-  parents: [aui-content, aui-pane, aui-dialog, aui-drawer, div, any]
-  children: [aui-header, aui-agent-feed, aui-agent-input, aui-footer]
-
+  parents:
+    - aui-content
+    - aui-pane
+    - aui-dialog
+    - aui-drawer
+    - div
+    - any
+  children:
+    - aui-header
+    - aui-agent-feed
+    - aui-agent-input
+    - aui-footer
 examples:
-  - html: |
+  - description: Full chat panel with header, message feed, and composer input
+    html: |-
       <aui-agent-panel panel-title="Design Assistant" max-width="xl" style="height: 32rem;">
         <aui-header dividers>
           <aui-stack direction="row" gap="2" align-items="center">
@@ -70,9 +69,8 @@ examples:
           </aui-agent-prompt>
         </aui-agent-input>
       </aui-agent-panel>
-    description: Full chat panel with header, message feed, and composer input.
-
-  - html: |
+  - description: Minimal chat panel with just feed and input, no header
+    html: |-
       <aui-agent-panel panel-title="Quick Chat" max-width="xl" style="height: 24rem;">
         <aui-agent-feed auto-scroll scrollable>
           <aui-agent-thread role="assistant" sender="Claude">
@@ -88,4 +86,3 @@ examples:
           </aui-agent-prompt>
         </aui-agent-input>
       </aui-agent-panel>
-    description: Minimal chat panel with just feed and input, no header.

package/dist/docs/components/agent-prompt.yaml

@@ -2,15 +2,9 @@ name: aui-agent-prompt
 tag: aui-agent-prompt
 type: component
 summary: Bordered prompt container for the chat composer textarea.
-description: >
-  Visual wrapper around the textarea inside aui-agent-input.
-  Provides bordered styling with focus ring when the inner
-  aui-textarea gains focus. Contains aui-textarea, optional
-  inline action buttons (ghost + hide-label), and a bottom
-  toolbar via aui-inset > aui-select mode="bar" transparent.
-
+description: |
+  Visual wrapper around the textarea inside aui-agent-input. Provides bordered styling with focus ring when the inner aui-textarea gains focus. Contains aui-textarea, optional inline action buttons (ghost + hide-label), and a bottom toolbar via aui-inset > aui-select mode="bar" transparent.
 base: AgentElement
-
 attributes:
   disabled:
     syntax: boolean
@@ -21,15 +15,17 @@ attributes:
     syntax: boolean
     type: boolean
     default: false
-    description: >
-      Single-line mode. Switches to row layout with textarea and send
-      button side-by-side. Textarea gets compact block padding and the
-      trailing button sits inline. Toolbar border is suppressed.
-
+    description: |
+      Single-line mode. Switches to row layout with textarea and send button side-by-side. Textarea gets compact block padding and the trailing button sits inline. Toolbar border is suppressed.
 composition:
-  parents: [aui-agent-input, aui-stack]
-  children: [aui-textarea, aui-button, aui-inset, any]
-
+  parents:
+    - aui-agent-input
+    - aui-stack
+  children:
+    - aui-textarea
+    - aui-button
+    - aui-inset
+    - any
 tokens:
   - name: --aui-agent-prompt-background
     default: var(--aui-control)
@@ -47,19 +43,19 @@ tokens:
     default: var(--aui-focus)
     description: Focus ring color when textarea is focused.
   - name: --aui-agent-prompt-surface-padding-block
-    default: "calc(var(--aui-space) * 2)"
+    default: calc(var(--aui-space) * 2)
     description: Block padding of the textarea surface.
   - name: --aui-agent-prompt-surface-padding-inline
-    default: "calc(var(--aui-space) * 3)"
+    default: calc(var(--aui-space) * 3)
     description: Inline padding of the textarea surface.
   - name: --aui-agent-prompt-toolbar-border
     default: var(--aui-border-muted)
     description: Border color of the bottom toolbar separator.
   - name: --aui-agent-prompt-toolbar-gap
-    default: "calc(var(--aui-space) * 2)"
+    default: calc(var(--aui-space) * 2)
     description: Gap between items in the toolbar.
   - name: --aui-agent-prompt-toolbar-padding
-    default: "calc(var(--aui-space) * 2)"
+    default: calc(var(--aui-space) * 2)
     description: Padding of the toolbar area.
   - name: --aui-agent-prompt-ghost-background-hover
     default: var(--aui-fill-hover)
@@ -71,55 +67,41 @@ tokens:
     default: var(--aui-fill-hover)
     description: Hover background in outline variant.
   - name: --aui-agent-prompt-inline-surface-padding-block
-    default: "calc(var(--aui-space) * 1.5)"
+    default: calc(var(--aui-space) * 1.5)
     description: Block padding of the textarea in inline mode.
   - name: --aui-agent-prompt-inline-submit-margin
-    default: "calc(var(--aui-space) * 1.5)"
+    default: calc(var(--aui-space) * 1.5)
     description: Inline-end margin for the submit button in inline mode.
-
 examples:
-  - html: |
+  - description: Basic bordered prompt with textarea — focus ring activates when textarea is focused
+    html: |-
       <aui-agent-prompt>
         <aui-textarea placeholder="Describe what you need help with..."></aui-textarea>
       </aui-agent-prompt>
-    description: Basic bordered prompt with textarea — focus ring activates when textarea is focused.
-
-  - html: |
+  - description: Prompt with an inline action icon (sparkle) positioned beside the textarea for triggering AI features
+    html: |-
       <aui-agent-prompt>
         <aui-textarea placeholder="Ask anything..."></aui-textarea>
         <div data-role="leading">
-          <aui-button ghost size="sm">
+          <aui-button ghost>
             <aui-icon name="sparkles"></aui-icon>
           </aui-button>
         </div>
       </aui-agent-prompt>
-    description: Prompt with an inline action icon (sparkle) positioned beside the textarea for triggering AI features.
-
-  - html: |
+  - description: Prompt with action toolbar below textarea — attach files, upload images, voice input, and send
+    html: |-
       <aui-agent-prompt>
         <aui-textarea placeholder="What would you like to build today?"></aui-textarea>
         <div data-role="actions">
-          <aui-button ghost size="sm">
+          <aui-button ghost>
             <aui-icon name="paperclip"></aui-icon>
           </aui-button>
-          <aui-button ghost size="sm">
+          <aui-button ghost>
             <aui-icon name="image"></aui-icon>
           </aui-button>
-          <aui-button ghost size="sm">
+          <aui-button ghost>
             <aui-icon name="microphone"></aui-icon>
           </aui-button>
           <aui-button primary data-submit>Send</aui-button>
         </div>
       </aui-agent-prompt>
-    description: >
-      Prompt with action toolbar below textarea — attach files, upload images,
-      voice input, and send.
-
-  - html: |
-      <aui-agent-prompt inline>
-        <aui-textarea placeholder="Quick message..."></aui-textarea>
-        <aui-button round label="Send" data-submit hide-label><aui-icon name="arrow-up"></aui-icon></aui-button>
-      </aui-agent-prompt>
-    description: >
-      Inline single-line prompt with textarea and send button side-by-side.
-      Row layout with compact padding, no toolbar border.

package/dist/docs/components/agent-seeds.yaml

@@ -2,36 +2,30 @@ name: aui-agent-seeds
 tag: aui-agent-seeds
 type: component
 summary: Suggestion chips for pre-seeded quick responses.
-description: >
-  Renders a wrapped row of outline-styled chips from a JSON options array.
-  Each chip fires aui:seed-select on click with the option's value and label.
-
+description: |
+  Renders a wrapped row of outline-styled chips from a JSON options array. Each chip fires aui:seed-select on click with the option's value and label.
 base: AgentElement
-
 attributes:
   options:
     syntax: key-value
     type: string
     default: ""
-    description: >
+    description: |
       JSON array of { value, label, icon? } objects.
-
   disabled:
     syntax: boolean
     type: boolean
     default: false
     description: Disables all chips.
-
 events:
   aui:seed-select:
-    description: >
-      Fired when a chip is clicked.
-      detail contains value and label.
-
+    description: |
+      Fired when a chip is clicked. detail contains value and label.
 composition:
-  parents: [aui-agent-message, aui-agent-feed]
+  parents:
+    - aui-agent-message
+    - aui-agent-feed
   children: []
-
 tokens:
   - name: --aui-agent-seeds-padding-block
     default: var(--aui-agent-seed-pad-block, var(--aui-space))
@@ -43,13 +37,13 @@ tokens:
     default: var(--aui-agent-seed-gap, var(--aui-space))
     description: Gap between chip rows.
   - name: --aui-agent-seeds-chip-gap
-    default: "calc(var(--aui-space) * 0.5)"
+    default: calc(var(--aui-space) * 0.5)
     description: Gap between icon and label within a chip.
   - name: --aui-agent-seeds-chip-padding-block
-    default: "calc(var(--aui-space) * 0.5)"
+    default: calc(var(--aui-space) * 0.5)
     description: Block padding of each chip.
   - name: --aui-agent-seeds-chip-padding-inline
-    default: "calc(var(--aui-space) * 1.5)"
+    default: calc(var(--aui-space) * 1.5)
     description: Inline padding of each chip.
   - name: --aui-agent-seeds-chip-font-family
     default: var(--aui-font-family)
@@ -84,14 +78,12 @@ tokens:
   - name: --aui-agent-seeds-chip-background-active
     default: var(--aui-fill-active, var(--aui-action-active))
     description: Background of chips when active/pressed.
-
 examples:
-  - html: |
+  - description: Quick action suggestions — common follow-up actions presented as selectable chips below the composer or a message
+    html: |-
       <aui-agent-seeds options='[{"value":"clarify","label":"Clarify user problem"},{"value":"context","label":"Define user context"},{"value":"deliverable","label":"Select deliverable"},{"value":"timeline","label":"Set timeline"}]'>
       </aui-agent-seeds>
-    description: Quick action suggestions — common follow-up actions presented as selectable chips below the composer or a message.
-
-  - html: |
+  - description: Conversation starters with icons — used on an empty chat state to help users begin a session with common tasks
+    html: |-
       <aui-agent-seeds options='[{"value":"write-email","label":"Draft an email","icon":"mail"},{"value":"summarize","label":"Summarize a document","icon":"file-text"},{"value":"brainstorm","label":"Brainstorm ideas","icon":"lightbulb"},{"value":"analyze-data","label":"Analyze data","icon":"chart-bar"}]'>
       </aui-agent-seeds>
-    description: Conversation starters with icons — used on an empty chat state to help users begin a session with common tasks.

package/dist/docs/components/agent-text.yaml

@@ -2,25 +2,19 @@ name: aui-agent-text
 tag: aui-agent-text
 type: component
 summary: Markdown renderer for chat message content.
-description: >
-  Renders a markdown subset (paragraphs, headings, lists, code fences,
-  inline code, bold, italic, links, blockquotes) to sanitized HTML.
-  Content can come from text content or the content property.
-  Debounced rendering during streaming updates.
-
+description: |
+  Renders a markdown subset (paragraphs, headings, lists, code fences, inline code, bold, italic, links, blockquotes) to sanitized HTML. Content can come from text content or the content property. Debounced rendering during streaming updates.
 base: AgentElement
-
 attributes:
   format:
     syntax: key-value
     type: string
     default: markdown
     description: Render format — markdown (default) or plain.
-
 composition:
-  parents: [aui-agent-message]
+  parents:
+    - aui-agent-message
   children: []
-
 tokens:
   - name: --aui-agent-text-padding-block
     default: var(--aui-agent-bubble-pad-block, 0.625rem)
@@ -29,7 +23,7 @@ tokens:
     default: var(--aui-agent-bubble-pad-inline, 0.875rem)
     description: Inline padding of the text container.
   - name: --aui-agent-text-prose-gap
-    default: "var(--aui-agent-prose-gap, calc(var(--aui-space) * 2))"
+    default: var(--aui-agent-prose-gap, calc(var(--aui-space) * 2))
     description: Vertical gap between prose elements (paragraphs, headings, etc.).
   - name: --aui-agent-text-heading-font-weight
     default: var(--aui-font-weight-bold, 600)
@@ -47,16 +41,16 @@ tokens:
     default: var(--aui-control, var(--aui-fill))
     description: Background of inline code spans.
   - name: --aui-agent-text-code-border-radius
-    default: "calc(var(--aui-radius) * 0.5)"
+    default: calc(var(--aui-radius) * 0.5)
     description: Border radius of inline code spans.
   - name: --aui-agent-text-pre-background
     default: var(--aui-control, var(--aui-fill))
     description: Background of code blocks.
   - name: --aui-agent-text-pre-border-radius
-    default: "calc(var(--aui-radius) * 0.5)"
+    default: calc(var(--aui-radius) * 0.5)
     description: Border radius of code blocks.
   - name: --aui-agent-text-pre-padding
-    default: "calc(var(--aui-space) * 2)"
+    default: calc(var(--aui-space) * 2)
     description: Padding inside code blocks.
   - name: --aui-agent-text-link-color
     default: var(--aui-ink-accent, var(--aui-accent-solid))
@@ -67,9 +61,9 @@ tokens:
   - name: --aui-agent-text-hr-border
     default: var(--aui-border-muted)
     description: Border color of horizontal rules.
-
 examples:
-  - html: |
+  - description: Rich markdown rendering with headings, code fences, bullet lists, blockquotes, bold text, and links
+    html: |-
       <aui-agent-text>## Getting Started
 
       To install the package, run:
@@ -87,13 +81,10 @@ examples:
       > Note: Requires a modern browser with custom element support.
 
       See the [documentation](https://example.com/docs) for the full API reference.</aui-agent-text>
-    description: Rich markdown rendering with headings, code fences, bullet lists, blockquotes, bold text, and links.
-
-  - html: |
-      <aui-agent-text format="plain">The deployment completed successfully. All 47 tests passed and the build artifact was uploaded to s3://releases/v2.1.0/bundle.tar.gz. No breaking changes detected.</aui-agent-text>
-    description: Plain text mode — no markdown processing, rendered as-is.
-
-  - html: |
+  - description: Plain text mode — no markdown processing, rendered as-is
+    html: <aui-agent-text format="plain">The deployment completed successfully. All 47 tests passed and the build artifact was uploaded to s3://releases/v2.1.0/bundle.tar.gz. No breaking changes detected.</aui-agent-text>
+  - description: Streaming content — text cuts off mid-sentence while the response is still being generated. The renderer handles partial markdown gracefully
+    html: |-
       <aui-agent-text>Here are the three main approaches to state management:
 
       1. **Local component state** — simplest, works for isolated UI
@@ -101,4 +92,3 @@ examples:
       3. **External store** — best for complex, cross-cutting state
 
       For your use case, I'd recommend starting with option 2 and migrating to an external store only if you hit performance issues with deeply nested...</aui-agent-text>
-    description: Streaming content — text cuts off mid-sentence while the response is still being generated. The renderer handles partial markdown gracefully.

package/dist/docs/components/agent-thread.yaml

@@ -2,44 +2,38 @@ name: aui-agent-thread
 tag: aui-agent-thread
 type: component
 summary: Message group with 2x2 grid layout for avatar, context, and bubbles.
-description: >
-  Cluster of messages from the same sender. Provides a 2x2 grid layout:
-  col 1 = avatar (bottom-aligned), col 2 row 1 = context area (metadata),
-  col 2 row 2 = bubbles area (message flex column). A MutationObserver
-  routes dynamically added children into the correct wrapper.
-
+description: |
+  Cluster of messages from the same sender. Provides a 2x2 grid layout: col 1 = avatar (bottom-aligned), col 2 row 1 = context area (metadata), col 2 row 2 = bubbles area (message flex column). A MutationObserver routes dynamically added children into the correct wrapper.
 base: AgentElement
-
 attributes:
   role:
     syntax: key-value
     type: string
     default: ""
     description: Message role — user, assistant, or system.
-
   sender:
     syntax: key-value
     type: string
     default: ""
     description: Display name of the sender.
-
   avatar-align:
     syntax: key-value
     type: string
     default: ""
     description: Avatar vertical alignment — top, center, or bottom (default).
-
 a11y:
   role: group
   aria-label: Messages from {sender}
-
 composition:
-  parents: [aui-agent-feed]
-  children: [aui-avatar, aui-agent-message, any]
-
+  parents:
+    - aui-agent-feed
+  children:
+    - aui-avatar
+    - aui-agent-message
+    - any
 tokens:
   - name: --aui-agent-thread-column-gap
-    default: "var(--aui-agent-message-gap, calc(var(--aui-space) * 2))"
+    default: var(--aui-agent-message-gap, calc(var(--aui-space) * 2))
     description: Gap between avatar column and message column.
   - name: --aui-agent-thread-max-width
     default: var(--aui-agent-bubble-max-width, 85%)
@@ -56,26 +50,24 @@ tokens:
   - name: --aui-agent-thread-user-avatar-color
     default: var(--aui-agent-bubble-user-ink)
     description: Text/icon color of the user avatar.
-
 examples:
-  - html: |
+  - description: Assistant thread with avatar and a single message bubble
+    html: |-
       <aui-agent-thread role="assistant" sender="Claude">
         <aui-avatar>C</aui-avatar>
         <aui-agent-message role="assistant">
           <aui-agent-text>I've analyzed your codebase and found three potential performance bottlenecks in the data processing pipeline. Let me walk through each one.</aui-agent-text>
         </aui-agent-message>
       </aui-agent-thread>
-    description: Assistant thread with avatar and a single message bubble.
-
-  - html: |
+  - description: User thread — right-aligned with no avatar
+    html: |-
       <aui-agent-thread role="user" sender="Sarah">
         <aui-agent-message role="user">
           <aui-agent-text format="plain">Can you refactor the authentication module to use JWT instead of session cookies?</aui-agent-text>
         </aui-agent-message>
       </aui-agent-thread>
-    description: User thread — right-aligned with no avatar.
-
-  - html: |
+  - description: Multi-message thread with context metadata (model, latency, token count) and top-aligned avatar
+    html: |-
       <aui-agent-thread role="assistant" sender="Claude" avatar-align="top">
         <aui-avatar>C</aui-avatar>
         <div data-role="context">
@@ -99,4 +91,3 @@ examples:
           <aui-agent-text>I've split the token generation and verification into separate functions for better testability. The refresh token rotation is handled in the middleware layer.</aui-agent-text>
         </aui-agent-message>
       </aui-agent-thread>
-    description: Multi-message thread with context metadata (model, latency, token count) and top-aligned avatar.