Status: Schváleno PM 2026-05-04

Spec definuje technologický stack pro renderování a editaci kódu a markdownu v TalkIDE FE. Zahrnuje volbu editoru pro file viewer a editor, renderer pro chat zprávy a .md soubory, zvýrazňování syntaxe uvnitř markdownu a strategii pro mermaid diagramy. Stávající pasivní file viewer (raw text) je výchozím bodem; tato spec ho nahrazuje a zarámovává do IDE roadmap.

1. Kontext a motivace

TalkIDE dnes zobrazuje otevřené soubory jako raw text — žádné zvýrazňování syntaxe, žádná editace, žádný diff. Tato pasivní vrstva nestačí pro IDE ambice produktu.

PM rozhodl, že file viewer není izolovaný feature — je to první krok IDE roadmap. Volba editoru se proto dělá teď, ne až při implementaci editace. Viewer = read-only mode toho samého enginu. Každý další krok (editace, diff, LSP) staví na stejné základně.

Plánované IDE features (timeline)

Zároveň TalkIDE potřebuje renderovat markdown — chat zprávy od Mary i ostatních agentů, a také .md soubory v exploreru — včetně mermaid diagramů a code bloků se syntaxí.

Obě potřeby (kód + markdown) jsou adresovány touto spec jako celek, protože sdílejí infrastrukturu (lazy loading, bundle strategy, design tokens).

2. Rozhodnutí

2.1 Code engine: Monaco Editor

Zvoleno: Monaco Editor (engine VS Code, Microsoft).

Monaco pokrývá celý IDE stack jedinou knihovnou — read-only viewer, edit mode i diff editor jsou součástí stejného API. Tím se eliminuje budoucí migrační náklad.

Důvody:

1. Full IDE feel bez práce — intellisense, suggestions, multi-cursor, find/replace, hover info jsou dostupné out-of-box. Uživatelé i AI agenti znají VS Code UX.
2. Diff editor built-in — monaco.editor.createDiffEditor() je first-class API, kritické pro AI change review (přijmout / odmítnout změny). Alternativy tento use case neřeší bez custom práce.
3. LSP ekosystém — monaco-languageclient je etablovaná cesta k napojení TypeScript nebo Kotlin language serveru přes WebSocket. Nevyžaduje výměnu enginu při přechodu na LSP.
4. Šíře jazykové podpory — ~50 jazyků out-of-box, TextMate grammars pro zbytek.
5. Aktivní údržba — Microsoft, velká komunita, pravidelné releasy.

Trade-offs:

• Velikost: ~2.5 MB initial bundle. Řešíme lazy importem — Monaco se loaduje jen při akci “Open file”, nikdy při inicializaci aplikace.
• Setup overhead: vyžaduje vite-plugin-monaco-editor a Web Workers. Nutné ověřit kompatibilitu s CSP (worker-src 'self' blob:) — viz Otevřené otázky §6.
• API komplexnost: Monaco API je obsáhlé. Benefit outweighuje náklad — alternativy by tento náklad nahradily custom implementací chybějících features.

2.2 Markdown renderer: markdown-it

Zvoleno: markdown-it.

TalkIDE renderuje markdown na dvou místech: chat zprávy od agentů a .md soubory v exploreru. Oba případy pravděpodobně sdílejí jednu Vue komponentu.

Důvody:

• Modulární architektura — každá feature (mermaid, task-list, footnote, anchor) je plugin.
• Nejaktivnější ekosystém markdown knihoven v JS ekosystému.
• Dobře zdokumentované API, stabilní.
• Přímočará integrace s shiki (syntax highlight) přes vlastní fence renderer.

2.3 Mermaid diagramy: mermaid (lazy)

Zvoleno: mermaid (oficiální knihovna), načítaná lazy on-demand.

Mermaid je velká knihovna (~500 KB). Načítá se pouze tehdy, když markdown-it parser narazí na ```mermaid blok — runtime dynamic import. Pokud žádný mermaid blok v obsahu není, knihovna se nestáhne vůbec.

2.4 Syntax highlight uvnitř markdownu: shiki

Zvoleno: shiki pro zvýrazňování code bloků uvnitř markdown obsahu.

Monaco (zvolený pro file viewer a editor) je nevhodný pro inline code bloky v chatu — každý blok by vyžadoval vlastní Monaco instanci s plným overhead. Shiki je lightweight alternativa určená přesně pro tento use case.

Důvody:

• Používá VS Code TextMate grammars — vizuálně konzistentní s Monaco editorerm.
• Async API s per-language lazy loadem jazykových balíčků.
• Výrazně menší footprint než Monaco instance per code block.

Pro file viewer a editor souborů (.ts, .kt, .vue, …) se používá Monaco v read-only modu — shiki tam nevstupuje.

3. Alternativy a důvody zamítnutí

Code engine

Markdown renderer

Syntax highlight v markdownu

4. Architektonická matice

5. Roadmap

Fáze 1 a 2 jsou na sobě nezávislé a lze je vyvíjet paralelně. Fáze 3–5 jsou sekvenční.

6. Bundle considerations

Cíl: uživatel, který neotevřel žádný soubor a jen chatuje s Marou, nestáhne Monaco.

Initial bundle chat + markdown view: ~70 KB. Monaco a mermaid zatěžují jen uživatele, kteří danou feature aktivně používají.

7. Otevřené otázky

1. Sdílená markdown komponenta — Markdown v chatu a .md file viewer pravděpodobně sdílejí jednu Vue komponentu. Ověřit při fázi 1 zda jsou use casy dostatečně identické, nebo zda potřebují separátní konfiguraci markdown-it pluginů (např. task-list jen pro .md soubory).

2. Theme strategie — Monaco i shiki podporují vlastní themes. Začít s jedním tématem (vs-dark / dark varianta konzistentní s warm charcoal design systemem) a přidat light variantu později, nebo respektovat OS prefers-color-scheme od začátku?

3. CSP a Web Workers — Monaco vyžaduje worker-src 'self' blob: v Content Security Policy. Frontend dev ověří, zda TalkIDE CSP toto povoluje, při implementaci fáze 2.

4. shiki vs highlight.js — Pokud shiki bundle nebo integrace s markdown-it způsobí problémy, fallback je markdown-it-highlightjs + highlight.js (~30 KB). Rozhodnutí při fázi 1 po prvním prototypu.

FEEDBACK

(Tato sekce není součástí dokumentu — je určená PM jako zpětná vazba k zadání.)

Co bylo jasné a pomohlo: Kompletní architektonická matice a roadmap v zadání šly přímo do dokumentu bez dohledávání. Důvody zamítnutí alternativ byly formulované přesně — stačilo je přeformulovat, ne rekonstruovat. To byl největší přínos zadání oproti typickému “zvol editor”.

Co mi chybělo nebo bylo nejasné:

• Verze knihoven — zadání explicitně říká “zmiň verze pokud je zmíním”, ale žádné nezmiňuje. Dokument proto verze neobsahuje. Pokud PM chce konkrétní verze (monaco-editor@0.52.x, markdown-it@14.x, shiki@1.x), doplní se snadno — jen potvrzení, která verze je cílová.

• Vztah k současnému file vieweru — není jasné, jestli pasivní raw text viewer žije jako samostatná Vue komponenta nebo je inline v panelu. Pro fázi 2 (Monaco read-only) bude potřeba vědět, co přesně nahrazujeme a jestli je migrační krok “přepsat komponentu” nebo “přepnout implementaci za interface”. Design spec to záměrně neřeší (není to architektura implementace), ale frontend dev to bude potřebovat.

• .md file viewer vs. Monaco — PM zadání říká “file viewer pro .md soubory používá markdown-it (pasivní render)”. To je v architektonické matici zachyceno. Ale editor .md souborů (fáze 3) — bude Monaco edit mode pro .md soubory, nebo markdown-it preview + raw Monaco edit? To je edge case, který spec neřeší a měl by být upřesněn před fází 3.