@peaceroad/markdown-it-renderer-fence 0.8.0 → 0.9.0

package/README.md

@@ -76,6 +76,8 @@ const md = MarkdownIt({
 | `@peaceroad/markdown-it-renderer-fence/custom-highlight-runtime` | browser runtime only (`applyCustomHighlights`, `observeCustomHighlights`, `clearCustomHighlights`) |
 | `@peaceroad/markdown-it-renderer-fence/theme/rf-basic` | color preset Shiki theme object and API provider helpers |
 | `@peaceroad/markdown-it-renderer-fence/theme/rf-basic.css` | complete color preset CSS |
+| `@peaceroad/markdown-it-renderer-fence/theme/line-number.css` | theme-neutral line-number layout CSS |
+| `@peaceroad/markdown-it-renderer-fence/theme/line-notes.css` | theme-neutral line-notes layout CSS |
 | `@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome` | one-color Shiki markup theme object |
 | `@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome.css` | complete one-color markup preset CSS |
 
@@ -83,6 +85,8 @@ Use `@peaceroad/markdown-it-renderer-fence/theme/rf-basic` for JavaScript helper
 
 Split preset CSS is also available:
 
+- `theme/line-number.css`
+- `theme/line-notes.css`
 - `theme/rf-basic/base.css`
 - `theme/rf-basic/api/highlightjs.css`
 - `theme/rf-basic/api/shiki.css`
@@ -165,7 +169,7 @@ For emitted HTML contracts and visual samples, see the files listed in [Docs and
 | `onFenceDecision` | debug hook for per-fence branch decisions |
 | `onFenceDecisionTiming` | include timing fields in `onFenceDecision` payloads |
 
-Line features fail closed when highlighter output line counts do not match source line counts. In `useHighlightPre` passthrough, line-splitting features and `<samp>` conversion are intentionally skipped.
+Line features fail closed when highlighter output line counts do not match source line counts. In `useHighlightPre` passthrough, line-splitting features and `<samp>` conversion are intentionally skipped. Emphasis ranges are normalized before rendering: reversed ranges are corrected, ranges are sorted, and overlapping or adjacent ranges are coalesced.
 
 ### Custom Highlight API options
 
@@ -198,7 +202,7 @@ import rendererFenceApi, {
   renderCustomHighlightPayloadScript,
 } from '@peaceroad/markdown-it-renderer-fence/custom-highlight'
 import {
-  createRfBasicShikiCustomHighlightOptions,
+  createRfBasicShikiRoleCustomHighlightOptions,
   rfBasicShikiTheme,
   rfBasicThemeName,
 } from '@peaceroad/markdown-it-renderer-fence/theme/rf-basic'
@@ -211,11 +215,9 @@ const highlighter = await createHighlighter({
 const md = MarkdownIt({ html: true })
   .use(markdownItAttrs)
   .use(rendererFenceApi, {
-    customHighlight: createRfBasicShikiCustomHighlightOptions({
+    customHighlight: createRfBasicShikiRoleCustomHighlightOptions({
       highlighter,
       theme: rfBasicThemeName,
-      shikiScopeMode: 'role',
-      includeScopeStyles: false,
       transport: 'env',
     }),
   })
@@ -251,7 +253,9 @@ The optional preset theme is a package artifact, not an automatically loaded dep
 @import "@peaceroad/markdown-it-renderer-fence/theme/rf-basic.css";
 ```
 
-The color preset covers base code blocks, `samp`, line features, highlight.js markup classes, Shiki API scopes, and highlight.js API scopes.
+The color preset covers fenced code blocks, `samp`, line-number/line-notes layout, other line features, highlight.js markup classes, Shiki role-mode API scopes, and highlight.js API scopes. It does not style inline Markdown code.
+
+Line-number HTML and counter behavior belong to the renderer, while spacing and colors remain theme-controlled. Override `--line-number-width`, `--line-number-gap`, `--line-number-rule-gap`, `--line-number-color`, and `--line-number-rule-color` after importing the structural or preset CSS.
 
 For one-color print/monochrome output, use markup mode and import the opt-in monochrome override:
 
@@ -281,6 +285,7 @@ From `@peaceroad/markdown-it-renderer-fence/theme/rf-basic`:
 - `rfBasicThemeName`
 - `createRfBasicShikiTheme`
 - `createRfBasicShikiCustomHighlightOptions`
+- `createRfBasicShikiRoleCustomHighlightOptions`
 - `createRfBasicHighlightjsCustomHighlightOptions`
 - `rfBasicSyntaxCssVars`
 - `createRfBasicShikiRoleScopeColorVars`

package/docs/code-highlighting-design.md

@@ -175,6 +175,8 @@ Exports:
 
 - `@peaceroad/markdown-it-renderer-fence/theme/rf-basic`
 - `@peaceroad/markdown-it-renderer-fence/theme/rf-basic.css`
+- `@peaceroad/markdown-it-renderer-fence/theme/line-number.css`
+- `@peaceroad/markdown-it-renderer-fence/theme/line-notes.css`
 - `@peaceroad/markdown-it-renderer-fence/theme/rf-basic/base.css`
 - `@peaceroad/markdown-it-renderer-fence/theme/rf-basic/api/shiki.css`
 - `@peaceroad/markdown-it-renderer-fence/theme/rf-basic/api/highlightjs.css`
@@ -185,8 +187,7 @@ Exports:
 
 The theme should cover:
 
-- base code block styling
-- inline code styling
+- fenced code block styling (inline Markdown code remains application-owned)
 - line numbers
 - emphasized lines
 - comment marks
@@ -201,12 +202,14 @@ Design rules:
 
 - CSS must not be auto-loaded by the renderer.
 - CSS variables should be stable enough for consumers to override.
+- Component theme CSS must not set document-wide `color-scheme`; scope UA color-scheme hints to the code/terminal surfaces that own the palette.
 - Light/dark variants should share the same role names.
 - `samp` should read as terminal output; using an inverted-looking surface is acceptable when contrast remains strong.
 - A one-color print theme should be markup-mode-only when it relies on bold/italic, because Custom Highlight API
   cannot apply `font-weight` or `font-style`.
 - In one-color terminal-like `samp` blocks, token-level bold/italic can make command/output boundaries ambiguous. Prefer suppressing token emphasis unless the terminal renderer has structural prompt/input/output markup.
 - Provider-specific CSS can be split, but base layout and shared variables should stay central.
+- Theme-neutral structural line CSS should have one package-owned source of truth and be imported by complete presets; examples may wrap those public files but must not become the implementation source.
 - An internal shared CSS source under `theme/_shared/` is acceptable when public theme files
   import it and package dry-runs verify it is shipped. Consumers should import public theme
   paths such as `theme/rf-basic/base.css`, not private shared files.
@@ -242,8 +245,9 @@ Current principles:
 - Use cheap source sentinels before scanning tokens for sidecar fences.
 - Run line splitting only when a line feature needs it.
 - Parse advanced line-number ranges lazily.
-- Keep role-mode caches bounded.
-- Avoid payload digest/state work unless incremental runtime apply is requested.
+- Keep role-mode caches bounded and cache every resolved base-scope bucket, not only fallback buckets.
+- Avoid payload digests, DOM text snapshots, and boundary-reference work unless incremental runtime apply is requested.
+- Reuse sanitized runtime scope names within one apply pass.
 - Keep markup-only and custom-highlight entries available for load isolation.
 
 Benchmark changes with:

package/docs/custom-highlight-styling-guide.md

@@ -28,7 +28,8 @@ In API mode, color comes from one of two sources:
 The plugin does not auto-load theme CSS files.
 The complete optional preset theme CSS is exported as `@peaceroad/markdown-it-renderer-fence/theme/rf-basic.css`.
 Provider-specific split files are also available:
-`theme/rf-basic/base.css`, `theme/rf-basic/api/shiki.css`, `theme/rf-basic/api/highlightjs.css`,
+`theme/line-number.css`, `theme/line-notes.css`, `theme/rf-basic/base.css`,
+`theme/rf-basic/api/shiki.css`, `theme/rf-basic/api/highlightjs.css`,
 `theme/rf-basic/markup/shiki.css`, and `theme/rf-basic/markup/highlightjs.css`.
 The optional JS theme helper uses CSS variable color values so Shiki can emit payload `scopeStyles` like `var(--rf-syntax-keyword)`.
 Your page still needs CSS that defines those variables, either by loading the preset CSS or by defining compatible variables in your app.
@@ -40,11 +41,9 @@ Your page still needs CSS that defines those variables, either by loading the pr
 Use CSS-managed role buckets:
 
 ```js
-customHighlight: {
-  provider: 'shiki',
-  shikiScopeMode: 'role',
-  includeScopeStyles: false,
-}
+import { createRfBasicShikiRoleCustomHighlightOptions } from '@peaceroad/markdown-it-renderer-fence/theme/rf-basic'
+
+customHighlight: createRfBasicShikiRoleCustomHighlightOptions({ highlighter })
 ```
 
 Why:
@@ -138,6 +137,8 @@ Notes:
 
 ## 7. Runtime and CSS Constraints
 
+Use one canonical runtime root per document, normally `document`. Custom highlight names are shared by scope and the browser's `CSS.highlights` registry is document-global, so applying two disjoint roots independently can replace same-named ranges registered by the other root. A subtree root is suitable when it is the only root managed by this runtime in that document.
+
 `::highlight(...)` reliably supports only a subset of properties.
 This plugin emits/uses:
 
@@ -168,6 +169,8 @@ This package ships an optional preset theme. It is not auto-loaded, but it is a
 CSS:
 
 - `@peaceroad/markdown-it-renderer-fence/theme/rf-basic.css`
+- `@peaceroad/markdown-it-renderer-fence/theme/line-number.css`
+- `@peaceroad/markdown-it-renderer-fence/theme/line-notes.css`
 - `@peaceroad/markdown-it-renderer-fence/theme/rf-basic/base.css`
 - `@peaceroad/markdown-it-renderer-fence/theme/rf-basic/api/shiki.css`
 - `@peaceroad/markdown-it-renderer-fence/theme/rf-basic/api/highlightjs.css`
@@ -186,6 +189,7 @@ The JS helper provides:
 
 - `rfBasicShikiTheme`: a Shiki theme object that uses `--rf-*` CSS variables.
 - `createRfBasicShikiCustomHighlightOptions(...)`: a small Shiki provider option helper.
+- `createRfBasicShikiRoleCustomHighlightOptions(...)`: the recommended CSS-managed role profile (`role` + no payload scope styles).
 - `createRfBasicHighlightjsCustomHighlightOptions(...)`: a small highlight.js provider option helper.
 - role maps used by repository examples to keep Shiki, highlight.js, and `::highlight(...)` CSS aligned.
 
@@ -197,6 +201,8 @@ syntax colors, so it is useful for print or one-color output. It is not a Custom
 
 The repository keeps `example/theme.css` only as a tiny local wrapper around the distributed preset CSS.
 
+The preset sets `color-scheme` only on themed `pre` surfaces. It does not opt the whole document into light/dark UA colors. Override `--rf-code-color-scheme` or `--rf-samp-color-scheme` when a site uses an explicit scheme that differs from `prefers-color-scheme`.
+
 For production:
 
 - Markup mode: use this preset, the CSS theme from your highlighter, or your design system.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peaceroad/markdown-it-renderer-fence",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A markdown-it fence renderer with code/samp output, line features, Custom Highlight API support, and optional themes.",
   "main": "index.js",
   "exports": {
@@ -11,6 +11,8 @@
     "./theme/rf-basic": "./theme/rf-basic/index.js",
     "./theme/rf-basic.css": "./theme/rf-basic/index.css",
     "./theme/rf-basic/*": "./theme/rf-basic/*",
+    "./theme/line-number.css": "./theme/line-number.css",
+    "./theme/line-notes.css": "./theme/line-notes.css",
     "./theme/rf-monochrome": "./theme/rf-monochrome/index.js",
     "./theme/rf-monochrome.css": "./theme/rf-monochrome/index.css",
     "./theme/rf-monochrome/*": "./theme/rf-monochrome/*"
@@ -51,10 +53,10 @@
   "repository": "https://github.com/peaceroad/p7d-markdown-it-renderer-fence",
   "license": "MIT",
   "devDependencies": {
-    "@peaceroad/markdown-it-figure-with-p-caption": "^0.18.0",
+    "@peaceroad/markdown-it-figure-with-p-caption": "^0.19.0",
     "highlight.js": "^11.11.1",
-    "markdown-it": "^14.1.1",
-    "markdown-it-attrs": "^4.3.1",
-    "shiki": "^4.1.0"
+    "markdown-it": "^14.3.0",
+    "markdown-it-attrs": "^5.0.0",
+    "shiki": "^4.3.1"
   }
 }

package/src/custom-highlight/payload-utils.js

@@ -1,3 +1,7 @@
+import {
+  escapeHtmlAttr,
+} from '../utils/attr-utils.js'
+
 const escapeJsonForScript = (data) => {
   return JSON.stringify(data)
     .replace(/</g, '\\u003C')
@@ -7,15 +11,6 @@ const escapeJsonForScript = (data) => {
     .replace(/\u2029/g, '\\u2029')
 }
 
-const escapeHtmlAttr = (value) => {
-  return String(value)
-    .replace(/&/g, '&amp;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-}
-
 const getCustomHighlightPayloadMap = (env, envKey = 'rendererFenceCustomHighlights') => {
   if (!env || typeof env !== 'object') return {}
   const map = env[envKey]

package/src/custom-highlight/shiki-role-rules.js

@@ -408,7 +408,7 @@ const roleV4SortedLangRules = new Map(
 )
 
 const applyShikiRoleLegacyPostRules = (currentBucket, ctx, helper) => {
-  const postHelper = helper && typeof helper === 'object' ? helper : {}
+  const postHelper = helper && typeof helper === 'object' ? helper : (ctx || {})
   const hasAnyScopePattern = typeof postHelper.hasAnyScopePattern === 'function'
     ? postHelper.hasAnyScopePattern
     : () => false
@@ -417,7 +417,7 @@ const applyShikiRoleLegacyPostRules = (currentBucket, ctx, helper) => {
     : (pattern) => hasAnyScopePattern([pattern])
   const classifyToken = typeof postHelper.classifyToken === 'function'
     ? postHelper.classifyToken
-    : () => null
+    : null
 
   const bucket = String(currentBucket || 'text')
   const langKey = String(ctx && ctx.langKey || '')
@@ -425,6 +425,12 @@ const applyShikiRoleLegacyPostRules = (currentBucket, ctx, helper) => {
   const tokenContent = String(ctx && ctx.tokenContent || '')
   const trimmed = String(ctx && ctx.tokenTrim || '')
   const tokenLower = (ctx && typeof ctx.tokenLower === 'string') ? ctx.tokenLower : trimmed.toLowerCase()
+  const isIdentifier = (ctx && typeof ctx.isIdentifier === 'boolean')
+    ? ctx.isIdentifier
+    : shikiSimpleIdentifierReg.test(trimmed)
+  const isPunctuation = (ctx && typeof ctx.isPunctuation === 'boolean')
+    ? ctx.isPunctuation
+    : shikiPunctuationTokenReg.test(trimmed)
   if (!trimmed) return 'text'
 
   if ((langKey === 'bash' || langKey === 'shellscript') && shikiShellOptionTokenReg.test(trimmed)) {
@@ -487,7 +493,7 @@ const applyShikiRoleLegacyPostRules = (currentBucket, ctx, helper) => {
     if (hasAnyScopePattern(['meta.function']) && !hasAnyScopePattern(['entity.name.function', 'support.function'])) return 'meta'
     if (hasAnyScopePattern(['punctuation.accessor'])) return 'text'
     if (!shikiFunctionLikeIdentifierReg.test(trimmed)) {
-      if (shikiPunctuationTokenReg.test(trimmed)) return 'punctuation'
+      if (isPunctuation) return 'punctuation'
       if (/[.\[\](){}:]/.test(trimmed)) return 'text'
     }
   }
@@ -505,7 +511,7 @@ const applyShikiRoleLegacyPostRules = (currentBucket, ctx, helper) => {
   if (bucket === 'variable') {
     if (
       hasAnyScopePattern(['meta.type.annotation']) &&
-      shikiPunctuationTokenReg.test(trimmed)
+      isPunctuation
     ) return 'punctuation'
     if (hasAnyScopePattern(['variable.language.this'])) return 'variable-this'
     if (hasAnyScopePattern(['variable.other.constant', 'constant.other.php', 'variable.other.enummember'])) return 'variable-const'
@@ -517,7 +523,7 @@ const applyShikiRoleLegacyPostRules = (currentBucket, ctx, helper) => {
     if (hasAnyScopePattern(['variable.other.constant', 'constant.other.php', 'variable.other.enummember'])) return 'variable-const'
     if (langKey === 'csharp' && hasAnyScopePattern(['entity.name.variable.local.cs'])) return 'text'
     if (hasAnyScopePattern(['source.sql', 'source.python', 'source.ruby'])) return 'text'
-    if (!shikiSimpleIdentifierReg.test(trimmed) && hasAnyScopePattern(['punctuation.'])) return 'punctuation'
+    if (!isIdentifier && hasAnyScopePattern(['punctuation.'])) return 'punctuation'
   }
   if (bucket === 'variable-member') {
     if (hasAnyScopePattern(['variable.object.property.ts', 'variable-object-property-ts', 'variable.object.property.js', 'variable-object-property-js'])) return 'variable-property'
@@ -530,7 +536,7 @@ const applyShikiRoleLegacyPostRules = (currentBucket, ctx, helper) => {
     if (hasAnyScopePattern(['variable.other.readwrite.hcl', 'variable.other.normal.shell', 'meta.block.hcl'])) return 'variable-plain'
     if (hasAnyScopePattern(['storage.type.built-in.primitive', 'keyword.operator.type.annotation', 'keyword.operator.type'])) return 'keyword'
     if (hasAnyScopePattern(['entity.name.type', 'support.type'])) return 'type-name'
-    if (!shikiSimpleIdentifierReg.test(trimmed)) return 'punctuation'
+    if (!isIdentifier) return 'punctuation'
   }
   if (bucket === 'variable-property') {
     if (hasAnyScopePattern(['variable.object.property', 'variable.other.property'])) return 'variable-parameter'
@@ -539,13 +545,17 @@ const applyShikiRoleLegacyPostRules = (currentBucket, ctx, helper) => {
   if (bucket === 'keyword' && hasAnyScopePattern(['variable.language.this'])) return 'variable-this'
   if (bucket === 'literal' && langKey === 'sql') return 'text'
   if (bucket === 'text') {
-    const tokenBucket = classifyToken(tokenContent, langKey)
+    const tokenBucket = classifyToken
+      ? classifyToken(tokenContent, langKey)
+      : ((ctx && ctx.tokenBucket) || null)
     if (tokenBucket) return tokenBucket
     if (hasAnyScopePattern(['source.sql', 'source.python', 'source.ruby', 'text.html.basic'])) return 'text'
-    if (shikiSimpleIdentifierReg.test(trimmed)) return 'variable-plain'
+    if (isIdentifier) return 'variable-plain'
   }
-  if (!shikiSimpleIdentifierReg.test(trimmed) && (bucket === 'text' || bucket === 'meta')) {
-    const tokenBucket = classifyToken(tokenContent, langKey)
+  if (!isIdentifier && (bucket === 'text' || bucket === 'meta')) {
+    const tokenBucket = classifyToken
+      ? classifyToken(tokenContent, langKey)
+      : ((ctx && ctx.tokenBucket) || null)
     if (tokenBucket) return tokenBucket
   }
   return bucket

package/src/custom-highlight/shiki-role.js

@@ -184,45 +184,44 @@ const classifyShikiScopeRoleSingle = (scope) => {
   const cached = shikiScopeRoleCache.get(s)
   if (cached) return cached
   let bucket = 'text'
-  if (s.includes('comment')) return 'comment'
-  if (s.includes('meta.shebang')) return 'meta-shebang'
-  if (s.includes('punctuation.definition.tag.begin') || s.includes('punctuation.definition.tag.end') || s.includes('punctuation.separator.key-value.html')) return 'tag-delimiter'
-  if (s.includes('entity.other.attribute-name') || s.includes('attribute-name')) return 'attribute'
-  if (s.includes('entity.name.tag')) return 'tag'
-  if (s.includes('string.unquoted')) return 'string-unquoted'
-  if (s.includes('regexp') || s.includes('regex') || s.includes('string') || s.includes('punctuation.definition.string')) return 'string'
-  if (s.includes('constant.other.color')) return 'number'
-  if (s.includes('constant.numeric') || s.includes('number')) return 'number'
-  if (s.includes('constant.language') || s.includes('boolean') || s.includes('null') || s.includes('undefined') || s.includes('none')) return 'literal'
-  if (s.includes('entity.name.scope-resolution') || s.includes('entity.name.namespace')) return 'namespace'
-  if (s.includes('storage.type.function.arrow') || s.includes('keyword.operator')) return 'keyword'
-  if (s.includes('variable.language.this')) return 'variable-this'
-  if (s.includes('constant.other.php') || s.includes('variable.other.constant') || s.includes('variable.other.enummember')) return 'variable-const'
-  if (s.includes('variable.object.property') || s.includes('variable.other.property') || s.includes('variable.other.member') || s.includes('variable.object.c') || s.includes('variable.ruby')) return 'variable-member'
-  if (s.includes('variable.parameter') || s.includes('entity.name.variable.parameter')) return 'variable-parameter'
-  if (s.includes('entity.name.variable.local') || s.includes('variable.other.readwrite') || s.includes('variable.other.normal') || s.includes('variable.other.php') || (s.includes('variable.other.') && !s.includes('variable.other.property') && !s.includes('variable.other.member'))) return 'variable-plain'
-  if (s.includes('support.function.builtin') || s.includes('support.function.kernel') || s.includes('support.function.construct')) return 'title-function-builtin'
-  if (s.includes('entity.name.function.macro')) return 'title-function'
-  if (s.includes('meta.function') && !s.includes('entity.name.function') && !s.includes('support.function')) return 'meta'
-  if (s.includes('entity.name.function') || s.includes('support.function')) return 'title-function'
-  if (s.includes('entity.name.class') || s.includes('entity.name.type.class')) return 'title-class'
-  if (s.includes('storage.type.built-in.primitive')) return 'type-primitive'
-  if (s.includes('entity.name.type.namespace') || s.includes('entity.name.type') || s.includes('support.class')) return 'type-name'
-  if (s.includes('support.type')) return 'type'
-  if (s.includes('storage') || s.includes('keyword') || s.includes('operator') || s.includes('control') || s.includes('modifier')) return 'keyword'
-  if (s.includes('variable')) return 'variable'
-  if (s.includes('punctuation')) return 'punctuation'
-  if (s.includes('source.')) bucket = 'text'
+  if (s.includes('comment')) bucket = 'comment'
+  else if (s.includes('meta.shebang')) bucket = 'meta-shebang'
+  else if (s.includes('punctuation.definition.tag.begin') || s.includes('punctuation.definition.tag.end') || s.includes('punctuation.separator.key-value.html')) bucket = 'tag-delimiter'
+  else if (s.includes('entity.other.attribute-name') || s.includes('attribute-name')) bucket = 'attribute'
+  else if (s.includes('entity.name.tag')) bucket = 'tag'
+  else if (s.includes('string.unquoted')) bucket = 'string-unquoted'
+  else if (s.includes('regexp') || s.includes('regex') || s.includes('string') || s.includes('punctuation.definition.string')) bucket = 'string'
+  else if (s.includes('constant.other.color')) bucket = 'number'
+  else if (s.includes('constant.numeric') || s.includes('number')) bucket = 'number'
+  else if (s.includes('constant.language') || s.includes('boolean') || s.includes('null') || s.includes('undefined') || s.includes('none')) bucket = 'literal'
+  else if (s.includes('entity.name.scope-resolution') || s.includes('entity.name.namespace')) bucket = 'namespace'
+  else if (s.includes('storage.type.function.arrow') || s.includes('keyword.operator')) bucket = 'keyword'
+  else if (s.includes('variable.language.this')) bucket = 'variable-this'
+  else if (s.includes('constant.other.php') || s.includes('variable.other.constant') || s.includes('variable.other.enummember')) bucket = 'variable-const'
+  else if (s.includes('variable.object.property') || s.includes('variable.other.property') || s.includes('variable.other.member') || s.includes('variable.object.c') || s.includes('variable.ruby')) bucket = 'variable-member'
+  else if (s.includes('variable.parameter') || s.includes('entity.name.variable.parameter')) bucket = 'variable-parameter'
+  else if (s.includes('entity.name.variable.local') || s.includes('variable.other.readwrite') || s.includes('variable.other.normal') || s.includes('variable.other.php') || (s.includes('variable.other.') && !s.includes('variable.other.property') && !s.includes('variable.other.member'))) bucket = 'variable-plain'
+  else if (s.includes('support.function.builtin') || s.includes('support.function.kernel') || s.includes('support.function.construct')) bucket = 'title-function-builtin'
+  else if (s.includes('entity.name.function.macro')) bucket = 'title-function'
+  else if (s.includes('meta.function') && !s.includes('entity.name.function') && !s.includes('support.function')) bucket = 'meta'
+  else if (s.includes('entity.name.function') || s.includes('support.function')) bucket = 'title-function'
+  else if (s.includes('entity.name.class') || s.includes('entity.name.type.class')) bucket = 'title-class'
+  else if (s.includes('storage.type.built-in.primitive')) bucket = 'type-primitive'
+  else if (s.includes('entity.name.type.namespace') || s.includes('entity.name.type') || s.includes('support.class')) bucket = 'type-name'
+  else if (s.includes('support.type')) bucket = 'type'
+  else if (s.includes('storage') || s.includes('keyword') || s.includes('operator') || s.includes('control') || s.includes('modifier')) bucket = 'keyword'
+  else if (s.includes('variable')) bucket = 'variable'
+  else if (s.includes('punctuation')) bucket = 'punctuation'
   else if (s.includes('meta')) bucket = 'meta'
+  if (shikiScopeRoleCache.size >= 8192) shikiScopeRoleCache.clear()
   shikiScopeRoleCache.set(s, bucket)
-  if (shikiScopeRoleCache.size > 8192) shikiScopeRoleCache.clear()
   return bucket
 }
 
-const hasJsonYamlPropertyNameScope = (scopeCandidates) => {
-  if (!Array.isArray(scopeCandidates)) return false
-  for (let i = 0; i < scopeCandidates.length; i++) {
-    const s = String(scopeCandidates[i] || '').toLowerCase()
+const hasJsonYamlPropertyNameScope = (lowerScopeCandidates) => {
+  if (!Array.isArray(lowerScopeCandidates)) return false
+  for (let i = 0; i < lowerScopeCandidates.length; i++) {
+    const s = lowerScopeCandidates[i]
     if (!s.includes('property-name') && !s.includes('dictionary-key')) continue
     if (s.includes('.json') || s.includes('-json') || s.includes('.yaml') || s.includes('-yaml')) return true
   }
@@ -302,18 +301,22 @@ const resolveShikiRoleLang = (lang, scopeCandidates, tok, opt) => {
   return ''
 }
 
-const classifyShikiRoleByToken = (content, langKey) => {
+const classifyShikiRoleByToken = (content, langKey, trimmedValue, lowerValue, punctuationValue) => {
   const text = String(content || '')
-  const trimmed = text.trim()
+  const trimmed = typeof trimmedValue === 'string' ? trimmedValue : text.trim()
   if (!trimmed) return 'text'
-  const lower = trimmed.toLowerCase().replace(/\s+/g, ' ')
+  const rawLower = typeof lowerValue === 'string' ? lowerValue : trimmed.toLowerCase()
+  const lower = rawLower.replace(/\s+/g, ' ')
   if (lower.startsWith('#!')) return 'meta'
   if (langKey !== 'sql' && shikiGlobalLiteralTokenSet.has(lower)) return 'literal'
   if (shikiNumberTokenReg.test(lower)) return 'number'
   const set = shikiLangKeywordTokens[langKey]
   if (set && set.has(lower)) return 'keyword'
   if (langKey === 'css' && lower.startsWith('@')) return 'keyword'
-  if (shikiPunctuationTokenReg.test(trimmed)) return 'punctuation'
+  const isPunctuation = typeof punctuationValue === 'boolean'
+    ? punctuationValue
+    : shikiPunctuationTokenReg.test(trimmed)
+  if (isPunctuation) return 'punctuation'
   return null
 }
 
@@ -326,6 +329,9 @@ const buildShikiRoleContext = (rawScope, tok, lang, opt, preResolvedLangKey = ''
   const langKey = preResolvedLangKey || resolveShikiRoleLang(lang, scopeCandidates, token, opt)
   const lowerScopeCandidates = toLowerScopeCandidates(scopeCandidates)
   const hasAnyScopePatternCached = createScopePatternMatcher(lowerScopeCandidates)
+  const isIdentifier = shikiSimpleIdentifierReg.test(tokenTrim)
+  const isPunctuation = shikiPunctuationTokenReg.test(tokenTrim)
+  const tokenBucket = classifyShikiRoleByToken(tokenContent, langKey, tokenTrim, tokenLower, isPunctuation)
   return {
     rawScope,
     token,
@@ -336,8 +342,9 @@ const buildShikiRoleContext = (rawScope, tok, lang, opt, preResolvedLangKey = ''
     tokenContent,
     tokenTrim,
     tokenLower,
-    isIdentifier: shikiSimpleIdentifierReg.test(tokenTrim),
-    isPunctuation: shikiPunctuationTokenReg.test(tokenTrim),
+    isIdentifier,
+    isPunctuation,
+    tokenBucket,
     hasAnyScopePattern: hasAnyScopePatternCached,
     hasScopePattern: (pattern) => hasAnyScopePatternCached([pattern]),
   }
@@ -347,7 +354,6 @@ const classifyShikiScopeRoleBaseFromContext = (context) => {
   if (!context || typeof context !== 'object') return 'text'
   let best = 'text'
   let bestScore = shikiRoleBucketScore.text
-  const candidates = Array.isArray(context.scopeCandidates) ? context.scopeCandidates : []
   const lowerScopeCandidates = Array.isArray(context.lowerScopeCandidates) ? context.lowerScopeCandidates : []
   const hasAnyPattern = (context && typeof context.hasAnyScopePattern === 'function')
     ? context.hasAnyScopePattern
@@ -356,12 +362,11 @@ const classifyShikiScopeRoleBaseFromContext = (context) => {
     ? context.hasScopePattern
     : (pattern) => hasAnyPattern([pattern])
   const langKey = String(context.langKey || '')
-  const tokenContent = context.tokenContent
   if (langKey === 'hcl' || langKey === 'terraform') {
     const hclBucket = classifyShikiHclRoleBucket(lowerScopeCandidates, hasAnyPattern)
     if (hclBucket) return hclBucket
   }
-  if (hasJsonYamlPropertyNameScope(candidates)) return 'type'
+  if (hasJsonYamlPropertyNameScope(lowerScopeCandidates)) return 'type'
   if (langKey === 'yaml' && hasScope('entity.name.tag.yaml')) return 'tag'
   for (let i = 0; i < lowerScopeCandidates.length; i++) {
     const bucket = classifyShikiScopeRoleSingle(lowerScopeCandidates[i])
@@ -378,7 +383,7 @@ const classifyShikiScopeRoleBaseFromContext = (context) => {
       bestScore = shikiRoleBucketScore.text + 1
     }
   }
-  const tokenBucket = classifyShikiRoleByToken(tokenContent, langKey)
+  const tokenBucket = context.tokenBucket
   if (tokenBucket) {
     const tokenScore = (shikiRoleBucketScore[tokenBucket] || shikiRoleBucketScore.text) + 1
     if (best !== 'string' && best !== 'string-unquoted' && tokenScore > bestScore) best = tokenBucket
@@ -407,12 +412,7 @@ const classifyShikiScopeRole = (rawScope, tok, lang, opt, preResolvedRoleLang =
     tokenLower,
   )
   const baseBucket = classifyShikiScopeRoleBaseFromContext(context)
-  const postHelpers = {
-    classifyToken: classifyShikiRoleByToken,
-    hasAnyScopePattern: context.hasAnyScopePattern,
-    hasScopePattern: context.hasScopePattern,
-  }
-  const postBucket = applyShikiRoleLegacyPostRules(baseBucket, context, postHelpers)
+  const postBucket = applyShikiRoleLegacyPostRules(baseBucket, context)
   const finalBucket = applyRoleV4Rules(postBucket, context)
   return finalBucket || postBucket || baseBucket
 }

package/src/fence/render-api-constants.js

@@ -11,7 +11,7 @@ const customHighlightDataScriptId = 'pre-highlight-data'
 const customHighlightStyleTagId = 'pre-highlight-style'
 const customHighlightEnvInitRuleName = 'renderer_fence_custom_highlight_env_init'
 
-const runtimeFallbackReasonSet = new Set(['api-unsupported', 'apply-error'])
+const runtimeFallbackReasonSet = new Set(['api-unsupported', 'range-invalid', 'apply-error'])
 
 const customHighlightPayloadSchemaVersion = 1
 const customHighlightPayloadSupportedVersions = [customHighlightPayloadSchemaVersion]

package/src/fence/render-api-provider.js

@@ -293,8 +293,6 @@ const getShikiTokenStyle = (token) => {
   const style = {}
   if (typeof token.color === 'string' && token.color) style.color = token.color
   const fontStyle = Number.isFinite(token.fontStyle) ? token.fontStyle : 0
-  if (fontStyle & 1) style.fontStyle = 'italic'
-  if (fontStyle & 2) style.fontWeight = '700'
   if (fontStyle & 4) style.textDecoration = 'underline'
   return normalizeScopeStyle(style)
 }
@@ -666,8 +664,8 @@ const buildShikiTokenOption = (chOpt, targetLang, themeOverride = '') => {
 }
 
 const getApiProviderEntries = (token, lang, chOpt, md, env, override) => {
-  const context = { token, md, env, option: chOpt }
   if (chOpt.provider === 'custom') {
+    const context = { token, md, env, option: chOpt }
     const getRanges = chOpt._customGetRanges
     if (typeof getRanges !== 'function') throw new Error('customHighlight.getRanges must be a function')
     const result = getRanges(token.content, lang, context)
@@ -675,6 +673,7 @@ const getApiProviderEntries = (token, lang, chOpt, md, env, override) => {
     return normalizeCustomProviderRanges(result)
   }
   if (chOpt.provider === 'hljs') {
+    const context = { token, md, env, option: chOpt }
     const highlightFn = chOpt._hljsHighlightFn
     if (typeof highlightFn !== 'function') {
       throw new Error('customHighlight.hljsHighlight (or customHighlight.highlight / md.options.highlight) must be a function when provider=hljs')

package/src/fence/render-api-renderer.js

@@ -1,4 +1,5 @@
 import {
+  escapeHtmlAttr,
   escapeJsonForScript,
 } from '../custom-highlight/payload-utils.js'
 import {
@@ -91,8 +92,9 @@ const renderFenceApiOrPlain = (token, lang, isSamp, md, opt, slf, env, startNumb
       env[customHighlightDataEnvKey][id] = payload
     } else {
       const payloadJson = escapeJsonForScript(payload)
-      const scriptId = `pre-highlight-data-${id}`
-      inlinePayloadScript = `<script type="application/json" id="${scriptId}" ${customHighlightPreAttr}="${id}">${payloadJson}</script>\n`
+      const scriptId = escapeHtmlAttr(`pre-highlight-data-${id}`)
+      const escapedId = escapeHtmlAttr(id)
+      inlinePayloadScript = `<script type="application/json" id="${scriptId}" ${customHighlightPreAttr}="${escapedId}">${payloadJson}</script>\n`
     }
   }
 
@@ -150,9 +152,22 @@ const getFenceHtml = (context, md, opt, slf, env) => {
       emitFenceDecision(opt, fallbackDecision)
       return html
     }
+    const fallbackDecision = {
+      renderer: 'api',
+      includePayload: false,
+      fallbackUsed: true,
+      fallback: 'markup',
+      reason: 'provider-error',
+      lineFeatureStrategy: opt.customHighlight.lineFeatureStrategy,
+    }
+    const markupOpt = typeof opt.onFenceDecision === 'function'
+      ? { ...opt, onFenceDecision: null }
+      : opt
+    const html = renderFenceMarkup(context, md, markupOpt, slf)
+    if (timingEnabled) fallbackDecision.timings = finalizeFenceTimings(timings, fenceStartedAt)
+    emitFenceDecision(opt, fallbackDecision)
+    return html
   }
-
-  return renderFenceMarkup(context, md, opt, slf)
 }
 
 export {