# Components

Decodal is split into a small runtime core and separate syntax tooling components.
The public surface is intentionally organized by use case: execute Decodal with Rust or WebAssembly, edit Decodal on the Web with Lezer and CodeMirror, and integrate Decodal into general-purpose editors with Tree-sitter.

## Runtime components

### Rust crate

The `decodal` crate is the primary Rust runtime and embedding API.
It owns parsing, evaluation, materialization, diagnostics, host-provided values, and schema/decode traits.
Rust applications should use this crate when they want to load Decodal source, evaluate it, or embed Decodal into a host program.

Important paths:

```text
crates/decodal-core/
crates/decodal-derive/
```

`decodal-derive` provides optional derive macros for Rust struct integration.
It is a companion to the runtime crate rather than an editor or syntax-highlighting component.

### WebAssembly package

`decodal-wasm` exposes the runtime to browsers.
The documentation site playground uses it to evaluate Decodal entirely in the browser.

Important paths:

```text
crates/decodal-wasm/
site/decodal-site/src/wasm/
```

The generated files in `site/decodal-site/src/wasm/` are committed so the site can build without requiring every consumer to run `wasm-pack` first.
The WebAssembly package is for execution, not syntax highlighting.

## Web editor components

The Web playground editor uses CodeMirror 6 with a generated Lezer parser.
This is the source of syntax highlighting, folding, indentation, and editor syntax tree behavior in the browser UI.

Important paths:

```text
editors/lezer-decodal/decodal.grammar
site/decodal-site/src/lib/codemirror/decodal-parser.js
site/decodal-site/src/lib/codemirror/decodal-parser.terms.js
site/decodal-site/src/lib/codemirror/decodal.js
```

The Lezer grammar is derived from the canonical grammar documentation, but it is not a literal copy of the EBNF.
Precedence and token conflict handling are represented in the Lezer grammar in the form CodeMirror needs.

## General editor components

Tree-sitter is the portable editor-integration grammar.
Editors such as Zed, Neovim, Helix, and Emacs should consume this component when they need Decodal parsing or highlighting outside the Web playground.

Important paths:

```text
editors/tree-sitter-decodal/grammar.js
editors/tree-sitter-decodal/queries/highlights.scm
editors/tree-sitter-decodal/queries/locals.scm
editors/tree-sitter-decodal/src/
```

The generated parser sources under `editors/tree-sitter-decodal/src/` are committed so editor integrations can consume the grammar without regenerating it first.

## Canonical grammar

The human-readable grammar lives in:

```text
doc/manual/souce/language/grammar.md
```

This EBNF is the language-level reference.
The Rust parser, Lezer grammar, and Tree-sitter grammar should be kept aligned with it, but each implementation may encode precedence and recovery behavior in the form required by its parser generator or runtime.

## What is not a public component

The Rust lexer is an implementation detail of the Rust parser.
Decodal does not expose a standalone public tokenizer API for editor tooling.
Consumers that need syntax information should use the component that matches their environment:

- Rust execution and embedding: `decodal`
- Browser execution: `decodal-wasm`
- Web editor syntax: Lezer / CodeMirror
- General editor syntax: Tree-sitter

This avoids having a separate token stream API whose behavior would have to be kept compatible with both runtime parsing and editor grammars.