@fuzdev/fuz_code 0.45.1 → 0.46.0

package/README.md

@@ -116,6 +116,7 @@ Enabled by default in `syntax_styler_global`:
 - [`js`](src/lib/grammar_js.ts)
 - [`json`](src/lib/grammar_json.ts)
 - [`clike`](src/lib/grammar_clike.ts)
+- [`bash`](src/lib/grammar_bash.ts)
 
 ### More
 

package/dist/Code.svelte

@@ -55,7 +55,7 @@
 			 */
 			lang?: string | null;
 			/**
-			 * Optional custom grammar object for syntax tokenization.
+			 * Optional custom `SyntaxGrammar` object for syntax tokenization.
 			 *
 			 * **When to use:**
 			 * - To provide a custom language definition not registered in `syntax_styler.langs`
@@ -100,7 +100,7 @@
 			 */
 			nomargin?: boolean;
 			/**
-			 * Custom SyntaxStyler instance to use for highlighting.
+			 * Custom `SyntaxStyler` instance to use for highlighting.
 			 * Allows using a different styler with custom grammars or configuration.
 			 *
 			 * @default syntax_styler_global

package/dist/Code.svelte.d.ts

@@ -35,7 +35,7 @@ type $$ComponentProps = SvelteHTMLElements['code'] & ({
      */
     lang?: string | null;
     /**
-     * Optional custom grammar object for syntax tokenization.
+     * Optional custom `SyntaxGrammar` object for syntax tokenization.
      *
      * **When to use:**
      * - To provide a custom language definition not registered in `syntax_styler.langs`
@@ -80,7 +80,7 @@ type $$ComponentProps = SvelteHTMLElements['code'] & ({
      */
     nomargin?: boolean;
     /**
-     * Custom SyntaxStyler instance to use for highlighting.
+     * Custom `SyntaxStyler` instance to use for highlighting.
      * Allows using a different styler with custom grammars or configuration.
      *
      * @default syntax_styler_global

package/dist/CodeHighlight.svelte

@@ -3,7 +3,7 @@
 	 * Uses the CSS Custom Highlight API when available --
 	 * https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API
 	 *
-	 * Requires importing theme_highlight.css instead of theme.css.
+	 * Requires importing `theme_highlight.css` instead of `theme.css`.
 	 */
 
 	import {onDestroy, type Snippet} from 'svelte';
@@ -65,7 +65,7 @@
 		 */
 		mode?: HighlightMode;
 		/**
-		 * Optional custom grammar object for syntax tokenization.
+		 * Optional custom `SyntaxGrammar` object for syntax tokenization.
 		 *
 		 * **When to use:**
 		 * - To provide a custom language definition not registered in `syntax_styler.langs`
@@ -103,7 +103,7 @@
 		 */
 		wrap?: boolean;
 		/**
-		 * Custom SyntaxStyler instance to use for highlighting.
+		 * Custom `SyntaxStyler` instance to use for highlighting.
 		 * Allows using a different styler with custom grammars or configuration.
 		 *
 		 * @default syntax_styler_global
@@ -117,7 +117,7 @@
 		children?: Snippet<[markup: string]>;
 	} = $props();
 
-	let code_element: HTMLElement | undefined = $state();
+	let code_element: HTMLElement | undefined = $state.raw();
 
 	const supports_ranges = supports_css_highlight_api();
 

package/dist/CodeHighlight.svelte.d.ts

@@ -2,7 +2,7 @@
      * Uses the CSS Custom Highlight API when available --
      * https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API
      *
-     * Requires importing theme_highlight.css instead of theme.css.
+     * Requires importing `theme_highlight.css` instead of `theme.css`.
      */
 import { type Snippet } from 'svelte';
 import type { SvelteHTMLElements } from 'svelte/elements';
@@ -44,7 +44,7 @@ type $$ComponentProps = SvelteHTMLElements['code'] & {
      */
     mode?: HighlightMode;
     /**
-     * Optional custom grammar object for syntax tokenization.
+     * Optional custom `SyntaxGrammar` object for syntax tokenization.
      *
      * **When to use:**
      * - To provide a custom language definition not registered in `syntax_styler.langs`
@@ -82,7 +82,7 @@ type $$ComponentProps = SvelteHTMLElements['code'] & {
      */
     wrap?: boolean;
     /**
-     * Custom SyntaxStyler instance to use for highlighting.
+     * Custom `SyntaxStyler` instance to use for highlighting.
      * Allows using a different styler with custom grammars or configuration.
      *
      * @default syntax_styler_global

package/dist/grammar_markdown.js

@@ -1,5 +1,5 @@
 /**
- * Helper to create fenced code block pattern for a language
+ * Helper to create fenced code block pattern for a language.
  */
 const create_fence_pattern = (backticks, aliases, lang_id, syntax_styler) => {
     const aliases_pattern = aliases.join('|');
@@ -21,7 +21,7 @@ const create_fence_pattern = (backticks, aliases, lang_id, syntax_styler) => {
     };
 };
 /**
- * Helper to create catch-all fence pattern (unknown languages)
+ * Helper to create catch-all fence pattern (unknown languages).
  */
 const create_catchall_fence = (backticks) => {
     const pattern = new RegExp(`^${backticks}[^\\n\\r]*(?:\\r?\\n|\\r)[\\s\\S]*?^${backticks}$`, 'm');
@@ -38,7 +38,7 @@ const create_catchall_fence = (backticks) => {
     };
 };
 /**
- * Helper to create md self-reference placeholder pattern
+ * Helper to create md self-reference placeholder pattern.
  */
 const create_md_placeholder = (backticks) => {
     const pattern = new RegExp(`^${backticks}(?:md|markdown)[^\\n\\r]*(?:\\r?\\n|\\r)[\\s\\S]*?^${backticks}$`, 'm');

package/dist/grammar_markup.d.ts

@@ -13,19 +13,20 @@ export declare const add_grammar_markup: AddSyntaxGrammar;
  *
  * An example of an inlined language is CSS with `<style>` tags.
  *
- * @param tag_name - The name of the tag that contains the inlined language. This name will be treated as
- * case insensitive.
- * @param lang - The language key.
+ * @param syntax_styler - the `SyntaxStyler` instance to modify
+ * @param tag_name - the name of the tag that contains the inlined language, treated as case insensitive
+ * @param lang - the language key
+ * @param inside_lang - the language to insert into, defaults to `'markup'`
  */
 export declare const grammar_markup_add_inlined: (syntax_styler: SyntaxStyler, tag_name: string, lang: string, inside_lang?: string) => void;
 /**
- * Adds an pattern to style languages embedded in HTML attributes.
+ * Adds a pattern to style languages embedded in HTML attributes.
  *
  * An example of an inlined language is CSS with `style` attributes.
  *
- * @param attr_name - The name of the tag that contains the inlined language. This name will be treated as
- * case insensitive.
- * @param lang - The language key.
+ * @param syntax_styler - the `SyntaxStyler` instance to modify
+ * @param attr_name - the name of the attribute that contains the inlined language, treated as case insensitive
+ * @param lang - the language key
  */
 export declare const grammar_markup_add_attribute: (syntax_styler: SyntaxStyler, attr_name: string, lang: string) => void;
 //# sourceMappingURL=grammar_markup.d.ts.map

package/dist/grammar_markup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grammar_markup.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/grammar_markup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,YAAY,EACZ,gBAAgB,EAIhB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,gBA6EhC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GACtC,eAAe,YAAY,EAC3B,UAAU,MAAM,EAChB,MAAM,MAAM,EACZ,oBAAsB,KACpB,IAmCF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GACxC,eAAe,YAAY,EAC3B,WAAW,MAAM,EACjB,MAAM,MAAM,KACV,IAiEF,CAAC"}
+{"version":3,"file":"grammar_markup.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/grammar_markup.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,YAAY,EACZ,gBAAgB,EAIhB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,EAAE,gBA6EhC,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GACtC,eAAe,YAAY,EAC3B,UAAU,MAAM,EAChB,MAAM,MAAM,EACZ,oBAAsB,KACpB,IAmCF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GACxC,eAAe,YAAY,EAC3B,WAAW,MAAM,EACjB,MAAM,MAAM,KACV,IAiEF,CAAC"}

package/dist/grammar_markup.js

@@ -86,9 +86,10 @@ export const add_grammar_markup = (syntax_styler) => {
  *
  * An example of an inlined language is CSS with `<style>` tags.
  *
- * @param tag_name - The name of the tag that contains the inlined language. This name will be treated as
- * case insensitive.
- * @param lang - The language key.
+ * @param syntax_styler - the `SyntaxStyler` instance to modify
+ * @param tag_name - the name of the tag that contains the inlined language, treated as case insensitive
+ * @param lang - the language key
+ * @param inside_lang - the language to insert into, defaults to `'markup'`
  */
 export const grammar_markup_add_inlined = (syntax_styler, tag_name, lang, inside_lang = 'markup') => {
     const lang_key = 'lang_' + lang;
@@ -120,13 +121,13 @@ export const grammar_markup_add_inlined = (syntax_styler, tag_name, lang, inside
     });
 };
 /**
- * Adds an pattern to style languages embedded in HTML attributes.
+ * Adds a pattern to style languages embedded in HTML attributes.
  *
  * An example of an inlined language is CSS with `style` attributes.
  *
- * @param attr_name - The name of the tag that contains the inlined language. This name will be treated as
- * case insensitive.
- * @param lang - The language key.
+ * @param syntax_styler - the `SyntaxStyler` instance to modify
+ * @param attr_name - the name of the attribute that contains the inlined language, treated as case insensitive
+ * @param lang - the language key
  */
 export const grammar_markup_add_attribute = (syntax_styler, attr_name, lang) => {
     // After normalization, grammar.tag is an array of SyntaxGrammarToken

package/dist/highlight_manager.d.ts

@@ -1,14 +1,14 @@
 import type { SyntaxTokenStream } from './syntax_token.js';
 export type HighlightMode = 'auto' | 'ranges' | 'html';
 /**
- * Check for CSS Highlights API support.
+ * Checks for CSS Highlights API support.
  */
 export declare const supports_css_highlight_api: () => boolean;
 /**
  * Manages CSS Custom Highlight API ranges for a single element.
  * Tracks ranges per element and only removes its own ranges when clearing.
  *
- * **Experimental** — limited browser support. Use `Code` for production.
+ * **Experimental** — limited browser support. Use `Code.svelte` for production.
  *
  * @example
  * ```ts
@@ -21,11 +21,11 @@ export declare class HighlightManager {
     element_ranges: Map<string, Array<Range>>;
     constructor();
     /**
-     * Highlight from syntax styler token stream.
+     * Highlights from a `SyntaxTokenStream` produced by `tokenize_syntax`.
      */
     highlight_from_syntax_tokens(element: Element, tokens: SyntaxTokenStream): void;
     /**
-     * Clear only this element's ranges from highlights.
+     * Clears only this element's ranges from highlights.
      */
     clear_element_ranges(): void;
     destroy(): void;

package/dist/highlight_manager.js

@@ -1,13 +1,13 @@
 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);
 /**
  * Manages CSS Custom Highlight API ranges for a single element.
  * Tracks ranges per element and only removes its own ranges when clearing.
  *
- * **Experimental** — limited browser support. Use `Code` for production.
+ * **Experimental** — limited browser support. Use `Code.svelte` for production.
  *
  * @example
  * ```ts
@@ -24,7 +24,7 @@ export class HighlightManager {
         this.element_ranges = new Map();
     }
     /**
-     * Highlight from syntax styler token stream.
+     * Highlights from a `SyntaxTokenStream` produced by `tokenize_syntax`.
      */
     highlight_from_syntax_tokens(element, tokens) {
         // Find the text node (it might not be firstChild due to Svelte comment nodes)
@@ -67,7 +67,7 @@ export class HighlightManager {
         }
     }
     /**
-     * Clear only this element's ranges from highlights.
+     * Clears only this element's ranges from highlights.
      */
     clear_element_ranges() {
         for (const [name, ranges] of this.element_ranges) {
@@ -88,7 +88,7 @@ export class HighlightManager {
         this.clear_element_ranges();
     }
     /**
-     * Create ranges for all tokens in the tree.
+     * Creates ranges for all tokens in the tree.
      */
     #create_all_ranges(tokens, text_node, ranges_by_type, offset) {
         const text_length = text_node.textContent?.length ?? 0;

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
@@ -83,7 +82,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 +109,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 +129,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 +143,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 +163,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 +217,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 +234,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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"}

package/dist/syntax_styler.js

@@ -79,15 +79,14 @@ export 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
@@ -140,7 +139,7 @@ export 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
@@ -167,12 +166,12 @@ export 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.
      *
@@ -187,16 +186,13 @@ export 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, before, insert, root = this.langs) {
         var grammar = root[inside];
@@ -231,9 +227,9 @@ export 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, lang) {
         if (typeof o === 'string') {
@@ -294,9 +290,9 @@ export 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, extension) {
         // Merge normalized base with un-normalized extension
@@ -307,7 +303,7 @@ export class SyntaxStyler {
         return extended;
     }
     /**
-     * Normalize a single pattern to have consistent shape.
+     * Normalizes a single pattern to have consistent shape.
      * This ensures all patterns have the same object shape for V8 optimization.
      */
     #normalize_pattern(pattern, visited) {
@@ -339,15 +335,15 @@ export class SyntaxStyler {
         };
     }
     /**
-     * Normalize a grammar to have consistent object shapes.
+     * Normalizes a grammar to have consistent object shapes.
      * This performs several optimizations:
-     * 1. Merges `rest` property into main grammar
-     * 2. Ensures all pattern values are arrays
-     * 3. Normalizes all pattern objects to have consistent shapes
-     * 4. Adds global flag to greedy patterns
+     * 1. Merges `rest` property into main grammar.
+     * 2. Ensures all pattern values are arrays.
+     * 3. Normalizes all pattern objects to have consistent shapes.
+     * 4. Adds global flag to greedy patterns.
      *
      * This is called once at registration time to avoid runtime overhead.
-     * @param visited - Set of grammar object IDs already normalized (for circular references)
+     * @param visited - set of grammar object IDs already normalized (for circular references)
      */
     #normalize_grammar(grammar, visited) {
         // Check if we've already normalized this grammar (circular reference)

package/dist/syntax_token.d.ts

@@ -2,13 +2,13 @@ export declare class SyntaxToken {
     /**
      * The type of the token.
      *
-     * This is usually the key of a pattern in a `Grammar`.
+     * This is usually the key of a pattern in a `SyntaxGrammar`.
      */
     type: string;
     /**
      * The strings or tokens contained by this token.
      *
-     * This will be a token stream if the pattern matched also defined an `inside` grammar.
+     * This will be a `SyntaxTokenStream` if the pattern matched also defined an `inside` grammar.
      */
     content: string | SyntaxTokenStream;
     /**
@@ -22,8 +22,8 @@ export declare class SyntaxToken {
 /**
  * A token stream is an array of strings and `SyntaxToken` objects.
  *
- * Syntax token streams have to fulfill a few properties that are assumed by most functions (mostly internal ones) that process
- * them.
+ * `SyntaxTokenStream` values have to fulfill a few properties that are assumed by most functions
+ * (mostly internal ones) that process them.
  *
  * 1. No adjacent strings.
  * 2. No empty strings.

package/dist/syntax_token.js

@@ -2,13 +2,13 @@ export class SyntaxToken {
     /**
      * The type of the token.
      *
-     * This is usually the key of a pattern in a `Grammar`.
+     * This is usually the key of a pattern in a `SyntaxGrammar`.
      */
     type;
     /**
      * The strings or tokens contained by this token.
      *
-     * This will be a token stream if the pattern matched also defined an `inside` grammar.
+     * This will be a `SyntaxTokenStream` if the pattern matched also defined an `inside` grammar.
      */
     content;
     /**

package/dist/tokenize_syntax.d.ts

@@ -9,11 +9,9 @@ import { type SyntaxTokenStream } from './syntax_token.js';
  * This method could be useful in other contexts as well, as a very crude parser.
  *
  * @param text - a string with the code to be styled
- * @param grammar - an object containing the tokens to use
- *
+ * @param grammar - a `SyntaxGrammar` object containing the tokens to use.
  * Usually a language definition like `syntax_styler.get_lang('markup')`.
- *
- * @returns an array of strings and tokens, a token stream
+ * @returns a `SyntaxTokenStream` array of strings and tokens
  *
  * @example
  * ```ts

package/dist/tokenize_syntax.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokenize_syntax.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tokenize_syntax.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAc,KAAK,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,EAAE,SAAS,aAAa,KAAG,iBAQtE,CAAC"}
+{"version":3,"file":"tokenize_syntax.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tokenize_syntax.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAc,KAAK,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,EAAE,SAAS,aAAa,KAAG,iBAQtE,CAAC"}

package/dist/tokenize_syntax.js

@@ -8,11 +8,9 @@ import { SyntaxToken } from './syntax_token.js';
  * This method could be useful in other contexts as well, as a very crude parser.
  *
  * @param text - a string with the code to be styled
- * @param grammar - an object containing the tokens to use
- *
+ * @param grammar - a `SyntaxGrammar` object containing the tokens to use.
  * Usually a language definition like `syntax_styler.get_lang('markup')`.
- *
- * @returns an array of strings and tokens, a token stream
+ * @returns a `SyntaxTokenStream` array of strings and tokens
  *
  * @example
  * ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_code",
-  "version": "0.45.1",
+  "version": "0.46.0",
   "description": "syntax styling utilities and components for TypeScript, Svelte, Markdown, and more",
   "glyph": "🎨",
   "logo": "logo.svg",
@@ -24,48 +24,45 @@
     "preview": "vite preview",
     "deploy": "gro deploy",
     "benchmark": "gro run benchmark/run_benchmarks.ts",
-    "benchmark:compare": "gro run benchmark/compare/run_compare.ts",
+    "benchmark:save": "gro run benchmark/run_benchmarks.ts --save",
+    "benchmark:clean": "rm -f benchmark/baseline.json",
+    "benchmark:vs": "gro run benchmark/compare/run_compare.ts",
+    "benchmark:vs:write": "gro run benchmark/compare/run_compare.ts --write",
     "fixtures:update": "gro src/test/fixtures/update"
   },
   "type": "module",
   "engines": {
-    "node": ">=22.15"
+    "node": ">=24.14"
   },
   "peerDependencies": {
-    "@fuzdev/fuz_css": ">=0.47.0",
-    "@fuzdev/fuz_util": ">=0.49.2",
+    "@fuzdev/fuz_css": ">=0.62.0",
+    "@fuzdev/fuz_util": ">=0.65.1",
     "esm-env": "^1",
-    "magic-string": "^0.30",
-    "svelte": "^5",
-    "zimmerframe": "^1"
+    "svelte": "^5"
   },
   "peerDependenciesMeta": {
     "@fuzdev/fuz_css": {
       "optional": true
     },
-    "@fuzdev/fuz_util": {
-      "optional": true
-    },
-    "magic-string": {
-      "optional": true
-    },
     "svelte": {
       "optional": true
-    },
-    "zimmerframe": {
-      "optional": true
     }
   },
+  "dependencies": {
+    "magic-string": "^0.30.21",
+    "zimmerframe": "^1.1.4"
+  },
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
-    "@fuzdev/fuz_css": "^0.50.0",
-    "@fuzdev/fuz_ui": "^0.183.1",
-    "@fuzdev/fuz_util": "^0.51.0",
-    "@fuzdev/gro": "^0.194.0",
-    "@jridgewell/trace-mapping": "^0.3.31",
-    "@ryanatkn/eslint-config": "^0.9.0",
+    "@fuzdev/blake3_wasm": "^0.1.1",
+    "@fuzdev/fuz_css": "^0.62.0",
+    "@fuzdev/fuz_ui": "^0.199.0",
+    "@fuzdev/fuz_util": "^0.65.1",
+    "@fuzdev/gro": "^0.203.0",
+    "@ryanatkn/eslint-config": "^0.12.1",
+    "@sveltejs/acorn-typescript": "^1.0.9",
     "@sveltejs/adapter-static": "^3.0.10",
-    "@sveltejs/kit": "^2.50.1",
+    "@sveltejs/kit": "^2.63.0",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@types/estree": "^1.0.8",
@@ -74,17 +71,17 @@
     "eslint": "^9.39.1",
     "eslint-plugin-svelte": "^3.13.1",
     "esm-env": "^1.2.2",
-    "magic-string": "^0.30.21",
     "prettier": "^3.7.4",
     "prettier-plugin-svelte": "^3.4.1",
-    "svelte": "^5.49.1",
-    "svelte-check": "^4.3.6",
-    "svelte2tsx": "^0.7.47",
+    "svelte": "^5.56.2",
+    "svelte-check": "^4.6.0",
+    "svelte-docinfo": "^0.3.0",
+    "svelte2tsx": "^0.7.55",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.48.1",
+    "vite": "^7.3.1",
     "vitest": "^4.0.15",
-    "zimmerframe": "^1.1.4",
     "zod": "^4.3.6"
   },
   "prettier": {

package/src/lib/grammar_markdown.ts

@@ -16,7 +16,7 @@ interface FenceType {
 }
 
 /**
- * Helper to create fenced code block pattern for a language
+ * Helper to create fenced code block pattern for a language.
  */
 const create_fence_pattern = (
 	backticks: string,
@@ -48,7 +48,7 @@ const create_fence_pattern = (
 };
 
 /**
- * Helper to create catch-all fence pattern (unknown languages)
+ * Helper to create catch-all fence pattern (unknown languages).
  */
 const create_catchall_fence = (backticks: string): SyntaxGrammarTokenRaw => {
 	const pattern = new RegExp(`^${backticks}[^\\n\\r]*(?:\\r?\\n|\\r)[\\s\\S]*?^${backticks}$`, 'm');
@@ -67,7 +67,7 @@ const create_catchall_fence = (backticks: string): SyntaxGrammarTokenRaw => {
 };
 
 /**
- * Helper to create md self-reference placeholder pattern
+ * Helper to create md self-reference placeholder pattern.
  */
 const create_md_placeholder = (backticks: string): SyntaxGrammarTokenRaw => {
 	const pattern = new RegExp(

package/src/lib/grammar_markup.ts

@@ -98,9 +98,10 @@ export const add_grammar_markup: AddSyntaxGrammar = (syntax_styler) => {
  *
  * An example of an inlined language is CSS with `<style>` tags.
  *
- * @param tag_name - The name of the tag that contains the inlined language. This name will be treated as
- * case insensitive.
- * @param lang - The language key.
+ * @param syntax_styler - the `SyntaxStyler` instance to modify
+ * @param tag_name - the name of the tag that contains the inlined language, treated as case insensitive
+ * @param lang - the language key
+ * @param inside_lang - the language to insert into, defaults to `'markup'`
  */
 export const grammar_markup_add_inlined = (
 	syntax_styler: SyntaxStyler,
@@ -145,13 +146,13 @@ export const grammar_markup_add_inlined = (
 };
 
 /**
- * Adds an pattern to style languages embedded in HTML attributes.
+ * Adds a pattern to style languages embedded in HTML attributes.
  *
  * An example of an inlined language is CSS with `style` attributes.
  *
- * @param attr_name - The name of the tag that contains the inlined language. This name will be treated as
- * case insensitive.
- * @param lang - The language key.
+ * @param syntax_styler - the `SyntaxStyler` instance to modify
+ * @param attr_name - the name of the attribute that contains the inlined language, treated as case insensitive
+ * @param lang - the language key
  */
 export const grammar_markup_add_attribute = (
 	syntax_styler: SyntaxStyler,

package/src/lib/highlight_manager.ts

@@ -4,16 +4,16 @@ import {highlight_priorities} from './highlight_priorities.js';
 export type HighlightMode = 'auto' | 'ranges' | 'html';
 
 /**
- * Check for CSS Highlights API support.
+ * Checks for CSS Highlights API support.
  */
 export const supports_css_highlight_api = (): boolean =>
-	!!(globalThis.CSS?.highlights && globalThis.Highlight); // eslint-disable-line @typescript-eslint/no-unnecessary-condition
+	!!(globalThis.CSS?.highlights && globalThis.Highlight);
 
 /**
  * Manages CSS Custom Highlight API ranges for a single element.
  * Tracks ranges per element and only removes its own ranges when clearing.
  *
- * **Experimental** — limited browser support. Use `Code` for production.
+ * **Experimental** — limited browser support. Use `Code.svelte` for production.
  *
  * @example
  * ```ts
@@ -32,7 +32,7 @@ export class HighlightManager {
 	}
 
 	/**
-	 * Highlight from syntax styler token stream.
+	 * Highlights from a `SyntaxTokenStream` produced by `tokenize_syntax`.
 	 */
 	highlight_from_syntax_tokens(element: Element, tokens: SyntaxTokenStream): void {
 		// Find the text node (it might not be firstChild due to Svelte comment nodes)
@@ -85,7 +85,7 @@ export class HighlightManager {
 	}
 
 	/**
-	 * Clear only this element's ranges from highlights.
+	 * Clears only this element's ranges from highlights.
 	 */
 	clear_element_ranges(): void {
 		for (const [name, ranges] of this.element_ranges) {
@@ -111,7 +111,7 @@ export class HighlightManager {
 	}
 
 	/**
-	 * Create ranges for all tokens in the tree.
+	 * Creates ranges for all tokens in the tree.
 	 */
 	#create_all_ranges(
 		tokens: SyntaxTokenStream,

package/src/lib/svelte_preprocess_fuz_code.ts

@@ -23,15 +23,15 @@ 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']
 	 */
@@ -48,7 +48,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
@@ -141,7 +141,7 @@ interface FindCodeUsagesOptions {
 }
 
 /**
- * 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 = (
@@ -165,7 +165,7 @@ const try_highlight = (
 };
 
 /**
- * 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 = (

package/src/lib/syntax_styler.ts

@@ -92,15 +92,14 @@ export 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
@@ -158,7 +157,7 @@ export 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
@@ -185,12 +184,12 @@ export 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.
 	 *
@@ -205,16 +204,13 @@ export 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,
@@ -261,9 +257,9 @@ export 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 {
 		if (typeof o === 'string') {
@@ -332,9 +328,9 @@ export 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 {
 		// Merge normalized base with un-normalized extension
@@ -346,7 +342,7 @@ export class SyntaxStyler {
 	}
 
 	/**
-	 * Normalize a single pattern to have consistent shape.
+	 * Normalizes a single pattern to have consistent shape.
 	 * This ensures all patterns have the same object shape for V8 optimization.
 	 */
 	#normalize_pattern(
@@ -387,15 +383,15 @@ export class SyntaxStyler {
 	}
 
 	/**
-	 * Normalize a grammar to have consistent object shapes.
+	 * Normalizes a grammar to have consistent object shapes.
 	 * This performs several optimizations:
-	 * 1. Merges `rest` property into main grammar
-	 * 2. Ensures all pattern values are arrays
-	 * 3. Normalizes all pattern objects to have consistent shapes
-	 * 4. Adds global flag to greedy patterns
+	 * 1. Merges `rest` property into main grammar.
+	 * 2. Ensures all pattern values are arrays.
+	 * 3. Normalizes all pattern objects to have consistent shapes.
+	 * 4. Adds global flag to greedy patterns.
 	 *
 	 * This is called once at registration time to avoid runtime overhead.
-	 * @param visited - Set of grammar object IDs already normalized (for circular references)
+	 * @param visited - set of grammar object IDs already normalized (for circular references)
 	 */
 	#normalize_grammar(grammar: SyntaxGrammarRaw, visited: Set<number>): void {
 		// Check if we've already normalized this grammar (circular reference)
@@ -510,14 +506,14 @@ 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;
@@ -529,7 +525,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>>;
 

package/src/lib/syntax_token.ts

@@ -2,14 +2,14 @@ export class SyntaxToken {
 	/**
 	 * The type of the token.
 	 *
-	 * This is usually the key of a pattern in a `Grammar`.
+	 * This is usually the key of a pattern in a `SyntaxGrammar`.
 	 */
 	type: string;
 
 	/**
 	 * The strings or tokens contained by this token.
 	 *
-	 * This will be a token stream if the pattern matched also defined an `inside` grammar.
+	 * This will be a `SyntaxTokenStream` if the pattern matched also defined an `inside` grammar.
 	 */
 	content: string | SyntaxTokenStream;
 
@@ -38,8 +38,8 @@ export class SyntaxToken {
 /**
  * A token stream is an array of strings and `SyntaxToken` objects.
  *
- * Syntax token streams have to fulfill a few properties that are assumed by most functions (mostly internal ones) that process
- * them.
+ * `SyntaxTokenStream` values have to fulfill a few properties that are assumed by most functions
+ * (mostly internal ones) that process them.
  *
  * 1. No adjacent strings.
  * 2. No empty strings.

package/src/lib/tokenize_syntax.ts

@@ -10,11 +10,9 @@ import {SyntaxToken, type SyntaxTokenStream} from './syntax_token.js';
  * This method could be useful in other contexts as well, as a very crude parser.
  *
  * @param text - a string with the code to be styled
- * @param grammar - an object containing the tokens to use
- *
+ * @param grammar - a `SyntaxGrammar` object containing the tokens to use.
  * Usually a language definition like `syntax_styler.get_lang('markup')`.
- *
- * @returns an array of strings and tokens, a token stream
+ * @returns a `SyntaxTokenStream` array of strings and tokens
  *
  * @example
  * ```ts