@regmisatyam/retex 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,226 +1,7 @@
-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.js';
-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.js';
-
-/**
- * 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;
-}
+import { T as Token, D as Diagnostic, H as HtmlRenderFn, R as ReTeXPlugin, a as ReTeXLibrary, P as PluginHost, E as EngineCommand, b as EnvironmentDefinition, I as IconDefinition, C as CommandRegistry } from './index-DJEasLJc.js';
+export { A as AppliedLibraries, c as ArgKind, d as ArgSpec, B as BLOCK_TYPES, e as BuildContext, f as BuilderUtils, g as CommandCategory, h as CommandDefinition, i as DiagnosticCode, j as DiagnosticSeverity, k as EnvBuildContext, l as EnvEntry, G as GATED_COMMANDS, m as HtmlRenderContext, L as LibraryLookup, N as NodeBuilder, Q as QuickFix, S as SPECIAL_CHARS, n as TokenType, o as applyLibraries, p as builtinLibraries, q as builtinLibraryNames, r as classicLibrary, s as collectLibraryOverrides, t as colorCommands, u as colorsLibrary, v as compactLibrary, w as fontCommands, x as fontStacks, y as fontTheme, z as fontsLibrary, F as getBuiltinLibrary, J as getIcon, K as hasIcon, M as iconNames, O as iconToSvg, U as isBlockNode, V as libraryDiagnostics, W as mergeLibraryTheme, X as modernLibrary, Y as palettes, Z as registerIcon, _ as resolveIconName, $ as resolveLibraryName, a0 as shapeCommands, a1 as shapesLibrary, a2 as usedLibraryNamesFromAst, a3 as usedLibraryNamesFromTokens } from './index-DJEasLJc.js';
+import { T as Theme, D as DocumentNode, N as Node, C as ContactNode, S as SectionNode, F as FieldMap, P as PartialTheme, R as ReactRenderFn, a as ReactRenderOptions, b as SourceRange } from './react-B3tN1iWa.js';
+export { A as ArgumentNode, c as ColorNode, d as ColumnNode, e as ColumnsNode, f as CommandNode, 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 ThemeHeadings, Z as ThemePage, _ as ThemeSpacing, $ as UrlNode, a0 as UsePackageNode, a1 as isNode, a2 as isParent, a3 as mergeRanges, a4 as pos, a5 as range, a6 as rangeContains, a7 as renderReact } from './react-B3tN1iWa.js';
 
 interface TokenizeResult {
     tokens: Token[];
@@ -262,86 +43,22 @@ declare class Tokenizer {
 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.
+ * Generate the stylesheet for a rendered resume from a {@link Theme}.
  *
- * 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`.
+ * Themes are **blank by default**: any field may be `undefined`. The structural
+ * layout (flex rows, list indents, spacing rhythm) is always emitted, while all
+ * *decoration* (accent colors, fonts, uppercased headings, skill chips, section
+ * rules) is driven by CSS custom properties whose fallbacks are neutral. So an
+ * unstyled theme produces a clean, browser-default document, and importing a
+ * library/theme simply fills in those variables.
+ *
+ * Every embedded theme value is vetted before it reaches the stylesheet
+ * (`isSafeColor` / `isSafeDimension` / `sanitizeStyleValue`), so even a
+ * user-supplied theme cannot inject CSS. Each color is also 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"`. */
@@ -350,6 +67,14 @@ interface HtmlRenderOptions {
     overrides?: Map<string, HtmlRenderFn>;
     /** Group leading contact commands into a `<header>`. Default `true`. */
     header?: boolean;
+    /**
+     * Emit source-position attributes (`data-rtx-pos="start:end"` and
+     * `data-rtx-type`) on rendered elements so a live editor can map preview
+     * clicks back to the source and vice-versa (Overleaf-style two-way sync).
+     * Offsets are zero-based UTF-16 code-unit offsets into the original source.
+     * Default `false` — final/exported HTML stays clean and unannotated.
+     */
+    sourceMap?: boolean;
 }
 /**
  * The HTML renderer. Produces clean, semantic, fully-escaped HTML. Every text
@@ -361,6 +86,7 @@ declare class HtmlRenderer {
     private readonly prefix;
     private readonly overrides;
     private readonly useHeader;
+    private readonly sourceMap;
     private readonly ctx;
     constructor(options?: HtmlRenderOptions);
     /** Render the resume body as an HTML fragment (no `<html>`/`<style>`). */
@@ -383,6 +109,16 @@ declare class HtmlRenderer {
     private renderSkills;
     private renderEntry;
     private renderCommand;
+    /**
+     * Source-position attributes for a node — `data-rtx-pos="start:end"` plus a
+     * `data-rtx-type`. Returns an empty string unless `sourceMap` is enabled and
+     * the node carries a range. Powers the live-preview two-way sync: a client
+     * reads these to map a clicked element back to the exact source offsets (and,
+     * in reverse, to find the element for a caret offset).
+     */
+    private src;
+    /** Like {@link src}, but spans a run of inline nodes (merges their ranges). */
+    private srcSpan;
     private icon;
     private dim;
     private cls;
@@ -481,50 +217,15 @@ interface EntryParts {
 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[];
+    /**
+     * Libraries to make available to `\usepackage` *without* activating them
+     * globally. Built-in libraries (`fonts`, `shapes`, `colors`, `modern`, …) are
+     * always available; use this to register your own.
+     */
+    libraries?: ReTeXLibrary[];
     classPrefix?: string;
     /** Max number of compiled documents to cache. Default 64. */
     cacheSize?: number;
@@ -541,13 +242,15 @@ interface CompileOptions {
 }
 /**
  * The ReTeX engine: the single entry point that wires the tokenizer, parser,
- * validator, renderers, theming, plugins, and caching together.
+ * validator, renderers, theming, libraries, plugins, and caching together.
+ *
+ * ReTeX is blank by default. Styling is opt-in via **libraries**, activated
+ * either from the document (`\usepackage{colors}`) or from code
+ * (`engine.use(colorsLibrary)`).
  *
  * ```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);
+ * const engine = new ReTeXEngine();
+ * engine.toHtml("\\usepackage{colors}\n\\textcolor{#7c3aed}{Hi}");
  * ```
  */
 declare class ReTeXEngine implements PluginHost {
@@ -556,11 +259,19 @@ declare class ReTeXEngine implements PluginHost {
     private readonly prefix;
     private readonly htmlOverrides;
     private readonly reactOverrides;
+    /** Libraries available to `\usepackage` (built-ins are resolved separately). */
+    private readonly customLibraries;
     private readonly cache;
     private readonly cacheSize;
     private generation;
     constructor(options?: EngineOptions);
     use(plugin: ReTeXPlugin): this;
+    /**
+     * Register a library so it can be activated with `\usepackage{name}`, without
+     * installing it globally. Built-in libraries are always available; use this
+     * for custom ones.
+     */
+    provideLibrary(library: ReTeXLibrary): this;
     registerCommand(def: EngineCommand): this;
     registerEnvironment(def: EnvironmentDefinition): this;
     registerHtmlRenderer(key: string, fn: HtmlRenderFn): this;
@@ -582,11 +293,22 @@ declare class ReTeXEngine implements PluginHost {
     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;
+    /**
+     * The CSS stylesheet for the active theme. Pass the document (source or AST)
+     * to fold in any libraries it imports via `\usepackage` (so the styles match
+     * `toHtml(input)`); omit it to get the engine theme's stylesheet.
+     */
+    styles(input?: string | DocumentNode): string;
+    /** Resolve a library name against custom libraries first, then built-ins. */
+    private lookupLibrary;
     private astOf;
-    private htmlRenderer;
-    private printOptions;
+    /**
+     * Build the per-document render inputs: the AST, the effective theme (engine
+     * theme + any libraries the document imports), and the merged render
+     * overrides. Library use is recovered from `\usepackage` nodes in the AST, so
+     * this works whether the input was a source string or a pre-parsed document.
+     */
+    private bundle;
     private invalidate;
     private remember;
 }
@@ -666,9 +388,13 @@ declare class Parser {
 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.
+ * Register every built-in (core) command and environment into a fresh registry.
+ * The core is intentionally minimal: document structure, basic emphasis, links,
+ * sections, entries, icons, and the `\usepackage` directive. Visual styling
+ * (color, fonts, shapes) is added by libraries — see `src/library`.
+ *
+ * The engine calls this once per instance so plugins/libraries can extend a
+ * private copy without touching global state.
  */
 declare function createDefaultRegistry(): CommandRegistry;
 
@@ -729,12 +455,32 @@ declare function flattenText(input: Node | Node[]): string;
 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.
+ * The default ReTeX theme is **blank** — it defines no colors, fonts, sizes, or
+ * section decoration. A document rendered with it is a clean, browser-default
+ * page: black text, the user agent's default font, plain section headings, and
+ * no accent colors or rules. This is "just simple editing".
+ *
+ * Visual styling is opt-in. Import a library to populate this theme:
+ *
+ *  - `\usepackage{fonts}`  / `engine.use(fontsLibrary)`  — fonts & sizes
+ *  - `\usepackage{shapes}` / `engine.use(shapesLibrary)` — rules, dividers, spacing
+ *  - `\usepackage{colors}` / `engine.use(colorsLibrary)` — text color & palettes
+ *  - `\usepackage{modern}` / `engine.use(modernTheme)`   — a full styled look
+ *
+ * Every renderer treats theme values as optional and substitutes a neutral,
+ * unstyled fallback when a field is absent, so the blank theme always produces
+ * a readable document.
  */
+declare const blankTheme: Theme;
+/** Alias kept for backwards compatibility — the default theme is the blank one. */
 declare const defaultTheme: Theme;
 
-/** Deep-merge a partial theme over a base theme (sub-objects merged shallowly). */
+/**
+ * Deep-merge a partial theme over a base theme (sub-objects merged shallowly).
+ * The result always has defined (possibly empty) sub-objects, so consumers can
+ * safely read `theme.colors`, `theme.fonts`, … without null checks even when
+ * the base is the blank theme.
+ */
 declare function resolveTheme(partial?: PartialTheme, base?: Theme): Theme;
 /** A modern, accent-forward theme with underlined section headings. */
 declare const modernTheme: Theme;
@@ -742,9 +488,13 @@ declare const modernTheme: Theme;
 declare const classicTheme: Theme;
 /** A compact, single-accent theme that maximizes content density. */
 declare const compactTheme: Theme;
-/** Built-in theme presets keyed by name. */
+/**
+ * Built-in theme presets keyed by name. `default` and `blank` both map to the
+ * unstyled theme; the styled presets are opt-in (import them, or activate them
+ * with `\usepackage{modern}` etc.).
+ */
 declare const themes: Record<string, Theme>;
-/** Look up a preset theme by name, falling back to the default. */
+/** Look up a preset theme by name, falling back to the blank default. */
 declare function getTheme(name: string): Theme;
 
 /**
@@ -832,6 +582,11 @@ interface SemanticToken {
 interface EditorServiceOptions {
     registry?: CommandRegistry;
     theme?: Theme;
+    /**
+     * Custom libraries addressable via `\usepackage{name}`. Built-in libraries
+     * (`fonts`, `shapes`, `colors`, `modern`, …) are always available.
+     */
+    libraries?: ReTeXLibrary[];
 }
 /**
  * Editor integration surface: everything a code editor (Monaco, CodeMirror, an
@@ -842,7 +597,11 @@ interface EditorServiceOptions {
 declare class EditorService {
     private readonly registry;
     private readonly theme?;
+    private readonly customLibraries;
     constructor(options?: EditorServiceOptions);
+    private lookupLibrary;
+    /** Build a registry that includes the libraries the source imports. */
+    private registryFor;
     getDiagnostics(source: string): Diagnostic[];
     /** Parse and return the AST for inspection / debugging. */
     inspect(source: string): DocumentNode;
@@ -868,6 +627,83 @@ declare class EditorService {
  */
 declare function printDocument(ast: DocumentNode): string;
 
+/**
+ * Two-way preview sync — the editor-agnostic half of ReTeX's Overleaf-style
+ * "click the preview, jump to the source" feature (and its reverse).
+ *
+ * The {@link HtmlRenderer} `sourceMap` option stamps every meaningful element
+ * with a `data-rtx-pos="start:end"` attribute (zero-based UTF-16 offsets into
+ * the source) and a `data-rtx-type`. These helpers are the small, dependency-
+ * free glue a host editor uses on top of those attributes:
+ *
+ *  - **Preview → code** (reverse sync): on a click in the preview, read the
+ *    nearest annotated ancestor's span and select/scroll to it in the editor.
+ *
+ *    ```ts
+ *    preview.addEventListener("click", (e) => {
+ *      const span = closestSourcePos(e.target as Element);
+ *      if (span) {
+ *        textarea.focus();
+ *        textarea.setSelectionRange(span.start, span.end);
+ *      }
+ *    });
+ *    ```
+ *
+ *  - **Code → preview** (forward sync): on caret move, find the tightest
+ *    element whose span contains the caret offset and highlight it.
+ *
+ *    ```ts
+ *    const el = pickElementForOffset(
+ *      preview.querySelectorAll(`[${SOURCE_POS_ATTR}]`),
+ *      textarea.selectionStart,
+ *    );
+ *    el?.scrollIntoView({ block: "center" });
+ *    ```
+ *
+ * Every function is pure and works with any object exposing `getAttribute`
+ * (real DOM elements, or test doubles), so this module never touches `document`
+ * and stays usable outside the browser.
+ */
+/** Attribute carrying a `"start:end"` source-offset span. */
+declare const SOURCE_POS_ATTR = "data-rtx-pos";
+/** Attribute carrying the originating AST node type (e.g. `"section"`). */
+declare const SOURCE_TYPE_ATTR = "data-rtx-type";
+/** A half-open `[start, end)` span of UTF-16 offsets into the source text. */
+interface SourceSpan {
+    start: number;
+    end: number;
+}
+/** The minimal shape these helpers need from a preview element. */
+interface AttrElement {
+    getAttribute(name: string): string | null;
+}
+/** An element that can also walk up to its nearest matching ancestor. */
+interface ClosestElement extends AttrElement {
+    closest(selectors: string): (AttrElement & ClosestElement) | null;
+}
+/** Parse a `"start:end"` attribute value into a {@link SourceSpan}. */
+declare function parseSourcePos(value: string | null | undefined): SourceSpan | null;
+/** Read the {@link SOURCE_POS_ATTR} span off a single element. */
+declare function readSourcePos(el: AttrElement | null | undefined): SourceSpan | null;
+/** Read the {@link SOURCE_TYPE_ATTR} off a single element. */
+declare function readSourceType(el: AttrElement | null | undefined): string | null;
+/**
+ * Reverse sync: from a clicked element, walk up to the nearest annotated
+ * ancestor and return its span. Uses the DOM `closest` when available.
+ */
+declare function closestSourcePos(el: ClosestElement | null | undefined): SourceSpan | null;
+/** Width of a span; used to prefer the most specific (smallest) match. */
+declare function spanLength(span: SourceSpan): number;
+/** Whether `offset` falls within `span` (both ends inclusive). */
+declare function spanContains(span: SourceSpan, offset: number): boolean;
+/**
+ * Forward sync: from a set of annotated elements, return the single tightest
+ * one whose span contains `offset` — i.e. the most specific element under the
+ * caret. Ties on width are broken toward the later span (the deepest/innermost
+ * element rendered). Returns `null` when no span contains the offset.
+ */
+declare function pickElementForOffset<T extends AttrElement>(elements: Iterable<T>, offset: number): T | null;
+
 interface Segment {
     start: number;
     end: number;
@@ -895,6 +731,7 @@ interface IncrementalResult {
  */
 declare class IncrementalCompiler {
     private readonly registry;
+    private readonly lookupLibrary;
     /** Position-independent parse cache, keyed by exact block text. */
     private readonly parseCache;
     /** Position-resolved cache, keyed by `offset:line:text` (already shifted). */
@@ -903,6 +740,7 @@ declare class IncrementalCompiler {
     private misses;
     constructor(options?: {
         registry?: CommandRegistry;
+        libraries?: ReTeXLibrary[];
     });
     /** Clear all caches (e.g. after registering new commands). */
     reset(): void;
@@ -913,4 +751,4 @@ 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 };
+export { type AttrElement, type ClosestElement, CommandRegistry, type CompileOptions, type CompileResult, type CompletionItem, type CompletionKind, ContactNode, Diagnostic, DocumentNode, EditorService, type EditorServiceOptions, EngineCommand, type EngineOptions, type EntryParts, EnvironmentDefinition, FieldMap, type HeadlessBrowser, type HeadlessPage, type HoverInfo, HtmlRenderFn, type HtmlRenderOptions, HtmlRenderer, IconDefinition, IncrementalCompiler, type IncrementalResult, type IncrementalStats, type JsonRenderOptions, Node, type ParseResult, Parser, type ParserOptions, PartialTheme, type PdfOptions, PluginHost, type PreambleParts, type PrintOptions, ReTeXEngine, ReTeXLibrary, ReTeXPlugin, ReactRenderFn, ReactRenderOptions, type Region, SOURCE_POS_ATTR, SOURCE_TYPE_ATTR, SectionNode, type SemanticToken, type SemanticTokenType, SourceRange, type SourceSpan, Theme, Token, type TokenizeResult, Tokenizer, type UrlSanitizeResult, type ValidateOptions, type VisitOptions, badgePlugin, blankTheme, childrenOf, classicTheme, closestMatch, closestSourcePos, collect, compactTheme, createDefaultRegistry, createEngine, dateRange, defaultTheme, entryParts, escapeAttribute, escapeHtml, flattenText, getTheme, isBalanced, isSafeColor, isSafeDimension, levenshtein, modernTheme, nodePathAt, normalizeWhitespace, pageCss, parse, parseKeyValArg, parseListArg, parseSourcePos, pickElementForOffset, printDocument, ratingPlugin, readSourcePos, readSourceType, renderHtml, renderHtmlDocument, renderJson, renderPdf, renderPrintHtml, resolveTheme, sanitizeStyleValue, sanitizeUrl, spanContains, spanLength, splitBalancedSegments, splitPreamble, splitTopLevel, themeToCss, themes, toJsonTree, toRegions, tokenize, validate, walk };