HTX Guide · 1.5.0-alpha.2

Source locations

AST loc fields, UTF-8 offsets, and diagnostic positions.

HTX 1.5.0-alpha.2 (reference implementation 0.3.0-alpha.3) — Features below are available in the htx CLI unless noted as browser-only.

Status: Shipped — AST loc on all nodes; LSP and CLI diagnostics use UTF-8 byte offsets

Purpose

AST nodes carry loc for:

  • Parse error messages (line 12, column 4: unmatched ::)
  • Editor go-to-definition and hover
  • Streaming renderer mapping DOM nodes back to source
  • Formatter preserving comments (future)

Schema

interface SourceLocation {
  start: { line: number; column: number; offset: number };
  end: { line: number; column: number; offset: number };
}
Field Encoding
line 1-based line number
column 1-based Unicode scalar value (code point) from line start
offset 0-based UTF-8 byte index from document start

See ADR-010.

Example

{
  "type": "block_directive",
  "tag": "card",
  "argument": "Metrics",
  "loc": {
    "start": { "line": 3, "column": 1, "offset": 42 },
    "end": { "line": 5, "column": 4, "offset": 89 }
  },
  "children": []
}

Diagnostics

Conformance fixtures use the flat JSON shape from the specification. CLI output SHOULD use full loc objects per §5.2.

{
  "code": "HTX001",
  "severity": "error",
  "message": "Unmatched block close ::",
  "line": 8,
  "column": 1
}

JavaScript interop

@htx/core may expose helpers to map UTF-8 byte offsets to UTF-16 code unit indices for string indexing. The canonical AST contract remains UTF-8 bytes.

Error recovery

Incomplete blocks at EOF attach diagnostic HTX002 with loc at the open token. Streaming mode (--streaming) auto-closes with HTX002W spanning the inferred close.

Prior art

  • Tree-sitter node byte ranges
  • miette-style error reporting (Rust ecosystem)
  • unified position on mdast nodes (different offset model)