Spec — AI code block

Sintaxe tokens consumidos do themes/color-schemes.kmd "Vocabulário syntax". Deferuntilfence durante streaming via streaming-text.kmd R4. Hospedado por chat-message-bubble.kmd R5 (content type code) e artifact-panel.kmd (#110).

Princípios

1. *efer until closed*— code blocks NOT highlighted during stream until closing fence (cross-link #106 R4).
2. *opy always full*— copy button gives unsanitized source; never truncated.
3. *un is opt-in per host*— Run button only when host has executor (Kortex liga; Talk não).
4. *iff when modifying*— AI editing existing file → sidebyside OR unified diff.
5. *ecurity boundary*— Run never eval()s; uses sandboxed executor (Koda runtime, WebAssembly, or external worker).

R1 — Anatomia

┌──────────────────────────────────────────┐
│ python · 12 lines              [⎘ ▶ ⇕]   │  ← header
├──────────────────────────────────────────┤
│  1  def fibonacci(n):                    │
│  2      if n <= 1:                       │
│  3          return n                     │
│  4      return fibonacci(n-1) + fibonacci(n-2)
│  5                                       │
│  6  print(fibonacci(10))                 │
└──────────────────────────────────────────┘

Slots:

Mono font: JetBrains Mono per themes/typography.kmd R1.

R2 — Language detection

Order of resolution:

1. Markdown fence info string: python → python`.
2. Filename hint (if AI provides via custom block attribute): .dart → dart.
3. Heuristic: first-line shebang (#!/usr/bin/env python).
4. Token-based detection (per surface library: flutter_highlight, prismjs, etc.).
5. Fallback: plaintext.

Detected language displayed in header.

R3 — Syntax highlighting

Tokens consumed from themes/color-schemes.kmd:

Perpreset color mapping via `themes/colorschemes.kmd` (não duplicar aqui).

Highlighting engine: per surface (Flutter flutter_highlight-compatible; Web prismjs-compatible; CLI uses chroma or equivalent). Surfaces MUST honor token vocabulary acima; engine choice é impl detail.

R4 — Copy button

Behavior:

• Tap copy → write *ull unmodified source*to clipboard.
• Visual feedback: toast "Copied to clipboard" (i18n) per 1.5s.
• Anti-pattern: Copy NEVER truncated. Even when display truncates per

  R7, clipboard has full.

R5 — Run button (opt-in per host)

Visible only when host declares executor capability:

KoderAICodeBlock(
  code: ...,
  language: "python",
  executor: KoderKodaSandbox(),  // or null = no Run button
)

Behavior:

• Tap Run → execute via passed executor.
• Spinner during execution.
• Output appended below code block in collapsible "Output" section.
• Errors displayed inline with error styling.

*ecurity* executor MUST be sandbox-isolated. Options:

NEVER use raw eval() / Function() / exec(). NEVER trust AI-generated code to be safe (cross-link policies/security.kmd).

R6 — Diff view

When AI edits existing file, response includes diff metadata:

{
  "content": [{
    "type": "code",
    "code": "def fibonacci(n):\n  ...",
    "language": "python",
    "diff": {
      "mode": "edit",
      "original_path": "lib/math.py",
      "original_content": "def fib(n):\n  ...",
      "edits": [...]
    }
  }]
}

Diff toggle button switches body between:

• *ode view* just new code (default for new files).
• *idebyside diff* original | new (default for edits).
• *nified diff* standard +/- markers.

Diff lib per surface: flutter_diff_view, diff2html, etc.

R7 — Truncation (display only)

Long code blocks (>50 lines): collapse with "Show more" after 50 lines. Copy + Run always operate on FULL source (R4).

R8 — Surface bindings

R9 — Acessibilidade

• Code container: role="region" aria-label="Code block, {language}, {N} lines".
• Line numbers: aria-hidden="true" (não anunciar).
• Syntax color: MUST atender AAA contrast (crosslink `themes/colorroles.kmd` R4).
• Copy button: aria-label="Copy code to clipboard".
• Run button: aria-label="Run code".
• Keyboard: Tab through code → block focuses → Tab again → actions.
• Screen reader: announces language + line count; code can be read line by line.

R10 — i18n

R11 — Per-preset variation

T-suite

• *1*Render code: code + language → syntax highlighted body + header showing language + line count.
• *2*Language detection: code without fence info but with #!/python → detected as python.
• *3*Copy full: tap copy → clipboard equals full source even when display truncated > 50 lines.
• *4*Copy toast: tap copy → "Copied" toast appears.
• *5*Run available: pass executor → Run button visible; tap → executor invoked.
• *6*Run unavailable: no executor → no Run button.
• *7*Diff view edit: receive diff metadata with mode="edit" → diff toggle visible; tap → sidebyside rendered.
• *8*Defer during stream (crosslink #106 T6): code block fenced opens midstream → placeholder "(writing code…)"; on close → syntax highlight done ONCE.
• *9*Truncation: 100-line code → 50 lines visible + "Show more"; copy still has 100 lines.
• *10*Security: Run with malicious code (e.g., os.system('rm -rf /')) → sandbox prevents file system access; capability error surfaces.
• *11*A11y: screen reader announces "Code block, python, 12 lines"; copy button has aria-label.
• *1*Run without executor: spec validation prevents calling onRun when executor=null.
• *2*Syntax engine fallback: unsupported language → renders as plaintext (no crash).

Cross-link

• Companion: chat-message-bubble.kmd (host), streaming-text.kmd R4 (defer), artifact-panel.kmd (alternate host for large code), agent-step-trace.kmd (step body may include code)
• Syntax tokens: themes/color-schemes.kmd
• Typography: themes/typography.kmd R8 (code typography)
• Color contrast: themes/color-roles.kmd R4 AAA
• Security: policies/security.kmd (executor sandbox)
• Executor: services/ai/sandbox/, engines/lang/koda/runtime/ (Koda VM)
• Refs: Claude Artifacts, ChatGPT code blocks, GitHub Copilot diff