#AST /ast

import {
  AST_SCHEMA_VERSION,
  SYNTAX_SCHEMA_VERSION,
  RENDER_SCHEMA_VERSION,
  flattenNodes,
  findNodeById,
  findNodeAtOffset,
  getSourceText,
  toPlainText,
  isNodeType,
  getTemplateParameters,
  getFileParameters,
  normalizeSource,
  serializeWikitextDocument,
  restoreWikitextDocument,
} from "react-wikitext/ast";

/ast loads neither the parser nor React. It can be used on servers, in workers, or in data-processing scripts.

#Node basics

interface WikitextNodeBase<TType extends string> {
  readonly type: TType;
  readonly id: string;
  readonly position?: WikitextPosition;
  readonly origin?: WikitextOrigin;
  readonly data?: Readonly<Record<string, unknown>>;
}

• id is unique within a snapshot and is not promised to be stable across edits.
• position is 1-based line/column + 0-based offset; generated nodes omit it.
• origin points at the original syntax node and range.
• data holds extension data.

#Node types

Extension tags without dedicated rendering still use extension nodes that retain the name and inner source; they never become unknown.

Custom nodes require extending WikitextNodeMap and registering a handler during preparation. A node without a handler produces a diagnostic and degrades to a source card.

#Source syntax tree

With retainSyntax: true, the parse snapshot includes syntax:

interface WikitextSyntaxNode {
  id: string; // path id, e.g. "0.0.1"
  type: string; // upstream token type
  range: WikitextRange; // [start, end)
  position: WikitextPosition;
  props: Readonly<Record<string, WikitextPrimitive>>;
  attributes: readonly WikitextSyntaxAttribute[];
  children: readonly WikitextSyntaxNode[];
}

The syntax tree serves the playground, ranges, and source mapping. It does not determine render structure; the semantic AST is the render input.

#Queries

interface SourceDocumentLike {
  readonly source: string;
  readonly ast: WikitextRoot;
}

• Zero-length nodes are excluded from findNodeAtOffset by default; use includeZeroLength to change that.
• getSourceText returns an empty string for generated content without origin.
• To index by id, build a Map from flattenNodes.
• Internal caches for flattenNodes and findNodeById invalidate automatically when preparation renumbers the working tree. Arrays or Maps held by plugins before that are not updated in place.
• Query transformed nodes with the render snapshot; do not use its ids against the original parse snapshot.

#Structured helpers

getTemplateParameters(node): WikitextParameter[]
getFileParameters(file): WikitextFileInfo

getTemplateParameters accepts both template and parserFunction and returns parameter nodes, names, anonymity, and 1-based indexes.

getFileParameters derives:

• name, parameters, caption, captionNodes.
• alt, link, lang, page, className, upright.
• width / height (supports 200, 200px, 200x100px; render-clamped to 1–4096).
• format, alignment, verticalAlignment, border.

The caption prefers explicit caption=, otherwise the unnamed caption. Parameter keys never enter caption text.

#Source normalization

interface NormalizedSource {
  readonly source: string;
  readonly normalized: boolean;
  readonly originalLength: number;
}

const normalized = normalizeSource(raw, maxSourceLength);

• Only CRLF / CR → LF; no other character changes.
• DEFAULT_MAX_SOURCE_LENGTH is 100,000; exceeding it throws WikitextParseError("SOURCE_TOO_LONG").
• All coordinates are based on normalized LF source. The library provides no mapping back to original offsets.

#Serialization

Parse snapshot:

const payload = serializeWikitextDocument(document);
const restored = restoreWikitextDocument(payload);

Render snapshot:

import {
  serializeWikitextRenderDocument,
  restoreWikitextRenderDocument,
} from "react-wikitext/hast";

Restore functions validate schema versions, the source string, the root, meta, headings, diagnostics, the full policy/labels shape, and the fixed node budget. Render snapshots are sanitized and finalized again. The snapshot's policy, labels, and authorizedImages belong to the trusted boundary; re-sanitizing only rebuilds derived structure. Invalid input throws:

• Parse snapshot: WikitextError("INVALID_DOCUMENT").
• Render snapshot: WikitextError("INVALID_DOCUMENT") (same base class as parse snapshots, without a stage field).

#Version constants

A version change means the snapshot shape is incompatible. Include it in cache keys when caching or transferring snapshots across processes.