@fuzdev/fuz_code 0.41.0 → 0.42.0

package/dist/Code.svelte

@@ -8,6 +8,7 @@
 
 	const {
 		content,
+		dangerous_raw_html,
 		lang = 'svelte',
 		grammar,
 		inline = false,
@@ -16,85 +17,101 @@
 		syntax_styler = syntax_styler_global,
 		children,
 		...rest
-	}: SvelteHTMLElements['code'] & {
-		/** 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;
-		/**
-		 * 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?: SyntaxGrammar | undefined;
-		/**
-		 * Whether to render as inline code or block code.
-		 * Controls display via CSS classes.
-		 *
-		 * @default false
-		 */
-		inline?: boolean;
-		/**
-		 * Whether to wrap long lines in block code.
-		 * Sets `white-space: pre-wrap` instead of `white-space: pre`.
-		 *
-		 * **Behavior:**
-		 * - Wraps at whitespace (spaces, newlines)
-		 * - Long tokens without spaces (URLs, hashes) will still scroll horizontally
-		 * - Default `false` provides traditional code block behavior
-		 *
-		 * Only affects block code (ignored for inline mode).
-		 *
-		 * @default false
-		 */
-		wrap?: boolean;
-		/**
-		 * Whether to disable the default margin-bottom on block code.
-		 * Block code has `margin-bottom: var(--space_lg)` by default when not `:last-child`.
-		 *
-		 * @default false
-		 */
-		nomargin?: boolean;
-		/**
-		 * Custom SyntaxStyler instance to use for highlighting.
-		 * Allows using a different styler with custom grammars or configuration.
-		 *
-		 * @default syntax_styler_global
-		 */
-		syntax_styler?: SyntaxStyler;
-		/**
-		 * Optional snippet to customize how the highlighted markup is rendered.
-		 * Receives the generated HTML string as a parameter.
-		 */
-		children?: Snippet<[markup: string]>;
-	} = $props();
+	}: SvelteHTMLElements['code'] &
+		(
+			| {
+					/** The source code to syntax highlight. */
+					content: string;
+					dangerous_raw_html?: undefined;
+			  }
+			| {
+					content?: undefined;
+					/**
+					 * Pre-highlighted HTML from the `svelte_preprocess_fuz_code` preprocessor.
+					 * When provided, skips runtime syntax highlighting entirely.
+					 *
+					 * Named `dangerous_raw_html` to signal that it bypasses sanitization,
+					 * matching the `{@html}` pattern already used by this component.
+					 */
+					dangerous_raw_html: 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;
+			/**
+			 * 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?: SyntaxGrammar | undefined;
+			/**
+			 * Whether to render as inline code or block code.
+			 * Controls display via CSS classes.
+			 *
+			 * @default false
+			 */
+			inline?: boolean;
+			/**
+			 * Whether to wrap long lines in block code.
+			 * Sets `white-space: pre-wrap` instead of `white-space: pre`.
+			 *
+			 * **Behavior:**
+			 * - Wraps at whitespace (spaces, newlines)
+			 * - Long tokens without spaces (URLs, hashes) will still scroll horizontally
+			 * - Default `false` provides traditional code block behavior
+			 *
+			 * Only affects block code (ignored for inline mode).
+			 *
+			 * @default false
+			 */
+			wrap?: boolean;
+			/**
+			 * Whether to disable the default margin-bottom on block code.
+			 * Block code has `margin-bottom: var(--space_lg)` by default when not `:last-child`.
+			 *
+			 * @default false
+			 */
+			nomargin?: boolean;
+			/**
+			 * Custom SyntaxStyler instance to use for highlighting.
+			 * Allows using a different styler with custom grammars or configuration.
+			 *
+			 * @default syntax_styler_global
+			 */
+			syntax_styler?: SyntaxStyler;
+			/**
+			 * Optional snippet to customize how the highlighted markup is rendered.
+			 * Receives the generated HTML string as a parameter.
+			 */
+			children?: Snippet<[markup: string]>;
+		} = $props();
 
 	const language_supported = $derived(lang !== null && !!syntax_styler.langs[lang]);
 
@@ -103,6 +120,8 @@
 	// DEV-only validation warnings
 	if (DEV) {
 		$effect(() => {
+			if (dangerous_raw_html != null) return;
+
 			if (lang && !language_supported && !grammar) {
 				const langs = Object.keys(syntax_styler.langs).join(', ');
 				// eslint-disable-next-line no-console
@@ -116,21 +135,16 @@
 
 	// Generate HTML markup for syntax highlighting
 	const html_content = $derived.by(() => {
-		if (!content || highlighting_disabled) {
-			return '';
-		}
-
+		if (dangerous_raw_html != null) return dangerous_raw_html;
+		if (!content || highlighting_disabled) return '';
 		return syntax_styler.stylize(content, lang!, grammar); // ! is safe bc of the `highlighting_disabled` calculation
 	});
-
-	// TODO do syntax styling at compile-time in the normal case, and don't import these at runtime
-	// TODO @html making me nervous
 </script>
 
 <!-- eslint-disable svelte/no-at-html-tags -->
 
 <code {...rest} class:inline class:wrap class:nomargin data-lang={lang}
-	>{#if highlighting_disabled}{content}{:else if children}{@render children(
+	>{#if highlighting_disabled && dangerous_raw_html == null}{content}{:else if children}{@render children(
 			html_content,
 		)}{:else}{@html html_content}{/if}</code
 >

package/dist/Code.svelte.d.ts

@@ -1,9 +1,21 @@
 import type { Snippet } from 'svelte';
 import type { SvelteHTMLElements } from 'svelte/elements';
 import type { SyntaxStyler, SyntaxGrammar } from './syntax_styler.js';
-type $$ComponentProps = SvelteHTMLElements['code'] & {
+type $$ComponentProps = SvelteHTMLElements['code'] & ({
     /** The source code to syntax highlight. */
     content: string;
+    dangerous_raw_html?: undefined;
+} | {
+    content?: undefined;
+    /**
+     * Pre-highlighted HTML from the `svelte_preprocess_fuz_code` preprocessor.
+     * When provided, skips runtime syntax highlighting entirely.
+     *
+     * Named `dangerous_raw_html` to signal that it bypasses sanitization,
+     * matching the `{@html}` pattern already used by this component.
+     */
+    dangerous_raw_html: string;
+}) & {
     /**
      * Language identifier (e.g., 'ts', 'css', 'html', 'json', 'svelte', 'md').
      *

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

@@ -1 +1 @@
-{"version":3,"file":"Code.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/Code.svelte"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,QAAQ,CAAC;AAEpC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AAGxD,OAAO,KAAK,EAAC,YAAY,EAAE,aAAa,EAAC,MAAM,oBAAoB,CAAC;AAEnE,KAAK,gBAAgB,GAAI,kBAAkB,CAAC,MAAM,CAAC,GAAG;IACrD,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACpC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrC,CAAC;AA8DH,QAAA,MAAM,IAAI,sDAAwC,CAAC;AACnD,KAAK,IAAI,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;AACpC,eAAe,IAAI,CAAC"}
+{"version":3,"file":"Code.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/Code.svelte"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,QAAQ,CAAC;AAEpC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AAGxD,OAAO,KAAK,EAAC,YAAY,EAAE,aAAa,EAAC,MAAM,oBAAoB,CAAC;AAEnE,KAAK,gBAAgB,GAAI,kBAAkB,CAAC,MAAM,CAAC,GAClD,CACG;IACA,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB,CAAC,EAAE,SAAS,CAAC;CAC9B,GACD;IACA,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;;;OAMG;IACH,kBAAkB,EAAE,MAAM,CAAC;CAC1B,CACH,GAAG;IACH;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IACpC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrC,CAAC;AA4DJ,QAAA,MAAM,IAAI,sDAAwC,CAAC;AACnD,KAAK,IAAI,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;AACpC,eAAe,IAAI,CAAC"}

package/dist/svelte_preprocess_fuz_code.d.ts

@@ -0,0 +1,24 @@
+import { type PreprocessorGroup } from 'svelte/compiler';
+import type { SyntaxStyler } from './syntax_styler.js';
+export interface PreprocessFuzCodeOptions {
+    /** File patterns to exclude. */
+    exclude?: Array<string | RegExp>;
+    /** Custom syntax styler. @default syntax_styler_global */
+    syntax_styler?: SyntaxStyler;
+    /** Enable in-memory caching. @default true */
+    cache?: boolean;
+    /**
+     * Import sources that resolve to the Code component.
+     * Used to verify that `<Code>` in templates actually refers to fuz_code's Code.svelte.
+     *
+     * @default ['@fuzdev/fuz_code/Code.svelte']
+     */
+    component_imports?: Array<string>;
+    /**
+     * How to handle errors.
+     * @default 'throw' in CI, 'log' otherwise
+     */
+    on_error?: 'log' | 'throw';
+}
+export declare const svelte_preprocess_fuz_code: (options?: PreprocessFuzCodeOptions) => PreprocessorGroup;
+//# sourceMappingURL=svelte_preprocess_fuz_code.d.ts.map

package/dist/svelte_preprocess_fuz_code.d.ts.map

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

package/dist/svelte_preprocess_fuz_code.js

@@ -0,0 +1,260 @@
+import { parse } from 'svelte/compiler';
+import MagicString from 'magic-string';
+import { walk } from 'zimmerframe';
+import { syntax_styler_global } from './syntax_styler_global.js';
+export const svelte_preprocess_fuz_code = (options = {}) => {
+    const { exclude = [], syntax_styler = syntax_styler_global, cache = true, component_imports = ['@fuzdev/fuz_code/Code.svelte'], on_error = process.env.CI ? 'throw' : 'log', } = options;
+    // In-memory cache: content+lang hash → highlighted HTML
+    const highlight_cache = new Map();
+    return {
+        name: 'fuz-code',
+        markup: ({ content, filename }) => {
+            // Skip excluded files
+            if (should_exclude(filename, exclude)) {
+                return { code: content };
+            }
+            // Quick check: does file import from a known Code component source?
+            if (!component_imports.some((source) => content.includes(source))) {
+                return { code: content };
+            }
+            const s = new MagicString(content);
+            const ast = parse(content, { filename, modern: true });
+            // Resolve which local names map to the Code component
+            const code_names = resolve_code_names(ast, component_imports);
+            if (code_names.size === 0) {
+                return { code: content };
+            }
+            // Find Code component usages with static content
+            const transformations = find_code_usages(ast, syntax_styler, code_names, {
+                cache: cache ? highlight_cache : null,
+                on_error,
+                filename,
+                source: content,
+            });
+            if (transformations.length === 0) {
+                return { code: content };
+            }
+            // Apply transformations
+            for (const t of transformations) {
+                s.overwrite(t.start, t.end, t.replacement);
+            }
+            return {
+                code: s.toString(),
+                map: s.generateMap({ hires: true }),
+            };
+        },
+    };
+};
+/**
+ * Check if a filename matches any exclusion pattern.
+ */
+const should_exclude = (filename, exclude) => {
+    if (!filename || exclude.length === 0)
+        return false;
+    return exclude.some((pattern) => typeof pattern === 'string' ? filename.includes(pattern) : pattern.test(filename));
+};
+/**
+ * Scans import declarations to find local names that import from known Code component sources.
+ * Handles default imports, named imports, and aliased imports.
+ * Checks both instance (`<script>`) and module (`<script module>`) scripts.
+ */
+const resolve_code_names = (ast, component_imports) => {
+    const names = new Set();
+    for (const script of [ast.instance, ast.module]) {
+        if (!script)
+            continue;
+        for (const node of script.content.body) {
+            if (node.type !== 'ImportDeclaration')
+                continue;
+            if (!component_imports.includes(node.source.value))
+                continue;
+            for (const specifier of node.specifiers) {
+                // default import: `import Code from '...'`
+                // aliased: `import Highlighter from '...'`
+                // named: `import { default as Code } from '...'`
+                names.add(specifier.local.name);
+            }
+        }
+    }
+    return names;
+};
+/**
+ * Attempt to highlight content, using cache if available.
+ * Returns the highlighted HTML, or `null` on error.
+ */
+const try_highlight = (text, lang, syntax_styler, options) => {
+    const cache_key = `${lang}:${text}`;
+    let html = options.cache?.get(cache_key);
+    if (html == null) {
+        try {
+            html = syntax_styler.stylize(text, lang);
+            options.cache?.set(cache_key, html);
+        }
+        catch (error) {
+            handle_error(error, options);
+            return null;
+        }
+    }
+    return html;
+};
+/**
+ * Walks the AST to find Code component usages with static `content` props
+ * and generates transformations to replace them with `dangerous_raw_html`.
+ */
+const find_code_usages = (ast, syntax_styler, code_names, options) => {
+    const transformations = [];
+    walk(ast.fragment, null, {
+        Component(node, context) {
+            // Always recurse into children - without this, Code components
+            // nested inside other components would be missed, because zimmerframe
+            // does not auto-recurse when a visitor is defined for a node type.
+            context.next();
+            if (!code_names.has(node.name))
+                return;
+            const content_attr = find_attribute(node, 'content');
+            if (!content_attr)
+                return;
+            // Skip if already preprocessed or custom grammar/syntax_styler is provided
+            if (find_attribute(node, 'dangerous_raw_html') ||
+                find_attribute(node, 'grammar') ||
+                find_attribute(node, 'syntax_styler')) {
+                return;
+            }
+            // Resolve language - must be static and supported
+            const lang_attr = find_attribute(node, 'lang');
+            const lang_value = lang_attr ? extract_static_string(lang_attr.value) : 'svelte';
+            if (lang_value === null)
+                return;
+            if (!syntax_styler.langs[lang_value])
+                return;
+            // Try simple static string
+            const content_value = extract_static_string(content_attr.value);
+            if (content_value !== null) {
+                const html = try_highlight(content_value, lang_value, syntax_styler, options);
+                if (html === null || html === content_value)
+                    return;
+                transformations.push({
+                    start: content_attr.start,
+                    end: content_attr.end,
+                    replacement: `dangerous_raw_html={'${escape_js_string(html)}'}`,
+                });
+                return;
+            }
+            // Try conditional expression with static string branches
+            const conditional = try_extract_conditional(content_attr.value, options.source);
+            if (conditional) {
+                const html_a = try_highlight(conditional.consequent, lang_value, syntax_styler, options);
+                const html_b = try_highlight(conditional.alternate, lang_value, syntax_styler, options);
+                if (html_a === null || html_b === null)
+                    return;
+                if (html_a === conditional.consequent && html_b === conditional.alternate)
+                    return;
+                transformations.push({
+                    start: content_attr.start,
+                    end: content_attr.end,
+                    replacement: `dangerous_raw_html={${conditional.test_source} ? '${escape_js_string(html_a)}' : '${escape_js_string(html_b)}'}`,
+                });
+            }
+        },
+    });
+    return transformations;
+};
+/**
+ * Find an attribute by name on a component node.
+ */
+const find_attribute = (node, name) => {
+    for (const attr of node.attributes) {
+        if (attr.type === 'Attribute' && attr.name === name) {
+            return attr;
+        }
+    }
+    return undefined;
+};
+/**
+ * Recursively evaluate an expression AST node to a static string value.
+ * Handles string literals, template literals (no interpolation), and string concatenation.
+ * Returns `null` for dynamic or non-string expressions.
+ */
+const evaluate_static_expr = (expr) => {
+    if (expr.type === 'Literal' && typeof expr.value === 'string')
+        return expr.value;
+    if (expr.type === 'TemplateLiteral' && expr.expressions.length === 0) {
+        return expr.quasis.map((q) => q.value.cooked ?? q.value.raw).join('');
+    }
+    if (expr.type === 'BinaryExpression' && expr.operator === '+') {
+        const left = evaluate_static_expr(expr.left);
+        if (left === null)
+            return null;
+        const right = evaluate_static_expr(expr.right);
+        if (right === null)
+            return null;
+        return left + right;
+    }
+    return null;
+};
+/**
+ * Extract the string value from a static attribute value.
+ * Returns `null` for dynamic, non-string, or null literal values.
+ */
+const extract_static_string = (value) => {
+    // Boolean attribute
+    if (value === true)
+        return null;
+    // Plain attribute: content="text"
+    if (Array.isArray(value)) {
+        const first = value[0];
+        if (value.length === 1 && first?.type === 'Text') {
+            return first.data;
+        }
+        return null;
+    }
+    // ExpressionTag
+    const expr = value.expression;
+    // Null literal
+    if (expr.type === 'Literal' && expr.value === null)
+        return null;
+    return evaluate_static_expr(expr);
+};
+/**
+ * Try to extract a conditional expression where both branches are static strings.
+ * Returns the condition source text and both branch values, or `null` if not applicable.
+ */
+const try_extract_conditional = (value, source) => {
+    if (value === true || Array.isArray(value))
+        return null;
+    const expr = value.expression;
+    if (expr.type !== 'ConditionalExpression')
+        return null;
+    const consequent = evaluate_static_expr(expr.consequent);
+    if (consequent === null)
+        return null;
+    const alternate = evaluate_static_expr(expr.alternate);
+    if (alternate === null)
+        return null;
+    const test = expr.test;
+    const test_source = source.slice(test.start, test.end);
+    return { test_source, consequent, alternate };
+};
+/**
+ * Escapes a string for use inside a single-quoted JS string literal.
+ * Single quotes are used because `stylize()` output contains double quotes
+ * on every token span, so wrapping with single quotes avoids escaping those.
+ */
+const escape_js_string = (html) => {
+    return html
+        .replace(/\\/g, '\\\\') // backslashes first
+        .replace(/'/g, "\\'") // single quotes
+        .replace(/\n/g, '\\n') // newlines
+        .replace(/\r/g, '\\r'); // carriage returns
+};
+/**
+ * Handle errors during highlighting.
+ */
+const handle_error = (error, options) => {
+    const message = `[fuz-code] Highlighting failed${options.filename ? ` in ${options.filename}` : ''}: ${error instanceof Error ? error.message : String(error)}`;
+    if (options.on_error === 'throw') {
+        throw new Error(message);
+    }
+    // eslint-disable-next-line no-console
+    console.error(message);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_code",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "syntax styling utilities and components for TypeScript, Svelte, and Markdown",
   "glyph": "🎨",
   "logo": "logo.svg",
@@ -23,8 +23,8 @@
     "test": "gro test",
     "preview": "vite preview",
     "deploy": "gro deploy",
-    "benchmark": "gro run src/benchmark/run_benchmarks.ts",
-    "benchmark:compare": "gro run src/benchmark/compare/run_compare.ts",
+    "benchmark": "gro run benchmark/run_benchmarks.ts",
+    "benchmark:compare": "gro run benchmark/compare/run_compare.ts",
     "fixtures:update": "gro src/test/fixtures/update"
   },
   "type": "module",
@@ -33,23 +33,31 @@
   },
   "peerDependencies": {
     "@fuzdev/fuz_css": ">=0.44.1",
-    "svelte": "^5"
+    "magic-string": "^0.30",
+    "svelte": "^5",
+    "zimmerframe": "^1"
   },
   "peerDependenciesMeta": {
     "@fuzdev/fuz_css": {
       "optional": true
     },
+    "magic-string": {
+      "optional": true
+    },
     "svelte": {
       "optional": true
+    },
+    "zimmerframe": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
-    "@fuzdev/fuz_css": "^0.45.0",
-    "@fuzdev/fuz_ui": "^0.180.0",
-    "@fuzdev/fuz_util": "^0.48.2",
+    "@fuzdev/fuz_css": "^0.47.0",
+    "@fuzdev/fuz_ui": "^0.181.1",
+    "@fuzdev/fuz_util": "^0.48.3",
     "@ryanatkn/eslint-config": "^0.9.0",
-    "@ryanatkn/gro": "^0.189.3",
+    "@ryanatkn/gro": "^0.190.0",
     "@sveltejs/adapter-static": "^3.0.10",
     "@sveltejs/kit": "^2.50.1",
     "@sveltejs/package": "^2.5.7",
@@ -59,14 +67,16 @@
     "eslint": "^9.39.1",
     "eslint-plugin-svelte": "^3.13.1",
     "esm-env": "^1.2.2",
+    "magic-string": "^0.30.21",
     "prettier": "^3.7.4",
     "prettier-plugin-svelte": "^3.4.1",
-    "svelte": "^5.48.5",
-    "svelte-check": "^4.3.5",
+    "svelte": "^5.49.1",
+    "svelte-check": "^4.3.6",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.48.1",
-    "vitest": "^4.0.15"
+    "vitest": "^4.0.15",
+    "zimmerframe": "^1.1.4"
   },
   "prettier": {
     "plugins": [

package/src/lib/svelte_preprocess_fuz_code.ts

@@ -0,0 +1,350 @@
+import {parse, type PreprocessorGroup, type AST} from 'svelte/compiler';
+import MagicString from 'magic-string';
+import {walk} from 'zimmerframe';
+
+import {syntax_styler_global} from './syntax_styler_global.js';
+import type {SyntaxStyler} from './syntax_styler.js';
+
+export interface PreprocessFuzCodeOptions {
+	/** File patterns to exclude. */
+	exclude?: Array<string | RegExp>;
+
+	/** Custom syntax styler. @default syntax_styler_global */
+	syntax_styler?: SyntaxStyler;
+
+	/** Enable in-memory caching. @default true */
+	cache?: boolean;
+
+	/**
+	 * Import sources that resolve to the Code component.
+	 * Used to verify that `<Code>` in templates actually refers to fuz_code's Code.svelte.
+	 *
+	 * @default ['@fuzdev/fuz_code/Code.svelte']
+	 */
+	component_imports?: Array<string>;
+
+	/**
+	 * How to handle errors.
+	 * @default 'throw' in CI, 'log' otherwise
+	 */
+	on_error?: 'log' | 'throw';
+}
+
+export const svelte_preprocess_fuz_code = (
+	options: PreprocessFuzCodeOptions = {},
+): PreprocessorGroup => {
+	const {
+		exclude = [],
+		syntax_styler = syntax_styler_global,
+		cache = true,
+		component_imports = ['@fuzdev/fuz_code/Code.svelte'],
+		on_error = process.env.CI ? 'throw' : 'log',
+	} = options;
+
+	// In-memory cache: content+lang hash → highlighted HTML
+	const highlight_cache: Map<string, string> = new Map();
+
+	return {
+		name: 'fuz-code',
+
+		markup: ({content, filename}) => {
+			// Skip excluded files
+			if (should_exclude(filename, exclude)) {
+				return {code: content};
+			}
+
+			// Quick check: does file import from a known Code component source?
+			if (!component_imports.some((source) => content.includes(source))) {
+				return {code: content};
+			}
+
+			const s = new MagicString(content);
+			const ast = parse(content, {filename, modern: true});
+
+			// Resolve which local names map to the Code component
+			const code_names = resolve_code_names(ast, component_imports);
+			if (code_names.size === 0) {
+				return {code: content};
+			}
+
+			// Find Code component usages with static content
+			const transformations = find_code_usages(ast, syntax_styler, code_names, {
+				cache: cache ? highlight_cache : null,
+				on_error,
+				filename,
+				source: content,
+			});
+
+			if (transformations.length === 0) {
+				return {code: content};
+			}
+
+			// Apply transformations
+			for (const t of transformations) {
+				s.overwrite(t.start, t.end, t.replacement);
+			}
+
+			return {
+				code: s.toString(),
+				map: s.generateMap({hires: true}),
+			};
+		},
+	};
+};
+
+/**
+ * Check if a filename matches any exclusion pattern.
+ */
+const should_exclude = (filename: string | undefined, exclude: Array<string | RegExp>): boolean => {
+	if (!filename || exclude.length === 0) return false;
+	return exclude.some((pattern) =>
+		typeof pattern === 'string' ? filename.includes(pattern) : pattern.test(filename),
+	);
+};
+
+/**
+ * Scans import declarations to find local names that import from known Code component sources.
+ * Handles default imports, named imports, and aliased imports.
+ * Checks both instance (`<script>`) and module (`<script module>`) scripts.
+ */
+const resolve_code_names = (ast: AST.Root, component_imports: Array<string>): Set<string> => {
+	const names: Set<string> = new Set();
+
+	for (const script of [ast.instance, ast.module]) {
+		if (!script) continue;
+
+		for (const node of script.content.body) {
+			if (node.type !== 'ImportDeclaration') continue;
+			if (!component_imports.includes(node.source.value as string)) continue;
+
+			for (const specifier of node.specifiers) {
+				// default import: `import Code from '...'`
+				// aliased: `import Highlighter from '...'`
+				// named: `import { default as Code } from '...'`
+				names.add(specifier.local.name);
+			}
+		}
+	}
+
+	return names;
+};
+
+interface Transformation {
+	start: number;
+	end: number;
+	replacement: string;
+}
+
+interface FindCodeUsagesOptions {
+	cache: Map<string, string> | null;
+	on_error: 'log' | 'throw';
+	filename: string | undefined;
+	source: string;
+}
+
+/**
+ * Attempt to highlight content, using cache if available.
+ * Returns the highlighted HTML, or `null` on error.
+ */
+const try_highlight = (
+	text: string,
+	lang: string,
+	syntax_styler: SyntaxStyler,
+	options: FindCodeUsagesOptions,
+): string | null => {
+	const cache_key = `${lang}:${text}`;
+	let html = options.cache?.get(cache_key);
+	if (html == null) {
+		try {
+			html = syntax_styler.stylize(text, lang);
+			options.cache?.set(cache_key, html);
+		} catch (error) {
+			handle_error(error, options);
+			return null;
+		}
+	}
+	return html;
+};
+
+/**
+ * Walks the AST to find Code component usages with static `content` props
+ * and generates transformations to replace them with `dangerous_raw_html`.
+ */
+const find_code_usages = (
+	ast: AST.Root,
+	syntax_styler: SyntaxStyler,
+	code_names: Set<string>,
+	options: FindCodeUsagesOptions,
+): Array<Transformation> => {
+	const transformations: Array<Transformation> = [];
+
+	walk(ast.fragment as any, null, {
+		Component(node: AST.Component, context: {next: () => void}) {
+			// Always recurse into children - without this, Code components
+			// nested inside other components would be missed, because zimmerframe
+			// does not auto-recurse when a visitor is defined for a node type.
+			context.next();
+
+			if (!code_names.has(node.name)) return;
+
+			const content_attr = find_attribute(node, 'content');
+			if (!content_attr) return;
+
+			// Skip if already preprocessed or custom grammar/syntax_styler is provided
+			if (
+				find_attribute(node, 'dangerous_raw_html') ||
+				find_attribute(node, 'grammar') ||
+				find_attribute(node, 'syntax_styler')
+			) {
+				return;
+			}
+
+			// Resolve language - must be static and supported
+			const lang_attr = find_attribute(node, 'lang');
+			const lang_value = lang_attr ? extract_static_string(lang_attr.value) : 'svelte';
+			if (lang_value === null) return;
+			if (!syntax_styler.langs[lang_value]) return;
+
+			// Try simple static string
+			const content_value = extract_static_string(content_attr.value);
+			if (content_value !== null) {
+				const html = try_highlight(content_value, lang_value, syntax_styler, options);
+				if (html === null || html === content_value) return;
+				transformations.push({
+					start: content_attr.start,
+					end: content_attr.end,
+					replacement: `dangerous_raw_html={'${escape_js_string(html)}'}`,
+				});
+				return;
+			}
+
+			// Try conditional expression with static string branches
+			const conditional = try_extract_conditional(content_attr.value, options.source);
+			if (conditional) {
+				const html_a = try_highlight(conditional.consequent, lang_value, syntax_styler, options);
+				const html_b = try_highlight(conditional.alternate, lang_value, syntax_styler, options);
+				if (html_a === null || html_b === null) return;
+				if (html_a === conditional.consequent && html_b === conditional.alternate) return;
+				transformations.push({
+					start: content_attr.start,
+					end: content_attr.end,
+					replacement: `dangerous_raw_html={${conditional.test_source} ? '${escape_js_string(html_a)}' : '${escape_js_string(html_b)}'}`,
+				});
+			}
+		},
+	});
+
+	return transformations;
+};
+
+/**
+ * Find an attribute by name on a component node.
+ */
+const find_attribute = (node: AST.Component, name: string): AST.Attribute | undefined => {
+	for (const attr of node.attributes) {
+		if (attr.type === 'Attribute' && attr.name === name) {
+			return attr;
+		}
+	}
+	return undefined;
+};
+
+type Attribute_Value = AST.Attribute['value'];
+
+/**
+ * Recursively evaluate an expression AST node to a static string value.
+ * Handles string literals, template literals (no interpolation), and string concatenation.
+ * Returns `null` for dynamic or non-string expressions.
+ */
+const evaluate_static_expr = (expr: any): string | null => {
+	if (expr.type === 'Literal' && typeof expr.value === 'string') return expr.value;
+	if (expr.type === 'TemplateLiteral' && expr.expressions.length === 0) {
+		return expr.quasis.map((q: any) => q.value.cooked ?? q.value.raw).join('');
+	}
+	if (expr.type === 'BinaryExpression' && expr.operator === '+') {
+		const left = evaluate_static_expr(expr.left);
+		if (left === null) return null;
+		const right = evaluate_static_expr(expr.right);
+		if (right === null) return null;
+		return left + right;
+	}
+	return null;
+};
+
+/**
+ * Extract the string value from a static attribute value.
+ * Returns `null` for dynamic, non-string, or null literal values.
+ */
+const extract_static_string = (value: Attribute_Value): string | null => {
+	// Boolean attribute
+	if (value === true) return null;
+
+	// Plain attribute: content="text"
+	if (Array.isArray(value)) {
+		const first = value[0];
+		if (value.length === 1 && first?.type === 'Text') {
+			return first.data;
+		}
+		return null;
+	}
+
+	// ExpressionTag
+	const expr = value.expression;
+	// Null literal
+	if (expr.type === 'Literal' && expr.value === null) return null;
+	return evaluate_static_expr(expr);
+};
+
+interface ConditionalStaticStrings {
+	test_source: string;
+	consequent: string;
+	alternate: string;
+}
+
+/**
+ * Try to extract a conditional expression where both branches are static strings.
+ * Returns the condition source text and both branch values, or `null` if not applicable.
+ */
+const try_extract_conditional = (
+	value: Attribute_Value,
+	source: string,
+): ConditionalStaticStrings | null => {
+	if (value === true || Array.isArray(value)) return null;
+	const expr = value.expression;
+	if (expr.type !== 'ConditionalExpression') return null;
+
+	const consequent = evaluate_static_expr(expr.consequent);
+	if (consequent === null) return null;
+	const alternate = evaluate_static_expr(expr.alternate);
+	if (alternate === null) return null;
+
+	const test = expr.test as any;
+	const test_source = source.slice(test.start, test.end);
+	return {test_source, consequent, alternate};
+};
+
+/**
+ * Escapes a string for use inside a single-quoted JS string literal.
+ * Single quotes are used because `stylize()` output contains double quotes
+ * on every token span, so wrapping with single quotes avoids escaping those.
+ */
+const escape_js_string = (html: string): string => {
+	return html
+		.replace(/\\/g, '\\\\') // backslashes first
+		.replace(/'/g, "\\'") // single quotes
+		.replace(/\n/g, '\\n') // newlines
+		.replace(/\r/g, '\\r'); // carriage returns
+};
+
+/**
+ * Handle errors during highlighting.
+ */
+const handle_error = (error: unknown, options: FindCodeUsagesOptions): void => {
+	const message = `[fuz-code] Highlighting failed${options.filename ? ` in ${options.filename}` : ''}: ${error instanceof Error ? error.message : String(error)}`;
+
+	if (options.on_error === 'throw') {
+		throw new Error(message);
+	}
+	// eslint-disable-next-line no-console
+	console.error(message);
+};