@fuzdev/fuz_code 0.45.1 → 0.46.1

package/dist/highlight_manager.js

@@ -1,13 +1,40 @@
+import { DEV } from 'esm-env';
 import { highlight_priorities } from './highlight_priorities.js';
 /**
- * Check for CSS Highlights API support.
+ * Checks for CSS Highlights API support.
  */
-export const supports_css_highlight_api = () => !!(globalThis.CSS?.highlights && globalThis.Highlight); // eslint-disable-line @typescript-eslint/no-unnecessary-condition
+export const supports_css_highlight_api = () => !!(globalThis.CSS?.highlights && globalThis.Highlight);
+const detect_range_kind = () => typeof globalThis.StaticRange === 'function' ? 'static' : 'live';
 /**
- * Manages CSS Custom Highlight API ranges for a single element.
- * Tracks ranges per element and only removes its own ranges when clearing.
+ * Finds the first text node child of `element`, or `null` if there is none.
  *
- * **Experimental** — limited browser support. Use `Code` for production.
+ * The text node might not be `firstChild` because frameworks (e.g. Svelte) can
+ * insert comment/anchor nodes around it.
+ */
+const find_text_node = (element) => {
+    for (const node of element.childNodes) {
+        if (node.nodeType === Node.TEXT_NODE)
+            return node;
+    }
+    return null;
+};
+const has_tokens = (tokens) => tokens.some((t) => typeof t !== 'string');
+const push_range = (ranges_by_name, name, range) => {
+    const existing = ranges_by_name.get(name);
+    if (existing) {
+        existing.push(range);
+    }
+    else {
+        ranges_by_name.set(name, [range]);
+    }
+};
+/**
+ * Manages CSS Custom Highlight API ranges for a single element's text node.
+ * Tracks ranges per element and only removes its own ranges when clearing,
+ * cooperating with other managers that share the global `CSS.highlights` registry.
+ *
+ * **Experimental** — limited browser support. Use `Code.svelte` for production
+ * block code; this powers the experimental `CodeHighlight` and `CodeTextarea`.
  *
  * @example
  * ```ts
@@ -16,65 +43,100 @@ export const supports_css_highlight_api = () => !!(globalThis.CSS?.highlights &&
  * ```
  */
 export class HighlightManager {
+    /**
+     * This manager's ranges, keyed by prefixed highlight name (e.g. `token_keyword`).
+     * A single range object may be shared across several names (a token type plus
+     * its aliases), since one range can belong to multiple `Highlight` sets.
+     */
     element_ranges;
+    #range_kind;
     constructor() {
         if (!supports_css_highlight_api()) {
             throw Error('CSS Highlights API not supported');
         }
         this.element_ranges = new Map();
+        this.#range_kind = detect_range_kind();
     }
     /**
-     * Highlight from syntax styler token stream.
+     * Highlights `element`'s text node from a `SyntaxTokenStream` produced by
+     * `tokenize_syntax`. Clears this manager's previous ranges first.
+     *
+     * In production this never throws on a tokenizer/DOM mismatch: out-of-bounds
+     * tokens are clamped and a missing text node is a no-op. In DEV the same
+     * conditions throw loudly to surface grammar bugs.
      */
     highlight_from_syntax_tokens(element, tokens) {
-        // Find the text node (it might not be firstChild due to Svelte comment nodes)
-        let text_node = null;
-        for (const node of element.childNodes) {
-            if (node.nodeType === Node.TEXT_NODE) {
-                text_node = node;
-                break;
+        this.clear_element_ranges();
+        const text_node = find_text_node(element);
+        if (!text_node) {
+            if (has_tokens(tokens)) {
+                if (DEV) {
+                    throw new Error('no text node to highlight');
+                }
+                else {
+                    // eslint-disable-next-line no-console
+                    console.error('[HighlightManager] tokens present but no text node to highlight');
+                }
             }
+            return;
         }
-        if (!text_node) {
-            throw new Error('no text node to highlight');
+        try {
+            this.#apply(text_node, tokens);
         }
-        this.clear_element_ranges();
-        const ranges_by_type = new Map();
-        const final_pos = this.#create_all_ranges(tokens, text_node, ranges_by_type, 0);
-        // Validate that token positions matched text node length
-        const text_length = text_node.textContent?.length ?? 0;
-        if (final_pos !== text_length) {
-            throw new Error(`Token stream length mismatch: tokens covered ${final_pos} chars but text node has ${text_length} chars`);
+        catch (err) {
+            // some engines may reject `StaticRange` in `Highlight.add` -- fall back to
+            // live `Range` once rather than letting the throw escape into the effect
+            if (this.#range_kind === 'static') {
+                this.#range_kind = 'live';
+                this.clear_element_ranges(); // undo any partial application
+                this.#apply(text_node, tokens);
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    #apply(text_node, tokens) {
+        const ranges_by_name = new Map();
+        const final_pos = this.#collect_ranges(tokens, text_node, ranges_by_name, 0);
+        if (DEV) {
+            const text_length = text_node.textContent?.length ?? 0;
+            if (final_pos !== text_length) {
+                throw new Error(`Token stream length mismatch: tokens covered ${final_pos} chars but text node has ${text_length} chars`);
+            }
         }
-        // Apply highlights
-        for (const [type, ranges] of ranges_by_type) {
-            const prefixed_type = `token_${type}`;
-            // Track ranges for this element
-            this.element_ranges.set(prefixed_type, ranges);
-            // Get or create the shared highlight
-            let highlight = CSS.highlights.get(prefixed_type);
+        // TODO: cross-instance coupling -- all managers share one global `Highlight`
+        // per token type, so re-highlighting one element (e.g. a textarea on every
+        // keystroke) mutates highlights that also hold ranges from every other code
+        // block on the page, forcing the browser to re-evaluate the shared set.
+        // Isolating per-instance needs unique highlight names + runtime-injected
+        // `::highlight()` CSS (≈50 token types × N instances), trading the static
+        // theme file for generated CSS. Only worth it with many concurrently-updating
+        // instances; revisit if profiling shows it.
+        for (const [name, ranges] of ranges_by_name) {
+            this.element_ranges.set(name, ranges);
+            let highlight = CSS.highlights.get(name);
             if (!highlight) {
                 highlight = new Highlight();
-                // Set priority based on CSS cascade order (higher = later in CSS = wins)
-                highlight.priority =
-                    highlight_priorities[prefixed_type] ?? 0;
-                CSS.highlights.set(prefixed_type, highlight);
+                // priority follows CSS cascade order (higher = later in CSS = wins)
+                highlight.priority = highlight_priorities[name] ?? 0;
+                CSS.highlights.set(name, highlight);
             }
-            // Add all ranges to the highlight
             for (const range of ranges) {
                 highlight.add(range);
             }
         }
     }
     /**
-     * Clear only this element's ranges from highlights.
+     * Clears only this manager's ranges from the shared highlights. Defensive:
+     * a highlight may already be gone (e.g. another manager removed the last
+     * range, or HMR reset the registry), which is a valid state, not an error.
      */
     clear_element_ranges() {
         for (const [name, ranges] of this.element_ranges) {
             const highlight = CSS.highlights.get(name);
-            if (!highlight) {
-                throw new Error('Expected to find CSS highlight: ' + name);
-            }
+            if (!highlight)
+                continue;
             for (const range of ranges) {
                 highlight.delete(range);
             }
@@ -87,10 +149,25 @@ export class HighlightManager {
     destroy() {
         this.clear_element_ranges();
     }
+    #make_range(text_node, start, end) {
+        if (this.#range_kind === 'static') {
+            return new StaticRange({
+                startContainer: text_node,
+                startOffset: start,
+                endContainer: text_node,
+                endOffset: end,
+            });
+        }
+        const range = new Range();
+        range.setStart(text_node, start);
+        range.setEnd(text_node, end);
+        return range;
+    }
     /**
-     * Create ranges for all tokens in the tree.
+     * Walks the token tree, collecting one range per non-empty token (shared
+     * across its type and aliases). Returns the end position covered.
      */
-    #create_all_ranges(tokens, text_node, ranges_by_type, offset) {
+    #collect_ranges(tokens, text_node, ranges_by_name, offset) {
         const text_length = text_node.textContent?.length ?? 0;
         let pos = offset;
         for (const token of tokens) {
@@ -98,49 +175,28 @@ export class HighlightManager {
                 pos += token.length;
                 continue;
             }
-            const length = token.length;
-            const end_pos = pos + length;
-            // Validate positions are within text node bounds before creating ranges
-            if (end_pos > text_length) {
+            const end_pos = pos + token.length;
+            if (DEV && end_pos > text_length) {
                 throw new Error(`Token ${token.type} extends beyond text node: position ${end_pos} > length ${text_length}`);
             }
-            try {
-                const range = new Range();
-                range.setStart(text_node, pos);
-                range.setEnd(text_node, end_pos);
-                // Add range for the token type
-                const type = token.type;
-                if (!ranges_by_type.has(type)) {
-                    ranges_by_type.set(type, []);
-                }
-                ranges_by_type.get(type).push(range);
-                // Also add range for any aliases (alias is always an array)
+            // production-safe: clamp rather than throw on a tokenizer edge case
+            const safe_end = end_pos > text_length ? text_length : end_pos;
+            if (safe_end > pos) {
+                // one range shared across the token type and all its aliases --
+                // the same range object can belong to multiple `Highlight` sets
+                const range = this.#make_range(text_node, pos, safe_end);
+                push_range(ranges_by_name, `token_${token.type}`, range);
                 for (const alias of token.alias) {
-                    if (!ranges_by_type.has(alias)) {
-                        ranges_by_type.set(alias, []);
-                    }
-                    // Create a new range for each alias (ranges can't be reused)
-                    const alias_range = new Range();
-                    alias_range.setStart(text_node, pos);
-                    alias_range.setEnd(text_node, end_pos);
-                    ranges_by_type.get(alias).push(alias_range);
+                    push_range(ranges_by_name, `token_${alias}`, range);
                 }
             }
-            catch (e) {
-                throw new Error(`Failed to create range for ${token.type}: ${e}`);
-            }
-            // Process nested tokens
             if (Array.isArray(token.content)) {
-                const actual_end_pos = this.#create_all_ranges(token.content, text_node, ranges_by_type, pos);
-                // Validate that nested tokens match the parent token's claimed length
-                if (actual_end_pos !== end_pos) {
-                    throw new Error(`Token ${token.type} length mismatch: claimed ${length} chars (${pos}-${end_pos}) but nested content covered ${actual_end_pos - pos} chars (${pos}-${actual_end_pos})`);
+                const nested_end = this.#collect_ranges(token.content, text_node, ranges_by_name, pos);
+                if (DEV && nested_end !== end_pos) {
+                    throw new Error(`Token ${token.type} length mismatch: claimed ${token.length} chars (${pos}-${end_pos}) but nested content covered ${nested_end - pos} chars (${pos}-${nested_end})`);
                 }
-                pos = actual_end_pos;
-            }
-            else {
-                pos = end_pos;
             }
+            pos = end_pos;
         }
         return pos;
     }

package/dist/range_highlighting.svelte.d.ts

@@ -0,0 +1,39 @@
+import type { SyntaxStyler, SyntaxGrammar } from './syntax_styler.js';
+/**
+ * Reactive inputs for `create_range_highlighting`. All values are getters so the
+ * helper can track the consuming component's reactive state across the call
+ * boundary (the Svelte 5 getter-injection pattern).
+ */
+export interface RangeHighlightingOptions {
+    /** The element whose first text node receives the highlight ranges. */
+    element: () => Element | undefined;
+    /**
+     * The text to tokenize. Must match the element's text node exactly (e.g. a
+     * textarea backdrop includes its trailing newline here too).
+     */
+    text: () => string;
+    /** Language id; `null` disables highlighting. */
+    lang: () => string | null;
+    /** Optional custom grammar; takes precedence over `lang` for tokenization. */
+    grammar: () => SyntaxGrammar | undefined;
+    /** The syntax styler whose registered grammars back `lang` lookups. */
+    syntax_styler: () => SyntaxStyler;
+    /** Extra gate — ranges are only applied when this returns true. Defaults to always-on. */
+    enabled?: () => boolean;
+    /** Component name used in DEV warnings. */
+    dev_label: string;
+}
+/** Reactive outputs from `create_range_highlighting`. */
+export interface RangeHighlighting {
+    readonly highlighting_disabled: boolean;
+}
+/**
+ * Wires up CSS Custom Highlight API range highlighting for a single element's
+ * text node, shared by `CodeHighlight` and `CodeTextarea`. Creates a
+ * `HighlightManager`, memoizes tokenization, applies/clears ranges in an effect,
+ * emits DEV warnings for unsupported languages, and tears down on destroy.
+ *
+ * Must be called during component initialization (it uses `$effect`/`onDestroy`).
+ */
+export declare const create_range_highlighting: (options: RangeHighlightingOptions) => RangeHighlighting;
+//# sourceMappingURL=range_highlighting.svelte.d.ts.map

package/dist/range_highlighting.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"range_highlighting.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/range_highlighting.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,YAAY,EAAE,aAAa,EAAC,MAAM,oBAAoB,CAAC;AAGpE;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACxC,uEAAuE;IACvE,OAAO,EAAE,MAAM,OAAO,GAAG,SAAS,CAAC;IACnC;;;OAGG;IACH,IAAI,EAAE,MAAM,MAAM,CAAC;IACnB,iDAAiD;IACjD,IAAI,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAC1B,8EAA8E;IAC9E,OAAO,EAAE,MAAM,aAAa,GAAG,SAAS,CAAC;IACzC,uEAAuE;IACvE,aAAa,EAAE,MAAM,YAAY,CAAC;IAClC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;IACxB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,wBAAwB,KAAG,iBAuD7E,CAAC"}

package/dist/range_highlighting.svelte.js

@@ -0,0 +1,57 @@
+import { onDestroy } from 'svelte';
+import { DEV } from 'esm-env';
+import { HighlightManager, supports_css_highlight_api } from './highlight_manager.js';
+/**
+ * Wires up CSS Custom Highlight API range highlighting for a single element's
+ * text node, shared by `CodeHighlight` and `CodeTextarea`. Creates a
+ * `HighlightManager`, memoizes tokenization, applies/clears ranges in an effect,
+ * emits DEV warnings for unsupported languages, and tears down on destroy.
+ *
+ * Must be called during component initialization (it uses `$effect`/`onDestroy`).
+ */
+export const create_range_highlighting = (options) => {
+    const manager = supports_css_highlight_api() ? new HighlightManager() : null;
+    const is_enabled = options.enabled ?? (() => true);
+    const language_supported = $derived(options.lang() !== null && !!options.syntax_styler().langs[options.lang()]);
+    const highlighting_disabled = $derived(options.lang() === null || (!language_supported && !options.grammar()));
+    // tokenize once per (text, grammar, lang) change -- memoized so unrelated
+    // reactivity doesn't trigger a full re-tokenization
+    const range_tokens = $derived.by(() => {
+        if (!manager || !is_enabled() || highlighting_disabled)
+            return null;
+        const text = options.text();
+        if (!text)
+            return null;
+        // route through the styler so `before_tokenize`/`after_tokenize` hooks run,
+        // matching `stylize`'s HTML path; `grammar` undefined falls back to the
+        // registered lang grammar (`! safe bc of `highlighting_disabled`)
+        return options.syntax_styler().tokenize(text, options.lang(), options.grammar());
+    });
+    if (manager) {
+        $effect(() => {
+            const element = options.element();
+            if (!element || !range_tokens) {
+                manager.clear_element_ranges();
+                return;
+            }
+            manager.highlight_from_syntax_tokens(element, range_tokens);
+        });
+    }
+    if (DEV) {
+        $effect(() => {
+            // a lang was requested but we can't highlight it (unknown id, no grammar)
+            if (options.lang() && highlighting_disabled) {
+                const langs = Object.keys(options.syntax_styler().langs).join(', ');
+                // eslint-disable-next-line no-console
+                console.error(`[${options.dev_label}] Language "${options.lang()}" is not supported and no custom grammar provided. ` +
+                    `Highlighting disabled. Supported: ${langs}`);
+            }
+        });
+    }
+    onDestroy(() => manager?.destroy());
+    return {
+        get highlighting_disabled() {
+            return highlighting_disabled;
+        },
+    };
+};

package/dist/svelte_preprocess_fuz_code.d.ts

@@ -6,13 +6,13 @@ import type { SyntaxStyler } from './syntax_styler.js';
 export interface PreprocessFuzCodeOptions {
     /** File patterns to exclude. */
     exclude?: Array<string | RegExp>;
-    /** Custom syntax styler. @default syntax_styler_global */
+    /** Custom `SyntaxStyler` instance. @default syntax_styler_global */
     syntax_styler?: SyntaxStyler;
     /** Enable in-memory caching. @default true */
     cache?: boolean;
     /**
-     * Import sources that resolve to the Code component.
-     * Used to verify that `<Code>` in templates actually refers to fuz_code's Code.svelte.
+     * Import sources that resolve to the `Code` component.
+     * Used to verify that `<Code>` in templates actually refers to `Code.svelte`.
      *
      * @default ['@fuzdev/fuz_code/Code.svelte']
      */
@@ -27,7 +27,7 @@ export interface PreprocessFuzCodeOptions {
  * Svelte preprocessor that compiles static `Code` component content at build time,
  * replacing runtime syntax highlighting with pre-rendered HTML.
  *
- * @param options preprocessor configuration
+ * @param options - `PreprocessFuzCodeOptions` configuration
  * @returns a Svelte preprocessor group
  *
  * @example

package/dist/svelte_preprocess_fuz_code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"svelte_preprocess_fuz_code.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/svelte_preprocess_fuz_code.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,iBAAiB,EAAW,MAAM,iBAAiB,CAAC;AAgBxE,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC,gCAAgC;IAChC,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAEjC,0DAA0D;IAC1D,aAAa,CAAC,EAAE,YAAY,CAAC;IAE7B,8CAA8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,0BAA0B,GACtC,UAAS,wBAA6B,KACpC,iBA6DF,CAAC"}
+{"version":3,"file":"svelte_preprocess_fuz_code.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/svelte_preprocess_fuz_code.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,iBAAiB,EAAW,MAAM,iBAAiB,CAAC;AAgBxE,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC,gCAAgC;IAChC,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;IAEjC,oEAAoE;IACpE,aAAa,CAAC,EAAE,YAAY,CAAC;IAE7B,8CAA8C;IAC9C,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAElC;;;OAGG;IACH,QAAQ,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,0BAA0B,GACtC,UAAS,wBAA6B,KACpC,iBA6DF,CAAC"}

package/dist/svelte_preprocess_fuz_code.js

@@ -9,7 +9,7 @@ import { syntax_styler_global } from './syntax_styler_global.js';
  * Svelte preprocessor that compiles static `Code` component content at build time,
  * replacing runtime syntax highlighting with pre-rendered HTML.
  *
- * @param options preprocessor configuration
+ * @param options - `PreprocessFuzCodeOptions` configuration
  * @returns a Svelte preprocessor group
  *
  * @example
@@ -68,7 +68,7 @@ export const svelte_preprocess_fuz_code = (options = {}) => {
     };
 };
 /**
- * Attempt to highlight content, using cache if available.
+ * Attempts to highlight content, using cache if available.
  * Returns the highlighted HTML, or `null` on error.
  */
 const try_highlight = (text, lang, syntax_styler, options) => {
@@ -87,7 +87,7 @@ const try_highlight = (text, lang, syntax_styler, options) => {
     return html;
 };
 /**
- * Walks the AST to find Code component usages with static `content` props
+ * Walks the AST to find `Code` component usages with static `content` props
  * and generates transformations to replace them with `dangerous_raw_html`.
  */
 const find_code_usages = (ast, syntax_styler, code_names, options) => {

package/dist/syntax_styler.d.ts

@@ -34,15 +34,14 @@ export declare class SyntaxStyler {
      * - Custom grammar: `stylize(code, 'ts', customGrammar)` - uses custom grammar but keeps 'ts' label
      * - Extended grammar: `stylize(code, 'custom', this.extend_grammar('ts', extension))` - new language variant
      *
-     * @param text - The source code to syntax highlight.
-     * @param lang - Language identifier (e.g., 'ts', 'css', 'html'). Used for:
-     *   - Grammar lookup when `grammar` is undefined
-     *   - Hook context (`lang` field passed to hooks)
-     *   - Language identification in output
-     * @param grammar - Optional custom grammar object. When undefined, automatically
-     *   looks up the grammar via `this.get_lang(lang)`. Provide this to use a custom
-     *   or modified grammar instead of the registered one.
-     *
+     * @param text - the source code to syntax highlight
+     * @param lang - language identifier (e.g., 'ts', 'css', 'html'), used for:
+     *   - grammar lookup when `grammar` is undefined
+     *   - hook context (`lang` field passed to hooks)
+     *   - language identification in output
+     * @param grammar - optional custom `SyntaxGrammar` object; when undefined, automatically
+     *   looks up the grammar via `this.get_lang(lang)`; provide this to use a custom
+     *   or modified grammar instead of the registered one
      * @returns HTML string with syntax highlighting using CSS classes (`.token_*`)
      *
      * @example
@@ -66,6 +65,18 @@ export declare class SyntaxStyler {
      * ```
      */
     stylize(text: string, lang: string, grammar?: SyntaxGrammar | undefined): string;
+    /**
+     * Tokenizes `text` into a `SyntaxTokenStream`, running the `before_tokenize`
+     * and `after_tokenize` hooks. This is the tokenization half of `stylize` — use
+     * it when you need the token stream itself (e.g. CSS Custom Highlight API range
+     * highlighting) rather than HTML.
+     *
+     * @param text - source to tokenize
+     * @param lang - language identifier; passed to the tokenize hooks
+     * @param grammar - grammar to tokenize with; defaults to `this.get_lang(lang)`
+     * @returns the resulting token stream
+     */
+    tokenize(text: string, lang: string, grammar?: SyntaxGrammar | undefined): SyntaxTokenStream;
     /**
      * Inserts tokens _before_ another token in a language definition or any other grammar.
      *
@@ -83,7 +94,7 @@ export declare class SyntaxStyler {
      * };
      * ```
      *
-     * then the `style` token will be added (and processed) at the end. `insert_before` allows you to insert tokens
+     * then the `style` token will be added (and processed) at the end. `grammar_insert_before` allows you to insert tokens
      * before existing tokens. For the CSS example above, you would use it like this:
      *
      * ```js
@@ -110,12 +121,12 @@ export declare class SyntaxStyler {
      *
      * ## Limitations
      *
-     * The main problem `insert_before` has to solve is iteration order. Since ES2015, the iteration order for object
+     * The main problem `grammar_insert_before` has to solve is iteration order. Since ES2015, the iteration order for object
      * properties is guaranteed to be the insertion order (except for integer keys) but some browsers behave
-     * differently when keys are deleted and re-inserted. So `insert_before` can't be implemented by temporarily
+     * differently when keys are deleted and re-inserted. So `grammar_insert_before` can't be implemented by temporarily
      * deleting properties which is necessary to insert at arbitrary positions.
      *
-     * To solve this problem, `insert_before` doesn't actually insert the given tokens into the target object.
+     * To solve this problem, `grammar_insert_before` doesn't actually insert the given tokens into the target object.
      * Instead, it will create a new object and replace all references to the target object with the new one. This
      * can be done without temporarily deleting properties, so the iteration order is well-defined.
      *
@@ -130,16 +141,13 @@ export declare class SyntaxStyler {
      * assert(newMarkup === syntax_styler.get_lang('markup'));
      * ```
      *
-     * @param inside - The property of `root` (e.g. a language id in `syntax_styler.langs`) that contains the
-     * object to be modified.
-     * @param before - The key to insert before.
-     * @param insert - An object containing the key-value pairs to be inserted.
-     * @param root - The object containing `inside`, i.e. the object that contains the
-     * object to be modified.
-     *
-     * Defaults to `syntax_styler.langs`.
-     *
-     * @returns the new grammar object
+     * @param inside - the property of `root` (e.g. a language id in `syntax_styler.langs`) that contains the
+     * object to be modified
+     * @param before - the key to insert before
+     * @param insert - an object containing the key-value pairs to be inserted
+     * @param root - the object containing `inside`, i.e. the object that contains the
+     * object to be modified; defaults to `syntax_styler.langs`
+     * @returns the new `SyntaxGrammar` object
      */
     grammar_insert_before(inside: string, before: string, insert: SyntaxGrammarRaw, root?: Record<string, any>): SyntaxGrammar;
     /**
@@ -147,9 +155,9 @@ export declare class SyntaxStyler {
      *
      * Runs the `wrap` hook on each `SyntaxToken`.
      *
-     * @param o - The token or token stream to be converted.
-     * @param lang - The name of current language.
-     * @returns The HTML representation of the token or token stream.
+     * @param o - the token or `SyntaxTokenStream` to be converted
+     * @param lang - the name of current language
+     * @returns HTML representation of the token or token stream
      */
     stringify_token(o: string | SyntaxToken | SyntaxTokenStream, lang: string): string;
     /**
@@ -167,9 +175,9 @@ export declare class SyntaxStyler {
      * Therefore, it is encouraged to order overwriting tokens according to the positions of the overwritten tokens.
      * Furthermore, all non-overwriting tokens should be placed after the overwriting ones.
      *
-     * @param base_id - The id of the language to extend. This has to be a key in `syntax_styler.langs`.
-     * @param extension - The new tokens to append.
-     * @returns the new grammar
+     * @param base_id - the id of the language to extend, must be a key in `syntax_styler.langs`
+     * @param extension - the new tokens to append
+     * @returns the new `SyntaxGrammar`
      */
     extend_grammar(base_id: string, extension: SyntaxGrammarRaw): SyntaxGrammar;
     plugins: Record<string, any>;
@@ -221,13 +229,13 @@ export interface SyntaxGrammarTokenRaw {
      */
     alias?: string | Array<string>;
     /**
-     * The nested grammar of this token.
+     * The nested `SyntaxGrammarRaw` of this token.
      */
     inside?: SyntaxGrammarRaw | null;
 }
 /**
  * Grammar token with all properties required.
- * This is the normalized representation used at runtime.
+ * This is the normalized representation of `SyntaxGrammarTokenRaw` used at runtime.
  */
 export interface SyntaxGrammarToken {
     pattern: RegExp;
@@ -238,7 +246,7 @@ export interface SyntaxGrammarToken {
 }
 /**
  * A grammar after normalization.
- * All values are arrays of normalized tokens with consistent shapes.
+ * All values are arrays of normalized `SyntaxGrammarToken` with consistent shapes.
  */
 export type SyntaxGrammar = Record<string, Array<SyntaxGrammarToken>>;
 export type HookBeforeTokenizeCallback = (ctx: HookBeforeTokenizeCallbackContext) => void;

package/dist/syntax_styler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"syntax_styler.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/syntax_styler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"syntax_styler.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/syntax_styler.ts"],"names":[],"mappings":"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"}