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". | |