Spec — AI chat message bubble

Baseline component consumido por todo produto AI Koder. Hosts streaming text (crosslink [`streamingtext.kmd](streaming-text.kmd)), tool invocations (cross-link [mcptoolinvocation.kmd](mcp-tool-invocation.kmd)), code blocks, citations, e disclaimer (cross-link [aidisclaimer.kmd`](aidisclaimer.kmd)).

Princípios

1. *wo-role taxonomy*— user vs assistant. Sem variantes "system" ou "tool" no bubble visual (tool calls são inline content do assistant bubble, não bubbles próprios).
2. *isclaimer is non-negotiable*— todo assistant bubble carrega disclaimer chip per #119. Sem exceção em produto distribuído.
3. *omposable content*— bubble é container; renderers de textcodeimagecitationtool são plug-ins.
4. *ctions where the user expects them*— toolbar inline (hover desktop / always-visible mobile) com Copy / Edit / Regenerate / Branch.

R1 — Anatomia

R1.1 — User bubble

                          ┌──────────────────────┐
                          │ "What's the weather?"│
                          └──────────────────────┘
                                        14:32 · ✎

• Alignment: right (LTR) / left (RTL per i18n/contract.kmd).
• Tint: primary-container (per themes/color-roles.kmd).
• Shape: shape-corner-large exceto trailingbottom corner (`shapecorner-small`) — tail.
• Avatar: opcional (off by default; product configurável).
• Footer chips: timestamp · edit pencil (R3.2).

R1.2 — Assistant bubble

[avatar] ┌──────────────────────────────────────────┐
         │ "It's 22°C in São Paulo right now."      │
         │                                          │
         │ [mcp-tool-card if any]                   │
         │ [code-block if any]                      │
         │ [citation[1]] inline                     │
         │                                          │
         │ — Sources                                │
         │ [1] weather.com/sp                       │
         └──────────────────────────────────────────┘
         🤖 Generated by AI — verify  ·  14:32 · ⎘ ✎ ↻ ⑂

• Alignment: left (LTR) / right (RTL).
• Tint: surface (per themes/color-roles.kmd).
• Shape: shape-corner-large exceto leading-bottom corner.
• Avatar: assistant icon (configurável: model logo OR product logo OR generic ✨).
• Disclaimer chip: SEMPRE presente (crosslink `aidisclaimer.kmd` per tier).
• Footer chips: timestamp · Copy ⎘ · Edit ✎ · Regenerate ↻ · Branch ⑂.

R2 — Mandatory disclaimer chip

ai-disclaimer.kmd R1 define 3 tiers (label / label+modal / label+banner+confirmation). Bubble hosts o *abel*form:

Chip clickable → expand modal explicativo (#119 R1 tier 2 behavior; tier 1 = chip-only).

Per feedback_kds_owner_curated_content: copy editorial não editável por IA autonomamente.

R3 — Actions

R3.1 — User actions

R3.2 — Assistant actions

Hover surface: actions reveal on desktop hover; mobile: actions always visible (touch).

R4 — States

R5 — Multi-modal content hosting

Bubble body é *ontainer*que renderiza array de content items (mesma estrutura do MCP tools/call content). Renderers:

Render order = array order from gateway response. Streaming: content items appear progressivamente.

R6 — Surface bindings

API consistent: role: "user" | "assistant", content: List<ContentItem>, state: streaming|complete|error, onAction: callback(action_id).

R7 — Acessibilidade

• Bubble é <article role="region" aria-label="Message from {role}">.
• Avatar tem aria-hidden="true" (role já anunciado).
• Disclaimer chip lido por screen reader como part of bubble: aria-describedby.
• Actions: keyboardaccessible via Tab; arialabel per action.
• Streaming state: aria-live="polite" announces "Generating…" → silent during stream → "Done" at end.
• Edited state: aria-label includes "edited".
• Reduced-motion: no entrance animation.
• Touch targets ≥48dp.

R8 — i18n

(Disclaimer copy lives em ai-disclaimer.kmd R7.)

R9 — Multi-tenant + persistência

Message stored per policies/multi-tenant-by-default.kmd:

• Key: (koder_user_id, workspace_id, conversation_id, message_id).
• Edit history mantém versions (linear); rollback via long-press menu.
• Crosstenant lookup 404 per multitenancy contract.
• Delete: cascata per policies/identity-data-retention.kmd R5 (24h grace + cascade).

R10 — Per-preset variation

T-suite

• *1*Mount user: render user bubble com text content; alignment right (LTR).
• *2*Mount assistant: render assistant bubble com text + disclaimer chip visible.
• *3*Multimodal: render assistant com text + codeblock + tool-call + citation; ordem preserved.
• *4*Action Copy: tap copy → clipboard content includes citations as markdown footnotes.
• *5*Action Regenerate: tap → bubble enters streaming state; new content replaces.
• *6*Action Branch: tap → new conversation created with prefix up to this message.
• *7*Action Edit (user): tap → composer pre-filled; submit invalidates downstream cascade.
• *8*Error state: simulate gateway error → red border + Retry button visible.
• *9*RTL: render em locale rtl-* → alignment flips.
• *10*A11y: screen reader announces role + content + disclaimer + actions list.
• *11*Disclaimer always present: render assistant bubble without disclaimer prop → spec validation FAILS (compile-time or runtime error).
• *1*Cross-tenant access: try to load message from another workspace → 404.

Cross-link

• Companion: streaming-text.kmd, ai-disclaimer.kmd, mcp-tool-invocation.kmd, citations.kmd, code-block.kmd
• Policies: multi-tenant-by-default.kmd, identity-data-retention.kmd
• Tokens: themes/color-roles.kmd, themes/typography.kmd, themes/shape.kmd
• i18n: specs/i18n/contract.kmd
• Backend: services/ai/chat-adapter/ (wire protocol)