@wdprlib/ast 1.1.0 → 1.1.1

package/dist/index.d.cts

@@ -1,124 +1,283 @@
 /**
-* Source code position
+* Source position tracking for Wikidot markup.
+*
+* Every token produced by the parser can carry a {@link Position} that maps it
+* back to its original location in the source text. This is used for error
+* reporting, source-map generation, and editor integration.
+*
+* Both {@link Point} and {@link Position} follow the
+* [unist Position](https://github.com/syntax-tree/unist#position) convention:
+* lines and columns are **1-based**, offsets are **0-based**.
+*
+* @module
+*/
+/**
+* A single point in the source text.
+*
+* Represents one end (start or end) of a {@link Position} range.
+* Line and column are 1-based to match text-editor conventions;
+* offset is 0-based for direct use with `String.prototype.slice()`.
+*
+* @group Source Position
 */
 interface Point {
-	/** Line number (1-based) */
+	/** Line number in the source text (1-based: the first line is line 1) */
 	line: number;
-	/** Column number (1-based) */
+	/** Column number within the line (1-based: the first character is column 1) */
 	column: number;
-	/** Offset (0-based) */
+	/** Character offset from the beginning of the source string (0-based) */
 	offset: number;
 }
 /**
-* Source code range
+* A contiguous range in the source text, defined by a start and end {@link Point}.
+*
+* The range is inclusive of `start` and exclusive of `end` — i.e., the
+* character at `end.offset` is **not** part of the range.
+*
+* @group Source Position
 */
 interface Position {
+	/** The first character of the range */
 	start: Point;
+	/** One past the last character of the range */
 	end: Point;
 }
 /**
-* Helper to create a Point
+* Create a {@link Point} value.
+*
+* @param line - 1-based line number
+* @param column - 1-based column number
+* @param offset - 0-based character offset
+* @returns A frozen {@link Point} object
+*
+* @group Source Position
 */
 declare function createPoint(line: number, column: number, offset: number): Point;
 /**
-* Helper to create a Position
+* Create a {@link Position} range from two {@link Point}s.
+*
+* @param start - Beginning of the range (inclusive)
+* @param end - End of the range (exclusive)
+* @returns A {@link Position} spanning `start..end`
+*
+* @group Source Position
 */
 declare function createPosition(start: Point, end: Point): Position;
 /**
-* Element types for AST
+* AST element types for Wikidot markup.
+*
+* Wikidot markup (`+ heading`, `**bold**`, `[[module ListPages]]`, etc.) is parsed into
+* a structured representation defined here. Each {@link Element} is a tagged union of
+* `{ element: tag, data: payload }`, where the data shape for each tag is defined in
+* {@link ElementDataMap}.
+*
+* @example
+* ```ts
+* import { parse } from "@wdprlib/parser";
+* const tree = parse("**Hello** world");
+* // tree.elements[0] → { element: "container", data: { type: "paragraph", ... } }
+* ```
+*
+* @module
 */
 /**
-* Attributes map
+* Key-value map of HTML attributes.
+* Populated from the Wikidot `_ class="foo" style="color:red"` attribute syntax.
+*
+* @group Primitives
 */
 type AttributeMap = Record<string, string>;
 /**
-* Variable map for includes
+* Key-value map of include variables.
+* Populated from `[[include page | key=value]]` pairs.
+*
+* @group Primitives
 */
 type VariableMap = Record<string, string>;
 /**
-* Alignment
+* Text alignment direction.
+* Maps to Wikidot alignment blocks: `[[=]]` (center), `[[<]]` (left),
+* `[[>]]` (right), `[[==]]` (justify).
+*
+* @group Primitives
 */
 type Alignment = "left" | "right" | "center" | "justify";
 /**
-* Float alignment
+* Image float alignment. Used in `[[image]]` positioning.
+*
+* When `float` is true, the image uses CSS float.
+* When false, it uses text-align only.
+*
+* @group Primitives
 */
 interface FloatAlignment {
 	align: Alignment;
+	/** Whether to use CSS float (true) or just text-align (false) */
 	float: boolean;
 }
 /**
-* Heading level
+* Heading level (1-6). Corresponds to Wikidot `+` (h1) through `++++++` (h6).
+*
+* @group Container Types
 */
 type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 /**
-* Heading structure
+* Heading configuration. Carries the level and whether this heading
+* should appear in the table of contents.
+*
+* In Wikidot, `+*` (asterisk suffix) excludes the heading from the TOC.
+*
+* @group Container Types
 */
 interface Heading {
 	level: HeadingLevel;
+	/** false when the heading uses `+*` syntax to opt out of the TOC */
 	"has-toc": boolean;
 }
 /**
-* Header container type
+* Discriminator for heading containers within {@link ContainerType}.
+*
+* @group Container Types
 */
 interface HeaderType {
 	header: Heading;
 }
 /**
-* Align container type
+* Discriminator for alignment-block containers within {@link ContainerType}.
+* Produced by `[[=]]`, `[[<]]`, `[[>]]`, and `[[==]]` blocks.
+*
+* @group Container Types
 */
 interface AlignType {
 	align: Alignment;
 }
 /**
-* String-only container types (formatting, structural, etc.)
+* Container types expressible as plain string literals.
+* Covers inline formatting (`**bold**`, `//italics//`, etc.) and
+* block-level structures (`div`, `blockquote`, `table-cell`, etc.).
+*
+* @group Container Types
 */
 type StringContainerType = "bold" | "italics" | "underline" | "superscript" | "subscript" | "strikethrough" | "monospace" | "span" | "div" | "blockquote" | "size" | "paragraph" | "heading" | "collapsible" | "definition-list" | "definition-list-item" | "definition-list-key" | "definition-list-value" | "table-row" | "table-cell";
 /**
-* Container types
+* Union of all container type discriminators.
+* Every container element in the AST carries one of these to identify
+* what kind of container it is.
+*
+* - String literals: inline formatting and block structures
+* - {@link HeaderType}: heading elements (`+ Heading`)
+* - {@link AlignType}: alignment blocks (`[[=]]...[[/=]]`)
+*
+* @group Container Types
 */
 type ContainerType = StringContainerType | HeaderType | AlignType;
 /**
-* Type guard: ContainerType is a string literal
+* Type guard: checks whether a {@link ContainerType} is a plain string literal.
+*
+* @group Container Types
 */
 declare function isStringContainerType(type: ContainerType): type is StringContainerType;
 /**
-* Type guard: ContainerType is a HeaderType
+* Type guard: checks whether a {@link ContainerType} is a {@link HeaderType}.
+*
+* @group Container Types
 */
 declare function isHeaderType(type: ContainerType): type is HeaderType;
 /**
-* Type guard: ContainerType is an AlignType
+* Type guard: checks whether a {@link ContainerType} is an {@link AlignType}.
+*
+* @group Container Types
 */
 declare function isAlignType(type: ContainerType): type is AlignType;
 /**
-* Container data
+* Data payload for container elements (paragraphs, bold, headings, divs, etc.).
+*
+* Every nestable Wikidot construct (`**bold**`, `[[div]]...[[/div]]`,
+* `+ heading`, etc.) is represented as an `{ element: "container", data: ContainerData }`.
+*
+* The `_`-prefixed fields are internal parser bookkeeping that gets stripped before
+* the final AST is returned. They coordinate paragraph splitting and span unwrapping
+* during post-processing.
+*
+* @group Container Types
 */
 interface ContainerData {
+	/** Identifies the kind of container and determines how it renders */
 	type: ContainerType;
+	/** HTML attributes specified via `_ class="..." style="..."` syntax */
 	attributes: AttributeMap;
+	/** Child elements nested inside this container */
 	elements: Element[];
+	/**
+	* Set on `[[span_]]` elements. Signals the post-processor to merge adjacent
+	* paragraphs, removing the `<p>` wrapper around the span's content.
+	* Consumed during post-processing; never present in the final AST.
+	* @internal
+	*/
 	_paragraphStrip?: boolean;
+	/**
+	* Set on empty `[[span_]][[/span_]]` elements. Acts as a line-break absorber:
+	* adjacent line-breaks are removed around this marker.
+	* Consumed during post-processing; never present in the final AST.
+	* @internal
+	*/
 	_emptyParagraphStrip?: boolean;
+	/**
+	* Set on content that follows a blank line inside `[[span_]]`.
+	* Indicates this content should be extracted outside its paragraph wrapper.
+	* Consumed during post-processing; never present in the final AST.
+	* @internal
+	*/
 	_escapedFromParagraph?: boolean;
+	/**
+	* Set on an orphaned `[[/span]]` closing tag (no matching open tag).
+	* The paragraph rule uses this to retroactively wrap preceding content in a span.
+	* Consumed during post-processing; never present in the final AST.
+	* @internal
+	*/
 	_closeSpan?: boolean;
+	/**
+	* Set on the 2nd+ segments of a regular `[[span]]` that was split by blank lines.
+	* Marks where the post-processor should split the enclosing paragraph.
+	* Consumed during post-processing; never present in the final AST.
+	* @internal
+	*/
 	_splitByBlankLine?: boolean;
 }
 /**
-* Anchor target
+* Link target window. Maps to the HTML `target` attribute.
+* In Wikidot, `*` suffix on a link (`[[[page*]]]`) sets `"new-tab"`.
+*
+* @group Link Types
 */
 type AnchorTarget = "new-tab" | "parent" | "top" | "same";
 /**
-* Page reference (for internal links)
+* Reference to an internal wiki page.
+* Produced by `[[[page]]]` or cross-site `[[[site:page]]]` syntax.
+*
+* @group Link Types
 */
 interface PageRef {
+	/** Site name for cross-site links; null for same-site links */
 	site: string | null;
+	/** Page UNIX name (e.g. `"scp-001"`, `"system:page-tags"`) */
 	page: string;
 }
 /**
-* Link location - either a page reference or a URL string
+* Link destination: either a {@link PageRef} for internal wiki links
+* or a plain URL string for external links.
+*
+* @group Link Types
 */
 type LinkLocation = PageRef | string;
 /**
-* Link label types
+* Link display label.
+*
+* - `{ text: string }` — explicit text (`[[[page | label]]]`)
+* - `{ url: string | null }` — use the URL itself as the label
+* - `"page"` — use the page name as the label (`[[[page]]]`)
+*
+* @group Link Types
 */
 type LinkLabel = {
 	text: string;
@@ -126,11 +285,26 @@ type LinkLabel = {
 	url: string | null;
 } | "page";
 /**
-* Link type
+* Link classification, determined by the syntax used.
+*
+* - `"direct"` — bare URL (`[http://...]`)
+* - `"page"` — page link (`[[[some-page]]]`)
+* - `"interwiki"` — interwiki link (`[[[wikipedia:article]]]`)
+* - `"anchor"` — in-page anchor (`[[# section]]`)
+* - `"table-of-contents"` — TOC-generated link
+*
+* @group Link Types
 */
 type LinkType = "direct" | "page" | "interwiki" | "anchor" | "table-of-contents";
 /**
-* Image source
+* Image source. Wikidot supports four resolution strategies:
+*
+* - `"url"` — absolute URL
+* - `"file1"` — file attached to the current page (`filename`)
+* - `"file2"` — file on another page (`page/filename`)
+* - `"file3"` — file on another site (`site:page/filename`)
+*
+* @group Image Types
 */
 type ImageSource = {
 	type: "url";
@@ -155,11 +329,16 @@ type ImageSource = {
 	};
 };
 /**
-* List type
+* List style. `"bullet"` for `*` items, `"numbered"` for `#` items,
+* `"generic"` for `[[li]]` block items.
+*
+* @group List Types
 */
 type ListType = "bullet" | "numbered" | "generic";
 /**
-* List item - discriminated union
+* A single list item. Either a leaf with inline content, or a nested sub-list.
+*
+* @group List Types
 */
 type ListItem = {
 	"item-type": "elements";
@@ -171,7 +350,9 @@ type ListItem = {
 	data: ListData;
 };
 /**
-* List data
+* Data payload for a list element (`* item`, `# item`, or `[[li]]`).
+*
+* @group List Types
 */
 interface ListData {
 	type: ListType;
@@ -179,95 +360,147 @@ interface ListData {
 	items: ListItem[];
 }
 /**
-* Definition list item
+* A single entry in a definition list (`: key : value`).
+*
+* @group List Types
 */
 interface DefinitionListItem {
+	/** Plain-text representation of the key (for quick lookups) */
 	key_string: string;
+	/** Rich-content key (may contain inline formatting) */
 	key: Element[];
+	/** Rich-content value */
 	value: Element[];
 }
 /**
-* Table cell
+* A single table cell (`||` delimited).
+*
+* @group Table Types
 */
 interface TableCell {
+	/** true if this cell is a header cell (`||~`) */
 	header: boolean;
+	/** Number of columns this cell spans (via `||` count) */
 	"column-span": number;
+	/** Explicit alignment, or null for default */
 	align: Alignment | null;
 	attributes: AttributeMap;
 	elements: Element[];
 }
 /**
-* Table row
+* A single table row.
+*
+* @group Table Types
 */
 interface TableRow {
 	attributes: AttributeMap;
 	cells: TableCell[];
 }
 /**
-* Table data
+* Data payload for a table element.
+*
+* @group Table Types
 */
 interface TableData {
 	attributes: AttributeMap;
 	rows: TableRow[];
 }
 /**
-* Tab data
+* A single tab in a `[[tabview]]` block.
+*
+* @group Block Elements
 */
 interface TabData {
+	/** Tab title displayed in the tab bar */
 	label: string;
+	/** Content inside the tab panel */
 	elements: Element[];
 }
 /**
-* Code block data
+* Data for a `[[code]]` block.
+*
+* @group Block Elements
 */
 interface CodeBlockData {
+	/** Raw source text inside the code block */
 	contents: string;
+	/** Language identifier for syntax highlighting, or null */
 	language: string | null;
+	/** Optional name/label for the code block */
 	name: string | null;
 }
 /**
-* Collapsible data
+* Data for a `[[collapsible]]` block.
+*
+* @group Block Elements
 */
 interface CollapsibleData {
 	elements: Element[];
 	attributes: AttributeMap;
+	/** Whether the block starts in the expanded state */
 	"start-open": boolean;
+	/** Custom text for the "show" toggle, or null for default */
 	"show-text": string | null;
+	/** Custom text for the "hide" toggle, or null for default */
 	"hide-text": string | null;
+	/** Whether to show the toggle at the top */
 	"show-top": boolean;
+	/** Whether to show the toggle at the bottom */
 	"show-bottom": boolean;
 }
 /**
-* Module types
+* Discriminated union of all `[[module ...]]` block types.
+*
+* Known modules have fully typed fields; unknown modules fall back to
+* `{ module: "unknown" }` with raw arguments preserved.
+*
+* @group Module Types
 */
 type Module = {
+	/** Unrecognized module — preserves raw arguments for pass-through */
 	module: "unknown";
 	name: string;
 	arguments: AttributeMap;
 	body?: string;
 } | {
+	/** `[[module Backlinks]]` — lists pages that link to a given page */
 	module: "backlinks";
+	/** Target page, or null for the current page */
 	page: string | null;
 } | {
+	/** `[[module Categories]]` — lists site categories */
 	module: "categories";
+	/** Whether to include categories marked as hidden */
 	"include-hidden": boolean;
 } | {
+	/** `[[module Join]]` — site membership join button */
 	module: "join";
 	"button-text": string | null;
 	attributes: AttributeMap;
 } | {
+	/** `[[module PageTree]]` — hierarchical page tree */
 	module: "page-tree";
+	/** Root page, or null for the site root */
 	root: string | null;
 	"show-root": boolean;
+	/** Max depth, or null for unlimited */
 	depth: number | null;
 } | {
+	/** `[[module Rate]]` — page rating widget */
 	module: "rate";
 } | {
+	/** `[[module ListUsers]]` — user listing with template body */
 	module: "list-users";
+	/** User selector expression (e.g. `"."` for current user) */
 	users: string;
+	/** Template body with `%%variable%%` placeholders */
 	body?: string;
 	attributes: AttributeMap;
 } | {
+	/**
+	* `[[module ListPages]]` — the most complex module.
+	* Queries pages by various criteria and renders each through a template body.
+	*/
 	module: "list-pages";
 	category?: string;
 	tags?: string;
@@ -296,12 +529,17 @@ type Module = {
 	"rss-home"?: string;
 	"rss-limit"?: number;
 	"rss-only": boolean;
+	/** Prefix for URL path parameters (HPC support) */
 	"url-attr-prefix"?: string;
+	/** Template body with `%%variable%%` placeholders */
 	body?: string;
 	attributes: AttributeMap;
 };
 /**
-* Embed types
+* Inline embed from `[[embed]]` syntax (not `[[embed]]...[[/embed]]` blocks).
+* Supports a fixed set of providers.
+*
+* @group Embed Types
 */
 type Embed = {
 	embed: "youtube";
@@ -326,108 +564,229 @@ type Embed = {
 	};
 };
 /**
-* Date item value
+* Parsed `[[date]]` value with timezone.
+*
+* @group Value Types
 */
 interface DateItem {
+	/** Unix timestamp (seconds) */
 	timestamp: number;
+	/** IANA timezone identifier */
 	timezone: string;
 }
 /**
-* Clear float direction
+* Direction for `[[f<]]`, `[[f>]]`, or `[[f=]]` (clear-float).
+*
+* @group Value Types
 */
 type ClearFloat = "left" | "right" | "both";
+/**
+* Data for `[[a]]` anchor element.
+*
+* @group Element Data
+*/
 interface AnchorData {
 	target: AnchorTarget | null;
 	attributes: AttributeMap;
 	elements: Element[];
 }
+/**
+* Data for link elements (`[[[page]]]`, `[http://...]`, etc.).
+*
+* @group Element Data
+*/
 interface LinkData {
 	type: LinkType;
 	link: LinkLocation;
+	/** Extra path segment (e.g. anchor fragment) */
 	extra: string | null;
 	label: LinkLabel;
 	target: AnchorTarget | null;
 }
+/**
+* Data for `[[image]]` elements.
+*
+* @group Element Data
+*/
 interface ImageData {
 	source: ImageSource;
+	/** If set, the image becomes a clickable link */
 	link: LinkLocation | null;
 	alignment: FloatAlignment | null;
 	attributes: AttributeMap;
 }
+/**
+* Data for `[[toc]]` (table of contents) elements.
+*
+* @group Element Data
+*/
 interface TableOfContentsData {
 	attributes: AttributeMap;
 	align: Alignment | null;
 }
+/**
+* Data for `[[footnoteblock]]` elements.
+*
+* @group Element Data
+*/
 interface FootnoteBlockData {
+	/** Custom title for the footnote section */
 	title: string | null;
+	/** If true, the block is hidden (footnotes rendered inline instead) */
 	hide?: boolean;
 }
+/**
+* Data for `[[bibcite label]]` (bibliography citation) elements.
+* Renders as a numbered reference link in the text.
+*
+* @group Element Data
+*/
 interface BibliographyCiteData {
+	/** Citation key that matches an entry in `[[bibliography]]` */
 	label: string;
+	/** Whether to render the citation number in brackets */
 	brackets: boolean;
 }
+/**
+* Data for `[[bibliography]]` block elements.
+* Collects all cited entries and renders as a reference list.
+*
+* @group Element Data
+*/
 interface BibliographyBlockData {
+	/** Definition list entries (`: label : description`) */
 	entries: DefinitionListItem[];
+	/** Custom section title, or null for default */
 	title: string | null;
+	/** If true, the block is hidden (for inline citation rendering) */
 	hide: boolean;
 }
+/**
+* Data for `[[user name]]` elements.
+*
+* @group Element Data
+*/
 interface UserData {
 	name: string;
+	/** Whether to show the user's avatar alongside the name */
 	"show-avatar": boolean;
 }
+/**
+* Data for `[[date timestamp]]` elements.
+*
+* @group Element Data
+*/
 interface DateData {
 	value: DateItem;
+	/** strftime-style format string, or null for default */
 	format: string | null;
+	/** Whether to show a tooltip with the full date on hover */
 	hover: boolean;
 }
+/**
+* Data for `##color|text##` inline color syntax.
+*
+* @group Element Data
+*/
 interface ColorData {
+	/** CSS color value (name, hex, rgb, etc.) */
 	color: string;
 	elements: Element[];
 }
+/**
+* Data for `[[math label]]` block math (LaTeX).
+*
+* @group Element Data
+*/
 interface MathData {
+	/** Optional equation label for cross-references */
 	name: string | null;
+	/** Raw LaTeX source */
 	"latex-source": string;
 }
+/**
+* Data for `[[$ ... $]]` inline math (LaTeX).
+*
+* @group Element Data
+*/
 interface MathInlineData {
+	/** Raw LaTeX source */
 	"latex-source": string;
 }
+/**
+* Data for `[[html]]` block elements.
+* Contains raw HTML that is sanitized at render time.
+*
+* @group Element Data
+*/
 interface HtmlData {
+	/** Raw HTML content */
 	contents: string;
+	/** Optional `<style>` content extracted from the HTML */
 	style?: string;
 }
 /**
-* Embed block data (Wikidot style [[embed]]..[[/embed]])
+* Data for `[[embed]]...[[/embed]]` block elements.
 * Contains raw HTML that is validated against an allowlist at render time.
-* Unlike html element, embed-block is paragraph-safe.
+* Unlike the `html` element, `embed-block` is paragraph-safe.
+*
+* @group Element Data
 */
 interface EmbedBlockData {
+	/** Raw HTML content */
 	contents: string;
 }
+/**
+* Data for `[[iframe url]]` elements.
+*
+* @group Element Data
+*/
 interface IframeData {
 	url: string;
 	attributes: AttributeMap;
 }
+/**
+* Data for `[[include page]]` elements.
+* After resolution via `resolveIncludes()`, `elements` is populated
+* with the included page's parsed content.
+*
+* @group Element Data
+*/
 interface IncludeData {
+	/** Whether this include appeared in an inline (paragraph-safe) context */
 	"paragraph-safe": boolean;
+	/** Variables passed to the included page (`key=value` pairs) */
 	variables: VariableMap;
+	/** Target page reference */
 	location: PageRef;
+	/** Parsed content of the included page (empty before resolution) */
 	elements: Element[];
 }
+/**
+* Data for `[[iftags]]` conditional blocks.
+* Content is shown/hidden based on the current page's tags.
+*
+* @group Element Data
+*/
 interface IfTagsData {
+	/** Tag condition expression (e.g. `"+scp -joke"`) */
 	condition: string;
 	elements: Element[];
 }
 /**
-* Expression data: [[#expr expression]]
+* Data for `[[#expr expression]]` inline expressions.
 * The expression is stored as a string and evaluated at render time.
+*
+* @group Element Data
 */
 interface ExprData {
 	expression: string;
 }
 /**
-* If data: [[#if value | then | else]]
-* Simple true/false checker that treats the value as a string.
-* False values: "false", "null", "", "0"
+* Data for `[[#if value | then | else]]` conditionals.
+* Simple truthy check — false values: `"false"`, `"null"`, `""`, `"0"`.
+*
+* @group Element Data
 */
 interface IfCondData {
 	condition: string;
@@ -435,14 +794,25 @@ interface IfCondData {
 	else: Element[];
 }
 /**
-* IfExpr data: [[#ifexpr expression | then | else]]
-* Evaluates the expression and branches based on the result.
+* Data for `[[#ifexpr expression | then | else]]` conditionals.
+* Evaluates the expression numerically and branches on the result.
+*
+* @group Element Data
 */
 interface IfExprData {
 	expression: string;
 	then: Element[];
 	else: Element[];
 }
+/**
+* Maps each element tag name to its data type.
+*
+* `void` means the element carries no data property (e.g. `line-break`).
+*
+* Declared as `type` (not `interface`) to prevent accidental declaration merging.
+*
+* @group Core
+*/
 type ElementDataMap = {
 	container: ContainerData;
 	module: Module;
@@ -489,15 +859,22 @@ type ElementDataMap = {
 	ifexpr: IfExprData;
 };
 /**
-* All element tag names
+* Union of all valid element tag names.
+*
+* @group Core
 */
 type ElementName = keyof ElementDataMap;
 /**
-* Get the data type for a given element name
+* Resolves the data type for a given element tag name.
+*
+* @group Core
 */
 type ElementData<K extends ElementName> = ElementDataMap[K];
 /**
-* Get the Element variant for a given element name
+* Resolves the full element shape for a given tag name.
+* Elements with `void` data omit the `data` property entirely.
+*
+* @group Core
 */
 type ElementOf<K extends ElementName> = ElementDataMap[K] extends void ? {
 	element: K;
@@ -506,61 +883,119 @@ type ElementOf<K extends ElementName> = ElementDataMap[K] extends void ? {
 	data: ElementDataMap[K];
 };
 /**
-* Element - tagged union generated from ElementDataMap
+* A single AST node. Tagged union over all element types.
+*
+* Use `element.element` to discriminate, then access `element.data`
+* with the appropriate type.
+*
+* @example
+* ```ts
+* if (el.element === "text") {
+*   console.log(el.data); // string
+* } else if (el.element === "container") {
+*   console.log(el.data.type); // ContainerType
+* }
+* ```
+*
+* @group Core
 */
 type Element = { [K in ElementName] : ElementOf<K> }[ElementName];
 /**
-* TOC entry collected during parsing (internal format)
+* Table-of-contents entry collected during parsing.
+* Used internally to build the TOC sidebar.
+*
+* @group Core
 */
 interface TocEntry {
+	/** Heading nesting level (1-6) */
 	level: number;
+	/** Plain-text heading content */
 	text: string;
 }
 /**
-* Syntax tree - root of the AST
+* Root of the parsed AST.
+*
+* Besides the main `elements` array, the tree may carry extracted
+* side-channel data (TOC, styles, code blocks, footnotes) that is
+* collected during parsing and used at render time.
+*
+* @group Core
 */
 interface SyntaxTree {
+	/** Top-level elements of the document */
 	elements: Element[];
+	/** Generated table-of-contents entries (if any headings have `has-toc: true`) */
 	"table-of-contents"?: Element[];
+	/** CSS from `[[module CSS]]` blocks */
 	styles?: string[];
+	/** Raw HTML from `[[html]]` blocks (rendered in sandboxed iframes) */
 	"html-blocks"?: string[];
+	/** Code blocks extracted for deferred syntax highlighting */
 	"code-blocks"?: CodeBlockData[];
+	/** Footnote content arrays, indexed by footnote number */
 	footnotes?: Element[][];
 }
 /**
-* Create a text element
+* Create a text element.
+*
+* @group Factories
 */
 declare function text(value: string): Element;
 /**
-* Create a container element
+* Create a container element with the given type and children.
+*
+* @group Factories
 */
 declare function container(type: ContainerType, elements: Element[], attributes?: AttributeMap): Element;
 /**
-* Create a paragraph element
+* Create a paragraph container.
+*
+* @group Factories
 */
 declare function paragraph(elements: Element[], attributes?: AttributeMap): Element;
 /**
-* Create a bold element
+* Create a bold (`**...**`) container.
+*
+* @group Factories
 */
 declare function bold(elements: Element[], attributes?: AttributeMap): Element;
 /**
-* Create an italics element
+* Create an italics (`//...//`) container.
+*
+* @group Factories
 */
 declare function italics(elements: Element[], attributes?: AttributeMap): Element;
 /**
-* Create a heading element
+* Create a heading (`+ ...` through `++++++ ...`) container.
+*
+* @param level - Heading depth (1-6)
+* @param elements - Heading content
+* @param hasToc - Whether to include in the table of contents (default: true)
+* @param attributes - Optional HTML attributes
+*
+* @group Factories
 */
 declare function heading(level: HeadingLevel, elements: Element[], hasToc?: boolean, attributes?: AttributeMap): Element;
 /**
-* Create a line break element
+* Create a line-break element.
+*
+* @group Factories
 */
 declare function lineBreak(): Element;
 /**
-* Create a horizontal rule element
+* Create a horizontal rule (`----`) element.
+*
+* @group Factories
 */
 declare function horizontalRule(): Element;
 /**
-* Create a link element
+* Create a link element.
+*
+* @param linkLocation - Destination (URL string or {@link PageRef})
+* @param label - Display label
+* @param options - Optional type, extra path, and target overrides
+*
+* @group Factories
 */
 declare function link(linkLocation: LinkLocation, label: LinkLabel, options?: {
 	type?: LinkType;
@@ -568,66 +1003,161 @@ declare function link(linkLocation: LinkLocation, label: LinkLabel, options?: {
 	target?: AnchorTarget | null;
 }): Element;
 /**
-* Create a list element
+* Create a list element.
+*
+* @group Factories
 */
 declare function list(type: ListType, items: ListItem[], attributes?: AttributeMap): Element;
 /**
-* Create a list item (elements type)
+* Create a list item containing inline elements.
+*
+* @group Factories
 */
 declare function listItemElements(elements: Element[], attributes?: AttributeMap): ListItem;
 /**
-* Create a list item (sub-list type)
+* Create a list item containing a nested sub-list.
+*
+* @group Factories
 */
 declare function listItemSubList(data: ListData): ListItem;
 /**
-* Check if a container type is paragraph-safe.
+* Check whether a container type can appear inside a `<p>` element.
+*
+* Inline formatting (bold, italics, span, etc.) is paragraph-safe.
+* Block-level structures (div, blockquote, heading, etc.) are not.
+*
+* @group Utilities
 */
 declare function isContainerTypeParagraphSafe(type: ContainerType): boolean;
 /**
-* Check if an element is paragraph-safe (can be contained within a paragraph).
+* Check whether an element can appear inside a `<p>` element.
 *
-* This does a surface-level check and does not look into element interiors.
+* Performs a surface-level check on the element tag (and container type
+* for containers). Does not recurse into child elements.
+*
+* Used by the parser to decide whether to wrap adjacent inline elements
+* in a paragraph or leave them as block-level siblings.
+*
+* @group Utilities
 */
 declare function isParagraphSafe(element: Element): boolean;
 /**
-* Wikitext parsing/rendering mode.
-* Each mode has different default settings for syntax availability.
+* Sentinel prefix for style slot placeholders in {@link SyntaxTree.styles}.
+*
+* When the resolver encounters an unresolved `[[iftags]]` block containing
+* `[[module CSS]]`, it inserts a sentinel string (`STYLE_SLOT_PREFIX + slotId`)
+* into the styles array to preserve source order. At render time the sentinel
+* is replaced with the actual CSS collected from the iftags block (if the
+* condition matches).
+*
+* A null-byte prefix ensures no collision with valid CSS content.
+*/
+declare const STYLE_SLOT_PREFIX = "\0__IFTAGS_SLOT__";
+/**
+* Context-dependent settings for the Wikidot parser and renderer.
+*
+* Wikidot content appears in several different contexts — full wiki pages,
+* draft previews, forum posts, and direct messages — each with different
+* security and capability requirements. {@link WikitextSettings} captures
+* those differences so the parser/renderer can enable or disable features
+* accordingly.
+*
+* Use {@link createSettings} to get sane defaults for a given
+* {@link WikitextMode}, then override individual fields as needed.
+*
+* @module
+*/
+/**
+* The context in which wikitext is being parsed and rendered.
+*
+* Each mode implies a different set of defaults for
+* {@link WikitextSettings}. The modes correspond to the places where
+* user-authored wikitext can appear on a Wikidot site.
+*
+* | Mode               | Page syntax | Local paths | True IDs | Style elements |
+* |--------------------|:-----------:|:-----------:|:--------:|:--------------:|
+* | `"page"`           | yes         | yes         | yes      | yes            |
+* | `"draft"`          | yes         | yes         | no       | no             |
+* | `"forum-post"`     | no          | no          | no       | no             |
+* | `"direct-message"` | no          | no          | no       | no             |
+*
+* @group Settings
 */
 type WikitextMode = "page" | "draft" | "forum-post" | "direct-message";
 /**
-* Settings that control parser and renderer behavior based on context.
+* Controls which parser and renderer features are active.
+*
+* These flags gate syntax availability and rendering behaviour based on the
+* context where the wikitext appears. Construct via {@link createSettings}
+* and override individual fields when non-default behaviour is needed.
+*
+* @group Settings
 */
 interface WikitextSettings {
-	/** Operating mode */
+	/** The context mode this settings object was created for */
 	mode: WikitextMode;
 	/**
 	* Whether page-contextual syntax is permitted.
-	* Controls: include, module, table-of-contents.
+	*
+	* When `true`, the parser recognises `[[include]]`, `[[module]]`, and
+	* `[[toc]]` blocks. These constructs are meaningful only inside a full
+	* wiki page and are disabled in forum posts and direct messages.
 	*/
 	enablePageSyntax: boolean;
 	/**
-	* Whether local file paths (file1, file2, file3) are permitted for images.
-	* Disable in contexts without a "local" page (forum posts, direct messages).
+	* Whether local file references (`file1`, `file2`, `file3`) are allowed
+	* in image sources.
+	*
+	* Local files belong to a specific wiki page. In contexts that lack a
+	* "current page" — such as forum posts and direct messages — local file
+	* references are meaningless and should be rejected.
 	*/
 	allowLocalPaths: boolean;
 	/**
-	* Whether element IDs should be stable sequential values.
-	* When false, IDs are randomized to prevent collisions
-	* when multiple rendered fragments appear on the same page.
+	* Whether heading and footnote IDs use stable sequential values
+	* (`toc0`, `toc1`, ...) or randomised strings.
+	*
+	* Stable IDs are appropriate when a single rendered page owns the full
+	* document. Randomised IDs prevent collisions when multiple rendered
+	* fragments (e.g. a live draft preview) coexist on the same HTML page.
 	*/
 	useTrueIds: boolean;
 	/**
-	* Whether [[module CSS]] style elements are rendered as <style> tags.
-	* Disable to prevent user-authored CSS from affecting the page layout
-	* (e.g., in draft previews, forum posts).
+	* Whether `[[module CSS]]` blocks are rendered as `<style>` tags.
+	*
+	* User-authored CSS can break page layout, so it is allowed only on
+	* full wiki pages. In draft previews, forum posts, and direct messages
+	* the CSS module is silently ignored.
 	*/
 	allowStyleElements: boolean;
 }
 /**
-* Create WikitextSettings with defaults for the given mode.
+* Create a {@link WikitextSettings} with sensible defaults for the given mode.
+*
+* See the table on {@link WikitextMode} for which flags each mode enables.
+*
+* @param mode - The context in which wikitext will be parsed
+* @returns A new settings object with defaults for that mode
+*
+* @group Settings
 */
 declare function createSettings(mode: WikitextMode): WikitextSettings;
-/** Default settings (page mode) */
+/**
+* Pre-built settings for `"page"` mode — the most common context.
+*
+* Equivalent to `createSettings("page")`. Provided as a convenience
+* for call-sites that always operate on full wiki pages.
+*
+* @group Settings
+*/
 declare const DEFAULT_SETTINGS: WikitextSettings;
+/**
+* Identifies the source markup dialect.
+*
+* Currently only `"wikidot"` is supported. Included in {@link SyntaxTree}
+* so consumers can branch on the dialect if other formats are added later.
+*
+* @group Core
+*/
 type Version = "wikidot";
-export { text, paragraph, listItemSubList, listItemElements, list, link, lineBreak, italics, isStringContainerType, isParagraphSafe, isHeaderType, isContainerTypeParagraphSafe, isAlignType, horizontalRule, heading, createSettings, createPosition, createPoint, container, bold, WikitextSettings, WikitextMode, Version, VariableMap, UserData, TocEntry, TableRow, TableOfContentsData, TableData, TableCell, TabData, SyntaxTree, StringContainerType, Position, Point, PageRef, Module, MathInlineData, MathData, ListType, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LinkData, IncludeData, ImageSource, ImageData, IframeData, IfTagsData, IfExprData, IfCondData, HtmlData, HeadingLevel, Heading, HeaderType, FootnoteBlockData, FloatAlignment, ExprData, EmbedBlockData, Embed, ElementOf, ElementName, ElementDataMap, ElementData, Element, DefinitionListItem, DateItem, DateData, DEFAULT_SETTINGS, ContainerType, ContainerData, ColorData, CollapsibleData, CodeBlockData, ClearFloat, BibliographyCiteData, BibliographyBlockData, AttributeMap, AnchorTarget, AnchorData, Alignment, AlignType };
+export { text, paragraph, listItemSubList, listItemElements, list, link, lineBreak, italics, isStringContainerType, isParagraphSafe, isHeaderType, isContainerTypeParagraphSafe, isAlignType, horizontalRule, heading, createSettings, createPosition, createPoint, container, bold, WikitextSettings, WikitextMode, Version, VariableMap, UserData, TocEntry, TableRow, TableOfContentsData, TableData, TableCell, TabData, SyntaxTree, StringContainerType, STYLE_SLOT_PREFIX, Position, Point, PageRef, Module, MathInlineData, MathData, ListType, ListItem, ListData, LinkType, LinkLocation, LinkLabel, LinkData, IncludeData, ImageSource, ImageData, IframeData, IfTagsData, IfExprData, IfCondData, HtmlData, HeadingLevel, Heading, HeaderType, FootnoteBlockData, FloatAlignment, ExprData, EmbedBlockData, Embed, ElementOf, ElementName, ElementDataMap, ElementData, Element, DefinitionListItem, DateItem, DateData, DEFAULT_SETTINGS, ContainerType, ContainerData, ColorData, CollapsibleData, CodeBlockData, ClearFloat, BibliographyCiteData, BibliographyBlockData, AttributeMap, AnchorTarget, AnchorData, Alignment, AlignType };