react-shiki 0.10.1 → 0.11.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Bassim Shahidy
+Copyright (c) 2026 Bassim Shahidy
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,12 +1,9 @@
 # 🎨 react-shiki
 
-
 A performant client-side syntax highlighting component and hook for React, built with [Shiki](https://shiki.matsu.io/).
 
-[See the demo page with highlighted code blocks showcasing several Shiki themes!](https://react-shiki.vercel.app/)
-
 <!--toc:start-->
-- [🎨 react-shiki](#🎨-react-shiki)
+- [🎨 react-shiki](#-react-shiki)
   - [Features](#features)
   - [Installation](#installation)
   - [Usage](#usage)
@@ -15,11 +12,14 @@ A performant client-side syntax highlighting component and hook for React, built
     - [`react-shiki/web` (Web Bundle)](#react-shikiweb-web-bundle)
     - [`react-shiki/core` (Minimal Bundle)](#react-shikicore-minimal-bundle)
     - [RegExp Engines](#regexp-engines)
-      - [Using Engines with Full and Web Bundles](#using-engines-with-full-and-web-bundles)
-      - [Using Engines with Core Bundle](#using-engines-with-core-bundle)
-      - [Engine Options](#engine-options)
+      - [Full and Web Bundles](#full-and-web-bundles)
+      - [Custom Highlighters (Core Bundle)](#custom-highlighters-core-bundle)
+        - [JavaScript Raw Engine](#javascript-raw-engine)
+  - [Output Formats](#output-formats)
   - [Configuration](#configuration)
     - [Common Configuration Options](#common-configuration-options)
+      - [react-shiki Options](#react-shiki-options)
+      - [Shiki Pass-through Options](#shiki-pass-through-options)
     - [Component-specific Props](#component-specific-props)
     - [Embedded Language Highlighting](#embedded-language-highlighting)
     - [Multi-theme Support](#multi-theme-support)
@@ -37,15 +37,14 @@ A performant client-side syntax highlighting component and hook for React, built
     - [Handling Inline Code](#handling-inline-code)
   - [Performance](#performance)
     - [Throttling Real-time Highlighting](#throttling-real-time-highlighting)
-    - [Output Format Optimization](#output-format-optimization)
 <!--toc:end-->
 
 ## Features
 
 - 🖼️ Provides both a `ShikiHighlighter` component and a `useShikiHighlighter` hook for more flexibility
-- 🔐 Flexible output: Choose between React elements (no `dangerouslySetInnerHTML`) or HTML strings for better performance
-- 📦 Multiple bundle options: Full bundle (~1.2MB gz), web bundle (~695KB gz), or minimal core bundle for fine-grained bundle control
-- 🖌️ Full support for custom TextMate themes and languages
+- 🔐 Flexible output: Choose between React elements (no `dangerouslySetInnerHTML`) or HTML strings
+- 📦 Multiple bundle options: Full bundle (~1.2MB gz), web bundle (~707KB gz), or minimal core bundle for fine-grained bundle control
+- 🖌️ Full support for custom TextMate themes and languages, passed as objects or dynamic imports
 - 🧬 Automatic highlighting of embedded languages (e.g. TypeScript fenced inside Markdown) via Shiki's `guessEmbeddedLanguages`
 - 🔧 Supports passing custom Shiki transformers to the highlighter, in addition to all other options supported by `codeToHast`
 - 🚰 Performant highlighting of streamed code, with optional throttling
@@ -99,8 +98,8 @@ function CodeBlock({ code, language }) {
 ```tsx
 import ShikiHighlighter from 'react-shiki';
 ```
-- **Size**: ~6.4MB minified, ~1.2MB gzipped (includes ~12KB react-shiki)
-- **Languages**: All Shiki languages and themes
+- **Size**: ~6.4MB minified, ~1.2MB gzipped (react-shiki itself: ~9KB minified, ~4KB gzipped)
+- **Languages**: All Shiki [languages](https://shiki.style/languages) and [themes](https://shiki.style/themes)
 - **Exported engines**: `createJavaScriptRegexEngine`, `createJavaScriptRawEngine`
 - **Use case**: Unknown language requirements, maximum language support
 - **Setup**: Zero configuration required
@@ -109,8 +108,8 @@ import ShikiHighlighter from 'react-shiki';
 ```tsx
 import ShikiHighlighter from 'react-shiki/web';
 ```
-- **Size**: ~3.8MB minified, ~707KB gzipped (includes ~12KB react-shiki)
-- **Languages**: Web-focused languages (HTML, CSS, JS, TS, JSON, Markdown, Vue, JSX, Svelte)
+- **Size**: ~3.8MB minified, ~707KB gzipped (react-shiki itself: ~9KB minified, ~4KB gzipped)
+- **Languages**: [Web-focused languages](https://shiki.style/guide/bundles#shiki-bundle-web) (HTML, CSS, JS, TS, JSON, Markdown, Vue, JSX, Svelte)
 - **Exported engines**: `createJavaScriptRegexEngine`, `createJavaScriptRawEngine`
 - **Use case**: Web applications with balanced size/functionality
 - **Setup**: Drop-in replacement for main entry point
@@ -135,7 +134,7 @@ const highlighter = await createHighlighterCore({
   {code}
 </ShikiHighlighter>
 ```
-- **Size**: ~12KB + your imported themes/languages
+- **Size**: ~9KB minified (~4KB gzipped) + your imported themes/languages
 - **Languages**: User-defined via custom highlighter  
 - **Use case**: Production apps requiring maximum bundle control
 - **Setup**: Requires custom highlighter configuration
@@ -144,40 +143,57 @@ const highlighter = await createHighlighterCore({
 ### RegExp Engines
 
 Shiki offers three built-in engines for syntax highlighting:
-- **Oniguruma** - Default engine using compiled WebAssembly, offers maximum language support
-- **JavaScript RegExp** - Smaller bundle, faster startup, compiles patterns on-the-fly, recommended for client-side highlighting
-- **JavaScript Raw** - For [pre-compiled languages](https://shiki.style/guide/regex-engines#pre-compiled-languages), skips transpilation step for best performance
 
-#### Using Engines with Full and Web Bundles
+| Engine | Payload (gzip) | Startup | Grammar support |
+| --- | --- | --- | --- |
+| **Oniguruma** (default) | ~150 KB (466 KB WASM) | fetch + compile WASM | Reference engine, all grammars |
+| **JavaScript RegExp** | ~20 KB | none, plain JS | All built-in languages ([compatibility table](https://shiki.style/references/engine-js-compat)); [strict by default](#full-and-web-bundles) |
+| **JavaScript Raw** | ~1 KB | none | [Pre-compiled grammars](https://shiki.style/guide/regex-engines#pre-compiled-languages) only, has a [known bug](https://github.com/shikijs/shiki/issues/918) |
 
-The full and web bundles use Oniguruma by default, but you can override this with the `engine` option:
+Payload sizes measured against shiki 4.3.0: `onig.wasm` is 466 KB (149 KB gzipped), the JavaScript engine's pattern transpiler ([oniguruma-to-es](https://github.com/slevithan/oniguruma-to-es)) is 57 KB (20 KB gzipped), and the raw engine skips the transpiler entirely. Beyond the smaller download, the JavaScript engine also starts instantly (no WASM fetch and compile) and [runs patterns as native JavaScript RegExp](https://shiki.style/guide/regex-engines#javascript-regexp-engine), which is faster for some languages.
 
-```tsx
-import {
-  useShikiHighlighter,
-  createJavaScriptRegexEngine,
-  createJavaScriptRawEngine
-} from 'react-shiki';
+#### Full and Web Bundles
 
-// Hook with JavaScript RegExp engine
+The full and web bundles use Oniguruma by default. You can swap to the JavaScript engine by passing `'javascript'` to `engine`. react-shiki creates and caches the engine internally, no need to import it, no WASM fetch with `'javascript'`, and it's safe to pass inline:
+
+```tsx
+// Hook
 const highlightedCode = useShikiHighlighter(code, 'typescript', 'github-dark', {
-  engine: createJavaScriptRegexEngine()
+  engine: 'javascript'
 });
 
-// Component with JavaScript Raw engine (for pre-compiled languages)
-// See https://shiki.style/guide/regex-engines#pre-compiled-languages
-<ShikiHighlighter
-  language="typescript"
-  theme="github-dark"
-  engine={createJavaScriptRawEngine()}
->
+// Component
+<ShikiHighlighter language="typescript" theme="github-dark" engine="javascript">
   {code}
 </ShikiHighlighter>
 ```
 
-#### Using Engines with Core Bundle
+> [!NOTE]
+> The underlying highlighter is a singleton created on the first highlight, so pass the same engine at every call site; mixed engines resolve to whichever highlighted first. 
+
+To customize engine configuration beyond the named defaults, pass an engine instance. **Create it once at module scope**; this avoids recreating new instances on every render, which would defeat memoization:
+
+```tsx
+import { useShikiHighlighter, createJavaScriptRegexEngine } from 'react-shiki';
+
+// Ensure this is at the module scope: created once, stable across renders
+const engine = createJavaScriptRegexEngine({ forgiving: true });
+
+const highlightedCode = useShikiHighlighter(code, 'typescript', 'github-dark', {
+  engine
+});
+```
+
+The JavaScript engine is strict by default: it throws when a grammar uses patterns it can't convert. `forgiving: true` skips those patterns for best-effort output. It also accepts `target` and `regexConstructor`, see [Shiki - RegExp Engines](https://shiki.style/guide/regex-engines) for details.
+
+The JavaScript Raw engine works the same way, but only with [pre-compiled languages](https://shiki.style/guide/regex-engines#pre-compiled-languages) (`@shikijs/langs-precompiled`). The full and web bundles don't support the raw engine because they bundle standard grammars, you need a [custom highlighter](#custom-highlighters-core-bundle).
 
-When using the core bundle, you must specify an engine:
+> [!IMPORTANT]
+> **Heads up:** in a future release, react-shiki's default engine will be swapped from Oniguruma WASM to the JavaScript engine (with [`forgiving`](https://shiki.style/guide/regex-engines#use-with-unsupported-languages) enabled by default).
+
+#### Custom Highlighters (Core Bundle)
+
+Named engines (`'javascript'`, `'oniguruma'`) don't apply to the core bundle since you create the highlighter with `createHighlighterCore`; instead, use `createJavaScriptRegexEngine` or `createOnigurumaEngine` to create a custom engine instance:
 
 ```tsx
 import {
@@ -193,42 +209,130 @@ const highlighter = await createHighlighterCore({
 });
 ```
 
-#### Engine Options
+##### JavaScript Raw Engine
 
-The JavaScript RegExp engine is [strict by default](https://shiki.style/guide/regex-engines#use-with-unsupported-languages). For best-effort results with unsupported grammars, enable the `forgiving` option:
+The JavaScript Raw engine is the smallest option at only ~1 KB, but requires [pre-compiled languages](https://shiki.style/guide/regex-engines#pre-compiled-languages), and faces a known upstream bug -- [shikijs/shiki:issue#918](https://github.com/shikijs/shiki/issues/918) -- causing some languages (Python, HTML, Perl, and YAML among those reported) to highlight incorrectly.
 
 ```tsx
-createJavaScriptRegexEngine({ forgiving: true });
+import {
+  useShikiHighlighter,
+  createHighlighterCore,
+  createJavaScriptRawEngine,
+} from 'react-shiki/core';
+
+// Module scope: raw engine + pre-compiled grammars, smallest and fastest
+const highlighter = await createHighlighterCore({
+  themes: [import('@shikijs/themes/github-dark')],
+  langs: [import('@shikijs/langs-precompiled/typescript')],
+  engine: createJavaScriptRawEngine()
+});
+
+const highlightedCode = useShikiHighlighter(code, 'typescript', 'github-dark', {
+  highlighter
+});
 ```
 
-See [Shiki - RegExp Engines](https://shiki.style/guide/regex-engines) for more info.
+Be sure to verify your language highlights correctly if you choose to use the raw engine ([shikijs/shiki:issue#918](https://github.com/shikijs/shiki/issues/918)).
+
+
+## Output Formats
 
+`react-shiki` can return highlighted code in three formats:
+
+**React Nodes (Default)** - Rendered as React elements, no `dangerouslySetInnerHTML` required
+```tsx
+// Hook
+const highlightedCode = useShikiHighlighter(code, "tsx", "github-dark");
+
+// Component
+<ShikiHighlighter language="tsx" theme="github-dark">
+  {code}
+</ShikiHighlighter>
+```
+
+**HTML String** - Rendered via `dangerouslySetInnerHTML`
+```tsx
+// Hook (returns HTML string, use dangerouslySetInnerHTML to render)
+const highlightedCode = useShikiHighlighter(code, "tsx", "github-dark", {
+  outputFormat: 'html'
+});
+
+// Component (automatically uses dangerouslySetInnerHTML when outputFormat is 'html')
+<ShikiHighlighter language="tsx" theme="github-dark" outputFormat="html">
+  {code}
+</ShikiHighlighter>
+```
+
+**Shiki Tokens (Experimental)** - Hook-only output (bring your own renderer, react-shiki does not provide one)
+```tsx
+const highlighted = useShikiHighlighter(code, "tsx", "github-dark", {
+  outputFormat: "tokens",
+});
+
+// Sample only, not a production renderer: you own rendering, memoization,
+// and commit management (critical for streaming highlighting)
+const rendered = highlighted?.tokens.map((line, i) => (
+  <div key={i}>
+    {line.map((token, j) => (
+      <span key={j} style={{ color: token.color }}>
+        {token.content}
+      </span>
+    ))}
+  </div>
+));
+```
+
+The React and HTML formats spend their rendering work in different phases. HTML output skips per-token React element creation and reconciliation, reducing render-phase overhead for large, one-shot highlights, but each update replaces the code block's entire DOM subtree via `innerHTML`. React output pays for element creation and diffing on every update, but commits only incremental DOM mutations, minimizing DOM churn for frequently re-highlighted code such as streaming LLM output.
+
+HTML output hands the highlighted markup to the DOM via `dangerouslySetInnerHTML`, so only use it with trusted code sources. The default React output is the safe choice for untrusted content.
+
+Token output is for when you need to own rendering yourself; it is intentionally available on the hook, not the `ShikiHighlighter` component, since react-shiki's markup-based features no longer apply once you control the markup. Note that Shiki's `codeToTokens` does not run transformers or decorations, so markup-producing options, including transformers, decorations, line numbers, and `structure`, have no effect on token output.
 
 ## Configuration
 
 ### Common Configuration Options
 
+The core inputs, positional arguments on the hook, props/children on the component:
 
-| Option              | Type               | Default         | Description                                                                   |
+| Input               | Type               | Default         | Description                                                                   |
 | ------------------- | ------------------ | --------------- | ----------------------------------------------------------------------------- |
 | `code`            | `string`           | -               | Code to highlight                                                               |
-| `language`          | `string \| object` | -               | Language to highlight, built-in or custom textmate grammer object             |
-| `theme`             | `string \| object` | `'github-dark'` | Single or multi-theme configuration, built-in or custom textmate theme object |
-| `delay`             | `number`           | `0`             | Delay between highlights (in milliseconds)                                    |
+| `language`          | `string \| object` | -               | Language to highlight, built-in or custom TextMate grammar object             |
+| `theme`             | `string \| object` | `'github-dark'` | Single or multi-theme configuration, built-in or custom TextMate theme object |
+
+#### react-shiki Options
+
+
+| Option              | Type               | Default         | Description                                                                   |
+| ------------------- | ------------------ | --------------- | ----------------------------------------------------------------------------- |
+| `delay`             | `number`           | -               | Minimum time between highlights (in milliseconds), no throttling by default   |
+| `engine`            | `'javascript' \| 'oniguruma' \| RegexEngine` | `'oniguruma'` | RegExp engine for syntax highlighting; named engines are created and cached internally |
+| `highlighter`       | `Highlighter \| HighlighterCore` | -  | Custom highlighter instance, required for the core bundle                     |
+| `outputFormat`      | `string`           | `'react'`       | Output format: 'react' for React nodes, 'html' for HTML string, or 'tokens' for Shiki tokens (hook only, experimental) |
+| `preloadLanguages`  | `array`            | `[]`            | Preload bundled language IDs, custom grammar objects, or dynamic grammar imports |
 | `customLanguages`   | `array`            | `[]`            | **Deprecated**: use `preloadLanguages` instead. |
-| `preloadLanguages`  | `array`            | `[]`            | Preload bundled language IDs and custom language grammars |
-| `langAlias`         | `object`           | `{}`            | Map of language aliases                                                       |
-| `engine`            | `RegexEngine`      | Oniguruma       | RegExp engine for syntax highlighting (Oniguruma, JavaScript RegExp, or JavaScript Raw) |
 | `showLineNumbers`   | `boolean`          | `false`         | Display line numbers alongside code                                           |
 | `startingLineNumber` | `number`           | `1`             | Starting line number when line numbers are enabled                           |
-| `transformers`      | `array`            | `[]`            | Custom Shiki transformers for modifying the highlighting output               |
-| `cssVariablePrefix` | `string`           | `'--shiki'`     | Prefix for CSS variables storing theme colors                                 |
-| `defaultColor`      | `string \| false`  | `'light'`       | Default theme mode when using multiple themes, can also disable default theme |
-| `outputFormat`      | `string`           | `'react'`       | Output format: 'react' for React nodes, 'html' for HTML string                 |
-| `tabindex`          | `number`           | `0`             | Tab index for the code block                                                  |
-| `decorations`       | `array`            | `[]`            | Custom decorations to wrap the highlighted tokens with                        |
-| `structure`        | `string`           | `classic`  | The structure of the generated HAST and HTML - `classic` or `inline`               |
-| [`codeToHastOptions`](https://github.com/shikijs/shiki/blob/main/packages/types/src/options.ts#L121) | -             | -              | All other options supported by Shiki's `codeToHast`      |
+| `highlightLineNumbers` | `number[]`     | -               | Displayed line numbers to highlight                                           |
+
+#### Shiki Pass-through Options
+
+All of Shiki's options pass-through and are accessible in react-shiki.
+
+Based on `outputFormat`:
+- `'tokens'`: All options supported by Shiki's [`codeToTokens`](https://github.com/shikijs/shiki/blob/v4.3.0/packages/types/src/tokens.ts#L27)
+- `'html'`: All options supported by Shiki's [`codeToHtml`](https://github.com/shikijs/shiki/blob/v4.3.0/packages/types/src/options.ts#L136)
+- `'react'`: All options supported by Shiki's [`codeToHast`](https://github.com/shikijs/shiki/blob/v4.3.0/packages/types/src/options.ts#L136)
+
+Commonly used:
+- `transformers`: modify the highlighting output with Shiki transformers (default: `[]`)
+- `decorations`: wrap ranges of highlighted tokens (default: `[]`)
+- `defaultColor`: default theme mode with multi-theme, `false` to disable (default: `'light'`)
+- `cssVariablePrefix`: prefix for theme color CSS variables (default: `'--shiki-'`)
+- `langAlias`: map custom language names to bundled ones (default: `{}`)
+- `structure`: `'classic'` or `'inline'` HAST/HTML shape (default: `'classic'`)
+- `tabindex`: tab index of the code block (default: `0`)
+- `meta`: arbitrary metadata passed to transformers (default: `{}`)
 
 ### Component-specific Props
 
@@ -246,7 +350,7 @@ The `ShikiHighlighter` component offers minimal built-in styling and customizati
 
 ### Embedded Language Highlighting
 
-react-shiki uses Shiki's [`guessEmbeddedLanguages`](https://shiki.style) to automatically detect, load, and highlight languages nested inside other languages — for example, a TypeScript fenced code block inside a Markdown document will be highlighted as TypeScript without any extra configuration. Embedded languages are dynamically loaded on demand, as long as they exist in your bundle.
+react-shiki uses Shiki's [`guessEmbeddedLanguages`](https://github.com/shikijs/shiki/blob/main/packages/core/src/utils/strings.ts) to automatically detect, load, and highlight languages nested inside other languages. For example, a TypeScript fenced code block inside a Markdown document will be highlighted as TypeScript without any extra configuration. Embedded languages are dynamically loaded on demand, as long as they exist in your bundle.
 
 ### Multi-theme Support
 
@@ -333,11 +437,11 @@ Ensure your site sets the `color-scheme` CSS property:
 
 For broader browser support or more control, add CSS snippets to your site to enable theme switching with media queries or class-based switching. See [Shiki's documentation](https://shiki.matsu.io/guide/dual-themes) for the required CSS snippets.
 
-> **Note**: The `light-dark()` function requires modern browser support. For older browsers, use the manual CSS variables approach.
+> **Note**: The `light-dark()` function requires [modern browser support](https://caniuse.com/wf-light-dark). For older browsers, use the manual CSS variables approach.
 
 ### Custom Themes
 
-Custom themes can be passed as a TextMate theme in JavaScript object. For example, [it should look like this](https://github.com/antfu/textmate-grammars-themes/blob/main/packages/tm-themes/themes/dark-plus.json).
+Custom themes can be passed as a TextMate theme JavaScript object ([example](https://github.com/antfu/textmate-grammars-themes/blob/main/packages/tm-themes/themes/dark-plus.json)).
 
 ```tsx
 import tokyoNight from "../styles/tokyo-night.json";
@@ -351,9 +455,29 @@ import tokyoNight from "../styles/tokyo-night.json";
 const highlightedCode = useShikiHighlighter(code, "tsx", tokyoNight);
 ```
 
+When using a fine-grained highlighter via `react-shiki/core`: pass the theme as a dynamic import to `createHighlighterCore` so it stays out of the initial chunk, then reference it by its `name` field:
+
+```tsx
+const highlighter = await createHighlighterCore({
+  themes: [import("../styles/tokyo-night.json")],
+  langs: [import("@shikijs/langs/tsx")],
+  engine: createJavaScriptRegexEngine(),
+});
+
+// Component
+<ShikiHighlighter highlighter={highlighter} language="tsx" theme="tokyo-night">
+  {code.trim()}
+</ShikiHighlighter>
+
+// Hook
+const highlightedCode = useShikiHighlighter(code, "tsx", tokyoNight, {
+  highlighter,
+});
+```
+
 ### Custom Languages
 
-Custom languages should be passed as a TextMate grammar in JavaScript object. For example, [it should look like this](https://github.com/shikijs/textmate-grammars-themes/blob/main/packages/tm-grammars/grammars/typescript.json)
+Custom languages should be passed as a TextMate grammar JavaScript object ([example](https://github.com/shikijs/textmate-grammars-themes/blob/main/packages/tm-grammars/grammars/typescript.json)).
 ```tsx
 import mcfunction from "../langs/mcfunction.tmLanguage.json";
 
@@ -366,6 +490,28 @@ import mcfunction from "../langs/mcfunction.tmLanguage.json";
 const highlightedCode = useShikiHighlighter(code, mcfunction, "github-dark");
 ```
 
+Passing grammar objects as props works with the full and web bundles, where react-shiki creates the highlighter and loads them for you. To keep custom grammars out of the main bundle, pass them as dynamic imports via `preloadLanguages` and reference them by name — see [Preloading Languages](#preloading-languages).
+
+On the core bundle you own the highlighter, so include grammars there as dynamic imports:
+
+```tsx
+const highlighter = await createHighlighterCore({
+  themes: [import("@shikijs/themes/github-dark")],
+  langs: [import("../langs/mcfunction.tmLanguage.json")],
+  engine: createJavaScriptRegexEngine(),
+});
+
+// Component
+<ShikiHighlighter highlighter={highlighter} language="mcfunction" theme="github-dark">
+  {code.trim()}
+</ShikiHighlighter>
+
+// Hook
+const highlightedCode = useShikiHighlighter(code, "mcfunction", "github-dark", {
+  highlighter,
+});
+```
+
 #### Preloading Languages
 
 If highlighting is dynamic at runtime, preload custom languages. 
@@ -389,8 +535,29 @@ const highlightedCode = useShikiHighlighter(code, "typescript", "github-dark", {
 });
 ```
 
+Custom grammars can also be dynamic imports, keeping them out of the main bundle. Reference them by the grammar's `name` field:
+
+```tsx
+// Module scope: stable identity across renders, fetched on first highlight
+const preloadLanguages = [
+  () => import("../langs/mcfunction.tmLanguage.json"),
+  () => import("../langs/bosque.tmLanguage.json"),
+];
+
+<ShikiHighlighter
+  language="mcfunction"
+  theme="github-dark"
+  preloadLanguages={preloadLanguages}
+>
+  {code.trim()}
+</ShikiHighlighter>
+```
+
+> [!IMPORTANT]
+> Define dynamic imports at module scope, preferring the getter form (`() => import(...)`). A fresh arrow function on every render re-triggers highlighting; bare promises are compared by type, so swapping one at runtime won't be picked up.
+
 > [!NOTE] 
-> Bundled language are dynamically loaded as needed, and do not need to be preloaded as long as they exist in your bundle.
+> Bundled languages are loaded on demand and do not need to be preloaded. `preloadLanguages` applies to the full and web bundles; with a custom highlighter, load languages in `createHighlighterCore` instead.
 
 ### Language Aliases
 
@@ -430,47 +597,37 @@ const highlightedCode = useShikiHighlighter(code, "tsx", "github-dark", {
 
 ### Line Numbers
 
-Display line numbers alongside your code, these are CSS-based
-and can be customized with CSS variables:
+Line numbers are CSS-based and can be customized with CSS variables:
 
 ```tsx
 // Component
 <ShikiHighlighter 
   language="javascript"
   theme="github-dark"
-  showLineNumbers,
+  showLineNumbers
   startingLineNumber={0} // default is 1
+  highlightLineNumbers={[2, 4]}
 >
   {code}
 </ShikiHighlighter>
 
-<ShikiHighlighter 
-  language="python" 
-  theme="github-dark" 
-  showLineNumbers 
-  startingLineNumber={0}
->
-  {code}
-</ShikiHighlighter>
-
-// Hook (import 'react-shiki/css' for line numbers to work)
+// Hook (line-number styles inject automatically when enabled)
 const highlightedCode = useShikiHighlighter(code, "javascript", "github-dark", {
   showLineNumbers: true,
-  startingLineNumber: 0, 
+  startingLineNumber: 0,
+  highlightLineNumbers: [2, 4],
 });
 ```
 
 > [!NOTE]
-> When using the hook with line numbers, import the CSS file or provide your own CSS 
-> for `.rs-line-number` (line `span`) and `.rs-has-line-numbers` (container `code` element). <!-- TODO: The CSS vars/classes/selectors are poorly documented -->
-> ```tsx
-> import 'react-shiki/css';
-> ```
+> No CSS import is needed: the shared highlighting hook injects line-number and highlight styles automatically when those features are enabled, including when used through the component.
+> To customize them, override `.rs-line-number` (line `span`), `.rs-highlighted-line` (line `span`), and `.rs-has-line-numbers` / `.rs-has-highlighted-lines` (container `code` element) in your own CSS.
 
-> [!WARNING]
-> Legacy `.line-numbers` / `.has-line-numbers` selectors and unprefixed line-number CSS variables are removed as of 0.10.1.
+`highlightLineNumbers` uses displayed line numbers, so it works with `startingLineNumber`.
 
-Component-internal default classes are namespaced under `rs-*` and shipped inside `@layer base` so app-level utilities can override them more predictably.
+Component styles are embedded in the JS and installed automatically when the component mounts — no CSS import or bundler configuration needed. Injection is scoped to usage: component styles tree-shake out of hook-only bundles entirely, while line-number/highlight styles are installed only when those options are enabled. The complete compiled stylesheet is also exported as `react-shiki/css` for build-time CSS pipelines or as an externally loaded fallback. Importing it does not disable automatic runtime injection.
+
+Component-internal default classes are namespaced under `rs-*` and written with zero-specificity `:where()` selectors, so they can't be clobbered by CSS resets (e.g. Tailwind preflight) regardless of stylesheet load order, while any rule in your own CSS — even a bare element selector — overrides them.
 
 Available CSS variables for customization:
 ```css
@@ -481,8 +638,12 @@ Available CSS variables for customization:
 --rs-line-numbers-font-size: inherit;
 --rs-line-numbers-font-weight: inherit;
 --rs-line-numbers-opacity: 1;
+--rs-highlighted-line-background: color-mix(in srgb, currentColor 10%, transparent);
+--rs-highlighted-line-number-foreground: color-mix(in srgb, currentColor 65%, transparent);
 ```
 
+With default styles, highlighted-line backgrounds automatically extend into the `pre`'s horizontal padding, reaching the container edges. When styling the `pre` yourself, highlights cover the code content area.
+
 You can customize them in your own CSS or by using the style prop on the component:
 ```tsx
 <ShikiHighlighter 
@@ -573,9 +734,9 @@ const CodeHighlight = ({ className, children, node, ...props }) => {
 **Method 2: Using the `rehypeInlineCodeProperty` plugin:**
 
 `react-shiki` also exports `rehypeInlineCodeProperty`, a rehype plugin that 
-provides the same API as `react-markdown` prior to `9.0.0`. It reintroduces the 
-`inline` prop which works by checking if `<code>` is nested within a `<pre>` tag, 
-if not, it's considered inline code and the `inline` prop is set to `true`.
+adds an `inline` prop to `react-markdown` code components. It works by checking 
+if `<code>` is nested within a `<pre>` tag; if not, it's considered inline code 
+and the `inline` prop is set to `true`.
 
 It's passed as a `rehypePlugin` to `react-markdown`:
 
@@ -623,7 +784,7 @@ const CodeHighlight = ({
 
 ### Throttling Real-time Highlighting
 
-For improved performance when highlighting frequently changing code:
+To reduce highlighting work for frequently changing code:
 
 ```tsx
 // With the component
@@ -637,36 +798,6 @@ const highlightedCode = useShikiHighlighter(code, "tsx", "github-dark", {
 });
 ```
 
-### Output Format Optimization
-
-`react-shiki` provides two output formats to balance safety and performance:
-
-**React Nodes (Default)** - Safer, no `dangerouslySetInnerHTML` required
-```tsx
-// Hook
-const highlightedCode = useShikiHighlighter(code, "tsx", "github-dark");
-
-// Component
-<ShikiHighlighter language="tsx" theme="github-dark">
-  {code}
-</ShikiHighlighter>
-```
-
-**HTML String** - 15-45% faster performance
-```tsx
-// Hook (returns HTML string, use dangerouslySetInnerHTML to render)
-const highlightedCode = useShikiHighlighter(code, "tsx", "github-dark", {
-  outputFormat: 'html'
-});
-
-// Component (automatically uses dangerouslySetInnerHTML when outputFormat is 'html')
-<ShikiHighlighter language="tsx" theme="github-dark" outputFormat="html">
-  {code}
-</ShikiHighlighter>
-```
-
-Choose HTML output when performance is critical and you trust the code source. Use the default React output when handling untrusted content or when security is the primary concern.
-
 ---
 
 Made with ❤️ by [Bassim (AVGVSTVS96)](https://github.com/AVGVSTVS96)