# Förbättringsförslag — rendering & editor

Genomgång av renderings- och editorlagret (`frontend/src/bridge/*`,
`components/editor/*`) med konkreta, prioriterade förslag. En bekräftad bugg är
redan åtgärdad i denna gren (se punkt 0).

---

## 0. ÅTGÄRDAD bugg: inline-formatering tappades vid sparning

I `asciidoc-bridge.ts → renderTextNodes` byggdes den markerade strängen
(`*fet*`, `_kursiv_`, `` `kod` ``, länkar) men **lades aldrig till utdata** — i
stället lades den *omarkerade* texten till i ett andra `if`-block. Följd: all
inline-formatering försvann tyst varje gång ett dokument sparades från den
visuella editorn. Nu appliceras och skrivs marks korrekt (en enda gång).

> Rekommendation: lägg ett litet round-trip-test (`adoc → toTipTap → fromTipTap`)
> som CI-steg så att den här klassen av regressioner fångas automatiskt.

---

## 1. Round-trip-modellen är den största risken

Idag är flödet vid varje sparning:

```
.adoc  ──asciidoctor.convert──▶  HTML  ──generateJSON──▶  TipTap-JSON
   ▲                                                          │
   └───────────  fromTipTap (handskriven)  ◀──────────────────┘
```

Två lossy konverteringar i rad. Allt som TipTap-schemat inte känner till
(attribut, `ifdef`/`ifeval`, `:attribut:`-definitioner, block-roller, kommentarer,
tabellformat, korsreferenser) går förlorat så fort man öppnar och sparar i den
visuella vyn.

**Förslag (välj en):**
- **A. Källan är sanningen.** Behandla `.adoc` som master. Visuella editorn får
  bara redigera dokument som är "rena" (kan round-trippa förlustfritt), annars
  öppnas källeditorn. Visa en varning "det här dokumentet innehåller avancerad
  AsciiDoc — redigera i källvyn".
- **B. Patch-baserad sparning.** Spara bara de block som faktiskt ändrats i den
  visuella vyn i stället för att reserialisera hela dokumentet.
- **C. Byt serialisering.** Använd en riktig AST (t.ex. `downdoc`/`@asciidoctor`
  reducer) i stället för den handskrivna `TipTapToAsciidoc`-klassen.

Minst arbete/störst nytta på kort sikt: **A** + en tydlig indikator i UI.

---

## 2. Konkreta serialiseringsluckor i `fromTipTap`

| Nod / mark | Problem | Förslag |
|------------|---------|---------|
| Kombinerade marks (fet+kursiv) | Ger `*_text_*` — bräckligt intill andra tecken | Använd oконstruerad syntax (`**`, `__`) vid behov |
| Tabeller (`convertTable`) | Ingen header-rad (`[%header]`), inga kolumn-specar, colspan/align tappas | Detektera `tableHeader`, skriv `[options="header"]`, `cols=` |
| Listor (`convertListItem`) | Blandning av stycke + nästlad lista i samma item blir fel; principallista använder nivå-räkning som spretar | Rendera item-innehåll block för block med `+`-continuation för flerstycke |
| `blockquote` | Attribution/citat-källa tappas | Stöd `[quote, author, source]` |
| `admonition` | Bara 5 typer, alltid versalt block-format | Bevara ursprunglig form (inline `NOTE:` vs `[NOTE]`-block) |
| Bild | `role`/alignment/`link=` tappas | Utöka `AsciidocImage`-attribut och serialisering |

---

## 3. Renderingspipelinen (adoc → HTML)

- **Regex-omskrivning av admonitions** (`htmlContent.replace(/<div class="admonitionblock…`)
  är känslig för nästlat innehåll och flera stycken. En admonition med en lista
  eller ett kodblock inuti går sönder. → Rendera i stället admonitions via en
  Asciidoctor-**converter/extension** i stället för att patcha HTML i efterhand.
- **`include::`** hanteras med regex och blir en platshållare. Riktiga includes
  (t.ex. återanvändbara fragment) renderas aldrig. → Implementera en
  include-resolver på backend (den har redan fil-I/O) och rendera server-side,
  eller hämta fragmentet via API innan `convert`.
- **Passthrough (`+++`)**: fotnötter injiceras som rå-HTML före parsing. Fungerar,
  men kringgår sanering. Låg risk internt, men värt en `DOMPurify` på
  renderad HTML om publika/gäst-användare någonsin ska se opålitligt innehåll.

---

## 4. Prestanda / bundle

`DocumentView`-chunken är **~2,8 MB** (880 kB gzip). Två tunga poster:

- **`lowlight` med `all`** (`createLowlight(all)`) drar in *alla* språkgrammatiker.
  → Byt till `common` eller registrera bara de språk ni faktiskt använder
  (go, js, ts, bash, python, yaml…). Sparar hundratals kB.
- **`asciidoctor.js`** är stort och laddas i varje dokumentvy. → Lazy-load
  (`import()` först när ett dokument öppnas) — delvis redan gjort via
  route-splitting, men Asciidoctor kan brytas ut ytterligare. Överväg
  server-side-rendering av HTML (backend har redan Go; ett litet
  `asciidoctor`-anrop eller cache av renderad HTML per commit-hash skulle ta bort
  klientkostnaden helt och göra läsvyn snabb även på Pi5/mobil).

---

## 5. Editor-UX (presentation)

- **Synk mellan Visual och Source.** Gör "source of truth"-valet (punkt 1)
  synligt: en toggle med en varningsikon när dokumentet inte kan round-trippa.
- **Live-förhandsvisning i källeditorn.** CodeMirror till vänster, renderad HTML
  till höger (delad vy) — vanligt och uppskattat för teknisk dokumentation.
- **Innehållsförteckning / rubriknavigering.** Generera en TOC från rubrikerna
  (finns redan `id` på `CustomHeading`) och visa i sidopanelen.
- **Bildhantering.** Uppladdning finns; lägg till drag-and-drop och inklistring
  från urklipp direkt i editorn.
- **Autospar / utkast.** Spara utkast lokalt (IndexedDB) så inget tappas vid
  session-timeout (sessioner ligger bara i minnet på servern).
- **Diff-vy i redigering.** `HistoryPanel`/`DiffViewer` finns — koppla en
  "jämför med sparad version"-knapp direkt i editorn.

---

## Prioriteringsordning (rekommenderad)

1. ✅ Fixa marks-buggen (klar).
2. Lägg round-trip-test i CI.
3. Byt `lowlight` `all` → `common`/whitelist (snabb, stor bundle-vinst).
4. Inför "source of truth"-indikator + öppna källvyn för avancerade dokument.
5. Server-side- eller cachead HTML-rendering (störst läs-prestandavinst).
6. Robustare tabell-/list-serialisering.