docs/plans/2026-10-05-highlighting.md

 1# Src Block Highlighting Implementation Plan
 2
 3> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 4
 5**Goal:** Code in src blocks is highlighted with tree-sitter grammars and their own highlight queries: shells, Python, Emacs Lisp, C, C++, R, JavaScript, Java, Scheme, Clojure, Haskell, Rust, Go, Ruby, JSON, YAML, Lua.
 6
 7**Architecture:** `OrgPresentation` defines `SyntaxCategory`, a `.syntax` style role and the `CodeHighlighter` protocol; `Presentation.styles` asks a highlighter for runs inside `#+begin_src LANG` blocks. `OrgHighlight` implements it with swift-tree-sitter 0.25: org language names map to grammars, each grammar and query compiles once, results are cached by code. Queries are embedded as Swift strings (`scripts/update-highlight-queries.sh`), so nothing ships as a resource bundle. The editor takes a highlighter at creation; the theme colors categories.
 8
 9**Tech Stack:** Swift 6.2 tools, swift-tree-sitter 0.25, tree-sitter grammars pinned in `Package.swift`.
10
11**Spec:** `docs/design.md`, "Babel and table formulas" (highlighting), "Phase 1 scope" (src block highlighting).
12
13## Notes
14
15- Emacs Lisp (no Swift package) and Clojure (no package at its tags) are vendored as C targets.
16- The JavaScript, Lua, Python and YAML packages include `scanner.c` only when `fileExists("src/scanner.c")` holds in SwiftPM's working directory, which it doesn't; their scanners are compiled in `TreeSitterScanners`.
17- Third-party licenses: `THIRD_PARTY.md`.
18
19## Not highlighted (user may decide)
20
21- SQL: its grammar ships parser.c (41 MB) only on a gh-pages branch.
22- LaTeX and Common Lisp (no highlight queries), dot, PlantUML, Mermaid (no usable grammars).
23
24---
25
26### Task 1: Highlighting
27
28- [ ] Hook, highlighter, vendored grammars and scanners, embedded queries, theme colors; tests for categories in Python, shell and Emacs Lisp and for runs in a src block; app snapshot.
29- [ ] Commit "Highlight src blocks with tree-sitter".