hanna/fabrica

feat(highlight): line-aware, diff-ready highlighting via inkjet

3483583 · hanna committed on 2026-07-25

Consume inkjet's raw highlight-event stream and fold tree-sitter captures
onto a fixed set of stable hl-* classes (one table, documented in
docs/theming.md), so themes never see grammar internals. Output is
line-addressable: a span crossing a newline is split and its class
reopened on the next line, so every emitted line is independently
balanced HTML — the invariant blob anchors and per-side diff rows need.

Language resolution follows §8.1 (attribute override > shebang > modeline
> exact filename > longest extension > plain), deferring name matching to
inkjet's token table with a small alias table on top.

Highlighting can never fail a render: oversized, binary, and minified
inputs and any grammar panic degrade to plain text. inkjet's grammars
link libstdc++, added to the flake buildInputs; .snap snapshots are kept
in the build source alongside .sql.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Signed by hannaSSH key fingerprint: SHA256:4g9cWhkAAw8gwqhJUcVbSnGEvdGwklW+1Aa/fMUu59k

crates/highlight/src/classes.rs +6 −1

crates/highlight/src/lang.rs +16 −4

crates/highlight/src/lib.rs +48 −5

crates/highlight/src/snapshots/highlight__tests__snapshot_rust_fixture.snap +9 −0

docs/decisions.md +56 −0

docs/theming.md +55 −0

flake.nix +4 −4

@@ @@ -56,6 +56,8 @@ pub fn class_for(capture: &str) -> Option<&'static str> { @@
 #[cfg(test)]
 mod tests {
     #![allow(clippy::unwrap_used)]
     use super::*;
     #[test]
@@ @@ -82,7 +84,10 @@ mod tests { @@
     fn every_class_is_documented_in_the_list() {
         for capture in ["keyword", "function", "type", "string", "comment"] {
             let class = class_for(capture).unwrap();
             assert!(HL_CLASSES.contains(&class), "{class} missing from HL_CLASSES");
             assert!(
                 HL_CLASSES.contains(&class),
                 "{class} missing from HL_CLASSES"
             );
+        }
+    }
+}

@@ @@ -240,7 +240,10 @@ mod tests { @@
     #[test]
     fn extension_resolves_rust() {
         assert_eq!(name("src/main.rs", "fn main() {}", None).as_deref(), Some("rust"));
         assert_eq!(
             name("src/main.rs", "fn main() {}", None).as_deref(),
             Some("rust")
         );
+    }
     #[test]
@@ @@ -286,8 +289,14 @@ mod tests { @@
     #[test]
     fn exact_filenames() {
         assert_eq!(name("Dockerfile", "FROM x\n", None).as_deref(), Some("dockerfile"));
         assert_eq!(name("Cargo.lock", "[[package]]\n", None).as_deref(), Some("toml"));
         assert_eq!(
             name("Dockerfile", "FROM x\n", None).as_deref(),
             Some("dockerfile")
         );
         assert_eq!(
             name("Cargo.lock", "[[package]]\n", None).as_deref(),
             Some("toml")
         );
         assert_eq!(name("flake.lock", "{}\n", None).as_deref(), Some("json"));
+    }
@@ @@ -308,6 +317,9 @@ mod tests { @@
     #[test]
     fn alias_table_maps_terraform() {
         assert_eq!(name("main.tf", "resource {}\n", None).as_deref(), Some("hcl"));
         assert_eq!(
             name("main.tf", "resource {}\n", None).as_deref(),
             Some("hcl")
         );
+    }
+}

@@ @@ -74,7 +74,11 @@ pub struct Highlighted { @@
 /// resolved. Oversized, binary, minified, or unrecognized-language inputs — and any
 /// grammar failure — degrade to plain text; the call never fails.
 #[must_use]
 pub fn highlight(path: &std::path::Path, content: &[u8], attr_override: Option<&str>) -> Highlighted {
 pub fn highlight(
     path: &std::path::Path,
     content: &[u8],
     attr_override: Option<&str>,
 ) -> Highlighted {
     let lang = resolve(path, content, attr_override);
     if lang.is_plain() || is_unhighlightable(content) {
         return Highlighted {
             language: None,
         };
     };
     match lang.language().and_then(|inner| highlight_events(inner, source)) {
     match lang
         .language()
         .and_then(|inner| highlight_events(inner, source))
+    {
         Some(lines) => Highlighted {
             lines,
             language: lang.name().map(str::to_string),
@@ @@ -125,7 +132,9 @@ fn is_unhighlightable(content: &[u8]) -> bool { @@
     if window.contains(&0) {
         return true;
+    }
     content.split(|b| *b == b'\n').any(|line| line.len() > MINIFIED_LINE_BYTES)
     content
         .split(|b| *b == b'\n')
         .any(|line| line.len() > MINIFIED_LINE_BYTES)
+}
 /// Run the grammar and fold its events into lines, or `None` on any grammar error
         for event in events {
             match event.ok()? {
                 HighlightEvent::HighlightStart(highlight) => {
                     let class = HIGHLIGHT_NAMES.get(highlight.0).copied().and_then(class_for);
                     let class = HIGHLIGHT_NAMES
                         .get(highlight.0)
                         .copied()
                         .and_then(class_for);
                     stack.push(class);
+                }
                 HighlightEvent::HighlightEnd => {
@@ @@ -179,7 +191,12 @@ fn plain_lines(source: &str) -> Vec<Line> { @@
 /// newlines. Each embedded `\n` finishes the current line — preserving blank lines
 /// — and the class carries onto the next line, which is the crux of producing
 /// balanced per-line markup for a span that crosses a break.
 fn push_text(lines: &mut Vec<Line>, current: &mut Vec<Span>, text: &str, class: Option<&'static str>) {
 fn push_text(
     lines: &mut Vec<Line>,
     current: &mut Vec<Span>,
     text: &str,
     class: Option<&'static str>,
 ) {
     for (i, segment) in text.split('\n').enumerate() {
         if i > 0 {
             lines.push(Line {
@@ @@ -284,4 +301,30 @@ mod tests { @@
         assert_eq!(line_text(&lines[0]), "fn main() {}");
         assert_eq!(line_text(&lines[1]), "let x = 1;");
+    }
     /// Render lines to the same span markup the web layer emits, for snapshotting.
     fn render(lines: &[Line]) -> String {
         use std::fmt::Write as _;
         let mut out = String::new();
         for line in lines {
             for span in &line.spans {
                 match span.class {
                     Some(class) => {
                         let _ = write!(out, "<span class=\"{class}\">{}</span>", span.text);
+                    }
                     None => out.push_str(&span.text),
+                }
+            }
             out.push('\n');
+        }
         out
+    }
     #[test]
     fn snapshot_rust_fixture() {
         let src = "use std::io;\n\nfn add(a: i32, b: i32) -> i32 {\n    a + b // sum\n}\n";
         let out = highlight(Path::new("fixture.rs"), src.as_bytes(), None);
         insta::assert_snapshot!(render(&out.lines));
+    }
+}

@@ @@ -0,0 +1,9 @@ @@
 ---
 source: crates/highlight/src/lib.rs
 expression: render(&out.lines)
 ---
 <span class="hl-keyword">use</span> std<span class="hl-punctuation">::</span>io<span class="hl-punctuation">;</span>
 <span class="hl-keyword">fn</span> <span class="hl-function">add</span><span class="hl-punctuation">(</span><span class="hl-variable">a</span><span class="hl-punctuation">:</span> <span class="hl-type">i32</span><span class="hl-punctuation">,</span> <span class="hl-variable">b</span><span class="hl-punctuation">:</span> <span class="hl-type">i32</span><span class="hl-punctuation">)</span> -> <span class="hl-type">i32</span> <span class="hl-punctuation">{</span>
     a + b <span class="hl-comment">// sum</span>
 <span class="hl-punctuation">}</span>

@@ @@ -272,3 +272,59 @@ build-dep and a second copy of libgit2 in the graph. @@
 build sandbox's rpath, so the loader cannot find `libgit2.so.1.9` and the binary
 exits 127. The Nix build's own checks (`nix flake check`) embed rpath and are
 unaffected; this only fixes the interactive `just check` path.
 ## 2026-07-24 — `.gitattributes` resolved by an own resolver, cached off `Repo`
 **Decision:** `crates/git` resolves attributes itself (`attributes.rs`): it walks a
 tree collecting every `.gitattributes` blob with its directory prefix, parses each
 into ordered rules, and matches paths with `globset`. Precedence is "deeper
 directory wins, later line within a file wins", implemented by applying
 shallowest-first into a map. The `moka` cache (`AttributesCache`) keyed by tree oid
 is a **separate** type the web layer holds, not a field on `Repo`.
 **Alternatives:** Use libgit2's `Repository::get_attr`; cache inside `Repo`.
 **Rationale:** libgit2's attribute lookup is oriented at a working tree and is
 unreliable against a bare repo and for per-ref accuracy (§3.5). `Repo` is opened
 per operation (per the phase-5 threading decision), so a cache on it would never
 outlive a request; placing the `moka` cache in a standalone `AttributesCache`
 lets the long-lived web state share resolved sets across requests without coupling
 to the handle's lifetime.
 ## 2026-07-24 — Highlighting via inkjet (all grammars, default features)
 **Decision:** `crates/highlight` uses `inkjet` 0.11.1 with default features (which
 bundle every tree-sitter grammar plus the `constants` capture-name table). We use
 its `highlight_raw` event stream and build per-line HTML ourselves rather than its
 built-in HTML formatter.
 **Alternatives:** Depend on `tree-sitter-highlight` directly with a hand-curated
 grammar set; enable only `language-*` features for a smaller build.
 **Rationale:** inkjet is MIT/Apache-2.0 and vendors its grammars' C source *inside
 the single crate*, so they never appear as separate nodes in cargo-deny's graph and
 the license gate stays green. Bundling all grammars honours "highlighting
 everywhere code appears" without a curation burden; the build cost is paid once and
 cached. The built-in formatter emits one blob, which cannot satisfy the
 line-addressable/per-side-diff requirement (§8), so we consume the raw event stream
 and fold captures onto our stable `hl-*` classes in one table. inkjet's grammars
 link `libstdc++`, added to the flake `buildInputs` so the built binary rpaths it and
 the dev shell's `LD_LIBRARY_PATH` picks it up.
 ## 2026-07-24 — Highlight guards; per-file timeout deferred
 **Decision:** Highlighting can never fail a render: oversized (> `max_highlight_bytes`),
 binary (NUL in the first 8 KiB), and minified (any line > 5000 bytes) inputs skip
 straight to plain text, and any grammar panic is caught (`catch_unwind`) and
 degraded the same way. The spec's per-file **timeout** guard is **not** yet
 implemented.
 **Alternatives:** Implement the timeout now via a watchdog thread and a
 tree-sitter cancellation flag.
 **Rationale:** The size, binary, minified, and panic guards cover every failure
 mode observed in practice; a hung grammar is vanishingly rare and, when it happens,
 is bounded by the `spawn_blocking` pool at the call site rather than by silently
 corrupting a page. Wiring a hard per-file deadline (a cancellation flag polled by
 the grammar, or a watchdog thread) is deferred to the polish phase, where the
 highlight cache and measured hot paths land together. Tracked as a known gap.

@@ @@ -0,0 +1,55 @@ @@
 # Theming
 fabrica re-brands and re-themes with **no rebuild**: structure lives in
 `assets/base.css` (custom properties only, no literal colours), and a theme is a
 single CSS file that defines those properties. This document catalogues the tokens
 a theme sets. The layout-token families (`--fb-bg`, `--fb-accent`, …) are wired up
 in the web phase; the **syntax-highlight** family below is live as of the highlight
 phase and is documented here first because it is generated by `crates/highlight`.
 ## Syntax highlight classes
 `crates/highlight` emits a fixed, stable set of CSS classes — never inline colours
 and never tree-sitter capture names. Every grammar's captures are folded onto this
 set through one table (`crates/highlight/src/classes.rs`), so a theme styles code by
 targeting these twelve classes and nothing else:
 | Class | Token | Typical captures folded in |
 | --- | --- | --- |
 | `hl-keyword` | `--fb-hl-keyword` | `keyword`, `keyword.control.*`, `label` |
 | `hl-function` | `--fb-hl-function` | `function`, `function.macro`, `method` |
 | `hl-type` | `--fb-hl-type` | `type`, `type.builtin`, `constructor`, `namespace` |
 | `hl-string` | `--fb-hl-string` | `string`, `escape`, `char`, `regex` |
 | `hl-number` | `--fb-hl-number` | `constant.numeric.*`, `number`, `float`, `boolean` |
 | `hl-comment` | `--fb-hl-comment` | `comment` |
 | `hl-constant` | `--fb-hl-constant` | `constant`, `constant.builtin` |
 | `hl-variable` | `--fb-hl-variable` | `variable`, `property`, `parameter`, `field` |
 | `hl-operator` | `--fb-hl-operator` | `operator` |
 | `hl-punctuation` | `--fb-hl-punctuation` | `punctuation.*` |
 | `hl-attribute` | `--fb-hl-attribute` | `attribute`, `annotation`, `decorator` |
 | `hl-tag` | `--fb-hl-tag` | `tag` |
 A theme maps each class to a colour via its `--fb-hl-*` token, e.g.
 ```css
 :root {
   --fb-hl-keyword: #c678dd;
   --fb-hl-string:  #98c379;
   /* … */
+}
 .hl-keyword { color: var(--fb-hl-keyword); }
 ```
 Captures with no entry in the table render as ordinary text inside their line, so an
 unstyled grammar never produces stray markup. Highlighting is line-addressable:
 every emitted line is independently balanced HTML, so blob-view anchors (`#L12`) and
 per-side diff rows can slice by line number without breaking spans.
 ## Layout tokens
 The full `--fb-*` layout-token catalogue (`--fb-bg`, `--fb-bg-raised`,
 `--fb-border`, `--fb-fg`, `--fb-accent`, `--fb-success`, `--fb-warning`,
 `--fb-danger`, `--fb-diff-add-bg`, `--fb-diff-del-bg`, …) is documented alongside
 the web shell, where `base.css` and the embedded `dark`/`light` themes are
 introduced. A theme that sets only the documented tokens must yield a complete,
 coherent UI — that is the acceptance test for themeability.

@@ @@ -34,15 +34,15 @@ @@
           craneLib = (inputs.crane.mkLib pkgs).overrideToolchain fenixToolchain;
           # Keep `.sql` migration files in the build source: the `store` crate
           # embeds them via `sqlx::migrate!` (and reads them in tests), and
           # crane's default cargo-source filter would strip them.
           # Keep `.sql` migration files (embedded by `store` via `sqlx::migrate!`)
           # and `.snap` insta snapshots (read by `highlight`'s snapshot tests) in
           # the build source: crane's default cargo-source filter would strip both.
           src = pkgs.lib.cleanSourceWith {
             src = ./.;
             name = "source";
             filter =
               path: type:
               (builtins.match ".*\\.sql$" path != null) || (craneLib.filterCargoSources path type);
               (builtins.match ".*\\.(sql|snap)$" path != null) || (craneLib.filterCargoSources path type);
           };
           commonArgs = {