diff --git a/docs/content/4.plugins/1.built-in/rangi.md b/docs/content/4.plugins/1.built-in/rangi.md
index f656f353..a69ca942 100644
--- a/docs/content/4.plugins/1.built-in/rangi.md
+++ b/docs/content/4.plugins/1.built-in/rangi.md
@@ -35,6 +35,8 @@ npm install rangi
 Use [`comark/plugins/shiki`](/plugins/built-in/shiki) when you need transformers, Twoslash, or the full VS Code grammar set. Use `rangi` for a faster, smaller highlighter with built-in light/dark themes.
 ::
 
+Inline code highlighting with `{lang="…"}` is currently shiki only. Rangi highlights fenced blocks.
+
 ## Usage
 
 ```typescript
diff --git a/docs/content/4.plugins/1.built-in/shiki.md b/docs/content/4.plugins/1.built-in/shiki.md
index 9ef4539b..c70cd860 100644
--- a/docs/content/4.plugins/1.built-in/shiki.md
+++ b/docs/content/4.plugins/1.built-in/shiki.md
@@ -196,6 +196,49 @@ const x: number = 42
 ```
 ````
 
+### Inline code
+
+Inline code is highlighted when it declares a language with the attributes syntax. `lang` wins over `language`:
+
+```markdown
+The type is `Ref<HTMLInputElement | null>`{lang="ts-type"} and the component is `<UButton />`{lang="vue-html"}.
+```
+
+Inline code uses the fast token path only, so `transformers` and `preStyles` are block-only and are not applied. The node gets the same `shiki` class a `<pre>` gets, so the dual-theme CSS in [Styling](#styling) covers it without extra rules.
+
+Inline code naming a grammar that is not registered is left exactly as it was written, with no class and no spans. That is deliberate: `lang` is a real HTML attribute for natural language, so `` `Bonjour`{lang="fr"} `` must not be treated as code. A fenced block behaves differently and still falls back to an unhighlighted `.shiki` block, because a `<pre>` is unambiguously code.
+
+Plain-text language names follow the same rule: `` `x`{lang="text"} ``, `txt` and `plain` are not registered grammars, so inline code naming one is left alone. The same name on a fence still produces a `.shiki` block.
+
+Set `inlineCode: false` to turn this off.
+
+### Grammar contexts
+
+Some inline snippets are fragments rather than whole statements, so the grammar needs seeding before it tokenizes them correctly. A grammar context maps a name you write in `{lang="…"}` onto a real grammar plus source that is tokenized and then discarded.
+
+Two ship by default, mirroring the `@nuxtjs/mdc` conventions:
+
+| Name | Grammar | Seed |
+|---|---|---|
+| `ts-type` | `typescript` | `let a:` |
+| `vue-html` | `vue` | `<template>` |
+
+Without the `ts-type` seed, `Ref<HTMLInputElement | null>` tokenizes as an expression and the type names fall through to plain text.
+
+Add your own with `grammarContexts`:
+
+```ts
+shiki({
+  grammarContexts: {
+    'sql-expr': { lang: 'sql', grammarContextCode: 'select ' },
+  },
+})
+```
+
+A registered grammar always wins. Shiki ships a real `vue-html` grammar, so registering it through `languages` gets you that grammar rather than the built-in context that seeds `vue`.
+
+Contexts apply to fence info strings too. The written name stays on the `<pre>`, so ```` ```ts-type ```` still round-trips. On the `core` entry the target grammar has to be registered through `languages` like any other.
+
 ### Line highlighting
 
 Highlight specific lines using `{line-numbers}` syntax:
@@ -304,6 +347,8 @@ Two option types, one per entry:
 | [`languages`](#options-languages) | `Array<LanguageRegistration \| LanguageRegistration[]>` | `undefined` | Extra languages (merged onto the default set) |
 | [`transformers`](#options-transformers) | `ShikiTransformer[]` | `undefined` | Shiki transformers applied to every block |
 | [`preStyles`](#options-prestyles) | `boolean` | `false` | Add inline background/foreground styles to `<pre>` |
+| [`inlineCode`](#options-inlinecode) | `boolean` | `true` | Highlight inline code that declares a language |
+| [`grammarContexts`](#options-grammarcontexts) | `Record<string, ShikiGrammarContext>` | Built-ins | Pseudo-languages merged over `ts-type` and `vue-html` |
 | [`registerDefaultLanguages`](#options-registerdefaultlanguages) | `boolean` | `true` | Register the built-in default language set |
 | [`registerDefaultThemes`](#options-registerdefaultthemes) | `boolean` | `true` | Register the built-in Material themes |
 
@@ -315,6 +360,8 @@ Two option types, one per entry:
 | `languages` | `Array<LanguageRegistration \| LanguageRegistration[]>` | **required** | Languages to register |
 | `transformers` | `ShikiTransformer[]` | `undefined` | Shiki transformers applied to every block |
 | `preStyles` | `boolean` | `false` | Add inline background/foreground styles to `<pre>` |
+| `inlineCode` | `boolean` | `true` | Highlight inline code that declares a language |
+| `grammarContexts` | `Record<string, ShikiGrammarContext>` | Built-ins | Pseudo-languages merged over `ts-type` and `vue-html` |
 
 ### `themes`
 
@@ -384,6 +431,34 @@ shiki({ preStyles: true })
 
 **Default:** `false`
 
+Block-only. Inline code never receives inline styles, so a user-authored `` `x`{style="…"} `` survives the round-trip.
+
+### `inlineCode`
+
+Whether to highlight inline code that declares a language, e.g. `` `Ref<T>`{lang="ts-type"} ``. See [Inline code](#inline-code).
+
+```typescript
+shiki({ inlineCode: false })
+```
+
+**Default:** `true`
+
+### `grammarContexts`
+
+Pseudo-languages usable in `{lang="…"}` and in fence info strings, merged on top of the built-in `ts-type` and `vue-html`. See [Grammar contexts](#grammar-contexts).
+
+```typescript
+shiki({
+  grammarContexts: {
+    'sql-expr': { lang: 'sql', grammarContextCode: 'select ' },
+  },
+})
+```
+
+Each entry is `{ lang, grammarContextCode? }`. A name that is already a registered grammar is never routed through a context.
+
+**Default:** the built-in contexts
+
 ### `registerDefaultLanguages`
 
 Standard entry only. When `true`, these languages are pre-registered: `vue`, `tsx`, `svelte`, `astro`, `typescript`, `javascript`, `bash`, `json`, `yaml` (plus the built-in Comark/`mdc` grammar). Set to `false` to control the language set entirely via `languages`.
@@ -488,6 +563,8 @@ Browser-side twoslash with CDN-fetched TypeScript types and interactive type pop
 
 Shiki outputs tokens as `<span class="line">` elements inside a `<pre class="shiki">` block.
 
+Highlighted inline code gets the same `shiki` class on the `<code>` element, with the token spans directly inside it and no `.line` wrapper. Rules written against `.shiki span` therefore cover both. Use `pre.shiki` when a rule should apply to blocks only.
+
 ### Line highlight
 
 Lines set with `{1,3-5}` syntax receive the `.highlight` class:
diff --git a/packages/comark/SPEC/COMARK/attributes/wrapped-pre-highlighted.md b/packages/comark/SPEC/COMARK/attributes/wrapped-pre-highlighted.md
index 4327a366..14b6356e 100644
--- a/packages/comark/SPEC/COMARK/attributes/wrapped-pre-highlighted.md
+++ b/packages/comark/SPEC/COMARK/attributes/wrapped-pre-highlighted.md
@@ -29,7 +29,10 @@ const variable = "value"
       {
         "language": "ts",
         "attr": "value",
-        "class": "shiki shiki-themes min-light nord dark:nord . class",
+        "class": "shiki shiki-themes min-light nord dark:nord class",
+        "$": {
+          "class": "class"
+        },
         "style": "background-color:#ffffff;color:#212121;--shiki-dark-bg:#2e3440;--shiki-dark:#d8dee9"
       },
       [
@@ -95,7 +98,7 @@ const variable = "value"
 ## HTML
 
 ```html
-<pre language="ts" attr="value" class="shiki shiki-themes min-light nord dark:nord . class" style="background-color:#ffffff;color:#212121;--shiki-dark-bg:#2e3440;--shiki-dark:#d8dee9"><code class="language-ts"><span class="line" style="display: inline"><span style="color:#D32F2F;--shiki-dark:#81A1C1">const</span><span style="color:#1976D2;--shiki-dark:#D8DEE9"> variable</span><span style="color:#D32F2F;--shiki-dark:#81A1C1"> =</span><span style="color:#22863A;--shiki-dark:#ECEFF4"> "</span><span style="color:#22863A;--shiki-dark:#A3BE8C">value</span><span style="color:#22863A;--shiki-dark:#ECEFF4">"</span></span></code></pre>
+<pre language="ts" attr="value" class="shiki shiki-themes min-light nord dark:nord class" style="background-color:#ffffff;color:#212121;--shiki-dark-bg:#2e3440;--shiki-dark:#d8dee9"><code class="language-ts"><span class="line" style="display: inline"><span style="color:#D32F2F;--shiki-dark:#81A1C1">const</span><span style="color:#1976D2;--shiki-dark:#D8DEE9"> variable</span><span style="color:#D32F2F;--shiki-dark:#81A1C1"> =</span><span style="color:#22863A;--shiki-dark:#ECEFF4"> "</span><span style="color:#22863A;--shiki-dark:#A3BE8C">value</span><span style="color:#22863A;--shiki-dark:#ECEFF4">"</span></span></code></pre>
 ```
 
 ## Markdown
diff --git a/packages/comark/SPEC/COMARK/shiki-codeblock-dual-theme.md b/packages/comark/SPEC/COMARK/shiki-codeblock-dual-theme.md
index b36dc44a..217e1497 100644
--- a/packages/comark/SPEC/COMARK/shiki-codeblock-dual-theme.md
+++ b/packages/comark/SPEC/COMARK/shiki-codeblock-dual-theme.md
@@ -32,6 +32,9 @@ console.log(greeting)
       {
         "language": "typescript",
         "class": "shiki shiki-themes min-light nord dark:nord",
+        "$": {
+          "class": ""
+        },
         "style": "background-color:#ffffff;color:#212121;--shiki-dark-bg:#2e3440;--shiki-dark:#d8dee9"
       },
       [
diff --git a/packages/comark/SPEC/COMARK/shiki-codeblock-highlight-complex.md b/packages/comark/SPEC/COMARK/shiki-codeblock-highlight-complex.md
index e0de7ee6..90eb6182 100644
--- a/packages/comark/SPEC/COMARK/shiki-codeblock-highlight-complex.md
+++ b/packages/comark/SPEC/COMARK/shiki-codeblock-highlight-complex.md
@@ -48,6 +48,9 @@ func main() {
           10
         ],
         "class": "shiki shiki-themes github-dark dark:github-dark",
+        "$": {
+          "class": ""
+        },
         "style": "background-color:#24292e;color:#e1e4e8"
       },
       [
diff --git a/packages/comark/SPEC/COMARK/shiki-codeblock-language-meta.md b/packages/comark/SPEC/COMARK/shiki-codeblock-language-meta.md
index d9eceaea..e5d73b9d 100644
--- a/packages/comark/SPEC/COMARK/shiki-codeblock-language-meta.md
+++ b/packages/comark/SPEC/COMARK/shiki-codeblock-language-meta.md
@@ -37,6 +37,9 @@ console.log(greeting)
         ],
         "meta": "some meta",
         "class": "shiki shiki-themes github-dark dark:github-dark",
+        "$": {
+          "class": ""
+        },
         "style": "background-color:#24292e;color:#e1e4e8"
       },
       [
diff --git a/packages/comark/SPEC/COMARK/shiki-codeblock-language-only.md b/packages/comark/SPEC/COMARK/shiki-codeblock-language-only.md
index a15c100f..74a95456 100644
--- a/packages/comark/SPEC/COMARK/shiki-codeblock-language-only.md
+++ b/packages/comark/SPEC/COMARK/shiki-codeblock-language-only.md
@@ -29,7 +29,10 @@ console.log(greeting)
       "pre",
       {
         "language": "typescript",
-        "class": "shiki shiki-themes github-dark dark:github-dark"
+        "class": "shiki shiki-themes github-dark dark:github-dark",
+        "$": {
+          "class": ""
+        }
       },
       [
         "code",
diff --git a/packages/comark/SPEC/COMARK/shiki-codeblock-no-language.md b/packages/comark/SPEC/COMARK/shiki-codeblock-no-language.md
index 9fd13c0e..71a31510 100644
--- a/packages/comark/SPEC/COMARK/shiki-codeblock-no-language.md
+++ b/packages/comark/SPEC/COMARK/shiki-codeblock-no-language.md
@@ -30,6 +30,9 @@ No language specified
       "pre",
       {
         "class": "shiki shiki-themes github-dark dark:github-dark",
+        "$": {
+          "class": ""
+        },
         "style": "background-color:#24292e;color:#e1e4e8"
       },
       [
diff --git a/packages/comark/SPEC/COMARK/shiki-codeblock-rust-example.md b/packages/comark/SPEC/COMARK/shiki-codeblock-rust-example.md
index 812bbba6..ce162932 100644
--- a/packages/comark/SPEC/COMARK/shiki-codeblock-rust-example.md
+++ b/packages/comark/SPEC/COMARK/shiki-codeblock-rust-example.md
@@ -41,6 +41,9 @@ fn main() {
           4
         ],
         "class": "shiki shiki-themes github-dark dark:github-dark",
+        "$": {
+          "class": ""
+        },
         "style": "background-color:#24292e;color:#e1e4e8"
       },
       [
diff --git a/packages/comark/SPEC/COMARK/shiki-codeblock-special-chars.md b/packages/comark/SPEC/COMARK/shiki-codeblock-special-chars.md
index 90c0f2d1..036bf98a 100644
--- a/packages/comark/SPEC/COMARK/shiki-codeblock-special-chars.md
+++ b/packages/comark/SPEC/COMARK/shiki-codeblock-special-chars.md
@@ -35,6 +35,9 @@ options:
         "language": "html",
         "filename": "template.html",
         "class": "shiki shiki-themes github-dark dark:github-dark",
+        "$": {
+          "class": ""
+        },
         "style": "background-color:#24292e;color:#e1e4e8"
       },
       [
diff --git a/packages/comark/SPEC/COMARK/shiki-codeblock-twoslash.md b/packages/comark/SPEC/COMARK/shiki-codeblock-twoslash.md
index 5e21947e..e2276482 100644
--- a/packages/comark/SPEC/COMARK/shiki-codeblock-twoslash.md
+++ b/packages/comark/SPEC/COMARK/shiki-codeblock-twoslash.md
@@ -32,7 +32,10 @@ const message = "Hello from twoslash"
       {
         "language": "ts",
         "meta": "twoslash",
-        "class": "shiki shiki-themes min-light twoslash lsp dark:min-light"
+        "class": "shiki shiki-themes min-light twoslash lsp dark:min-light",
+        "$": {
+          "class": ""
+        }
       },
       [
         "code",
diff --git a/packages/comark/SPEC/COMARK/shiki-codeblock-with-empty-lines.md b/packages/comark/SPEC/COMARK/shiki-codeblock-with-empty-lines.md
index b54295fd..bde0502d 100644
--- a/packages/comark/SPEC/COMARK/shiki-codeblock-with-empty-lines.md
+++ b/packages/comark/SPEC/COMARK/shiki-codeblock-with-empty-lines.md
@@ -37,6 +37,9 @@ More content here.
         "language": "markdown",
         "filename": "content.md",
         "class": "shiki shiki-themes github-dark dark:github-dark",
+        "$": {
+          "class": ""
+        },
         "style": "background-color:#24292e;color:#e1e4e8"
       },
       [
diff --git a/packages/comark/SPEC/COMARK/shiki-inline-code-lang.md b/packages/comark/SPEC/COMARK/shiki-inline-code-lang.md
new file mode 100644
index 00000000..2e687bad
--- /dev/null
+++ b/packages/comark/SPEC/COMARK/shiki-inline-code-lang.md
@@ -0,0 +1,129 @@
+---
+timeout:
+  parse: 500ms
+  html: 5ms
+  markdown: 5ms
+options:
+  highlight:
+    themes:
+      light: 'github-dark'
+---
+
+## Input
+
+```md
+Use `Ref<HTMLInputElement | null>`{lang="ts-type"} with `<UButton />`{lang="vue-html"}.
+```
+
+## AST
+
+```json
+{
+  "frontmatter": {},
+  "meta": {},
+  "nodes": [
+    [
+      "p",
+      {},
+      "Use ",
+      [
+        "code",
+        {
+          "lang": "ts-type",
+          "class": "shiki shiki-themes github-dark dark:github-dark",
+          "$": {
+            "class": ""
+          }
+        },
+        [
+          "span",
+          {
+            "style": "color:#B392F0"
+          },
+          "Ref"
+        ],
+        [
+          "span",
+          {
+            "style": "color:#E1E4E8"
+          },
+          "<"
+        ],
+        [
+          "span",
+          {
+            "style": "color:#B392F0"
+          },
+          "HTMLInputElement"
+        ],
+        [
+          "span",
+          {
+            "style": "color:#F97583"
+          },
+          " |"
+        ],
+        [
+          "span",
+          {
+            "style": "color:#79B8FF"
+          },
+          " null"
+        ],
+        [
+          "span",
+          {
+            "style": "color:#E1E4E8"
+          },
+          ">"
+        ]
+      ],
+      " with ",
+      [
+        "code",
+        {
+          "lang": "vue-html",
+          "class": "shiki shiki-themes github-dark dark:github-dark",
+          "$": {
+            "class": ""
+          }
+        },
+        [
+          "span",
+          {
+            "style": "color:#E1E4E8"
+          },
+          "<"
+        ],
+        [
+          "span",
+          {
+            "style": "color:#85E89D"
+          },
+          "UButton"
+        ],
+        [
+          "span",
+          {
+            "style": "color:#E1E4E8"
+          },
+          " />"
+        ]
+      ],
+      "."
+    ]
+  ]
+}
+```
+
+## HTML
+
+```html
+<p>Use <code lang="ts-type" class="shiki shiki-themes github-dark dark:github-dark"><span style="color:#B392F0">Ref</span><span style="color:#E1E4E8">&lt;</span><span style="color:#B392F0">HTMLInputElement</span><span style="color:#F97583"> |</span><span style="color:#79B8FF"> null</span><span style="color:#E1E4E8">&gt;</span></code> with <code lang="vue-html" class="shiki shiki-themes github-dark dark:github-dark"><span style="color:#E1E4E8">&lt;</span><span style="color:#85E89D">UButton</span><span style="color:#E1E4E8"> /&gt;</span></code>.</p>
+```
+
+## Markdown
+
+```md
+Use `Ref<HTMLInputElement | null>`{lang="ts-type"} with `<UButton />`{lang="vue-html"}.
+```
diff --git a/packages/comark/SPEC/COMARK/shiki-inline-code-plain.md b/packages/comark/SPEC/COMARK/shiki-inline-code-plain.md
new file mode 100644
index 00000000..29ab27ae
--- /dev/null
+++ b/packages/comark/SPEC/COMARK/shiki-inline-code-plain.md
@@ -0,0 +1,91 @@
+---
+timeout:
+  parse: 500ms
+  html: 5ms
+  markdown: 5ms
+options:
+  highlight:
+    themes:
+      light: 'github-dark'
+---
+
+## Input
+
+```md
+A `Bonjour`{lang="fr"} and a `const a = 1`{lang="ts"}.
+```
+
+## AST
+
+```json
+{
+  "frontmatter": {},
+  "meta": {},
+  "nodes": [
+    [
+      "p",
+      {},
+      "A ",
+      [
+        "code",
+        {
+          "lang": "fr"
+        },
+        "Bonjour"
+      ],
+      " and a ",
+      [
+        "code",
+        {
+          "lang": "ts",
+          "class": "shiki shiki-themes github-dark dark:github-dark",
+          "$": {
+            "class": ""
+          }
+        },
+        [
+          "span",
+          {
+            "style": "color:#F97583"
+          },
+          "const"
+        ],
+        [
+          "span",
+          {
+            "style": "color:#79B8FF"
+          },
+          " a"
+        ],
+        [
+          "span",
+          {
+            "style": "color:#F97583"
+          },
+          " ="
+        ],
+        [
+          "span",
+          {
+            "style": "color:#79B8FF"
+          },
+          " 1"
+        ]
+      ],
+      "."
+    ]
+  ]
+}
+```
+
+## HTML
+
+```html
+<p>A <code lang="fr">Bonjour</code> and a <code lang="ts" class="shiki shiki-themes github-dark dark:github-dark"><span style="color:#F97583">const</span><span style="color:#79B8FF"> a</span><span style="color:#F97583"> =</span><span style="color:#79B8FF"> 1</span></code>.</p>
+```
+
+## Markdown
+
+```md
+A `Bonjour`{lang="fr"} and a `const a = 1`{lang="ts"}.
+```
diff --git a/packages/comark/SPEC/COMARK/shiki-ordered-list-nested-codeblock.md b/packages/comark/SPEC/COMARK/shiki-ordered-list-nested-codeblock.md
index 8257ae0c..ddece277 100644
--- a/packages/comark/SPEC/COMARK/shiki-ordered-list-nested-codeblock.md
+++ b/packages/comark/SPEC/COMARK/shiki-ordered-list-nested-codeblock.md
@@ -41,7 +41,10 @@ options:
           "pre",
           {
             "language": "rust",
-            "class": "shiki shiki-themes github-dark dark:github-dark"
+            "class": "shiki shiki-themes github-dark dark:github-dark",
+            "$": {
+              "class": ""
+            }
           },
           [
             "code",
diff --git a/packages/comark/src/internal/shiki.ts b/packages/comark/src/internal/shiki.ts
index 62ca7d23..4e10799e 100644
--- a/packages/comark/src/internal/shiki.ts
+++ b/packages/comark/src/internal/shiki.ts
@@ -1,4 +1,4 @@
-import type { LanguageRegistration, ShikiTransformer, ShikiPrimitive, ThemeRegistration } from 'shiki'
+import type { LanguageRegistration, ShikiTransformer, ShikiPrimitive, ThemeRegistration, ThemedToken } from 'shiki'
 import type { ElementNode, Node, MarkdownDocument, ElementNodeAttributes } from 'comark'
 import { defineComarkPlugin } from '../utils/helpers.ts'
 import { createShikiPrimitive } from 'shiki'
@@ -6,6 +6,34 @@ import { createJavaScriptRegexEngine } from 'shiki/engine/javascript'
 import { codeToHast, codeToTokens, getTokenStyleObject, stringifyTokenStyle } from 'shiki/core'
 import comarkLanguages from '../plugins/shiki/language-comark.ts'
 
+/**
+ * A pseudo-language: a name authors may write in `{lang="…"}` or a fence info
+ * string, mapped onto a real Shiki grammar plus optional seed source that puts
+ * that grammar into the right state before the real code is tokenized.
+ */
+export interface ShikiGrammarContext {
+  /** Real Shiki grammar to tokenize with. Must be registered via `languages`. */
+  lang: string
+  /**
+   * Source prepended to the code purely to establish grammar state. It is
+   * tokenized and then discarded, so none of its tokens reach the output.
+   */
+  grammarContextCode?: string
+}
+
+/**
+ * Pseudo-languages Comark ships out of the box, mirroring the `@nuxtjs/mdc`
+ * conventions so `{lang="ts-type"}` and `{lang="vue-html"}` keep working for
+ * sites migrating off it. Same class of opinion as the `md`/`markdown`/`comark`
+ * to `mdc` and `json-render` to `json` aliases registered on the highlighter
+ * (see `langAlias` below). Both target languages are in the standard entry's
+ * default set, and this map is data only, so it pulls in no grammar chunk.
+ */
+export const defaultGrammarContexts: Readonly<Record<string, ShikiGrammarContext>> = {
+  'ts-type': { lang: 'typescript', grammarContextCode: 'let a:' },
+  'vue-html': { lang: 'vue', grammarContextCode: '<template>' },
+}
+
 export interface ShikiCoreOptions {
   /**
    * Languages to register. Required — core has no default language set.
@@ -32,6 +60,32 @@ export interface ShikiCoreOptions {
    * @default false
    */
   preStyles?: boolean
+
+  /**
+   * Whether to highlight inline code that declares a language, e.g.
+   * `` `Ref<T>`{lang="ts-type"} `` or `` `x`{language="ts"} ``. `lang` wins
+   * over `language`.
+   *
+   * Inline code uses the fast token path only: `transformers` and `preStyles`
+   * are block-only and are not applied. Inline code naming a grammar that is
+   * not registered is left exactly as authored, with no class and no spans, so
+   * a natural-language `lang="fr"` is never mistaken for code.
+   *
+   * @default true
+   */
+  inlineCode?: boolean
+
+  /**
+   * Pseudo-languages usable in `{lang="…"}` and in fence info strings, merged
+   * on top of {@link defaultGrammarContexts}. A registered grammar always wins,
+   * so a context only ever applies to a name that is not a real grammar.
+   *
+   * @example
+   * grammarContexts: {
+   *   'sql-expr': { lang: 'sql', grammarContextCode: 'select ' },
+   * }
+   */
+  grammarContexts?: Record<string, ShikiGrammarContext>
 }
 
 /**
@@ -230,6 +284,52 @@ function hastToNode(input: any): Node {
   return result as Node
 }
 
+/**
+ * Read the language an inline `<code>` declares. `lang` wins over `language`;
+ * `lang` is the `@nuxtjs/mdc` convention and what authors type, `language` is
+ * what the fence path already uses.
+ */
+function inlineCodeLanguage(attrs: ElementNodeAttributes): string | undefined {
+  const raw = attrs?.lang ?? attrs?.language
+  if (typeof raw !== 'string') return undefined
+  return raw.trim() || undefined
+}
+
+/**
+ * Build `<span style=…>` children for one tokenized line.
+ * Replicates shiki's `mergeWhitespaceTokens`: a pure-whitespace token merges
+ * into the following token unless it is underlined or struck through.
+ */
+function tokensToSpans(line: ThemedToken[]): Node[] {
+  const spanCount = line.length
+  let carry = ''
+  const spans: Node[] = []
+  for (let t = 0; t < spanCount; t++) {
+    const tk = line[t]
+    const canMerge = !((tk.fontStyle && (tk.fontStyle & 8 /* Strikethrough */ || tk.fontStyle & 4)) /* Underline */)
+    if (canMerge && /^\s+$/.test(tk.content) && t + 1 < spanCount) {
+      carry += tk.content
+    } else if (carry) {
+      const style = stringifyTokenStyle(tk.htmlStyle || getTokenStyleObject(tk))
+      if (canMerge) {
+        spans.push(style ? ['span', { style }, carry + tk.content] : ['span', {}, carry + tk.content])
+      } else {
+        spans.push(['span', {}, carry])
+        spans.push(style ? ['span', { style }, tk.content] : ['span', {}, tk.content])
+      }
+      carry = ''
+    } else {
+      const style = stringifyTokenStyle(tk.htmlStyle || getTokenStyleObject(tk))
+      spans.push(style ? ['span', { style }, tk.content] : ['span', {}, tk.content])
+    }
+  }
+  // If trailing whitespace wasn't merged, emit it
+  if (carry) {
+    spans.push(['span', {}, carry])
+  }
+  return spans
+}
+
 /**
  * Apply syntax highlighting to all code blocks in a Comark tree
  * Uses codeToTokens API with batched async operations
@@ -240,28 +340,54 @@ export async function highlightCodeBlocks(
   defaultThemeLoaders: ShikiThemeLoader[] = [],
   defaultLanguageLoaders: ShikiLanguageLoader[] = []
 ): Promise<MarkdownDocument> {
-  interface CodeBlockRef {
-    node: Node
+  interface CodeRef {
+    node: ElementNode
     path: number[]
+    /** Inline `<code>` with no `<pre>` wrapper. Fast token path only. */
+    inline: boolean
   }
 
-  const codeBlocks: CodeBlockRef[] = []
+  const codeBlocks: CodeRef[] = []
   const pathBuf: number[] = []
+  const inlineEnabled = options.inlineCode !== false
+
+  /**
+   * Collect a node if it is highlightable. Returns true when the node owns its
+   * whole subtree, so the caller must not descend: a matched `<pre><code>`,
+   * whose own `<code>` child is a fenced block rather than inline code.
+   */
+  const collect = (node: ElementNode, path: number[]): boolean => {
+    if (node[0] === 'pre') {
+      if (Array.isArray(node[2]) && node[2][0] === 'code' && typeof node[2][2] === 'string') {
+        codeBlocks.push({ node, path: path.slice(), inline: false })
+        return true
+      }
+      return false
+    }
+    // An already-highlighted `<code>` has element children, so `node[2]` is not
+    // a string and it is never collected twice.
+    if (inlineEnabled && node[0] === 'code' && node.length === 3 && typeof node[2] === 'string') {
+      const inlineAttrs = node[1] as ElementNodeAttributes
+      // A raw-HTML `<code lang="ts">` is authored markup, not Comark inline
+      // code. Highlighting it would turn the author's own tag into a tree of
+      // spans and break the byte-for-byte round-trip raw HTML guarantees.
+      if (inlineAttrs?.$?.html === 1) return false
+      if (inlineCodeLanguage(inlineAttrs)) {
+        codeBlocks.push({ node, path: path.slice(), inline: true })
+      }
+    }
+    return false
+  }
 
-  // Recursively find <pre><code> blocks, tracking their path via push/pop on a shared buffer
+  // Recursively find highlightable nodes, tracking their path via push/pop on a shared buffer
   const walkChildren = (element: ElementNode): void => {
     for (let i = 2; i < element.length; i++) {
       const child = element[i]
       if (typeof child === 'string') continue
       if (!Array.isArray(child) || child.length < 3) continue
       pathBuf.push(i - 2)
-      if (child[0] === 'pre' && Array.isArray(child[2]) && child[2][0] === 'code') {
-        const codeContent = child[2][2]
-        if (typeof codeContent === 'string') {
-          codeBlocks.push({ node: child, path: pathBuf.slice() })
-        }
-      }
-      walkChildren(child as ElementNode)
+      const handled = collect(child as ElementNode, pathBuf)
+      if (!handled) walkChildren(child as ElementNode)
       pathBuf.pop()
     }
   }
@@ -270,15 +396,10 @@ export async function highlightCodeBlocks(
     const node = tree.nodes[i]
     if (typeof node === 'string') continue
     if (!Array.isArray(node) || node.length < 3) continue
-    if (node[0] === 'pre' && Array.isArray(node[2]) && node[2][0] === 'code') {
-      const codeContent = node[2][2]
-      if (typeof codeContent === 'string') {
-        codeBlocks.push({ node, path: [i] })
-      }
-    }
     pathBuf.length = 1
     pathBuf[0] = i
-    walkChildren(node as ElementNode)
+    const handled = collect(node as ElementNode, pathBuf)
+    if (!handled) walkChildren(node as ElementNode)
   }
 
   if (codeBlocks.length === 0) return tree
@@ -295,14 +416,108 @@ export async function highlightCodeBlocks(
   const hasTransformers = options.transformers && options.transformers.length > 0
   const darkClassSuffix = options.themes?.dark?.name ? ` dark:${options.themes.dark.name}` : ''
 
-  // Build new nodes array, spine-copying only paths to modified <pre> nodes
+  // Built once per call. `getLoadedLanguages()` includes alias names, so the
+  // `langAlias` entries above resolve without touching the registry.
+  const loadedLangs = new Set(hl.getLoadedLanguages())
+
+  const grammarContexts: Record<string, ShikiGrammarContext> = options.grammarContexts
+    ? { ...defaultGrammarContexts, ...options.grammarContexts }
+    : defaultGrammarContexts
+
+  /**
+   * Resolve a written language name to a real grammar plus optional seed source.
+   * A registered grammar wins: shiki ships a real `vue-html` grammar, so anyone
+   * who registers it gets it instead of the built-in context that seeds `vue`.
+   * The context lookup is own-property only, so a fence written ```constructor```
+   * cannot resolve through `Object.prototype`.
+   */
+  const resolveGrammar = (language: string | undefined): ShikiGrammarContext => {
+    if (language && loadedLangs.has(language)) return { lang: language }
+    const ctx =
+      language && Object.prototype.hasOwnProperty.call(grammarContexts, language)
+        ? grammarContexts[language]
+        : undefined
+    return ctx ?? { lang: language as string }
+  }
+
+  // Build new nodes array, spine-copying only paths to modified nodes
   const newNodes = [...tree.nodes] as Node[]
+
+  /**
+   * Replace the node at `path`, copying only the spine from the root down to it
+   * so the rest of the tree stays shared. Each level reads back from `newNodes`
+   * rather than `tree.nodes`, so several replacements under a shared ancestor
+   * compose instead of clobbering each other.
+   */
+  const replaceAt = (path: number[], replacement: Node): void => {
+    if (path.length === 1) {
+      newNodes[path[0]] = replacement
+      return
+    }
+    const rootIdx = path[0]
+    let current = [...(newNodes[rootIdx] as ElementNode)] as ElementNode
+    newNodes[rootIdx] = current
+    for (let j = 1; j < path.length - 1; j++) {
+      const childSlot = path[j] + 2
+      const next = [...(current[childSlot] as ElementNode)] as ElementNode
+      current[childSlot] = next
+      current = next
+    }
+    current[path[path.length - 1] + 2] = replacement
+  }
+
   for (let i = 0; i < codeBlocks.length; i++) {
-    const { node, path } = codeBlocks[i]
+    const { node, path, inline } = codeBlocks[i]
+
+    if (inline) {
+      const inlineAttrs = node[1] as ElementNodeAttributes
+      const inlineCode = node[2] as string
+      const { lang, grammarContextCode } = resolveGrammar(inlineCodeLanguage(inlineAttrs))
+
+      // Unlike a <pre>, an inline <code> is not unambiguously code: `lang` is a
+      // real HTML attribute for natural language. When the grammar is not
+      // registered, leave the node exactly as it was authored rather than
+      // tagging it `.shiki`.
+      if (!lang || !loadedLangs.has(lang)) continue
+
+      let spans: Node[]
+      let inlineClass: string
+      try {
+        const result = codeToTokens(hl, inlineCode, { lang, grammarContextCode, themes: themeOptions })
+        spans = []
+        for (let li = 0; li < result.tokens.length; li++) {
+          if (li > 0) spans.push('\n')
+          for (const span of tokensToSpans(result.tokens[li])) spans.push(span)
+        }
+        if (spans.length === 0) spans = [inlineCode]
+        inlineClass = `shiki ${result.themeName || ''}${darkClassSuffix}`
+      } catch {
+        continue
+      }
+
+      // `class` is the full string renderers need. The author's own class is
+      // recorded in the reserved `$` metadata so markdown stringify can put
+      // back exactly what was written, and nothing else.
+      const inlineUserClass = typeof inlineAttrs.class === 'string' ? inlineAttrs.class.trim() : ''
+      // eslint-disable-next-line unicorn/no-new-array -- pre-allocated for perf
+      const inlineNode = new Array(spans.length + 2) as ElementNode
+      inlineNode[0] = 'code'
+      inlineNode[1] = {
+        ...inlineAttrs,
+        class: inlineUserClass ? `${inlineClass} ${inlineUserClass}` : inlineClass,
+        $: { ...inlineAttrs.$, class: inlineUserClass },
+      }
+      for (let sp = 0; sp < spans.length; sp++) inlineNode[sp + 2] = spans[sp]
+
+      replaceAt(path, inlineNode as Node)
+      continue
+    }
+
     const code = (node[2] as any)[2] as string
     const attrs = node[1] as CodeBlockAttributes
     const preAttrs = attrs as Record<string, any>
     const language: string = (attrs as any)?.language
+    const { lang: fenceLang, grammarContextCode: fenceContext } = resolveGrammar(language)
 
     let classStr: string
     let codeChildren: Node[]
@@ -311,7 +526,8 @@ export async function highlightCodeBlocks(
       if (hasTransformers) {
         // Transformers operate on hast, so we must go through codeToHast
         const result = codeToHast(hl, code, {
-          lang: language,
+          lang: fenceLang,
+          grammarContextCode: fenceContext,
           transformers: options.transformers,
           themes: themeOptions,
           meta: { __raw: attrs.meta },
@@ -323,7 +539,8 @@ export async function highlightCodeBlocks(
       } else {
         // Fast path: build Nodes directly from tokens, skipping hast
         const result = codeToTokens(hl, code, {
-          lang: language,
+          lang: fenceLang,
+          grammarContextCode: fenceContext,
           themes: themeOptions,
         })
         classStr = `shiki ${result.themeName || ''}`
@@ -333,37 +550,7 @@ export async function highlightCodeBlocks(
         const tokenLines = result.tokens
         codeChildren = []
         for (let li = 0; li < tokenLines.length; li++) {
-          const line = tokenLines[li]
-          const spanCount = line.length
-
-          // Merge whitespace tokens inline while building spans
-          let carry = ''
-          const spans: Node[] = []
-          for (let t = 0; t < spanCount; t++) {
-            const tk = line[t]
-            const canMerge = !(
-              (tk.fontStyle && (tk.fontStyle & 8 /* Strikethrough */ || tk.fontStyle & 4)) /* Underline */
-            )
-            if (canMerge && /^\s+$/.test(tk.content) && t + 1 < spanCount) {
-              carry += tk.content
-            } else if (carry) {
-              const style = stringifyTokenStyle(tk.htmlStyle || getTokenStyleObject(tk))
-              if (canMerge) {
-                spans.push(style ? ['span', { style }, carry + tk.content] : ['span', {}, carry + tk.content])
-              } else {
-                spans.push(['span', {}, carry])
-                spans.push(style ? ['span', { style }, tk.content] : ['span', {}, tk.content])
-              }
-              carry = ''
-            } else {
-              const style = stringifyTokenStyle(tk.htmlStyle || getTokenStyleObject(tk))
-              spans.push(style ? ['span', { style }, tk.content] : ['span', {}, tk.content])
-            }
-          }
-          // If trailing whitespace wasn't merged, emit it
-          if (carry) {
-            spans.push(['span', {}, carry])
-          }
+          const spans = tokensToSpans(tokenLines[li])
 
           // eslint-disable-next-line unicorn/no-new-array -- pre-allocated for perf
           const lineNode = new Array(spans.length + 2) as ElementNode
@@ -402,12 +589,15 @@ export async function highlightCodeBlocks(
       }
     }
 
-    // Merge highlighter class with any user-supplied class (e.g. from
-    // `::pre{.user-class}`) so the wrapper's class isn't lost.
+    // Merge the highlighter class with any user-supplied class (e.g. from
+    // `::pre{.user-class}`) so the wrapper's class isn't lost, and record the
+    // user portion in the reserved `$` metadata so markdown stringify can
+    // recover it without guessing which tokens came from where.
     const userClass = typeof preAttrs.class === 'string' ? preAttrs.class.trim() : ''
     const newPreAttrs: Record<string, any> = {
       ...preAttrs,
-      class: userClass ? `${classStr} . ${userClass}` : classStr,
+      class: userClass ? `${classStr} ${userClass}` : classStr,
+      $: { ...preAttrs.$, class: userClass },
     }
 
     if (options.preStyles) {
@@ -441,22 +631,7 @@ export async function highlightCodeBlocks(
     for (let j = 0; j < codeChildren.length; j++) codeNode[j + 2] = codeChildren[j]
     const newPreNode: Node = ['pre', newPreAttrs, codeNode]
 
-    if (path.length === 1) {
-      newNodes[path[0]] = newPreNode
-    } else {
-      // Copy only the spine from root to this node to preserve immutability
-      const rootIdx = path[0]
-      let current = [...(newNodes[rootIdx] as ElementNode)] as ElementNode
-      newNodes[rootIdx] = current
-      for (let j = 1; j < path.length - 1; j++) {
-        const childSlot = path[j] + 2
-        const next = [...(current[childSlot] as ElementNode)] as ElementNode
-        current[childSlot] = next
-        current = next
-      }
-      const childSlot = path[path.length - 1] + 2
-      current[childSlot] = newPreNode
-    }
+    replaceAt(path, newPreNode)
   }
 
   return { ...tree, nodes: newNodes }
diff --git a/packages/comark/src/internal/stringify/attributes.ts b/packages/comark/src/internal/stringify/attributes.ts
index 557cf70f..22d99ac0 100644
--- a/packages/comark/src/internal/stringify/attributes.ts
+++ b/packages/comark/src/internal/stringify/attributes.ts
@@ -132,9 +132,9 @@ const IMPLICIT_ATTRS: Record<string, { drop?: string[]; classBlocklist?: string[
   li: { classBlocklist: ['task-list-item'] },
   // `language`/`filename`/`highlights`/`meta` ride on the fence info string.
   // `style` comes from render-time plugins (e.g. shiki / rangi) and has no
-  // markdown form. `class` is handled specially in userBlockAttrs because
-  // highlighters merge their injected classes with the user's class — we need
-  // to strip just the highlighter portion.
+  // markdown form. `class` is handled separately in userBlockAttrs, which reads
+  // the author's own class back out of `$` when a highlighter has taken the
+  // `class` attribute over.
   pre: { drop: ['language', 'filename', 'highlights', 'meta', 'style'] },
 }
 
@@ -146,35 +146,31 @@ const IMPLICIT_ATTRS: Record<string, { drop?: string[]; classBlocklist?: string[
  */
 export function userBlockAttrs(tag: string, attributes: Record<string, unknown>): Record<string, unknown> {
   const rule = IMPLICIT_ATTRS[tag]
-  if (!rule) return { ...attributes }
+  // A highlighter owns the `class` of a `<pre>` (fenced block) or an inline
+  // `<code>`, and records the author's own class in `$`. When that record is
+  // there it is the whole truth: the user class is exactly its value, and an
+  // empty string means the author wrote none. Without it, `class` was authored
+  // and passes through untouched.
+  const recordedClass =
+    tag === 'pre' || tag === 'code' ? (attributes.$ as { class?: string } | undefined)?.class : undefined
 
   const result: Record<string, unknown> = {}
   for (const [key, value] of Object.entries(attributes)) {
-    if (rule.drop?.includes(key)) continue
-    if (key === 'class' && rule.classBlocklist && typeof value === 'string') {
+    // `$` is reserved metadata, never a user attribute.
+    if (key === '$') continue
+    if (rule?.drop?.includes(key)) continue
+    if (key === 'class' && recordedClass !== undefined) {
+      if (recordedClass) result[key] = recordedClass
+      continue
+    }
+    if (key === 'class' && rule?.classBlocklist && typeof value === 'string') {
       const remaining = value
         .split(/\s+/)
-        .filter((c) => c && !rule.classBlocklist!.includes(c))
+        .filter((c) => c && !rule!.classBlocklist!.includes(c))
         .join(' ')
       if (remaining) result[key] = remaining
       continue
     }
-    if (
-      key === 'class' &&
-      tag === 'pre' &&
-      typeof value === 'string' &&
-      (value.startsWith('shiki') || value.startsWith('shj'))
-    ) {
-      // Highlighters inject their own classes (`shiki …` / `shj shj-lang-…`)
-      // and append any user class after a `.` separator. Recover the user
-      // portion by dropping everything up to and including that separator.
-      const tokens = value.split(/\s+/)
-      const cutoff = tokens.findIndex((t) => t === '.')
-
-      const userClass = cutoff >= 0 ? tokens.slice(cutoff + 1).join(' ') : ''
-      if (userClass) result[key] = userClass
-      continue
-    }
     result[key] = value
   }
   return result
@@ -188,6 +184,9 @@ export function userBlockAttrs(tag: string, attributes: Record<string, unknown>)
  */
 export function comarkAttributes(attributes: Record<string, unknown>) {
   const attrs = Object.entries(attributes)
+    // `$` holds internal metadata (source line, raw-HTML markers, the class a
+    // highlighter took over). It has no markdown form and must never round-trip.
+    .filter(([key]) => key !== '$')
     .map(([key, value]) => {
       if (key.startsWith(':') && value === 'true') {
         return key.slice(1)
@@ -242,6 +241,8 @@ export function htmlAttributes(attributes: Record<string, unknown>) {
   const parts: string[] = []
   for (const [rawKey, value] of Object.entries(attributes)) {
     const key = rawKey.startsWith(':') ? rawKey.slice(1) : rawKey
+    // `$` is reserved metadata and has no HTML form. `SAFE_ATTR_NAME` already
+    // rejects it, so callers that forward raw attributes stay safe.
     if (!SAFE_ATTR_NAME.test(key)) continue
 
     if (rawKey.startsWith(':')) {
diff --git a/packages/comark/src/internal/stringify/handlers/code.ts b/packages/comark/src/internal/stringify/handlers/code.ts
index fec315fb..bc3c048e 100644
--- a/packages/comark/src/internal/stringify/handlers/code.ts
+++ b/packages/comark/src/internal/stringify/handlers/code.ts
@@ -1,10 +1,14 @@
 import type { State } from 'comark/render'
 import type { ElementNode } from 'comark'
-import { comarkAttributes } from '../attributes.ts'
+import { comarkAttributes, userBlockAttrs } from '../attributes.ts'
 import { textContent } from '../../../utils/index.ts'
 
 export function code(node: ElementNode, _state: State) {
-  const [_, attrs] = node
+  const [_, attributes] = node
+  // The shiki plugin owns the `class` of highlighted inline code and records the
+  // author's own class in `$`, so the node round-trips as `` `text`{lang=…} ``
+  // instead of leaking `.shiki.shiki-themes…`.
+  const attrs = userBlockAttrs('code', attributes as Record<string, unknown>)
   const attrsString = Object.keys(attrs).length > 0 ? comarkAttributes(attrs) : ''
   const content = textContent(node)
   const fence = content.includes('`') ? '``' : '`'
diff --git a/packages/comark/src/plugins/rangi.ts b/packages/comark/src/plugins/rangi.ts
index 2ce91c4b..dcc63089 100644
--- a/packages/comark/src/plugins/rangi.ts
+++ b/packages/comark/src/plugins/rangi.ts
@@ -1,4 +1,4 @@
-import type { ElementNode, Node, MarkdownDocument } from 'comark'
+import type { ElementNode, ElementNodeAttributes, Node, MarkdownDocument } from 'comark'
 import type { ShjLanguage, ShjLanguages, ShjTheme, ShjThemePair, ShjToken, ShjTokenized } from 'rangi'
 import { tokenize } from 'rangi'
 import { dark as defaultDark, defaultTheme } from 'rangi/themes'
@@ -83,6 +83,7 @@ export interface CodeBlockAttributes {
   highlights?: number[]
   meta?: string
   filename?: string
+  $?: ElementNodeAttributes['$']
 }
 
 /**
@@ -303,9 +304,16 @@ export async function rangiCodeBlocks(tree: MarkdownDocument, options: RangiOpti
       const userClass = typeof attrs.class === 'string' ? attrs.class.trim() : ''
       // `shiki` so dual-theme CSS hooks shared with the Shiki plugin work
       const highlighterClass = `${classPrefix} shiki shj-lang-${lang}`
-      const classStr = userClass ? `${highlighterClass} . ${userClass}` : highlighterClass
-
-      const newPreAttrs: Record<string, unknown> = { ...attrs, class: classStr }
+      const classStr = userClass ? `${highlighterClass} ${userClass}` : highlighterClass
+
+      // `class` is the full string renderers need. The author's own class goes
+      // in the reserved `$` metadata so markdown stringify can put back exactly
+      // what was written.
+      const newPreAttrs: Record<string, unknown> = {
+        ...attrs,
+        class: classStr,
+        $: { ...attrs.$, class: userClass },
+      }
       if (preStyles) {
         const style = buildPreStyle(light, dark, dual)
         if (style) newPreAttrs.style = style
diff --git a/packages/comark/src/plugins/shiki.ts b/packages/comark/src/plugins/shiki.ts
index 06ad459c..9ee54245 100644
--- a/packages/comark/src/plugins/shiki.ts
+++ b/packages/comark/src/plugins/shiki.ts
@@ -9,6 +9,7 @@ import {
 
 export type {
   CodeBlockAttributes,
+  ShikiGrammarContext,
   HighlightOptions,
   ShikiCoreOptions,
   ShikiLanguageLoader,
diff --git a/packages/comark/src/plugins/shiki/core.ts b/packages/comark/src/plugins/shiki/core.ts
index 2bf5406a..c3b25444 100644
--- a/packages/comark/src/plugins/shiki/core.ts
+++ b/packages/comark/src/plugins/shiki/core.ts
@@ -10,6 +10,7 @@ import {
 
 export type {
   CodeBlockAttributes,
+  ShikiGrammarContext,
   HighlightOptions,
   ShikiCoreOptions,
   ShikiLanguageLoader,
diff --git a/packages/comark/src/types.ts b/packages/comark/src/types.ts
index 50ceeae9..1aa34acf 100644
--- a/packages/comark/src/types.ts
+++ b/packages/comark/src/types.ts
@@ -28,6 +28,13 @@ export type ElementNodeAttributes = {
     line?: number
     html?: 0 | 1
     block?: 0 | 1
+    /**
+     * The author's own `class` on a node whose `class` a highlighter has since
+     * taken over (`<pre>` and inline `<code>`). Empty string when the author
+     * wrote none. Markdown stringify puts back exactly this value, so the
+     * combined `class` that renderers need is never taken apart again.
+     */
+    class?: string
   }
 }
 
diff --git a/packages/comark/test/plugins/rangi.test.ts b/packages/comark/test/plugins/rangi.test.ts
index 49e56fc9..7a688526 100644
--- a/packages/comark/test/plugins/rangi.test.ts
+++ b/packages/comark/test/plugins/rangi.test.ts
@@ -257,7 +257,7 @@ describe('rangi plugin', () => {
     expect(textOf(pre)).toBe('const a = 1\nconst b = 2\nconst c = 3')
   })
 
-  it('preserves user class after the `.` separator', async () => {
+  it('keeps the user class and records it in $', async () => {
     const document: MarkdownDocument = {
       frontmatter: {},
       meta: {},
@@ -266,7 +266,8 @@ describe('rangi plugin', () => {
 
     const tree = await rangiCodeBlocks(document)
     const pre = tree.nodes[0] as ElementNode
-    expect((pre[1] as any).class).toBe('shj shiki shj-lang-js . my-block')
+    expect((pre[1] as any).class).toBe('shj shiki shj-lang-js my-block')
+    expect((pre[1] as any).$.class).toBe('my-block')
   })
 
   it('uses plain for fences with no language', async () => {
@@ -369,22 +370,29 @@ const x = 1
 })
 
 describe('rangi code block round-trip', () => {
-  function preTree(preClass: string): MarkdownDocument {
+  // `$.class` is what the plugin records: the author's own class, verbatim.
+  function preTree(preClass: string, userClass: string): MarkdownDocument {
     return {
       frontmatter: {},
       meta: {},
-      nodes: [['pre', { language: 'bash', class: preClass }, ['code', { class: 'language-bash' }, 'npx install']]],
+      nodes: [
+        [
+          'pre',
+          { language: 'bash', class: preClass, $: { class: userClass } },
+          ['code', { class: 'language-bash' }, 'npx install'],
+        ],
+      ],
     }
   }
 
   it('serializes a bare `shj` class back to a plain fence', async () => {
-    const md = await renderMarkdown(preTree('shj shiki shj-lang-bash'))
+    const md = await renderMarkdown(preTree('shj shiki shj-lang-bash', ''))
     expect(md.trim()).toBe('```bash\nnpx install\n```')
     expect(md).not.toContain('::pre')
   })
 
-  it('serializes a highlighted block with user class via `.` separator', async () => {
-    const md = await renderMarkdown(preTree('shj shiki shj-lang-bash . my-block'))
+  it('serializes a highlighted block with a user class recorded in $', async () => {
+    const md = await renderMarkdown(preTree('shj shiki shj-lang-bash my-block', 'my-block'))
     expect(md).toContain('my-block')
     expect(md).not.toContain('shj-lang')
     expect(md).toContain('npx install')
diff --git a/packages/comark/test/plugins/shiki-inline.test.ts b/packages/comark/test/plugins/shiki-inline.test.ts
new file mode 100644
index 00000000..3d66961e
--- /dev/null
+++ b/packages/comark/test/plugins/shiki-inline.test.ts
@@ -0,0 +1,172 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import javascript from 'shiki/dist/langs/javascript.mjs'
+import vueHtml from 'shiki/dist/langs/vue-html.mjs'
+import githubDark from 'shiki/dist/themes/github-dark.mjs'
+import { parseMarkdown } from '../../src/index'
+import { renderMarkdown } from '../../src/render'
+import type { ComarkPlugin, ElementNode, Node } from '../../src/types'
+import shiki from '../../src/plugins/shiki'
+import shikiCore, { resetHighlighter } from '../../src/plugins/shiki/core'
+import type { ShikiOptions } from '../../src/plugins/shiki'
+
+afterEach(resetHighlighter)
+
+async function inlineCode(source: string, options: ShikiOptions = {}): Promise<ElementNode> {
+  const document = await parseMarkdown(source, { plugins: [shiki(options)] })
+  return (document.nodes[0] as ElementNode)[2] as ElementNode
+}
+
+/** Collect every `style` on the node's span children, in order. */
+function styles(node: ElementNode): string[] {
+  return (node.slice(2) as Node[])
+    .filter((child): child is ElementNode => Array.isArray(child))
+    .map((child) => String((child[1] as Record<string, unknown>).style ?? ''))
+}
+
+describe('shiki inline code', () => {
+  it('highlights inline code carrying a lang attribute', async () => {
+    const code = await inlineCode('`const a = 1`{lang="ts"}')
+
+    expect(code[0]).toBe('code')
+    expect(String((code[1] as Record<string, unknown>).class)).toMatch(/^shiki /)
+    expect(code.length).toBeGreaterThan(3)
+    expect(styles(code).some(Boolean)).toBe(true)
+  })
+
+  it('accepts `language` as well as `lang`', async () => {
+    const code = await inlineCode('`const a = 1`{language="ts"}')
+    expect(String((code[1] as Record<string, unknown>).class)).toMatch(/^shiki /)
+  })
+
+  it('prefers `lang` when both are present', async () => {
+    const both = await inlineCode('`Ref<T>`{lang="ts-type" language="ts"}')
+    const asType = await inlineCode('`Ref<T>`{lang="ts-type"}')
+    expect(styles(both)).toEqual(styles(asType))
+  })
+
+  describe('built-in grammar contexts', () => {
+    it('tokenizes ts-type as a type expression, not a plain statement', async () => {
+      const asType = await inlineCode('`Ref<T>`{lang="ts-type"}', { themes: { dark: githubDark } })
+      const asStatement = await inlineCode('`Ref<T>`{lang="ts"}', { themes: { dark: githubDark } })
+
+      // Without the `let a:` seed, `Ref` falls through to plain text.
+      expect(styles(asType)).not.toEqual(styles(asStatement))
+      expect(styles(asType)[0]).toContain('#B392F0')
+      expect(styles(asStatement)[0]).toContain('#E1E4E8')
+    })
+
+    it('merges custom contexts over the built-ins', async () => {
+      const custom = await inlineCode('`Ref<T>`{lang="ts-type"}', {
+        grammarContexts: { 'sql-expr': { lang: 'sql' } },
+      })
+      expect(String((custom[1] as Record<string, unknown>).class)).toMatch(/^shiki /)
+    })
+
+    it('lets a registered grammar win over a built-in context', async () => {
+      const plugin = shikiCore({ languages: [vueHtml], themes: { dark: githubDark } })
+      const document = await parseMarkdown('`<b/>`{lang="vue-html"}', { plugins: [plugin] })
+      const code = (document.nodes[0] as ElementNode)[2] as ElementNode
+
+      // The built-in context would route `vue-html` through the `vue` grammar
+      // seeded with `<template>`, which is not registered here. Highlighting at
+      // all proves the real grammar was used.
+      expect(String((code[1] as Record<string, unknown>).class)).toMatch(/^shiki /)
+      expect(styles(code).some(Boolean)).toBe(true)
+    })
+  })
+
+  describe('left untouched', () => {
+    it('leaves inline code with no language alone', async () => {
+      const code = await inlineCode('`plain`')
+      expect(code).toEqual(['code', {}, 'plain'])
+    })
+
+    it('leaves inline code alone when inlineCode is false', async () => {
+      const code = await inlineCode('`const a = 1`{lang="ts"}', { inlineCode: false })
+      expect(code).toEqual(['code', { lang: 'ts' }, 'const a = 1'])
+    })
+  })
+
+  describe('core entry with an unregistered grammar', () => {
+    it('leaves the node alone and keeps working afterwards', async () => {
+      const plugin = shikiCore({ languages: [javascript], themes: { dark: githubDark } })
+
+      const first = await parseMarkdown('`Ref<T>`{lang="ts-type"}', { plugins: [plugin] })
+      expect((first.nodes[0] as ElementNode)[2]).toEqual(['code', { lang: 'ts-type' }, 'Ref<T>'])
+
+      // A failed lookup must not poison the shared highlighter.
+      const second = await parseMarkdown('```js\nconst a = 1\n```', { plugins: [plugin] })
+      const pre = second.nodes[0] as ElementNode
+      expect(String((pre[1] as Record<string, unknown>).class)).toContain('shiki')
+      expect(Array.isArray((pre[2] as ElementNode)[2])).toBe(true)
+    })
+  })
+
+  describe('interaction with fenced blocks', () => {
+    it('does not treat a fenced block inner code as inline', async () => {
+      const document = await parseMarkdown('```ts\nconst a = 1\n```', { plugins: [shiki()] })
+      const pre = document.nodes[0] as ElementNode
+      expect((pre[2] as ElementNode)[1]).toEqual({ class: 'language-ts' })
+    })
+
+    it('resolves a pseudo-language on a fence too', async () => {
+      const document = await parseMarkdown('```ts-type\nRef<T>\n```', { plugins: [shiki()] })
+      const pre = document.nodes[0] as ElementNode
+      // The written language stays on the <pre> so the fence round-trips.
+      expect((pre[1] as Record<string, unknown>).language).toBe('ts-type')
+      expect(String((pre[1] as Record<string, unknown>).class)).toContain('shiki')
+    })
+
+    it('leaves untouched sibling nodes referentially identical', async () => {
+      // Plugins run in registration order, so this captures the nodes shiki is
+      // about to see. Only the paragraph holding the inline code may be
+      // re-created; its siblings must come out as the very same arrays.
+      let before: Node[] = []
+      const capture: ComarkPlugin = {
+        name: 'capture',
+        post(state) {
+          before = [...state.tree.nodes]
+        },
+      }
+
+      const document = await parseMarkdown('# Heading\n\nSome `x`{lang="ts"} text\n\nUntouched', {
+        plugins: [capture, shiki()],
+      })
+
+      expect(before).toHaveLength(3)
+      expect(document.nodes[0]).toBe(before[0])
+      expect(document.nodes[2]).toBe(before[2])
+      expect(document.nodes[1]).not.toBe(before[1])
+    })
+  })
+
+  it('keeps a user class behind the highlighter classes', async () => {
+    const code = await inlineCode('`x`{lang="ts" .foo}')
+    const attrs = code[1] as Record<string, any>
+    expect(String(attrs.class)).toMatch(/^shiki .* foo$/)
+    expect(attrs.$.class).toBe('foo')
+  })
+
+  it('records an empty author class when none was written', async () => {
+    const code = await inlineCode('`x`{lang="ts"}')
+    expect((code[1] as Record<string, any>).$.class).toBe('')
+  })
+
+  describe('raw HTML', () => {
+    // A raw-HTML `<code lang="ts">` is the author's own markup. Highlighting it
+    // would replace the text with spans and break the byte-for-byte round-trip.
+    const source = 'A <code lang="ts">const a = 1</code> here'
+
+    it('leaves a raw-HTML code element untouched', async () => {
+      const withPlugin = await parseMarkdown(source, { plugins: [shiki()] })
+      const withoutPlugin = await parseMarkdown(source)
+
+      expect(withPlugin.nodes).toEqual(withoutPlugin.nodes)
+    })
+
+    it('round-trips the source unchanged', async () => {
+      const document = await parseMarkdown(source, { plugins: [shiki()] })
+      expect(await renderMarkdown(document)).toBe(source)
+    })
+  })
+})
diff --git a/packages/comark/test/plugins/shiki.test.ts b/packages/comark/test/plugins/shiki.test.ts
index 53d84b1a..467b92bc 100644
--- a/packages/comark/test/plugins/shiki.test.ts
+++ b/packages/comark/test/plugins/shiki.test.ts
@@ -1,15 +1,24 @@
 import { describe, expect, it } from 'vitest'
 import type { MarkdownDocument } from '../../src/types'
 import { renderMarkdown } from '../../src/render'
+import { parseMarkdown } from '../../src/index'
+import shiki from '../../src/plugins/shiki'
 
 describe('shiki code block round-trip', () => {
   // The highlight plugin's injected attrs have no markdown form, so a
   // highlighted block must serialize to a plain fence, never a `::pre{...}`.
+  // `$.class` is what the plugin records: the author's own class, empty here.
   function preTree(preClass: string): MarkdownDocument {
     return {
       frontmatter: {},
       meta: {},
-      nodes: [['pre', { language: 'bash', class: preClass }, ['code', { class: 'language-bash' }, 'npx install']]],
+      nodes: [
+        [
+          'pre',
+          { language: 'bash', class: preClass, $: { class: '' } },
+          ['code', { class: 'language-bash' }, 'npx install'],
+        ],
+      ],
     }
   }
 
@@ -38,7 +47,11 @@ describe('shiki code block round-trip', () => {
           [
             'template',
             { name: 'code' },
-            ['pre', { language: 'bash', class: 'shiki' }, ['code', { class: 'language-bash' }, 'npx install']],
+            [
+              'pre',
+              { language: 'bash', class: 'shiki', $: { class: '' } },
+              ['code', { class: 'language-bash' }, 'npx install'],
+            ],
           ],
         ],
       ],
@@ -48,3 +61,104 @@ describe('shiki code block round-trip', () => {
     expect(md).toContain('```bash\nnpx install\n```')
   })
 })
+
+describe('shiki inline code round-trip', () => {
+  // The plugin takes the node's `class` over and records the author's own class
+  // in `$`, so a highlighted span serializes back to `` `text`{lang=…} `` rather
+  // than leaking `.shiki.shiki-themes…`.
+  function inlineTree(codeClass: string, userClass: string): MarkdownDocument {
+    return {
+      frontmatter: {},
+      meta: {},
+      nodes: [
+        [
+          'p',
+          {},
+          'Type ',
+          [
+            'code',
+            { lang: 'ts-type', class: codeClass, $: { class: userClass } },
+            ['span', { style: 'color:#B392F0' }, 'Ref'],
+            ['span', { style: 'color:#E1E4E8' }, '<T>'],
+          ],
+        ],
+      ],
+    }
+  }
+
+  it('puts back the class recorded in $', async () => {
+    const md = await renderMarkdown(inlineTree('shiki shiki-themes github-dark foo', 'foo'))
+    expect(md).toBe('Type `Ref<T>`{lang="ts-type" .foo}')
+    expect(md).not.toContain('.shiki')
+  })
+
+  it('drops the class entirely when the author wrote none', async () => {
+    const md = await renderMarkdown(inlineTree('shiki shiki-themes github-dark', ''))
+    expect(md).toBe('Type `Ref<T>`{lang="ts-type"}')
+  })
+
+  it('round-trips a parsed document unchanged', async () => {
+    const source = 'Mix `a`{lang="ts-type"} and `<b />`{lang="vue-html"} and `plain` here'
+    const document = await parseMarkdown(source, { plugins: [shiki()] })
+    expect(await renderMarkdown(document)).toBe(source)
+  })
+})
+
+describe('user class recorded in $', () => {
+  // Stringify never inspects the class string. `$.class` is the author's class
+  // verbatim, so anything a highlighter injected is dropped and anything the
+  // author wrote is kept, whatever it is named.
+  function render(node: MarkdownDocument['nodes'][number]) {
+    return renderMarkdown({ frontmatter: {}, meta: {}, nodes: [node] })
+  }
+
+  it('serializes a highlighted block with no user class as a plain fence', async () => {
+    const md = await render(['pre', { language: 'ts', class: 'shiki themes', $: { class: '' } }, ['code', {}, 'x']])
+    expect(md.trim()).toBe('```ts\nx\n```')
+  })
+
+  it('keeps the user class on a highlighted block', async () => {
+    const md = await render([
+      'pre',
+      { language: 'ts', class: 'shiki themes foo', $: { class: 'foo' } },
+      ['code', {}, 'x'],
+    ])
+    expect(md.trim()).toBe('::pre{.foo}\n```ts\nx\n```\n::')
+  })
+
+  it('keeps the user class on highlighted inline code', async () => {
+    const md = await render(['p', {}, ['code', { lang: 'ts', class: 'shiki themes foo', $: { class: 'foo' } }, 'x']])
+    expect(md).toBe('`x`{lang="ts" .foo}')
+  })
+
+  it('leaves an authored `.shiki` on unhighlighted inline code alone', async () => {
+    expect(await render(['p', {}, ['code', { class: 'shiki' }, 'x']])).toBe('`x`{.shiki}')
+    // Multi-class attrs always stringify without separators, highlighter or not.
+    expect(await render(['p', {}, ['code', { class: 'shiki foo' }, 'x']])).toBe('`x`{.shiki.foo}')
+  })
+
+  it('leaves an authored class that starts with a highlighter prefix alone', async () => {
+    expect(await render(['pre', { language: 'ts', class: 'shiki-custom' }, ['code', {}, 'x']])).toContain(
+      '::pre{.shiki-custom}'
+    )
+    expect(await render(['p', {}, ['code', { lang: 'ts', class: 'shj-custom' }, 'x']])).toBe(
+      '`x`{lang="ts" .shj-custom}'
+    )
+  })
+
+  it('serializes rangi output as a plain fence, whatever the class prefix', async () => {
+    expect(
+      await render(['pre', { language: 'ts', class: 'shj shiki shj-lang-ts', $: { class: '' } }, ['code', {}, 'x']])
+    ).not.toContain('::pre')
+    expect(
+      await render(['pre', { language: 'ts', class: 'myhl shiki shj-lang-ts', $: { class: '' } }, ['code', {}, 'x']])
+    ).not.toContain('::pre')
+  })
+
+  it('round-trips an authored `.shiki` through the plugin', async () => {
+    for (const source of ['`x`{.shiki}', '`x`{.shiki.foo}', '`x`{.shiki-custom}']) {
+      const document = await parseMarkdown(source, { plugins: [shiki()] })
+      expect(await renderMarkdown(document)).toBe(source)
+    }
+  })
+})
diff --git a/packages/comark/test/resolve-attributes.test.ts b/packages/comark/test/resolve-attributes.test.ts
index bab8b0b2..a804b75b 100644
--- a/packages/comark/test/resolve-attributes.test.ts
+++ b/packages/comark/test/resolve-attributes.test.ts
@@ -63,6 +63,15 @@ describe('resolveAttributes (default / preserve mode)', () => {
     const result = resolveAttributes({ $: { line: 3 }, type: 'info' }, makeRenderData())
     expect(result).toEqual({ type: 'info' })
   })
+
+  // A highlighter keeps `class` as the full string renderers need and records
+  // the author's own class in `$`. Framework renderers spread this result onto a
+  // real element, so `class` passes through verbatim and `$` never comes along.
+  it('passes a highlighter class through and leaves $ behind', () => {
+    const result = resolveAttributes({ class: 'shiki x foo', $: { class: 'foo' } }, makeRenderData())
+    expect(result).toEqual({ class: 'shiki x foo' })
+    expect(result).not.toHaveProperty('$')
+  })
 })
 
 describe('resolveAttributes (parseJson mode)', () => {
diff --git a/packages/comark/test/streaming.test.ts b/packages/comark/test/streaming.test.ts
index fa7956ca..1eaf0d56 100644
--- a/packages/comark/test/streaming.test.ts
+++ b/packages/comark/test/streaming.test.ts
@@ -1,9 +1,22 @@
 import { describe, it, expect } from 'vitest'
 import { createMarkdownParser } from 'comark'
+import { renderMarkdown } from 'comark/render'
 import type { ElementNode } from 'comark'
 
 describe('streaming mode', () => {
   describe('$.line metadata', () => {
+    it('does not leak into rendered markdown', async () => {
+      // `$` is reserved metadata. `comarkAttributes` used to serialise it as an
+      // attribute, so a streaming parse round-tripped as `# Title {$="…"}` and
+      // forced blocks into the `::tag{…}` wrapper form.
+      const parse = createMarkdownParser()
+      const source = '# Title\n\n- a\n- b\n\n```ts\nlet a = 1\n```'
+      const document = await parse(source, { streaming: true })
+
+      expect((document.nodes[0] as ElementNode)[1].$).toEqual({ line: 1 })
+      expect(await renderMarkdown(document)).toBe(source)
+    })
+
     it('preserves position metadata on nodes in streaming mode', async () => {
       const parse = createMarkdownParser()
       const result = await parse('# Hello\n\nParagraph one.\n\nParagraph two.\n', { streaming: true })
diff --git a/test/bundle.test.ts b/test/bundle.test.ts
index 6513ed58..7bef53b8 100644
--- a/test/bundle.test.ts
+++ b/test/bundle.test.ts
@@ -67,7 +67,7 @@ describe('package bundle size', { timeout: 60_000 }, () => {
         "@comark/react": "36.8k (74 files)",
         "@comark/svelte": "43.9k (82 files)",
         "@comark/vue": "54.7k (78 files)",
-        "comark": "364k (158 files)",
+        "comark": "370k (158 files)",
       }
     `)
   })