Spec — AI chat message bubble

Baseline component consumido por todo produto AI Koder. Hosts streaming text (cross-link streaming-text.kmd), tool invocations (cross-link mcp-tool-invocation.kmd), code blocks, citations, e disclaimer (cross-link ai-disclaimer.kmd).

Princípios

1. Two-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. Disclaimer is non-negotiable — todo assistant bubble carrega disclaimer chip per #119. Sem exceção em produto distribuído.
3. Composable content — bubble é container; renderers de text/code/image/citation/tool são plug-ins.
4. Actions 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 trailing-bottom corner (shape-corner-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 (cross-link ai-disclaimer.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 label 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 é container 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: keyboard-accessible via Tab; aria-label 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.
• Cross-tenant lookup 404 per multi-tenancy contract.
• Delete: cascata per policies/identity-data-retention.kmd R5 (24h grace + cascade).

R10 — Per-preset variation

T-suite

• T1 Mount user: render user bubble com text content; alignment right (LTR).
• T2 Mount assistant: render assistant bubble com text + disclaimer chip visible.
• T3 Multi-modal: render assistant com text + code-block + tool-call + citation; ordem preserved.
• T4 Action Copy: tap copy → clipboard content includes citations as markdown footnotes.
• T5 Action Regenerate: tap → bubble enters streaming state; new content replaces.
• T6 Action Branch: tap → new conversation created with prefix up to this message.
• T7 Action Edit (user): tap → composer pre-filled; submit invalidates downstream cascade.
• T8 Error state: simulate gateway error → red border + Retry button visible.
• T9 RTL: render em locale rtl-* → alignment flips.
• T10 A11y: screen reader announces role + content + disclaimer + actions list.
• T11 Disclaimer always present: render assistant bubble without disclaimer prop → spec validation FAILS (compile-time or runtime error).
• N1 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)