@fuzdev/fuz_code 0.44.1 → 0.45.1

package/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, and Markdown 🎨
+> syntax styling utilities and components for TypeScript, Svelte, Markdown, and more 🎨
 
 **[code.fuz.dev](https://code.fuz.dev/)**
 

package/dist/code_sample.d.ts

@@ -3,6 +3,6 @@ export interface CodeSample {
     lang: string;
     content: string;
 }
-export declare const sample_langs: readonly ["json", "css", "ts", "html", "svelte", "md"];
+export declare const sample_langs: readonly ["json", "css", "ts", "html", "svelte", "md", "bash"];
 export type SampleLang = (typeof sample_langs)[number];
 //# sourceMappingURL=code_sample.d.ts.map

package/dist/code_sample.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"code_sample.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/code_sample.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAGD,eAAO,MAAM,YAAY,wDAAyD,CAAC;AAEnF,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"code_sample.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/code_sample.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAGD,eAAO,MAAM,YAAY,gEAAiE,CAAC;AAE3F,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/code_sample.js

@@ -1,2 +1,2 @@
 // Languages ordered from simple to complex
-export const sample_langs = ['json', 'css', 'ts', 'html', 'svelte', 'md'];
+export const sample_langs = ['json', 'css', 'ts', 'html', 'svelte', 'md', 'bash'];

package/dist/grammar_bash.d.ts

@@ -0,0 +1,17 @@
+import type { AddSyntaxGrammar } from './syntax_styler.js';
+/**
+ * Bash/shell grammar for syntax highlighting.
+ *
+ * Standalone grammar (no base extension). Covers core bash syntax:
+ * comments, strings, variables, functions, keywords, builtins,
+ * operators, and redirections.
+ *
+ * Based on Prism (https://github.com/PrismJS/prism)
+ * by Lea Verou (https://lea.verou.me/)
+ *
+ * MIT license
+ *
+ * @see LICENSE
+ */
+export declare const add_grammar_bash: AddSyntaxGrammar;
+//# sourceMappingURL=grammar_bash.d.ts.map

package/dist/grammar_bash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar_bash.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/grammar_bash.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,gBAAgB,EAAmB,MAAM,oBAAoB,CAAC;AAE3E;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gBAAgB,EAAE,gBA8J9B,CAAC"}

package/dist/grammar_bash.js

@@ -0,0 +1,153 @@
+/**
+ * Bash/shell grammar for syntax highlighting.
+ *
+ * Standalone grammar (no base extension). Covers core bash syntax:
+ * comments, strings, variables, functions, keywords, builtins,
+ * operators, and redirections.
+ *
+ * Based on Prism (https://github.com/PrismJS/prism)
+ * by Lea Verou (https://lea.verou.me/)
+ *
+ * MIT license
+ *
+ * @see LICENSE
+ */
+export const add_grammar_bash = (syntax_styler) => {
+    // Shared inside grammar for command substitution — `rest` wired after construction
+    const command_sub_inside = {
+        punctuation: /^\$\(|\)$/,
+    };
+    // Reusable balanced-paren pattern for $(...) — handles 2 levels of inner () nesting,
+    // which supports up to 3 levels of $() command substitution (4+ is vanishingly rare)
+    const command_sub_pattern = /\$\((?:[^()]*|\((?:[^()]*|\([^()]*\))*\))*\)/;
+    const grammar_bash = {
+        // Shebang at file start — matched before general comments
+        shebang: {
+            pattern: /^#!.*/,
+            alias: 'comment',
+        },
+        // Line comments — require whitespace or start-of-string before #
+        comment: {
+            pattern: /(^|\s)#.*/,
+            lookbehind: true,
+            greedy: true,
+        },
+        // Here-documents — must precede string to avoid delimiter consumption
+        heredoc: [
+            // Quoted delimiter (<<'DELIM' or <<"DELIM") — no expansion
+            {
+                pattern: /(^|[^<])<<-?\s*(?:['"])(\w+)(?:['"])[\t ]*\n[\s\S]*?\n[\t ]*\2(?=\s*$)/m,
+                lookbehind: true,
+                greedy: true,
+                alias: 'string',
+                inside: {
+                    // No `m` flag — `^` matches start-of-string (opening) and `$` matches
+                    // end-of-string (closing), so single-word content lines can't false-positive
+                    heredoc_delimiter: [
+                        {
+                            pattern: /^<<-?\s*(?:['"])\w+(?:['"])/,
+                            alias: 'punctuation',
+                        },
+                        {
+                            pattern: /\w+$/,
+                            alias: 'punctuation',
+                        },
+                    ],
+                },
+            },
+            // Unquoted delimiter (<<DELIM) — with variable/command expansion
+            {
+                pattern: /(^|[^<])<<-?\s*(\w+)[\t ]*\n[\s\S]*?\n[\t ]*\2(?=\s*$)/m,
+                lookbehind: true,
+                greedy: true,
+                alias: 'string',
+                inside: {
+                    heredoc_delimiter: [
+                        {
+                            pattern: /^<<-?\s*\w+/,
+                            alias: 'punctuation',
+                        },
+                        {
+                            pattern: /\w+$/,
+                            alias: 'punctuation',
+                        },
+                    ],
+                    command_substitution: {
+                        pattern: command_sub_pattern,
+                        greedy: true,
+                        inside: command_sub_inside,
+                    },
+                    variable: /\$\{[^}]+\}|\$(?:\w+|[!@#$*?\-0-9])/,
+                },
+            },
+        ],
+        // Strings — three variants
+        string: [
+            // Double-quoted: supports escape sequences, variable interpolation, command substitution
+            {
+                pattern: /(^|[^\\](?:\\\\)*)"(?:\\[\s\S]|\$\((?:[^()]*|\((?:[^()]*|\([^()]*\))*\))*\)|\$(?!\()|[^"\\$])*"/,
+                lookbehind: true,
+                greedy: true,
+                inside: {
+                    command_substitution: {
+                        pattern: command_sub_pattern,
+                        greedy: true,
+                        inside: command_sub_inside,
+                    },
+                    variable: /\$\{[^}]+\}|\$(?:\w+|[!@#$*?\-0-9])/,
+                },
+            },
+            // Single-quoted: completely literal
+            {
+                pattern: /(^|[^\\](?:\\\\)*)'[^']*'/,
+                lookbehind: true,
+                greedy: true,
+            },
+            // ANSI-C quoting: $'...' with C-style escapes
+            {
+                pattern: /\$'(?:[^'\\]|\\[\s\S])*'/,
+                greedy: true,
+            },
+        ],
+        // Command substitution $(...) — before variable since both start with $
+        command_substitution: {
+            pattern: command_sub_pattern,
+            greedy: true,
+            inside: command_sub_inside,
+        },
+        // Variables and parameter expansion
+        variable: /\$\{[^}]+\}|\$(?:\w+|[!@#$*?\-0-9])/,
+        // Function definitions — both styles
+        function: [
+            // function fname style
+            {
+                pattern: /(\bfunction\s+)\w+/,
+                lookbehind: true,
+            },
+            // fname() style
+            {
+                pattern: /\b\w+(?=\s*\(\s*\))/,
+            },
+        ],
+        // Shell keywords
+        keyword: /\b(?:if|then|else|elif|fi|for|while|until|do|done|case|esac|in|select|function|return|local|export|declare|typeset|readonly|unset|set|shift|trap|break|continue|coproc|time)\b/,
+        // Builtin commands
+        builtin: /\b(?:echo|printf|cd|pwd|read|test|source|eval|exec|exit|getopts|hash|type|ulimit|umask|wait|kill|jobs|bg|fg|disown|alias|unalias|command|shopt)\b/,
+        // Boolean commands
+        boolean: /\b(?:true|false)\b/,
+        // File descriptors before redirections — must precede number
+        file_descriptor: {
+            pattern: /\B&\d\b|\b\d(?=>>?|<)/,
+            alias: 'important',
+        },
+        // Numbers: hex, octal, base-N, decimal
+        number: /\b(?:0x[\da-fA-F]+|0[0-7]+|\d+#[\da-zA-Z]+|\d+)\b/,
+        // Operators — longest first
+        operator: /\|\||&&|;;|&>>?|<<<?|>>?|=~|[!=]=|[<>]|[|&!]/,
+        // Punctuation
+        punctuation: /[{}[\]();,]/,
+    };
+    // Wire circular reference so command substitutions get full bash highlighting
+    command_sub_inside.rest = grammar_bash;
+    syntax_styler.add_lang('bash', grammar_bash, ['sh', 'shell']);
+};

package/dist/grammar_markdown.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grammar_markdown.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/grammar_markdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,gBAAgB,EAIhB,MAAM,oBAAoB,CAAC;AAsF5B;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,gBAgMlC,CAAC"}
+{"version":3,"file":"grammar_markdown.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/grammar_markdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,gBAAgB,EAIhB,MAAM,oBAAoB,CAAC;AAsF5B;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,gBAiMlC,CAAC"}

package/dist/grammar_markdown.js

@@ -69,6 +69,7 @@ export const add_grammar_markdown = (syntax_styler) => {
         { aliases: ['html', 'markup'], id: 'markup' },
         { aliases: ['json'], id: 'json' },
         { aliases: ['svelte'], id: 'svelte' },
+        { aliases: ['bash', 'sh', 'shell'], id: 'bash' },
     ];
     // Fence types: higher counts first (for proper precedence in tokenization)
     const fence_types = [

package/dist/highlight_manager.d.ts

@@ -5,8 +5,16 @@ export type HighlightMode = 'auto' | 'ranges' | 'html';
  */
 export declare const supports_css_highlight_api: () => boolean;
 /**
- * Manages highlights for a single element.
+ * Manages CSS Custom Highlight API ranges for a single element.
  * Tracks ranges per element and only removes its own ranges when clearing.
+ *
+ * **Experimental** — limited browser support. Use `Code` for production.
+ *
+ * @example
+ * ```ts
+ * const manager = new HighlightManager();
+ * manager.highlight_from_syntax_tokens(element, tokens);
+ * ```
  */
 export declare class HighlightManager {
     #private;

package/dist/highlight_manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"highlight_manager.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/highlight_manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAGzD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,0BAA0B,QAAO,OACS,CAAC;AAExD;;;GAGG;AACH,qBAAa,gBAAgB;;IAC5B,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;;IAS1C;;OAEG;IACH,4BAA4B,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAkD/E;;OAEG;IACH,oBAAoB,IAAI,IAAI;IAmB5B,OAAO,IAAI,IAAI;CAiFf"}
+{"version":3,"file":"highlight_manager.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/highlight_manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAGzD,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,0BAA0B,QAAO,OACS,CAAC;AAExD;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;;IAC5B,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;;IAS1C;;OAEG;IACH,4BAA4B,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAkD/E;;OAEG;IACH,oBAAoB,IAAI,IAAI;IAmB5B,OAAO,IAAI,IAAI;CAiFf"}

package/dist/highlight_manager.js

@@ -4,8 +4,16 @@ import { highlight_priorities } from './highlight_priorities.js';
  */
 export const supports_css_highlight_api = () => !!(globalThis.CSS?.highlights && globalThis.Highlight); // eslint-disable-line @typescript-eslint/no-unnecessary-condition
 /**
- * Manages highlights for a single element.
+ * Manages CSS Custom Highlight API ranges for a single element.
  * Tracks ranges per element and only removes its own ranges when clearing.
+ *
+ * **Experimental** — limited browser support. Use `Code` for production.
+ *
+ * @example
+ * ```ts
+ * const manager = new HighlightManager();
+ * manager.highlight_from_syntax_tokens(element, tokens);
+ * ```
  */
 export class HighlightManager {
     element_ranges;

package/dist/highlight_priorities.gen.d.ts

@@ -1,4 +1,4 @@
-import type { Gen } from '@ryanatkn/gro';
+import type { Gen } from '@fuzdev/gro';
 /** @nodocs */
 export declare const gen: Gen;
 //# sourceMappingURL=highlight_priorities.gen.d.ts.map

package/dist/highlight_priorities.gen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"highlight_priorities.gen.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/highlight_priorities.gen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,eAAe,CAAC;AAKvC,cAAc;AACd,eAAO,MAAM,GAAG,EAAE,GAgEjB,CAAC"}
+{"version":3,"file":"highlight_priorities.gen.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/highlight_priorities.gen.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,aAAa,CAAC;AAKrC,cAAc;AACd,eAAO,MAAM,GAAG,EAAE,GAgEjB,CAAC"}

package/dist/svelte_preprocess_fuz_code.d.ts

@@ -1,5 +1,8 @@
 import { type PreprocessorGroup } from 'svelte/compiler';
 import type { SyntaxStyler } from './syntax_styler.js';
+/**
+ * Options for `svelte_preprocess_fuz_code`.
+ */
 export interface PreprocessFuzCodeOptions {
     /** File patterns to exclude. */
     exclude?: Array<string | RegExp>;
@@ -20,5 +23,22 @@ export interface PreprocessFuzCodeOptions {
      */
     on_error?: 'log' | 'throw';
 }
+/**
+ * Svelte preprocessor that compiles static `Code` component content at build time,
+ * replacing runtime syntax highlighting with pre-rendered HTML.
+ *
+ * @param options preprocessor configuration
+ * @returns a Svelte preprocessor group
+ *
+ * @example
+ * ```ts
+ * // svelte.config.js
+ * import {svelte_preprocess_fuz_code} from './svelte_preprocess_fuz_code.js';
+ *
+ * export default {
+ *   preprocess: [svelte_preprocess_fuz_code(), vitePreprocess()],
+ * };
+ * ```
+ */
 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

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

package/dist/svelte_preprocess_fuz_code.js

@@ -5,6 +5,23 @@ import { should_exclude_path } from '@fuzdev/fuz_util/path.js';
 import { escape_js_string } from '@fuzdev/fuz_util/string.js';
 import { find_attribute, extract_static_string, try_extract_conditional_chain, build_static_bindings, resolve_component_names, handle_preprocess_error, } from '@fuzdev/fuz_util/svelte_preprocess_helpers.js';
 import { syntax_styler_global } from './syntax_styler_global.js';
+/**
+ * Svelte preprocessor that compiles static `Code` component content at build time,
+ * replacing runtime syntax highlighting with pre-rendered HTML.
+ *
+ * @param options preprocessor configuration
+ * @returns a Svelte preprocessor group
+ *
+ * @example
+ * ```ts
+ * // svelte.config.js
+ * import {svelte_preprocess_fuz_code} from './svelte_preprocess_fuz_code.js';
+ *
+ * export default {
+ *   preprocess: [svelte_preprocess_fuz_code(), vitePreprocess()],
+ * };
+ * ```
+ */
 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 === 'true' ? 'throw' : 'log', } = options;
     // In-memory cache: content+lang hash → highlighted HTML

package/dist/syntax_styler.d.ts

@@ -46,18 +46,24 @@ export declare class SyntaxStyler {
      * @returns HTML string with syntax highlighting using CSS classes (`.token_*`)
      *
      * @example
+     * ```ts
      * // Standard usage - uses registered grammar
      * stylize('var foo = true;', 'ts');
+     * ```
      *
      * @example
+     * ```ts
      * // Custom grammar - overrides registered grammar
      * const customGrammar = { keyword: [...], string: [...] };
      * stylize('var foo = false;', 'ts', customGrammar);
+     * ```
      *
      * @example
+     * ```ts
      * // Extended grammar - builds on existing grammar
      * const extended = this.extend_grammar('ts', { customToken: [...] });
      * stylize('var foo = 42;', 'ts-extended', extended);
+     * ```
      */
     stylize(text: string, lang: string, grammar?: SyntaxGrammar | undefined): string;
     /**

package/dist/syntax_styler.d.ts.map

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

package/dist/syntax_styler.js

@@ -91,18 +91,24 @@ export class SyntaxStyler {
      * @returns HTML string with syntax highlighting using CSS classes (`.token_*`)
      *
      * @example
+     * ```ts
      * // Standard usage - uses registered grammar
      * stylize('var foo = true;', 'ts');
+     * ```
      *
      * @example
+     * ```ts
      * // Custom grammar - overrides registered grammar
      * const customGrammar = { keyword: [...], string: [...] };
      * stylize('var foo = false;', 'ts', customGrammar);
+     * ```
      *
      * @example
+     * ```ts
      * // Extended grammar - builds on existing grammar
      * const extended = this.extend_grammar('ts', { customToken: [...] });
      * stylize('var foo = 42;', 'ts-extended', extended);
+     * ```
      */
     stylize(text, lang, grammar = this.get_lang(lang)) {
         var ctx = {

package/dist/syntax_styler_global.d.ts

@@ -1,3 +1,13 @@
 import { SyntaxStyler } from './syntax_styler.js';
+/**
+ * Pre-configured `SyntaxStyler` instance with all built-in grammars registered.
+ *
+ * @example
+ * ```ts
+ * import {syntax_styler_global} from './syntax_styler_global.js';
+ *
+ * const html = syntax_styler_global.stylize('const x = 1;', 'ts');
+ * ```
+ */
 export declare const syntax_styler_global: SyntaxStyler;
 //# sourceMappingURL=syntax_styler_global.d.ts.map

package/dist/syntax_styler_global.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"syntax_styler_global.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/syntax_styler_global.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAUhD,eAAO,MAAM,oBAAoB,cAAqB,CAAC"}
+{"version":3,"file":"syntax_styler_global.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/syntax_styler_global.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAWhD;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,cAAqB,CAAC"}

package/dist/syntax_styler_global.js

@@ -6,7 +6,18 @@ import { add_grammar_js } from './grammar_js.js';
 import { add_grammar_ts } from './grammar_ts.js';
 import { add_grammar_svelte } from './grammar_svelte.js';
 import { add_grammar_json } from './grammar_json.js';
+import { add_grammar_bash } from './grammar_bash.js';
 import { add_grammar_markdown } from './grammar_markdown.js';
+/**
+ * Pre-configured `SyntaxStyler` instance with all built-in grammars registered.
+ *
+ * @example
+ * ```ts
+ * import {syntax_styler_global} from './syntax_styler_global.js';
+ *
+ * const html = syntax_styler_global.stylize('const x = 1;', 'ts');
+ * ```
+ */
 export const syntax_styler_global = new SyntaxStyler();
 add_grammar_markup(syntax_styler_global);
 add_grammar_css(syntax_styler_global);
@@ -15,4 +26,5 @@ add_grammar_js(syntax_styler_global);
 add_grammar_ts(syntax_styler_global);
 add_grammar_svelte(syntax_styler_global);
 add_grammar_json(syntax_styler_global);
+add_grammar_bash(syntax_styler_global); // before markdown — markdown references bash for fenced code blocks
 add_grammar_markdown(syntax_styler_global);

package/dist/tokenize_syntax.d.ts

@@ -16,6 +16,7 @@ import { type SyntaxTokenStream } from './syntax_token.js';
  * @returns an array of strings and tokens, a token stream
  *
  * @example
+ * ```ts
  * var code = `var foo = 0;`;
  * var tokens = tokenize_syntax(code, SyntaxStyler.langs.js);
  * for (var token of tokens) {
@@ -23,6 +24,7 @@ import { type SyntaxTokenStream } from './syntax_token.js';
  *         console.log(`Found numeric literal: ${token.content}`);
  *     }
  * }
+ * ```
  */
 export declare const tokenize_syntax: (text: string, grammar: SyntaxGrammar) => SyntaxTokenStream;
 //# sourceMappingURL=tokenize_syntax.d.ts.map

package/dist/tokenize_syntax.d.ts.map

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

package/dist/tokenize_syntax.js

@@ -15,6 +15,7 @@ import { SyntaxToken } from './syntax_token.js';
  * @returns an array of strings and tokens, a token stream
  *
  * @example
+ * ```ts
  * var code = `var foo = 0;`;
  * var tokens = tokenize_syntax(code, SyntaxStyler.langs.js);
  * for (var token of tokens) {
@@ -22,6 +23,7 @@ import { SyntaxToken } from './syntax_token.js';
  *         console.log(`Found numeric literal: ${token.content}`);
  *     }
  * }
+ * ```
  */
 export const tokenize_syntax = (text, grammar) => {
     // Grammar is already normalized (rest merged, patterns in arrays, etc.)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fuzdev/fuz_code",
-  "version": "0.44.1",
-  "description": "syntax styling utilities and components for TypeScript, Svelte, and Markdown",
+  "version": "0.45.1",
+  "description": "syntax styling utilities and components for TypeScript, Svelte, Markdown, and more",
   "glyph": "🎨",
   "logo": "logo.svg",
   "logo_alt": "a friendly pink spider facing you",
@@ -58,15 +58,17 @@
   },
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
-    "@fuzdev/fuz_css": "^0.47.0",
-    "@fuzdev/fuz_ui": "^0.181.1",
-    "@fuzdev/fuz_util": "^0.50.0",
+    "@fuzdev/fuz_css": "^0.50.0",
+    "@fuzdev/fuz_ui": "^0.183.1",
+    "@fuzdev/fuz_util": "^0.51.0",
+    "@fuzdev/gro": "^0.194.0",
+    "@jridgewell/trace-mapping": "^0.3.31",
     "@ryanatkn/eslint-config": "^0.9.0",
-    "@ryanatkn/gro": "^0.191.0",
     "@sveltejs/adapter-static": "^3.0.10",
     "@sveltejs/kit": "^2.50.1",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
+    "@types/estree": "^1.0.8",
     "@types/node": "^24.10.1",
     "@webref/css": "^8.2.0",
     "eslint": "^9.39.1",
@@ -77,11 +79,13 @@
     "prettier-plugin-svelte": "^3.4.1",
     "svelte": "^5.49.1",
     "svelte-check": "^4.3.6",
+    "svelte2tsx": "^0.7.47",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.48.1",
     "vitest": "^4.0.15",
-    "zimmerframe": "^1.1.4"
+    "zimmerframe": "^1.1.4",
+    "zod": "^4.3.6"
   },
   "prettier": {
     "plugins": [

package/src/lib/code_sample.ts

@@ -5,6 +5,6 @@ export interface CodeSample {
 }
 
 // Languages ordered from simple to complex
-export const sample_langs = ['json', 'css', 'ts', 'html', 'svelte', 'md'] as const;
+export const sample_langs = ['json', 'css', 'ts', 'html', 'svelte', 'md', 'bash'] as const;
 
 export type SampleLang = (typeof sample_langs)[number];

package/src/lib/grammar_bash.ts

@@ -0,0 +1,175 @@
+import type {AddSyntaxGrammar, SyntaxGrammarRaw} from './syntax_styler.js';
+
+/**
+ * Bash/shell grammar for syntax highlighting.
+ *
+ * Standalone grammar (no base extension). Covers core bash syntax:
+ * comments, strings, variables, functions, keywords, builtins,
+ * operators, and redirections.
+ *
+ * Based on Prism (https://github.com/PrismJS/prism)
+ * by Lea Verou (https://lea.verou.me/)
+ *
+ * MIT license
+ *
+ * @see LICENSE
+ */
+export const add_grammar_bash: AddSyntaxGrammar = (syntax_styler) => {
+	// Shared inside grammar for command substitution — `rest` wired after construction
+	const command_sub_inside: SyntaxGrammarRaw = {
+		punctuation: /^\$\(|\)$/,
+	};
+
+	// Reusable balanced-paren pattern for $(...) — handles 2 levels of inner () nesting,
+	// which supports up to 3 levels of $() command substitution (4+ is vanishingly rare)
+	const command_sub_pattern = /\$\((?:[^()]*|\((?:[^()]*|\([^()]*\))*\))*\)/;
+
+	const grammar_bash = {
+		// Shebang at file start — matched before general comments
+		shebang: {
+			pattern: /^#!.*/,
+			alias: 'comment',
+		},
+
+		// Line comments — require whitespace or start-of-string before #
+		comment: {
+			pattern: /(^|\s)#.*/,
+			lookbehind: true,
+			greedy: true,
+		},
+
+		// Here-documents — must precede string to avoid delimiter consumption
+		heredoc: [
+			// Quoted delimiter (<<'DELIM' or <<"DELIM") — no expansion
+			{
+				pattern: /(^|[^<])<<-?\s*(?:['"])(\w+)(?:['"])[\t ]*\n[\s\S]*?\n[\t ]*\2(?=\s*$)/m,
+				lookbehind: true,
+				greedy: true,
+				alias: 'string',
+				inside: {
+					// No `m` flag — `^` matches start-of-string (opening) and `$` matches
+					// end-of-string (closing), so single-word content lines can't false-positive
+					heredoc_delimiter: [
+						{
+							pattern: /^<<-?\s*(?:['"])\w+(?:['"])/,
+							alias: 'punctuation',
+						},
+						{
+							pattern: /\w+$/,
+							alias: 'punctuation',
+						},
+					],
+				} as SyntaxGrammarRaw,
+			},
+			// Unquoted delimiter (<<DELIM) — with variable/command expansion
+			{
+				pattern: /(^|[^<])<<-?\s*(\w+)[\t ]*\n[\s\S]*?\n[\t ]*\2(?=\s*$)/m,
+				lookbehind: true,
+				greedy: true,
+				alias: 'string',
+				inside: {
+					heredoc_delimiter: [
+						{
+							pattern: /^<<-?\s*\w+/,
+							alias: 'punctuation',
+						},
+						{
+							pattern: /\w+$/,
+							alias: 'punctuation',
+						},
+					],
+					command_substitution: {
+						pattern: command_sub_pattern,
+						greedy: true,
+						inside: command_sub_inside,
+					},
+					variable: /\$\{[^}]+\}|\$(?:\w+|[!@#$*?\-0-9])/,
+				} as SyntaxGrammarRaw,
+			},
+		],
+
+		// Strings — three variants
+		string: [
+			// Double-quoted: supports escape sequences, variable interpolation, command substitution
+			{
+				pattern:
+					/(^|[^\\](?:\\\\)*)"(?:\\[\s\S]|\$\((?:[^()]*|\((?:[^()]*|\([^()]*\))*\))*\)|\$(?!\()|[^"\\$])*"/,
+				lookbehind: true,
+				greedy: true,
+				inside: {
+					command_substitution: {
+						pattern: command_sub_pattern,
+						greedy: true,
+						inside: command_sub_inside,
+					},
+					variable: /\$\{[^}]+\}|\$(?:\w+|[!@#$*?\-0-9])/,
+				} as SyntaxGrammarRaw,
+			},
+			// Single-quoted: completely literal
+			{
+				pattern: /(^|[^\\](?:\\\\)*)'[^']*'/,
+				lookbehind: true,
+				greedy: true,
+			},
+			// ANSI-C quoting: $'...' with C-style escapes
+			{
+				pattern: /\$'(?:[^'\\]|\\[\s\S])*'/,
+				greedy: true,
+			},
+		],
+
+		// Command substitution $(...) — before variable since both start with $
+		command_substitution: {
+			pattern: command_sub_pattern,
+			greedy: true,
+			inside: command_sub_inside,
+		},
+
+		// Variables and parameter expansion
+		variable: /\$\{[^}]+\}|\$(?:\w+|[!@#$*?\-0-9])/,
+
+		// Function definitions — both styles
+		function: [
+			// function fname style
+			{
+				pattern: /(\bfunction\s+)\w+/,
+				lookbehind: true,
+			},
+			// fname() style
+			{
+				pattern: /\b\w+(?=\s*\(\s*\))/,
+			},
+		],
+
+		// Shell keywords
+		keyword:
+			/\b(?:if|then|else|elif|fi|for|while|until|do|done|case|esac|in|select|function|return|local|export|declare|typeset|readonly|unset|set|shift|trap|break|continue|coproc|time)\b/,
+
+		// Builtin commands
+		builtin:
+			/\b(?:echo|printf|cd|pwd|read|test|source|eval|exec|exit|getopts|hash|type|ulimit|umask|wait|kill|jobs|bg|fg|disown|alias|unalias|command|shopt)\b/,
+
+		// Boolean commands
+		boolean: /\b(?:true|false)\b/,
+
+		// File descriptors before redirections — must precede number
+		file_descriptor: {
+			pattern: /\B&\d\b|\b\d(?=>>?|<)/,
+			alias: 'important',
+		},
+
+		// Numbers: hex, octal, base-N, decimal
+		number: /\b(?:0x[\da-fA-F]+|0[0-7]+|\d+#[\da-zA-Z]+|\d+)\b/,
+
+		// Operators — longest first
+		operator: /\|\||&&|;;|&>>?|<<<?|>>?|=~|[!=]=|[<>]|[|&!]/,
+
+		// Punctuation
+		punctuation: /[{}[\]();,]/,
+	} satisfies SyntaxGrammarRaw;
+
+	// Wire circular reference so command substitutions get full bash highlighting
+	command_sub_inside.rest = grammar_bash;
+
+	syntax_styler.add_lang('bash', grammar_bash, ['sh', 'shell']);
+};

package/src/lib/grammar_markdown.ts

@@ -103,6 +103,7 @@ export const add_grammar_markdown: AddSyntaxGrammar = (syntax_styler) => {
 		{aliases: ['html', 'markup'], id: 'markup'},
 		{aliases: ['json'], id: 'json'},
 		{aliases: ['svelte'], id: 'svelte'},
+		{aliases: ['bash', 'sh', 'shell'], id: 'bash'},
 	];
 
 	// Fence types: higher counts first (for proper precedence in tokenization)

package/src/lib/highlight_manager.ts

@@ -10,8 +10,16 @@ export const supports_css_highlight_api = (): boolean =>
 	!!(globalThis.CSS?.highlights && globalThis.Highlight); // eslint-disable-line @typescript-eslint/no-unnecessary-condition
 
 /**
- * Manages highlights for a single element.
+ * Manages CSS Custom Highlight API ranges for a single element.
  * Tracks ranges per element and only removes its own ranges when clearing.
+ *
+ * **Experimental** — limited browser support. Use `Code` for production.
+ *
+ * @example
+ * ```ts
+ * const manager = new HighlightManager();
+ * manager.highlight_from_syntax_tokens(element, tokens);
+ * ```
  */
 export class HighlightManager {
 	element_ranges: Map<string, Array<Range>>;

package/src/lib/highlight_priorities.gen.ts

@@ -1,4 +1,4 @@
-import type {Gen} from '@ryanatkn/gro';
+import type {Gen} from '@fuzdev/gro';
 import {readFileSync} from 'node:fs';
 
 const theme_css_path = 'src/lib/theme_highlight.css';

package/src/lib/svelte_preprocess_fuz_code.ts

@@ -16,6 +16,9 @@ import {
 import {syntax_styler_global} from './syntax_styler_global.js';
 import type {SyntaxStyler} from './syntax_styler.js';
 
+/**
+ * Options for `svelte_preprocess_fuz_code`.
+ */
 export interface PreprocessFuzCodeOptions {
 	/** File patterns to exclude. */
 	exclude?: Array<string | RegExp>;
@@ -41,6 +44,23 @@ export interface PreprocessFuzCodeOptions {
 	on_error?: 'log' | 'throw';
 }
 
+/**
+ * Svelte preprocessor that compiles static `Code` component content at build time,
+ * replacing runtime syntax highlighting with pre-rendered HTML.
+ *
+ * @param options preprocessor configuration
+ * @returns a Svelte preprocessor group
+ *
+ * @example
+ * ```ts
+ * // svelte.config.js
+ * import {svelte_preprocess_fuz_code} from '@fuzdev/fuz_code/svelte_preprocess_fuz_code.js';
+ *
+ * export default {
+ *   preprocess: [svelte_preprocess_fuz_code(), vitePreprocess()],
+ * };
+ * ```
+ */
 export const svelte_preprocess_fuz_code = (
 	options: PreprocessFuzCodeOptions = {},
 ): PreprocessorGroup => {

package/src/lib/syntax_styler.ts

@@ -104,18 +104,24 @@ export class SyntaxStyler {
 	 * @returns HTML string with syntax highlighting using CSS classes (`.token_*`)
 	 *
 	 * @example
+	 * ```ts
 	 * // Standard usage - uses registered grammar
 	 * stylize('var foo = true;', 'ts');
+	 * ```
 	 *
 	 * @example
+	 * ```ts
 	 * // Custom grammar - overrides registered grammar
 	 * const customGrammar = { keyword: [...], string: [...] };
 	 * stylize('var foo = false;', 'ts', customGrammar);
+	 * ```
 	 *
 	 * @example
+	 * ```ts
 	 * // Extended grammar - builds on existing grammar
 	 * const extended = this.extend_grammar('ts', { customToken: [...] });
 	 * stylize('var foo = 42;', 'ts-extended', extended);
+	 * ```
 	 */
 	stylize(
 		text: string,

package/src/lib/syntax_styler_global.ts

@@ -6,8 +6,19 @@ import {add_grammar_js} from './grammar_js.js';
 import {add_grammar_ts} from './grammar_ts.js';
 import {add_grammar_svelte} from './grammar_svelte.js';
 import {add_grammar_json} from './grammar_json.js';
+import {add_grammar_bash} from './grammar_bash.js';
 import {add_grammar_markdown} from './grammar_markdown.js';
 
+/**
+ * Pre-configured `SyntaxStyler` instance with all built-in grammars registered.
+ *
+ * @example
+ * ```ts
+ * import {syntax_styler_global} from '@fuzdev/fuz_code/syntax_styler_global.js';
+ *
+ * const html = syntax_styler_global.stylize('const x = 1;', 'ts');
+ * ```
+ */
 export const syntax_styler_global = new SyntaxStyler();
 
 add_grammar_markup(syntax_styler_global);
@@ -17,4 +28,5 @@ add_grammar_js(syntax_styler_global);
 add_grammar_ts(syntax_styler_global);
 add_grammar_svelte(syntax_styler_global);
 add_grammar_json(syntax_styler_global);
+add_grammar_bash(syntax_styler_global); // before markdown — markdown references bash for fenced code blocks
 add_grammar_markdown(syntax_styler_global);

package/src/lib/tokenize_syntax.ts

@@ -17,6 +17,7 @@ import {SyntaxToken, type SyntaxTokenStream} from './syntax_token.js';
  * @returns an array of strings and tokens, a token stream
  *
  * @example
+ * ```ts
  * var code = `var foo = 0;`;
  * var tokens = tokenize_syntax(code, SyntaxStyler.langs.js);
  * for (var token of tokens) {
@@ -24,6 +25,7 @@ import {SyntaxToken, type SyntaxTokenStream} from './syntax_token.js';
  *         console.log(`Found numeric literal: ${token.content}`);
  *     }
  * }
+ * ```
  */
 export const tokenize_syntax = (text: string, grammar: SyntaxGrammar): SyntaxTokenStream => {
 	// Grammar is already normalized (rest merged, patterns in arrays, etc.)