Commit db643a1f22
Verified · cmc
Layout: unified · split
docs/plans/2026-10-05-highlighting.md added +29
| @@ -0,0 +1,29 @@ | |||
| 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". | ||