@fuzdev/fuz_code 0.45.0 → 0.46.0

package/dist/syntax_styler.d.ts

@@ -34,15 +34,14 @@ export declare class SyntaxStyler {
      * - Custom grammar: `stylize(code, 'ts', customGrammar)` - uses custom grammar but keeps 'ts' label
      * - Extended grammar: `stylize(code, 'custom', this.extend_grammar('ts', extension))` - new language variant
      *
-     * @param text - The source code to syntax highlight.
-     * @param lang - Language identifier (e.g., 'ts', 'css', 'html'). Used for:
-     *   - Grammar lookup when `grammar` is undefined
-     *   - Hook context (`lang` field passed to hooks)
-     *   - Language identification in output
-     * @param grammar - Optional custom grammar object. When undefined, automatically
-     *   looks up the grammar via `this.get_lang(lang)`. Provide this to use a custom
-     *   or modified grammar instead of the registered one.
-     *
+     * @param text - the source code to syntax highlight
+     * @param lang - language identifier (e.g., 'ts', 'css', 'html'), used for:
+     *   - grammar lookup when `grammar` is undefined
+     *   - hook context (`lang` field passed to hooks)
+     *   - language identification in output
+     * @param grammar - optional custom `SyntaxGrammar` object; when undefined, automatically
+     *   looks up the grammar via `this.get_lang(lang)`; provide this to use a custom
+     *   or modified grammar instead of the registered one
      * @returns HTML string with syntax highlighting using CSS classes (`.token_*`)
      *
      * @example
@@ -83,7 +82,7 @@ export declare class SyntaxStyler {
      * };
      * ```
      *
-     * then the `style` token will be added (and processed) at the end. `insert_before` allows you to insert tokens
+     * then the `style` token will be added (and processed) at the end. `grammar_insert_before` allows you to insert tokens
      * before existing tokens. For the CSS example above, you would use it like this:
      *
      * ```js
@@ -110,12 +109,12 @@ export declare class SyntaxStyler {
      *
      * ## Limitations
      *
-     * The main problem `insert_before` has to solve is iteration order. Since ES2015, the iteration order for object
+     * The main problem `grammar_insert_before` has to solve is iteration order. Since ES2015, the iteration order for object
      * properties is guaranteed to be the insertion order (except for integer keys) but some browsers behave
-     * differently when keys are deleted and re-inserted. So `insert_before` can't be implemented by temporarily
+     * differently when keys are deleted and re-inserted. So `grammar_insert_before` can't be implemented by temporarily
      * deleting properties which is necessary to insert at arbitrary positions.
      *
-     * To solve this problem, `insert_before` doesn't actually insert the given tokens into the target object.
+     * To solve this problem, `grammar_insert_before` doesn't actually insert the given tokens into the target object.
      * Instead, it will create a new object and replace all references to the target object with the new one. This
      * can be done without temporarily deleting properties, so the iteration order is well-defined.
      *
@@ -130,16 +129,13 @@ export declare class SyntaxStyler {
      * assert(newMarkup === syntax_styler.get_lang('markup'));
      * ```
      *
-     * @param inside - The property of `root` (e.g. a language id in `syntax_styler.langs`) that contains the
-     * object to be modified.
-     * @param before - The key to insert before.
-     * @param insert - An object containing the key-value pairs to be inserted.
-     * @param root - The object containing `inside`, i.e. the object that contains the
-     * object to be modified.
-     *
-     * Defaults to `syntax_styler.langs`.
-     *
-     * @returns the new grammar object
+     * @param inside - the property of `root` (e.g. a language id in `syntax_styler.langs`) that contains the
+     * object to be modified
+     * @param before - the key to insert before
+     * @param insert - an object containing the key-value pairs to be inserted
+     * @param root - the object containing `inside`, i.e. the object that contains the
+     * object to be modified; defaults to `syntax_styler.langs`
+     * @returns the new `SyntaxGrammar` object
      */
     grammar_insert_before(inside: string, before: string, insert: SyntaxGrammarRaw, root?: Record<string, any>): SyntaxGrammar;
     /**
@@ -147,9 +143,9 @@ export declare class SyntaxStyler {
      *
      * Runs the `wrap` hook on each `SyntaxToken`.
      *
-     * @param o - The token or token stream to be converted.
-     * @param lang - The name of current language.
-     * @returns The HTML representation of the token or token stream.
+     * @param o - the token or `SyntaxTokenStream` to be converted
+     * @param lang - the name of current language
+     * @returns HTML representation of the token or token stream
      */
     stringify_token(o: string | SyntaxToken | SyntaxTokenStream, lang: string): string;
     /**
@@ -167,9 +163,9 @@ export declare class SyntaxStyler {
      * Therefore, it is encouraged to order overwriting tokens according to the positions of the overwritten tokens.
      * Furthermore, all non-overwriting tokens should be placed after the overwriting ones.
      *
-     * @param base_id - The id of the language to extend. This has to be a key in `syntax_styler.langs`.
-     * @param extension - The new tokens to append.
-     * @returns the new grammar
+     * @param base_id - the id of the language to extend, must be a key in `syntax_styler.langs`
+     * @param extension - the new tokens to append
+     * @returns the new `SyntaxGrammar`
      */
     extend_grammar(base_id: string, extension: SyntaxGrammarRaw): SyntaxGrammar;
     plugins: Record<string, any>;
@@ -221,13 +217,13 @@ export interface SyntaxGrammarTokenRaw {
      */
     alias?: string | Array<string>;
     /**
-     * The nested grammar of this token.
+     * The nested `SyntaxGrammarRaw` of this token.
      */
     inside?: SyntaxGrammarRaw | null;
 }
 /**
  * Grammar token with all properties required.
- * This is the normalized representation used at runtime.
+ * This is the normalized representation of `SyntaxGrammarTokenRaw` used at runtime.
  */
 export interface SyntaxGrammarToken {
     pattern: RegExp;
@@ -238,7 +234,7 @@ export interface SyntaxGrammarToken {
 }
 /**
  * A grammar after normalization.
- * All values are arrays of normalized tokens with consistent shapes.
+ * All values are arrays of normalized `SyntaxGrammarToken` with consistent shapes.
  */
 export type SyntaxGrammar = Record<string, Array<SyntaxGrammarToken>>;
 export type HookBeforeTokenizeCallback = (ctx: HookBeforeTokenizeCallbackContext) => void;

package/dist/syntax_styler.d.ts.map

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

package/dist/syntax_styler.js

@@ -79,15 +79,14 @@ export class SyntaxStyler {
      * - Custom grammar: `stylize(code, 'ts', customGrammar)` - uses custom grammar but keeps 'ts' label
      * - Extended grammar: `stylize(code, 'custom', this.extend_grammar('ts', extension))` - new language variant
      *
-     * @param text - The source code to syntax highlight.
-     * @param lang - Language identifier (e.g., 'ts', 'css', 'html'). Used for:
-     *   - Grammar lookup when `grammar` is undefined
-     *   - Hook context (`lang` field passed to hooks)
-     *   - Language identification in output
-     * @param grammar - Optional custom grammar object. When undefined, automatically
-     *   looks up the grammar via `this.get_lang(lang)`. Provide this to use a custom
-     *   or modified grammar instead of the registered one.
-     *
+     * @param text - the source code to syntax highlight
+     * @param lang - language identifier (e.g., 'ts', 'css', 'html'), used for:
+     *   - grammar lookup when `grammar` is undefined
+     *   - hook context (`lang` field passed to hooks)
+     *   - language identification in output
+     * @param grammar - optional custom `SyntaxGrammar` object; when undefined, automatically
+     *   looks up the grammar via `this.get_lang(lang)`; provide this to use a custom
+     *   or modified grammar instead of the registered one
      * @returns HTML string with syntax highlighting using CSS classes (`.token_*`)
      *
      * @example
@@ -140,7 +139,7 @@ export class SyntaxStyler {
      * };
      * ```
      *
-     * then the `style` token will be added (and processed) at the end. `insert_before` allows you to insert tokens
+     * then the `style` token will be added (and processed) at the end. `grammar_insert_before` allows you to insert tokens
      * before existing tokens. For the CSS example above, you would use it like this:
      *
      * ```js
@@ -167,12 +166,12 @@ export class SyntaxStyler {
      *
      * ## Limitations
      *
-     * The main problem `insert_before` has to solve is iteration order. Since ES2015, the iteration order for object
+     * The main problem `grammar_insert_before` has to solve is iteration order. Since ES2015, the iteration order for object
      * properties is guaranteed to be the insertion order (except for integer keys) but some browsers behave
-     * differently when keys are deleted and re-inserted. So `insert_before` can't be implemented by temporarily
+     * differently when keys are deleted and re-inserted. So `grammar_insert_before` can't be implemented by temporarily
      * deleting properties which is necessary to insert at arbitrary positions.
      *
-     * To solve this problem, `insert_before` doesn't actually insert the given tokens into the target object.
+     * To solve this problem, `grammar_insert_before` doesn't actually insert the given tokens into the target object.
      * Instead, it will create a new object and replace all references to the target object with the new one. This
      * can be done without temporarily deleting properties, so the iteration order is well-defined.
      *
@@ -187,16 +186,13 @@ export class SyntaxStyler {
      * assert(newMarkup === syntax_styler.get_lang('markup'));
      * ```
      *
-     * @param inside - The property of `root` (e.g. a language id in `syntax_styler.langs`) that contains the
-     * object to be modified.
-     * @param before - The key to insert before.
-     * @param insert - An object containing the key-value pairs to be inserted.
-     * @param root - The object containing `inside`, i.e. the object that contains the
-     * object to be modified.
-     *
-     * Defaults to `syntax_styler.langs`.
-     *
-     * @returns the new grammar object
+     * @param inside - the property of `root` (e.g. a language id in `syntax_styler.langs`) that contains the
+     * object to be modified
+     * @param before - the key to insert before
+     * @param insert - an object containing the key-value pairs to be inserted
+     * @param root - the object containing `inside`, i.e. the object that contains the
+     * object to be modified; defaults to `syntax_styler.langs`
+     * @returns the new `SyntaxGrammar` object
      */
     grammar_insert_before(inside, before, insert, root = this.langs) {
         var grammar = root[inside];
@@ -231,9 +227,9 @@ export class SyntaxStyler {
      *
      * Runs the `wrap` hook on each `SyntaxToken`.
      *
-     * @param o - The token or token stream to be converted.
-     * @param lang - The name of current language.
-     * @returns The HTML representation of the token or token stream.
+     * @param o - the token or `SyntaxTokenStream` to be converted
+     * @param lang - the name of current language
+     * @returns HTML representation of the token or token stream
      */
     stringify_token(o, lang) {
         if (typeof o === 'string') {
@@ -294,9 +290,9 @@ export class SyntaxStyler {
      * Therefore, it is encouraged to order overwriting tokens according to the positions of the overwritten tokens.
      * Furthermore, all non-overwriting tokens should be placed after the overwriting ones.
      *
-     * @param base_id - The id of the language to extend. This has to be a key in `syntax_styler.langs`.
-     * @param extension - The new tokens to append.
-     * @returns the new grammar
+     * @param base_id - the id of the language to extend, must be a key in `syntax_styler.langs`
+     * @param extension - the new tokens to append
+     * @returns the new `SyntaxGrammar`
      */
     extend_grammar(base_id, extension) {
         // Merge normalized base with un-normalized extension
@@ -307,7 +303,7 @@ export class SyntaxStyler {
         return extended;
     }
     /**
-     * Normalize a single pattern to have consistent shape.
+     * Normalizes a single pattern to have consistent shape.
      * This ensures all patterns have the same object shape for V8 optimization.
      */
     #normalize_pattern(pattern, visited) {
@@ -339,15 +335,15 @@ export class SyntaxStyler {
         };
     }
     /**
-     * Normalize a grammar to have consistent object shapes.
+     * Normalizes a grammar to have consistent object shapes.
      * This performs several optimizations:
-     * 1. Merges `rest` property into main grammar
-     * 2. Ensures all pattern values are arrays
-     * 3. Normalizes all pattern objects to have consistent shapes
-     * 4. Adds global flag to greedy patterns
+     * 1. Merges `rest` property into main grammar.
+     * 2. Ensures all pattern values are arrays.
+     * 3. Normalizes all pattern objects to have consistent shapes.
+     * 4. Adds global flag to greedy patterns.
      *
      * This is called once at registration time to avoid runtime overhead.
-     * @param visited - Set of grammar object IDs already normalized (for circular references)
+     * @param visited - set of grammar object IDs already normalized (for circular references)
      */
     #normalize_grammar(grammar, visited) {
         // Check if we've already normalized this grammar (circular reference)

package/dist/syntax_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;;;;;;;;;GASG;AACH,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,6 +6,7 @@ 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.
@@ -25,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/syntax_token.d.ts

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

package/dist/syntax_token.js

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

package/dist/tokenize_syntax.d.ts

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

package/dist/tokenize_syntax.d.ts.map

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

package/dist/tokenize_syntax.js

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

package/package.json

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

package/src/lib/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']);
+};