@fuzdev/fuz_code 0.46.0 → 0.46.2

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/syntax_styler.d.ts

@@ -65,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.
      *

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

@@ -1,5 +1,11 @@
 import { SyntaxToken } from './syntax_token.js';
 import { tokenize_syntax } from './tokenize_syntax.js';
+/**
+ * Maps a matched `&`, `<`, or non-breaking space in text content to its
+ * HTML-safe form. Used as the replacer in `stringify_token` for leaf strings
+ * (non-breaking spaces are normalized to a regular space).
+ */
+const escape_text_char = (ch) => (ch === '&' ? '&amp;' : ch === '<' ? '&lt;' : ' ');
 /**
  * Based on Prism (https://github.com/PrismJS/prism)
  * by Lea Verou (https://lea.verou.me/)
@@ -110,7 +116,32 @@ export class SyntaxStyler {
      * ```
      */
     stylize(text, lang, grammar = this.get_lang(lang)) {
-        var ctx = {
+        // stringify with the post-hook `lang`, which a `before_tokenize` hook may
+        // have rewritten (it flows into each token's `wrap` hook context)
+        const c = this.#tokenize_hooked(text, lang, grammar);
+        return this.stringify_token(c.tokens, c.lang);
+    }
+    /**
+     * 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, lang, grammar = this.get_lang(lang)) {
+        return this.#tokenize_hooked(text, lang, grammar).tokens;
+    }
+    /**
+     * Runs `before_tokenize` → `tokenize_syntax` → `after_tokenize`, returning the
+     * resolved context. Shared by `stylize` (which also needs the post-hook `lang`)
+     * and `tokenize` (which only needs `tokens`).
+     */
+    #tokenize_hooked(text, lang, grammar) {
+        const ctx = {
             code: text,
             grammar,
             lang,
@@ -120,7 +151,7 @@ export class SyntaxStyler {
         const c = ctx;
         c.tokens = tokenize_syntax(c.code, c.grammar);
         this.run_hook_after_tokenize(c);
-        return this.stringify_token(c.tokens, c.lang);
+        return c;
     }
     /**
      * Inserts tokens _before_ another token in a language definition or any other grammar.
@@ -233,10 +264,9 @@ export class SyntaxStyler {
      */
     stringify_token(o, lang) {
         if (typeof o === 'string') {
-            return o
-                .replace(/&/g, '&amp;')
-                .replace(/</g, '&lt;')
-                .replace(/\u00a0/g, ' ');
+            // single pass over the leaf text (only `&` and `<` need escaping in text
+            // content; `\u00a0` is normalized to a regular space)
+            return o.replace(/[&<\u00a0]/g, escape_text_char);
         }
         if (Array.isArray(o)) {
             var s = '';
@@ -245,19 +275,25 @@ export class SyntaxStyler {
             }
             return s;
         }
+        var content = this.stringify_token(o.content, lang);
+        // build the class list once; aliases are always an array after normalization
+        var classes = `token_${o.type}`;
+        for (const a of o.alias) {
+            classes += ` token_${a}`;
+        }
+        // fast path: with no `wrap` hooks the tag is always a plain <span> with no
+        // attributes, so skip the per-token context object and hook dispatch
+        if (this.hooks_wrap.length === 0) {
+            return '<span class="' + classes + '">' + content + '</span>';
+        }
         var ctx = {
             type: o.type,
-            content: this.stringify_token(o.content, lang),
+            content,
             tag: 'span',
-            classes: [`token_${o.type}`],
+            classes: classes.split(' '),
             attributes: {},
             lang,
         };
-        var aliases = o.alias;
-        // alias is always an array after normalization
-        for (const a of aliases) {
-            ctx.classes.push(`token_${a}`);
-        }
         this.run_hook_wrap(ctx);
         var attributes = '';
         for (var name in ctx.attributes) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_code",
-  "version": "0.46.0",
+  "version": "0.46.2",
   "description": "syntax styling utilities and components for TypeScript, Svelte, Markdown, and more",
   "glyph": "🎨",
   "logo": "logo.svg",
@@ -55,10 +55,11 @@
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
     "@fuzdev/blake3_wasm": "^0.1.1",
-    "@fuzdev/fuz_css": "^0.62.0",
-    "@fuzdev/fuz_ui": "^0.199.0",
+    "@fuzdev/fuz_css": "^0.63.2",
+    "@fuzdev/fuz_ui": "^0.205.1",
     "@fuzdev/fuz_util": "^0.65.1",
-    "@fuzdev/gro": "^0.203.0",
+    "@fuzdev/gro": "^0.204.0",
+    "@fuzdev/mdz": "^0.1.0",
     "@ryanatkn/eslint-config": "^0.12.1",
     "@sveltejs/acorn-typescript": "^1.0.9",
     "@sveltejs/adapter-static": "^3.0.10",
@@ -75,7 +76,7 @@
     "prettier-plugin-svelte": "^3.4.1",
     "svelte": "^5.56.2",
     "svelte-check": "^4.6.0",
-    "svelte-docinfo": "^0.3.0",
+    "svelte-docinfo": "^0.5.1",
     "svelte2tsx": "^0.7.55",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",

package/src/lib/highlight_manager.ts

@@ -1,3 +1,5 @@
+import {DEV} from 'esm-env';
+
 import type {SyntaxTokenStream} from './syntax_token.js';
 import {highlight_priorities} from './highlight_priorities.js';
 
@@ -10,10 +12,55 @@ export const supports_css_highlight_api = (): boolean =>
 	!!(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.
+ * How a manager builds ranges for the Highlight API.
  *
- * **Experimental** — limited browser support. Use `Code.svelte` for production.
+ * `StaticRange` is preferred: it's an immutable snapshot the browser does *not*
+ * track across DOM mutations. Since highlights are rebuilt wholesale whenever
+ * content changes, liveness buys nothing and only costs per-mutation boundary
+ * bookkeeping and paint work — the main efficiency (and Safari-stability) lever.
+ * Falls back to a live `Range` where `StaticRange` is unavailable.
+ */
+type RangeKind = 'static' | 'live';
+
+const detect_range_kind = (): RangeKind =>
+	typeof globalThis.StaticRange === 'function' ? 'static' : 'live';
+
+/**
+ * Finds the first text node child of `element`, or `null` if there is none.
+ *
+ * The text node might not be `firstChild` because frameworks (e.g. Svelte) can
+ * insert comment/anchor nodes around it.
+ */
+const find_text_node = (element: Element): Node | null => {
+	for (const node of element.childNodes) {
+		if (node.nodeType === Node.TEXT_NODE) return node;
+	}
+	return null;
+};
+
+const has_tokens = (tokens: SyntaxTokenStream): boolean =>
+	tokens.some((t) => typeof t !== 'string');
+
+const push_range = (
+	ranges_by_name: Map<string, Array<AbstractRange>>,
+	name: string,
+	range: AbstractRange,
+): void => {
+	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
@@ -22,62 +69,94 @@ export const supports_css_highlight_api = (): boolean =>
  * ```
  */
 export class HighlightManager {
-	element_ranges: Map<string, Array<Range>>;
+	/**
+	 * 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: Map<string, Array<AbstractRange>>;
+
+	#range_kind: RangeKind;
 
 	constructor() {
 		if (!supports_css_highlight_api()) {
 			throw Error('CSS Highlights API not supported');
 		}
 		this.element_ranges = new Map();
+		this.#range_kind = detect_range_kind();
 	}
 
 	/**
-	 * Highlights from a `SyntaxTokenStream` produced by `tokenize_syntax`.
+	 * 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: Element, tokens: SyntaxTokenStream): void {
-		// Find the text node (it might not be firstChild due to Svelte comment nodes)
-		let text_node: Node | null = 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) {
-			throw new Error('no text node to highlight');
+			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;
 		}
 
-		this.clear_element_ranges();
+		try {
+			this.#apply(text_node, tokens);
+		} 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;
+			}
+		}
+	}
 
-		const ranges_by_type: Map<string, Array<Range>> = new Map();
-		const final_pos = this.#create_all_ranges(tokens, text_node, ranges_by_type, 0);
+	#apply(text_node: Node, tokens: SyntaxTokenStream): void {
+		const ranges_by_name: Map<string, Array<AbstractRange>> = new Map();
+		const final_pos = this.#collect_ranges(tokens, text_node, ranges_by_name, 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`,
-			);
+		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);
+		// 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);
 
-			// Get or create the shared highlight
-			let highlight = CSS.highlights.get(prefixed_type);
+			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 as keyof typeof highlight_priorities] ?? 0;
-				CSS.highlights.set(prefixed_type, highlight);
+				// priority follows CSS cascade order (higher = later in CSS = wins)
+				highlight.priority = highlight_priorities[name as keyof typeof highlight_priorities] ?? 0;
+				CSS.highlights.set(name, highlight);
 			}
 
-			// Add all ranges to the highlight
 			for (const range of ranges) {
 				highlight.add(range);
 			}
@@ -85,14 +164,14 @@ export class HighlightManager {
 	}
 
 	/**
-	 * Clears 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(): void {
 		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);
@@ -110,13 +189,29 @@ export class HighlightManager {
 		this.clear_element_ranges();
 	}
 
+	#make_range(text_node: Node, start: number, end: number): AbstractRange {
+		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;
+	}
+
 	/**
-	 * Creates 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(
+	#collect_ranges(
 		tokens: SyntaxTokenStream,
 		text_node: Node,
-		ranges_by_type: Map<string, Array<Range>>,
+		ranges_by_name: Map<string, Array<AbstractRange>>,
 		offset: number,
 	): number {
 		const text_length = text_node.textContent?.length ?? 0;
@@ -128,61 +223,36 @@ export class HighlightManager {
 				continue;
 			}
 
-			const length = token.length;
-			const end_pos = pos + length;
+			const end_pos = pos + token.length;
 
-			// Validate positions are within text node bounds before creating ranges
-			if (end_pos > text_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) {
+				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 ${length} chars (${pos}-${end_pos}) but nested content covered ${actual_end_pos - pos} chars (${pos}-${actual_end_pos})`,
+						`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;