@regmisatyam/retex 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,916 @@
+import { S as SourceRange, A as ArgumentNode, N as Node, C as CommandNode, T as Theme, D as DocumentNode, a as ContactNode, b as SectionNode, F as FieldMap, R as ReactRenderFn, P as PartialTheme, c as ReactRenderOptions } from './react-v8gyKEAs.cjs';
+export { d as ColorNode, e as ColumnNode, f as ColumnsNode, g as ContactField, E as EducationNode, h as ErrorNode, i as FontFamilyNode, j as FontScale, k as FontScaleNode, l as FontSizeNode, G as GroupNode, I as IconNode, J as JobNode, m as JsxFactory, L as LineBreakNode, n as LinkNode, o as ListItemNode, p as ListKind, q as ListNode, M as MarkNode, r as MarkType, s as NodeBase, t as NodeMap, u as NodeType, v as ParBreakNode, w as ParentNode, x as Position, y as ProjectNode, z as ReactRenderContext, B as ReactRenderer, H as RuleNode, K as SkillsNode, O as SpaceNode, Q as TextNode, U as ThemeColorNode, V as ThemeColors, W as ThemeFontSizes, X as ThemeFonts, Y as ThemePage, Z as ThemeSpacing, _ as UrlNode, $ as isNode, a0 as isParent, a1 as mergeRanges, a2 as pos, a3 as range, a4 as rangeContains, a5 as renderReact } from './react-v8gyKEAs.cjs';
+
+/**
+ * Token kinds produced by the {@link Tokenizer}.
+ *
+ * ReTeX intentionally diverges from TeX in a few places that matter for
+ * resumes:
+ *  - `%` is a *literal* percent sign (so `Reduced latency by 40%` and
+ *    `\column{40%}` work as written) rather than a comment marker.
+ *  - Comments use `%%` to end-of-line, which never collides with percentages.
+ */
+declare enum TokenType {
+    /** A command such as `\section`, `\textbf`, `\item`. The lexeme excludes the backslash. */
+    Command = "Command",
+    /** `{` — begin group / argument. */
+    LBrace = "LBrace",
+    /** `}` — end group / argument. */
+    RBrace = "RBrace",
+    /** `[` — begin optional argument. */
+    LBracket = "LBracket",
+    /** `]` — end optional argument. */
+    RBracket = "RBracket",
+    /** Run of literal text. */
+    Text = "Text",
+    /** Run of inline whitespace (spaces/tabs, single newline). */
+    Whitespace = "Whitespace",
+    /** A blank line — paragraph break. */
+    ParBreak = "ParBreak",
+    /** `\\` — explicit line break. */
+    LineBreak = "LineBreak",
+    /** `%% ...` comment (stripped from output, surfaced to editor tooling). */
+    Comment = "Comment",
+    /** End of input. */
+    EOF = "EOF"
+}
+/** A lexical token with full source provenance. */
+interface Token {
+    type: TokenType;
+    /** The exact source text of the token (backslash stripped for commands). */
+    value: string;
+    range: SourceRange;
+}
+/** Reserved single characters that the tokenizer treats specially. */
+declare const SPECIAL_CHARS: Set<string>;
+
+/** Severity levels, ordered the same way LSP orders them. */
+declare enum DiagnosticSeverity {
+    Error = "error",
+    Warning = "warning",
+    Info = "info",
+    Hint = "hint"
+}
+/**
+ * Stable, machine-readable diagnostic codes. Editors can key quick-fixes and
+ * documentation links off these rather than the (localizable) message text.
+ */
+declare enum DiagnosticCode {
+    UnexpectedToken = "RTX1001",
+    UnterminatedGroup = "RTX1002",
+    UnterminatedArgument = "RTX1003",
+    UnexpectedEOF = "RTX1004",
+    MismatchedBrace = "RTX1005",
+    UnknownCommand = "RTX2001",
+    UnknownEnvironment = "RTX2002",
+    MissingRequiredArgument = "RTX2003",
+    TooManyArguments = "RTX2004",
+    MissingEnvironmentEnd = "RTX2005",
+    MismatchedEnvironment = "RTX2006",
+    InvalidColor = "RTX3001",
+    InvalidUrl = "RTX3002",
+    InvalidDimension = "RTX3003",
+    MissingRequiredField = "RTX3004",
+    UnknownField = "RTX3005",
+    EmptyArgument = "RTX3006",
+    CommandOutsideContext = "RTX4001",
+    UnknownIcon = "RTX4002",
+    UnknownThemeColor = "RTX4003",
+    UnsafeUrlBlocked = "RTX5001"
+}
+/** Optional quick-fix an editor can apply. */
+interface QuickFix {
+    title: string;
+    /** Replacement text for {@link Diagnostic.range}. */
+    replacement: string;
+    range?: SourceRange;
+}
+/** A single diagnostic emitted by any stage of the pipeline. */
+interface Diagnostic {
+    severity: DiagnosticSeverity;
+    code: DiagnosticCode;
+    message: string;
+    range: SourceRange;
+    /** Stage that produced the diagnostic, for filtering. */
+    source: "tokenizer" | "parser" | "validator" | "security";
+    /** Optional editor quick-fixes. */
+    fixes?: QuickFix[];
+}
+
+/**
+ * How a single argument should be consumed by the parser.
+ *
+ *  - `content`   — recursively parse markup (nested commands, text).
+ *  - `string`    — verbatim text; no command expansion (URLs, colors, sizes).
+ *  - `keyval`    — `key=value, key=value` map.
+ *  - `list`      — comma-separated list of trimmed strings.
+ */
+type ArgKind = "content" | "string" | "keyval" | "list";
+interface ArgSpec {
+    kind: ArgKind;
+    /** When true the argument may be absent (no diagnostic if missing). */
+    optional?: boolean;
+    /**
+     * Delimiter pair. `"brace"` (default) → `{...}`; `"bracket"` → `[...]`.
+     * An optional brace argument (e.g. an entry body) is still written with
+     * `{...}` but may be omitted.
+     */
+    delimiter?: "brace" | "bracket";
+    /** Human-readable name surfaced in hover docs / diagnostics. */
+    name?: string;
+    /** Validation hint for `string` args (drives format checks). */
+    format?: "color" | "url" | "dimension" | "text";
+}
+/**
+ * Semantic category of a command. Drives default rendering and where the
+ * command is legal.
+ *
+ *  - `inline` — flows within text (`\textbf`).
+ *  - `block`  — starts a block (`\section`, `\job`).
+ *  - `switch` — a state switch that applies to the rest of its group
+ *               (`\large`, `\bfseries`-style).
+ *  - `meta`   — document metadata that produces no inline flow on its own.
+ */
+type CommandCategory = "inline" | "block" | "switch" | "meta";
+/**
+ * A factory the parser calls once arguments are consumed, to build the AST
+ * node for a command. Returning `null` drops the command from the tree.
+ */
+type NodeBuilder = (ctx: BuildContext) => Node | Node[] | null;
+interface BuildContext {
+    name: string;
+    args: ArgumentNode[];
+    /** For switches: the trailing content the switch applies to. */
+    scope: Node[];
+    /** Emit a diagnostic from within a builder. */
+    report: (d: Omit<Diagnostic, "source">) => void;
+    /** Utilities exposed to plugin authors. */
+    utils: BuilderUtils;
+}
+interface BuilderUtils {
+    /** Flatten an argument's children into a plain string (best-effort). */
+    textOf(arg: ArgumentNode | undefined): string;
+    /** Sanitize a URL; returns `"#"` (and reports) when unsafe. */
+    safeUrl(url: string): string;
+}
+/**
+ * The contract for a command. Used by the parser (argument signature, scope
+ * behavior) and the renderers (when no native node exists, renderers consult
+ * the command's per-target `render` map).
+ */
+interface CommandDefinition {
+    name: string;
+    category?: CommandCategory;
+    /** Argument signature, in order. */
+    args?: ArgSpec[];
+    /**
+     * `true` for switches that swallow the remainder of their enclosing group
+     * as scoped content (`\large`, `\itshape`).
+     */
+    scoped?: boolean;
+    /**
+     * Builds the AST node. When omitted, the parser emits a generic
+     * {@link CommandNode} carrying the parsed arguments.
+     */
+    build?: NodeBuilder;
+    /** One-line summary for hover docs / completion detail. */
+    summary?: string;
+    /** Longer documentation (markdown) for hover. */
+    documentation?: string;
+    /** Example snippet shown in completion / hover. */
+    example?: string;
+}
+/** Environment (`\begin{x} … \end{x}`) contract. */
+interface EnvironmentDefinition {
+    name: string;
+    /**
+     * Command that introduces each entry inside the environment, e.g. `item`
+     * for `itemize`, `column` for `columns`. The parser uses this to slice
+     * the body into entries.
+     */
+    itemCommand?: string;
+    /** Commands legal as direct children (for validation). `*` allows any. */
+    allowedChildren?: string[];
+    /** Build the environment node from its parsed body. */
+    build?: (ctx: EnvBuildContext) => Node | Node[] | null;
+    summary?: string;
+    documentation?: string;
+    example?: string;
+}
+/**
+ * One entry of an `itemCommand`-delimited environment. For `itemize`, the
+ * marker command is `\item`; for `columns`, it is `\column{width}`.
+ */
+interface EnvEntry {
+    /** The marker command that introduced the entry, with its parsed arguments. */
+    marker: CommandNode;
+    /** Content nodes belonging to this entry (up to the next marker / `\end`). */
+    content: Node[];
+}
+interface EnvBuildContext {
+    name: string;
+    /** Parsed body nodes of the environment (always present). */
+    body: Node[];
+    /**
+     * When the environment declares an `itemCommand`, the body sliced into
+     * entries at each marker. `undefined` for plain block environments.
+     */
+    entries?: EnvEntry[];
+    /** Optional `[...]` arguments after `\begin{env}`. */
+    options: ArgumentNode[];
+    report: (d: Omit<Diagnostic, "source">) => void;
+    utils: BuilderUtils;
+}
+
+interface TokenizeResult {
+    tokens: Token[];
+    diagnostics: Diagnostic[];
+}
+/**
+ * Stage 1 of the pipeline. Converts raw ReTeX source into a flat token stream
+ * with exact source ranges. The tokenizer is deliberately permissive — it
+ * never throws — so the parser can perform error recovery downstream.
+ *
+ * Design notes specific to resumes:
+ *  - `%` is a literal percent sign. Comments are `%%` to end-of-line.
+ *  - Escapes (`\%`, `\&`, `\{`, `\_`, `\$`, `\#`, `\ `) become literal text.
+ *  - `\\` is an explicit line break.
+ *  - A whitespace run containing a blank line becomes a single `ParBreak`.
+ */
+declare class Tokenizer {
+    private readonly src;
+    private offset;
+    private line;
+    private column;
+    private readonly tokens;
+    private readonly diagnostics;
+    constructor(source: string);
+    static tokenize(source: string): TokenizeResult;
+    run(): TokenizeResult;
+    private scanToken;
+    private scanBackslash;
+    private scanComment;
+    private scanWhitespace;
+    private scanText;
+    private atEnd;
+    private peek;
+    private read;
+    private position;
+    private push;
+}
+/** Convenience wrapper. */
+declare function tokenize(source: string): TokenizeResult;
+
+/**
+ * The command/environment registry. The parser consults it for argument
+ * signatures and node builders; the plugin system mutates it. A registry can
+ * be cloned cheaply so an engine instance never mutates shared global state.
+ */
+declare class CommandRegistry {
+    private commands;
+    private environments;
+    registerCommand(def: CommandDefinition): this;
+    registerEnvironment(def: EnvironmentDefinition): this;
+    getCommand(name: string): CommandDefinition | undefined;
+    getEnvironment(name: string): EnvironmentDefinition | undefined;
+    hasCommand(name: string): boolean;
+    hasEnvironment(name: string): boolean;
+    commandNames(): string[];
+    environmentNames(): string[];
+    allCommands(): CommandDefinition[];
+    allEnvironments(): EnvironmentDefinition[];
+    /** Shallow-clone the registry (definitions are shared, maps are copied). */
+    clone(): CommandRegistry;
+}
+
+/**
+ * Icon registry. Icons are stored as the inner markup of a `0 0 24 24` SVG and
+ * use `currentColor` so they inherit surrounding text color. The set is
+ * intentionally small and extensible via {@link registerIcon} / plugins.
+ *
+ * Glyphs are simplified, original representations (not vendor logo artwork) so
+ * the package carries no third-party asset licensing.
+ */
+interface IconDefinition {
+    /** Inner SVG markup (paths/shapes) with a `0 0 24 24` viewBox. */
+    body: string;
+    /** Whether shapes are stroked (true) or filled (false). */
+    stroked?: boolean;
+    /** Aliases that resolve to this icon. */
+    aliases?: string[];
+}
+/** Resolve a (possibly aliased) icon name to its canonical key. */
+declare function resolveIconName(name: string): string | undefined;
+declare function hasIcon(name: string): boolean;
+declare function getIcon(name: string): IconDefinition | undefined;
+/** Register (or override) an icon at runtime. Used by plugins. */
+declare function registerIcon(name: string, def: IconDefinition): void;
+/** All canonical icon names, for completion / docs. */
+declare function iconNames(): string[];
+/**
+ * Render an icon to an inline SVG string. Returns `null` for unknown icons so
+ * callers can emit a diagnostic and a graceful fallback.
+ */
+declare function iconToSvg(name: string, opts?: {
+    size?: number | string;
+    className?: string;
+}): string | null;
+
+/**
+ * Generate the stylesheet for a rendered resume from a {@link Theme}. Theme
+ * values become CSS custom properties so they can be overridden at runtime,
+ * and every theme color is exposed as `--retex-color-<token>` for use by
+ * `\themecolor`.
+ */
+declare function themeToCss(theme: Theme, prefix?: string): string;
+
+/** Node types that participate in block (vertical) flow. */
+declare const BLOCK_TYPES: Set<string>;
+declare function isBlockNode(node: Node): boolean;
+/**
+ * Plugin HTML renderer. Receives the node, the active context, and a callback
+ * to recursively render child nodes to HTML.
+ */
+type HtmlRenderFn = (node: Node, ctx: HtmlRenderContext, renderChildren: (nodes: Node[]) => string) => string;
+interface HtmlRenderContext {
+    theme: Theme;
+    classPrefix: string;
+    /** Override renderers keyed by node `type` or `command:<name>`. */
+    overrides: Map<string, HtmlRenderFn>;
+    /** Render arbitrary inline/block nodes to an HTML string. */
+    renderNodes: (nodes: Node[]) => string;
+    cls: (name: string) => string;
+}
+
+interface HtmlRenderOptions {
+    theme?: Theme;
+    /** CSS class prefix. Default `"retex"`. */
+    classPrefix?: string;
+    /** Plugin render overrides keyed by node `type` or `command:<name>`. */
+    overrides?: Map<string, HtmlRenderFn>;
+    /** Group leading contact commands into a `<header>`. Default `true`. */
+    header?: boolean;
+}
+/**
+ * The HTML renderer. Produces clean, semantic, fully-escaped HTML. Every text
+ * node and attribute is escaped; every URL is re-sanitized at render time as a
+ * defense-in-depth measure even though the parser already vetted it.
+ */
+declare class HtmlRenderer {
+    private readonly theme;
+    private readonly prefix;
+    private readonly overrides;
+    private readonly useHeader;
+    private readonly ctx;
+    constructor(options?: HtmlRenderOptions);
+    /** Render the resume body as an HTML fragment (no `<html>`/`<style>`). */
+    render(ast: DocumentNode): string;
+    /** Render a complete, standalone HTML document including the stylesheet. */
+    renderDocument(ast: DocumentNode, title?: string): string;
+    /** The stylesheet for the active theme (without `<style>` tags). */
+    styles(): string;
+    private renderSection;
+    private renderPreamble;
+    private renderContactItem;
+    private contactLink;
+    /** Block-aware rendering: groups inline runs into `<p>`, renders blocks as-is. */
+    private renderFlow;
+    private renderInline;
+    private renderNode;
+    private renderLink;
+    private renderList;
+    private renderColumns;
+    private renderSkills;
+    private renderEntry;
+    private renderCommand;
+    private icon;
+    private dim;
+    private cls;
+}
+/** Render a document AST to an HTML fragment. */
+declare function renderHtml(ast: DocumentNode, options?: HtmlRenderOptions): string;
+/** Render a document AST to a complete standalone HTML page. */
+declare function renderHtmlDocument(ast: DocumentNode, options?: HtmlRenderOptions & {
+    title?: string;
+}): string;
+
+interface JsonRenderOptions {
+    /** Strip `range`/`hash` metadata for a compact, stable payload. */
+    stripMeta?: boolean;
+    /** `JSON.stringify` indentation (number of spaces). Default 2. */
+    indent?: number;
+}
+/** Deep-clone an AST, optionally removing source metadata. */
+declare function toJsonTree(ast: Node, opts?: JsonRenderOptions): unknown;
+/**
+ * The JSON renderer. Produces a structured, machine-readable representation of
+ * the document AST — handy for editor tooling, diffing, and storage.
+ */
+declare function renderJson(ast: DocumentNode, opts?: JsonRenderOptions): string;
+
+interface PrintOptions extends HtmlRenderOptions {
+    title?: string;
+}
+/**
+ * Build the `@page` CSS for the theme's page geometry. This is what turns a
+ * web page into a paginated, print-ready document.
+ */
+declare function pageCss(theme: Theme): string;
+/**
+ * Render a print-optimized, standalone HTML document. This is the portable
+ * core of the PDF strategy: the same HTML can be
+ *  - printed to PDF in the browser via `window.print()`,
+ *  - converted headlessly with Puppeteer/Playwright ({@link renderPdf}), or
+ *  - handed to any HTML-to-PDF service.
+ */
+declare function renderPrintHtml(ast: DocumentNode, options?: PrintOptions): string;
+interface PdfOptions extends PrintOptions {
+    /**
+     * Optional injected headless-browser launcher. When omitted, `renderPdf`
+     * dynamically imports `puppeteer` if it is installed.
+     */
+    launch?: () => Promise<HeadlessBrowser>;
+    /** Print background colors/images. Default `true`. */
+    printBackground?: boolean;
+}
+/** Minimal structural types for the puppeteer/playwright adapter. */
+interface HeadlessPage {
+    setContent(html: string, opts?: {
+        waitUntil?: string;
+    }): Promise<void>;
+    pdf(opts: Record<string, unknown>): Promise<Uint8Array>;
+}
+interface HeadlessBrowser {
+    newPage(): Promise<HeadlessPage>;
+    close(): Promise<void>;
+}
+/**
+ * Render a document to a PDF byte buffer using a headless browser.
+ *
+ * The default path lazily imports `puppeteer` (an *optional* dependency) so the
+ * core library stays dependency-free. Supply `options.launch` to plug in
+ * Playwright, a pooled browser, or a remote Chromium instead.
+ *
+ * @throws if no launcher is available, with guidance on how to enable PDF export.
+ */
+declare function renderPdf(ast: DocumentNode, options?: PdfOptions): Promise<Uint8Array>;
+
+/** A document region: an optional leading section heading plus its body. */
+interface Region {
+    section?: SectionNode;
+    nodes: Node[];
+}
+/** Split a document's children into regions delimited by level-1 sections. */
+declare function toRegions(children: Node[]): Region[];
+interface PreambleParts {
+    name?: ContactNode;
+    title?: ContactNode;
+    contacts: Node[];
+    other: Node[];
+}
+/** Separate a preamble into header pieces (name/title/contacts) and the rest. */
+declare function splitPreamble(nodes: Node[]): PreambleParts;
+interface EntryParts {
+    title: string;
+    subtitle: string;
+    dates: string;
+    location: string;
+    url: string;
+}
+/** Normalize a job/education/project field map into renderable entry parts. */
+declare function entryParts(fields: FieldMap, kind: string): EntryParts;
+declare function dateRange(start?: string, end?: string, date?: string): string;
+
+/**
+ * A command definition extended with optional per-target render functions.
+ * Passing `render.html` is shorthand for registering an HTML override keyed by
+ * `command:<name>` — the common case for a plugin command with no custom AST
+ * node (e.g. `\badge{...}`).
+ */
+interface EngineCommand extends CommandDefinition {
+    render?: {
+        html?: HtmlRenderFn;
+        react?: ReactRenderFn;
+    };
+}
+/**
+ * A ReTeX plugin. Everything is optional; a plugin may contribute commands,
+ * environments, icons, renderers, theme overrides, or run arbitrary setup
+ * against the engine. Plugins never touch global state — they mutate only the
+ * engine instance they are installed on.
+ */
+interface ReTeXPlugin {
+    name: string;
+    commands?: EngineCommand[];
+    environments?: EnvironmentDefinition[];
+    icons?: Record<string, IconDefinition>;
+    /** HTML overrides keyed by node `type` or `command:<name>`. */
+    htmlRenderers?: Record<string, HtmlRenderFn>;
+    /** React overrides keyed by node `type` or `command:<name>`. */
+    reactRenderers?: Record<string, ReactRenderFn>;
+    /** A theme patch applied when the plugin is installed. */
+    theme?: PartialTheme;
+    /** Imperative hook for advanced setup. */
+    setup?: (engine: PluginHost) => void;
+}
+/** The subset of the engine surface a plugin's `setup` hook may use. */
+interface PluginHost {
+    registerCommand(def: EngineCommand): PluginHost;
+    registerEnvironment(def: EnvironmentDefinition): PluginHost;
+    registerHtmlRenderer(key: string, fn: HtmlRenderFn): PluginHost;
+    registerReactRenderer(key: string, fn: ReactRenderFn): PluginHost;
+    registerIcon(name: string, def: IconDefinition): PluginHost;
+}
+
+interface EngineOptions {
+    theme?: Theme | PartialTheme;
+    plugins?: ReTeXPlugin[];
+    classPrefix?: string;
+    /** Max number of compiled documents to cache. Default 64. */
+    cacheSize?: number;
+}
+interface CompileResult {
+    source: string;
+    tokens: Token[];
+    ast: DocumentNode;
+    diagnostics: Diagnostic[];
+}
+interface CompileOptions {
+    /** Run semantic validation in addition to parsing. Default `true`. */
+    validate?: boolean;
+}
+/**
+ * The ReTeX engine: the single entry point that wires the tokenizer, parser,
+ * validator, renderers, theming, plugins, and caching together.
+ *
+ * ```ts
+ * const engine = new ReTeXEngine({ theme: { colors: { primary: "#7c3aed" } } });
+ * engine.registerCommand({ name: "badge", args: [{ kind: "content" }],
+ *   render: { html: (n, ctx, kids) => `<span class="badge">${kids((n as any).args[0].children)}</span>` } });
+ * const html = engine.toHtml(source);
+ * ```
+ */
+declare class ReTeXEngine implements PluginHost {
+    private registry;
+    private theme;
+    private readonly prefix;
+    private readonly htmlOverrides;
+    private readonly reactOverrides;
+    private readonly cache;
+    private readonly cacheSize;
+    private generation;
+    constructor(options?: EngineOptions);
+    use(plugin: ReTeXPlugin): this;
+    registerCommand(def: EngineCommand): this;
+    registerEnvironment(def: EnvironmentDefinition): this;
+    registerHtmlRenderer(key: string, fn: HtmlRenderFn): this;
+    registerReactRenderer(key: string, fn: ReactRenderFn): this;
+    registerIcon(name: string, def: IconDefinition): this;
+    setTheme(theme: Theme | PartialTheme): this;
+    getTheme(): Theme;
+    getRegistry(): CommandRegistry;
+    tokenize(source: string): TokenizeResult;
+    /** Tokenize, parse, and (by default) validate a source string. Cached. */
+    compile(source: string, options?: CompileOptions): CompileResult;
+    parse(source: string): DocumentNode;
+    validate(input: string | DocumentNode): Diagnostic[];
+    toHtml(input: string | DocumentNode, options?: HtmlRenderOptions): string;
+    toHtmlDocument(input: string | DocumentNode, options?: HtmlRenderOptions & {
+        title?: string;
+    }): string;
+    toReact(input: string | DocumentNode, options: Omit<ReactRenderOptions, "theme" | "classPrefix" | "overrides">): unknown;
+    toJson(input: string | DocumentNode, options?: JsonRenderOptions): string;
+    toPrintHtml(input: string | DocumentNode, options?: PrintOptions): string;
+    toPdf(input: string | DocumentNode, options?: PdfOptions): Promise<Uint8Array>;
+    /** The CSS stylesheet for the active theme. */
+    styles(): string;
+    private astOf;
+    private htmlRenderer;
+    private printOptions;
+    private invalidate;
+    private remember;
+}
+/** Create an engine with the default configuration. */
+declare function createEngine(options?: EngineOptions): ReTeXEngine;
+
+interface ParseResult {
+    ast: DocumentNode;
+    diagnostics: Diagnostic[];
+}
+interface ParserOptions {
+    registry?: CommandRegistry;
+    /**
+     * Maximum structural nesting depth before the parser stops recursing and
+     * degrades gracefully (emitting a diagnostic). Guards against stack overflow
+     * on adversarial input such as thousands of unclosed braces. Default 300.
+     */
+    maxDepth?: number;
+}
+/**
+ * Stage 2 of the pipeline. A recursive-descent parser that turns the token
+ * stream into a {@link DocumentNode}. It is fully error-recovering: it never
+ * throws, always returns a tree, and records every problem as a
+ * {@link Diagnostic} so editors and the validator can surface them.
+ */
+declare class Parser {
+    private readonly tokens;
+    private readonly registry;
+    private readonly diagnostics;
+    private readonly utils;
+    private pos;
+    private depth;
+    private readonly maxDepth;
+    private reportedMaxDepth;
+    /** Range of the command currently being built, for builder diagnostics. */
+    private currentRange;
+    constructor(tokens: Token[], options?: ParserOptions);
+    static parse(tokens: Token[], options?: ParserOptions): ParseResult;
+    parse(): ParseResult;
+    private parseContent;
+    private parseContentInner;
+    private parseNode;
+    private parseGroup;
+    private parseScopedSwitch;
+    private parseCommandApplication;
+    private buildCommand;
+    private parseArgs;
+    private parseArg;
+    private parseGreedyArgs;
+    /** Concatenate the raw source of tokens until the matching close at depth 0. */
+    private readRawUntil;
+    private parseEnvironment;
+    private parseEnvBody;
+    private parseEnvEntries;
+    private consumeEnd;
+    /** Read a `{name}` group's raw contents, reporting if it is missing. */
+    private readGroupName;
+    /** Like {@link readGroupName} but returns "" silently when absent. */
+    private tryReadGroupRaw;
+    /**
+     * Recursion-limit fallback: consume the current scope's tokens flatly
+     * (tracking nested braces) without descending, so adversarial deep nesting
+     * cannot overflow the stack. Emits one diagnostic per parse.
+     */
+    private skipFlat;
+    private consumeClose;
+    private at;
+    private atCommand;
+    private skipInlineTrivia;
+    private skipTrivia;
+    private peek;
+    private advance;
+    private previousEnd;
+    private report;
+}
+/** Convenience wrapper. */
+declare function parse(tokens: Token[], options?: ParserOptions): ParseResult;
+
+/**
+ * Register every built-in command and environment into a fresh registry.
+ * The engine calls this once per instance so plugins can extend a private
+ * copy without touching global state.
+ */
+declare function createDefaultRegistry(): CommandRegistry;
+
+/**
+ * Split a comma-separated list, respecting `{...}` and `[...]` nesting so that
+ * a brace-protected comma (`{a, b}`) is not treated as a separator.
+ */
+declare function splitTopLevel(raw: string, sep?: string): string[];
+/** Parse a comma-separated list argument into trimmed, non-empty entries. */
+declare function parseListArg(raw: string): string[];
+/**
+ * Parse a `key=value, key=value` argument into a {@link FieldMap}.
+ *
+ * To keep unquoted values like `location=New York, NY` working, any comma
+ * segment that contains no `=` is merged back into the previous value (the
+ * comma is treated as literal). The first `=` in a segment separates key from
+ * value; later `=` characters are preserved in the value.
+ */
+declare function parseKeyValArg(raw: string): FieldMap;
+
+/** Damerau-ish Levenshtein distance (no transpositions) for "did you mean?". */
+declare function levenshtein(a: string, b: string): number;
+/** Return the closest candidate to `name` within a small edit distance. */
+declare function closestMatch(name: string, candidates: Iterable<string>): string | undefined;
+
+interface ValidateOptions {
+    /** When provided, `\themecolor{token}` tokens are checked against it. */
+    theme?: Theme;
+}
+/**
+ * Stage 3 of the pipeline. Semantic validation over the AST, complementing the
+ * syntactic diagnostics produced by the parser. Pure and side-effect free.
+ */
+declare function validate(ast: DocumentNode, options?: ValidateOptions): Diagnostic[];
+
+/** Return the child nodes of any node, regardless of where they're stored. */
+declare function childrenOf(node: Node): Node[];
+interface VisitOptions {
+    /** Called before visiting children. Return `false` to skip the subtree. */
+    enter?: (node: Node, parent: Node | null) => boolean | void;
+    /** Called after visiting children. */
+    exit?: (node: Node, parent: Node | null) => void;
+}
+/** Depth-first traversal of the tree. */
+declare function walk(root: Node, opts: VisitOptions): void;
+/** Collect every node matching a predicate. */
+declare function collect(root: Node, pred: (n: Node) => boolean): Node[];
+/** Find the innermost node whose range contains `offset`, plus its ancestors. */
+declare function nodePathAt(root: Node, offset: number): Node[];
+
+/**
+ * Best-effort extraction of the plain-text content of a node or node list.
+ * Used to derive section titles, contact values, and accessible labels, and
+ * by `keyval`/`list` argument parsing.
+ */
+declare function flattenText(input: Node | Node[]): string;
+/** Collapse internal runs of whitespace and trim — useful for titles/labels. */
+declare function normalizeWhitespace(s: string): string;
+
+/**
+ * The default ReTeX theme — a clean, ATS-friendly look that reads well both on
+ * screen and in print. All other themes are partial overrides of this one.
+ */
+declare const defaultTheme: Theme;
+
+/** Deep-merge a partial theme over a base theme (sub-objects merged shallowly). */
+declare function resolveTheme(partial?: PartialTheme, base?: Theme): Theme;
+/** A modern, accent-forward theme with underlined section headings. */
+declare const modernTheme: Theme;
+/** A restrained, classic serif theme suited to academic CVs. */
+declare const classicTheme: Theme;
+/** A compact, single-accent theme that maximizes content density. */
+declare const compactTheme: Theme;
+/** Built-in theme presets keyed by name. */
+declare const themes: Record<string, Theme>;
+/** Look up a preset theme by name, falling back to the default. */
+declare function getTheme(name: string): Theme;
+
+/**
+ * Example plugin: `\badge{New}` renders a small pill. Demonstrates a custom
+ * inline command with both HTML and React renderers and no custom AST node.
+ */
+declare const badgePlugin: ReTeXPlugin;
+/**
+ * Example plugin: `\rating{4}` (out of 5) renders filled/empty dots.
+ * Demonstrates a `string` argument and an HTML override.
+ */
+declare const ratingPlugin: ReTeXPlugin;
+
+/**
+ * Security utilities. ReTeX renders untrusted markup to HTML, so every text
+ * node and attribute value must be escaped, and every URL must be vetted
+ * before it reaches an `href`/`src`. The engine never evaluates source as
+ * code — there is no `eval`, `Function`, or template-string interpolation of
+ * user input into executable contexts.
+ */
+/** HTML text-content escaping. Order matters: ampersand first. */
+declare function escapeHtml(input: string): string;
+/** Escaping for values placed inside double-quoted HTML attributes. */
+declare function escapeAttribute(input: string): string;
+interface UrlSanitizeResult {
+    /** Safe URL, or `"#"` when the input was rejected. */
+    safe: string;
+    /** True when the original URL was blocked. */
+    blocked: boolean;
+    /** The detected scheme, when present. */
+    scheme?: string;
+}
+/**
+ * Sanitize a URL for use in an `href`.
+ *
+ *  - Relative URLs and fragments are allowed as-is.
+ *  - Absolute URLs are allowed only for an allow-listed protocol.
+ *  - `javascript:`, `data:`, `vbscript:`, `file:` and friends are blocked.
+ *  - Control characters used to obfuscate the scheme are removed first.
+ */
+declare function sanitizeUrl(input: string): UrlSanitizeResult;
+/**
+ * Validate a CSS color token. Accepts `#rgb`, `#rrggbb`, `#rrggbbaa`,
+ * `rgb()/rgba()/hsl()/hsla()` functional notation, and a curated set of
+ * CSS named colors. Anything else is rejected so it can't smuggle
+ * `url(javascript:…)` or `expression(...)` into a `style` attribute.
+ */
+declare function isSafeColor(value: string): boolean;
+/**
+ * Validate a CSS length/dimension such as `14pt`, `1.5rem`, `40%`, `200px`.
+ * Used for `\fontsize`, `\column` widths and spacing commands.
+ */
+declare function isSafeDimension(value: string): boolean;
+/**
+ * Sanitize a value destined for a CSS property. Returns `undefined` when the
+ * value is unsafe so callers can omit the declaration entirely.
+ */
+declare function sanitizeStyleValue(value: string): string | undefined;
+
+type CompletionKind = "command" | "environment" | "field" | "snippet";
+interface CompletionItem {
+    label: string;
+    kind: CompletionKind;
+    detail?: string;
+    documentation?: string;
+    /** Plain text to insert. */
+    insertText: string;
+    /** LSP-style snippet with `${n:placeholder}` tab stops. */
+    snippet?: string;
+    /** Range the completion replaces (the partial token being typed). */
+    range?: SourceRange;
+}
+interface HoverInfo {
+    /** Markdown documentation. */
+    contents: string;
+    range: SourceRange;
+}
+type SemanticTokenType = "command" | "command-unknown" | "environment" | "brace" | "bracket" | "text" | "comment" | "linebreak" | "argument";
+interface SemanticToken {
+    range: SourceRange;
+    type: SemanticTokenType;
+    /** e.g. `["section"]`, `["typography"]`, derived from the command category. */
+    modifiers: string[];
+}
+interface EditorServiceOptions {
+    registry?: CommandRegistry;
+    theme?: Theme;
+}
+/**
+ * Editor integration surface: everything a code editor (Monaco, CodeMirror, an
+ * LSP server) needs to provide a great ReTeX authoring experience —
+ * completion, hover docs, semantic highlighting, diagnostics, formatting, and
+ * AST inspection. All methods are pure and synchronous.
+ */
+declare class EditorService {
+    private readonly registry;
+    private readonly theme?;
+    constructor(options?: EditorServiceOptions);
+    getDiagnostics(source: string): Diagnostic[];
+    /** Parse and return the AST for inspection / debugging. */
+    inspect(source: string): DocumentNode;
+    format(source: string): string;
+    getCompletions(source: string, offset: number): CompletionItem[];
+    private commandCompletion;
+    private environmentCompletion;
+    /** Suggest field keys when the cursor is inside a `\job/\education/\project{…}`. */
+    private fieldContext;
+    getHover(source: string, offset: number): HoverInfo | null;
+    private commandDoc;
+    private environmentDoc;
+    getSemanticTokens(source: string): SemanticToken[];
+    private readNameAfter;
+    private rangeAt;
+    private positionAt;
+}
+
+/**
+ * Serialize an AST back into canonical ReTeX source. Used by the formatter and
+ * for round-trip testing. Inline content is printed compactly; block content is
+ * separated by blank lines and environments are indented.
+ */
+declare function printDocument(ast: DocumentNode): string;
+
+interface Segment {
+    start: number;
+    end: number;
+    startLine: number;
+}
+interface IncrementalStats {
+    segments: number;
+    cacheHits: number;
+    cacheMisses: number;
+}
+interface IncrementalResult {
+    ast: DocumentNode;
+    diagnostics: Diagnostic[];
+    stats: IncrementalStats;
+}
+/**
+ * Incremental, block-level compiler optimized for editors. The document is
+ * split into balanced blocks at blank-line boundaries; each block's parse is
+ * cached by its exact text. When the user edits one block, only that block is
+ * re-tokenized and re-parsed — every other block is served from cache and
+ * re-positioned with a cheap range shift.
+ *
+ * The produced AST is equivalent to a full parse (top-level blocks separated by
+ * paragraph breaks), making this a drop-in fast path for live preview.
+ */
+declare class IncrementalCompiler {
+    private readonly registry;
+    /** Position-independent parse cache, keyed by exact block text. */
+    private readonly parseCache;
+    /** Position-resolved cache, keyed by `offset:line:text` (already shifted). */
+    private positioned;
+    private hits;
+    private misses;
+    constructor(options?: {
+        registry?: CommandRegistry;
+    });
+    /** Clear all caches (e.g. after registering new commands). */
+    reset(): void;
+    compile(source: string): IncrementalResult;
+}
+/** Split source at blank lines, merging neighbours until each block is balanced. */
+declare function splitBalancedSegments(source: string): Segment[];
+/** Are braces and `\begin`/`\end` balanced in `text`? (Escapes are skipped.) */
+declare function isBalanced(text: string): boolean;
+
+export { type ArgKind, type ArgSpec, ArgumentNode, BLOCK_TYPES, type BuildContext, type BuilderUtils, type CommandCategory, type CommandDefinition, CommandNode, CommandRegistry, type CompileOptions, type CompileResult, type CompletionItem, type CompletionKind, ContactNode, type Diagnostic, DiagnosticCode, DiagnosticSeverity, DocumentNode, EditorService, type EditorServiceOptions, type EngineCommand, type EngineOptions, type EntryParts, type EnvBuildContext, type EnvEntry, type EnvironmentDefinition, FieldMap, type HeadlessBrowser, type HeadlessPage, type HoverInfo, type HtmlRenderContext, type HtmlRenderFn, type HtmlRenderOptions, HtmlRenderer, type IconDefinition, IncrementalCompiler, type IncrementalResult, type IncrementalStats, type JsonRenderOptions, Node, type NodeBuilder, type ParseResult, Parser, type ParserOptions, PartialTheme, type PdfOptions, type PluginHost, type PreambleParts, type PrintOptions, type QuickFix, ReTeXEngine, type ReTeXPlugin, ReactRenderFn, ReactRenderOptions, type Region, SPECIAL_CHARS, SectionNode, type SemanticToken, type SemanticTokenType, SourceRange, Theme, type Token, TokenType, type TokenizeResult, Tokenizer, type UrlSanitizeResult, type ValidateOptions, type VisitOptions, badgePlugin, childrenOf, classicTheme, closestMatch, collect, compactTheme, createDefaultRegistry, createEngine, dateRange, defaultTheme, entryParts, escapeAttribute, escapeHtml, flattenText, getIcon, getTheme, hasIcon, iconNames, iconToSvg, isBalanced, isBlockNode, isSafeColor, isSafeDimension, levenshtein, modernTheme, nodePathAt, normalizeWhitespace, pageCss, parse, parseKeyValArg, parseListArg, printDocument, ratingPlugin, registerIcon, renderHtml, renderHtmlDocument, renderJson, renderPdf, renderPrintHtml, resolveIconName, resolveTheme, sanitizeStyleValue, sanitizeUrl, splitBalancedSegments, splitPreamble, splitTopLevel, themeToCss, themes, toJsonTree, toRegions, tokenize, validate, walk };