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

package/src/fence/line-notes.js

@@ -0,0 +1,199 @@
+import {
+  getInfoAttr,
+} from '../utils/attr-utils.js'
+
+const lineNotesRuleName = 'renderer_fence_line_notes'
+const lineNotesMetaKey = '__rendererFenceLineNotes'
+const lineNotesInstalledKey = '__rendererFenceLineNotesInstalled'
+const lineNoteHeaderReg = /^\s*([1-9]\d*)(?:\s*-\s*([1-9]\d*))?\s*[:：]\s*(.*)$/
+const lineNoteContinuationReg = /^(?: {2,}|\t)/
+const lineNoteAttrsReg = /^(.*?)(?:\s+\{([^{}]+)\})\s*$/
+const lineNoteAttrsOnlyReg = /^\{([^{}]+)\}\s*$/
+const lineNoteWidthReg = /^(?:\d+(?:\.\d+)?|\.\d+)(?:px|em|rem|ch|vw|svw|lvw|dvw|%)$/
+
+const canContainLineNotes = (state) => {
+  const src = state && state.src
+  return typeof src === 'string' && src.indexOf('notes') !== -1
+}
+
+const isInfoWhitespaceCode = (code) => {
+  return code === 32 || code === 9 || code === 10 || code === 13 || code === 12
+}
+
+const isInfoNameEnd = (str, pos) => {
+  if (pos >= str.length) return true
+  const code = str.charCodeAt(pos)
+  return code === 123 || isInfoWhitespaceCode(code)
+}
+
+const infoNameStartsWith = (info, name) => {
+  const str = String(info ?? '')
+  let pos = 0
+  while (pos < str.length && isInfoWhitespaceCode(str.charCodeAt(pos))) pos++
+  return str.startsWith(name, pos) && isInfoNameEnd(str, pos + name.length)
+}
+
+const isLineNoteFenceInfo = (info) => {
+  return infoNameStartsWith(info, 'line-notes') || infoNameStartsWith(info, 'notes')
+}
+
+const stripContinuationIndent = (line) => {
+  if (!line) return ''
+  if (line[0] === '\t') return line.slice(1)
+  if (line.startsWith('  ')) return line.slice(2)
+  return line
+}
+
+const parseValidatedLineNoteWidth = (attrText) => {
+  if (!attrText || attrText.indexOf('width') === -1) return ''
+  const attrs = getInfoAttr(attrText)
+  if (!attrs.length) return ''
+  for (let i = 0; i < attrs.length; i++) {
+    const name = attrs[i][0]
+    const value = String(attrs[i][1] || '').trim()
+    if (name !== 'width') continue
+    if (lineNoteWidthReg.test(value)) return value
+  }
+  return ''
+}
+
+const parseLineNoteHeaderText = (text) => {
+  const str = String(text ?? '')
+  if (str.indexOf('{') === -1 || str.indexOf('}') === -1) {
+    return { text: str, width: '' }
+  }
+  const match = str.match(lineNoteAttrsReg)
+  if (!match) return { text: str, width: '' }
+  return {
+    text: match[1].trimEnd(),
+    width: parseValidatedLineNoteWidth(match[2]),
+  }
+}
+
+const parseLineNoteAttrsOnlyText = (text) => {
+  const str = String(text ?? '').trim()
+  if (str[0] !== '{' || str[str.length - 1] !== '}') return null
+  const match = str.match(lineNoteAttrsOnlyReg)
+  if (!match) return null
+  const width = parseValidatedLineNoteWidth(match[1])
+  return width ? { width } : null
+}
+
+const parseLineNotesContent = (content) => {
+  const raw = String(content ?? '')
+  if (!raw || (raw.indexOf(':') === -1 && raw.indexOf('：') === -1)) return []
+  const lines = raw.split('\n')
+  const notes = []
+  const seenStarts = new Set()
+  let current = null
+
+  const pushCurrent = () => {
+    if (!current) return true
+    if (!current.lines.length) return false
+    notes.push({
+      from: current.from,
+      to: current.to,
+      text: current.lines.join('\n'),
+      lineCount: current.lines.length,
+      width: current.width || '',
+    })
+    seenStarts.add(current.from)
+    current = null
+    return true
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const header = line.match(lineNoteHeaderReg)
+    if (header) {
+      if (!pushCurrent()) return null
+      let from = Number(header[1])
+      let to = header[2] ? Number(header[2]) : from
+      if (from > to) {
+        const swap = from
+        from = to
+        to = swap
+      }
+      if (seenStarts.has(from)) return null
+      current = {
+        from,
+        to,
+        lines: [],
+        width: '',
+      }
+      const parsed = parseLineNoteHeaderText(header[3])
+      current.width = parsed.width
+      if (parsed.text) current.lines.push(parsed.text)
+      continue
+    }
+
+    if (current && lineNoteContinuationReg.test(line)) {
+      const stripped = stripContinuationIndent(line)
+      const attrsOnly = parseLineNoteAttrsOnlyText(stripped)
+      if (attrsOnly) {
+        if (attrsOnly.width) current.width = attrsOnly.width
+        continue
+      }
+      current.lines.push(stripped)
+      continue
+    }
+
+    if (!line.trim()) {
+      continue
+    }
+
+    return null
+  }
+
+  if (!pushCurrent()) return null
+  return notes
+}
+
+const getTokenLineNotes = (token) => {
+  if (!token || !token.meta || typeof token.meta !== 'object') return null
+  const notes = token.meta[lineNotesMetaKey]
+  return Array.isArray(notes) && notes.length ? notes : null
+}
+
+const setTokenLineNotes = (token, notes) => {
+  if (!token || !notes || !notes.length) return
+  if (!token.meta || typeof token.meta !== 'object') token.meta = {}
+  token.meta[lineNotesMetaKey] = notes
+}
+
+const extendTokenMapWithImmediateFollower = (token, next) => {
+  if (!token || !Array.isArray(token.map) || token.map.length !== 2) return
+  if (!next || !Array.isArray(next.map) || next.map.length !== 2) return
+  const start = token.map[0]
+  const end = next.map[1]
+  if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end)) return
+  if (end > token.map[1]) token.map = [start, end]
+}
+
+const installLineNotesCoreRule = (md) => {
+  if (!md || md[lineNotesInstalledKey]) return
+  md[lineNotesInstalledKey] = true
+  md.core.ruler.after('block', lineNotesRuleName, (state) => {
+    if (!canContainLineNotes(state)) return
+    const tokens = state && state.tokens
+    if (!Array.isArray(tokens) || tokens.length < 2) return
+
+    for (let i = 0; i < tokens.length - 1; i++) {
+      const token = tokens[i]
+      const next = tokens[i + 1]
+      if (!token || token.type !== 'fence' || !next || next.type !== 'fence') continue
+      if (!isLineNoteFenceInfo(next.info)) continue
+      if (isLineNoteFenceInfo(token.info)) continue
+      const notes = parseLineNotesContent(next.content)
+      if (!notes || !notes.length) continue
+      setTokenLineNotes(token, notes)
+      extendTokenMapWithImmediateFollower(token, next)
+      tokens.splice(i + 1, 1)
+    }
+  })
+}
+
+export {
+  getTokenLineNotes,
+  installLineNotesCoreRule,
+}

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

@@ -1,9 +1,9 @@
 import {
-  classifyShikiScopeKeyword,
+  classifyShikiScopeRole,
   getShikiRawScopeName,
-  normalizeShikiKeywordLangAliasMap,
-  resolveShikiKeywordLangForFence,
-} from '../custom-highlight/shiki-keyword.js'
+  normalizeShikiRoleLangAliasMap,
+  resolveShikiRoleLangForFence,
+} from '../custom-highlight/shiki-role.js'
 import {
   escapeHtmlAttr,
   getCustomHighlightPayloadMap,
@@ -15,8 +15,12 @@ import {
 import {
   validateCustomHighlightOptions,
 } from '../custom-highlight/option-validator.js'
+import {
+  sanitizeHighlightName,
+} from '../custom-highlight/scope-name.js'
 import {
   commentLineClass,
+  getCommentLineRanges,
   normalizeEmphasisRanges,
 } from './render-shared.js'
 import {
@@ -31,7 +35,6 @@ import {
 } from './render-api-constants.js'
 
 const highlightNameUnsafeReg = /[^A-Za-z0-9_-]+/g
-const hyphenMultiReg = /-+/g
 
 const defaultCustomHighlightOpt = {
   provider: 'shiki',
@@ -44,9 +47,9 @@ const defaultCustomHighlightOpt = {
   scopePrefix: 'hl',
   includeScopeStyles: true,
   shikiScopeMode: 'auto',
-  shikiKeywordClassifier: null,
-  shikiKeywordLangResolver: null,
-  shikiKeywordLangAliases: null,
+  shikiRoleClassifier: null,
+  shikiRoleLangResolver: null,
+  shikiRoleLangAliases: null,
 }
 
 const normalizeCustomHighlightProvider = (provider) => {
@@ -58,7 +61,7 @@ const normalizeCustomHighlightProvider = (provider) => {
 const normalizeShikiScopeMode = (mode) => {
   const key = String(mode || '').trim().toLowerCase()
   if (!key) return null
-  if (key === 'keyword') return 'keyword'
+  if (key === 'role') return 'role'
   if (key === 'semantic') return 'semantic'
   if (key === 'color') return 'color'
   if (key === 'auto') return 'auto'
@@ -133,7 +136,7 @@ const buildShikiInternalLangAliasMap = (highlighter) => {
     } catch (e) {}
     rawMap[rawName] = canonical
   }
-  return normalizeShikiKeywordLangAliasMap(rawMap)
+  return normalizeShikiRoleLangAliasMap(rawMap)
 }
 
 const normalizeCustomHighlightOpt = (opt = {}) => {
@@ -160,11 +163,11 @@ const normalizeCustomHighlightOpt = (opt = {}) => {
   } else {
     next.theme = normalizedTheme.singleTheme || null
   }
-  if (typeof next.shikiKeywordClassifier !== 'function') next.shikiKeywordClassifier = null
-  if (typeof next.shikiKeywordLangResolver !== 'function') next.shikiKeywordLangResolver = null
-  next.shikiKeywordLangAliases = normalizeShikiKeywordLangAliasMap(next.shikiKeywordLangAliases)
+  if (typeof next.shikiRoleClassifier !== 'function') next.shikiRoleClassifier = null
+  if (typeof next.shikiRoleLangResolver !== 'function') next.shikiRoleLangResolver = null
+  next.shikiRoleLangAliases = normalizeShikiRoleLangAliasMap(next.shikiRoleLangAliases)
   next._shikiInternalLangAliasMap =
-    (next.provider === 'shiki' && next.shikiScopeMode === 'keyword')
+    (next.provider === 'shiki' && next.shikiScopeMode === 'role')
       ? buildShikiInternalLangAliasMap(next.highlighter)
       : null
   const fallbackOn = Array.isArray(next.fallbackOn) ? next.fallbackOn : fallbackOnDefault
@@ -183,16 +186,6 @@ const shouldApplyApiFallbackForReason = (chOpt, reason) => {
   return chOpt._fallbackOnSet.has(reason)
 }
 
-const sanitizeHighlightName = (name, prefix = '') => {
-  const prefixBase = String(prefix == null ? '' : prefix).replace(highlightNameUnsafeReg, '-').replace(hyphenMultiReg, '-').replace(/^-+|-+$/g, '')
-  const raw = String(name || '')
-  let safe = raw.replace(highlightNameUnsafeReg, '-').replace(hyphenMultiReg, '-').replace(/^-+|-+$/g, '')
-  if (!safe) safe = 'scope'
-  if (/^[0-9]/.test(safe)) safe = 'x-' + safe
-  if (safe.startsWith('--')) safe = safe.slice(2) || 'scope'
-  return prefixBase ? `${prefixBase}-${safe}` : safe
-}
-
 const uniqueHighlightName = (base, usedMap) => {
   if (!usedMap.has(base)) {
     usedMap.set(base, 1)
@@ -280,19 +273,20 @@ const sameScopeStyles = (a, b) => {
   return true
 }
 
-const getLogicalLinesAndOffsets = (text) => {
-  const rawLines = text.split('\n')
-  const logicalLineCount = rawLines.length > 0 && rawLines[rawLines.length - 1] === '' ? rawLines.length - 1 : rawLines.length
-  const lines = new Array(logicalLineCount)
-  const offsets = new Array(logicalLineCount)
-  let cursor = 0
-  for (let i = 0; i < logicalLineCount; i++) {
-    const line = rawLines[i]
-    lines[i] = line
-    offsets[i] = [cursor, cursor + line.length]
-    cursor += line.length + 1
+const getLogicalLineOffsets = (text) => {
+  const str = String(text ?? '')
+  const offsets = []
+  if (!str) return offsets
+  let lineStart = 0
+  for (let i = 0; i < str.length; i++) {
+    const code = str.charCodeAt(i)
+    if (code !== 10 && code !== 13) continue
+    offsets.push([lineStart, i])
+    if (code === 13 && i + 1 < str.length && str.charCodeAt(i + 1) === 10) i++
+    lineStart = i + 1
   }
-  return { lines, offsets }
+  if (lineStart < str.length) offsets.push([lineStart, str.length])
+  return offsets
 }
 
 const getShikiTokenStyle = (token) => {
@@ -467,21 +461,21 @@ const hasShikiOffsets = (tokenLines) => {
   return false
 }
 
-const getShikiScopeName = (tok, lang, style, opt, preResolvedKeywordLang = '') => {
+const getShikiScopeName = (tok, lang, style, opt, preResolvedRoleLang = '') => {
   const scopeMode = (opt && opt.shikiScopeMode) || 'auto'
   const rawScope = getShikiRawScopeName(tok)
-  let customKeywordName = null
-  const isKeywordScopeMode = scopeMode === 'keyword'
-  if (isKeywordScopeMode && opt && typeof opt.shikiKeywordClassifier === 'function') {
+  let customRoleName = null
+  const isRoleScopeMode = scopeMode === 'role'
+  if (isRoleScopeMode && opt && typeof opt.shikiRoleClassifier === 'function') {
     try {
-      const customName = opt.shikiKeywordClassifier(rawScope, tok, { lang, style, scopeMode })
-      if (customName != null && customName !== '') customKeywordName = String(customName)
+      const customName = opt.shikiRoleClassifier(rawScope, tok, { lang, style, scopeMode })
+      if (customName != null && customName !== '') customRoleName = String(customName)
     } catch (e) {}
   }
-  if (isKeywordScopeMode) {
-    if (customKeywordName) return 'shiki-' + customKeywordName
-    const bucket = classifyShikiScopeKeyword(rawScope, tok, lang, opt, preResolvedKeywordLang)
-    return 'shiki-' + bucket
+  if (isRoleScopeMode) {
+    if (customRoleName) return 'shiki-role-' + customRoleName
+    const bucket = classifyShikiScopeRole(rawScope, tok, lang, opt, preResolvedRoleLang)
+    return 'shiki-role-' + bucket
   }
   if (scopeMode === 'semantic') {
     if (rawScope) return 'shiki-' + rawScope
@@ -523,11 +517,11 @@ const createRangesFromShikiTokens = (lang, tokenLines, opt) => {
     scopeMode === 'auto' ||
     scopeMode === 'color' ||
     scopeMode === 'semantic' ||
-    (scopeMode === 'keyword' && !!(opt && typeof opt.shikiKeywordClassifier === 'function'))
+    (scopeMode === 'role' && !!(opt && typeof opt.shikiRoleClassifier === 'function'))
   const needTokenStyle = includeScopeStyles || needStyleForScopeName
-  let preResolvedKeywordLang = ''
-  if (scopeMode === 'keyword' && (!opt || typeof opt.shikiKeywordLangResolver !== 'function')) {
-    preResolvedKeywordLang = resolveShikiKeywordLangForFence(lang, opt)
+  let preResolvedRoleLang = ''
+  if (scopeMode === 'role' && (!opt || typeof opt.shikiRoleLangResolver !== 'function')) {
+    preResolvedRoleLang = resolveShikiRoleLangForFence(lang, opt)
   }
   let cursor = 0
   for (let i = 0; i < tokenLines.length; i++) {
@@ -542,7 +536,7 @@ const createRangesFromShikiTokens = (lang, tokenLines, opt) => {
       const start = hasOffset ? tok.offset : cursor
       const end = start + content.length
       const style = needTokenStyle ? getShikiTokenStyle(tok) : null
-      const scope = getShikiScopeName(tok, lang, style, opt, preResolvedKeywordLang)
+      const scope = getShikiScopeName(tok, lang, style, opt, preResolvedRoleLang)
       entries.push({ scope, start, end, style })
       cursor = end
     }
@@ -559,6 +553,7 @@ const normalizeCustomProviderRanges = (result) => {
   const entries = []
   for (const range of source.ranges) {
     let scope
+    let scopeIndex = null
     let start
     let end
     let style
@@ -575,10 +570,11 @@ const normalizeCustomProviderRanges = (result) => {
     } else {
       continue
     }
-    if (typeof scope === 'number' && scopes && scopes[scope] != null) scope = scopes[scope]
+    if (Number.isSafeInteger(scope)) scopeIndex = scope
+    if (scopeIndex != null && scopes && scopes[scopeIndex] != null) scope = scopes[scopeIndex]
     if (scope == null) continue
     if (!style && scopeStyles) {
-      if (typeof scope === 'number' && Array.isArray(scopeStyles)) style = scopeStyles[scope]
+      if (scopeIndex != null && Array.isArray(scopeStyles)) style = scopeStyles[scopeIndex]
       else style = scopeStyles[String(scope)]
     }
     entries.push({ scope: String(scope), start, end, style: normalizeScopeStyle(style) })
@@ -617,7 +613,12 @@ const buildApiPayload = (entries, text, lang, engine, scopePrefix, includeScopeS
       }
       scopeKeyToIndex.set(key, scopeIndex)
     }
-    ranges.push([scopeIndex, start, end])
+    const previousRange = ranges.length ? ranges[ranges.length - 1] : null
+    if (previousRange && previousRange[0] === scopeIndex && previousRange[2] === start) {
+      previousRange[2] = end
+    } else {
+      ranges.push([scopeIndex, start, end])
+    }
   }
   const payload = {
     v: customHighlightPayloadSchemaVersion,
@@ -637,8 +638,8 @@ const pushLineFeatureRanges = (entries, content, emphasizeLines, setEmphasizeLin
   const needsEmphasis = !!(setEmphasizeLines && emphasizeLines && emphasizeLines.length > 0)
   const needsCommentScan = !!(commentMarkValue && content.indexOf(commentMarkValue) !== -1)
   if (!needsEmphasis && !needsCommentScan) return
-  const { lines, offsets } = getLogicalLinesAndOffsets(content)
-  const maxLine = lines.length
+  const offsets = needsEmphasis ? getLogicalLineOffsets(content) : null
+  const maxLine = offsets ? offsets.length : 0
   if (needsEmphasis) {
     const normalized = normalizeEmphasisRanges(emphasizeLines, maxLine)
     for (const [s, e] of normalized) {
@@ -648,11 +649,11 @@ const pushLineFeatureRanges = (entries, content, emphasizeLines, setEmphasizeLin
     }
   }
   if (needsCommentScan) {
-    for (let i = 0; i < lines.length; i++) {
-      if (lines[i].trimStart().startsWith(commentMarkValue)) {
-        const [start, end] = offsets[i]
-        if (end > start) entries.push({ scope: commentLineClass, start, end })
-      }
+    const ranges = getCommentLineRanges(content, commentMarkValue)
+    if (!ranges) return
+    for (let i = 0; i < ranges.length; i++) {
+      const [start, end] = ranges[i]
+      entries.push({ scope: commentLineClass, start, end })
     }
   }
 }
@@ -805,6 +806,5 @@ export {
   normalizeCustomHighlightOpt,
   renderCustomHighlightPayloadScript,
   renderCustomHighlightScopeStyleTag,
-  sanitizeHighlightName,
   shouldApplyApiFallbackForReason,
 }

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

@@ -11,7 +11,9 @@ import {
   orderTokenAttrs,
   preWrapStyle,
   resolveAdvancedLineNumberPlan,
+  resolveLineNotesPlan,
   splitFenceBlockToLines,
+  wrapFencePreWithLineNotes,
 } from './render-shared.js'
 import {
   createApiPayloadForFence,
@@ -26,6 +28,8 @@ import {
   renderFenceMarkup,
 } from './render-markup.js'
 
+const apiDisableLineFeatureList = Object.freeze(['setLineNumber', 'line-number-skip', 'line-number-set', 'setEmphasizeLines', 'lineEndSpanThreshold', 'comment-mark', 'line-notes'])
+
 let fallbackCustomHighlightSeq = 0
 
 const nextCustomHighlightId = (env, prefix) => {
@@ -45,23 +49,29 @@ const buildApiPreAttrs = (preWrapValue, wrapEnabled, opt) => {
   return preAttrs
 }
 
-const renderFenceApiOrPlain = (token, lang, md, opt, slf, env, startNumber, emphasizeLines, lineNumberSkipValue, lineNumberSetValue, wrapEnabled, preWrapValue, commentMarkValue, includePayload, timings) => {
-  const isSamp = opt._sampReg.test(lang)
+const renderFenceApiOrPlain = (token, lang, isSamp, md, opt, slf, env, startNumber, emphasizeLines, lineNumberSkipValue, lineNumberSetValue, wrapEnabled, preWrapValue, commentMarkValue, lineNotes, lineNoteIdPrefix, includePayload, timings) => {
   const tag = isSamp ? 'samp' : 'code'
   let content = md.utils.escapeHtml(token.content)
   const lineStrategy = opt.customHighlight.lineFeatureStrategy
   const needLineNumber = lineStrategy === 'hybrid' && opt.setLineNumber && startNumber >= 0
   const needEndSpan = lineStrategy === 'hybrid' && opt.lineEndSpanThreshold > 0
+  const needAdvancedLineNumberPlan = needLineNumber && (lineNumberSkipValue !== undefined || lineNumberSetValue !== undefined)
+  const needLineNotes = lineStrategy !== 'disable' && !!(lineNotes && lineNotes.length)
+  const logicalLineCount = (needAdvancedLineNumberPlan || needLineNotes)
+    ? getLogicalLineCount(token.content)
+    : -1
   let lineNumberPlan = null
-  if (needLineNumber && (lineNumberSkipValue !== undefined || lineNumberSetValue !== undefined)) {
-    const logicalLineCount = getLogicalLineCount(token.content)
+  if (needAdvancedLineNumberPlan) {
     lineNumberPlan = resolveAdvancedLineNumberPlan(lineNumberSkipValue, lineNumberSetValue, logicalLineCount, logicalLineCount)
   }
-  if (needLineNumber || needEndSpan) {
+  const lineNotePlan = needLineNotes
+    ? resolveLineNotesPlan(lineNotes, logicalLineCount, logicalLineCount, lineNoteIdPrefix)
+    : null
+  if (needLineNumber || needEndSpan || lineNotePlan) {
     const splitStartedAt = timings ? getNowMs() : 0
     const nlIndex = content.indexOf('\n')
     const br = nlIndex > 0 && content[nlIndex - 1] === '\r' ? '\r\n' : '\n'
-    content = splitFenceBlockToLines(content, [], needLineNumber, false, needEndSpan, opt.lineEndSpanThreshold, opt.lineEndSpanClass, br, undefined, commentLineClass, lineNumberPlan)
+    content = splitFenceBlockToLines(content, [], needLineNumber, false, needEndSpan, opt.lineEndSpanThreshold, opt.lineEndSpanClass, br, undefined, commentLineClass, lineNumberPlan, lineNotePlan)
     if (timings) addTimingMs(timings, 'lineSplitMs', getNowMs() - splitStartedAt)
   }
 
@@ -88,7 +98,8 @@ const renderFenceApiOrPlain = (token, lang, md, opt, slf, env, startNumber, emph
 
   if (preAttrs.length) orderTokenAttrs({ attrs: preAttrs }, opt)
   const preAttrsText = preAttrs.length ? slf.renderAttrs({ attrs: preAttrs }) : ''
-  const html = `<pre${preAttrsText}><${tag}${slf.renderAttrs(token)}>${content}</${tag}></pre>\n`
+  const preHtml = `<pre${preAttrsText}><${tag}${slf.renderAttrs(token)}>${content}</${tag}></pre>`
+  const html = wrapFencePreWithLineNotes(preHtml, lineNotePlan)
   return inlinePayloadScript ? html + inlinePayloadScript : html
 }
 
@@ -105,6 +116,9 @@ const getFenceHtml = (context, md, opt, slf, env) => {
   const wrapEnabled = context.wrapEnabled
   const preWrapValue = context.preWrapValue
   const commentMarkValue = context.commentMarkValue
+  const lineNotes = context.lineNotes
+  const lineNoteIdPrefix = context.lineNoteIdPrefix
+  const isSamp = context.isSamp
 
   const apiDecisionBase = {
     renderer: 'api',
@@ -112,16 +126,17 @@ const getFenceHtml = (context, md, opt, slf, env) => {
     fallbackUsed: false,
     lineFeatureStrategy: opt.customHighlight.lineFeatureStrategy,
     disabledFeatures: opt.customHighlight.lineFeatureStrategy === 'disable'
-      ? ['setLineNumber', 'line-number-skip', 'line-number-set', 'lineEndSpanThreshold']
+      ? apiDisableLineFeatureList
       : [],
   }
   try {
-    const html = renderFenceApiOrPlain(token, lang, md, opt, slf, env, startNumber, emphasizeLines, lineNumberSkipValue, lineNumberSetValue, wrapEnabled, preWrapValue, commentMarkValue, true, timings)
+    const html = renderFenceApiOrPlain(token, lang, isSamp, md, opt, slf, env, startNumber, emphasizeLines, lineNumberSkipValue, lineNumberSetValue, wrapEnabled, preWrapValue, commentMarkValue, lineNotes, lineNoteIdPrefix, true, timings)
     if (timingEnabled) apiDecisionBase.timings = finalizeFenceTimings(timings, fenceStartedAt)
     emitFenceDecision(opt, apiDecisionBase)
     return html
   } catch (err) {
-    if (opt.customHighlight.fallback === 'plain' && shouldApplyApiFallbackForReason(opt.customHighlight, 'provider-error')) {
+    if (!shouldApplyApiFallbackForReason(opt.customHighlight, 'provider-error')) throw err
+    if (opt.customHighlight.fallback === 'plain') {
       const fallbackDecision = {
         renderer: 'api',
         includePayload: false,
@@ -130,7 +145,7 @@ const getFenceHtml = (context, md, opt, slf, env) => {
         reason: 'provider-error',
         lineFeatureStrategy: opt.customHighlight.lineFeatureStrategy,
       }
-      const html = renderFenceApiOrPlain(token, lang, md, opt, slf, env, startNumber, emphasizeLines, lineNumberSkipValue, lineNumberSetValue, wrapEnabled, preWrapValue, commentMarkValue, false, timings)
+      const html = renderFenceApiOrPlain(token, lang, isSamp, md, opt, slf, env, startNumber, emphasizeLines, lineNumberSkipValue, lineNumberSetValue, wrapEnabled, preWrapValue, commentMarkValue, lineNotes, lineNoteIdPrefix, false, timings)
       if (timingEnabled) fallbackDecision.timings = finalizeFenceTimings(timings, fenceStartedAt)
       emitFenceDecision(opt, fallbackDecision)
       return html

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

@@ -4,6 +4,9 @@ import {
   getPayloadMapFromScript,
   styleToHighlightCss,
 } from '../custom-highlight/runtime-utils.js'
+import {
+  sanitizeHighlightName,
+} from '../custom-highlight/scope-name.js'
 import {
   customHighlightAppliedAttr,
   customHighlightAppliedSelector,
@@ -19,17 +22,6 @@ const globalRuntimeInsertedScopeStyles = new Map()
 const runtimeInsertedScopeStylesByDoc = new WeakMap()
 const runtimeApplyStateByRoot = new WeakMap()
 const validColorSchemeSet = new Set(['light', 'dark', 'auto'])
-const highlightNameUnsafeReg = /[^A-Za-z0-9_-]+/g
-const hyphenMultiReg = /-+/g
-
-const sanitizeHighlightName = (name) => {
-  const raw = String(name || '')
-  let safe = raw.replace(highlightNameUnsafeReg, '-').replace(hyphenMultiReg, '-').replace(/^-+|-+$/g, '')
-  if (!safe) safe = 'scope'
-  if (/^[0-9]/.test(safe)) safe = 'x-' + safe
-  if (safe.startsWith('--')) safe = safe.slice(2) || 'scope'
-  return safe
-}
 
 const getCustomHighlightBlockId = (node) => {
   if (!node || typeof node.getAttribute !== 'function') return null
@@ -133,10 +125,10 @@ const addMediaQueryChangeListener = (queryList, listener) => {
 }
 
 const getRuntimeSupportedPayloadVersions = (options = {}) => {
-  const set = new Set()
   if (options.strictVersion === true) {
-    for (const v of customHighlightPayloadSupportedVersions) set.add(v)
+    return new Set(customHighlightPayloadSupportedVersions)
   }
+  const set = new Set()
   if (Number.isSafeInteger(options.supportedVersion)) set.add(options.supportedVersion)
   if (Array.isArray(options.supportedVersions)) {
     for (const v of options.supportedVersions) {

package/src/fence/render-api.js

@@ -7,6 +7,9 @@ import {
   finalizeCommonFenceOption,
   prepareFenceRenderContext,
 } from './render-shared.js'
+import {
+  installLineNotesCoreRule,
+} from './line-notes.js'
 import {
   customHighlightDataEnvKey,
   customHighlightEnvInitRuleName,
@@ -37,6 +40,9 @@ const shouldRuntimeFallback = (reason, opt = {}) => {
   return shouldApplyApiFallbackForReason(chOpt, reason)
 }
 
+const customHighlightEnvInitInstalledKey = '__rendererFenceCustomHighlightEnvInitInstalled'
+const customHighlightEnvInitOptionKey = '__rendererFenceCustomHighlightEnvInitOption'
+
 const mditRendererFenceCustomHighlight = (md, option) => {
   const opt = {
     ...createCommonFenceOptionDefaults(md),
@@ -66,25 +72,31 @@ const mditRendererFenceCustomHighlight = (md, option) => {
     opt.customHighlight._hasShikiHighlighter = !!(opt.customHighlight.highlighter && typeof opt.customHighlight.highlighter.codeToTokens === 'function')
     const tokenOptionBase = {}
     if (opt.customHighlight._singleTheme) tokenOptionBase.theme = opt.customHighlight._singleTheme
-    if (opt.customHighlight.shikiScopeMode === 'semantic' || opt.customHighlight.shikiScopeMode === 'keyword') {
+    if (opt.customHighlight.shikiScopeMode === 'semantic' || opt.customHighlight.shikiScopeMode === 'role') {
       tokenOptionBase.includeExplanation = 'scopeName'
     }
     opt.customHighlight._shikiTokenOptionBase = Object.keys(tokenOptionBase).length ? tokenOptionBase : null
   }
 
   finalizeCommonFenceOption(opt)
+  installLineNotesCoreRule(md)
 
-  md.core.ruler.before('block', customHighlightEnvInitRuleName, (state) => {
-    const env = state && state.env
-    if (!env || typeof env !== 'object') return
-    if (opt.customHighlight.transport === 'env') {
-      env[customHighlightDataEnvKey] = {}
-      env[customHighlightSeqEnvKey] = 0
-      return
-    }
-    delete env[customHighlightDataEnvKey]
-    delete env[customHighlightSeqEnvKey]
-  })
+  md[customHighlightEnvInitOptionKey] = opt.customHighlight
+  if (!md[customHighlightEnvInitInstalledKey]) {
+    md[customHighlightEnvInitInstalledKey] = true
+    md.core.ruler.before('block', customHighlightEnvInitRuleName, (state) => {
+      const env = state && state.env
+      if (!env || typeof env !== 'object') return
+      const chOpt = md[customHighlightEnvInitOptionKey]
+      if (chOpt && chOpt.transport === 'env') {
+        env[customHighlightDataEnvKey] = {}
+        env[customHighlightSeqEnvKey] = 0
+        return
+      }
+      delete env[customHighlightDataEnvKey]
+      delete env[customHighlightSeqEnvKey]
+    })
+  }
 
   md.renderer.rules.fence = (tokens, idx, options, env, slf) => {
     const context = prepareFenceRenderContext(tokens, idx, opt)