# Core API

# Core API

`@tanstack/highlight/core` contains the engine and renderers. It does not import a language or theme.

## Language registration

### `LanguageDefinition`

```ts
type LanguageDefinition<Name extends string = string> = {
  aliases?: ReadonlyArray<string>
  name: Name
  tokenize: (
    code: string,
    context: TokenizerContext,
  ) => ReadonlyArray<TokenRange>
}
```

A language registration. The tokenizer returns semantic ranges in the original source.

### `TokenRange`

```ts
type TokenRange = {
  className: HighlightTokenClass
  start: number
  end: number
}
```

`start` is inclusive and `end` is exclusive. Both are zero-based UTF-16 string offsets. The highlighter clamps integer offsets to the source bounds, sorts ranges, and skips overlaps. Non-integer offsets are ignored.

### `TokenizerContext`

```ts
type TokenizerContext = {
  hasLanguage: (lang: string) => boolean
  tokenize: (code: string, lang: string) => Array<TokenRange>
}
```

Passed to language tokenizers for opt-in embedded-language delegation. The initial call has depth zero; delegated calls beyond depth 24 return no token ranges.

### `defineLanguage`

```ts
function defineLanguage<const Name extends string>(
  definition: LanguageDefinition<Name>,
): LanguageDefinition<Name>
```

An identity helper that preserves the literal language name and validates the definition with TypeScript.

### `createHighlighter`

```ts
function createHighlighter(options: {
  fallbackLanguage?: string
  languages: ReadonlyArray<LanguageDefinition>
}): Highlighter
```

Builds a highlighter with name and alias maps from the supplied registrations. There is no method for adding registrations later. The returned object and language definitions are not frozen; keep shared definitions unchanged.

The default fallback name is `plaintext`. Unknown language names resolve to the configured fallback and use its tokenizer if registered. An unregistered fallback produces escaped plain text under that fallback name.

Duplicate canonical names or aliases use the last registration encountered.

## Highlighter

### `Highlighter`

```ts
type Highlighter = {
  highlight(code: string, options?: HighlightOptions): HighlightResult
  highlightToHtml(code: string, options?: HighlightOptions): string
  listLanguages(): Array<string>
  normalizeLanguage(lang?: string): string
  renderCodeBlockData(options: RenderCodeBlockOptions & { code: string }): RenderedCodeBlockData
  tokenize(code: string, options?: HighlightOptions): HighlightTokenResult
}
```

`listLanguages` returns canonical names, not aliases. `normalizeLanguage` returns a canonical name when registered and the configured fallback otherwise.

### `HighlightOptions`

| Field | Type | Meaning |
| --- | --- | --- |
| `lang` | `string` | Registered name or alias |
| `lineNumbers` | `boolean` | Wrap each line and emit line-number hooks |
| `decorations` | `ReadonlyArray<HighlightDecoration>` | Line or character-range annotations |

### `RenderCodeBlockOptions`

`HighlightOptions` plus an optional `title`.

### `HighlightTokenResult`

```ts
type HighlightTokenResult = {
  code: string
  lang: string
  tokens: Array<HighlightToken>
}
```

### `HighlightResult`

`HighlightTokenResult` plus `html`, a complete escaped `<pre><code>` string.

### `RenderedCodeBlockData`

```ts
type RenderedCodeBlockData = {
  copyText: string
  htmlMarkup: string
  lang: string
  title?: string
  tokens: Array<HighlightToken>
}
```

`renderCodeBlockData` applies `code.trimEnd()` before generating `copyText`, `htmlMarkup`, and `tokens`. It preserves the supplied `title` and normalizes `lang`.

## Tokens

### `HighlightTokenClass`

The semantic class union: `attr`, `code-inline`, `command`, `comment`, `deleted`, `function`, `heading`, `inserted`, `keyword`, `link`, `literal`, `meta`, `number`, `operator`, `property`, `selector`, `string`, `tag`, `type`, and `variable`.

### `HighlightToken`

```ts
type HighlightToken = {
  className?: HighlightTokenClass
  value: string
}
```

Untyped source segments omit `className`. Concatenating every `value` reconstructs the string passed to tokenization. For block-data and fence helpers, that string has already had trailing whitespace removed.

## Decorations

### `HighlightDecorationData`

`Record<string, boolean | number | string>`. Keys become escaped `data-*` attributes on rendered spans.

### `HighlightRangeDecoration`

```ts
type HighlightRangeDecoration = {
  range: readonly [start: number, end: number]
  className?: string
  data?: HighlightDecorationData
}
```

The range uses zero-based, end-exclusive UTF-16 offsets. Both offsets must be integers with `start < end`; otherwise the decoration is ignored. Ranges extending outside the source are clipped to its bounds.

### `HighlightLineDecoration`

```ts
type HighlightLineDecoration = {
  lines: number | readonly [start: number, end: number]
  className?: string
  data?: HighlightDecorationData
}
```

Lines are one-based and an interval includes both ends.

### `HighlightDecoration`

The union of `HighlightLineDecoration` and `HighlightRangeDecoration`. A decoration cannot contain both `lines` and `range`.

## Render tree

### `HighlightTextNode`

```ts
type HighlightTextNode = { type: 'text'; value: string }
```

### `HighlightElementNode`

```ts
type HighlightElementNode = {
  type: 'element'
  classNames: Array<string>
  data?: Record<string, string>
  children: Array<HighlightRenderNode>
}
```

### `HighlightRenderNode`

The union of `HighlightTextNode` and `HighlightElementNode`.

### `renderTokens`

```ts
function renderTokens(
  tokens: ReadonlyArray<HighlightToken>,
  options?: Pick<HighlightOptions, 'decorations' | 'lineNumbers'>,
): Array<HighlightRenderNode>
```

Converts flat tokens to the renderer-neutral tree. It adds `th-*` token spans, decoration spans, and `th-line` wrappers when line numbers or line decorations require them.

### `renderNodesToHtml`

```ts
function renderNodesToHtml(nodes: ReadonlyArray<HighlightRenderNode>): string
```

Serializes render nodes to escaped HTML.

### `escapeHtml`

```ts
function escapeHtml(value: string): string
```

Escapes `&`, `<`, `>`, double quotes, and single quotes for HTML text output.