Clarify Highlight registration and annotations

[tannerlinsley]

A review of the README and all 33 documentation pages found imprecise statements about language registration, fallback behavior, shared definitions, and annotations. Explain what imports and registration each control, clarify configured fallbacks and retained tokenizer references, and identify diagnostic messages as application-supplied data.

Refresh current size tables with dated 1.0.0 measurements, qualify historical comparisons before their tables, and remove unsupported general cache/worker cost assertions. Update matching shipped skill prose. Implementation and API behavior are unchanged; the annotation demo's visible caption now identifies its supplied message.

Validation: typecheck, build, 33-page docs verification, 115 tests, five skill/version checks, 50 public ESM exports, ten tree-shaking bundles, publint, all seventeen size profiles, and ten benchmark profiles passed. Shiki and Sugar High comparison scripts were also rerun; timings vary by host, so historical tables remain explicitly qualified. Measurements used Node 26.3.1 and esbuild 0.28.1.

Draft for review; no release or deployment.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}