@regmisatyam/retex 0.1.0 → 0.2.0

package/dist/index.js

@@ -69,6 +69,8 @@ var DiagnosticCode = /* @__PURE__ */ ((DiagnosticCode2) => {
   DiagnosticCode2["CommandOutsideContext"] = "RTX4001";
   DiagnosticCode2["UnknownIcon"] = "RTX4002";
   DiagnosticCode2["UnknownThemeColor"] = "RTX4003";
+  DiagnosticCode2["UnknownLibrary"] = "RTX4004";
+  DiagnosticCode2["LibraryRequired"] = "RTX4005";
   DiagnosticCode2["UnsafeUrlBlocked"] = "RTX5001";
   return DiagnosticCode2;
 })(DiagnosticCode || {});
@@ -314,103 +316,6 @@ function parseKeyValArg(raw) {
   return fields;
 }
 
-// src/security/sanitize.ts
-function escapeHtml(input) {
-  return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
-}
-function escapeAttribute(input) {
-  return escapeHtml(input);
-}
-var SAFE_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:", "mailto:", "tel:", "ftp:", "sms:"]);
-var SCHEME_RE = /^([a-z][a-z0-9+.-]*):/i;
-var CONTROL_CHARS_RE = /[\x00-\x1f\x7f]/g;
-function sanitizeUrl(input) {
-  const raw = String(input ?? "").trim();
-  const cleaned = raw.replace(CONTROL_CHARS_RE, "");
-  const match = SCHEME_RE.exec(cleaned);
-  if (!match) {
-    return { safe: cleaned, blocked: false };
-  }
-  const scheme = match[1].toLowerCase() + ":";
-  if (SAFE_PROTOCOLS.has(scheme)) {
-    return { safe: cleaned, blocked: false, scheme };
-  }
-  return { safe: "#", blocked: true, scheme };
-}
-function isSafeColor(value) {
-  const v = value.trim();
-  if (/^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(v)) return true;
-  if (/^(rgb|rgba|hsl|hsla)\(\s*[0-9.,%\s/]+\)$/i.test(v)) return true;
-  return CSS_NAMED_COLORS.has(v.toLowerCase());
-}
-function isSafeDimension(value) {
-  return /^-?\d*\.?\d+(px|pt|em|rem|ex|ch|vw|vh|vmin|vmax|cm|mm|in|pc|%|fr)?$/.test(
-    value.trim()
-  );
-}
-function sanitizeStyleValue(value) {
-  const v = value.trim();
-  if (/[<>;{}]/.test(v) || /expression|url\s*\(|javascript:/i.test(v)) {
-    return void 0;
-  }
-  return v;
-}
-var CSS_NAMED_COLORS = /* @__PURE__ */ new Set([
-  "black",
-  "silver",
-  "gray",
-  "grey",
-  "white",
-  "maroon",
-  "red",
-  "purple",
-  "fuchsia",
-  "green",
-  "lime",
-  "olive",
-  "yellow",
-  "navy",
-  "blue",
-  "teal",
-  "aqua",
-  "cyan",
-  "magenta",
-  "orange",
-  "pink",
-  "brown",
-  "gold",
-  "indigo",
-  "violet",
-  "tan",
-  "beige",
-  "ivory",
-  "coral",
-  "salmon",
-  "khaki",
-  "crimson",
-  "turquoise",
-  "lavender",
-  "plum",
-  "orchid",
-  "slateblue",
-  "slategray",
-  "steelblue",
-  "skyblue",
-  "royalblue",
-  "midnightblue",
-  "darkblue",
-  "darkgreen",
-  "darkred",
-  "darkgray",
-  "darkgrey",
-  "lightgray",
-  "lightgrey",
-  "lightblue",
-  "transparent",
-  "currentcolor",
-  "inherit"
-]);
-
 // src/icons/icons.ts
 var ICONS = {
   github: {
@@ -491,10 +396,10 @@ function iconToSvg(name, opts = {}) {
   const def = getIcon(name);
   if (!def) return null;
   const size = opts.size ?? "1em";
-  const dim = typeof size === "number" ? `${size}` : size;
+  const dim2 = typeof size === "number" ? `${size}` : size;
   const cls = opts.className ? ` class="${opts.className}"` : "";
   const fillOrStroke = def.stroked ? 'fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"' : 'fill="currentColor"';
-  return `<svg${cls} width="${dim}" height="${dim}" viewBox="0 0 24 24" ${fillOrStroke} role="img" aria-hidden="true" focusable="false">${def.body}</svg>`;
+  return `<svg${cls} width="${dim2}" height="${dim2}" viewBox="0 0 24 24" ${fillOrStroke} role="img" aria-hidden="true" focusable="false">${def.body}</svg>`;
 }
 
 // src/parser/builtins.ts
@@ -506,113 +411,12 @@ var mark = (name, type, summary) => ({
   example: `\\${name}{...}`,
   build: ({ args }) => ({ type, children: args[0]?.children ?? [] })
 });
-var scaleSwitch = (name, scale) => ({
-  name,
-  category: "switch",
-  scoped: true,
-  summary: `Set the font size to "${name}" for the rest of the group.`,
-  example: `{\\${name} ...}`,
-  build: ({ scope }) => ({ type: "fontscale", scale, children: scope })
-});
 var TYPOGRAPHY = [
   mark("textbf", "bold", "Bold text."),
   mark("textit", "italic", "Italic text."),
   mark("emph", "italic", "Emphasized (italic) text."),
   mark("underline", "underline", "Underlined text."),
   mark("sout", "strike", "Struck-through text."),
-  {
-    name: "textcolor",
-    category: "inline",
-    args: [
-      { kind: "string", name: "color", format: "color" },
-      { kind: "content", name: "content" }
-    ],
-    summary: "Color text with a hex/named color.",
-    example: "\\textcolor{#2563eb}{OpenAI}",
-    build: ({ args, utils, report }) => {
-      const color = utils.textOf(args[0]).trim();
-      if (color && !isSafeColor(color)) {
-        report({
-          severity: "warning" /* Warning */,
-          code: "RTX3001" /* InvalidColor */,
-          message: `"${color}" is not a recognized color; it will be ignored.`,
-          range: args[0]?.range ?? ZERO_RANGE
-        });
-      }
-      return {
-        type: "color",
-        color: isSafeColor(color) ? color : "",
-        children: args[1]?.children ?? []
-      };
-    }
-  },
-  {
-    name: "fontsize",
-    category: "inline",
-    args: [
-      { kind: "string", name: "size", format: "dimension" },
-      { kind: "content", name: "content" }
-    ],
-    summary: "Set an explicit font size for the wrapped content.",
-    example: "\\fontsize{14pt}{Custom Size}",
-    build: ({ args, utils, report }) => {
-      const size = utils.textOf(args[0]).trim();
-      if (size && !isSafeDimension(size)) {
-        report({
-          severity: "warning" /* Warning */,
-          code: "RTX3003" /* InvalidDimension */,
-          message: `"${size}" is not a valid dimension.`,
-          range: args[0]?.range ?? ZERO_RANGE
-        });
-      }
-      return {
-        type: "fontsize",
-        size: isSafeDimension(size) ? size : "1em",
-        children: args[1]?.children ?? []
-      };
-    }
-  },
-  {
-    name: "fontfamily",
-    category: "inline",
-    args: [
-      { kind: "string", name: "family" },
-      { kind: "content", name: "content" }
-    ],
-    summary: "Set the font family for the wrapped content.",
-    example: "\\fontfamily{Georgia}{Serif text}",
-    build: ({ args, utils }) => ({
-      type: "fontfamily",
-      family: utils.textOf(args[0]).trim() || "inherit",
-      children: args[1]?.children ?? []
-    })
-  },
-  {
-    name: "themecolor",
-    category: "inline",
-    args: [
-      { kind: "string", name: "token" },
-      { kind: "content", name: "content" }
-    ],
-    summary: "Color text using a token from the active theme.",
-    example: "\\themecolor{primary}{Highlighted}",
-    build: ({ args, utils }) => ({
-      type: "themecolor",
-      token: utils.textOf(args[0]).trim() || "primary",
-      children: args[1]?.children ?? []
-    })
-  },
-  scaleSwitch("small", "small"),
-  scaleSwitch("large", "large"),
-  scaleSwitch("Large", "Large"),
-  scaleSwitch("Huge", "Huge"),
-  {
-    name: "normalsize",
-    category: "switch",
-    scoped: true,
-    summary: "Reset the font size to the document base size.",
-    build: ({ scope }) => ({ type: "fontscale", scale: "normal", children: scope })
-  },
   {
     name: "bfseries",
     category: "switch",
@@ -626,16 +430,30 @@ var TYPOGRAPHY = [
     scoped: true,
     summary: "Switch to italic for the rest of the group.",
     build: ({ scope }) => ({ type: "italic", children: scope })
+  }
+];
+var DIRECTIVES = [
+  {
+    name: "usepackage",
+    category: "meta",
+    args: [{ kind: "list", name: "libraries" }],
+    summary: "Import styling libraries (fonts, shapes, colors, modern, \u2026).",
+    documentation: "ReTeX is blank by default. `\\usepackage{...}` activates one or more libraries for this document so their commands and styling become available. Multiple libraries can be comma-separated.",
+    example: "\\usepackage{shapes, colors}",
+    build: ({ args }) => ({
+      type: "usepackage",
+      names: parseListArg(args[0]?.raw ?? "")
+    })
   },
   {
-    name: "ttfamily",
-    category: "switch",
-    scoped: true,
-    summary: "Switch to a monospace font for the rest of the group.",
-    build: ({ scope }) => ({
-      type: "fontfamily",
-      family: "monospace",
-      children: scope
+    name: "use",
+    category: "meta",
+    args: [{ kind: "list", name: "libraries" }],
+    summary: "Alias for \\usepackage \u2014 import styling libraries.",
+    example: "\\use{fonts}",
+    build: ({ args }) => ({
+      type: "usepackage",
+      names: parseListArg(args[0]?.raw ?? "")
     })
   }
 ];
@@ -819,42 +637,6 @@ var PRIMITIVES = [
     summary: "An explicit line break.",
     build: () => ({ type: "linebreak" })
   },
-  {
-    name: "hrule",
-    category: "block",
-    summary: "A horizontal rule / divider.",
-    build: () => ({ type: "rule" })
-  },
-  {
-    name: "divider",
-    category: "block",
-    summary: "A horizontal rule / divider.",
-    build: () => ({ type: "rule" })
-  },
-  {
-    name: "vspace",
-    category: "block",
-    args: [{ kind: "string", name: "size", format: "dimension" }],
-    summary: "Vertical space.",
-    example: "\\vspace{1em}",
-    build: ({ args, utils }) => ({
-      type: "space",
-      axis: "vertical",
-      size: utils.textOf(args[0]).trim() || "1em"
-    })
-  },
-  {
-    name: "hspace",
-    category: "inline",
-    args: [{ kind: "string", name: "size", format: "dimension" }],
-    summary: "Horizontal space.",
-    example: "\\hspace{1em}",
-    build: ({ args, utils }) => ({
-      type: "space",
-      axis: "horizontal",
-      size: utils.textOf(args[0]).trim() || "1em"
-    })
-  },
   // `\item` and `\column` are consumed by their environments; they are
   // registered so they are recognized (and so the validator can flag misuse
   // outside the right environment) but have no standalone builder.
@@ -872,6 +654,13 @@ var PRIMITIVES = [
     example: "\\column{40%}"
   }
 ];
+function entryRange(e) {
+  const start = e.marker.range?.start;
+  if (!start) return void 0;
+  let end = e.marker.range?.end;
+  for (const n of e.content) if (n.range) end = n.range.end;
+  return end ? { start, end } : void 0;
+}
 var ENVIRONMENTS = [
   {
     name: "itemize",
@@ -883,7 +672,11 @@ var ENVIRONMENTS = [
       type: "list",
       kind: "itemize",
       items: (entries ?? []).map(
-        (e) => ({ type: "item", children: e.content })
+        (e) => ({
+          type: "item",
+          children: e.content,
+          range: entryRange(e)
+        })
       )
     })
   },
@@ -897,7 +690,11 @@ var ENVIRONMENTS = [
       type: "list",
       kind: "enumerate",
       items: (entries ?? []).map(
-        (e) => ({ type: "item", children: e.content })
+        (e) => ({
+          type: "item",
+          children: e.content,
+          range: entryRange(e)
+        })
       )
     })
   },
@@ -911,7 +708,7 @@ var ENVIRONMENTS = [
       type: "columns",
       columns: (entries ?? []).map((e) => {
         const width = utils.textOf(e.marker.args[0]).trim() || "auto";
-        return { type: "column", width, children: e.content };
+        return { type: "column", width, children: e.content, range: entryRange(e) };
       })
     })
   },
@@ -930,6 +727,7 @@ function createDefaultRegistry() {
   const registry = new CommandRegistry();
   for (const def of [
     ...TYPOGRAPHY,
+    ...DIRECTIVES,
     ...LINKS,
     ...SECTIONS,
     ...CONTACT,
@@ -1015,25 +813,122 @@ function normalizeWhitespace(s) {
   return s.replace(/\s+/g, " ").trim();
 }
 
-// src/parser/suggest.ts
-function levenshtein(a, b) {
-  const m = a.length;
-  const n = b.length;
-  if (m === 0) return n;
-  if (n === 0) return m;
-  let prev = new Array(n + 1);
-  let curr = new Array(n + 1);
-  for (let j = 0; j <= n; j++) prev[j] = j;
-  for (let i = 1; i <= m; i++) {
-    curr[0] = i;
-    for (let j = 1; j <= n; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
-    }
-    [prev, curr] = [curr, prev];
-  }
-  return prev[n];
-}
+// src/security/sanitize.ts
+function escapeHtml(input) {
+  return input.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function escapeAttribute(input) {
+  return escapeHtml(input);
+}
+var SAFE_PROTOCOLS = /* @__PURE__ */ new Set(["http:", "https:", "mailto:", "tel:", "ftp:", "sms:"]);
+var SCHEME_RE = /^([a-z][a-z0-9+.-]*):/i;
+var CONTROL_CHARS_RE = /[\x00-\x1f\x7f]/g;
+function sanitizeUrl(input) {
+  const raw = String(input ?? "").trim();
+  const cleaned = raw.replace(CONTROL_CHARS_RE, "");
+  const match = SCHEME_RE.exec(cleaned);
+  if (!match) {
+    return { safe: cleaned, blocked: false };
+  }
+  const scheme = match[1].toLowerCase() + ":";
+  if (SAFE_PROTOCOLS.has(scheme)) {
+    return { safe: cleaned, blocked: false, scheme };
+  }
+  return { safe: "#", blocked: true, scheme };
+}
+function isSafeColor(value) {
+  const v = value.trim();
+  if (/^#([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(v)) return true;
+  if (/^(rgb|rgba|hsl|hsla)\(\s*[0-9.,%\s/]+\)$/i.test(v)) return true;
+  return CSS_NAMED_COLORS.has(v.toLowerCase());
+}
+function isSafeDimension(value) {
+  return /^-?\d*\.?\d+(px|pt|em|rem|ex|ch|vw|vh|vmin|vmax|cm|mm|in|pc|%|fr)?$/.test(
+    value.trim()
+  );
+}
+function sanitizeStyleValue(value) {
+  const v = value.trim();
+  if (/[<>;{}]/.test(v) || /expression|url\s*\(|javascript:/i.test(v)) {
+    return void 0;
+  }
+  return v;
+}
+var CSS_NAMED_COLORS = /* @__PURE__ */ new Set([
+  "black",
+  "silver",
+  "gray",
+  "grey",
+  "white",
+  "maroon",
+  "red",
+  "purple",
+  "fuchsia",
+  "green",
+  "lime",
+  "olive",
+  "yellow",
+  "navy",
+  "blue",
+  "teal",
+  "aqua",
+  "cyan",
+  "magenta",
+  "orange",
+  "pink",
+  "brown",
+  "gold",
+  "indigo",
+  "violet",
+  "tan",
+  "beige",
+  "ivory",
+  "coral",
+  "salmon",
+  "khaki",
+  "crimson",
+  "turquoise",
+  "lavender",
+  "plum",
+  "orchid",
+  "slateblue",
+  "slategray",
+  "steelblue",
+  "skyblue",
+  "royalblue",
+  "midnightblue",
+  "darkblue",
+  "darkgreen",
+  "darkred",
+  "darkgray",
+  "darkgrey",
+  "lightgray",
+  "lightgrey",
+  "lightblue",
+  "transparent",
+  "currentcolor",
+  "inherit"
+]);
+
+// src/parser/suggest.ts
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = new Array(n + 1);
+  let curr = new Array(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost);
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[n];
+}
 function closestMatch(name, candidates) {
   let best;
   let bestDist = Infinity;
@@ -1504,231 +1399,688 @@ var Parser = class _Parser {
       this.advance();
     }
   }
-  skipTrivia() {
-    while (this.at("Whitespace" /* Whitespace */) || this.at("Comment" /* Comment */) || this.at("ParBreak" /* ParBreak */)) {
-      this.advance();
+  skipTrivia() {
+    while (this.at("Whitespace" /* Whitespace */) || this.at("Comment" /* Comment */) || this.at("ParBreak" /* ParBreak */)) {
+      this.advance();
+    }
+  }
+  peek(k = 0) {
+    return this.tokens[this.pos + k] ?? this.tokens[this.tokens.length - 1];
+  }
+  advance() {
+    const t = this.peek();
+    if (this.pos < this.tokens.length - 1) this.pos++;
+    return t;
+  }
+  previousEnd() {
+    return this.tokens[this.pos - 1]?.range.end ?? this.peek().range.start;
+  }
+  report(d) {
+    this.diagnostics.push({ ...d, source: "parser" });
+  }
+};
+function parse(tokens, options) {
+  return Parser.parse(tokens, options);
+}
+
+// src/validator/validator.ts
+var ZERO_RANGE3 = {
+  start: { offset: 0, line: 1, column: 1 },
+  end: { offset: 0, line: 1, column: 1 }
+};
+function validate(ast, options = {}) {
+  const diagnostics = [];
+  const report = (d) => {
+    diagnostics.push({ ...d, source: "validator" });
+  };
+  walk(ast, {
+    enter(node) {
+      switch (node.type) {
+        case "command":
+          checkStrayCommand(node, report);
+          break;
+        case "section":
+          if (node.title.trim() === "") {
+            report({
+              severity: "warning" /* Warning */,
+              code: "RTX3006" /* EmptyArgument */,
+              message: "Section heading is empty.",
+              range: node.range ?? ZERO_RANGE3
+            });
+          }
+          break;
+        case "contact":
+          if (node.value.trim() === "") {
+            report({
+              severity: "warning" /* Warning */,
+              code: "RTX3006" /* EmptyArgument */,
+              message: `\\${node.field} is empty.`,
+              range: node.range ?? ZERO_RANGE3
+            });
+          }
+          break;
+        case "themecolor":
+          if (options.theme?.colors && !(node.token in options.theme.colors)) {
+            report({
+              severity: "warning" /* Warning */,
+              code: "RTX4003" /* UnknownThemeColor */,
+              message: `Theme color "${node.token}" is not defined in theme "${options.theme.name}".`,
+              range: node.range ?? ZERO_RANGE3
+            });
+          }
+          break;
+        case "skills":
+          if (node.items.length === 0) {
+            report({
+              severity: "info" /* Info */,
+              code: "RTX3006" /* EmptyArgument */,
+              message: "\\skills has no entries.",
+              range: node.range ?? ZERO_RANGE3
+            });
+          }
+          break;
+      }
+    }
+  });
+  return diagnostics;
+}
+function checkStrayCommand(node, report) {
+  if (node.name === "item") {
+    report({
+      severity: "error" /* Error */,
+      code: "RTX4001" /* CommandOutsideContext */,
+      message: "\\item must appear inside an itemize or enumerate environment.",
+      range: node.range ?? ZERO_RANGE3
+    });
+  } else if (node.name === "column") {
+    report({
+      severity: "error" /* Error */,
+      code: "RTX4001" /* CommandOutsideContext */,
+      message: "\\column must appear inside a columns environment.",
+      range: node.range ?? ZERO_RANGE3
+    });
+  }
+}
+
+// src/theme/default.ts
+var blankTheme = {
+  name: "blank"
+};
+var defaultTheme = blankTheme;
+
+// src/theme/themes.ts
+function resolveTheme(partial, base = defaultTheme) {
+  return {
+    name: partial?.name ?? base.name,
+    colors: { ...base.colors, ...partial?.colors },
+    fonts: { ...base.fonts, ...partial?.fonts },
+    fontSizes: { ...base.fontSizes, ...partial?.fontSizes },
+    spacing: { ...base.spacing, ...partial?.spacing },
+    page: { ...base.page, ...partial?.page },
+    sectionStyle: partial?.sectionStyle ?? base.sectionStyle,
+    headings: { ...base.headings, ...partial?.headings }
+  };
+}
+var styledBase = {
+  fonts: {
+    heading: '"Inter", "Helvetica Neue", Helvetica, Arial, sans-serif',
+    body: '"Inter", "Helvetica Neue", Helvetica, Arial, sans-serif',
+    mono: '"JetBrains Mono", "SF Mono", "Fira Code", Consolas, monospace'
+  },
+  fontSizes: {
+    base: "10.5pt",
+    small: "9pt",
+    large: "12pt",
+    Large: "15pt",
+    Huge: "22pt",
+    name: "26pt",
+    section: "13pt"
+  },
+  spacing: { unit: "4px", section: "1.1rem", item: "0.28rem", page: "0.55in" },
+  page: { size: "Letter", margin: "0.55in", maxWidth: "8.5in" },
+  headings: { transform: "uppercase", tracking: "0.06em", nameTracking: "-0.01em" }
+};
+var modernTheme = resolveTheme({
+  ...styledBase,
+  name: "modern",
+  colors: {
+    primary: "#7c3aed",
+    secondary: "#64748b",
+    text: "#111827",
+    muted: "#64748b",
+    background: "#ffffff",
+    border: "#e2e8f0",
+    accent: "#7c3aed"
+  },
+  sectionStyle: "underline"
+});
+var classicTheme = resolveTheme({
+  ...styledBase,
+  name: "classic",
+  colors: {
+    primary: "#111827",
+    secondary: "#4b5563",
+    text: "#1e293b",
+    muted: "#4b5563",
+    background: "#ffffff",
+    border: "#cbd5e1",
+    accent: "#111827"
+  },
+  fonts: {
+    heading: 'Georgia, "Times New Roman", serif',
+    body: 'Georgia, "Times New Roman", serif',
+    mono: 'Consolas, "Courier New", monospace'
+  },
+  sectionStyle: "rule"
+});
+var compactTheme = resolveTheme({
+  ...styledBase,
+  name: "compact",
+  colors: {
+    primary: "#2563eb",
+    secondary: "#64748b",
+    text: "#1e293b",
+    muted: "#64748b",
+    background: "#ffffff",
+    border: "#e2e8f0",
+    accent: "#2563eb"
+  },
+  fontSizes: {
+    base: "9.5pt",
+    small: "8pt",
+    large: "11pt",
+    Large: "13pt",
+    Huge: "18pt",
+    name: "20pt",
+    section: "11pt"
+  },
+  spacing: { unit: "3px", section: "0.7rem", item: "0.18rem", page: "0.4in" },
+  sectionStyle: "bar"
+});
+var themes = {
+  blank: blankTheme,
+  default: blankTheme,
+  modern: modernTheme,
+  classic: classicTheme,
+  compact: compactTheme
+};
+function getTheme(name) {
+  return themes[name] ?? defaultTheme;
+}
+
+// src/library/colors.ts
+var zero2 = { offset: 0, line: 1, column: 1 };
+var ZERO_RANGE4 = { start: zero2, end: zero2 };
+var colorCommands = [
+  {
+    name: "textcolor",
+    category: "inline",
+    args: [
+      { kind: "string", name: "color", format: "color" },
+      { kind: "content", name: "content" }
+    ],
+    summary: "Color text with a hex/named color.",
+    example: "\\textcolor{#2563eb}{OpenAI}",
+    build: ({ args, utils, report }) => {
+      const color2 = utils.textOf(args[0]).trim();
+      if (color2 && !isSafeColor(color2)) {
+        report({
+          severity: "warning" /* Warning */,
+          code: "RTX3001" /* InvalidColor */,
+          message: `"${color2}" is not a recognized color; it will be ignored.`,
+          range: args[0]?.range ?? ZERO_RANGE4
+        });
+      }
+      return {
+        type: "color",
+        color: isSafeColor(color2) ? color2 : "",
+        children: args[1]?.children ?? []
+      };
+    }
+  },
+  {
+    name: "themecolor",
+    category: "inline",
+    args: [
+      { kind: "string", name: "token" },
+      { kind: "content", name: "content" }
+    ],
+    summary: "Color text using a token from the active theme.",
+    example: "\\themecolor{primary}{Highlighted}",
+    build: ({ args, utils }) => ({
+      type: "themecolor",
+      token: utils.textOf(args[0]).trim() || "primary",
+      children: args[1]?.children ?? []
+    })
+  }
+];
+var palettes = {
+  slate: {
+    primary: "#0f172a",
+    secondary: "#475569",
+    text: "#1e293b",
+    muted: "#64748b",
+    border: "#cbd5e1",
+    accent: "#0f172a"
+  },
+  blue: {
+    primary: "#2563eb",
+    secondary: "#64748b",
+    text: "#1e293b",
+    muted: "#64748b",
+    border: "#e2e8f0",
+    accent: "#2563eb"
+  },
+  violet: {
+    primary: "#7c3aed",
+    secondary: "#6b7280",
+    text: "#111827",
+    muted: "#6b7280",
+    border: "#e5e7eb",
+    accent: "#7c3aed"
+  },
+  emerald: {
+    primary: "#059669",
+    secondary: "#6b7280",
+    text: "#111827",
+    muted: "#6b7280",
+    border: "#d1fae5",
+    accent: "#059669"
+  },
+  rose: {
+    primary: "#e11d48",
+    secondary: "#6b7280",
+    text: "#111827",
+    muted: "#6b7280",
+    border: "#fecdd3",
+    accent: "#e11d48"
+  },
+  amber: {
+    primary: "#d97706",
+    secondary: "#6b7280",
+    text: "#111827",
+    muted: "#6b7280",
+    border: "#fde68a",
+    accent: "#d97706"
+  }
+};
+var colorsLibrary = {
+  name: "colors",
+  summary: "Text color (\\textcolor, \\themecolor) and named palettes.",
+  commands: colorCommands
+};
+
+// src/library/fonts.ts
+var zero3 = { offset: 0, line: 1, column: 1 };
+var ZERO_RANGE5 = { start: zero3, end: zero3 };
+var scaleSwitch = (name, scale) => ({
+  name,
+  category: "switch",
+  scoped: true,
+  summary: `Set the font size to "${name}" for the rest of the group.`,
+  example: `{\\${name} ...}`,
+  build: ({ scope }) => ({ type: "fontscale", scale, children: scope })
+});
+var fontCommands = [
+  {
+    name: "fontsize",
+    category: "inline",
+    args: [
+      { kind: "string", name: "size", format: "dimension" },
+      { kind: "content", name: "content" }
+    ],
+    summary: "Set an explicit font size for the wrapped content.",
+    example: "\\fontsize{14pt}{Custom Size}",
+    build: ({ args, utils, report }) => {
+      const size = utils.textOf(args[0]).trim();
+      if (size && !isSafeDimension(size)) {
+        report({
+          severity: "warning" /* Warning */,
+          code: "RTX3003" /* InvalidDimension */,
+          message: `"${size}" is not a valid dimension.`,
+          range: args[0]?.range ?? ZERO_RANGE5
+        });
+      }
+      return {
+        type: "fontsize",
+        size: isSafeDimension(size) ? size : "1em",
+        children: args[1]?.children ?? []
+      };
+    }
+  },
+  {
+    name: "fontfamily",
+    category: "inline",
+    args: [
+      { kind: "string", name: "family" },
+      { kind: "content", name: "content" }
+    ],
+    summary: "Set the font family for the wrapped content.",
+    example: "\\fontfamily{Georgia}{Serif text}",
+    build: ({ args, utils }) => ({
+      type: "fontfamily",
+      family: utils.textOf(args[0]).trim() || "inherit",
+      children: args[1]?.children ?? []
+    })
+  },
+  scaleSwitch("small", "small"),
+  scaleSwitch("large", "large"),
+  scaleSwitch("Large", "Large"),
+  scaleSwitch("Huge", "Huge"),
+  {
+    name: "normalsize",
+    category: "switch",
+    scoped: true,
+    summary: "Reset the font size to the document base size.",
+    build: ({ scope }) => ({ type: "fontscale", scale: "normal", children: scope })
+  },
+  {
+    name: "ttfamily",
+    category: "switch",
+    scoped: true,
+    summary: "Switch to a monospace font for the rest of the group.",
+    build: ({ scope }) => ({
+      type: "fontfamily",
+      family: "monospace",
+      children: scope
+    })
+  }
+];
+var fontStacks = {
+  inter: '"Inter", "Helvetica Neue", Helvetica, Arial, sans-serif',
+  system: 'system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif',
+  helvetica: '"Helvetica Neue", Helvetica, Arial, sans-serif',
+  georgia: 'Georgia, "Times New Roman", Times, serif',
+  times: '"Times New Roman", Times, serif',
+  garamond: '"EB Garamond", Garamond, Georgia, serif',
+  spaceGrotesk: '"Space Grotesk", system-ui, sans-serif',
+  sourceSerif: '"Source Serif 4", Georgia, serif',
+  jetbrainsMono: '"JetBrains Mono", "SF Mono", "Fira Code", Consolas, monospace',
+  firaCode: '"Fira Code", "JetBrains Mono", Consolas, monospace',
+  ibmPlexMono: '"IBM Plex Mono", "SF Mono", Consolas, monospace'
+};
+function fontTheme(spec) {
+  const resolve = (v) => v == null ? void 0 : fontStacks[v] ?? v;
+  return {
+    heading: resolve(spec.heading),
+    body: resolve(spec.body),
+    mono: resolve(spec.mono)
+  };
+}
+var fontsLibrary = {
+  name: "fonts",
+  summary: "Font family & size control (\\fontfamily, \\fontsize, \\small \u2026 \\Huge).",
+  commands: fontCommands
+};
+
+// src/library/shapes.ts
+var rule = (name, style, summary) => ({
+  name,
+  category: "block",
+  summary,
+  example: `\\${name}`,
+  build: () => style ? { type: "rule", style } : { type: "rule" }
+});
+var shapeCommands = [
+  rule("hrule", "solid", "A horizontal rule / divider."),
+  rule("divider", "solid", "A horizontal rule / divider."),
+  rule("dashrule", "dashed", "A dashed horizontal rule."),
+  rule("dotrule", "dotted", "A dotted horizontal rule."),
+  rule("thickrule", "thick", "A thick horizontal rule."),
+  rule("doublerule", "double", "A double horizontal rule."),
+  {
+    name: "vspace",
+    category: "block",
+    args: [{ kind: "string", name: "size", format: "dimension" }],
+    summary: "Vertical space.",
+    example: "\\vspace{1em}",
+    build: ({ args, utils }) => ({
+      type: "space",
+      axis: "vertical",
+      size: utils.textOf(args[0]).trim() || "1em"
+    })
+  },
+  {
+    name: "hspace",
+    category: "inline",
+    args: [{ kind: "string", name: "size", format: "dimension" }],
+    summary: "Horizontal space.",
+    example: "\\hspace{1em}",
+    build: ({ args, utils }) => ({
+      type: "space",
+      axis: "horizontal",
+      size: utils.textOf(args[0]).trim() || "1em"
+    })
+  }
+];
+var shapesLibrary = {
+  name: "shapes",
+  summary: "Horizontal rules / dividers (\\hrule, \\dashrule, \u2026) and spacing.",
+  commands: shapeCommands
+};
+
+// src/library/themes.ts
+var stylingCommands = [...colorCommands, ...fontCommands, ...shapeCommands];
+var modernLibrary = {
+  name: "modern",
+  summary: "A modern, accent-forward theme (violet, underlined headings).",
+  theme: modernTheme,
+  commands: stylingCommands
+};
+var classicLibrary = {
+  name: "classic",
+  summary: "A classic serif theme with ruled section headings.",
+  theme: classicTheme,
+  commands: stylingCommands
+};
+var compactLibrary = {
+  name: "compact",
+  summary: "A compact, single-accent theme maximizing content density.",
+  theme: compactTheme,
+  commands: stylingCommands
+};
+
+// src/library/registry.ts
+var builtinLibraries = {
+  colors: colorsLibrary,
+  fonts: fontsLibrary,
+  shapes: shapesLibrary,
+  modern: modernLibrary,
+  classic: classicLibrary,
+  compact: compactLibrary
+};
+var ALIASES2 = {
+  color: "colors",
+  font: "fonts",
+  shape: "shapes"
+};
+function resolveLibraryName(name) {
+  const key = name.trim().toLowerCase();
+  if (builtinLibraries[key]) return key;
+  if (ALIASES2[key]) return ALIASES2[key];
+  return void 0;
+}
+function getBuiltinLibrary(name) {
+  const key = resolveLibraryName(name);
+  return key ? builtinLibraries[key] : void 0;
+}
+function builtinLibraryNames() {
+  return Object.keys(builtinLibraries);
+}
+var GATED_COMMANDS = (() => {
+  const map = {};
+  const add = (lib) => {
+    for (const c of lib.commands ?? []) map[c.name] = lib.name;
+  };
+  add(colorsLibrary);
+  add(fontsLibrary);
+  add(shapesLibrary);
+  return map;
+})();
+var dedupe = (names) => [...new Set(names)];
+function usedLibraryNamesFromTokens(tokens) {
+  const names = [];
+  for (let i = 0; i < tokens.length; i++) {
+    const t = tokens[i];
+    if (t.type !== "Command" /* Command */ || t.value !== "usepackage" && t.value !== "use") {
+      continue;
+    }
+    let j = i + 1;
+    while (tokens[j] && (tokens[j].type === "Whitespace" /* Whitespace */ || tokens[j].type === "Comment" /* Comment */)) {
+      j++;
+    }
+    if (!tokens[j] || tokens[j].type !== "LBrace" /* LBrace */) continue;
+    j++;
+    let raw = "";
+    let depth = 0;
+    while (tokens[j] && !(depth === 0 && tokens[j].type === "RBrace" /* RBrace */)) {
+      const tj = tokens[j];
+      if (tj.type === "LBrace" /* LBrace */) depth++;
+      else if (tj.type === "RBrace" /* RBrace */) depth--;
+      raw += tj.type === "Command" /* Command */ ? `\\${tj.value}` : tj.value;
+      j++;
+    }
+    for (const part of raw.split(",")) {
+      const name = part.trim();
+      if (name) names.push(name);
+    }
+    i = j;
+  }
+  return dedupe(names);
+}
+function usedLibraryNamesFromAst(root) {
+  const names = [];
+  for (const node of collect(root, (n) => n.type === "usepackage")) {
+    for (const name of node.names) {
+      const trimmed = name.trim();
+      if (trimmed) names.push(trimmed);
     }
   }
-  peek(k = 0) {
-    return this.tokens[this.pos + k] ?? this.tokens[this.tokens.length - 1];
-  }
-  advance() {
-    const t = this.peek();
-    if (this.pos < this.tokens.length - 1) this.pos++;
-    return t;
-  }
-  previousEnd() {
-    return this.tokens[this.pos - 1]?.range.end ?? this.peek().range.start;
+  return dedupe(names);
+}
+function applyLibraries(base, names, lookup = getBuiltinLibrary) {
+  const registry = base.clone();
+  const libraries = [];
+  const missing = [];
+  for (const name of names) {
+    const lib = lookup(name);
+    if (!lib) {
+      missing.push(name);
+      continue;
+    }
+    libraries.push(lib);
+    for (const cmd of lib.commands ?? []) registry.registerCommand(cmd);
+    for (const env of lib.environments ?? []) registry.registerEnvironment(env);
   }
-  report(d) {
-    this.diagnostics.push({ ...d, source: "parser" });
+  return { registry, libraries, missing };
+}
+function mergeLibraryTheme(base, libraries) {
+  let theme = base;
+  for (const lib of libraries) {
+    if (lib.theme) theme = resolveTheme(lib.theme, theme);
   }
-};
-function parse(tokens, options) {
-  return Parser.parse(tokens, options);
+  return theme;
 }
-
-// src/validator/validator.ts
-var ZERO_RANGE3 = {
+var ZERO_RANGE6 = {
   start: { offset: 0, line: 1, column: 1 },
   end: { offset: 0, line: 1, column: 1 }
 };
-function validate(ast, options = {}) {
-  const diagnostics = [];
-  const report = (d) => {
-    diagnostics.push({ ...d, source: "validator" });
-  };
-  walk(ast, {
-    enter(node) {
-      switch (node.type) {
-        case "command":
-          checkStrayCommand(node, report);
-          break;
-        case "section":
-          if (node.title.trim() === "") {
-            report({
-              severity: "warning" /* Warning */,
-              code: "RTX3006" /* EmptyArgument */,
-              message: "Section heading is empty.",
-              range: node.range ?? ZERO_RANGE3
-            });
-          }
-          break;
-        case "contact":
-          if (node.value.trim() === "") {
-            report({
-              severity: "warning" /* Warning */,
-              code: "RTX3006" /* EmptyArgument */,
-              message: `\\${node.field} is empty.`,
-              range: node.range ?? ZERO_RANGE3
-            });
-          }
-          break;
-        case "themecolor":
-          if (options.theme && !(node.token in options.theme.colors)) {
-            report({
-              severity: "warning" /* Warning */,
-              code: "RTX4003" /* UnknownThemeColor */,
-              message: `Theme color "${node.token}" is not defined in theme "${options.theme.name}".`,
-              range: node.range ?? ZERO_RANGE3
-            });
-          }
-          break;
-        case "skills":
-          if (node.items.length === 0) {
-            report({
-              severity: "info" /* Info */,
-              code: "RTX3006" /* EmptyArgument */,
-              message: "\\skills has no entries.",
-              range: node.range ?? ZERO_RANGE3
-            });
-          }
-          break;
-      }
-    }
-  });
-  return diagnostics;
-}
-function checkStrayCommand(node, report) {
-  if (node.name === "item") {
-    report({
-      severity: "error" /* Error */,
-      code: "RTX4001" /* CommandOutsideContext */,
-      message: "\\item must appear inside an itemize or enumerate environment.",
-      range: node.range ?? ZERO_RANGE3
-    });
-  } else if (node.name === "column") {
-    report({
-      severity: "error" /* Error */,
-      code: "RTX4001" /* CommandOutsideContext */,
-      message: "\\column must appear inside a columns environment.",
-      range: node.range ?? ZERO_RANGE3
+function libraryDiagnostics(ast, diagnostics, lookup = getBuiltinLibrary) {
+  const gated = collect(
+    ast,
+    (n) => n.type === "command" && n.name in GATED_COMMANDS
+  );
+  const gatedOffsets = new Set(
+    gated.map((n) => n.range?.start.offset).filter((o) => o != null)
+  );
+  const out = diagnostics.filter(
+    (d) => !(d.code === "RTX2001" /* UnknownCommand */ && gatedOffsets.has(d.range.start.offset))
+  );
+  for (const node of gated) {
+    const lib = GATED_COMMANDS[node.name];
+    out.push({
+      source: "parser",
+      severity: "warning" /* Warning */,
+      code: "RTX4005" /* LibraryRequired */,
+      message: `\\${node.name} requires the "${lib}" library. Add \\usepackage{${lib}} to the preamble (or engine.use(${lib}Library)).`,
+      range: node.range ?? ZERO_RANGE6
     });
   }
+  for (const node of collect(ast, (n) => n.type === "usepackage")) {
+    for (const name of node.names) {
+      if (lookup(name)) continue;
+      out.push({
+        source: "parser",
+        severity: "warning" /* Warning */,
+        code: "RTX4004" /* UnknownLibrary */,
+        message: `Unknown library "${name}". Available: ${builtinLibraryNames().join(", ")}.`,
+        range: node.range ?? ZERO_RANGE6
+      });
+    }
+  }
+  return out;
 }
-
-// src/theme/default.ts
-var defaultTheme = {
-  name: "default",
-  colors: {
-    primary: "#2563eb",
-    secondary: "#64748b",
-    text: "#1e293b",
-    muted: "#64748b",
-    background: "#ffffff",
-    border: "#e2e8f0",
-    accent: "#2563eb",
-    success: "#16a34a"
-  },
-  fonts: {
-    heading: '"Inter", "Helvetica Neue", Helvetica, Arial, sans-serif',
-    body: '"Inter", "Helvetica Neue", Helvetica, Arial, sans-serif',
-    mono: '"JetBrains Mono", "SF Mono", "Fira Code", Consolas, monospace'
-  },
-  fontSizes: {
-    base: "10.5pt",
-    small: "9pt",
-    large: "12pt",
-    Large: "15pt",
-    Huge: "22pt",
-    name: "26pt",
-    section: "13pt"
-  },
-  spacing: {
-    unit: "4px",
-    section: "1.1rem",
-    item: "0.28rem",
-    page: "0.55in"
-  },
-  page: {
-    size: "Letter",
-    margin: "0.55in",
-    maxWidth: "8.5in"
-  },
-  sectionStyle: "rule"
-};
-
-// src/theme/themes.ts
-function resolveTheme(partial, base = defaultTheme) {
-  if (!partial) return base;
-  return {
-    name: partial.name ?? base.name,
-    colors: { ...base.colors, ...partial.colors },
-    fonts: { ...base.fonts, ...partial.fonts },
-    fontSizes: { ...base.fontSizes, ...partial.fontSizes },
-    spacing: { ...base.spacing, ...partial.spacing },
-    page: { ...base.page, ...partial.page },
-    sectionStyle: partial.sectionStyle ?? base.sectionStyle
-  };
-}
-var modernTheme = resolveTheme({
-  name: "modern",
-  colors: { primary: "#7c3aed", accent: "#7c3aed", text: "#111827" },
-  sectionStyle: "underline"
-});
-var classicTheme = resolveTheme({
-  name: "classic",
-  colors: { primary: "#111827", secondary: "#4b5563", accent: "#111827" },
-  fonts: {
-    heading: 'Georgia, "Times New Roman", serif',
-    body: 'Georgia, "Times New Roman", serif',
-    mono: 'Consolas, "Courier New", monospace'
-  },
-  sectionStyle: "rule"
-});
-var compactTheme = resolveTheme({
-  name: "compact",
-  fontSizes: {
-    base: "9.5pt",
-    small: "8pt",
-    large: "11pt",
-    Large: "13pt",
-    Huge: "18pt",
-    name: "20pt",
-    section: "11pt"
-  },
-  spacing: { unit: "3px", section: "0.7rem", item: "0.18rem", page: "0.4in" },
-  sectionStyle: "bar"
-});
-var themes = {
-  default: defaultTheme,
-  modern: modernTheme,
-  classic: classicTheme,
-  compact: compactTheme
-};
-function getTheme(name) {
-  return themes[name] ?? defaultTheme;
+function collectLibraryOverrides(libraries) {
+  const html = /* @__PURE__ */ new Map();
+  const react = /* @__PURE__ */ new Map();
+  for (const lib of libraries) {
+    for (const cmd of lib.commands ?? []) {
+      if (cmd.render?.html) html.set(`command:${cmd.name}`, cmd.render.html);
+      if (cmd.render?.react) react.set(`command:${cmd.name}`, cmd.render.react);
+    }
+    for (const [k, fn] of Object.entries(lib.htmlRenderers ?? {})) html.set(k, fn);
+    for (const [k, fn] of Object.entries(lib.reactRenderers ?? {})) react.set(k, fn);
+  }
+  return { html, react };
 }
 
 // src/renderers/css.ts
 var tokenSafe = (s) => s.replace(/[^a-zA-Z0-9_-]/g, "");
+var has = (v) => v != null && v !== "";
+var color = (v, fallback) => has(v) && isSafeColor(v) ? v : fallback;
+var dim = (v, fallback) => has(v) && isSafeDimension(v) ? v : fallback;
+var val = (v, fallback) => has(v) ? sanitizeStyleValue(v) ?? fallback : fallback;
 function themeToCss(theme, prefix = "retex") {
   const p = prefix;
-  const colorVars = Object.entries(theme.colors).map(([k, v]) => `    --${p}-color-${tokenSafe(k)}: ${v};`).join("\n");
+  const c = theme.colors ?? {};
+  const f = theme.fonts ?? {};
+  const fs = theme.fontSizes ?? {};
+  const sp = theme.spacing ?? {};
+  const h = theme.headings ?? {};
+  const colorVars = Object.entries(c).filter(([, v]) => has(v) && isSafeColor(v)).map(([k, v]) => `    --${p}-color-${tokenSafe(k)}: ${v};`).join("\n");
+  const primary = color(c.primary, "");
+  const skillBg = primary ? `color-mix(in srgb, ${primary} 12%, transparent)` : "transparent";
+  const skillColor = primary || "inherit";
+  const linkDecoration = primary ? "none" : "underline";
   return `.${p}-resume {
-${colorVars}
-    --${p}-primary: ${theme.colors.primary};
-    --${p}-text: ${theme.colors.text};
-    --${p}-muted: ${theme.colors.muted};
-    --${p}-border: ${theme.colors.border};
-    --${p}-bg: ${theme.colors.background};
-    --${p}-font-heading: ${theme.fonts.heading};
-    --${p}-font-body: ${theme.fonts.body};
-    --${p}-font-mono: ${theme.fonts.mono};
-    --${p}-fs-base: ${theme.fontSizes.base};
-    --${p}-fs-small: ${theme.fontSizes.small};
-    --${p}-fs-large: ${theme.fontSizes.large};
-    --${p}-fs-Large: ${theme.fontSizes.Large};
-    --${p}-fs-Huge: ${theme.fontSizes.Huge};
-    --${p}-fs-name: ${theme.fontSizes.name};
-    --${p}-fs-section: ${theme.fontSizes.section};
-    --${p}-sp-section: ${theme.spacing.section};
-    --${p}-sp-item: ${theme.spacing.item};
+${colorVars ? colorVars + "\n" : ""}    --${p}-primary: ${primary || "inherit"};
+    --${p}-text: ${color(c.text, "inherit")};
+    --${p}-muted: ${color(c.muted, "inherit")};
+    --${p}-border: ${color(c.border, "currentColor")};
+    --${p}-bg: ${color(c.background, "transparent")};
+    --${p}-font-heading: ${val(f.heading, "inherit")};
+    --${p}-font-body: ${val(f.body, "inherit")};
+    --${p}-font-mono: ${val(f.mono, "ui-monospace, SFMono-Regular, Menlo, monospace")};
+    --${p}-fs-base: ${dim(fs.base, "inherit")};
+    --${p}-fs-small: ${dim(fs.small, "0.85em")};
+    --${p}-fs-large: ${dim(fs.large, "1.2em")};
+    --${p}-fs-Large: ${dim(fs.Large, "1.45em")};
+    --${p}-fs-Huge: ${dim(fs.Huge, "2em")};
+    --${p}-fs-name: ${dim(fs.name, "2em")};
+    --${p}-fs-section: ${dim(fs.section, "1.25em")};
+    --${p}-sp-section: ${dim(sp.section, "1.1rem")};
+    --${p}-sp-item: ${dim(sp.item, "0.28rem")};
+    --${p}-section-transform: ${val(h.transform, "none")};
+    --${p}-section-tracking: ${val(h.tracking, "normal")};
+    --${p}-name-tracking: ${val(h.nameTracking, "normal")};
+    --${p}-link-decoration: ${linkDecoration};
+    --${p}-skill-bg: ${skillBg};
+    --${p}-skill-color: ${skillColor};
 
     box-sizing: border-box;
-    max-width: ${theme.page.maxWidth};
+    max-width: ${dim(theme.page?.maxWidth, "none")};
     margin: 0 auto;
-    padding: ${theme.spacing.page};
+    padding: ${dim(sp.page, "0")};
     background: var(--${p}-bg);
     color: var(--${p}-text);
     font-family: var(--${p}-font-body);
@@ -1744,7 +2096,7 @@ ${colorVars}
     font-weight: 700;
     margin: 0 0 0.1em;
     color: var(--${p}-text);
-    letter-spacing: -0.01em;
+    letter-spacing: var(--${p}-name-tracking);
 }
 .${p}-title {
     font-size: var(--${p}-fs-large);
@@ -1773,8 +2125,8 @@ ${colorVars}
     font-family: var(--${p}-font-heading);
     font-size: var(--${p}-fs-section);
     font-weight: 700;
-    text-transform: uppercase;
-    letter-spacing: 0.06em;
+    text-transform: var(--${p}-section-transform);
+    letter-spacing: var(--${p}-section-tracking);
     color: var(--${p}-primary);
     margin: 0 0 0.5em;
 }
@@ -1817,8 +2169,8 @@ ${colorVars}
 
 .${p}-skills { display: flex; flex-wrap: wrap; gap: 0.4rem; list-style: none; margin: 0.2rem 0; padding: 0; }
 .${p}-skill {
-    background: color-mix(in srgb, var(--${p}-primary) 12%, transparent);
-    color: var(--${p}-primary);
+    background: var(--${p}-skill-bg);
+    color: var(--${p}-skill-color);
     border-radius: 4px;
     padding: 0.12rem 0.5rem;
     font-size: var(--${p}-fs-small);
@@ -1826,10 +2178,14 @@ ${colorVars}
     white-space: nowrap;
 }
 
-.${p}-link { color: var(--${p}-primary); text-decoration: none; }
+.${p}-link { color: var(--${p}-primary); text-decoration: var(--${p}-link-decoration); }
 .${p}-link:hover { text-decoration: underline; }
 .${p}-icon { display: inline-flex; vertical-align: -0.125em; }
 .${p}-rule { border: none; border-top: 1px solid var(--${p}-border); margin: 0.6rem 0; }
+.${p}-rule--dashed { border-top-style: dashed; }
+.${p}-rule--dotted { border-top-style: dotted; }
+.${p}-rule--thick { border-top-width: 3px; }
+.${p}-rule--double { border-top-style: double; border-top-width: 3px; }
 .${p}-center { text-align: center; }
 .${p}-scale-small { font-size: var(--${p}-fs-small); }
 .${p}-scale-large { font-size: var(--${p}-fs-large); }
@@ -1887,7 +2243,7 @@ function splitPreamble(nodes) {
     (n) => CONTACTISH.has(n.type) && n !== name && n !== title
   );
   const other = nodes.filter(
-    (n) => !CONTACTISH.has(n.type) && n.type !== "parbreak" && !(n.type === "text" && n.value.trim() === "")
+    (n) => !CONTACTISH.has(n.type) && n.type !== "parbreak" && n.type !== "usepackage" && !(n.type === "text" && n.value.trim() === "")
   );
   return { name, title, contacts, other };
 }
@@ -1922,10 +2278,11 @@ function dateRange(start, end, date) {
 var tokenSafe2 = (s) => s.replace(/[^a-zA-Z0-9_-]/g, "");
 var HtmlRenderer = class {
   constructor(options = {}) {
-    this.theme = options.theme ?? resolveTheme();
+    this.theme = resolveTheme(options.theme);
     this.prefix = options.classPrefix ?? "retex";
     this.overrides = options.overrides ?? /* @__PURE__ */ new Map();
     this.useHeader = options.header ?? true;
+    this.sourceMap = options.sourceMap ?? false;
     this.ctx = {
       theme: this.theme,
       classPrefix: this.prefix,
@@ -1973,8 +2330,8 @@ ${this.styles()}
   }
   /* --------------------------- structuring ---------------------------- */
   renderSection(section, body) {
-    const styleMod = ` ${this.cls("section")}--${this.theme.sectionStyle}`;
-    return `<section class="${this.cls("section")}${styleMod}"><h2 class="${this.cls("section-title")}">${escapeHtml(section.title)}</h2><div class="${this.cls("section-body")}">${this.renderFlow(body)}</div></section>`;
+    const styleMod = this.theme.sectionStyle ? ` ${this.cls("section")}--${this.theme.sectionStyle}` : "";
+    return `<section class="${this.cls("section")}${styleMod}"${this.src(section)}><h2 class="${this.cls("section-title")}"${this.src(section, "section-title")}>${escapeHtml(section.title)}</h2><div class="${this.cls("section-body")}">${this.renderFlow(body)}</div></section>`;
   }
   renderPreamble(nodes) {
     if (!this.useHeader) return this.renderFlow(nodes);
@@ -1983,8 +2340,10 @@ ${this.styles()}
     let html = "";
     if (hasHeader) {
       html += `<header class="${this.cls("header")}">`;
-      if (name) html += `<h1 class="${this.cls("name")}">${escapeHtml(name.value)}</h1>`;
-      if (title) html += `<p class="${this.cls("title")}">${escapeHtml(title.value)}</p>`;
+      if (name)
+        html += `<h1 class="${this.cls("name")}"${this.src(name)}>${escapeHtml(name.value)}</h1>`;
+      if (title)
+        html += `<p class="${this.cls("title")}"${this.src(title)}>${escapeHtml(title.value)}</p>`;
       if (contacts.length > 0) {
         html += `<div class="${this.cls("contact")}">${contacts.map((c) => this.renderContactItem(c)).join("")}</div>`;
       }
@@ -1995,35 +2354,37 @@ ${this.styles()}
   }
   renderContactItem(node) {
     const item = this.cls("contact-item");
+    const src = this.src(node);
     if (node.type === "contact") {
       switch (node.field) {
         case "email":
-          return this.contactLink(`mailto:${node.value}`, "email", node.value, item);
+          return this.contactLink(`mailto:${node.value}`, "email", node.value, item, src);
         case "phone":
           return this.contactLink(
             `tel:${node.value.replace(/[^\d+]/g, "")}`,
             "phone",
             node.value,
-            item
+            item,
+            src
           );
         case "website":
-          return this.contactLink(node.value, "website", node.value, item);
+          return this.contactLink(node.value, "website", node.value, item, src);
         case "location":
-          return `<span class="${item}">${this.icon("location")}${escapeHtml(node.value)}</span>`;
+          return `<span class="${item}"${src}>${this.icon("location")}${escapeHtml(node.value)}</span>`;
         default:
-          return `<span class="${item}">${escapeHtml(node.value)}</span>`;
+          return `<span class="${item}"${src}>${escapeHtml(node.value)}</span>`;
       }
     }
     if (node.type === "icon")
-      return `<span class="${item}">${this.renderNode(node)}</span>`;
+      return `<span class="${item}"${src}>${this.renderNode(node)}</span>`;
     if (node.type === "link" || node.type === "url") {
-      return `<span class="${item}">${this.renderNode(node)}</span>`;
+      return `<span class="${item}"${src}>${this.renderNode(node)}</span>`;
     }
     return this.renderNode(node);
   }
-  contactLink(url, icon, label, cls) {
+  contactLink(url, icon, label, cls, src = "") {
     const { safe } = sanitizeUrl(url);
-    return `<a class="${cls}" href="${escapeAttribute(safe)}">${this.icon(icon)}${escapeHtml(label)}</a>`;
+    return `<a class="${cls}"${src} href="${escapeAttribute(safe)}">${this.icon(icon)}${escapeHtml(label)}</a>`;
   }
   /* ----------------------------- flow / inline ------------------------ */
   /** Block-aware rendering: groups inline runs into `<p>`, renders blocks as-is. */
@@ -2032,7 +2393,10 @@ ${this.styles()}
     let inline = [];
     const flush = () => {
       const html = this.renderInline(inline).trim();
-      if (html) out.push(`<p class="${this.cls("para")}">${html}</p>`);
+      if (html)
+        out.push(
+          `<p class="${this.cls("para")}"${this.srcSpan(inline, "para")}>${html}</p>`
+        );
       inline = [];
     };
     for (const node of nodes) {
@@ -2060,68 +2424,76 @@ ${this.styles()}
         return escapeHtml(node.value);
       case "parbreak":
         return "";
+      case "usepackage":
+        return "";
       case "linebreak":
         return "<br>";
-      case "rule":
-        return `<hr class="${this.cls("rule")}">`;
+      case "rule": {
+        const variant = node.style && node.style !== "solid" ? ` ${this.cls(`rule--${node.style}`)}` : "";
+        return `<hr class="${this.cls("rule")}${variant}"${this.src(node)}>`;
+      }
       case "space":
-        return node.axis === "vertical" ? `<div style="height:${this.dim(node.size)}"></div>` : `<span style="display:inline-block;width:${this.dim(node.size)}"></span>`;
+        return node.axis === "vertical" ? `<div style="height:${this.dim(node.size)}"${this.src(node)}></div>` : `<span style="display:inline-block;width:${this.dim(node.size)}"${this.src(node)}></span>`;
       case "group":
         return this.renderInline(node.children);
       case "bold":
-        return `<strong>${this.renderInline(node.children)}</strong>`;
+        return `<strong${this.src(node)}>${this.renderInline(node.children)}</strong>`;
       case "italic":
-        return `<em>${this.renderInline(node.children)}</em>`;
+        return `<em${this.src(node)}>${this.renderInline(node.children)}</em>`;
       case "underline":
-        return `<u>${this.renderInline(node.children)}</u>`;
+        return `<u${this.src(node)}>${this.renderInline(node.children)}</u>`;
       case "strike":
-        return `<s>${this.renderInline(node.children)}</s>`;
+        return `<s${this.src(node)}>${this.renderInline(node.children)}</s>`;
       case "color": {
         const inner = this.renderInline(node.children);
         if (!node.color || !isSafeColor(node.color)) return inner;
-        return `<span style="color:${node.color}">${inner}</span>`;
+        return `<span style="color:${node.color}"${this.src(node)}>${inner}</span>`;
       }
       case "themecolor": {
         const inner = this.renderInline(node.children);
         const tok = tokenSafe2(node.token);
-        return `<span style="color:var(--${this.prefix}-color-${tok}, currentColor)">${inner}</span>`;
+        return `<span style="color:var(--${this.prefix}-color-${tok}, currentColor)"${this.src(node)}>${inner}</span>`;
       }
       case "fontsize": {
         const inner = this.renderInline(node.children);
         if (!isSafeDimension(node.size)) return inner;
-        return `<span style="font-size:${node.size}">${inner}</span>`;
+        return `<span style="font-size:${node.size}"${this.src(node)}>${inner}</span>`;
       }
       case "fontfamily": {
         const inner = this.renderInline(node.children);
         const family = node.family === "monospace" ? `var(--${this.prefix}-font-mono)` : sanitizeStyleValue(node.family);
         if (!family) return inner;
-        return `<span style="font-family:${family}">${inner}</span>`;
+        return `<span style="font-family:${family}"${this.src(node)}>${inner}</span>`;
       }
       case "fontscale": {
         const inner = this.renderInline(node.children);
-        if (node.scale === "normal") return `<span>${inner}</span>`;
-        return `<span class="${this.cls(`scale-${node.scale}`)}">${inner}</span>`;
+        if (node.scale === "normal") return `<span${this.src(node)}>${inner}</span>`;
+        return `<span class="${this.cls(`scale-${node.scale}`)}"${this.src(node)}>${inner}</span>`;
       }
       case "link":
-        return this.renderLink(node.href, this.renderInline(node.children));
+        return this.renderLink(
+          node.href,
+          this.renderInline(node.children),
+          this.src(node)
+        );
       case "url":
-        return this.renderLink(node.href, escapeHtml(node.rawHref));
+        return this.renderLink(node.href, escapeHtml(node.rawHref), this.src(node));
       case "icon":
         return this.icon(node.name);
       case "section":
-        return `<h${node.level + 1} class="${this.cls("subsection-title")}">${escapeHtml(node.title)}</h${node.level + 1}>`;
+        return `<h${node.level + 1} class="${this.cls("subsection-title")}"${this.src(node)}>${escapeHtml(node.title)}</h${node.level + 1}>`;
       case "list":
         return this.renderList(node);
       case "columns":
         return this.renderColumns(node);
       case "skills":
-        return this.renderSkills(node.items);
+        return this.renderSkills(node);
       case "job":
-        return this.renderEntry(node.fields, node.children, "job");
+        return this.renderEntry(node, "job");
       case "education":
-        return this.renderEntry(node.fields, node.children, "education");
+        return this.renderEntry(node, "education");
       case "project":
-        return this.renderEntry(node.fields, node.children, "project");
+        return this.renderEntry(node, "project");
       case "contact":
         return this.renderContactItem(node);
       case "command":
@@ -2132,33 +2504,36 @@ ${this.styles()}
         return "";
     }
   }
-  renderLink(href, label) {
+  renderLink(href, label, src = "") {
     const { safe } = sanitizeUrl(href);
     const external = /^https?:/i.test(safe);
     const rel = external ? ' target="_blank" rel="noopener noreferrer"' : "";
-    return `<a class="${this.cls("link")}" href="${escapeAttribute(safe)}"${rel}>${label}</a>`;
+    return `<a class="${this.cls("link")}"${src} href="${escapeAttribute(safe)}"${rel}>${label}</a>`;
   }
   renderList(node) {
     const tag = node.kind === "enumerate" ? "ol" : "ul";
-    const items = node.items.map((item) => `<li>${this.renderInline(item.children).trim()}</li>`).join("");
-    return `<${tag} class="${this.cls("list")}">${items}</${tag}>`;
+    const items = node.items.map(
+      (item) => `<li${this.src(item)}>${this.renderInline(item.children).trim()}</li>`
+    ).join("");
+    return `<${tag} class="${this.cls("list")}"${this.src(node)}>${items}</${tag}>`;
   }
   renderColumns(node) {
     const cols = node.columns.map((col) => {
       const basis = isSafeDimension(col.width) ? col.width : "auto";
       const flex = basis === "auto" ? "flex:1 1 0" : `flex:0 0 ${basis}`;
-      return `<div class="${this.cls("column")}" style="${flex}">${this.renderFlow(col.children)}</div>`;
+      return `<div class="${this.cls("column")}" style="${flex}"${this.src(col)}>${this.renderFlow(col.children)}</div>`;
     }).join("");
-    return `<div class="${this.cls("columns")}">${cols}</div>`;
+    return `<div class="${this.cls("columns")}"${this.src(node)}>${cols}</div>`;
   }
-  renderSkills(items) {
-    const lis = items.map((s) => `<li class="${this.cls("skill")}">${escapeHtml(s)}</li>`).join("");
-    return `<ul class="${this.cls("skills")}">${lis}</ul>`;
+  renderSkills(node) {
+    const lis = node.items.map((s) => `<li class="${this.cls("skill")}">${escapeHtml(s)}</li>`).join("");
+    return `<ul class="${this.cls("skills")}"${this.src(node)}>${lis}</ul>`;
   }
-  renderEntry(fields, body, kind) {
+  renderEntry(node, kind) {
+    const { fields, children: body } = node;
     const { title, subtitle, dates, location, url } = entryParts(fields, kind);
     const titleHtml = url ? this.renderLink(sanitizeUrl(url).safe, escapeHtml(title)) : escapeHtml(title);
-    let html = `<div class="${this.cls("entry")} ${this.cls(kind)}">`;
+    let html = `<div class="${this.cls("entry")} ${this.cls(kind)}"${this.src(node)}>`;
     html += `<div class="${this.cls("entry-row")}">`;
     html += `<span class="${this.cls("entry-title")}">${titleHtml}</span>`;
     if (dates)
@@ -2180,12 +2555,38 @@ ${this.styles()}
   renderCommand(node) {
     if (node.name === "center") {
       const inner2 = node.args.flatMap((a) => a.children);
-      return `<div class="${this.cls("center")}">${this.renderFlow(inner2)}</div>`;
+      return `<div class="${this.cls("center")}"${this.src(node)}>${this.renderFlow(inner2)}</div>`;
     }
     const inner = node.args.flatMap((a) => a.children);
     return inner.length > 0 ? this.renderInline(inner) : "";
   }
   /* ------------------------------ helpers ----------------------------- */
+  /**
+   * 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).
+   */
+  src(node, type) {
+    if (!this.sourceMap || !node?.range) return "";
+    const kind = type ?? node.type;
+    const kindAttr = kind ? ` data-rtx-type="${kind}"` : "";
+    return ` data-rtx-pos="${node.range.start.offset}:${node.range.end.offset}"${kindAttr}`;
+  }
+  /** Like {@link src}, but spans a run of inline nodes (merges their ranges). */
+  srcSpan(nodes, type) {
+    if (!this.sourceMap) return "";
+    let start = Infinity;
+    let end = -Infinity;
+    for (const n of nodes) {
+      if (!n.range) continue;
+      if (n.range.start.offset < start) start = n.range.start.offset;
+      if (n.range.end.offset > end) end = n.range.end.offset;
+    }
+    if (end < 0) return "";
+    return ` data-rtx-pos="${start}:${end}" data-rtx-type="${type}"`;
+  }
   icon(name) {
     const svg = iconToSvg(name, { className: this.cls("icon") });
     if (svg) return svg;
@@ -2227,8 +2628,12 @@ function renderJson(ast, opts = {}) {
 }
 
 // src/renderers/pdf.ts
+var pageSize = (v) => v && sanitizeStyleValue(v) || "Letter";
+var pageMargin = (v) => v && isSafeDimension(v) ? v : "0.5in";
 function pageCss(theme) {
-  return `@page { size: ${theme.page.size}; margin: ${theme.page.margin}; }
+  const size = pageSize(theme.page?.size);
+  const margin = pageMargin(theme.page?.margin);
+  return `@page { size: ${size}; margin: ${margin}; }
 html, body { margin: 0; padding: 0; background: #fff; }
 @media screen { body { background: #f1f5f9; padding: 24px; } .retex-resume { box-shadow: 0 1px 8px rgba(0,0,0,.12); } }`;
 }
@@ -2263,16 +2668,13 @@ async function renderPdf(ast, options = {}) {
   try {
     const page = await browser.newPage();
     await page.setContent(html, { waitUntil: "networkidle0" });
+    const size = pageSize(theme.page?.size);
+    const margin = pageMargin(theme.page?.margin);
     return await page.pdf({
       printBackground: options.printBackground ?? true,
       preferCSSPageSize: true,
-      format: theme.page.size,
-      margin: {
-        top: theme.page.margin,
-        bottom: theme.page.margin,
-        left: theme.page.margin,
-        right: theme.page.margin
-      }
+      format: size,
+      margin: { top: margin, bottom: margin, left: margin, right: margin }
     });
   } finally {
     await browser.close();
@@ -2302,7 +2704,7 @@ var ReactRenderer = class {
         "ReactRenderer requires a `createElement` factory (e.g. React.createElement)."
       );
     }
-    this.theme = options.theme ?? resolveTheme();
+    this.theme = resolveTheme(options.theme);
     this.prefix = options.classPrefix ?? "retex";
     this.h = options.createElement;
     this.Fragment = options.Fragment ?? "div";
@@ -2338,10 +2740,11 @@ var ReactRenderer = class {
   }
   /* --------------------------- structuring ---------------------------- */
   renderSection(section, body) {
+    const className = this.theme.sectionStyle ? `${this.cls("section")} ${this.cls("section")}--${this.theme.sectionStyle}` : this.cls("section");
     return this.el(
       "section",
       {
-        className: `${this.cls("section")} ${this.cls("section")}--${this.theme.sectionStyle}`
+        className
       },
       [
         this.el("h2", { className: this.cls("section-title") }, [section.title]),
@@ -2407,10 +2810,14 @@ var ReactRenderer = class {
         return node.value;
       case "parbreak":
         return null;
+      case "usepackage":
+        return null;
       case "linebreak":
         return this.el("br", null, []);
-      case "rule":
-        return this.el("hr", { className: this.cls("rule") }, []);
+      case "rule": {
+        const variant = node.style && node.style !== "solid" ? ` ${this.cls(`rule--${node.style}`)}` : "";
+        return this.el("hr", { className: `${this.cls("rule")}${variant}` }, []);
+      }
       case "space":
         return node.axis === "vertical" ? this.el("div", { style: { height: this.dim(node.size) } }, []) : this.el(
           "span",
@@ -2624,17 +3031,20 @@ function renderReact(ast, options) {
 }
 
 // src/engine.ts
-var isTheme = (t) => !!t && "colors" in t && "fonts" in t && "fontSizes" in t && "page" in t;
+var isFullTheme = (t) => typeof t?.name === "string" && t.name.length > 0;
 var ReTeXEngine = class {
   constructor(options = {}) {
     this.htmlOverrides = /* @__PURE__ */ new Map();
     this.reactOverrides = /* @__PURE__ */ new Map();
+    /** Libraries available to `\usepackage` (built-ins are resolved separately). */
+    this.customLibraries = /* @__PURE__ */ new Map();
     this.cache = /* @__PURE__ */ new Map();
     this.generation = 0;
     this.registry = createDefaultRegistry();
-    this.theme = isTheme(options.theme) ? options.theme : resolveTheme(options.theme);
+    this.theme = resolveTheme(options.theme);
     this.prefix = options.classPrefix ?? "retex";
     this.cacheSize = options.cacheSize ?? 64;
+    for (const lib of options.libraries ?? []) this.provideLibrary(lib);
     for (const plugin of options.plugins ?? []) this.use(plugin);
   }
   /* ----------------------------- plugins ------------------------------ */
@@ -2651,10 +3061,21 @@ var ReTeXEngine = class {
       this.registerReactRenderer(key, fn);
     }
     if (plugin.theme) this.setTheme(plugin.theme);
+    if (plugin.name) this.customLibraries.set(plugin.name.trim().toLowerCase(), plugin);
     plugin.setup?.(this);
     this.invalidate();
     return 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) {
+    this.customLibraries.set(library.name.trim().toLowerCase(), library);
+    this.invalidate();
+    return this;
+  }
   registerCommand(def) {
     const { render, ...spec } = def;
     this.registry.registerCommand(spec);
@@ -2682,7 +3103,7 @@ var ReTeXEngine = class {
   }
   /* ----------------------------- theming ------------------------------ */
   setTheme(theme) {
-    this.theme = isTheme(theme) ? theme : resolveTheme(theme, this.theme);
+    this.theme = isFullTheme(theme) ? resolveTheme(theme, defaultTheme) : resolveTheme(theme, this.theme);
     this.invalidate();
     return this;
   }
@@ -2703,11 +3124,22 @@ var ReTeXEngine = class {
     const cached = this.cache.get(key);
     if (cached) return cached;
     const { tokens, diagnostics: lexDiags } = tokenize(source);
-    const { ast, diagnostics: parseDiags } = new Parser(tokens, {
-      registry: this.registry
-    }).parse();
-    const diagnostics = [...lexDiags, ...parseDiags];
-    if (runValidate) diagnostics.push(...validate(ast, { theme: this.theme }));
+    const usedNames = usedLibraryNamesFromTokens(tokens);
+    const { registry, libraries } = applyLibraries(
+      this.registry,
+      usedNames,
+      (n) => this.lookupLibrary(n)
+    );
+    const { ast, diagnostics: parseDiags } = new Parser(tokens, { registry }).parse();
+    let diagnostics = libraryDiagnostics(
+      ast,
+      [...lexDiags, ...parseDiags],
+      (n) => this.lookupLibrary(n)
+    );
+    if (runValidate) {
+      const theme = mergeLibraryTheme(this.theme, libraries);
+      diagnostics.push(...validate(ast, { theme }));
+    }
     const result = { source, tokens, ast, diagnostics };
     this.remember(key, result);
     return result;
@@ -2717,54 +3149,97 @@ var ReTeXEngine = class {
   }
   validate(input) {
     if (typeof input === "string") return this.compile(input).diagnostics;
-    return validate(input, { theme: this.theme });
+    return validate(input, { theme: this.bundle(input).theme });
   }
   /* ----------------------------- renderers ---------------------------- */
   toHtml(input, options = {}) {
-    return this.htmlRenderer(options).render(this.astOf(input));
+    const b = this.bundle(input);
+    return new HtmlRenderer({
+      theme: b.theme,
+      classPrefix: this.prefix,
+      overrides: b.htmlOverrides,
+      ...options
+    }).render(b.ast);
   }
   toHtmlDocument(input, options = {}) {
-    return this.htmlRenderer(options).renderDocument(this.astOf(input), options.title);
+    const b = this.bundle(input);
+    return new HtmlRenderer({
+      theme: b.theme,
+      classPrefix: this.prefix,
+      overrides: b.htmlOverrides,
+      ...options
+    }).renderDocument(b.ast, options.title);
   }
   toReact(input, options) {
+    const b = this.bundle(input);
     return new ReactRenderer({
       ...options,
-      theme: this.theme,
+      theme: b.theme,
       classPrefix: this.prefix,
-      overrides: this.reactOverrides
-    }).render(this.astOf(input));
+      overrides: b.reactOverrides
+    }).render(b.ast);
   }
   toJson(input, options) {
     return renderJson(this.astOf(input), options);
   }
   toPrintHtml(input, options = {}) {
-    return renderPrintHtml(this.astOf(input), this.printOptions(options));
+    const b = this.bundle(input);
+    return renderPrintHtml(b.ast, {
+      theme: b.theme,
+      classPrefix: this.prefix,
+      overrides: b.htmlOverrides,
+      ...options
+    });
   }
   toPdf(input, options = {}) {
-    return renderPdf(this.astOf(input), this.printOptions(options));
+    const b = this.bundle(input);
+    return renderPdf(b.ast, {
+      theme: b.theme,
+      classPrefix: this.prefix,
+      overrides: b.htmlOverrides,
+      ...options
+    });
   }
-  /** The CSS stylesheet for the active theme. */
-  styles() {
-    return this.htmlRenderer().styles();
+  /**
+   * 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) {
+    const theme = input === void 0 ? this.theme : this.bundle(input).theme;
+    return new HtmlRenderer({ theme, classPrefix: this.prefix }).styles();
   }
   /* ------------------------------ internals --------------------------- */
+  /** Resolve a library name against custom libraries first, then built-ins. */
+  lookupLibrary(name) {
+    return this.customLibraries.get(name.trim().toLowerCase()) ?? getBuiltinLibrary(name);
+  }
   astOf(input) {
     return typeof input === "string" ? this.compile(input, { validate: false }).ast : input;
   }
-  htmlRenderer(options = {}) {
-    return new HtmlRenderer({
-      theme: this.theme,
-      classPrefix: this.prefix,
-      overrides: this.htmlOverrides,
-      ...options
-    });
-  }
-  printOptions(options) {
+  /**
+   * 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.
+   */
+  bundle(input) {
+    const ast = this.astOf(input);
+    const libraries = usedLibraryNamesFromAst(ast).map((n) => this.lookupLibrary(n)).filter((l) => !!l);
+    if (libraries.length === 0) {
+      return {
+        ast,
+        theme: this.theme,
+        htmlOverrides: this.htmlOverrides,
+        reactOverrides: this.reactOverrides
+      };
+    }
+    const { html, react } = collectLibraryOverrides(libraries);
     return {
-      theme: this.theme,
-      classPrefix: this.prefix,
-      overrides: this.htmlOverrides,
-      ...options
+      ast,
+      theme: mergeLibraryTheme(this.theme, libraries),
+      htmlOverrides: new Map([...this.htmlOverrides, ...html]),
+      reactOverrides: new Map([...this.reactOverrides, ...react])
     };
   }
   invalidate() {
@@ -2871,7 +3346,7 @@ function printBlocks(nodes) {
   for (const node of nodes) {
     if (node.type === "parbreak") {
       flush();
-    } else if (isBlockNode(node) || node.type === "section" || node.type === "list" || node.type === "columns") {
+    } else if (isBlockNode(node) || node.type === "section" || node.type === "list" || node.type === "columns" || node.type === "usepackage") {
       flush();
       out.push(printBlock(node));
     } else {
@@ -2910,8 +3385,10 @@ ${indent}\\end{columns}`;
     }
     case "skills":
       return `${indent}\\skills{${node.items.join(", ")}}`;
+    case "usepackage":
+      return `${indent}\\usepackage{${node.names.join(", ")}}`;
     case "rule":
-      return `${indent}\\hrule`;
+      return indent + ruleCommand(node.style);
     case "space":
       return `${indent}\\${node.axis === "vertical" ? "vspace" : "hspace"}{${node.size}}`;
     case "command":
@@ -2963,6 +3440,8 @@ function printNode(node) {
       return `\\url{${node.rawHref}}`;
     case "icon":
       return `\\icon{${node.name}}`;
+    case "usepackage":
+      return `\\usepackage{${node.names.join(", ")}}`;
     case "contact":
       return `\\${node.field}{${node.value}}`;
     case "space":
@@ -2976,6 +3455,20 @@ function printNode(node) {
       return printBlock(node);
   }
 }
+function ruleCommand(style) {
+  switch (style) {
+    case "dashed":
+      return "\\dashrule";
+    case "dotted":
+      return "\\dotrule";
+    case "thick":
+      return "\\thickrule";
+    case "double":
+      return "\\doublerule";
+    default:
+      return "\\hrule";
+  }
+}
 function indentLines(text, indent) {
   return text.split("\n").map((line) => line ? indent + line : line).join("\n");
 }
@@ -2983,22 +3476,34 @@ function indentLines(text, indent) {
 // src/editor/editor.ts
 var EditorService = class {
   constructor(options = {}) {
+    this.customLibraries = /* @__PURE__ */ new Map();
+    this.lookupLibrary = (name) => this.customLibraries.get(name.trim().toLowerCase()) ?? getBuiltinLibrary(name);
     this.registry = options.registry ?? createDefaultRegistry();
     this.theme = options.theme;
+    for (const lib of options.libraries ?? []) {
+      this.customLibraries.set(lib.name.trim().toLowerCase(), lib);
+    }
+  }
+  /** Build a registry that includes the libraries the source imports. */
+  registryFor(tokens) {
+    const names = usedLibraryNamesFromTokens(tokens);
+    return applyLibraries(this.registry, names, this.lookupLibrary).registry;
   }
   /* ----------------------------- diagnostics -------------------------- */
   getDiagnostics(source) {
     const { tokens, diagnostics: lex } = tokenize(source);
-    const { ast, diagnostics: parse2 } = new Parser(tokens, {
-      registry: this.registry
-    }).parse();
-    return [...lex, ...parse2, ...validate(ast, this.theme ? { theme: this.theme } : {})];
+    const names = usedLibraryNamesFromTokens(tokens);
+    const { registry, libraries } = applyLibraries(this.registry, names, this.lookupLibrary);
+    const { ast, diagnostics: parse2 } = new Parser(tokens, { registry }).parse();
+    const diagnostics = libraryDiagnostics(ast, [...lex, ...parse2], this.lookupLibrary);
+    const theme = this.theme ? mergeLibraryTheme(this.theme, libraries) : void 0;
+    return [...diagnostics, ...validate(ast, theme ? { theme } : {})];
   }
   /* ------------------------------ inspect ----------------------------- */
   /** Parse and return the AST for inspection / debugging. */
   inspect(source) {
     const { tokens } = tokenize(source);
-    return new Parser(tokens, { registry: this.registry }).parse().ast;
+    return new Parser(tokens, { registry: this.registryFor(tokens) }).parse().ast;
   }
   /* ------------------------------ format ------------------------------ */
   format(source) {
@@ -3007,11 +3512,12 @@ var EditorService = class {
   /* --------------------------- completion ----------------------------- */
   getCompletions(source, offset) {
     const before = source.slice(0, offset);
+    const registry = this.registryFor(tokenize(source).tokens);
     const envMatch = /\\(begin|end)\{([a-zA-Z*]*)$/.exec(before);
     if (envMatch) {
       const prefix = envMatch[2];
       const start = offset - prefix.length;
-      return this.registry.allEnvironments().filter((e) => e.name.startsWith(prefix)).map((e) => this.environmentCompletion(e, this.rangeAt(source, start, offset)));
+      return registry.allEnvironments().filter((e) => e.name.startsWith(prefix)).map((e) => this.environmentCompletion(e, this.rangeAt(source, start, offset)));
     }
     const fieldKeys = this.fieldContext(before);
     if (fieldKeys) {
@@ -3026,7 +3532,18 @@ var EditorService = class {
     if (cmdMatch) {
       const prefix = cmdMatch[1];
       const start = offset - prefix.length - 1;
-      return this.registry.allCommands().filter((c) => c.name.startsWith(prefix)).sort((a, b) => a.name.localeCompare(b.name)).map((c) => this.commandCompletion(c, this.rangeAt(source, start, offset)));
+      const range2 = this.rangeAt(source, start, offset);
+      const active = registry.allCommands().filter((c) => c.name.startsWith(prefix)).sort((a, b) => a.name.localeCompare(b.name)).map((c) => this.commandCompletion(c, range2));
+      const present = new Set(registry.commandNames());
+      const gated = Object.entries(GATED_COMMANDS).filter(([name]) => name.startsWith(prefix) && !present.has(name)).sort(([a], [b]) => a.localeCompare(b)).map(([name, lib]) => ({
+        label: `\\${name}`,
+        kind: "command",
+        detail: `requires \\usepackage{${lib}}`,
+        documentation: `\`\\${name}\` is provided by the **${lib}** library. Add \`\\usepackage{${lib}}\` to your preamble to use it.`,
+        insertText: name,
+        range: range2
+      }));
+      return [...active, ...gated];
     }
     return [];
   }
@@ -3077,6 +3594,7 @@ var EditorService = class {
   /* ------------------------------ hover ------------------------------- */
   getHover(source, offset) {
     const { tokens } = tokenize(source);
+    const registry = this.registryFor(tokens);
     const idx = tokens.findIndex(
       (t) => t.type === "Command" /* Command */ && offset >= t.range.start.offset && offset <= t.range.end.offset
     );
@@ -3084,7 +3602,7 @@ var EditorService = class {
     const token = tokens[idx];
     if (token.value === "begin" || token.value === "end") {
       const name = this.readNameAfter(tokens, idx);
-      const env = name ? this.registry.getEnvironment(name) : void 0;
+      const env = name ? registry.getEnvironment(name) : void 0;
       if (env) {
         return {
           contents: this.environmentDoc(env),
@@ -3093,12 +3611,13 @@ var EditorService = class {
       }
       return null;
     }
-    const def = this.registry.getCommand(token.value);
+    const def = registry.getCommand(token.value);
     if (!def) {
-      return {
-        contents: `Unknown command \`\\${token.value}\``,
-        range: token.range
-      };
+      const lib = GATED_COMMANDS[token.value];
+      const contents = lib ? `\`\\${token.value}\` is provided by the **${lib}** library.
+
+Add \`\\usepackage{${lib}}\` to your preamble to use it.` : `Unknown command \`\\${token.value}\``;
+      return { contents, range: token.range };
     }
     return { contents: this.commandDoc(def), range: token.range };
   }
@@ -3129,6 +3648,7 @@ ${def.example}
   /* ------------------------ semantic highlighting --------------------- */
   getSemanticTokens(source) {
     const { tokens } = tokenize(source);
+    const registry = this.registryFor(tokens);
     const out = [];
     for (let i = 0; i < tokens.length; i++) {
       const t = tokens[i];
@@ -3138,7 +3658,7 @@ ${def.example}
             out.push({ range: t.range, type: "environment", modifiers: [] });
             break;
           }
-          const def = this.registry.getCommand(t.value);
+          const def = registry.getCommand(t.value);
           out.push({
             range: t.range,
             type: def ? "command" : "command-unknown",
@@ -3201,6 +3721,53 @@ ${def.example}
   }
 };
 
+// src/editor/sync.ts
+var SOURCE_POS_ATTR = "data-rtx-pos";
+var SOURCE_TYPE_ATTR = "data-rtx-type";
+function parseSourcePos(value) {
+  if (!value) return null;
+  const sep = value.indexOf(":");
+  if (sep === -1) return null;
+  const start = Number.parseInt(value.slice(0, sep), 10);
+  const end = Number.parseInt(value.slice(sep + 1), 10);
+  if (!Number.isFinite(start) || !Number.isFinite(end) || end < start) return null;
+  return { start, end };
+}
+function readSourcePos(el) {
+  if (!el) return null;
+  return parseSourcePos(el.getAttribute(SOURCE_POS_ATTR));
+}
+function readSourceType(el) {
+  return el?.getAttribute(SOURCE_TYPE_ATTR) ?? null;
+}
+function closestSourcePos(el) {
+  if (!el) return null;
+  const match = el.closest(`[${SOURCE_POS_ATTR}]`);
+  return readSourcePos(match);
+}
+function spanLength(span) {
+  return span.end - span.start;
+}
+function spanContains(span, offset) {
+  return offset >= span.start && offset <= span.end;
+}
+function pickElementForOffset(elements, offset) {
+  let best = null;
+  let bestLen = Infinity;
+  let bestStart = -1;
+  for (const el of elements) {
+    const span = readSourcePos(el);
+    if (!span || !spanContains(span, offset)) continue;
+    const len = spanLength(span);
+    if (len < bestLen || len === bestLen && span.start > bestStart) {
+      best = el;
+      bestLen = len;
+      bestStart = span.start;
+    }
+  }
+  return best;
+}
+
 // src/incremental/incremental.ts
 var isLetter2 = (c) => c >= "a" && c <= "z" || c >= "A" && c <= "Z";
 var IncrementalCompiler = class {
@@ -3212,6 +3779,11 @@ var IncrementalCompiler = class {
     this.hits = 0;
     this.misses = 0;
     this.registry = options.registry ?? createDefaultRegistry();
+    const custom = /* @__PURE__ */ new Map();
+    for (const lib of options.libraries ?? []) {
+      custom.set(lib.name.trim().toLowerCase(), lib);
+    }
+    this.lookupLibrary = (name) => custom.get(name.trim().toLowerCase()) ?? getBuiltinLibrary(name);
   }
   /** Clear all caches (e.g. after registering new commands). */
   reset() {
@@ -3221,6 +3793,9 @@ var IncrementalCompiler = class {
   compile(source) {
     this.hits = 0;
     this.misses = 0;
+    const usedNames = usedLibraryNamesFromTokens(tokenize(source).tokens);
+    const registry = applyLibraries(this.registry, usedNames, this.lookupLibrary).registry;
+    const libsKey = usedNames.join(",");
     const segments = splitBalancedSegments(source);
     const children = [];
     const diagnostics = [];
@@ -3229,22 +3804,21 @@ var IncrementalCompiler = class {
     for (const seg of segments) {
       const text = source.slice(seg.start, seg.end);
       if (text.trim() === "") continue;
-      const posKey = `${seg.start}:${seg.startLine}:${text}`;
+      const posKey = `${libsKey}\0${seg.start}:${seg.startLine}:${text}`;
       let resolved = this.positioned.get(posKey);
       if (resolved) {
         this.hits++;
       } else {
-        let parsed = this.parseCache.get(text);
+        const cacheKey = `${libsKey}\0${text}`;
+        let parsed = this.parseCache.get(cacheKey);
         if (parsed) {
           this.hits++;
         } else {
           this.misses++;
           const { tokens } = tokenize(text);
-          const { ast: ast2, diagnostics: d } = new Parser(tokens, {
-            registry: this.registry
-          }).parse();
+          const { ast: ast2, diagnostics: d } = new Parser(tokens, { registry }).parse();
           parsed = { children: ast2.children, diagnostics: d };
-          this.parseCache.set(text, parsed);
+          this.parseCache.set(cacheKey, parsed);
         }
         const dOffset = seg.start;
         const dLine = seg.startLine - 1;
@@ -3267,7 +3841,7 @@ var IncrementalCompiler = class {
     };
     return {
       ast,
-      diagnostics,
+      diagnostics: libraryDiagnostics(ast, diagnostics, this.lookupLibrary),
       stats: {
         segments: segments.length,
         cacheHits: this.hits,
@@ -3365,6 +3939,6 @@ function endPosition(source) {
   return { offset: source.length, line, column };
 }
 
-export { BLOCK_TYPES, CommandRegistry, DiagnosticCode, DiagnosticSeverity, EditorService, HtmlRenderer, IncrementalCompiler, Parser, ReTeXEngine, ReactRenderer, SPECIAL_CHARS, TokenType, Tokenizer, badgePlugin, childrenOf, classicTheme, closestMatch, collect, compactTheme, createDefaultRegistry, createEngine, dateRange, defaultTheme, entryParts, escapeAttribute, escapeHtml, flattenText, getIcon, getTheme, hasIcon, iconNames, iconToSvg, isBalanced, isBlockNode, isNode, isParent, isSafeColor, isSafeDimension, levenshtein, mergeRanges, modernTheme, nodePathAt, normalizeWhitespace, pageCss, parse, parseKeyValArg, parseListArg, pos, printDocument, range, rangeContains, ratingPlugin, registerIcon, renderHtml, renderHtmlDocument, renderJson, renderPdf, renderPrintHtml, renderReact, resolveIconName, resolveTheme, sanitizeStyleValue, sanitizeUrl, splitBalancedSegments, splitPreamble, splitTopLevel, themeToCss, themes, toJsonTree, toRegions, tokenize, validate, walk };
+export { BLOCK_TYPES, CommandRegistry, DiagnosticCode, DiagnosticSeverity, EditorService, GATED_COMMANDS, HtmlRenderer, IncrementalCompiler, Parser, ReTeXEngine, ReactRenderer, SOURCE_POS_ATTR, SOURCE_TYPE_ATTR, SPECIAL_CHARS, TokenType, Tokenizer, applyLibraries, badgePlugin, blankTheme, builtinLibraries, builtinLibraryNames, childrenOf, classicLibrary, classicTheme, closestMatch, closestSourcePos, collect, collectLibraryOverrides, colorCommands, colorsLibrary, compactLibrary, compactTheme, createDefaultRegistry, createEngine, dateRange, defaultTheme, entryParts, escapeAttribute, escapeHtml, flattenText, fontCommands, fontStacks, fontTheme, fontsLibrary, getBuiltinLibrary, getIcon, getTheme, hasIcon, iconNames, iconToSvg, isBalanced, isBlockNode, isNode, isParent, isSafeColor, isSafeDimension, levenshtein, libraryDiagnostics, mergeLibraryTheme, mergeRanges, modernLibrary, modernTheme, nodePathAt, normalizeWhitespace, pageCss, palettes, parse, parseKeyValArg, parseListArg, parseSourcePos, pickElementForOffset, pos, printDocument, range, rangeContains, ratingPlugin, readSourcePos, readSourceType, registerIcon, renderHtml, renderHtmlDocument, renderJson, renderPdf, renderPrintHtml, renderReact, resolveIconName, resolveLibraryName, resolveTheme, sanitizeStyleValue, sanitizeUrl, shapeCommands, shapesLibrary, spanContains, spanLength, splitBalancedSegments, splitPreamble, splitTopLevel, themeToCss, themes, toJsonTree, toRegions, tokenize, usedLibraryNamesFromAst, usedLibraryNamesFromTokens, validate, walk };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map