# Handover — `highlight` (syntax highlighting in the blob view)

Branch `feat/highlighting`. One commit of code, plus this file.

## What shipped

`/{handle}/repos/{name}/tree/{rev}/-/{path}` renders a text file with syntax
highlighting. Nothing else changed: no new route, no new `GitQuery` method, **no extra
`git` subprocess** — the bytes were already being read for the plain-text view.

- `src/infrastructure/highlight.rs` — the whole adapter. `source_lines(file_name, text)`
  returns `Source { lines: Vec<SourceLine>, too_large: bool }`, one entry per line of
  `text.lines()`, each either `Plain(String)` or `Classed(String)` of HTML.
- `src/infrastructure/web/browse.rs` — only the `source` component: it takes a
  `file_name` as well as the text, and the code cell renders `Classed` through
  `Unescaped`. The row, the line-number cell and the scroll container are untouched, so
  the blob-header toggle and the `id="L<n>"` anchors being added by sibling agents do
  not collide with this.
- `styles.css` — a `--syntax-*` family on `:root` and `.dark`, and the mapping onto the
  `hl-` classes at the bottom of the file.
- `syntect 5.3` with `default-features = false, features = ["default-fancy"]`: the pure
  Rust regex engine, so the Debian release build gains no C dependency.

## progress.md material — decisions worth not rediscovering

- **Classes, not inline styles.** `syntect` will happily emit `style="color:#..."`.
  That would hardcode one palette into generated markup and follow neither a palette
  change nor the colour scheme, which is the one rule `styles.css` states outright. So
  the output is `ClassStyle::SpacedPrefixed { prefix: "hl-" }` and the colours live in
  `styles.css` with every other token.
- **`ClassedHTMLGenerator` cannot be used here.** It produces a single string whose
  `<span>`s cross line boundaries — its own docs say the output must go in one `<pre>` —
  and the blob view is a table with one row per line, so those spans cannot be split
  across cells. `highlight.rs` therefore drives `ParseState` + `ScopeStack` +
  `line_tokens_to_classed_spans` itself: the parse state carries across lines (a block
  comment opens on one and closes on another) but the *markup* does not — whatever is
  open at the end of a line is closed there and reopened at the start of the next. That
  is the whole reason the module is 150 lines rather than 20.
- **The line ending is stripped by character, not trimmed.** The `_newlines` syntaxes
  need the `\n` handed to the parser, but it comes back *escaped inside the output* and
  can land before or after a closing `</span>` depending on where a scope pops. Left in,
  `white-space: pre` renders a second, empty line inside every row and the whole file
  reads double-spaced. It is dropped with a `filter`, not a `trim_end`.
- **`hl-` classes are scope *atoms*, and atoms are not positional.** `keyword.control`
  becomes `class="hl-keyword hl-control"`, and `meta.function` — which wraps a whole
  function *body* — becomes `class="hl-meta hl-function"`. A bare `.hl-function` rule
  would therefore colour every function body. Single-atom selectors are only safe for an
  atom that leads its scope; the rest are spelled as compounds
  (`.hl-entity.hl-name.hl-function`). **Rule order is load-bearing** for the same
  reason: `punctuation.definition.string` carries both `hl-punctuation` and `hl-string`,
  equal specificity, so `.hl-string` is written later and a quote reads as its string.
  The comment rule is last so a comment is a comment whatever it contains.
- **Plain text is not "highlighted with a plain-text syntax".** When the resolved syntax
  is syntect's `Plain Text`, `source_lines` returns `Plain` lines, so a `LICENSE` is not
  wrapped in spans that colour nothing.
- **The caps are 512 KiB and 10,000 lines**, and they are two caps because the cost is
  both per byte (one enormous minified line) and per line. The page states it —
  otherwise a large Rust file silently looks like an unsupported language. Neither
  number was derived from a measurement; see below.
- **The syntax set is loaded once into a `OnceLock`** on the first blob viewed. It is a
  few MB of resident memory for the life of the process.

## current.md material — holes opened and shortcuts taken

- **The default syntax set is missing four languages this project itself uses.** Checked
  by test (`which_common_languages_the_default_set_knows`, prints its findings):

  | Highlighted | **Plain** |
  |---|---|
  | Rust, shell, Markdown, Python, JavaScript, Go, YAML, JSON, CSS, SQL, Makefile, C | **TOML, Dockerfile, TypeScript, JSX/TSX** |

  `Cargo.toml` and `Dockerfile` render unhighlighted in this repository today — the
  `highlight-toml-dark.png` screenshot is exactly that. `two-face` bundles the missing
  grammars and is the fix, **deliberately not added here**: it is another dependency and
  a decision for the orchestrator. As briefed, it was not attempted.
- **Highlighting costs ~87 ms per 1,255-line file in a release build** — measured on
  `browse.rs` with `cargo test --release`, and it is paid on every view because nothing
  caches. In the `topcoat dev` (debug) build the same page takes ~0.7 s to serve versus
  ~0.06 s for a file past the cap, so debug is roughly eight times slower and is not the
  number to plan against. 87 ms is still the most expensive thing on a blob page: it is
  a Rust regex engine over every line, not a subprocess. If it needs to go, the answers
  in order are cache per blob object id (the id is already in `FileView`), then lower the
  caps.
- **Nothing caches.** The same file is re-highlighted on every view.
- **Diffs, READMEs and markdown code fences are unhighlighted**, as scoped. A README
  rendered on the repository page goes through `web/markdown.rs`, which writes its own
  `<pre><code>`; wiring this module into it is a small, obvious follow-up and was left
  alone to keep the branches apart.
- **`\r\n` files keep the `\r` inside the highlighted markup** (it is stripped from the
  plain path by `str::lines`). Invisible in `white-space: pre`; noted rather than fixed.
- **The blob view's own header has no "this is Rust" indicator.** The language is
  detected and then only ever visible as colour.

## ui.md material

- The blob's code cell is the only place colour carries information rather than
  position. The palette is deliberately narrow — comments below muted-foreground,
  strings and keywords carrying the contrast, punctuation just under foreground,
  everything else close to it — so a file reads as text with structure, not as a parade.
  It is one more `--syntax-*` block in `styles.css`, so it follows the palette.
- **The over-cap notice is a row of the blob panel, not a banner**: one line of muted
  mono between the file header and the table, sharing the header's hairline. A page
  state, not an error.
- Entry point: none. Highlighting has no control and no URL of its own — it is what the
  blob view now does. The "Where the next features go" table needs no new row.