### Example Syntax Roles

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/syntax-roles.md

Illustrates the hierarchical structure of SyntaxMP roles, showing parent-child relationships.

```text
keyword
keyword.control
keyword.declaration
function
function.builtin
variable.parameter
markup.diff.addition
```

--------------------------------

### Applying Minor Theme Tweaks

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/theming.md

Example of using helper extensions to modify keyword color and remove language-specific styles. Useful for one-off customizations on top of a base theme.

```kotlin
val brand = SyntaxTheme.DefaultDark
    .withRoleStyle(
        role = SyntaxRole.Keyword,
        style = SyntaxStyle(color = Color(0xFF7F52FF), fontWeight = FontWeight.Bold),
    )

// Remove a previously-set language override entirely:
val cleared = brand.withLanguageRoleStyles(languageId = LanguageId.Kotlin, styles = null)
```

--------------------------------

### Bash Keywords and Variables

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/languages.md

Examples of keywords, built-in functions, variables, and escapes in Bash scripting.

```bash
if
```

```bash
echo
```

```bash
grep
```

```bash
$HOME
```

```bash
${
```

```bash
default
```

```bash
"home"
```

```bash
1
```

```bash
-
```

```bash
;

```

```bash
# note
```

--------------------------------

### Creating a SyntaxRoleStyles Map

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/theming.md

Provides an example of creating a `SyntaxRoleStyles` map, which associates `SyntaxRole` objects with their corresponding `SyntaxStyle` definitions. This map is used to apply themes.

```kotlin
val styles: SyntaxRoleStyles = SyntaxRoleStyles(
    SyntaxRole.Keyword to SyntaxStyle(color = Color(0xFF3B73D9), fontWeight = FontWeight.SemiBold),
    SyntaxRole.String to SyntaxStyle(color = Color(0xFF2E7D5B)),
    SyntaxRole.Number to SyntaxStyle(color = Color(0xFFAD3DA4)),
    SyntaxRole.Comment to SyntaxStyle(color = Color(0xFF7A7F87), fontStyle = FontStyle.Italic),
)
```

--------------------------------

### DefaultLight and DefaultDark Themes

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/api.md

Provides pre-configured SyntaxTheme instances for light and dark surfaces. These themes offer basic color styling for common roles and serve as a starting point for customization.

```kotlin
public val DefaultLight: SyntaxTheme
public val DefaultDark: SyntaxTheme
```

--------------------------------

### Documenting Known Gaps in Scanner Behavior

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs-internal/adding-a-built-in-language.md

Example of documenting a known gap in scanner behavior directly within the fixture code. This helps track limitations and plan future improvements.

```kotlin
// KNOWN GAP: Kotlin backtick identifiers are still emitted with the generic
// identifier path. Fixture expectation reflects current behavior.
```

--------------------------------

### Example Stable Case IDs

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs-internal/benchmark-language-fixture-inventory.md

Examples of stable case IDs for different languages and multipliers.

```text
languages/representative/kotlin/1x
```

```text
languages/representative/kotlin/10x
```

```text
languages/representative/markdown-plain/1x
```

```text
languages/representative/markdown-embedded/10x
```

--------------------------------

### 404 Redirection Logic

Source: https://github.com/gallatinapps/syntaxmp/blob/main/syntaxmp-demo/src/wasmJsMain/resources/404.html

This JavaScript code snippet runs immediately to process the URL and redirect the user. It prioritizes a 'path' query parameter, falls back to the current pathname, and ensures the path starts with a '/'. If no valid path is determined, it defaults to '/404'.

```javascript
SyntaxMP (function () { var simulatedPath = new URLSearchParams(window.location.search).get("path"); var actualPath = window.location.pathname === "/404.html" ? "/404" : window.location.pathname + window.location.search; var path = simulatedPath || actualPath; if (!path || path === "/" || path === "/404.html") { path = "/404"; } if (path.charAt(0) !== "/") { path = "/" + path; } var target = "/#" + path; window.location.replace(target); }());
```

--------------------------------

### Constructing Custom Syntax Roles

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/theming.md

Demonstrates how to create custom or refined syntax roles using factory methods. Use these for specific styling needs beyond the predefined roles.

```kotlin
val custom = SyntaxRole.of("custom.myql.directive")
val refined = SyntaxRole.Keyword.append("sql")          // keyword.sql
val markupAddition = SyntaxRole.of("markup.diff.addition")
```

--------------------------------

### rolePathValuesFromRoot

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/api.md

Expands a dotted role path string into a list of its parent role path values, starting from the root.

```APIDOC
## `rolePathValuesFromRoot`

### Description
Returns the root-to-exact dotted role path values for a role string.

### Method
```kotlin
public fun rolePathValuesFromRoot(value: String): List<String>
```

### Parameters
#### Path Parameters
- **value** (String) - Required - Dotted role path value to expand.

### Returns
`List<String>`: parent role values ordered from root to exact.

### See also
- [`SyntaxRole.rolesFromRoot`](#syntaxrole)
- [`SyntaxTheme`](#syntaxtheme)
```

--------------------------------

### Create a SyntaxTheme with Custom Styles

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/theming.md

Instantiate SyntaxTheme with a comprehensive set of global role styles and specific language overrides for Kotlin and a custom 'myql' language.

```kotlin
val theme = SyntaxTheme(
    roleStyles = SyntaxRoleStyles(
        SyntaxRole.Keyword to SyntaxStyle(color = Color(0xFF3B73D9), fontWeight = FontWeight.SemiBold),
        SyntaxRole.Type to SyntaxStyle(color = Color(0xFF6D28D9)),
        SyntaxRole.String to SyntaxStyle(color = Color(0xFF2E7D5B)),
        SyntaxRole.Number to SyntaxStyle(color = Color(0xFFAD3DA4)),
        SyntaxRole.Comment to SyntaxStyle(color = Color(0xFF7A7F87), fontStyle = FontStyle.Italic),
        SyntaxRole.Function to SyntaxStyle(color = Color(0xFF1D4ED8)),
        SyntaxRole.Variable to SyntaxStyle(color = Color(0xFFBE185D)),
        SyntaxRole.Property to SyntaxStyle(color = Color(0xFFBE185D)),
        SyntaxRole.Operator to SyntaxStyle(color = Color(0xFF334155)),
        SyntaxRole.Punctuation to SyntaxStyle(color = Color(0xFF64748B)),
        SyntaxRole.Annotation to SyntaxStyle(color = Color(0xFFA16207)),
        SyntaxRole.Tag to SyntaxStyle(color = Color(0xFF047857)),
        SyntaxRole.Attribute to SyntaxStyle(color = Color(0xFF0E7490)),
        SyntaxRole.Constant to SyntaxStyle(color = Color(0xFFB91C1C)),
        SyntaxRole.Escape to SyntaxStyle(color = Color(0xFF9A3412)),
        SyntaxRole.Markup to SyntaxStyle(color = Color(0xFF475569)),
    ),
    languageOverrides = mapOf(
        LanguageId.Kotlin to SyntaxRoleStyles(
            SyntaxRole.Keyword.Control to SyntaxStyle(fontWeight = FontWeight.Bold),
            SyntaxRole.Variable.Parameter to SyntaxStyle(color = Color(0xFF7DCFFF)),
        ),
        LanguageId.fromString("myql") to SyntaxRoleStyles(
            SyntaxRole.of("custom.myql.directive") to SyntaxStyle(
                color = Color(0xFF9333EA),
                fontWeight = FontWeight.SemiBold,
            ),
        ),
    ),
)
```

--------------------------------

### Get All Built-in Languages

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/api.md

Retrieves the complete set of registered built-in languages. This set is used as the default for `SyntaxTokenizer.builtInLanguages`.

```kotlin
public val BuiltIns: Set<LanguageId>
```

--------------------------------

### SyntaxMP Render Pipeline Layers

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/building-an-editor.md

Illustrates the three layers of SyntaxMP's render pipeline: tokenization, theming, and display. Shows where caching can be applied.

```text
engine.tokenize(code, languageLabel)
  → List<SyntaxTokenSpan>          ← cache here (theme-independent)
      │
      ├─ + theme → buildSyntaxAnnotatedString → AnnotatedString → BasicText
      │   (or rememberSyntaxAnnotatedString from a Composable)
      │
      └─ + theme → buildSyntaxStyledSpans → List<SyntaxStyledSpan>
                                              │
                                              └─ TextFieldBuffer.applySyntaxStyledSpans → BasicTextField
```

--------------------------------

### Get Roles From Root

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/api.md

Returns the chain of roles from the root through this exact role, root-first. Used by SyntaxTheme for style resolution.

```kotlin
public fun rolesFromRoot(): List<SyntaxRole>
```

--------------------------------

### Run Demo Compilation and Tests

Source: https://github.com/gallatinapps/syntaxmp/blob/main/AGENTS.md

Compile and run tests for the demo module, specifically for WasmJs.

```bash
./gradlew :syntaxmp-demo:compileKotlinWasmJs :syntaxmp-demo:wasmJsBrowserTest
```

--------------------------------

### rolePathValuesFromRoot

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/api.md

A utility function to derive role path values starting from a root element, likely used in theme resolution or syntax analysis.

```APIDOC
## rolePathValuesFromRoot

### Description
A utility function to derive role path values starting from a root element, likely used in theme resolution or syntax analysis.
```

--------------------------------

### Run Combined SyntaxMP Benchmarks

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs-internal/performance-benchmarking.md

Execute the main benchmark task for SyntaxMP from the project root. This command initiates a comprehensive set of benchmarks covering various aspects of the SyntaxMP parser.

```bash
./gradlew :syntaxmp-benchmarks:runSyntaxMpBenchmarks
```

--------------------------------

### Define a Basic SyntaxTheme

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/theming.md

Use SyntaxTheme to define global role styles and language-specific overrides. This constructor sets up the theme with default empty styles.

```kotlin
data class SyntaxTheme(
    val roleStyles: SyntaxRoleStyles = SyntaxRoleStyles(),
    val languageOverrides: Map<LanguageId, SyntaxRoleStyles> = emptyMap(),
)
```

--------------------------------

### Tokenizing Embedded Code in Extensions

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/embedded-languages.md

When an extension's tokenizer identifies a child region, it should use `request.tokenizeEmbedded` to process it. Ensure to offset the returned spans relative to the child code's starting position.

```kotlin
val childSpans = request.tokenizeEmbedded(childCode, childLabel).map { span ->
    span.copy(
        start = childStart + span.start,
        endExclusive = childStart + span.endExclusive,
    )
}
```

--------------------------------

### Tokenizing Code for Custom Span Styling

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/theming.md

Example of tokenizing code and applying custom SpanStyles based on token roles and language IDs. Use this when you need to control more than just foreground color, weight, and style, such as background or text decoration.

```kotlin
val tokens: List<SyntaxTokenSpan> = engine.tokenize(code = code, languageLabel = languageLabel)

val annotated = AnnotatedString.Builder(code).apply {
    tokens.forEach {
        val style: SpanStyle = mySpanStyleFor(it.role, it.languageId)
        addStyle(style, it.start, it.endExclusive)
    }
}.toAnnotatedString()
```

--------------------------------

### Create Empty SyntaxRoleStyles

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/api.md

Returns an empty map for SyntaxRoleStyles. This is a more readable alternative to `emptyMap<SyntaxRole, SyntaxStyle>()`.

```kotlin
public fun SyntaxRoleStyles(): SyntaxRoleStyles
```

--------------------------------

### SyntaxMP Modules and Dependencies

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/architecture.md

Illustrates the module structure and dependency direction within the SyntaxMP library. The main 'syntaxmp' module depends on 'syntaxmp-tokenizer'.

```text
com.gallatinapps.syntaxmp:syntaxmp
  └─ api dependency on com.gallatinapps.syntaxmp:syntaxmp-tokenizer
```

--------------------------------

### Defining Syntax Styles

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/theming.md

Shows how to define a `SyntaxStyle` object, which specifies visual properties like color, font weight, and font style for a given syntax role. Fields left at their default contribute no styling.

```kotlin
data class SyntaxStyle(
    val color: Color = Color.Unspecified,
    val fontWeight: FontWeight? = null,
    val fontStyle: FontStyle? = null,
)
```

--------------------------------

### C Language Constructs

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/languages.md

Illustrates C language roles including preprocessor directives, keywords, types, functions, and comments.

```c
#include <stdio.h>
```

```c
struct
```

```c
return
```

```c
int
```

```c
printf
```

```c
score
```

```c
title
```

```c
NOTE_DRAFT
```

```c
NULL
```

```c
%s
```

```c
"ok"
```

```c
0xFF
```

```c
=,+,>
```

```c
;

```

```c
count
```

```c
/* note */
```

--------------------------------

### Representative Language Fixture Structure

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs-internal/performance-benchmarking.md

Illustrates the structure of representative language fixtures used in benchmarking. It shows how headers, repeated bodies with placeholders, and footers are combined to create benchmark inputs.

```text
header + repeat(body with {{index}} replacement) + footer
```

--------------------------------

### Create SyntaxRoleStyles from Pairs

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/api.md

Constructs a SyntaxRoleStyles map from a variable number of SyntaxRole to SyntaxStyle pairs.

```kotlin
public fun SyntaxRoleStyles(vararg styles: Pair<SyntaxRole, SyntaxStyle>): SyntaxRoleStyles
```

```kotlin
SyntaxRoleStyles(
    SyntaxRole.Keyword to SyntaxStyle(color = Color(0xFF9A3412)),
    SyntaxRole.String to SyntaxStyle(color = Color(0xFF15803D)),
)
```

--------------------------------

### Set Environment Variables for Benchmark Metadata

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs-internal/performance-benchmarking.md

Run the SyntaxMP benchmarks while setting specific environment variables to capture detailed local runtime metadata. This ensures benchmark results are compared against a consistent and well-documented local environment.

```bash
SYNTAXMP_BENCHMARK_CPU="Local workstation" \
SYNTAXMP_BENCHMARK_POWER="AC power" \
./gradlew :syntaxmp-benchmarks:runSyntaxMpBenchmarks
```

--------------------------------

### Access Local Syntax Engine at Call Site

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/building-an-editor.md

Read the current value of the `LocalAppSyntaxEngine` CompositionLocal at any composable that requires tokenization services.

```kotlin
val engine = LocalAppSyntaxEngine.current
```

--------------------------------

### Run Tokenizer Library Tests

Source: https://github.com/gallatinapps/syntaxmp/blob/main/AGENTS.md

Execute tests for pure tokenizer library changes, including compilation across multiple platforms.

```bash
./gradlew :syntaxmp-tokenizer:jvmTest \
  :syntaxmp-tokenizer:compileKotlinJvm \
  :syntaxmp-tokenizer:compileAndroidMain \
  :syntaxmp-tokenizer:compileKotlinIosArm64 \
  :syntaxmp-tokenizer:compileKotlinIosSimulatorArm64 \
  :syntaxmp-tokenizer:compileKotlinWasmJs
```

--------------------------------

### SyntaxTokenizer Constructor

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/api.md

Constructs a SyntaxTokenizer instance. This is the main entry point for tokenization and should be created once per app or editor surface.

```APIDOC
## `SyntaxTokenizer` Constructor

### Description
Initializes a SyntaxTokenizer, which acts as the central routing authority for tokenization. It manages built-in languages and custom extensions to process code into normalized token spans.

### Parameters
#### Constructor Parameters
- **builtInLanguages** (`Set<LanguageId>`) - Optional - Defaults to `LanguageId.BuiltIns`. A subset of built-in languages to enable for this tokenizer. Must be a subset of `LanguageId.BuiltIns`.
- **extensions** (`List<LanguageExtension>`) - Optional - Defaults to `emptyList()`. A list of custom language extensions to be used alongside built-in tokenizers. Extensions are checked before built-ins.
```

--------------------------------

### Run Kotlin Hot-Path Profiling

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs-internal/performance-benchmarking.md

Initiate a specific benchmark task focused on profiling Kotlin hot paths using the benchmark-local JFR task. This is useful for in-depth performance analysis of Kotlin-specific code.

```bash
./gradlew :syntaxmp-benchmarks:runKotlinHotPathProfiling
```

--------------------------------

### Kotlin Fixture Template

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs-internal/adding-a-built-in-language.md

A template for creating fixture tests for the Kotlin language, demonstrating how to use `assertTokenAt` and `assertNoTokenAt` for specific token expectations and negative cases.

```kotlin
package com.gallatinapps.syntaxmp.builtins.fixtures.kotlin

import com.gallatinapps.syntaxmp.builtins.fixtures.assertNoTokenAt
import com.gallatinapps.syntaxmp.builtins.fixtures.assertTokenAt
import kotlin.test.Test

class KotlinFixtureTest {

    @Test
    fun `fun keyword is keyword declaration`() = assertTokenAt(
        language = "kotlin",
        code = "fun greet(): String = \"hi\"",
        substring = "fun",
        category = "Keyword",
        scope = "keyword.declaration",
    )

    @Test
    fun `String type is recognized`() = assertTokenAt(
        language = "kotlin",
        code = "fun greet(): String = \"hi\"",
        substring = "String",
        category = "Type",
        scope = "type",
    )

    @Test
    fun `fun inside a string is not a keyword`() = assertNoTokenAt(
        language = "kotlin",
        code = "val message = \"fun stuff\"",
        substring = "fun",
        category = "Keyword",
    )
}
```

--------------------------------

### Add SyntaxMP Dependency (Version Catalog)

Source: https://github.com/gallatinapps/syntaxmp/blob/main/README.md

Add the SyntaxMP version and library to your Gradle version catalog for dependency management.

```toml
[versions]
syntaxmpVersion = "0.3.0"

[libraries]
syntaxmp = { module = "com.gallatinapps.syntaxmp:syntaxmp", version.ref = "syntaxmpVersion" }
```

--------------------------------

### SyntaxMP Pipeline Stages

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/architecture.md

Outlines the six-stage processing pipeline for a code snippet within SyntaxMP, from initial host input to final Compose UI rendering.

```text
host: (code: String, languageLabel: String?)
  │
  ▼
[1] Language resolution                     SyntaxTokenizer.resolveLanguageId
  │      └─ active extension labels + enabled built-in labels
  ▼
[2] Engine routing                          SyntaxTokenizer.tokenize
  │      └─ resolveTokenizer()              extensions → built-ins
  ▼
[3] Per-language tokenizer                  builtins/<lang>/<Lang>Tokenizer
  │      └─ drives a scanner with vocabulary + options
  ▼
[4] Scanner                                 scanners/* or builtins/<lang>/*Scanner
  │      └─ single-pass char state machine; may recurse into embedded languages
  │      → raw List<SyntaxTokenSpan> (possibly overlapping/out-of-order)
  ▼
[5] Span normalization                      spans/TokenSpanNormalizer
  │      → clean List<SyntaxTokenSpan>      (engine.tokenize boundary)
  │
  ▼
[6] Theme + Compose styling                 compose/
         └─ SyntaxTheme.resolveSpanStyle(span) → SpanStyle
         → AnnotatedString  or  List<SyntaxStyledSpan>
```

--------------------------------

### Run Compose Library Tests

Source: https://github.com/gallatinapps/syntaxmp/blob/main/AGENTS.md

Execute tests for Compose library changes, including compilation across multiple platforms.

```bash
./gradlew :syntaxmp:jvmTest \
  :syntaxmp:compileKotlinJvm \
  :syntaxmp:compileAndroidMain \
  :syntaxmp:compileKotlinIosArm64 \
  :syntaxmp:compileKotlinIosSimulatorArm64 \
  :syntaxmp:compileKotlinWasmJs
```

--------------------------------

### Compile Benchmark Harness

Source: https://github.com/gallatinapps/syntaxmp/blob/main/AGENTS.md

Perform compile checks for the benchmark harness.

```bash
./gradlew :syntaxmp-benchmarks:compileKotlinJvm
```

--------------------------------

### Add SyntaxMP Dependency (build.gradle.kts)

Source: https://github.com/gallatinapps/syntaxmp/blob/main/README.md

Include the SyntaxMP library in your common main source set dependencies within your Gradle build script.

```kotlin
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.syntaxmp)
        }
    }
}
```

--------------------------------

### withRoleStyle Helper Function

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/api.md

Creates a new SyntaxTheme with an updated global role style. This function is non-destructive and preserves existing language overrides.

```kotlin
public fun SyntaxTheme.withRoleStyle(role: SyntaxRole, style: SyntaxStyle): SyntaxTheme
```

--------------------------------

### SyntaxRole Constants

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/theming.md

Illustrates the hierarchical structure of predefined syntax roles in SyntaxMP. These roles are used to categorize different parts of code for styling.

```kotlin
SyntaxRole.Keyword                  // root role
SyntaxRole.Keyword.Control          // child refinement
SyntaxRole.Keyword.Declaration
SyntaxRole.String
SyntaxRole.String.Regex
SyntaxRole.Function
SyntaxRole.Function.Builtin
SyntaxRole.Variable
SyntaxRole.Variable.Parameter
SyntaxRole.Constant
SyntaxRole.Constant.Builtin
SyntaxRole.Markup
SyntaxRole.Markup.Expression
// …and roots for Number, Comment, Type, Property, Operator,
// Punctuation, Annotation, Tag, Attribute, Escape.
```

--------------------------------

### Full Web/Demo Validation Pass

Source: https://github.com/gallatinapps/syntaxmp/blob/main/AGENTS.md

Perform a comprehensive validation pass including tokenizer, compose, demo, and benchmarks.

```bash
./gradlew :syntaxmp-tokenizer:jvmTest \
  :syntaxmp-tokenizer:compileKotlinJvm \
  :syntaxmp-tokenizer:compileAndroidMain \
  :syntaxmp-tokenizer:compileKotlinIosArm64 \
  :syntaxmp-tokenizer:compileKotlinIosSimulatorArm64 \
  :syntaxmp-tokenizer:compileKotlinWasmJs \
  :syntaxmp:jvmTest \
  :syntaxmp:compileKotlinJvm \
  :syntaxmp:compileAndroidMain \
  :syntaxmp:compileKotlinIosArm64 \
  :syntaxmp:compileKotlinIosSimulatorArm64 \
  :syntaxmp:compileKotlinWasmJs \
  :syntaxmp-demo:compileKotlinWasmJs \
  :syntaxmp-demo:wasmJsBrowserDistribution \
  :syntaxmp-benchmarks:compileKotlinJvm
```

--------------------------------

### Remember Syntax Engine for a Single Surface

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/building-an-editor.md

If only one composable needs the syntax engine, use `remember` to construct it. Key the `remember` block on dynamic inputs like `extensions` to ensure the engine is recreated only when necessary.

```kotlin
val engine = remember(extensions) {
    SyntaxTokenizer(extensions = extensions)
}
```

--------------------------------

### SyntaxStyle Data Class

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/api.md

Defines a single role's foreground styling contribution with optional color, font weight, and font style. Unspecified fields do not override existing styles.

```kotlin
public data class SyntaxStyle(
    val color: Color = Color.Unspecified,
    val fontWeight: FontWeight? = null,
    val fontStyle: FontStyle? = null,
) {
    public fun toSpanStyle(): SpanStyle
}
```

--------------------------------

### Define Custom Syntax Role

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/syntax-roles.md

Use `SyntaxRole.of` to create an exact custom role with an arbitrary dotted path.

```kotlin
SyntaxRole.of("custom.myql.directive")
```

--------------------------------

### Applying Language-Specific Theme Overrides

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/embedded-languages.md

Demonstrates how to apply a theme override for a specific embedded language (CSS) within a larger context (HTML). This ensures that styling for the embedded language is correctly applied.

```kotlin
val theme = SyntaxTheme.DefaultDark
    .withLanguageRoleStyles(
        languageId = LanguageId.Css,
        styles = SyntaxRoleStyles(
            SyntaxRole.Property to SyntaxStyle(color = Color(0xFFFF79C6))
        )
    )

BasicText(
    text = rememberSyntaxAnnotatedString(
        code = htmlSource,
        languageLabel = "html",
        engine = engine,
        theme = theme
    )
)
// The CSS override fires for spans inside <style> bodies even though
// the top-level language is HTML.
```

--------------------------------

### withLanguageRoleStyles Helper Function

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/api.md

Creates a new SyntaxTheme by replacing or setting the entire SyntaxRoleStyles map for a specific language. This function is non-destructive.

```kotlin
public fun SyntaxTheme.withLanguageRoleStyles(
    languageId: LanguageId,
    styles: SyntaxRoleStyles?,
): SyntaxTheme
```

--------------------------------

### HTML Script with TypeScript

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/embedded-languages.md

Demonstrates how an HTML <script> tag with lang="ts" is tokenized as TypeScript.

```html
<script setup lang="ts">
  // tokenized as TypeScript
  const message: string = "hello"
</script>
```

--------------------------------

### Validate SyntaxMP Tokenizer

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs-internal/shared-scanner-coverage-matrix.md

Runs Gradle tasks to validate the tokenizer for JVM and Kotlin compilation.

```bash
./gradlew :syntaxmp-tokenizer:jvmTest :syntaxmp-tokenizer:compileKotlinJvm

```

--------------------------------

### withLanguageRoleStyle Helper Function

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/api.md

Creates a new SyntaxTheme with an updated style for a specific role within a given language's overrides. If the language override map doesn't exist, it will be created.

```kotlin
public fun SyntaxTheme.withLanguageRoleStyle(
    languageId: LanguageId,
    role: SyntaxRole,
    style: SyntaxStyle,
): SyntaxTheme
```

--------------------------------

### Helper Extensions for Theme Tweaking

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/theming.md

Use these Kotlin extension functions to create a new SyntaxTheme with one or two specific style changes applied to an existing theme. They are efficient for minor adjustments.

```kotlin
fun SyntaxTheme.withRoleStyle(role: SyntaxRole, style: SyntaxStyle): SyntaxTheme
fun SyntaxTheme.withLanguageRoleStyle(languageId: LanguageId, role: SyntaxRole, style: SyntaxStyle): SyntaxTheme
fun SyntaxTheme.withLanguageRoleStyles(languageId: LanguageId, styles: SyntaxRoleStyles?): SyntaxTheme
fun SyntaxRoleStyles.withRoleStyle(role: SyntaxRole, style: SyntaxStyle): SyntaxRoleStyles
```

--------------------------------

### Define and Provide Local Syntax Engine

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs/building-an-editor.md

Use `staticCompositionLocalOf` to create a CompositionLocal for the SyntaxTokenizer. This is suitable when many surfaces need access to the same immutable engine. The engine is constructed once near the app's root and provided via `CompositionLocalProvider`.

```kotlin
val LocalAppSyntaxEngine = staticCompositionLocalOf<SyntaxTokenizer> {
    error("LocalAppSyntaxEngine not provided")
}

@Composable
fun AppSyntaxProvider(
    extensions: List<LanguageExtension> = emptyList(),
    content: @Composable () -> Unit,
) {
    val engine = remember(extensions) {
        SyntaxTokenizer(extensions = extensions)
    }

    CompositionLocalProvider(LocalAppSyntaxEngine provides engine) {
        content()
    }
}
```

--------------------------------

### Aggregate Historical Benchmark Runs

Source: https://github.com/gallatinapps/syntaxmp/blob/main/docs-internal/performance-benchmarking.md

Use this command to summarize repeated historical runs without re-executing benchmarks. Pass at least three historical run directories or metadata.json files as a comma-separated list.

```bash
./gradlew \
  -Dsyntaxmp.benchmark.aggregateRuns=<run-a>,<run-b>,<run-c> \
  :syntaxmp-benchmarks:aggregateSyntaxMpBenchmarkRuns
```