diff --git a/.changeset/red-places-argue.md b/.changeset/red-places-argue.md
new file mode 100644
index 00000000..f2b0996d
--- /dev/null
+++ b/.changeset/red-places-argue.md
@@ -0,0 +1,5 @@
+---
+'@ryanatkn/fuz_code': minor
+---
+
+rename `Syntax_Grammar_Raw` from `Syntax_Grammar` and `Syntax_Grammar` from `Normalized_Syntax_Grammar`
diff --git a/README.md b/README.md
index a3ad9864..d45a620e 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 [<img src="static/logo.svg" alt="a friendly pink spider facing you" align="right" width="192" height="192">](https://code.fuz.dev/)
 
-> syntax styling utilities and components for TypeScript, Svelte, SvelteKit 🎨
+> syntax styling utilities and components for TypeScript, Svelte, and Markdown 🎨
 
 **[code.fuz.dev](https://code.fuz.dev/)**
 
diff --git a/benchmark/compare/compare.ts b/benchmark/compare/compare.ts
index bc6cbf43..76f7dfe2 100644
--- a/benchmark/compare/compare.ts
+++ b/benchmark/compare/compare.ts
@@ -150,7 +150,7 @@ export const run_comparison_benchmark = async (
 			});
 
 			// Prism tokenize benchmark
-			if ((Prism.languages as any)[prism_lang]) {
+			if (Prism.languages[prism_lang]) {
 				bench.add(`prism_tokenize_${lang}_${size_label}`, () => {
 					Prism.tokenize(content, Prism.languages[prism_lang]);
 				});
@@ -163,7 +163,7 @@ export const run_comparison_benchmark = async (
 			});
 
 			// Prism stylize benchmark
-			if ((Prism.languages as any)[prism_lang]) {
+			if (Prism.languages[prism_lang]) {
 				bench.add(`prism_stylize_${lang}_${size_label}`, () => {
 					Prism.highlight(content, Prism.languages[prism_lang], prism_lang);
 				});
diff --git a/package.json b/package.json
index 61b9c9f2..808231a7 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@ryanatkn/fuz_code",
   "version": "0.28.0",
-  "description": "syntax styling utilities and components for TypeScript, Svelte, SvelteKit",
+  "description": "syntax styling utilities and components for TypeScript, Svelte, and Markdown",
   "glyph": "🎨",
   "logo": "logo.svg",
   "logo_alt": "a friendly pink spider facing you",
diff --git a/src/fixtures/helpers.ts b/src/fixtures/helpers.ts
index 88fe263e..bf7c0395 100644
--- a/src/fixtures/helpers.ts
+++ b/src/fixtures/helpers.ts
@@ -33,7 +33,8 @@ export const discover_samples = (): Array<Sample_Spec> => {
 		const match = /sample_([^.]+)\.(.+)$/.exec(filename);
 		if (!match) continue;
 
-		const [, variant, lang] = match;
+		const variant = match[1]!;
+		const lang = match[2]!;
 		const content = readFileSync(file.id, 'utf-8');
 
 		samples.push({
diff --git a/src/lib/Code.svelte b/src/lib/Code.svelte
index 6150f49f..3e390e4a 100644
--- a/src/lib/Code.svelte
+++ b/src/lib/Code.svelte
@@ -1,5 +1,6 @@
 <script lang="ts">
 	import type {Snippet} from 'svelte';
+	import {DEV} from 'esm-env';
 
 	import {syntax_styler_global} from '$lib/syntax_styler_global.js';
 	import type {Syntax_Styler, Syntax_Grammar} from '$lib/syntax_styler.js';
@@ -14,13 +15,64 @@
 		syntax_styler = syntax_styler_global,
 		children,
 	}: {
+		/** The source code to syntax highlight. */
 		content: string;
+		/**
+		 * Language identifier (e.g., 'ts', 'css', 'html', 'json', 'svelte', 'md').
+		 *
+		 * **Purpose:**
+		 * - When `grammar` is not provided, used to look up the grammar via `syntax_styler.get_lang(lang)`
+		 * - Used for metadata: sets the `data-lang` attribute and determines `language_supported`
+		 *
+		 * **Special values:**
+		 * - `null` - Explicitly disables syntax highlighting (content rendered as plain text)
+		 * - `undefined` - Falls back to default ('svelte')
+		 *
+		 * **Relationship with `grammar`:**
+		 * - If both `lang` and `grammar` are provided, `grammar` takes precedence for tokenization
+		 * - However, `lang` is still used for the `data-lang` attribute and language detection
+		 *
+		 * @default 'svelte'
+		 */
 		lang?: string | null;
+		/** Additional attributes to apply to the outer `<pre>` or `<span>` element. */
 		pre_attrs?: any;
+		/** Additional attributes to apply to the inner `<code>` element. */
 		code_attrs?: any;
+		/**
+		 * Optional custom grammar object for syntax tokenization.
+		 *
+		 * **When to use:**
+		 * - To provide a custom language definition not registered in `syntax_styler.langs`
+		 * - To use a modified/extended version of an existing grammar
+		 * - For one-off grammar variations without registering globally
+		 *
+		 * **Behavior:**
+		 * - When provided, this grammar is used for tokenization instead of looking up via `lang`
+		 * - Enables highlighting even if `lang` is not in the registry (useful for custom languages)
+		 * - The `lang` parameter is still used for metadata (data-lang attribute)
+		 * - When undefined, the grammar is automatically looked up via `syntax_styler.get_lang(lang)`
+		 *
+		 * @default undefined (uses grammar from `syntax_styler.langs[lang]`)
+		 */
 		grammar?: Syntax_Grammar | undefined;
+		/**
+		 * Whether to render inline code (uses `<span>`) or block code (uses `<pre>`).
+		 *
+		 * @default false
+		 */
 		inline?: boolean;
+		/**
+		 * Custom Syntax_Styler instance to use for highlighting.
+		 * Allows using a different styler with custom grammars or configuration.
+		 *
+		 * @default syntax_styler_global
+		 */
 		syntax_styler?: Syntax_Styler;
+		/**
+		 * Optional snippet to customize how the highlighted markup is rendered.
+		 * Receives the generated HTML string as a parameter.
+		 */
 		children?: Snippet<[markup: string]>;
 	} = $props();
 
@@ -28,7 +80,21 @@
 
 	const language_supported = $derived(lang !== null && !!syntax_styler.langs[lang]);
 
-	const highlighting_disabled = $derived(lang === null || !language_supported);
+	const highlighting_disabled = $derived(lang === null || (!language_supported && !grammar));
+
+	// DEV-only validation warnings
+	if (DEV) {
+		$effect(() => {
+			if (lang && !language_supported && !grammar) {
+				const langs = Object.keys(syntax_styler.langs).join(', ');
+				// eslint-disable-next-line no-console
+				console.error(
+					`[Code] Language "${lang}" is not supported and no custom grammar provided. ` +
+						`Highlighting disabled. Supported: ${langs}`,
+				);
+			}
+		});
+	}
 
 	// Generate HTML markup for syntax highlighting
 	const html_content = $derived.by(() => {
diff --git a/src/lib/Code_Highlight.svelte b/src/lib/Code_Highlight.svelte
index ef95298d..1377ef57 100644
--- a/src/lib/Code_Highlight.svelte
+++ b/src/lib/Code_Highlight.svelte
@@ -1,9 +1,13 @@
-<script lang="ts" module>
-	const supports_ranges = supports_css_highlight_api();
-</script>
-
 <script lang="ts">
+	/**
+	 * 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.
+	 */
+
 	import {onDestroy, type Snippet} from 'svelte';
+	import {DEV} from 'esm-env';
 
 	import {syntax_styler_global} from '$lib/syntax_styler_global.js';
 	import type {Syntax_Styler, Syntax_Grammar} from '$lib/syntax_styler.js';
@@ -25,19 +29,88 @@
 		syntax_styler = syntax_styler_global,
 		children,
 	}: {
+		/** The source code to syntax highlight. */
 		content: string;
+		/**
+		 * Language identifier (e.g., 'ts', 'css', 'html', 'json', 'svelte', 'md').
+		 *
+		 * **Purpose:**
+		 * - When `grammar` is not provided, used to look up the grammar via `syntax_styler.get_lang(lang)`
+		 * - Used for metadata: sets the `data-lang` attribute and determines `language_supported`
+		 *
+		 * **Special values:**
+		 * - `null` - Explicitly disables syntax highlighting (content rendered as plain text)
+		 * - `undefined` - Falls back to default ('svelte')
+		 *
+		 * **Relationship with `grammar`:**
+		 * - If both `lang` and `grammar` are provided, `grammar` takes precedence for tokenization
+		 * - However, `lang` is still used for the `data-lang` attribute and language detection
+		 *
+		 * @default 'svelte'
+		 */
 		lang?: string | null;
+		/**
+		 * Highlighting mode for this component.
+		 *
+		 * **Options:**
+		 * - `'auto'` - Uses CSS Custom Highlight API if supported, falls back to HTML mode
+		 * - `'ranges'` - Forces CSS Custom Highlight API (requires browser support)
+		 * - `'html'` - Forces HTML generation with CSS classes
+		 *
+		 * **Note:** CSS Custom Highlight API has limitations and limited browser support.
+		 * Requires importing `theme_highlight.css` instead of `theme.css`.
+		 *
+		 * @default 'auto'
+		 */
 		mode?: Highlight_Mode;
+		/** Additional attributes to apply to the outer `<pre>` or `<span>` element. */
 		pre_attrs?: any;
+		/** Additional attributes to apply to the inner `<code>` element. */
 		code_attrs?: any;
+		/**
+		 * Optional custom grammar object for syntax tokenization.
+		 *
+		 * **When to use:**
+		 * - To provide a custom language definition not registered in `syntax_styler.langs`
+		 * - To use a modified/extended version of an existing grammar
+		 * - For one-off grammar variations without registering globally
+		 *
+		 * **Behavior:**
+		 * - When provided, this grammar is used for tokenization instead of looking up via `lang`
+		 * - Enables highlighting even if `lang` is not in the registry (useful for custom languages)
+		 * - The `lang` parameter is still used for metadata (data-lang attribute)
+		 * - When undefined, the grammar is automatically looked up:
+		 *   - In HTML mode: via `syntax_styler.get_lang(lang)` (automatic fallback in `stylize()`)
+		 *   - In range mode: via `grammar || syntax_styler.get_lang(lang)` (explicit fallback)
+		 *
+		 * @default undefined (uses grammar from `syntax_styler.langs[lang]`)
+		 */
 		grammar?: Syntax_Grammar | undefined;
+		/**
+		 * Whether to render inline code (uses `<span>`) or block code (uses `<pre>`).
+		 *
+		 * @default false
+		 */
 		inline?: boolean;
+		/**
+		 * Custom Syntax_Styler instance to use for highlighting.
+		 * Allows using a different styler with custom grammars or configuration.
+		 *
+		 * @default syntax_styler_global
+		 */
 		syntax_styler?: Syntax_Styler;
+		/**
+		 * Optional snippet to customize how the highlighted markup is rendered.
+		 * - In HTML mode: receives the generated HTML string
+		 * - In range mode: receives the plain text content
+		 */
 		children?: Snippet<[markup: string]>;
 	} = $props();
 
 	let code_element: HTMLElement | undefined = $state();
 
+	const supports_ranges = supports_css_highlight_api();
+
 	const highlight_manager = supports_ranges ? new Highlight_Manager() : null;
 
 	const use_ranges = $derived(supports_ranges && (mode === 'ranges' || mode === 'auto'));
@@ -46,7 +119,21 @@
 
 	const language_supported = $derived(lang !== null && !!syntax_styler.langs[lang]);
 
-	const highlighting_disabled = $derived(lang === null || !language_supported);
+	const highlighting_disabled = $derived(lang === null || (!language_supported && !grammar));
+
+	// DEV-only validation warnings
+	if (DEV) {
+		$effect(() => {
+			if (lang && !language_supported && !grammar) {
+				const langs = Object.keys(syntax_styler.langs).join(', ');
+				// eslint-disable-next-line no-console
+				console.error(
+					`[Code_Highlight] Language "${lang}" is not supported and no custom grammar provided. ` +
+						`Highlighting disabled. Supported: ${langs}`,
+				);
+			}
+		});
+	}
 
 	// Generate HTML markup for syntax highlighting in non-range mode
 	const html_content = $derived.by(() => {
diff --git a/src/lib/grammar_clike.ts b/src/lib/grammar_clike.ts
index d2de8257..b837861c 100644
--- a/src/lib/grammar_clike.ts
+++ b/src/lib/grammar_clike.ts
@@ -1,4 +1,4 @@
-import type {Add_Syntax_Grammar, Syntax_Grammar} from '$lib/syntax_styler.js';
+import type {Add_Syntax_Grammar, Syntax_Grammar_Raw} from '$lib/syntax_styler.js';
 
 export const class_keywords = 'class|extends|implements|instanceof|interface|new';
 
@@ -42,7 +42,7 @@ export const add_grammar_clike: Add_Syntax_Grammar = (syntax_styler) => {
 		number: /\b0x[\da-f]+\b|(?:\b\d+(?:\.\d*)?|\B\.\d+)(?:e[+-]?\d+)?/i,
 		operator: /[<>]=?|[!=]=?=?|--?|\+\+?|&&?|\|\|?|[?*/~^%]/,
 		punctuation: /[{}[\];(),.:]/,
-	} satisfies Syntax_Grammar;
+	} satisfies Syntax_Grammar_Raw;
 
 	syntax_styler.add_lang('clike', grammar_clike);
 };
diff --git a/src/lib/grammar_css.ts b/src/lib/grammar_css.ts
index c6171d75..c9b1447c 100644
--- a/src/lib/grammar_css.ts
+++ b/src/lib/grammar_css.ts
@@ -1,4 +1,4 @@
-import type {Add_Syntax_Grammar, Syntax_Grammar} from '$lib/syntax_styler.js';
+import type {Add_Syntax_Grammar, Syntax_Grammar_Raw} from '$lib/syntax_styler.js';
 import {grammar_markup_add_attribute, grammar_markup_add_inlined} from '$lib/grammar_markup.js';
 
 var string = /(?:"(?:\\(?:\r\n|[\s\S])|[^"\\\r\n])*"|'(?:\\(?:\r\n|[\s\S])|[^'\\\r\n])*')/;
@@ -35,7 +35,7 @@ export const add_grammar_css: Add_Syntax_Grammar = (syntax_styler) => {
 					pattern: /(^|[^\w-])(?:and|not|only|or)(?![\w-])/,
 					lookbehind: true,
 				},
-			} as Syntax_Grammar, // see `rest` below
+			} as Syntax_Grammar_Raw, // see `rest` below
 		},
 		url: {
 			// https://drafts.csswg.org/css-values-3/#urls
@@ -73,7 +73,7 @@ export const add_grammar_css: Add_Syntax_Grammar = (syntax_styler) => {
 			lookbehind: true,
 		},
 		punctuation: /[(){};:,]/,
-	} satisfies Syntax_Grammar;
+	} satisfies Syntax_Grammar_Raw;
 
 	grammar_css.atrule.inside.rest = grammar_css;
 
diff --git a/src/lib/grammar_js.ts b/src/lib/grammar_js.ts
index df49e776..672e8ccf 100644
--- a/src/lib/grammar_js.ts
+++ b/src/lib/grammar_js.ts
@@ -30,7 +30,7 @@ export const add_grammar_js: Add_Syntax_Grammar = (syntax_styler) => {
 		'js',
 		{
 			class_name: [
-				...grammar_clike.class_name,
+				...grammar_clike.class_name!,
 				{
 					pattern:
 						/(^|[^$\w\xA0-\uFFFF])(?!\s)[_$A-Z\xA0-\uFFFF](?:(?!\s)[$\w\xA0-\uFFFF])*(?=\.(?:constructor|prototype))/,
diff --git a/src/lib/grammar_json.ts b/src/lib/grammar_json.ts
index f338a3d7..d5883aaf 100644
--- a/src/lib/grammar_json.ts
+++ b/src/lib/grammar_json.ts
@@ -1,4 +1,4 @@
-import type {Add_Syntax_Grammar, Syntax_Grammar} from '$lib/syntax_styler.js';
+import type {Add_Syntax_Grammar, Syntax_Grammar_Raw} from '$lib/syntax_styler.js';
 
 /**
  * Based on Prism (https://github.com/PrismJS/prism)
@@ -32,7 +32,7 @@ export const add_grammar_json: Add_Syntax_Grammar = (syntax_styler) => {
 			pattern: /\bnull\b/,
 			alias: 'keyword',
 		},
-	} satisfies Syntax_Grammar;
+	} satisfies Syntax_Grammar_Raw;
 
 	syntax_styler.add_lang('json', grammar_json);
 };
diff --git a/src/lib/grammar_markdown.ts b/src/lib/grammar_markdown.ts
index 01fc8717..1422ae03 100644
--- a/src/lib/grammar_markdown.ts
+++ b/src/lib/grammar_markdown.ts
@@ -1,7 +1,7 @@
 import type {
 	Add_Syntax_Grammar,
-	Syntax_Grammar_Token,
-	Syntax_Grammar_Value,
+	Syntax_Grammar_Token_Raw,
+	Syntax_Grammar_Value_Raw,
 	Syntax_Styler,
 } from '$lib/syntax_styler.js';
 
@@ -23,7 +23,7 @@ const create_fence_pattern = (
 	aliases: Array<string>,
 	lang_id: string,
 	syntax_styler: Syntax_Styler,
-): Syntax_Grammar_Token => {
+): Syntax_Grammar_Token_Raw => {
 	const aliases_pattern = aliases.join('|');
 	const pattern = new RegExp(
 		`^${backticks}(?:${aliases_pattern})[^\\n\\r]*(?:\\r?\\n|\\r)[\\s\\S]*?^${backticks}$`,
@@ -50,7 +50,7 @@ const create_fence_pattern = (
 /**
  * Helper to create catch-all fence pattern (unknown languages)
  */
-const create_catchall_fence = (backticks: string): Syntax_Grammar_Token => {
+const create_catchall_fence = (backticks: string): Syntax_Grammar_Token_Raw => {
 	const pattern = new RegExp(`^${backticks}[^\\n\\r]*(?:\\r?\\n|\\r)[\\s\\S]*?^${backticks}$`, 'm');
 	const code_fence_pattern = new RegExp(`^${backticks}[^\\n\\r]*|^${backticks}$`, 'm');
 
@@ -69,7 +69,7 @@ const create_catchall_fence = (backticks: string): Syntax_Grammar_Token => {
 /**
  * Helper to create md self-reference placeholder pattern
  */
-const create_md_placeholder = (backticks: string): Syntax_Grammar_Token => {
+const create_md_placeholder = (backticks: string): Syntax_Grammar_Token_Raw => {
 	const pattern = new RegExp(
 		`^${backticks}(?:md|markdown)[^\\n\\r]*(?:\\r?\\n|\\r)[\\s\\S]*?^${backticks}$`,
 		'm',
@@ -113,7 +113,7 @@ export const add_grammar_markdown: Add_Syntax_Grammar = (syntax_styler) => {
 	];
 
 	// Build grammar dynamically
-	const grammar: Record<string, Syntax_Grammar_Value> = {};
+	const grammar: Record<string, Syntax_Grammar_Value_Raw> = {};
 	const md_self_refs: Array<string> = []; // Track md patterns for later self-reference
 
 	// Generate fence patterns for each type
@@ -273,17 +273,17 @@ export const add_grammar_markdown: Add_Syntax_Grammar = (syntax_styler) => {
 		inside: syntax_styler.get_lang('md'),
 	};
 	for (const key of md_self_refs) {
-		// After normalization, grammar values are arrays of Normalized_Grammar_Token
+		// After normalization, grammar values are arrays of Syntax_Grammar_Token
 		// We need to add lang_md as a normalized array
-		const patterns = grammar_md[key] as any;
+		const patterns = grammar_md[key]!;
 		// Manually normalize the lang_md pattern we're adding
-		const normalized_lang_md = {
+		const lang_md_token = {
 			pattern: lang_md_inside.pattern,
 			lookbehind: false,
 			greedy: false,
 			alias: [],
 			inside: lang_md_inside.inside,
 		};
-		patterns[0].inside.lang_md = [normalized_lang_md];
+		patterns[0]!.inside!.lang_md = [lang_md_token];
 	}
 };
diff --git a/src/lib/grammar_markup.ts b/src/lib/grammar_markup.ts
index c5a96c59..694bc6d6 100644
--- a/src/lib/grammar_markup.ts
+++ b/src/lib/grammar_markup.ts
@@ -1,8 +1,9 @@
 import type {
 	Syntax_Styler,
 	Add_Syntax_Grammar,
-	Syntax_Grammar,
+	Syntax_Grammar_Raw,
 	Syntax_Grammar_Token,
+	Syntax_Grammar,
 } from '$lib/syntax_styler.js';
 
 /**
@@ -84,7 +85,7 @@ export const add_grammar_markup: Add_Syntax_Grammar = (syntax_styler) => {
 			},
 			/&#x?[\da-f]{1,8};/i,
 		],
-	} satisfies Syntax_Grammar;
+	} satisfies Syntax_Grammar_Raw;
 
 	grammar_markup.tag.inside.attr_value.inside.entity = grammar_markup.entity;
 
@@ -157,12 +158,12 @@ export const grammar_markup_add_attribute = (
 	attr_name: string,
 	lang: string,
 ): void => {
-	// After normalization, grammar.tag is an array of Normalized_Grammar_Token
+	// After normalization, grammar.tag is an array of Syntax_Grammar_Token
 	const markup_grammar = syntax_styler.get_lang('markup');
-	const tag_patterns = markup_grammar.tag as any;
-	const tag_inside = tag_patterns[0].inside;
+	const tag_patterns = markup_grammar.tag;
+	const tag_inside = tag_patterns![0]!.inside!;
 
-	(tag_inside.special_attr as Array<Syntax_Grammar_Token>).push({
+	tag_inside.special_attr!.push({
 		pattern: RegExp(
 			/(^|["'\s])/.source +
 				'(?:' +
@@ -172,29 +173,53 @@ export const grammar_markup_add_attribute = (
 			'i',
 		),
 		lookbehind: true,
+		greedy: false,
+		alias: [],
 		inside: {
-			attr_name: /^[^\s=]+/,
-			attr_value: {
-				pattern: /=[\s\S]+/,
-				inside: {
-					value: {
-						pattern: /(^=\s*(["']|(?!["'])))\S[\s\S]*(?=\2$)/,
-						lookbehind: true,
-						alias: [lang, 'lang_' + lang], // TODO remove this alias?
-						inside: syntax_styler.get_lang(lang),
-					},
-					punctuation: [
-						{
-							pattern: /^=/,
-							alias: 'attr_equals',
-						},
-						{
-							pattern: /"|'/,
-							alias: 'attr_quote',
-						},
-					],
+			attr_name: [
+				{
+					pattern: /^[^\s=]+/,
+					lookbehind: false,
+					greedy: false,
+					alias: [],
+					inside: null,
 				},
-			},
-		},
-	});
+			],
+			attr_value: [
+				{
+					pattern: /=[\s\S]+/,
+					lookbehind: false,
+					greedy: false,
+					alias: [],
+					inside: {
+						value: [
+							{
+								pattern: /(^=\s*(["']|(?!["'])))\S[\s\S]*(?=\2$)/,
+								lookbehind: true,
+								greedy: false,
+								alias: [lang, 'lang_' + lang], // TODO remove this alias?
+								inside: syntax_styler.get_lang(lang),
+							},
+						],
+						punctuation: [
+							{
+								pattern: /^=/,
+								lookbehind: false,
+								greedy: false,
+								alias: ['attr_equals'],
+								inside: null,
+							},
+							{
+								pattern: /"|'/,
+								lookbehind: false,
+								greedy: false,
+								alias: ['attr_quote'],
+								inside: null,
+							},
+						],
+					} as Syntax_Grammar,
+				},
+			],
+		} as Syntax_Grammar,
+	} satisfies Syntax_Grammar_Token);
 };
diff --git a/src/lib/grammar_svelte.ts b/src/lib/grammar_svelte.ts
index 5d832f9f..875f3070 100644
--- a/src/lib/grammar_svelte.ts
+++ b/src/lib/grammar_svelte.ts
@@ -146,7 +146,7 @@ export const add_grammar_svelte: Add_Syntax_Grammar = (syntax_styler) => {
 	});
 
 	// oof lol
-	// After normalization, grammar.tag is an array of Normalized_Grammar_Token
+	// After normalization, grammar.tag is an array of Syntax_Grammar_Token
 	const tag_patterns = grammar_svelte.tag as any;
 	const tag_inside = tag_patterns[0].inside;
 	tag_inside.attr_value[0].inside.entity = grammar_svelte.entity;
diff --git a/src/lib/grammar_ts.ts b/src/lib/grammar_ts.ts
index d9a585cb..e9ded389 100644
--- a/src/lib/grammar_ts.ts
+++ b/src/lib/grammar_ts.ts
@@ -59,7 +59,7 @@ export const add_grammar_ts: Add_Syntax_Grammar = (syntax_styler) => {
 	(type_inside as any).class_name = undefined;
 
 	// After normalization, grammar_ts.class_name is an array
-	(grammar_ts.class_name as any)[0].inside = type_inside;
+	grammar_ts.class_name![0]!.inside = type_inside;
 
 	syntax_styler.grammar_insert_before('ts', 'function', {
 		type_assertion: {
diff --git a/src/lib/highlight_manager.ts b/src/lib/highlight_manager.ts
index 96ef1a50..bdc906c4 100644
--- a/src/lib/highlight_manager.ts
+++ b/src/lib/highlight_manager.ts
@@ -43,7 +43,15 @@ export class Highlight_Manager {
 		this.clear_element_ranges();
 
 		const ranges_by_type: Map<string, Array<Range>> = new Map();
-		this.#create_all_ranges(tokens, text_node, ranges_by_type, 0);
+		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`,
+			);
+		}
 
 		// Apply highlights
 		for (const [type, ranges] of ranges_by_type) {
@@ -103,6 +111,7 @@ export class Highlight_Manager {
 		ranges_by_type: Map<string, Array<Range>>,
 		offset: number,
 	): number {
+		const text_length = text_node.textContent?.length ?? 0;
 		let pos = offset;
 
 		for (const token of tokens) {
@@ -114,6 +123,13 @@ export class Highlight_Manager {
 			const length = token.length;
 			const end_pos = pos + length;
 
+			// Validate positions are within text node bounds before creating ranges
+			if (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);
@@ -132,10 +148,10 @@ export class Highlight_Manager {
 						ranges_by_type.set(alias, []);
 					}
 					// Create a new range for each alias (ranges can't be reused)
-					const aliasRange = new Range();
-					aliasRange.setStart(text_node, pos);
-					aliasRange.setEnd(text_node, end_pos);
-					ranges_by_type.get(alias)!.push(aliasRange);
+					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);
 				}
 			} catch (e) {
 				throw new Error(`Failed to create range for ${token.type}: ${e}`);
@@ -143,10 +159,22 @@ export class Highlight_Manager {
 
 			// Process nested tokens
 			if (Array.isArray(token.content)) {
-				this.#create_all_ranges(token.content, text_node, ranges_by_type, pos);
+				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})`,
+					);
+				}
+				pos = actual_end_pos;
+			} else {
+				pos = end_pos;
 			}
-
-			pos = end_pos;
 		}
 
 		return pos;
diff --git a/src/lib/highlight_priorities.gen.ts b/src/lib/highlight_priorities.gen.ts
index 3a4ad008..d752f9d9 100644
--- a/src/lib/highlight_priorities.gen.ts
+++ b/src/lib/highlight_priorities.gen.ts
@@ -26,7 +26,7 @@ export const gen: Gen = {
 			let match;
 
 			while ((match = highlight_regex.exec(block)) !== null) {
-				const token_name = match[1];
+				const token_name = match[1]!;
 				if (!tokens_in_block.includes(token_name)) {
 					tokens_in_block.push(token_name);
 				}
diff --git a/src/lib/samples/all.gen.ts b/src/lib/samples/all.gen.ts
index 634130fa..b75a1d7f 100644
--- a/src/lib/samples/all.gen.ts
+++ b/src/lib/samples/all.gen.ts
@@ -25,7 +25,7 @@ export const gen: Gen = ({origin_path}) => {
 		samples.push({
 			key: `${lang}_${variant}`,
 			name: `${lang}_${variant}`,
-			lang,
+			lang: lang!,
 			content: escape_string(content),
 		});
 	}
diff --git a/src/lib/syntax_styler.ts b/src/lib/syntax_styler.ts
index eb0a0b0e..cf2fc447 100644
--- a/src/lib/syntax_styler.ts
+++ b/src/lib/syntax_styler.ts
@@ -12,7 +12,7 @@ export type Add_Syntax_Grammar = (syntax_styler: Syntax_Styler) => void;
  * @see LICENSE
  */
 export class Syntax_Styler {
-	langs: Record<string, Normalized_Grammar | undefined> = {
+	langs: Record<string, Syntax_Grammar | undefined> = {
 		plaintext: {},
 	};
 
@@ -32,12 +32,12 @@ export class Syntax_Styler {
 	// }
 	// }
 
-	add_lang(id: string, grammar: Syntax_Grammar, aliases?: Array<string>): void {
+	add_lang(id: string, grammar: Syntax_Grammar_Raw, aliases?: Array<string>): void {
 		// Normalize grammar once at registration for optimal runtime performance
 		// Use a visited set to handle circular references
 		this.normalize_grammar(grammar, new Set());
-		// After normalization, grammar has the shape of Normalized_Grammar
-		const normalized = grammar as unknown as Normalized_Grammar;
+		// After normalization, grammar has the shape of Syntax_Grammar
+		const normalized = grammar as unknown as Syntax_Grammar;
 		this.langs[id] = normalized;
 		if (aliases !== undefined) {
 			for (var alias of aliases) {
@@ -49,9 +49,9 @@ export class Syntax_Styler {
 	add_extended_lang(
 		base_id: string,
 		extension_id: string,
-		extension: Syntax_Grammar,
+		extension: Syntax_Grammar_Raw,
 		aliases?: Array<string>,
-	): Normalized_Grammar {
+	): Syntax_Grammar {
 		// extend_grammar returns already normalized grammar
 		var grammar = this.extend_grammar(base_id, extension);
 		// Store the normalized grammar directly
@@ -64,7 +64,7 @@ export class Syntax_Styler {
 		return grammar;
 	}
 
-	get_lang(id: string): Normalized_Grammar {
+	get_lang(id: string): Syntax_Grammar {
 		var lang = this.langs[id];
 		if (lang === undefined) {
 			throw Error(`The language "${id}" has no grammar.`);
@@ -73,28 +73,49 @@ export class Syntax_Styler {
 	}
 
 	/**
-	 * Accepts a string of text as input
-	 * and the language definitions to use,
-	 * and returns a string with the HTML produced.
-	 *
-	 * The following hooks will be run:
-	 * 1. `before_tokenize`
-	 * 2. `after_tokenize`
-	 * 3. `wrap`: on each `Syntax_Token`
-	 *
-	 * @param text - A string with the code to be styled.
-	 * @param lang - The name of the language definition passed to `grammar`.
-	 * @param grammar - An object containing the tokens to use.
-	 *
-	 * Usually a language definition like `syntax_styler.get_lang('markup')`.
-	 *
-	 * @returns the styled HTML
+	 * Generates HTML with syntax highlighting from source code.
+	 *
+	 * **Process:**
+	 * 1. Runs `before_tokenize` hook
+	 * 2. Tokenizes code using the provided or looked-up grammar
+	 * 3. Runs `after_tokenize` hook
+	 * 4. Runs `wrap` hook on each token
+	 * 5. Converts tokens to HTML with CSS classes
+	 *
+	 * **Parameter Relationship:**
+	 * - `lang` is ALWAYS required for hook context and identification
+	 * - `grammar` is optional; when undefined, automatically looks up via `this.get_lang(lang)`
+	 * - When both are provided, `grammar` is used for tokenization, `lang` for metadata
+	 *
+	 * **Use cases:**
+	 * - Standard usage: `stylize(code, 'ts')` - uses registered TypeScript grammar
+	 * - 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.
+	 *
+	 * @returns HTML string with syntax highlighting using CSS classes (`.token_*`)
 	 *
 	 * @example
+	 * // Standard usage - uses registered grammar
 	 * stylize('var foo = true;', 'ts');
 	 *
 	 * @example
-	 * stylize('var foo = false;', 'ts', custom_grammar);
+	 * // Custom grammar - overrides registered grammar
+	 * const customGrammar = { keyword: [...], string: [...] };
+	 * stylize('var foo = false;', 'ts', customGrammar);
+	 *
+	 * @example
+	 * // Extended grammar - builds on existing grammar
+	 * const extended = this.extend_grammar('ts', { customToken: [...] });
+	 * stylize('var foo = 42;', 'ts-extended', extended);
 	 */
 	stylize(
 		text: string,
@@ -192,11 +213,11 @@ export class Syntax_Styler {
 	grammar_insert_before(
 		inside: string,
 		before: string,
-		insert: Syntax_Grammar,
+		insert: Syntax_Grammar_Raw,
 		root: Record<string, any> = this.langs,
-	): Normalized_Grammar {
+	): Syntax_Grammar {
 		var grammar = root[inside];
-		var updated: Syntax_Grammar = {};
+		var updated: Syntax_Grammar_Raw = {};
 
 		for (var token in grammar) {
 			if (token === before) {
@@ -214,8 +235,8 @@ export class Syntax_Styler {
 		// Normalize the updated grammar to ensure inserted patterns have consistent shape
 		this.normalize_grammar(updated, new Set());
 
-		// After normalization, cast to Normalized_Grammar
-		const normalized = updated as unknown as Normalized_Grammar;
+		// After normalization, cast to Syntax_Grammar
+		const normalized = updated as unknown as Syntax_Grammar;
 		var old = root[inside];
 		root[inside] = normalized;
 
@@ -309,13 +330,13 @@ export class Syntax_Styler {
 	 * @param extension - The new tokens to append.
 	 * @returns the new grammar
 	 */
-	extend_grammar(base_id: string, extension: Syntax_Grammar): Normalized_Grammar {
+	extend_grammar(base_id: string, extension: Syntax_Grammar_Raw): Syntax_Grammar {
 		// Merge normalized base with un-normalized extension
 		const extended = {...structuredClone(this.get_lang(base_id)), ...extension};
 		// Normalize the extension parts
-		this.normalize_grammar(extended as Syntax_Grammar, new Set());
-		// Return as Normalized_Grammar
-		return extended as unknown as Normalized_Grammar;
+		this.normalize_grammar(extended as Syntax_Grammar_Raw, new Set());
+		// Return as Syntax_Grammar
+		return extended as unknown as Syntax_Grammar;
 	}
 
 	/**
@@ -323,9 +344,9 @@ export class Syntax_Styler {
 	 * This ensures all patterns have the same object shape for V8 optimization.
 	 */
 	private normalize_pattern(
-		pattern: RegExp | Syntax_Grammar_Token,
+		pattern: RegExp | Syntax_Grammar_Token_Raw,
 		visited: Set<number>,
-	): Normalized_Grammar_Token {
+	): Syntax_Grammar_Token {
 		const p = pattern instanceof RegExp ? {pattern} : pattern;
 
 		let regex = p.pattern;
@@ -343,11 +364,11 @@ export class Syntax_Styler {
 		}
 
 		// Recursively normalize the inside grammar if present
-		let normalized_inside: Normalized_Grammar | null = null;
+		let normalized_inside: Syntax_Grammar | null = null;
 		if (p.inside) {
 			this.normalize_grammar(p.inside, visited);
-			// After normalization, cast to Normalized_Grammar
-			normalized_inside = p.inside as unknown as Normalized_Grammar;
+			// After normalization, cast to Syntax_Grammar
+			normalized_inside = p.inside as unknown as Syntax_Grammar;
 		}
 
 		return {
@@ -370,7 +391,7 @@ export class Syntax_Styler {
 	 * This is called once at registration time to avoid runtime overhead.
 	 * @param visited - Set of grammar object IDs already normalized (for circular references)
 	 */
-	private normalize_grammar(grammar: Syntax_Grammar, visited: Set<number>): void {
+	private normalize_grammar(grammar: Syntax_Grammar_Raw, visited: Set<number>): void {
 		// Check if we've already normalized this grammar (circular reference)
 		const grammar_id = id_of(grammar);
 		if (visited.has(grammar_id)) {
@@ -401,7 +422,7 @@ export class Syntax_Styler {
 
 			// Always store as array of normalized patterns
 			const patterns = Array.isArray(value) ? value : [value];
-			grammar[key] = patterns.map((p) => this.normalize_pattern(p, visited)) as any;
+			grammar[key] = patterns.map((p) => this.normalize_pattern(p, visited));
 		}
 	}
 
@@ -440,13 +461,13 @@ export class Syntax_Styler {
 	}
 }
 
-export type Syntax_Grammar_Value =
+export type Syntax_Grammar_Value_Raw =
 	| RegExp
-	| Syntax_Grammar_Token
-	| Array<RegExp | Syntax_Grammar_Token>;
+	| Syntax_Grammar_Token_Raw
+	| Array<RegExp | Syntax_Grammar_Token_Raw>;
 
-export type Syntax_Grammar = Record<string, Syntax_Grammar_Value | undefined> & {
-	rest?: Syntax_Grammar | undefined;
+export type Syntax_Grammar_Raw = Record<string, Syntax_Grammar_Value_Raw | undefined> & {
+	rest?: Syntax_Grammar_Raw | undefined;
 };
 
 /**
@@ -462,7 +483,7 @@ export type Syntax_Grammar = Record<string, Syntax_Grammar_Value | undefined> &
  * Note: Grammar authors can use optional properties, but they will be normalized
  * to required properties at registration time for optimal performance.
  */
-export interface Syntax_Grammar_Token {
+export interface Syntax_Grammar_Token_Raw {
 	/**
 	 * The regular expression of the token.
 	 */
@@ -485,26 +506,26 @@ export interface Syntax_Grammar_Token {
 	/**
 	 * The nested grammar of this token.
 	 */
-	inside?: Syntax_Grammar | null;
+	inside?: Syntax_Grammar_Raw | null;
 }
 
 /**
- * Normalized grammar token with all properties required.
- * This is the internal representation after normalization.
+ * Grammar token with all properties required.
+ * This is the normalized representation used at runtime.
  */
-export interface Normalized_Grammar_Token {
+export interface Syntax_Grammar_Token {
 	pattern: RegExp;
 	lookbehind: boolean;
 	greedy: boolean;
 	alias: Array<string>;
-	inside: Normalized_Grammar | null;
+	inside: Syntax_Grammar | null;
 }
 
 /**
  * A grammar after normalization.
  * All values are arrays of normalized tokens with consistent shapes.
  */
-export type Normalized_Grammar = Record<string, Array<Normalized_Grammar_Token>>;
+export type Syntax_Grammar = Record<string, Array<Syntax_Grammar_Token>>;
 
 const depth_first_search = (
 	o: any,
diff --git a/src/lib/tokenize_syntax.ts b/src/lib/tokenize_syntax.ts
index bcd93a55..31113017 100644
--- a/src/lib/tokenize_syntax.ts
+++ b/src/lib/tokenize_syntax.ts
@@ -43,7 +43,7 @@ interface Rematch_Options {
 const match_grammar = (
 	text: string,
 	token_list: Linked_List,
-	grammar: any,
+	grammar: Syntax_Grammar,
 	start_node: Linked_List_Node,
 	start_pos: number,
 	rematch?: Rematch_Options,
@@ -61,7 +61,7 @@ const match_grammar = (
 				return;
 			}
 
-			var pattern_obj = patterns[j];
+			var pattern_obj = patterns[j]!;
 			// All properties are guaranteed to be present after normalization
 			var inside = pattern_obj.inside;
 			var lookbehind = pattern_obj.lookbehind;
diff --git a/src/routes/+page.svelte b/src/routes/+page.svelte
index aa76fd21..81820478 100644
--- a/src/routes/+page.svelte
+++ b/src/routes/+page.svelte
@@ -13,11 +13,11 @@
 </script>
 
 <main class="box width_100">
-	<div class="box width_upto_md">
-		<section>
+	<div class="width_upto_md">
+		<section class="box">
 			<Package_Summary {pkg} />
 		</section>
-		<section>
+		<section class="box">
 			<aside class="width_upto_sm">
 				⚠️ Docs are a work in progress. This page has usage examples with the optional Svelte
 				component, and the <a href="https://github.com/ryanatkn/fuz_code">readme</a> has TypeScript usage
diff --git a/src/routes/Code_Tome.svelte b/src/routes/Code_Tome.svelte
index e5a0bb29..4915fc1e 100644
--- a/src/routes/Code_Tome.svelte
+++ b/src/routes/Code_Tome.svelte
@@ -1,4 +1,6 @@
 <script lang="ts">
+	import {resolve} from '$app/paths';
+
 	// import Tome from '@ryanatkn/fuz/Tome.svelte';
 	// import Docs_Item from '@ryanatkn/fuz/Docs_Item.svelte';
 	// import Tome_Link from '@ryanatkn/fuz/Tome_Link.svelte';
@@ -39,8 +41,9 @@ import '@ryanatkn/fuz_code/theme.css'; // add this"
 <section>
 	<h3>Dependencies</h3>
 	<p>
-		By default fuz_code depends on my CSS framework <a href="https://moss.ryanatkn.com">Moss</a>. If
-		you're not using it, import <code>theme_variables.css</code>:
+		By default fuz_code depends on my CSS framework <a href="https://moss.ryanatkn.com">Moss</a> to
+		provide color-schema-aware color variables. If you're not using it, import
+		<code>theme_variables.css</code> or bring your own:
 	</p>
 	<Code
 		lang="ts"
@@ -50,11 +53,19 @@ import '@ryanatkn/fuz_code/theme_variables.css'; // also this if not using Moss"
 	/>
 </section>
 <section>
-	<aside>
-		⚠️ Performing syntax styling at runtime like this is often wasteful. The plan is to provide a
-		Vite plugin to optimize static cases. For now you can use <code>lang={'{'}null}</code> with pre-highligted
+	<h3>Caveats</h3>
+	<p>
+		The <code>Code</code> component generates HTML with CSS classes for text highlighting. It also
+		includes experimental support for the CSS Custom Highlight API with <code>Code_Highlight</code>,
+		see the
+		<a href={resolve('/samples')}>samples</a>
+		for more.
+	</p>
+	<p>
+		Performing syntax styling at runtime like this is often wasteful. The plan is to provide a Vite
+		plugin to optimize static cases. For now you can use <code>lang={'{'}null}</code> with pre-highligted
 		HTML.
-	</aside>
+	</p>
 </section>
 <section>
 	<h3>Svelte support</h3>
@@ -98,13 +109,14 @@ import '@ryanatkn/fuz_code/theme_variables.css'; // also this if not using Moss"
 <section>
 	<h3>Markdown support</h3>
 	<p>
-		<Tome_Link name="Code" /> supports Markdown with <code>lang="md"</code>:
+		<Tome_Link name="Code" /> supports Markdown with <code>lang="md"</code>, and fenced blocks for
+		all languages:
 	</p>
 	<div class="mb_lg">
-		<Code content={`<Code lang="md" content="# hello **world**" />`} />
+		<Code content={`<Code lang="md" content="# hello \`world\` ..." />`} />
 	</div>
 	<div>
-		<Code lang="md" content={`# hello **world**`} />
+		<Code lang="md" content={`# hello \`world\`\n\n\`\`\`ts\n\tconst a = 1;\n\`\`\``} />
 	</div>
 </section>
 <section>
diff --git a/src/routes/benchmark/+page.svelte b/src/routes/benchmark/+page.svelte
index c8f0fd80..e26cf0a1 100644
--- a/src/routes/benchmark/+page.svelte
+++ b/src/routes/benchmark/+page.svelte
@@ -88,35 +88,39 @@
 	</p>
 
 	<section class="panel p_lg">
-		<h2 class="mt_0">config</h2>
-		<label>
-			iterations:
-			<input type="number" bind:value={config.iterations} min="10" disabled={running} />
-		</label>
-
-		<label>
-			content multiplier:
-			<input type="number" bind:value={config.content_multiplier} min="50" disabled={running} />
-		</label>
-
-		<label>
-			warmup runs:
-			<input type="number" bind:value={config.warmup_count} min="3" disabled={running} />
-		</label>
-
-		<label>
-			cooldown (ms):
-			<input type="number" bind:value={config.cooldown_ms} min="10" disabled={running} />
-		</label>
-
-		<button type="button" onclick={run_benchmarks} disabled={running}>
-			{running ? 'running...' : 'run benchmarks'}
-		</button>
-		{#if running}
-			<button type="button" onclick={stop_benchmarks} style:margin-left="1rem">
-				stop benchmark
+		<form>
+			<fieldset>
+				<legend>config</legend>
+				<label>
+					<div class="title">iterations</div>
+					<input type="number" bind:value={config.iterations} min="10" disabled={running} />
+				</label>
+
+				<label>
+					<div class="title">content multiplier</div>
+					<input type="number" bind:value={config.content_multiplier} min="50" disabled={running} />
+				</label>
+
+				<label>
+					<div class="title">warmup runs</div>
+					<input type="number" bind:value={config.warmup_count} min="3" disabled={running} />
+				</label>
+
+				<label>
+					<div class="title">cooldown (ms)</div>
+					<input type="number" bind:value={config.cooldown_ms} min="10" disabled={running} />
+				</label>
+			</fieldset>
+
+			<button type="button" onclick={run_benchmarks} disabled={running}>
+				{running ? 'running...' : 'run benchmarks'}
 			</button>
-		{/if}
+			{#if running}
+				<button type="button" class="mt_lg" onclick={stop_benchmarks} style:margin-left="1rem">
+					stop benchmark
+				</button>
+			{/if}
+		</form>
 	</section>
 
 	{#if running}
diff --git a/src/routes/benchmark/benchmark_stats.ts b/src/routes/benchmark/benchmark_stats.ts
index c2509c00..78a783f7 100644
--- a/src/routes/benchmark/benchmark_stats.ts
+++ b/src/routes/benchmark/benchmark_stats.ts
@@ -27,8 +27,8 @@ const MIN_SAMPLE_SIZE = 3;
 const calculate_median = (sorted_array: Array<number>): number => {
 	const mid = Math.floor(sorted_array.length / 2);
 	return sorted_array.length % 2 === 0
-		? (sorted_array[mid - 1] + sorted_array[mid]) / 2
-		: sorted_array[mid];
+		? (sorted_array[mid - 1]! + sorted_array[mid]!) / 2
+		: sorted_array[mid]!;
 };
 
 // Outlier detection using MAD (Median Absolute Deviation) method
@@ -51,8 +51,8 @@ export const detect_outliers = (
 	const mad = calculate_median(sorted_deviations);
 
 	if (mad === 0) {
-		const q1 = sorted[Math.floor(sorted.length * QUARTILE_Q1)];
-		const q3 = sorted[Math.floor(sorted.length * QUARTILE_Q3)];
+		const q1 = sorted[Math.floor(sorted.length * QUARTILE_Q1)]!;
+		const q3 = sorted[Math.floor(sorted.length * QUARTILE_Q3)]!;
 		const iqr = q3 - q1;
 
 		if (iqr === 0) {
@@ -117,9 +117,9 @@ export const detect_outliers = (
 
 			for (let i = 0; i < with_distances.length; i++) {
 				if (i < keep_count) {
-					cleaned_times.push(with_distances[i].time);
+					cleaned_times.push(with_distances[i]!.time);
 				} else {
-					outliers.push(with_distances[i].time);
+					outliers.push(with_distances[i]!.time);
 				}
 			}
 		}
@@ -175,10 +175,10 @@ export const analyze_results = (data: Measurement_Data): Benchmark_Stats => {
 		cleaned_times.reduce((sum, val) => sum + (val - mean) ** 2, 0) / cleaned_times.length;
 	const std_dev = Math.sqrt(variance);
 
-	const min = final_sorted[0];
-	const max = final_sorted[final_sorted.length - 1];
-	const p95 = final_sorted[Math.floor(final_sorted.length * PERCENTILE_95)];
-	const p99 = final_sorted[Math.floor(final_sorted.length * PERCENTILE_99)];
+	const min = final_sorted[0]!;
+	const max = final_sorted[final_sorted.length - 1]!;
+	const p95 = final_sorted[Math.floor(final_sorted.length * PERCENTILE_95)]!;
+	const p99 = final_sorted[Math.floor(final_sorted.length * PERCENTILE_99)]!;
 
 	const cv = std_dev / mean;
 
@@ -226,7 +226,7 @@ export const calculate_summary = (
 		if (!(by_impl as Record<string, Array<Benchmark_Result> | undefined>)[result.implementation]) {
 			by_impl[result.implementation] = [];
 		}
-		by_impl[result.implementation].push(result);
+		by_impl[result.implementation]!.push(result);
 	}
 
 	const summary: Record<string, Summary_Stats> = {};
@@ -248,10 +248,10 @@ export const calculate_summary = (
 	}
 
 	// Calculate relative performance (only if baseline exists)
-	const baseline_mean = summary.html.avg_mean;
+	const baseline_mean = summary.html!.avg_mean;
 	for (const impl of Object.keys(summary)) {
-		summary[impl].relative_speed = baseline_mean / summary[impl].avg_mean;
-		summary[impl].improvement = (summary[impl].relative_speed - 1) * 100;
+		summary[impl]!.relative_speed = baseline_mean / summary[impl]!.avg_mean;
+		summary[impl]!.improvement = (summary[impl]!.relative_speed - 1) * 100;
 	}
 
 	return summary;
diff --git a/src/routes/moss.css b/src/routes/moss.css
index d878c00a..8b217098 100644
--- a/src/routes/moss.css
+++ b/src/routes/moss.css
@@ -122,9 +122,6 @@ a.chip {
 .width_100 {
 	width: 100%;
 }
-.width_md {
-	width: var(--space_md);
-}
 .height_100 {
 	height: 100%;
 }
@@ -155,6 +152,9 @@ a.chip {
 .mt_md {
 	margin-top: var(--space_md);
 }
+.mt_lg {
+	margin-top: var(--space_lg);
+}
 .mt_xl5 {
 	margin-top: var(--space_xl5);
 }
diff --git a/src/routes/package.ts b/src/routes/package.ts
index ebbda018..62c0cd96 100644
--- a/src/routes/package.ts
+++ b/src/routes/package.ts
@@ -6,7 +6,7 @@ import type {Src_Json} from '@ryanatkn/belt/src_json.js';
 export const package_json: Package_Json = {
 	name: '@ryanatkn/fuz_code',
 	version: '0.28.0',
-	description: 'syntax styling utilities and components for TypeScript, Svelte, SvelteKit',
+	description: 'syntax styling utilities and components for TypeScript, Svelte, and Markdown',
 	glyph: '🎨',
 	logo: 'logo.svg',
 	logo_alt: 'a friendly pink spider facing you',
@@ -169,11 +169,11 @@ export const src_json: Src_Json = {
 			declarations: [
 				{name: 'Add_Syntax_Grammar', kind: 'type'},
 				{name: 'Syntax_Styler', kind: 'class'},
-				{name: 'Syntax_Grammar_Value', kind: 'type'},
-				{name: 'Syntax_Grammar', kind: 'type'},
+				{name: 'Syntax_Grammar_Value_Raw', kind: 'type'},
+				{name: 'Syntax_Grammar_Raw', kind: 'type'},
+				{name: 'Syntax_Grammar_Token_Raw', kind: 'type'},
 				{name: 'Syntax_Grammar_Token', kind: 'type'},
-				{name: 'Normalized_Grammar_Token', kind: 'type'},
-				{name: 'Normalized_Grammar', kind: 'type'},
+				{name: 'Syntax_Grammar', kind: 'type'},
 				{name: 'Hook_Before_Tokenize_Callback', kind: 'type'},
 				{name: 'Hook_After_Tokenize_Callback', kind: 'type'},
 				{name: 'Hook_Wrap_Callback', kind: 'type'},
diff --git a/src/routes/samples/+page.svelte b/src/routes/samples/+page.svelte
index 7a22ee06..b57abac2 100644
--- a/src/routes/samples/+page.svelte
+++ b/src/routes/samples/+page.svelte
@@ -1,4 +1,6 @@
 <script lang="ts">
+	import '$lib/theme_highlight.css';
+
 	import Breadcrumb from '@ryanatkn/fuz/Breadcrumb.svelte';
 
 	import Code from '$lib/Code.svelte';
@@ -9,10 +11,19 @@
 
 <main class="box width_100 py_xl5">
 	<Breadcrumb>🎨</Breadcrumb>
-	<h1 class="text_align_center">Syntax Highlighting Samples</h1>
 
 	<section class="box mb_xl5">
-		<h2 class="text_align_center">Standard (HTML Mode)</h2>
+		<h2 class="text_align_center">HTML rendering (default)</h2>
+		<aside
+			class="panel p_md mb_xl3 width_upto_md
+		"
+		>
+			<p>
+				These samples use the normal <code>Code</code> component, which renders using HTML. See
+				<a href="#experimental">below</a> for the experimental <code>Code_Highlight</code> that uses
+				the Highlight API.
+			</p>
+		</aside>
 		{#each Object.values(samples) as sample (sample.name)}
 			<div class="mb_xl3">
 				<h3 class="box panel p_md mb_xs">{sample.lang}</h3>
@@ -23,28 +34,47 @@
 
 	<hr class="my_xl5" />
 
-	<section class="box">
-		<h2 class="text_align_center">Experimental: CSS Custom Highlight API</h2>
-		<aside class="box panel p_md mb_xl3 width_md">
-			⚠️ <strong>Experimental:</strong> The comparison below shows both HTML mode and CSS Custom
-			Highlight API mode. The Highlight API has limited browser support and is not recommended for
-			production use. The standard <code>Code.svelte</code> component (shown above) uses HTML generation
-			and is recommended for all use cases.
+	<section class="box" id="experimental">
+		<h2 class="text_align_center">CSS Custom Highlight API (experimental)</h2>
+		<aside
+			class="panel p_md mb_xl3 width_upto_md
+		"
+		>
+			<p>
+				⚠️ <strong>Experimental:</strong> the comparison below uses
+				<code>Code_Highlight.svelte</code> instead of <code>Code.svelte</code>
+				with both HTML mode and
+				<a href="https://developer.mozilla.org/en-US/docs/Web/API/CSS_Custom_Highlight_API"
+					>CSS Custom Highlight API</a
+				>.
+			</p>
+			<p>
+				A limitation: layout-affecting styles like font weight do not work, even for monospaced
+				fonts:
+				<a href="https://github.com/w3c/csswg-drafts/issues/8355"
+					>github.com/w3c/csswg-drafts/issues/8355</a
+				>
+			</p>
+			<p>
+				The Highlight API has limited browser support as of October 2025 and is not recommended for
+				production use yet. Note <code>theme_highlight.css</code> is required instead of
+				<code>theme.css</code>.
+			</p>
 		</aside>
 		{#each Object.values(samples) as sample (sample.name)}
-			<div class="mb_xl3">
-				<h3 class="box panel p_md mb_0">{sample.lang}</h3>
+			<section>
+				<h2 class="box panel p_md mb_0">{sample.lang}</h2>
 				<div class="display_flex justify_content_center flex_wrap_wrap gap_sm py_xl5">
 					<div>
-						<h4>{sample.lang} HTML mode</h4>
+						<h3>{sample.lang} html strings</h3>
 						<Code_Highlight content={sample.content} lang={sample.lang} mode="html" />
 					</div>
 					<div>
-						<h4>{sample.lang} ranges mode</h4>
+						<h3>{sample.lang} highlighted ranges</h3>
 						<Code_Highlight content={sample.content} lang={sample.lang} mode="ranges" />
 					</div>
 				</div>
-			</div>
+			</section>
 			<hr />
 		{/each}
 	</section>
diff --git a/src/test/highlight_manager.test.ts b/src/test/highlight_manager.test.ts
new file mode 100644
index 00000000..854c8016
--- /dev/null
+++ b/src/test/highlight_manager.test.ts
@@ -0,0 +1,712 @@
+import {test, assert, describe, beforeEach, afterEach} from 'vitest';
+import {Highlight_Manager, supports_css_highlight_api} from '$lib/highlight_manager.js';
+import {Syntax_Token, type Syntax_Token_Stream} from '$lib/syntax_token.js';
+import {
+	setup_mock_highlight_api,
+	restore_globals,
+	create_code_element,
+	create_code_element_with_comment,
+	type Saved_Globals,
+} from './highlight_test_helpers.js';
+
+/**
+ * Test suite for Highlight_Manager
+ *
+ * Tests organized by domain:
+ * - Initialization and API detection
+ * - DOM element handling
+ * - Range creation and positioning
+ * - Lifecycle management (clear/destroy)
+ * - Edge cases and error conditions
+ */
+
+let saved_globals: Saved_Globals;
+
+beforeEach(() => {
+	saved_globals = setup_mock_highlight_api();
+});
+
+afterEach(() => {
+	restore_globals(saved_globals);
+});
+
+describe('API detection', () => {
+	test('supports_css_highlight_api returns true when API is available', () => {
+		assert.ok(supports_css_highlight_api());
+	});
+
+	test('supports_css_highlight_api returns false when CSS is undefined', () => {
+		const saved_css = (globalThis as any).CSS;
+		delete (globalThis as any).CSS;
+
+		assert.equal(supports_css_highlight_api(), false);
+
+		(globalThis as any).CSS = saved_css;
+	});
+
+	test('supports_css_highlight_api returns false when CSS.highlights is undefined', () => {
+		const saved_highlights = (globalThis as any).CSS.highlights;
+		delete (globalThis as any).CSS.highlights;
+
+		assert.equal(supports_css_highlight_api(), false);
+
+		(globalThis as any).CSS.highlights = saved_highlights;
+	});
+
+	test('supports_css_highlight_api returns false when Highlight constructor is undefined', () => {
+		const saved_highlight = (globalThis as any).Highlight;
+		delete (globalThis as any).Highlight;
+
+		assert.equal(supports_css_highlight_api(), false);
+
+		(globalThis as any).Highlight = saved_highlight;
+	});
+});
+
+describe('initialization', () => {
+	test('constructor throws if CSS Highlight API is not supported', () => {
+		const saved_css = (globalThis as any).CSS;
+		delete (globalThis as any).CSS;
+
+		assert.throws(() => new Highlight_Manager(), /CSS Highlights API not supported/);
+
+		(globalThis as any).CSS = saved_css;
+	});
+
+	test('constructor initializes with empty element_ranges map', () => {
+		const manager = new Highlight_Manager();
+		assert.equal(manager.element_ranges.size, 0);
+	});
+});
+
+describe('DOM element handling', () => {
+	test('throws if element has no text node', () => {
+		const manager = new Highlight_Manager();
+		const element = {
+			childNodes: [], // No children
+		} as unknown as Element;
+		const tokens: Syntax_Token_Stream = [];
+
+		assert.throws(
+			() => manager.highlight_from_syntax_tokens(element, tokens),
+			/no text node to highlight/,
+		);
+	});
+
+	test('finds text node as first child', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('const x = 1;');
+
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token('keyword', 'const', undefined, 'const'),
+			' x = 1;',
+		];
+
+		// Should not throw
+		assert.doesNotThrow(() => manager.highlight_from_syntax_tokens(element, tokens));
+	});
+
+	test('finds text node after comment nodes', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element_with_comment('const x = 1;');
+
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token('keyword', 'const', undefined, 'const'),
+			' x = 1;',
+		];
+
+		// Should not throw
+		assert.doesNotThrow(() => manager.highlight_from_syntax_tokens(element, tokens));
+	});
+
+	test('handles empty text node', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('');
+
+		const tokens: Syntax_Token_Stream = [];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+		assert.equal(manager.element_ranges.size, 0);
+	});
+});
+
+describe('range creation', () => {
+	test('creates ranges for simple token stream', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('const x = 1;');
+
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token('keyword', 'const', undefined, 'const'),
+			' ',
+			new Syntax_Token('variable', 'x', undefined, 'x'),
+			' = ',
+			new Syntax_Token('number', '1', undefined, '1'),
+			';',
+		];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		// Should have created ranges for keyword, variable, number
+		assert.equal(manager.element_ranges.size, 3);
+		assert.ok(manager.element_ranges.has('token_keyword'));
+		assert.ok(manager.element_ranges.has('token_variable'));
+		assert.ok(manager.element_ranges.has('token_number'));
+	});
+
+	test('creates ranges for token with string content', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('keyword');
+
+		// Token where content is a string (not nested array)
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token('keyword', 'keyword', undefined, 'keyword'),
+		];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		assert.ok(manager.element_ranges.has('token_keyword'));
+		const ranges = manager.element_ranges.get('token_keyword')!;
+		assert.equal(ranges.length, 1);
+		assert.equal(ranges[0]!.startOffset, 0);
+		assert.equal(ranges[0]!.endOffset, 7);
+	});
+
+	test('creates ranges for nested tokens', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('`hello ${name}`');
+
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token(
+				'template_string',
+				[
+					new Syntax_Token('punctuation', '`', undefined, '`'),
+					'hello ',
+					new Syntax_Token(
+						'interpolation',
+						[
+							new Syntax_Token('punctuation', '${', undefined, '${'),
+							new Syntax_Token('variable', 'name', undefined, 'name'),
+							new Syntax_Token('punctuation', '}', undefined, '}'),
+						],
+						undefined,
+						'${name}',
+					),
+					new Syntax_Token('punctuation', '`', undefined, '`'),
+				],
+				undefined,
+				'`hello ${name}`',
+			),
+		];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		// Should have ranges for all token types
+		assert.ok(manager.element_ranges.has('token_template_string'));
+		assert.ok(manager.element_ranges.has('token_punctuation'));
+		assert.ok(manager.element_ranges.has('token_interpolation'));
+		assert.ok(manager.element_ranges.has('token_variable'));
+	});
+
+	test('creates ranges for deeply nested tokens (4 levels)', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('abcd');
+
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token(
+				'level1',
+				[
+					new Syntax_Token(
+						'level2',
+						[
+							new Syntax_Token(
+								'level3',
+								[new Syntax_Token('level4', 'a', undefined, 'a'), 'bcd'],
+								undefined,
+								'abcd',
+							),
+						],
+						undefined,
+						'abcd',
+					),
+				],
+				undefined,
+				'abcd',
+			),
+		];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		// All levels should have ranges
+		assert.ok(manager.element_ranges.has('token_level1'));
+		assert.ok(manager.element_ranges.has('token_level2'));
+		assert.ok(manager.element_ranges.has('token_level3'));
+		assert.ok(manager.element_ranges.has('token_level4'));
+
+		// Verify positions
+		const level4_ranges = manager.element_ranges.get('token_level4')!;
+		assert.equal(level4_ranges[0]!.startOffset, 0);
+		assert.equal(level4_ranges[0]!.endOffset, 1);
+	});
+
+	test('creates ranges for mixed nested content (strings and tokens)', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('a-b-c');
+
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token(
+				'outer',
+				[
+					new Syntax_Token('part1', 'a', undefined, 'a'),
+					'-',
+					new Syntax_Token('part2', 'b', undefined, 'b'),
+					'-',
+					new Syntax_Token('part3', 'c', undefined, 'c'),
+				],
+				undefined,
+				'a-b-c',
+			),
+		];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		// All parts should have ranges with correct positions
+		const part1_ranges = manager.element_ranges.get('token_part1')!;
+		const part2_ranges = manager.element_ranges.get('token_part2')!;
+		const part3_ranges = manager.element_ranges.get('token_part3')!;
+
+		assert.equal(part1_ranges[0]!.startOffset, 0);
+		assert.equal(part1_ranges[0]!.endOffset, 1);
+		assert.equal(part2_ranges[0]!.startOffset, 2);
+		assert.equal(part2_ranges[0]!.endOffset, 3);
+		assert.equal(part3_ranges[0]!.startOffset, 4);
+		assert.equal(part3_ranges[0]!.endOffset, 5);
+	});
+
+	test('creates separate ranges for aliases', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('function');
+
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token('keyword', 'function', ['reserved', 'special_keyword'], 'function'),
+		];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		// Should have ranges for type + all aliases
+		assert.ok(manager.element_ranges.has('token_keyword'));
+		assert.ok(manager.element_ranges.has('token_reserved'));
+		assert.ok(manager.element_ranges.has('token_special_keyword'));
+
+		// Each should have one range
+		assert.equal(manager.element_ranges.get('token_keyword')!.length, 1);
+		assert.equal(manager.element_ranges.get('token_reserved')!.length, 1);
+		assert.equal(manager.element_ranges.get('token_special_keyword')!.length, 1);
+	});
+
+	test('handles token stream with only strings', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('plain text');
+
+		const tokens: Syntax_Token_Stream = ['plain text'];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		// No token ranges should be created
+		assert.equal(manager.element_ranges.size, 0);
+	});
+
+	test('adds ranges to global CSS.highlights registry', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('const');
+
+		const tokens: Syntax_Token_Stream = [new Syntax_Token('keyword', 'const', undefined, 'const')];
+
+		assert.equal(CSS.highlights.size, 0);
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		assert.ok(CSS.highlights.has('token_keyword'));
+		const highlight = CSS.highlights.get('token_keyword')!;
+		assert.equal(highlight.size, 1);
+	});
+
+	test('prefixes token types with "token_"', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('test');
+
+		const tokens: Syntax_Token_Stream = [new Syntax_Token('mytype', 'test', undefined, 'test')];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		// Should create 'token_mytype', not 'mytype'
+		assert.equal(CSS.highlights.has('mytype'), false);
+		assert.ok(CSS.highlights.has('token_mytype'));
+	});
+
+	test('sets highlight priority from highlight_priorities', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('const');
+
+		const tokens: Syntax_Token_Stream = [new Syntax_Token('keyword', 'const', undefined, 'const')];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		const highlight = CSS.highlights.get('token_keyword')!;
+		// keyword should have priority 2 according to highlight_priorities
+		assert.equal(highlight.priority, 2);
+	});
+});
+
+describe('position tracking', () => {
+	test('correctly tracks positions through simple tokens', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('a b c');
+
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token('a', 'a', undefined, 'a'), // pos 0-1
+			' ', // pos 1-2
+			new Syntax_Token('b', 'b', undefined, 'b'), // pos 2-3
+			' ', // pos 3-4
+			new Syntax_Token('c', 'c', undefined, 'c'), // pos 4-5
+		];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		// Get the created ranges
+		const ranges_a = manager.element_ranges.get('token_a')!;
+		const ranges_b = manager.element_ranges.get('token_b')!;
+		const ranges_c = manager.element_ranges.get('token_c')!;
+
+		assert.equal(ranges_a[0]!.startOffset, 0);
+		assert.equal(ranges_a[0]!.endOffset, 1);
+		assert.equal(ranges_b[0]!.startOffset, 2);
+		assert.equal(ranges_b[0]!.endOffset, 3);
+		assert.equal(ranges_c[0]!.startOffset, 4);
+		assert.equal(ranges_c[0]!.endOffset, 5);
+	});
+
+	test('correctly tracks positions through nested tokens', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('abc');
+
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token(
+				'outer',
+				[
+					new Syntax_Token('inner1', 'a', undefined, 'a'), // pos 0-1
+					new Syntax_Token('inner2', 'bc', undefined, 'bc'), // pos 1-3
+				],
+				undefined,
+				'abc',
+			),
+		];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		const outer_ranges = manager.element_ranges.get('token_outer')!;
+		const inner1_ranges = manager.element_ranges.get('token_inner1')!;
+		const inner2_ranges = manager.element_ranges.get('token_inner2')!;
+
+		assert.equal(outer_ranges[0]!.startOffset, 0);
+		assert.equal(outer_ranges[0]!.endOffset, 3);
+		assert.equal(inner1_ranges[0]!.startOffset, 0);
+		assert.equal(inner1_ranges[0]!.endOffset, 1);
+		assert.equal(inner2_ranges[0]!.startOffset, 1);
+		assert.equal(inner2_ranges[0]!.endOffset, 3);
+	});
+
+	test('handles token at position 0 (start boundary)', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('abc');
+
+		const tokens: Syntax_Token_Stream = [new Syntax_Token('start', 'a', undefined, 'a'), 'bc'];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		const ranges = manager.element_ranges.get('token_start')!;
+		assert.equal(ranges[0]!.startOffset, 0);
+		assert.equal(ranges[0]!.endOffset, 1);
+	});
+
+	test('handles token at end of text (end boundary)', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('abc');
+
+		const tokens: Syntax_Token_Stream = ['ab', new Syntax_Token('end', 'c', undefined, 'c')];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		const ranges = manager.element_ranges.get('token_end')!;
+		assert.equal(ranges[0]!.startOffset, 2);
+		assert.equal(ranges[0]!.endOffset, 3);
+	});
+
+	test('validates nested content length matches parent token', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('abc');
+
+		// Token with mismatched lengths: outer claims 3 chars but nested content only has 2
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token(
+				'outer',
+				[
+					new Syntax_Token('inner1', 'a', undefined, 'a'), // 1 char
+					new Syntax_Token('inner2', 'b', undefined, 'b'), // 1 char
+					// Nested tokens total: 2 chars
+				],
+				undefined,
+				'abc', // Claims 3 chars
+			),
+			// 'c' is unaccounted for
+		];
+
+		// Now validates that nested tokens match parent token's claimed length
+		assert.throws(
+			() => manager.highlight_from_syntax_tokens(element, tokens),
+			/Token outer length mismatch: claimed 3 chars.*but nested content covered 2 chars/,
+		);
+	});
+});
+
+describe('error handling', () => {
+	test('validates token position does not exceed text node length', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('abc'); // 3 characters
+
+		// Token claims to be longer than the text
+		const bad_token = new Syntax_Token('bad', 'abcd', undefined, 'abcd'); // 4 chars
+		const tokens: Syntax_Token_Stream = [bad_token];
+
+		// Validates bounds before creating range
+		assert.throws(
+			() => manager.highlight_from_syntax_tokens(element, tokens),
+			/Token bad extends beyond text node: position 4 > length 3/,
+		);
+	});
+
+	test('validates token stream matches text content length', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('abc'); // 3 characters
+
+		// Tokens only cover 2 characters
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token('keyword', 'ab', undefined, 'ab'),
+			// Missing 'c'
+		];
+
+		// Validates that sum of token lengths equals text node length
+		assert.throws(
+			() => manager.highlight_from_syntax_tokens(element, tokens),
+			/Token stream length mismatch: tokens covered 2 chars but text node has 3 chars/,
+		);
+	});
+
+	test('handles emoji and multi-byte characters', () => {
+		const manager = new Highlight_Manager();
+		const emoji = '🎨';
+		const element = create_code_element(`${emoji} = 1;`);
+
+		// JavaScript string length vs DOM position
+		assert.equal(emoji.length, 2); // UTF-16 code units
+
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token('variable', emoji, undefined, emoji),
+			' = ',
+			new Syntax_Token('number', '1', undefined, '1'),
+			';',
+		];
+
+		// Should handle emoji correctly
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		assert.ok(manager.element_ranges.has('token_variable'));
+		assert.ok(manager.element_ranges.has('token_number'));
+
+		// Verify positions are correct
+		const variable_ranges = manager.element_ranges.get('token_variable')!;
+		const number_ranges = manager.element_ranges.get('token_number')!;
+
+		// Emoji takes 2 code units, so number starts at position 5 (2 + 3)
+		assert.equal(variable_ranges[0]!.startOffset, 0);
+		assert.equal(variable_ranges[0]!.endOffset, 2);
+		assert.equal(number_ranges[0]!.startOffset, 5);
+		assert.equal(number_ranges[0]!.endOffset, 6);
+	});
+
+	test('wraps range creation errors with context', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('x');
+
+		// Create token with invalid position
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token('bad', 'xy', undefined, 'xy'), // Extends beyond text
+		];
+
+		try {
+			manager.highlight_from_syntax_tokens(element, tokens);
+			assert.fail('Should have thrown');
+		} catch (e: any) {
+			// Now throws earlier with bounds check before range creation
+			assert.ok(e.message.includes('bad')); // Includes token type
+			assert.ok(e.message.includes('extends beyond text node'));
+		}
+	});
+});
+
+describe('lifecycle management', () => {
+	test('clear_element_ranges removes ranges from CSS.highlights', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('const x;');
+
+		const tokens: Syntax_Token_Stream = [
+			new Syntax_Token('keyword', 'const', undefined, 'const'),
+			' x;',
+		];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+		assert.ok(CSS.highlights.has('token_keyword'));
+
+		manager.clear_element_ranges();
+		assert.equal(CSS.highlights.has('token_keyword'), false);
+	});
+
+	test('clear_element_ranges only removes own ranges from shared highlights', () => {
+		const manager1 = new Highlight_Manager();
+		const manager2 = new Highlight_Manager();
+
+		const element1 = create_code_element('const');
+		const element2 = create_code_element('const');
+
+		const tokens: Syntax_Token_Stream = [new Syntax_Token('keyword', 'const', undefined, 'const')];
+
+		manager1.highlight_from_syntax_tokens(element1, tokens);
+		manager2.highlight_from_syntax_tokens(element2, tokens);
+
+		const highlight = CSS.highlights.get('token_keyword')!;
+		assert.equal(highlight.size, 2); // Two ranges from two managers
+
+		manager1.clear_element_ranges();
+		assert.equal(highlight.size, 1); // Only manager1's range removed
+		assert.ok(CSS.highlights.has('token_keyword')); // Highlight still exists
+	});
+
+	test('clear_element_ranges throws if highlight unexpectedly missing', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('const');
+
+		const tokens: Syntax_Token_Stream = [new Syntax_Token('keyword', 'const', undefined, 'const')];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+
+		// Manually delete the highlight to simulate unexpected state
+		CSS.highlights.delete('token_keyword');
+
+		assert.throws(
+			() => manager.clear_element_ranges(),
+			/Expected to find CSS highlight: token_keyword/,
+		);
+	});
+
+	test('clear_element_ranges deletes highlight when last range removed', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('const');
+
+		const tokens: Syntax_Token_Stream = [new Syntax_Token('keyword', 'const', undefined, 'const')];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+		assert.ok(CSS.highlights.has('token_keyword'));
+
+		manager.clear_element_ranges();
+		assert.equal(CSS.highlights.has('token_keyword'), false);
+		assert.equal(CSS.highlights.size, 0);
+	});
+
+	test('clear_element_ranges can be called multiple times safely', () => {
+		const manager = new Highlight_Manager();
+
+		manager.clear_element_ranges();
+		manager.clear_element_ranges();
+
+		assert.equal(manager.element_ranges.size, 0);
+	});
+
+	test('destroy calls clear_element_ranges', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('const');
+
+		const tokens: Syntax_Token_Stream = [new Syntax_Token('keyword', 'const', undefined, 'const')];
+
+		manager.highlight_from_syntax_tokens(element, tokens);
+		assert.equal(manager.element_ranges.size, 1);
+
+		manager.destroy();
+		assert.equal(manager.element_ranges.size, 0);
+		assert.equal(CSS.highlights.size, 0);
+	});
+
+	test('highlight_from_syntax_tokens clears previous highlights', () => {
+		const manager = new Highlight_Manager();
+		const element = create_code_element('const');
+
+		const tokens1: Syntax_Token_Stream = [new Syntax_Token('keyword', 'const', undefined, 'const')];
+		const tokens2: Syntax_Token_Stream = [
+			new Syntax_Token('variable', 'const', undefined, 'const'),
+		];
+
+		manager.highlight_from_syntax_tokens(element, tokens1);
+		assert.ok(manager.element_ranges.has('token_keyword'));
+		assert.equal(manager.element_ranges.size, 1);
+
+		// Re-highlight with different tokens
+		manager.highlight_from_syntax_tokens(element, tokens2);
+		assert.equal(manager.element_ranges.has('token_keyword'), false);
+		assert.ok(manager.element_ranges.has('token_variable'));
+		assert.equal(manager.element_ranges.size, 1);
+	});
+});
+
+describe('multiple managers', () => {
+	test('multiple managers share global CSS.highlights registry', () => {
+		const manager1 = new Highlight_Manager();
+		const manager2 = new Highlight_Manager();
+
+		const element1 = create_code_element('const');
+		const element2 = create_code_element('let');
+
+		manager1.highlight_from_syntax_tokens(element1, [
+			new Syntax_Token('keyword', 'const', undefined, 'const'),
+		]);
+		manager2.highlight_from_syntax_tokens(element2, [
+			new Syntax_Token('keyword', 'let', undefined, 'let'),
+		]);
+
+		// Both contribute to same global highlight
+		const highlight = CSS.highlights.get('token_keyword')!;
+		assert.equal(highlight.size, 2);
+	});
+
+	test('managers maintain independent element_ranges', () => {
+		const manager1 = new Highlight_Manager();
+		const manager2 = new Highlight_Manager();
+
+		const element1 = create_code_element('const');
+		const element2 = create_code_element('let');
+
+		manager1.highlight_from_syntax_tokens(element1, [
+			new Syntax_Token('keyword', 'const', undefined, 'const'),
+		]);
+		manager2.highlight_from_syntax_tokens(element2, [
+			new Syntax_Token('keyword', 'let', undefined, 'let'),
+		]);
+
+		// Each has their own range
+		assert.equal(manager1.element_ranges.get('token_keyword')!.length, 1);
+		assert.equal(manager2.element_ranges.get('token_keyword')!.length, 1);
+
+		// Different range objects
+		assert.notEqual(
+			manager1.element_ranges.get('token_keyword')![0],
+			manager2.element_ranges.get('token_keyword')![0],
+		);
+	});
+});
diff --git a/src/test/highlight_test_helpers.ts b/src/test/highlight_test_helpers.ts
new file mode 100644
index 00000000..8969e442
--- /dev/null
+++ b/src/test/highlight_test_helpers.ts
@@ -0,0 +1,136 @@
+/**
+ * Test helpers for Highlight_Manager tests
+ *
+ * Provides utilities for mocking the CSS Custom Highlight API and creating
+ * test DOM elements in a jsdom environment.
+ */
+
+// Mock implementation of CSS Custom Highlight API
+export class Mock_Highlight extends Set<Range> {
+	priority = 0;
+}
+
+// Mock Range class with bounds validation
+export class Mock_Range {
+	start_container: Node | null = null;
+	start_offset = 0;
+	end_container: Node | null = null;
+	end_offset = 0;
+
+	get startOffset(): number {
+		return this.start_offset;
+	}
+
+	get endOffset(): number {
+		return this.end_offset;
+	}
+
+	setStart(node: Node, offset: number): void {
+		if (node.nodeType !== 3) {
+			throw new Error('Range can only be set on text nodes');
+		}
+		const text_length = node.textContent?.length ?? 0;
+		if (offset < 0 || offset > text_length) {
+			throw new DOMException(`Index or size is negative or greater than the allowed amount`);
+		}
+		this.start_container = node;
+		this.start_offset = offset;
+	}
+
+	setEnd(node: Node, offset: number): void {
+		if (node.nodeType !== 3) {
+			throw new Error('Range can only be set on text nodes');
+		}
+		const text_length = node.textContent?.length ?? 0;
+		if (offset < 0 || offset > text_length) {
+			throw new DOMException(`Index or size is negative or greater than the allowed amount`);
+		}
+		this.end_container = node;
+		this.end_offset = offset;
+	}
+}
+
+// Store for original globals
+export interface Saved_Globals {
+	css: any;
+	highlight: any;
+	range: any;
+	node: any;
+}
+
+/**
+ * Setup CSS Highlight API mocks in global scope
+ */
+export function setup_mock_highlight_api(): Saved_Globals {
+	const saved: Saved_Globals = {
+		css: (globalThis as any).CSS,
+		highlight: (globalThis as any).Highlight,
+		range: (globalThis as any).Range,
+		node: (globalThis as any).Node,
+	};
+
+	// Mock CSS Highlight API
+	(globalThis as any).CSS = {
+		highlights: new Map<string, Mock_Highlight>(),
+	};
+	(globalThis as any).Highlight = Mock_Highlight;
+	(globalThis as any).Range = Mock_Range;
+
+	// Mock Node with TEXT_NODE constant
+	(globalThis as any).Node = {
+		TEXT_NODE: 3,
+		ELEMENT_NODE: 1,
+		COMMENT_NODE: 8,
+	};
+
+	return saved;
+}
+
+/**
+ * Restore original globals
+ */
+export function restore_globals(saved: Saved_Globals): void {
+	(globalThis as any).CSS = saved.css;
+	(globalThis as any).Highlight = saved.highlight;
+	(globalThis as any).Range = saved.range;
+	(globalThis as any).Node = saved.node;
+}
+
+/**
+ * Create a mock code element with text content
+ */
+export function create_code_element(text_content: string): Element {
+	const text_node = {
+		nodeType: 3, // TEXT_NODE
+		textContent: text_content,
+	} as unknown as Text;
+
+	const element = {
+		childNodes: [text_node],
+	} as unknown as Element;
+
+	return element;
+}
+
+/**
+ * Create a mock code element with comment node before text (simulates Svelte)
+ */
+export function create_code_element_with_comment(
+	text_content: string,
+	_comment: string = 'svelte-check-ignore',
+): Element {
+	const comment_node = {
+		nodeType: 8, // COMMENT_NODE
+	} as unknown as Comment;
+
+	const text_node = {
+		nodeType: 3, // TEXT_NODE
+		textContent: text_content,
+	} as unknown as Text;
+
+	const element = {
+		childNodes: [comment_node, text_node],
+	} as unknown as Element;
+
+	return element;
+}
diff --git a/src/lib/syntax_styler.test.ts b/src/test/syntax_styler.test.ts
similarity index 93%
rename from src/lib/syntax_styler.test.ts
rename to src/test/syntax_styler.test.ts
index 92e3901a..a54d1f70 100644
--- a/src/lib/syntax_styler.test.ts
+++ b/src/test/syntax_styler.test.ts
@@ -1,16 +1,17 @@
 import {test, assert, describe} from 'vitest';
-import {Syntax_Styler} from './syntax_styler.js';
-import {tokenize_syntax} from './tokenize_syntax.js';
-import {add_grammar_js} from './grammar_js.js';
-import {add_grammar_ts} from './grammar_ts.js';
-import {add_grammar_css} from './grammar_css.js';
-import {add_grammar_markup} from './grammar_markup.js';
-import {add_grammar_json} from './grammar_json.js';
-import {add_grammar_svelte} from './grammar_svelte.js';
-import {add_grammar_markdown} from './grammar_markdown.js';
-import {add_grammar_clike} from './grammar_clike.js';
-import {syntax_styler_global} from './syntax_styler_global.js';
-import {samples} from './samples/all.js';
+
+import {Syntax_Styler} from '$lib/syntax_styler.js';
+import {tokenize_syntax} from '$lib/tokenize_syntax.js';
+import {add_grammar_js} from '$lib/grammar_js.js';
+import {add_grammar_ts} from '$lib/grammar_ts.js';
+import {add_grammar_css} from '$lib/grammar_css.js';
+import {add_grammar_markup} from '$lib/grammar_markup.js';
+import {add_grammar_json} from '$lib/grammar_json.js';
+import {add_grammar_svelte} from '$lib/grammar_svelte.js';
+import {add_grammar_markdown} from '$lib/grammar_markdown.js';
+import {add_grammar_clike} from '$lib/grammar_clike.js';
+import {syntax_styler_global} from '$lib/syntax_styler_global.js';
+import {samples} from '$lib/samples/all.js';
 
 // Helper to create a properly initialized syntax styler
 const create_styler_with_grammars = (): Syntax_Styler => {
@@ -37,7 +38,7 @@ describe('grammar mutation behavior', () => {
 			const grammar = syntax_styler.get_lang(lang);
 			// After normalization, grammar values are arrays
 			if ((grammar.string as any)?.[0]?.pattern) {
-				before_flags.set(lang, (grammar.string as any)[0].pattern.flags);
+				before_flags.set(lang, grammar.string![0]!.pattern.flags);
 			}
 		}
 
@@ -49,7 +50,7 @@ describe('grammar mutation behavior', () => {
 		// Verify mutation happened (documenting expected behavior)
 		for (const lang of before_flags.keys()) {
 			const grammar = syntax_styler.get_lang(lang);
-			const new_flags = (grammar.string as any)[0].pattern.flags;
+			const new_flags = grammar.string![0]!.pattern.flags;
 			assert.ok(
 				new_flags.includes('g'),
 				`${lang} string pattern should have global flag after use`,
@@ -78,7 +79,7 @@ describe('grammar mutation behavior', () => {
 				if (visited.has(obj)) return;
 				visited.add(obj);
 
-				// After normalization, all grammar values are arrays of Normalized_Grammar_Token
+				// After normalization, all grammar values are arrays of Syntax_Grammar_Token
 				for (const key in obj) {
 					const val = obj[key];
 					if (!Array.isArray(val)) continue;
@@ -424,24 +425,24 @@ describe('pattern flag edge cases', () => {
 
 		// Patterns that already had g flag should keep the same RegExp instance
 		assert.equal(
-			(grammar.already_global as any)[0].pattern,
+			grammar.already_global![0]!.pattern,
 			patterns_before.already_global,
 			'Already global pattern should not be replaced',
 		);
 		assert.equal(
-			(grammar.multi_flag as any)[0].pattern,
+			grammar.multi_flag![0]!.pattern,
 			patterns_before.multi_flag,
 			'Multi-flag pattern should not be replaced',
 		);
 
 		// Pattern without g gets a new RegExp with g added during normalization
 		assert.notEqual(
-			(grammar.case_insensitive as any)[0].pattern,
+			grammar.case_insensitive![0]!.pattern,
 			patterns_before.case_insensitive,
 			'Pattern without g gets replaced with global version during normalization',
 		);
 		assert.equal(
-			(grammar.case_insensitive as any)[0].pattern.flags,
+			grammar.case_insensitive![0]!.pattern.flags,
 			'gi', // Now has both flags
 			'Pattern gains global flag',
 		);
@@ -450,7 +451,7 @@ describe('pattern flag edge cases', () => {
 		syntax_styler.stylize('test TEST tEsT', 'test');
 
 		assert.equal(
-			(grammar.already_global as any)[0].pattern,
+			grammar.already_global![0]!.pattern,
 			patterns_before.already_global,
 			'Pattern unchanged after tokenization',
 		);
@@ -491,8 +492,8 @@ describe('multiple Syntax_Styler instances', () => {
 		const grammar2 = styler2.get_lang('js');
 
 		// Store patterns after normalization (grammar values are arrays)
-		const pattern1 = (grammar1.string as any)[0].pattern;
-		const pattern2 = (grammar2.string as any)[0].pattern;
+		const pattern1 = grammar1.string![0]!.pattern;
+		const pattern2 = grammar2.string![0]!.pattern;
 
 		// Patterns should be different objects (each instance has its own)
 		assert.notEqual(pattern1, pattern2, 'Each instance has separate pattern objects');
@@ -507,20 +508,20 @@ describe('multiple Syntax_Styler instances', () => {
 
 		// Patterns remain unchanged after tokenization (no runtime mutation)
 		assert.equal(
-			(grammar1.string as any)[0].pattern,
+			grammar1.string![0]!.pattern,
 			pattern1,
 			'styler1 pattern unchanged after tokenization',
 		);
 		assert.equal(
-			(grammar2.string as any)[0].pattern,
+			grammar2.string![0]!.pattern,
 			pattern2,
 			'styler2 pattern unchanged after tokenization',
 		);
 
 		// Each instance still has its own pattern object
 		assert.notEqual(
-			(grammar1.string as any)[0].pattern,
-			(grammar2.string as any)[0].pattern,
+			grammar1.string![0]!.pattern,
+			grammar2.string![0]!.pattern,
 			'Instances remain independent',
 		);
 	});
diff --git a/svelte.config.js b/svelte.config.js
index 3b10d6b6..7759731c 100644
--- a/svelte.config.js
+++ b/svelte.config.js
@@ -11,7 +11,7 @@ export default {
 	kit: {
 		adapter: adapter(),
 		paths: {relative: false}, // use root-absolute paths: https://kit.svelte.dev/docs/configuration#paths
-		alias: {$routes: 'src/routes'},
+		alias: {$routes: 'src/routes', $test: 'src/test'},
 		csp: {
 			directives: create_csp_directives({
 				trusted_sources: csp_trusted_sources_of_ryanatkn,
diff --git a/tsconfig.json b/tsconfig.json
index 52e51f1f..1bfafe42 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -13,6 +13,7 @@
 		"noImplicitReturns": true,
 		"noImplicitOverride": true,
 		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
 		"resolveJsonModule": true,
 		"sourceMap": true,
 		"declaration": true,