From c22a550bfcbbfa108fad18ca8982abda722d51d2 Mon Sep 17 00:00:00 2001 From: Lukas May Date: Fri, 6 Mar 2026 19:40:26 +0100 Subject: [PATCH] docs: document Web Worker syntax highlighting architecture in frontend.md Co-Authored-By: Claude Sonnet 4.6 --- docs/frontend.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/frontend.md b/docs/frontend.md index 0797687..ce5982d 100644 --- a/docs/frontend.md +++ b/docs/frontend.md @@ -122,6 +122,17 @@ The initiative detail page has three tabs managed via local state (not URL param | `PreviewPanel` | Docker preview status: building/running/failed with start/stop (legacy, now integrated into ReviewHeader) | | `ProposalCard` | Individual proposal display | +#### Syntax Highlighting (`use-syntax-highlight.ts` + `highlight-worker.ts`) + +`useHighlightedFile(filePath, allLines)` returns `LineTokenMap | null`. Tokenisation runs off the main thread: + +- **Worker path** (default): a module-level pool of 2 ES module Web Workers (`highlight-worker.ts`) each import shiki's `codeToTokens` dynamically. Requests are round-robined by `requestCount % 2`. Responses are correlated by UUID. Late responses after unmount are silently discarded via the `pending` Map. +- **Fallback path** (CSP / browser-compat): if `Worker` construction throws, `createHighlighter` is used on the main thread but processes 200 lines per chunk, yielding between chunks via `scheduler.yield()` or `setTimeout(0)`. + +Callers receive `null` while highlighting is in progress and a populated `Map` once it resolves. `LineWithComments` already renders plain text when `null`, so no caller changes are needed. + +Vite must be configured with `worker.format: 'es'` (added to `vite.config.ts`) for the worker chunk to bundle correctly alongside code-split app chunks. + ### UI Primitives (`src/components/ui/`) shadcn/ui components: badge (6 status variants + xs size), button, card, dialog, dropdown-menu, input, label, select, sonner, textarea, tooltip.