Engine-neutral tokens keep adapters replaceable

A highlighter port is an interface for highlighting code, independent of the chosen highlighting tool. This follows ports and adapters19.

The code-snippets design brief14 specifies an engine-neutral token:

The highlighter port also exposes languages, aliases, themes, and an engine fingerprint. This identifier records the highlighter, version, and settings used in token cache keys.

The proposed Shiki adapter keeps Shiki’s token type inside the adapter. A plain adapter returns uncoloured text. Both adapters provide the same port through an Effect Layer12.

Core properties use the plain adapter. The whole-file token property exercises Shiki. One snippet model8 supplies both renderers.

See the glossary for engine-neutral token and highlighter port.

Sources

  1. Hexagonal architecture. Primary source. Port and adapter boundary Accessed 2026-10-02.
  2. Code-snippets design brief. Primary source. Proposed highlighter contract Accessed 2026-10-02.
  3. Effect Layer. Effect contributors. Service providers Accessed 2026-10-02.

Last changed 2026-10-07 in 0e2d656. Source on GitHub. Change log.

Linked from

  1. Agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.

    Engine-neutral tokens keep adapters replaceable — The highlighter port exposes text, roles, and font styles rather than Shiki types.

  2. Change log. What changed in the files served here, newest first.

    Engine-neutral tokens keep adapters replaceable — edited: feat(learn): teach cards 23 to 42 with plain lines, diagrams and snippets

  3. Code snippets quote a pinned source. Shipped design brief: pinned Git objects, typed diagnostics, and one build-only snippet model for both views.

    The highlighter port exposes:¶

  4. Full agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
  5. One snippet model feeds both renderers. HTML and agent Markdown derive their code, repository, commit, path, and line numbers from the same snippet.

    Engine-neutral tokens keep renderer input independent of Shiki.¶

  6. Rat Stack lore | rat-stack. Short, source-grounded notes on the ideas and decisions behind rat-stack.

    Engine-neutral tokens keep adapters replaceable — The highlighter port exposes text, roles, and font styles rather than Shiki types.

  7. Source change history (log.md). The generated change log as Markdown.

    Engine-neutral tokens keep adapters replaceable — edited: feat(learn): teach cards 23 to 42 with plain lines, diagrams and snippets