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

package/README.md

@@ -1,8 +1,8 @@
 # p7d-markdown-it-renderer-fence
 
-A `markdown-it` plugin for code block rendering and enhancements.
+A `markdown-it` fence renderer for safer `<pre><code>` / `<pre><samp>` output, line features, optional syntax highlighting, and advanced Custom Highlight API integration.
 
-Default is `markup` mode. Custom Highlight API mode is available as an advanced/experimental path.
+Default mode is **markup**. Custom Highlight API mode is available for advanced browser-runtime highlighting.
 
 ## Install
 
@@ -10,32 +10,15 @@ Default is `markup` mode. Custom Highlight API mode is available as an advanced/
 npm i @peaceroad/markdown-it-renderer-fence markdown-it markdown-it-attrs
 ```
 
-If you use syntax highlighting, install a highlighter too (for example `highlight.js` or `shiki`).
+Install a highlighter separately when you need syntax highlighting, for example `highlight.js` or `shiki`.
 
-## Entry Points
-
-- `@peaceroad/markdown-it-renderer-fence`  
-  Dispatcher entry (`highlightRenderer` selects mode).
-- `@peaceroad/markdown-it-renderer-fence/markup-highlight`  
-  Markup-focused entry.
-- `@peaceroad/markdown-it-renderer-fence/custom-highlight`  
-  API-mode entry + runtime/payload helpers.
-- `@peaceroad/markdown-it-renderer-fence/custom-highlight-runtime`  
-  Runtime-only entry (`applyCustomHighlights` / `observeCustomHighlights` / `clearCustomHighlights`).
-
-## Markup Mode (Default)
-
-### Quick Start
-
-Dispatcher entry:
+## Quick Start (Markup Mode)
 
 ```js
 import MarkdownIt from 'markdown-it'
 import markdownItAttrs from 'markdown-it-attrs'
 import hljs from 'highlight.js'
-import rendererFence from '@peaceroad/markdown-it-renderer-fence'
-// Markup-only entry (skips dispatcher/API branch):
-// import rendererFence from '@peaceroad/markdown-it-renderer-fence/markup-highlight'
+import rendererFence from '@peaceroad/markdown-it-renderer-fence/markup-highlight'
 
 const md = MarkdownIt({
   html: true,
@@ -50,53 +33,31 @@ const md = MarkdownIt({
   },
 })
   .use(markdownItAttrs)
-  .use(rendererFence) // defaults to markup; direct markup entry can be leaner
+  .use(rendererFence)
 ```
 
-### Markup with Shiki
+### Shiki in Markup Mode
 
-Use the markup-only entry and provide `md.options.highlight` with Shiki.
-For production/blog builds, pre-scan markdown and preload only used languages.
+Preload the languages you render, then return Shiki HTML from `md.options.highlight`.
 
 ```js
 import MarkdownIt from 'markdown-it'
 import markdownItAttrs from 'markdown-it-attrs'
 import { createHighlighter } from 'shiki'
 import rendererFence from '@peaceroad/markdown-it-renderer-fence/markup-highlight'
-import fs from 'node:fs'
-import path from 'node:path'
-
-const fenceInfoReg = /^```([^\s`{]+)/gm
-const collectFenceLangs = (markdown) => {
-  const out = new Set()
-  if (!markdown) return out
-  let m
-  while ((m = fenceInfoReg.exec(markdown)) !== null) {
-    const lang = String(m[1] || '').trim().toLowerCase()
-    if (lang) out.add(lang)
-  }
-  return out
-}
-
-// Example: scan markdown source(s) before highlighter creation
-const markdown = fs.readFileSync(path.join(process.cwd(), 'article.md'), 'utf8')
-const langs = Array.from(collectFenceLangs(markdown))
-langs.push('text') // safe fallback
 
 const highlighter = await createHighlighter({
   themes: ['github-light'],
-  langs, // preload grammars; Shiki does not auto-detect language
+  langs: ['javascript', 'typescript', 'json', 'text'],
 })
 
 const md = MarkdownIt({
   html: true,
   langPrefix: 'language-',
   highlight: (code, lang) => {
-    const targetLang = lang || 'text'
     try {
-      return highlighter.codeToHtml(code, { lang: targetLang, theme: 'github-light' })
+      return highlighter.codeToHtml(code, { lang: lang || 'text', theme: 'github-light' })
     } catch (e) {
-      // when lang grammar is not loaded (or invalid), keep output safe
       return md.utils.escapeHtml(code)
     }
   },
@@ -105,133 +66,75 @@ const md = MarkdownIt({
   .use(rendererFence)
 ```
 
-Note:
-
-- For small projects, a fixed list like `['javascript', 'typescript', 'json', 'text']` is also fine.
-- If Shiki grammar for a language is not loaded, `codeToHtml` can fail.
-- In markup mode, handle this in your `highlight` callback (for example fallback to escaped plain text as above).
-
-### Main Features
-
-- `samp` rendering for `samp`, `shell`, `console` languages.
-- line number wrapping via `start` (`line-number-start` long form) / `data-pre-start`.
-- line number skip/set controls via `line-number-skip` / `line-number-set`.
-- emphasized lines via `em-lines` / `emphasize-lines`.
-- optional line-end spacer via `lineEndSpanThreshold`.
-- optional pre-wrap support via `wrap` / `pre-wrap`.
-- comment line markers via `comment-mark`.
-- sidecar line notes via immediate `line-notes` fence (`notes` alias).
-
-### Fence Attribute Examples
-
-Simplified HTML below focuses on renderer-fence structure (not full highlighter token spans).
-
-`samp` conversion:
-
-~~~md
-```shell
-$ pwd
-```
-~~~
-
-```html
-<pre><samp class="language-shell">$ pwd
-</samp></pre>
-```
+## Entry Points
 
-Line numbers:
+| Import | Purpose |
+| --- | --- |
+| `@peaceroad/markdown-it-renderer-fence` | compatibility dispatcher; `highlightRenderer` selects mode |
+| `@peaceroad/markdown-it-renderer-fence/markup-highlight` | markup-only renderer path |
+| `@peaceroad/markdown-it-renderer-fence/custom-highlight` | Custom Highlight API renderer + payload/runtime helpers |
+| `@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 |
+
+Use `@peaceroad/markdown-it-renderer-fence/theme/rf-basic` for JavaScript helpers. CSS assets are exposed as CSS subpaths.
+
+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`
+- `theme/rf-basic/markup/shiki.css`
+- `theme/rf-basic/markup/highlightjs.css`
+- `theme/rf-monochrome.css`
+- `theme/rf-monochrome/markup/highlightjs.css`
+- `theme/rf-monochrome/markup/shiki.css`
+
+The plugin does not auto-load CSS or browser runtime JavaScript.
+
+## Features
+
+- markup mode with highlighter-owned HTML (`md.options.highlight`)
+- `<samp>` rendering for `samp`, `shell`, and `console` fence languages
+- per-fence `{samp}` / `{code}` tag overrides
+- line numbers via `start` / `line-number-start`
+- advanced line-number controls via `line-number-skip` / `line-number-set`
+- emphasized lines via `em-lines` / `emphasize-lines`
+- optional long-line spacer via `lineEndSpanThreshold`
+- optional pre-wrap via `{wrap}` / `{pre-wrap}`
+- comment markers via `comment-mark`
+- sidecar line notes via an immediate `line-notes` fence (`notes` alias)
+- advanced Custom Highlight API mode for span-free code text plus browser-applied ranges
+- optional first-party theme CSS and Shiki/provider helper exports
+
+## Fence Attribute Examples
 
 ~~~md
-```js {start="1"}
+```js {start="1" em-lines="2"}
 const a = 1
 console.log(a)
 ```
 ~~~
 
-```html
-<pre><code class="language-js" data-pre-start="1" style="counter-set:pre-line-number 1;">
-<span class="pre-line">const a = 1</span>
-<span class="pre-line">console.log(a)</span>
-</code></pre>
-```
-
-Advanced line number control:
-
-~~~md
-```txt {start="25" line-number-skip="5" line-number-set="6:136"}
-line1
-line2
-line3
-line4
-...
-line6
-```
-~~~
-
-```html
-<pre><code class="language-txt" data-pre-start="25" data-pre-line-number-skip="5" data-pre-line-number-set="6:136" style="counter-set:pre-line-number 25;">
-<span class="pre-line">line1</span>
-<span class="pre-line">line2</span>
-<span class="pre-line">line3</span>
-<span class="pre-line">line4</span>
-<span class="pre-line pre-line-no-number">...</span>
-<span class="pre-line" style="counter-set:pre-line-number 136;">line6</span>
-</code></pre>
-```
-
-Emphasis:
-
-~~~md
-```js {em-lines="2,4-5"}
-line1
-line2
-line3
-line4
-line5
-```
-~~~
-
-```html
-<pre><code class="language-js" data-pre-emphasis="2,4-5">line1
-<span class="pre-lines-emphasis">line2</span>
-line3
-<span class="pre-lines-emphasis">line4
-line5</span>
-</code></pre>
-```
-
-Wrap:
-
 ~~~md
-```js {wrap}
-const veryLongLine = '...'
+```bash {samp comment-mark="#"}
+# setup
+export NODE_ENV=test
 ```
 ~~~
 
-```html
-<pre data-pre-wrap="true" style="white-space: pre-wrap; overflow-wrap: anywhere;">
-<code class="language-js">const veryLongLine = '...'
-</code></pre>
-```
-
-Comment line marker:
-
 ~~~md
-```samp {comment-mark="#"}
-# comment
-echo 1
+```shell {code}
+# render as <code> even though shell is normally sampLang
 ```
 ~~~
 
-```html
-<pre><samp data-pre-comment-mark="#" class="language-samp">
-<span class="pre-line-comment"># comment</span>
-echo 1
-</samp></pre>
-```
-
-Line notes:
-
 ~~~md
 ```js {start="5"}
 const a = 1
@@ -239,135 +142,56 @@ console.log(a)
 ```
 ```line-notes
 1: setup {width="7em"}
-2：result {width="10em"}
+2: result {width="10em"}
 ```
 ~~~
 
-```html
-<div class="pre-wrapper-line-notes" data-pre-line-notes-layout="anchor"><pre><code class="language-js" data-pre-start="5" data-pre-line-notes="true" style="counter-set:pre-line-number 5;"><span class="pre-line pre-line-has-end-note" data-pre-line-note-from="1" data-pre-line-note-to="1"><span class="pre-line-content" style="anchor-name:--pre-line-note-1;" aria-describedby="pre-line-note-1-1-1">const a = 1</span></span>
-<span class="pre-line pre-line-has-end-note" data-pre-line-note-from="2" data-pre-line-note-to="2"><span class="pre-line-content" style="anchor-name:--pre-line-note-2;" aria-describedby="pre-line-note-1-1-2">console.log(a)</span></span>
-</code></pre><div class="pre-line-note-layer"><div id="pre-line-note-1-1-1" class="pre-line-note" role="note" data-pre-line-note-from="1" data-pre-line-note-to="1" data-pre-line-note-label="1" style="position-anchor:--pre-line-note-1; --line-note-width:7em;">setup</div><div id="pre-line-note-1-1-2" class="pre-line-note" role="note" data-pre-line-note-from="2" data-pre-line-note-to="2" data-pre-line-note-label="2" style="position-anchor:--pre-line-note-2; --line-note-width:10em;">result</div></div></div>
-```
-
-### Markup Notes
-
-- `useHighlightPre: true` keeps highlighter-provided `<pre><code>` when present.
-- In that passthrough path, line-splitting features are intentionally disabled:
-  - line numbers
-  - `line-number-skip`
-  - `line-number-set`
-  - `em-lines`
-  - line-end spacer
-  - `comment-mark`
-  - `line-notes`
-  - `samp` conversion
-
-Reference line-number CSS contract:
-
-Minimum counter contract:
-
-```css
-pre :is(code, samp)[data-pre-start] .pre-line::before {
-  content: counter(pre-line-number);
-}
-
-pre :is(code, samp)[data-pre-start] .pre-line::after {
-  content: "";
-  counter-increment: pre-line-number;
-}
-
-pre :is(code, samp)[data-pre-start] .pre-line.pre-line-no-number::before {
-  content: "";
-}
-
-pre :is(code, samp)[data-pre-start] .pre-line.pre-line-no-number::after {
-  counter-increment: none;
-}
-```
-
-Recommended display CSS:
-
-- See [`example/line-number.css`](./example/line-number.css) for the full reference stylesheet.
-- See [`example/line-number-sample.html`](./example/line-number-sample.html) for Markdown / Preview / HTML side-by-side examples.
-- See [`example/line-notes.css`](./example/line-notes.css) for the companion line-note stylesheet.
-- See [`example/line-notes-sample.html`](./example/line-notes-sample.html) for sidecar line-note examples.
-
-Note:
-
-- renderer-fence emits `counter-set` as the displayed line number value itself
-- the reference CSS increments the counter in `span.pre-line::after`, so `start="1"` maps directly to `counter-set:pre-line-number 1;`
-- `line-number-set="6:136"` similarly emits `counter-set:pre-line-number 136;` on that line wrapper
-- the minimum contract above is the required part; `example/line-number.css` adds gutter width, divider line, and whitespace handling
-- if a consumer uses a different counter strategy, its CSS must be aligned with this HTML contract
-
-### Markup Options
-
-- `attrsOrder` (default: `['class', 'id', 'data-*', 'style']`): output attribute order (`data-*` wildcard supported).
-- `setHighlight` (default: `true`): call `md.options.highlight` when available.
-- `setLineNumber` (default: `true`): enable line wrapper spans when `start` / `line-number-start` is valid.
-- `setEmphasizeLines` (default: `true`): enable `em-lines` / `emphasize-lines`.
-- `lineEndSpanThreshold` (default: `0`): append line-end spacer span when visual width threshold is met.
-- `setLineEndSpan`: alias of `lineEndSpanThreshold`.
-- `lineEndSpanClass` (default: `'pre-lineend-spacer'`): CSS class of the spacer span.
-- `setPreWrapStyle` (default: `true`): inject inline pre-wrap style for wrap-enabled blocks.
-- `sampLang` (default: `'shell,console'`): additional fence langs rendered as `<samp>`.
-- `langPrefix` (default: `md.options.langPrefix || 'language-'`): class prefix for language class.
-- `useHighlightPre` (default: `false`): passthrough highlighter `<pre><code>` wrappers and skip line-splitting features.
-- `onFenceDecision` (default: `null`): debug hook for per-fence branch decisions.
-- `onFenceDecisionTiming` (default: `false`): include timing fields in `onFenceDecision`.
-
-`em-lines` syntax note:
-
-- supports single values (`2`) and ranges (`4-6`)
-- supports open-ended forms (`3-`, `-2`)
-- reversed ranges are normalized (`5-3` behaves as `3-5`)
-
-Line-number attr syntax note:
-
-- `line-number-start` is the long form of `start`; rendered output still uses `data-pre-start`.
-- `line-number-skip` supports single values (`2`), ranges (`4-6`), and open-ended forms (`3-`).
-- `line-number-set` uses `line:number` pairs (for example `6:136,14:220`).
-- `line-number-skip` and `line-number-set` must not target the same source line. If they overlap, the skipped line stays blank and the conflicting `line-number-set` entry is ignored.
-- `line-number-skip` / `line-number-set` are applied only when source and highlighted logical line counts match; otherwise renderer falls back to plain sequential numbering.
-
-Line-note syntax note:
-
-- `line-notes` is the canonical sidecar fence name; `notes` is a short alias.
-- Sidecar notes are folded only when they immediately follow a code/samp fence.
-- Immediate sidecar folding is fail-closed: if any non-empty line is malformed, a note entry is incomplete, or the same note start line appears twice, the `line-notes` fence stays as a normal literal fence block.
-- Syntax supports `N: text`, `N-M: text`, `N：text`, and `N-M：text`.
-- Per-note attrs can be appended in markdown-it-attrs style on the same line for single-line notes, for example `5: cache lookup key {width="8rem"}`.
-- For multiline notes, prefer a trailing attrs-only continuation line, for example `  {width="11rem"}`.
-- Continuation lines start with indentation (`  ` or tab) and append multiline note text to the previous note.
-- Output keeps note text outside `<code>/<samp>` in a sibling note layer for safer copy semantics.
-- Line-note blocks use the external wrapper contract `pre-wrapper-line-notes`.
-- `data-pre-line-notes-layout="anchor"` is added only for simple non-overlapping note layouts. The current check is intentionally lightweight: it uses the note start line plus the note text's explicit logical line count, so a two-line note starting at line `3` prevents another anchored note from starting at line `4`.
-- This anchor-safety check does not measure CSS wrapping. If a note wraps because of narrow CSS width, consumer CSS should still be prepared to fall back to a below-block list.
-- When anchor positioning is unavailable or the layout is not marked safe, consumer CSS should render notes as a below-block list. The reference stylesheet uses `data-pre-line-note-label` so the fallback still shows which source line each note belongs to.
-- In anchor layouts, the rendered line HTML carries note metadata on `.pre-line`, and the anchor itself is attached to `.pre-line-content` so notes can start from the rendered code end.
-- Accessibility contract: the rendered `.pre-line-content` carries `aria-describedby`, and each note item renders with a stable `id` plus `role="note"`, so assistive tech can associate the note text with its anchor line.
-- When a sidecar fence is folded, the previous fence token `map` is extended to cover the absorbed note-fence lines so editor scroll/jump integrations can still treat the merged output as one source span.
-- `line-notes` are applied only when source and highlighted logical line counts match; otherwise note markup is skipped.
-
-Migration note (`0.5.0`):
-
-- `comment-line` / `data-pre-comment-line` / `pre-comment-line` were removed
-- use `comment-mark` / `data-pre-comment-mark` / `pre-line-comment`
-- `line-number-reset` was removed; use `line-number-set`
-
-## Custom Highlight API Mode (Experimental / Advanced)
-
-Custom Highlight API mode renders plain code text and emits range payloads for browser-side Custom Highlight API application.
-
-Important:
-
-- You must run runtime apply in the browser (`applyCustomHighlights` or `observeCustomHighlights`).
-- Without runtime apply, payload exists but browser highlights are not activated.
-- `test/custom-highlight/pre-highlight.js` is a demo helper, not the package runtime API contract.
-
-Use API mode only if you need runtime range highlighting and can manage runtime/CSS integration in your app.
-
-### Minimal API Example (Shiki provider)
+For emitted HTML contracts and visual samples, see the files listed in [Docs and Examples](#docs-and-examples).
+
+## Main Options
+
+### Markup / shared options
+
+| Option | Summary |
+| --- | --- |
+| `attrsOrder` | output attribute order; supports `data-*` wildcard |
+| `setHighlight` | call `md.options.highlight` when available |
+| `setLineNumber` | enable line wrapping when `start` / `line-number-start` is valid |
+| `setEmphasizeLines` | enable `em-lines` / `emphasize-lines` |
+| `lineEndSpanThreshold` | append line-end spacer spans for visually long lines |
+| `setLineEndSpan` | alias of `lineEndSpanThreshold` |
+| `lineEndSpanClass` | CSS class for line-end spacer spans |
+| `setPreWrapStyle` | inject inline pre-wrap style for wrap-enabled blocks |
+| `sampLang` | comma-separated languages rendered as `<samp>`; default: `shell,console` |
+| `{samp}` / `{code}` | per-fence tag override attrs |
+| `langPrefix` | language class prefix; defaults to `md.options.langPrefix || 'language-'` |
+| `useHighlightPre` | preserve highlighter-owned `<pre><code>` wrappers; disables line-splitting features |
+| `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. Emphasis ranges are normalized before rendering: reversed ranges are corrected, ranges are sorted, and overlapping or adjacent ranges are coalesced.
+
+### Custom Highlight API options
+
+| Option | Summary |
+| --- | --- |
+| `highlightRenderer` | dispatcher mode: `markup`, `api`, or `custom-highlight-api` |
+| `customHighlight.provider` | `shiki`, `hljs`, or `custom` |
+| `customHighlight.highlighter` | Shiki highlighter with synchronous `codeToTokens` |
+| `customHighlight.hljsHighlight` | highlight.js-style function for the `hljs` provider |
+| `customHighlight.getRanges` | synchronous custom range provider |
+| `customHighlight.theme` | Shiki theme name or `{ light, dark, default? }` |
+| `customHighlight.shikiScopeMode` | `auto`, `color`, `semantic`, or `role` |
+| `customHighlight.includeScopeStyles` | include payload `scopeStyles` when available |
+| `customHighlight.transport` | `env` or `inline-script` |
+| `customHighlight.fallback` | provider-error fallback: `plain` or `markup` |
+| `customHighlight.lineFeatureStrategy` | `hybrid` or `disable` |
+
+For detailed API-mode styling, runtime, role-mode, and payload guidance, see [Custom Highlight Styling Guide](docs/custom-highlight-styling-guide.md) and [Code Highlighting Design](docs/code-highlighting-design.md).
+
+## Custom Highlight API Mode
+
+API mode renders escaped code text and emits payload ranges. It does **not** activate browser highlights by itself; call the runtime in the browser.
 
 ```js
 import MarkdownIt from 'markdown-it'
@@ -377,211 +201,73 @@ import rendererFenceApi, {
   applyCustomHighlights,
   renderCustomHighlightPayloadScript,
 } from '@peaceroad/markdown-it-renderer-fence/custom-highlight'
-// Dispatcher entry alternative:
-// import rendererFenceApi from '@peaceroad/markdown-it-renderer-fence'
+import {
+  createRfBasicShikiRoleCustomHighlightOptions,
+  rfBasicShikiTheme,
+  rfBasicThemeName,
+} from '@peaceroad/markdown-it-renderer-fence/theme/rf-basic'
 
 const highlighter = await createHighlighter({
-  themes: ['github-light'],
-  langs: ['javascript', 'typescript', 'json'], // preload grammars; Shiki does not auto-detect language
+  themes: [rfBasicShikiTheme],
+  langs: ['javascript', 'typescript', 'json'],
 })
 
 const md = MarkdownIt({ html: true })
   .use(markdownItAttrs)
   .use(rendererFenceApi, {
-    // highlightRenderer: 'api', // required only with dispatcher entry
-    customHighlight: {
-      provider: 'shiki',
+    customHighlight: createRfBasicShikiRoleCustomHighlightOptions({
       highlighter,
-      theme: 'github-light',
+      theme: rfBasicThemeName,
       transport: 'env',
-    },
+    }),
   })
 
 const env = {}
-const html = md.render('```js\nconst x = 1\n```', env)
-const payloadScript = renderCustomHighlightPayloadScript(env) // id="pre-highlight-data"
-```
+const html = md.render('```js
+const x = 1
+```', env)
+const payloadScript = renderCustomHighlightPayloadScript(env)
 
-Browser-side apply:
-
-```js
+// Browser side:
 applyCustomHighlights(document)
 ```
 
-When using `colorScheme: 'auto'`, scheme resolution happens at apply time.
-If OS/browser theme changes after first apply, re-run apply (or use observer watch mode below).
-
-If you only need runtime apply on the browser, import runtime-only entry:
+For lazy apply and color-scheme watching:
 
 ```js
 import { observeCustomHighlights } from '@peaceroad/markdown-it-renderer-fence/custom-highlight-runtime'
-```
-
-`langs` note:
-
-- `createHighlighter({ langs: [...] })` should include the languages you expect to render.
-- Shiki does not auto-detect language from code text.
-- if a target language is not loaded, this plugin falls back to Shiki `text` tokenization for that block (safe, but no syntax color buckets).
-
-### Minimal API Example (highlight.js provider)
-
-```js
-import MarkdownIt from 'markdown-it'
-import markdownItAttrs from 'markdown-it-attrs'
-import hljs from 'highlight.js'
-import rendererFenceApi from '@peaceroad/markdown-it-renderer-fence/custom-highlight'
-// Dispatcher entry alternative:
-// import rendererFenceApi from '@peaceroad/markdown-it-renderer-fence'
-
-const md = MarkdownIt({ html: true })
-  .use(markdownItAttrs)
-  .use(rendererFenceApi, {
-    // highlightRenderer: 'api', // required only with dispatcher entry
-    customHighlight: {
-      provider: 'hljs',
-      hljsHighlight: (code, lang) => {
-        if (lang && hljs.getLanguage(lang)) {
-          return hljs.highlight(code, { language: lang }).value
-        }
-        return hljs.highlight(code, { language: 'plaintext' }).value
-      },
-      transport: 'env',
-    },
-  })
-```
-
-### API Providers
-
-- `customHighlight.provider: 'shiki'`  
-  Requires `customHighlight.highlighter.codeToTokens(...)` (synchronous).
-- `customHighlight.provider: 'hljs'`  
-  Uses `customHighlight.hljsHighlight`, fallback to `customHighlight.highlight`, then `md.options.highlight`.
-- `customHighlight.provider: 'custom'`  
-  Escape hatch. Requires synchronous `customHighlight.getRanges(...)`.
-
-### Shiki Scope Modes
-
-- `auto` (default)
-- `color`
-- `semantic`
-- `keyword` (best for stable CSS-managed styling)
-
-Migration note (`0.5.0`):
-
-- legacy aliases like `json`, `bucket`, `keyword-only` are removed
-- use canonical values: `auto | color | semantic | keyword`
-
-Recommended production profile for API mode:
 
-```js
-customHighlight: {
-  provider: 'shiki',
-  shikiScopeMode: 'keyword',
-  includeScopeStyles: false
-}
-```
-
-### API Multi-Theme (Shiki, `v:1` additive payload)
-
-When you need runtime light/dark switching with Shiki color styles, pass object form theme:
-
-```js
-customHighlight: {
-  provider: 'shiki',
-  highlighter,
-  shikiScopeMode: 'color',
-  includeScopeStyles: true,
-  theme: {
-    light: 'github-light',
-    dark: 'github-dark',
-    default: 'light',
-  },
-}
-```
-
-Runtime apply can choose variant:
-
-```js
-applyCustomHighlights(document, { colorScheme: 'auto' }) // 'auto' | 'light' | 'dark'
-```
-
-Auto re-apply on color-scheme change:
-
-```js
 observeCustomHighlights(document, {
   applyOptions: { colorScheme: 'auto', incremental: true },
   watchColorScheme: true,
 })
 ```
 
-### CMS / Copy-Paste Operation
-
-If you copy rendered HTML+payload JSON into another CMS/page:
-
-- API mode works only when runtime JS is also available on that page.
-- payload JSON alone is not enough.
-- if the target CMS cannot run custom JS, use `markup` mode instead.
-- this plugin does not auto-generate/write runtime JS files during markdown render.
+Use markup mode instead when the target page cannot run runtime JavaScript.
 
-Practical patterns:
+## Theme
 
-1. Site/app with bundler  
-   Bundle `@peaceroad/markdown-it-renderer-fence/custom-highlight-runtime` and run `observeCustomHighlights(...)`.
-2. Static page with module scripts  
-   Load runtime entry via your ESM delivery path and call `applyCustomHighlights(...)`.
-3. HTML-only CMS (no JS injection)  
-   Use `markup` mode (API mode is not suitable).
+The optional preset theme is a package artifact, not an automatically loaded dependency.
 
-### CLI Build Artifact Contract
-
-For CLI/static generation, treat API mode output as two artifacts:
+```css
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-basic.css";
+```
 
-1. HTML artifact  
-   Includes `<pre data-pre-highlight="...">...</pre>` and payload JSON (`env` script or inline-script transport).
-2. Runtime artifact  
-   Browser JS that imports `@peaceroad/markdown-it-renderer-fence/custom-highlight-runtime` and runs `applyCustomHighlights(...)` or `observeCustomHighlights(...)`.
+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.
 
-Typical runtime bridge file:
+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.
 
-```js
-import { observeCustomHighlights } from '@peaceroad/markdown-it-renderer-fence/custom-highlight-runtime'
+For one-color print/monochrome output, use markup mode and import the opt-in monochrome override:
 
-observeCustomHighlights(document, {
-  applyOptions: { colorScheme: 'auto', incremental: true },
-  watchColorScheme: true,
-})
+```css
+@import "@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome.css";
 ```
 
-Then include that bridge in generated HTML:
+For theme design details, see [`theme/rf-basic/README.md`](theme/rf-basic/README.md) and [`theme/rf-monochrome/README.md`](theme/rf-monochrome/README.md).
 
-```html
-<script type="module" src="/assets/custom-highlight-runtime.js"></script>
-```
+## Helper Exports
 
-### API Options
-
-- `highlightRenderer` (`'markup' | 'api' | 'custom-highlight-api'`, default: `'markup'`): dispatcher mode selector (`/custom-highlight` entry does not need this).
-- `customHighlight.provider` (default: `'shiki'`): range source (`'shiki' | 'hljs' | 'custom'`).
-- `customHighlight.getRanges`: required when `provider: 'custom'`; must return synchronous ranges.
-- `customHighlight.highlighter`: Shiki highlighter object with synchronous `codeToTokens`.
-- `customHighlight.hljsHighlight`: highlight.js-style function used when `provider: 'hljs'`.
-- `customHighlight.highlight`: fallback highlight function for `hljs` provider.
-- `customHighlight.defaultLang`: default language when fence language is empty.
-- `customHighlight.theme`: Shiki theme name string, or object `{ light, dark, default? }` for dual-theme payload.
-- `customHighlight.shikiScopeMode` (default: `'auto'`): scope naming mode (`auto | color | semantic | keyword`).
-- `customHighlight.shikiKeywordClassifier`: custom classifier hook for keyword mode.
-- `customHighlight.shikiKeywordLangResolver`: custom language resolver hook for keyword mode.
-- `customHighlight.shikiKeywordLangAliases`: language alias map for keyword resolver.
-- `customHighlight.includeScopeStyles` (default: `true`): include payload `scopeStyles` when available.
-- `customHighlight.fallback` (`'plain' | 'markup'`, default: `'plain'`): server-side fallback renderer on provider errors.
-- `customHighlight.fallbackOn`: restrict fallback trigger reasons.
-- `customHighlight.transport` (`'env' | 'inline-script'`, default: `'env'`): payload transport target.
-- `customHighlight.idPrefix` (default: `'hl-'`): generated per-block payload id prefix.
-- `customHighlight.scopePrefix` (default: `'hl'`): scope name prefix used for highlight registration.
-- `customHighlight.lineFeatureStrategy` (`'hybrid' | 'disable'`, default: `'hybrid'`): keep or disable line-span features in API rendering.
-- In `NODE_ENV=development`, invalid known enum-like values and unknown `customHighlight` keys emit warn-once diagnostics while keeping normalized fallback behavior.
-
-### API Helper Exports
+From `@peaceroad/markdown-it-renderer-fence/custom-highlight`:
 
 - `applyCustomHighlights`
 - `observeCustomHighlights`
@@ -593,29 +279,52 @@ Then include that bridge in generated HTML:
 - `customHighlightPayloadSchemaVersion`
 - `customHighlightPayloadSupportedVersions`
 
-### Runtime Version Policy
+From `@peaceroad/markdown-it-renderer-fence/theme/rf-basic`:
+
+- `rfBasicShikiTheme`
+- `rfBasicThemeName`
+- `createRfBasicShikiTheme`
+- `createRfBasicShikiCustomHighlightOptions`
+- `createRfBasicShikiRoleCustomHighlightOptions`
+- `createRfBasicHighlightjsCustomHighlightOptions`
+- `rfBasicSyntaxCssVars`
+- `createRfBasicShikiRoleScopeColorVars`
 
-- `applyCustomHighlights(..., { strictVersion: true })` accepts only `customHighlightPayloadSupportedVersions` (currently `v:1`).
-- `supportedVersion` / `supportedVersions` allow explicit accepted payload versions.
-- If `strictVersion` is `true`, it takes precedence and custom accepted versions are ignored.
+From `@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome`:
+
+- `rfMonochromeShikiTheme`
+- `rfMonochromeShikiThemeName`
+- `rfMonochromeThemeName`
+- `createRfMonochromeShikiTheme`
 
 ## Docs and Examples
 
-- API styling guide: `docs/custom-highlight-styling-guide.md`
-- default preset CSS sample: `docs/default-highlight-theme.css`
-- provider matrix page: `example/custom-highlight-provider-matrix.html`
-- line-number sample: `example/line-number-sample.html`
-- line-notes sample: `example/line-notes-sample.html`
+- [Docs overview](docs/README.md)
+- [Code Highlighting Design](docs/code-highlighting-design.md)
+- [Custom Highlight Styling Guide](docs/custom-highlight-styling-guide.md)
+- [rf-basic Theme README](theme/rf-basic/README.md)
+- [rf-monochrome Theme README](theme/rf-monochrome/README.md)
+- [Example README](example/README.md)
+- `example/custom-highlight-provider-matrix.html`
+- `example/monochrome-highlight-compare.html`
+- `example/line-number-sample.html`
+- `example/line-notes-sample.html`
+- `example/samp-sample.html`
+
+Examples are demonstration and verification assets. Do not import runtime or theme helpers from `example/`; use the public package entry points above.
 
 ## Tests and Benchmarks
 
-- all tests: `npm test`
-- provider contract: `npm run test:provider:contract`
-- keyword coverage: `npm run test:provider:keyword`
-- keyword holdout parity: `npm run test:provider:keyword:holdout`
-- performance baseline: `npm run test:performance`
-- runtime apply benchmark: `npm run test:performance:runtime`
+```bash
+npm test
+npm run test:provider:contract
+npm run test:provider:role
+npm run test:provider:role:holdout
+npm run test:provider:matrix
+npm run test:performance
+npm run test:performance:runtime
+```
 
 ## License
 
-- Project license: MIT (`LICENSE`)
+MIT (`LICENSE`)