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

package/docs/README.md

@@ -0,0 +1,37 @@
+# Documentation
+
+This directory contains the long-form documentation for
+`@peaceroad/markdown-it-renderer-fence`.
+
+The top-level [README](../README.md) is intentionally a quick-start and API
+surface overview. Keep details here unless they are needed for first use.
+
+## Files
+
+- [Code Highlighting Design](code-highlighting-design.md)
+  - mode selection
+  - renderer/provider/runtime/theme responsibility boundaries
+  - Shiki role-mode policy
+  - theme packaging policy
+  - line-feature and performance trade-offs
+- [Custom Highlight Styling Guide](custom-highlight-styling-guide.md)
+  - API-mode color sources
+  - recommended Shiki/highlight.js profiles
+  - runtime apply and light/dark behavior
+  - preset CSS usage
+
+Theme-specific documentation lives next to each packaged theme:
+
+- [rf-basic Theme](../theme/rf-basic/README.md)
+- [rf-monochrome Theme](../theme/rf-monochrome/README.md)
+
+Repository examples are described in [example/README.md](../example/README.md).
+
+## Documentation ownership
+
+- Put runnable first-use snippets in the top-level README.
+- Put operational API-mode guidance in the styling guide.
+- Put durable design policy and maintenance trade-offs in the design document.
+- Put palette/file-role details in each theme README.
+- Keep generated example pages under `example/`; do not treat them as package
+  implementation dependencies.

package/docs/code-highlighting-design.md

@@ -0,0 +1,317 @@
+# Code Highlighting Design
+
+This document describes how code highlighting should be designed, configured, and maintained in this package.
+The README keeps the quick-start surface small; this document records the deeper policy and trade-offs.
+
+## 1. What This Plugin Owns
+
+`@peaceroad/markdown-it-renderer-fence` is a `markdown-it` fence renderer plugin.
+It is an integration layer around Markdown fence tokens, optional syntax highlighters, line features, and optional browser Custom Highlight API payloads.
+
+The plugin owns:
+
+- fence info/attribute normalization
+- safe `<pre><code>` / `<pre><samp>` rendering
+- integration with `md.options.highlight` in markup mode
+- optional API-mode payload generation from supported providers
+- line features such as line numbers, emphasized lines, comment marks, and sidecar line notes
+- fail-closed behavior when highlighted line counts or sidecar syntax cannot be mapped safely
+- optional preset CSS and provider option helpers
+
+The plugin does not own:
+
+- a full syntax parser for every language
+- asynchronous highlighter initialization inside `markdown-it` rendering
+- automatic CSS or runtime JavaScript injection into the host page
+- a huge language keyword database that tries to clone every upstream grammar
+- replacing Shiki or highlight.js as the primary syntax highlighter
+- importing runtime or theme implementation from `example/`
+
+This boundary is important: the best default is a stable renderer with good integration points, not a second highlighter implementation hidden inside a Markdown plugin.
+Examples may import public package entry points for demonstrations and generated comparison pages, but implementation and public integration helpers must remain independent from `example/`.
+
+## 2. Mode Selection
+
+Choose the renderer mode before choosing the theme.
+
+| Use case | Recommended mode | Why |
+| --- | --- | --- |
+| Static HTML, README-like output, blogs, docs sites | `markup` | Simple, portable HTML. No browser runtime required. |
+| Existing highlight.js or Shiki HTML output is enough | `markup` | Let the highlighter own token spans and CSS classes. |
+| You need `CSS.highlights` ranges and external runtime control | `api` | Produces escaped text plus payload ranges for browser-side application. |
+| You need cleaner copy behavior with line notes outside code text | `api` or markup with structural line features | API mode avoids highlighter spans in text; sidecar notes stay outside `<code>` / `<samp>`. |
+| You need theme-faithful Shiki colors | `api` + Shiki `color` or `semantic`, or markup Shiki | Keep Shiki as the color authority. |
+| You need CSS-managed light/dark buckets | `api` + Shiki `role` | Stable role buckets controlled by package/user CSS. |
+| You use normal highlight.js class CSS | `markup` | The highlight.js provider bridge is useful, but markup mode is usually simpler. |
+
+Defaulting to `markup` is intentional. API mode is advanced because it has a browser runtime contract.
+
+## 3. Markup Mode
+
+Markup mode is the default and should remain the recommended path for most users.
+
+In markup mode:
+
+1. the plugin normalizes fence attrs and language classes
+2. `md.options.highlight` may return escaped HTML, `<code>...</code>`, or `<pre><code>...</code>`
+3. the plugin merges safe wrapper attrs when possible
+4. line features are applied only when the output can be line-split safely
+
+Design rules:
+
+- Keep `md.options.highlight` as the highlighter boundary.
+- Do not require a package-specific highlighter helper for normal markup mode.
+- Treat `<samp>` as an output semantics decision, not as a syntax language. Use `sampLang` for site-wide terminal defaults and `{samp}` / `{code}` for per-fence overrides.
+- If `useHighlightPre` passes through highlighter-owned `<pre><code>`, structural line features must be skipped.
+- If the highlighted logical line count differs from the source logical line count, line-number controls, comment marks, and line notes must be skipped rather than mapped incorrectly.
+- Attribute parsing should be conservative; unusual highlighter wrapper HTML should fall back safely.
+
+Markup mode is the right choice when the output needs to work in static environments or when the host page already has highlighter CSS.
+
+## 4. Custom Highlight API Mode
+
+API mode is opt-in. It renders escaped code text and emits a payload describing highlight ranges.
+The browser then applies ranges with `CSS.highlights` through `applyCustomHighlights()` or `observeCustomHighlights()`.
+
+In API mode:
+
+1. provider output is normalized into ranges
+2. scope names are sanitized and de-collided
+3. payloads are emitted via `env` or inline JSON script transport
+4. the runtime applies ranges to `pre > code` and `pre > samp`
+5. optional CSS or payload `scopeStyles` controls visual color
+
+API mode is useful when:
+
+- a page wants text content to remain clean and span-free
+- line notes and other overlays should remain outside copied code text
+- a SPA can explicitly re-apply highlights after DOM updates
+- light/dark styling should be controlled by CSS variables and runtime variant selection
+
+API mode is not ideal when:
+
+- the host cannot load runtime JavaScript
+- the rendered HTML must be fully styled without post-processing
+- the highlighter already emits satisfactory HTML and CSS
+
+Runtime responsibilities should remain explicit. The Markdown render step should not automatically emit a general-purpose runtime script because bundlers, CSP policies, and page lifecycle rules differ across hosts.
+
+## 5. Provider Policy
+
+### Shiki Provider
+
+The Shiki provider requires a synchronous highlighter object with `codeToTokens`.
+Highlighter creation and language/theme loading are caller responsibilities.
+
+Supported Shiki scope modes:
+
+- `color`: derive scope names from Shiki theme colors; closest to theme-owned visual output
+- `semantic`: use more semantic Shiki explanation scopes; useful when users want scope-like names
+- `role`: map Shiki scopes and token text to stable rf-basic role buckets
+
+`role` mode is a CSS-managed role adapter, not a full replacement for Shiki's token taxonomy.
+It should be judged by practical visual role parity, not by one-to-one upstream scope identity.
+
+### highlight.js Provider
+
+The highlight.js provider converts highlight.js output into API payload ranges.
+It is a compatibility bridge for users who want API mode while using highlight.js.
+
+If normal highlight.js HTML is enough, prefer markup mode.
+That keeps highlight.js in its usual ownership model: markup classes plus CSS.
+
+### Custom Provider
+
+The custom provider is an escape hatch for precomputed ranges or application-specific highlighters.
+It must still follow the same payload invariants: valid range bounds, valid scope indexes, and safe sanitized scope names.
+
+## 6. Role Mode Policy
+
+Shiki `role` mode exists to provide stable CSS buckets such as:
+
+- `keyword`
+- `string`
+- `number`
+- `comment`
+- `type`
+- `title`
+- `variable`
+- `literal`
+- `tag`
+- `attribute`
+- `punctuation`
+- `text`
+
+The goal is broad visual parity with the package preset theme, not exhaustive grammar cloning.
+
+Rules for maintaining role mode:
+
+- Prefer role buckets over language-specific taxonomy.
+- Keep the bucket list small and themeable.
+- Use Shiki explanation scopes first, then token text and language-specific rules only when they clarify a role.
+- Do not classify all `keyword.operator` scopes as `punctuation`; only demote safe punctuation-like operators.
+- Avoid adding framework, library, or application names as keywords.
+- Avoid bulk-importing large upstream keyword lists unless the data has a clear maintenance owner and test value.
+- Favor local correction rules for known over-classification patterns, such as JSON property quotes, HTML text, CSS property values, SQL identifiers, or shell punctuation.
+- Treat unknown languages safely: fall back to scope heuristics and `text` rather than aggressive coloring.
+
+Role parity should improve through:
+
+1. fixture and holdout samples that represent real documents
+2. mismatch reports that identify role-level residuals
+3. small rules with clear comments and tests
+4. package theme tuning when a mismatch is visual rather than semantic
+
+The target is high practical parity, not 100% identical Shiki output for every token.
+For the curated matrix samples, it is reasonable to keep each language around 98% or better non-whitespace parity when the correction is role-level and easy to explain.
+The holdout regression gate can stay more conservative than that target: it should catch broad regressions with an average non-whitespace floor plus a minimum-language floor, because some grammars expose coarse or theme-specific scopes.
+Forcing 100% everywhere would likely require cloning theme-specific and grammar-specific behavior, which would make the plugin heavier and more brittle.
+
+## 7. Theme Policy
+
+The optional preset theme is a convenience layer, not an implicit dependency.
+
+Exports:
+
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-basic`
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-basic.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`
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-basic/markup/shiki.css`
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-basic/markup/highlightjs.css`
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome`
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome.css`
+
+The theme should cover:
+
+- base code block styling
+- inline code styling
+- line numbers
+- emphasized lines
+- comment marks
+- sidecar line notes
+- `<samp>` terminal-like blocks
+- Shiki markup `<samp>` surface correction, because Shiki emits inline
+  `pre` background/color styles
+- Shiki API `::highlight(...)` names
+- highlight.js markup/API class names
+
+Design rules:
+
+- CSS must not be auto-loaded by the renderer.
+- CSS variables should be stable enough for consumers to override.
+- 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.
+- 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.
+- Header comments should identify the package/theme and license briefly; deeper rationale belongs in docs.
+
+The theme JS helper is a render-side helper for provider options and Shiki theme data.
+It does not replace the browser runtime apply step for API mode.
+
+## 8. Line Features and Copy Semantics
+
+Line features must preserve safe mapping from source lines to rendered lines.
+
+Important behavior:
+
+- `line-notes` / `notes` are immediate sidecar fences.
+- Sidecar notes render outside `<code>` / `<samp>` to keep copied code cleaner.
+- Malformed sidecar fences fail closed and remain literal code blocks.
+- Line features are skipped when highlighter output line counts do not match source line counts.
+- `useHighlightPre` passthrough disables structural line splitting by design.
+- `comment-mark` should avoid extra scans unless the feature is enabled and line splitting is safe.
+
+This conservative behavior is better than visually plausible but semantically wrong annotations.
+
+## 9. Performance Policy
+
+Performance work should keep the default path lean.
+
+Current principles:
+
+- Normalize options at plugin setup where possible.
+- Keep per-render state in `env` or render-local objects, not global mutable state.
+- Reset API payload maps at render start when reusing `env`.
+- 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 markup-only and custom-highlight entries available for load isolation.
+
+Benchmark changes with:
+
+```bash
+npm run test:performance
+npm run test:performance:provider-modes
+npm run test:performance:runtime
+```
+
+Compare before/after runs in both orders when judging micro-optimizations.
+Shiki is normally much heavier than highlight.js in this repository's benchmark corpus, so avoid turning Shiki-specific work into the default markup hot path.
+
+## 10. Configuration Recipes
+
+This document intentionally does not duplicate full setup recipes. Keep runnable examples in the README and API-specific operational guidance in the styling guide.
+
+Use these entry points:
+
+- markup with highlight.js: README quick start
+- markup with Shiki HTML: README Shiki example
+- API mode profiles and runtime behavior: [Custom Highlight Styling Guide](custom-highlight-styling-guide.md)
+- concrete preset theme imports and color rationale: [rf-basic Theme README](../theme/rf-basic/README.md)
+
+When adding a new recipe, place it where the reader expects to copy it:
+
+- short first-use snippets: README
+- API runtime/color/payload choices: styling guide
+- long-term policy and trade-offs: this design document
+- palette and file-role details: theme README
+
+## 11. Testing and Regression Checklist
+
+For code highlighting changes, prefer this order:
+
+```bash
+npm run test:theme:contrast
+npm run test:provider:role
+npm run test:provider:role:holdout
+npm run test:provider:matrix
+npm test
+```
+
+Use the mismatch report when improving role mode:
+
+```bash
+node test/custom-highlight/provider-role-mismatch-report.js
+node test/custom-highlight/provider-role-mismatch-report.js example/custom-highlight-provider-matrix.html javascript --detail
+```
+
+Before accepting a new rule, check:
+
+- Does it improve multiple realistic samples, or only one overfit case?
+- Does it keep unknown languages safe?
+- Does it increase the hot path for all modes or only for role mode?
+- Does it preserve payload invariants?
+- Does it keep the public bucket list stable?
+- Does it require new CSS variables, and are light/dark contrast checks updated?
+
+## 12. Future Direction
+
+The best long-term direction is:
+
+1. keep markup mode simple and stable
+2. keep API mode explicit about runtime responsibilities
+3. make the optional theme good enough to stand beside common Shiki/highlight.js themes for rf-basic use cases
+4. improve Shiki role parity through measured, role-level rules rather than unbounded keyword growth
+5. maintain provider contract tests and holdout fixtures as the source of truth for practical compatibility
+
+Large algorithm rewrites are justified only when they simplify these responsibilities or clearly improve correctness/performance across realistic documents.
+If a change mostly chases a matrix percentage by adding brittle language-specific exceptions, it should stay out of the default implementation.

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

@@ -0,0 +1,204 @@
+# Custom Highlight Styling Guide
+
+This guide explains practical styling choices for `highlightRenderer: 'api'`.
+For broader mode selection, provider responsibility boundaries, role-mode policy, and theme design,
+see [Code Highlighting Design](code-highlighting-design.md).
+For the documentation map, see [Documentation](README.md).
+
+## 1. Choose Your Mode First
+
+- Most users should stay on `markup` mode.
+- Use API mode only when you need browser runtime ranges (`CSS.highlights`) and custom runtime control.
+
+Runtime note:
+
+- API mode requires browser-side apply (`applyCustomHighlights` or `observeCustomHighlights`).
+- `test/custom-highlight/pre-highlight.js` is a demo helper, not the package runtime API contract.
+- runtime-only import path is `@peaceroad/markdown-it-renderer-fence/custom-highlight-runtime`.
+- markdown-it render itself does not emit runtime JS files; CLI/static generators should output a small runtime bridge asset separately.
+- optional render-side theme helpers live at `@peaceroad/markdown-it-renderer-fence/theme/rf-basic`; they do not replace browser-side runtime apply.
+
+## 2. Where API-Mode Colors Come From
+
+In API mode, color comes from one of two sources:
+
+1. payload `scopeStyles` (`customHighlight.includeScopeStyles: true`)
+2. external `::highlight(...)` CSS (`customHighlight.includeScopeStyles: false`)
+
+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/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.
+
+## 3. Recommended Profiles
+
+### Profile A (recommended for production)
+
+Use CSS-managed role buckets:
+
+```js
+customHighlight: {
+  provider: 'shiki',
+  shikiScopeMode: 'role',
+  includeScopeStyles: false,
+}
+```
+
+Why:
+
+- stable scope names (`hl-shiki-role-keyword`, `hl-shiki-role-string`, ...)
+- easiest light/dark control with CSS variables and media queries
+- smaller payloads
+
+### Profile B (theme-faithful embedded colors)
+
+Use Shiki color scopes with embedded styles:
+
+```js
+import {
+  createRfBasicShikiCustomHighlightOptions,
+  rfBasicShikiTheme,
+} from '@peaceroad/markdown-it-renderer-fence/theme/rf-basic'
+
+const highlighter = await createHighlighter({
+  themes: [rfBasicShikiTheme],
+  langs: ['javascript'],
+})
+
+customHighlight: {
+  ...createRfBasicShikiCustomHighlightOptions({
+    highlighter,
+    shikiScopeMode: 'color',
+    includeScopeStyles: true,
+  }),
+}
+```
+
+Use this only when you need self-contained per-theme styles in payloads.
+If the Shiki theme uses CSS variables, the payload stays small and can follow light/dark CSS variables without a second Shiki tokenization pass.
+
+## 4. Shiki Scope Modes
+
+### `shikiScopeMode: 'color'`
+
+- scope name is color-derived
+- closest to selected Shiki theme output
+- less maintainable for long-term CSS governance
+
+### `shikiScopeMode: 'semantic'`
+
+- scope name is TextMate-like semantic scope
+- useful for analysis and fine-grained mapping
+- usually more complex than needed for site-wide design tokens
+
+### `shikiScopeMode: 'role'`
+
+- scope name is plugin bucket name
+- best for long-term CSS-managed theming
+
+## 5. Light/Dark Behavior (Important)
+
+### Initial apply
+
+- `applyCustomHighlights(root, { colorScheme: 'auto' })` resolves current scheme at apply time.
+
+### After page is already open and OS/browser theme changes
+
+- `applyCustomHighlights(...)` does not automatically rerun by itself.
+- You need either:
+  1. explicit re-apply call, or
+  2. observer with color-scheme watch.
+
+Example with automatic watch:
+
+```js
+const lazy = observeCustomHighlights(document, {
+  applyOptions: { colorScheme: 'auto', incremental: true },
+  watchColorScheme: true,
+})
+```
+
+With `watchColorScheme: true`, after the first apply, `prefers-color-scheme` changes trigger re-apply.
+
+## 6. Theme Option Shapes
+
+`customHighlight.theme` supports:
+
+- `string` (single-theme payload)
+- `{ light, dark, default? }` (dual-theme payload with additive `v:1` fields)
+
+Notes:
+
+- object form runs Shiki tokenization twice (`light` + `dark`)
+- payload size can grow (especially in `shikiScopeMode: 'color'`)
+- a single CSS-variable Shiki theme can be a simpler alternative when your CSS variables already switch between light/dark values.
+
+## 7. Runtime and CSS Constraints
+
+`::highlight(...)` reliably supports only a subset of properties.
+This plugin emits/uses:
+
+- `color`
+- `background-color`
+- `text-decoration`
+- `text-shadow`
+
+Do not expect full token-span parity for properties like:
+
+- `font-style`
+- `font-weight`
+
+## 8. highlight.js Provider Notes
+
+For `customHighlight.provider: 'hljs'`:
+
+- scope names are hljs-derived (`hl-hljs-*`)
+- `scopeStyles` is typically not emitted
+- external `::highlight(...)` CSS is the standard approach
+
+For normal markup highlighting with highlight.js, continue using highlight.js theme CSS.
+
+## 9. Preset Theme
+
+This package ships an optional preset theme. It is not auto-loaded, but it is a maintained package artifact rather than an example-only file.
+
+CSS:
+
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-basic.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`
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-basic/markup/shiki.css`
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-basic/markup/highlightjs.css`
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome.css`
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome/markup/highlightjs.css`
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome/markup/shiki.css`
+
+JS helper:
+
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-basic`
+- `@peaceroad/markdown-it-renderer-fence/theme/rf-monochrome`
+
+The JS helper provides:
+
+- `rfBasicShikiTheme`: a Shiki theme object that uses `--rf-*` CSS variables.
+- `createRfBasicShikiCustomHighlightOptions(...)`: a small Shiki provider option helper.
+- `createRfBasicHighlightjsCustomHighlightOptions(...)`: a small highlight.js provider option helper.
+- role maps used by repository examples to keep Shiki, highlight.js, and `::highlight(...)` CSS aligned.
+
+See `theme/rf-basic/README.md` and `theme/rf-monochrome/README.md` for the color design and file roles.
+
+Note: `rf-monochrome.css` is a markup-mode theme. It uses the shared code surface plus bold/italic instead of
+syntax colors, so it is useful for print or one-color output. It is not a Custom Highlight API theme because
+`::highlight(...)` cannot apply `font-weight` or `font-style`.
+
+The repository keeps `example/theme.css` only as a tiny local wrapper around the distributed preset CSS.
+
+For production:
+
+- Markup mode: use this preset, the CSS theme from your highlighter, or your design system.
+- API mode with `includeScopeStyles: true`: provider style data may be emitted in payloads.
+- API mode with `includeScopeStyles: false`: use this preset or define your own `::highlight(...)` rules.

package/package.json

@@ -1,17 +1,25 @@
 {
   "name": "@peaceroad/markdown-it-renderer-fence",
-  "version": "0.7.0",
-  "description": "In code blocks, the `<samp>` tag is used with the language keywords `samp`, `shell`, and `console`, and provides an option to display line numbers.",
+  "version": "0.8.0",
+  "description": "A markdown-it fence renderer with code/samp output, line features, Custom Highlight API support, and optional themes.",
   "main": "index.js",
   "exports": {
     ".": "./index.js",
     "./custom-highlight": "./src/entry/custom-highlight.js",
     "./custom-highlight-runtime": "./src/entry/custom-highlight-runtime.js",
-    "./markup-highlight": "./src/entry/markup-highlight.js"
+    "./markup-highlight": "./src/entry/markup-highlight.js",
+    "./theme/rf-basic": "./theme/rf-basic/index.js",
+    "./theme/rf-basic.css": "./theme/rf-basic/index.css",
+    "./theme/rf-basic/*": "./theme/rf-basic/*",
+    "./theme/rf-monochrome": "./theme/rf-monochrome/index.js",
+    "./theme/rf-monochrome.css": "./theme/rf-monochrome/index.css",
+    "./theme/rf-monochrome/*": "./theme/rf-monochrome/*"
   },
   "files": [
     "index.js",
     "src",
+    "docs",
+    "theme",
     "LICENSE",
     "README.md"
   ],
@@ -23,28 +31,30 @@
     ]
   },
   "scripts": {
-    "test": "node test/test.js && node test/custom-highlight/provider-contract.test.js && node test/custom-highlight/provider-keyword-coverage.test.js && node test/custom-highlight/provider-keyword-holdout-parity.test.js && node -e \"console.log('Passed all test.')\"",
+    "test": "node test/test.js && node test/custom-highlight/provider-contract.test.js && node test/theme/contrast-check.js && node test/custom-highlight/provider-role-coverage.test.js && node test/custom-highlight/provider-role-holdout-parity.test.js && node -e \"console.log('Passed all test.')\"",
     "test:provider:contract": "node test/custom-highlight/provider-contract.test.js",
-    "test:provider:keyword": "node test/custom-highlight/provider-keyword-coverage.test.js",
-    "test:provider:keyword:holdout": "node test/custom-highlight/provider-keyword-holdout-parity.test.js",
-    "test:provider:keyword:mismatch": "node test/custom-highlight/provider-keyword-mismatch-report.js",
+    "test:provider:role": "node test/custom-highlight/provider-role-coverage.test.js",
+    "test:provider:role:holdout": "node test/custom-highlight/provider-role-holdout-parity.test.js",
+    "test:provider:role:mismatch": "node test/custom-highlight/provider-role-mismatch-report.js",
     "test:provider:matrix": "node test/custom-highlight/provider-matrix-audit.js",
-    "build:demo:provider:keyword": "node test/custom-highlight/build-provider-keyword-demos.js",
+    "build:demo:provider:role": "node test/custom-highlight/build-provider-role-demos.js",
     "build:example:custom-highlight": "node example/build-custom-highlight-compare.js",
+    "build:example:monochrome-highlight": "node example/build-monochrome-highlight-compare.js",
     "test:performance": "node test/performance/benchmark.js",
     "test:performance:highlighter": "node test/performance/highlighter-benchmark.js",
     "test:performance:provider-modes": "node test/performance/provider-mode-benchmark.js",
     "test:performance:runtime": "node test/performance/runtime-apply-benchmark.js",
-    "test:performance:keyword": "node test/performance/provider-mode-benchmark.js"
+    "test:performance:role": "node test/performance/provider-mode-benchmark.js",
+    "test:theme:contrast": "node test/theme/contrast-check.js"
   },
   "author": "peaceroad <peaceroad@gmail.com>",
   "repository": "https://github.com/peaceroad/p7d-markdown-it-renderer-fence",
   "license": "MIT",
   "devDependencies": {
-    "@peaceroad/markdown-it-figure-with-p-caption": "^0.17.0",
+    "@peaceroad/markdown-it-figure-with-p-caption": "^0.18.0",
     "highlight.js": "^11.11.1",
     "markdown-it": "^14.1.1",
     "markdown-it-attrs": "^4.3.1",
-    "shiki": "^4.0.2"
+    "shiki": "^4.1.0"
   }
 }

package/src/custom-highlight/option-validator.js

@@ -1,7 +1,7 @@
 const warnedOptionIssues = new Set()
 
 const isWarnEnabled = () => {
-  if (typeof process === 'undefined' || !process || !process.env) return true
+  if (typeof process === 'undefined' || !process || !process.env) return false
   const mode = process.env.NODE_ENV
   return mode === 'development'
 }
@@ -20,7 +20,7 @@ const validProviderSet = new Set(['shiki', 'hljs', 'custom'])
 const validFallbackSet = new Set(['plain', 'markup'])
 const validTransportSet = new Set(['env', 'inline-script'])
 const validLineFeatureStrategySet = new Set(['hybrid', 'disable'])
-const validShikiScopeModeSet = new Set(['auto', 'color', 'semantic', 'keyword'])
+const validShikiScopeModeSet = new Set(['auto', 'color', 'semantic', 'role'])
 const knownCustomHighlightKeys = new Set([
   'provider',
   'getRanges',
@@ -32,9 +32,9 @@ const knownCustomHighlightKeys = new Set([
   'scopePrefix',
   'includeScopeStyles',
   'shikiScopeMode',
-  'shikiKeywordClassifier',
-  'shikiKeywordLangResolver',
-  'shikiKeywordLangAliases',
+  'shikiRoleClassifier',
+  'shikiRoleLangResolver',
+  'shikiRoleLangAliases',
   'highlighter',
   'hljsHighlight',
   'highlight',