@sciexpr/renderer 0.1.0

package/dist/index.cjs

@@ -0,0 +1,489 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  KatexRenderer: () => KatexRenderer,
+  LatexReverseRenderer: () => LatexReverseRenderer,
+  MathMLRenderer: () => MathMLRenderer,
+  RendererRegistry: () => RendererRegistry,
+  UnicodeRenderer: () => UnicodeRenderer
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var RendererRegistry = class {
+  renderers = /* @__PURE__ */ new Map();
+  /** 注册渲染器 */
+  register(renderer) {
+    this.renderers.set(renderer.id, renderer);
+  }
+  /** 移除渲染器 */
+  unregister(id) {
+    return this.renderers.delete(id);
+  }
+  /** 按 ID 获取 */
+  get(id) {
+    return this.renderers.get(id);
+  }
+  /** 按输出格式查找 */
+  findByFormat(format) {
+    for (const r of this.renderers.values()) {
+      if (r.outputFormat === format) return r;
+    }
+    return void 0;
+  }
+  /**
+   * 渲染 AST
+   * @param root AST 根节点
+   * @param format 目标输出格式
+   * @param options 渲染选项
+   */
+  render(root, format, options) {
+    const renderer = this.findByFormat(format);
+    if (!renderer) {
+      throw new Error(`No renderer registered for format: ${format}`);
+    }
+    return renderer.render(root, options);
+  }
+  /** 列出所有已注册格式 */
+  listFormats() {
+    return Array.from(this.renderers.values()).map((r) => r.outputFormat);
+  }
+};
+
+// src/latex-renderer.ts
+var LatexReverseRenderer = class {
+  id = "latex-reverse";
+  outputFormat = "latex";
+  render(root, _options) {
+    const latex = this.renderNode(root);
+    return { value: latex, format: "latex" };
+  }
+  renderNode(node) {
+    const n = node;
+    switch (n.kind) {
+      case "root":
+        return n.children.map((c) => this.renderNode(c)).join("");
+      case "symbol":
+        return n.value;
+      case "frac":
+        return `\\frac{${this.renderNode(n.numerator)}}{${this.renderNode(n.denominator)}}`;
+      case "script": {
+        let result = this.renderNode(n.base);
+        if (n.sub) {
+          result += `_{${this.renderNode(n.sub)}}`;
+        }
+        if (n.super) {
+          result += `^{${this.renderNode(n.super)}}`;
+        }
+        return result;
+      }
+      case "radical": {
+        if (n.index) {
+          return `\\sqrt[${this.renderNode(n.index)}]{${this.renderNode(n.radicand)}}`;
+        }
+        return `\\sqrt{${this.renderNode(n.radicand)}}`;
+      }
+      case "delimiter":
+        return `${n.left}${this.renderNode(n.body)}${n.right}`;
+      case "matrix": {
+        const cols = n.columnAlign ? `{${n.columnAlign.join("")}}` : "";
+        const type = n.matrixType ?? "matrix";
+        const rows = n.rows.map((row) => row.map((cell) => this.renderNode(cell)).join(" & ")).join(" \\\\ ");
+        return `\\begin{${type}}${cols}${rows}\\end{${type}}`;
+      }
+      case "text":
+        return `\\text{${n.content}}`;
+      case "space":
+        return n.width === 1 ? "\\," : "\\quad";
+      case "accent":
+        return `\\${n.accentType}{${this.renderNode(n.base)}}`;
+      case "largeop": {
+        let result = `\\${n.opType}`;
+        if (n.lower) {
+          result += `_{${this.renderNode(n.lower)}}`;
+        }
+        if (n.upper) {
+          result += `^{${this.renderNode(n.upper)}}`;
+        }
+        if (n.body) {
+          result += `{${this.renderNode(n.body)}}`;
+        }
+        return result;
+      }
+      case "color":
+        return `\\color{${n.color}}{${this.renderNode(n.body)}}`;
+      case "group":
+        return `{${n.children.map((c) => this.renderNode(c)).join("")}}`;
+      case "chem-element": {
+        let result = n.symbol;
+        if (n.count && n.count > 1) {
+          result += n.count;
+        }
+        if (n.charge) {
+          result += `^{${n.charge}${n.chargeSign ?? "+"}}`;
+        }
+        return result;
+      }
+      case "chem-bond": {
+        const bondMap = {
+          single: "-",
+          double: "=",
+          triple: "\\equiv ",
+          aromatic: "~",
+          coordinate: "->"
+        };
+        return `${this.renderNode(n.left)}${bondMap[n.bondType] ?? "-"}${this.renderNode(n.right)}`;
+      }
+      case "chem-reaction": {
+        const arrowMap = {
+          "->": "->",
+          "<-": "<-",
+          "<=>": "<=>",
+          "<->": "<->",
+          "->[": "->[",
+          "<-[": "<-[",
+          "<=>>": "<=>>",
+          "<<=>": "<<=>"
+        };
+        const react = n.reactants.map((r) => this.renderNode(r)).join(" + ");
+        const prod = n.products.map((p) => this.renderNode(p)).join(" + ");
+        return `\\ce{${react} ${arrowMap[n.arrowType] ?? "->"} ${prod}}`;
+      }
+      case "chem-group":
+        return n.atoms.map((a) => this.renderNode(a)).join("");
+      default:
+        return "";
+    }
+  }
+};
+
+// src/katex-renderer.ts
+var KatexRenderer = class {
+  id = "katex";
+  outputFormat = "html";
+  latexRenderer = new LatexReverseRenderer();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  katexInstance = null;
+  constructor() {
+    this.loadKatex();
+  }
+  async loadKatex() {
+    try {
+      this.katexInstance = await import("katex");
+    } catch {
+      this.katexInstance = null;
+    }
+  }
+  /** 手动设置 KaTeX 实例 */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  setKatex(katex) {
+    this.katexInstance = katex;
+  }
+  /** 检查 KaTeX 是否可用 */
+  isAvailable() {
+    return this.katexInstance !== null;
+  }
+  render(root, options) {
+    if (!this.katexInstance) {
+      const latex = this.latexRenderer.render(root).value;
+      return {
+        value: `<code class="sciexpr-latex-fallback">${this.escapeHtml(latex)}</code>`,
+        format: "html",
+        warnings: [{ message: "KaTeX not available, showing LaTeX source", code: "KATEX_UNAVAILABLE" }]
+      };
+    }
+    const latexSource = this.latexRenderer.render(root).value;
+    try {
+      const html = this.katexInstance.renderToString(latexSource, {
+        displayMode: options?.displayMode ?? root.metadata?.displayMode ?? false,
+        throwOnError: options?.throwOnError ?? false,
+        macros: options?.macros,
+        trust: true
+      });
+      return { value: html, format: "html" };
+    } catch (err) {
+      const error = {
+        message: err instanceof Error ? err.message : String(err)
+      };
+      options?.hooks?.onError?.(error);
+      if (options?.throwOnError) {
+        throw error;
+      }
+      return {
+        value: `<span class="sciexpr-error">${this.escapeHtml(latexSource)}</span>`,
+        format: "html",
+        warnings: [{ message: error.message, code: "KATEX_RENDER_ERROR" }]
+      };
+    }
+  }
+  escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  }
+};
+
+// src/unicode-renderer.ts
+var UnicodeRenderer = class _UnicodeRenderer {
+  id = "unicode";
+  outputFormat = "unicode";
+  static GREEK_MAP = {
+    "\\alpha": "\u03B1",
+    "\\beta": "\u03B2",
+    "\\gamma": "\u03B3",
+    "\\delta": "\u03B4",
+    "\\pi": "\u03C0",
+    "\\theta": "\u03B8",
+    "\\lambda": "\u03BB",
+    "\\mu": "\u03BC",
+    "\\sigma": "\u03C3",
+    "\\omega": "\u03C9",
+    "\\infty": "\u221E",
+    "\\partial": "\u2202",
+    "\\nabla": "\u2207",
+    "\\forall": "\u2200",
+    "\\exists": "\u2203",
+    "\\times": "\xD7",
+    "\\pm": "\xB1",
+    "\\neq": "\u2260",
+    "\\leq": "\u2264",
+    "\\geq": "\u2265",
+    "\\approx": "\u2248",
+    "\\to": "\u2192",
+    "\\Rightarrow": "\u21D2",
+    "\\int": "\u222B",
+    "\\sum": "\u2211"
+  };
+  static SUPER_DIGITS = {
+    "0": "\u2070",
+    "1": "\xB9",
+    "2": "\xB2",
+    "3": "\xB3",
+    "4": "\u2074",
+    "5": "\u2075",
+    "6": "\u2076",
+    "7": "\u2077",
+    "8": "\u2078",
+    "9": "\u2079",
+    "+": "\u207A",
+    "-": "\u207B"
+  };
+  static SUB_DIGITS = {
+    "0": "\u2080",
+    "1": "\u2081",
+    "2": "\u2082",
+    "3": "\u2083",
+    "4": "\u2084",
+    "5": "\u2085",
+    "6": "\u2086",
+    "7": "\u2087",
+    "8": "\u2088",
+    "9": "\u2089",
+    "+": "\u208A",
+    "-": "\u208B"
+  };
+  render(root, _options) {
+    const unicode = this.renderNode(root);
+    return { value: unicode, format: "unicode" };
+  }
+  renderNode(node) {
+    const n = node;
+    switch (n.kind) {
+      case "root":
+        return n.children.map((c) => this.renderNode(c)).join("");
+      case "symbol":
+        return _UnicodeRenderer.GREEK_MAP[n.value] ?? n.value;
+      case "frac":
+        return `(${this.renderNode(n.numerator)})/(${this.renderNode(n.denominator)})`;
+      case "script": {
+        let result = this.renderNode(n.base);
+        if (n.sub) result += this.toSub(this.renderNode(n.sub));
+        if (n.super) result += this.toSuper(this.renderNode(n.super));
+        return result;
+      }
+      case "radical":
+        if (n.index) {
+          return `${this.toSuper(this.renderNode(n.index))}\u221A(${this.renderNode(n.radicand)})`;
+        }
+        return `\u221A(${this.renderNode(n.radicand)})`;
+      case "delimiter":
+        return n.left + this.renderNode(n.body) + n.right;
+      case "text":
+        return n.content;
+      case "space":
+        return " ";
+      case "accent":
+        return this.renderNode(n.base);
+      case "largeop":
+        return this.renderNode(n.body ?? { kind: "text", content: "" });
+      case "group":
+        return n.children.map((c) => this.renderNode(c)).join("");
+      case "chem-element": {
+        let result = n.symbol;
+        if (n.count && n.count > 1) result += this.toSub(String(n.count));
+        if (n.charge) result += this.toSuper(`${n.charge}${n.chargeSign ?? "+"}`);
+        return result;
+      }
+      case "chem-bond":
+        return this.renderNode(n.left) + "-" + this.renderNode(n.right);
+      case "chem-reaction":
+        return n.reactants.map((r) => this.renderNode(r)).join(" + ") + " \u2192 " + n.products.map((p) => this.renderNode(p)).join(" + ");
+      case "chem-group":
+        return n.atoms.map((a) => this.renderNode(a)).join("");
+      default:
+        return "";
+    }
+  }
+  toSuper(text) {
+    let r = "";
+    for (const ch of text) r += _UnicodeRenderer.SUPER_DIGITS[ch] ?? ch;
+    return r;
+  }
+  toSub(text) {
+    let r = "";
+    for (const ch of text) r += _UnicodeRenderer.SUB_DIGITS[ch] ?? ch;
+    return r;
+  }
+};
+
+// src/mathml-renderer.ts
+var MathMLRenderer = class {
+  id = "mathml";
+  outputFormat = "mathml";
+  render(root, options) {
+    const display = options?.displayMode ?? root.metadata?.displayMode ?? false;
+    const body = this.renderNode(root);
+    const mathml = display ? `<math xmlns="http://www.w3.org/1998/Math/MathML" display="block">${body}</math>` : `<math xmlns="http://www.w3.org/1998/Math/MathML">${body}</math>`;
+    return { value: mathml, format: "mathml" };
+  }
+  renderNode(node) {
+    const n = node;
+    switch (n.kind) {
+      case "root":
+        return n.children.length === 1 ? this.renderNode(n.children[0]) : `<mrow>${n.children.map((c) => this.renderNode(c)).join("")}</mrow>`;
+      case "symbol": {
+        const value = this.escapeXml(n.value);
+        const greek = {
+          "\\alpha": "\u03B1",
+          "\\beta": "\u03B2",
+          "\\gamma": "\u03B3",
+          "\\delta": "\u03B4",
+          "\\pi": "\u03C0",
+          "\\theta": "\u03B8",
+          "\\lambda": "\u03BB",
+          "\\mu": "\u03BC",
+          "\\sigma": "\u03C3",
+          "\\omega": "\u03C9",
+          "\\infty": "\u221E",
+          "\\partial": "\u2202"
+        };
+        if (greek[n.value]) {
+          return `<mi>${greek[n.value]}</mi>`;
+        }
+        if (/^\d+(\.\d+)?$/.test(value)) {
+          return `<mn>${value}</mn>`;
+        }
+        return `<mi>${value}</mi>`;
+      }
+      case "frac":
+        return `<mfrac><mrow>${this.renderNode(n.numerator)}</mrow><mrow>${this.renderNode(n.denominator)}</mrow></mfrac>`;
+      case "script": {
+        let result = this.renderNode(n.base);
+        if (n.sub) {
+          result = `<msub>${result}<mrow>${this.renderNode(n.sub)}</mrow></msub>`;
+        }
+        if (n.super) {
+          result = `<msup>${result}<mrow>${this.renderNode(n.super)}</mrow></msup>`;
+        }
+        if (n.sub && n.super) {
+          result = `<msubsup>${this.renderNode(n.base)}<mrow>${this.renderNode(n.sub)}</mrow><mrow>${this.renderNode(n.super)}</mrow></msubsup>`;
+        }
+        return result;
+      }
+      case "radical": {
+        if (n.index) {
+          return `<mroot><mrow>${this.renderNode(n.radicand)}</mrow><mrow>${this.renderNode(n.index)}</mrow></mroot>`;
+        }
+        return `<msqrt><mrow>${this.renderNode(n.radicand)}</mrow></msqrt>`;
+      }
+      case "delimiter":
+        return `<mfenced open="${this.escapeXml(n.left)}" close="${this.escapeXml(n.right)}">${this.renderNode(n.body)}</mfenced>`;
+      case "matrix": {
+        const rows = n.rows.map((row) => `<mtr>${row.map((cell) => `<mtd>${this.renderNode(cell)}</mtd>`).join("")}</mtr>`).join("");
+        return `<mtable>${rows}</mtable>`;
+      }
+      case "text":
+        return `<mtext>${this.escapeXml(n.content)}</mtext>`;
+      case "space":
+        return `<mspace width="${n.width}em"/>`;
+      case "accent": {
+        const accentMap = {
+          hat: "^",
+          tilde: "~",
+          bar: "\xAF",
+          dot: "\u02D9",
+          ddot: "\xA8",
+          vec: "\u2192"
+        };
+        return `<mover accent="true"><mrow>${this.renderNode(n.base)}</mrow><mo>${accentMap[n.accentType] ?? "^"}</mo></mover>`;
+      }
+      case "largeop": {
+        let result = `<mo>${n.opType}</mo>`;
+        if (n.body) {
+          result = `<mrow>${result}<mrow>${this.renderNode(n.body)}</mrow></mrow>`;
+        }
+        if (n.lower) {
+          result = `<munder>${result}<mrow>${this.renderNode(n.lower)}</mrow></munder>`;
+        }
+        if (n.upper) {
+          result = `<mover>${result}<mrow>${this.renderNode(n.upper)}</mrow></mover>`;
+        }
+        return result;
+      }
+      case "group":
+        return `<mrow>${n.children.map((c) => this.renderNode(c)).join("")}</mrow>`;
+      case "chem-element":
+        return `<mi mathvariant="normal">${this.escapeXml(n.symbol)}</mi>` + (n.count ? `<mn>${n.count}</mn>` : "");
+      default:
+        return "";
+    }
+  }
+  escapeXml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  KatexRenderer,
+  LatexReverseRenderer,
+  MathMLRenderer,
+  RendererRegistry,
+  UnicodeRenderer
+});

package/dist/index.d.cts

@@ -0,0 +1,151 @@
+import { ExpressionRoot, ExpressionNode, SourceLocation } from '@sciexpr/core';
+
+/** 渲染输出格式 */
+type RenderOutputFormat = 'html' | 'mathml' | 'latex' | 'unicode' | 'omml' | 'svg';
+/** 渲染结果 */
+interface RenderResult {
+    /** 渲染输出值 */
+    value: string;
+    /** 输出格式 */
+    format: RenderOutputFormat;
+    /** 警告信息 */
+    warnings?: RenderWarning[];
+}
+/** 渲染警告 */
+interface RenderWarning {
+    message: string;
+    code: string;
+}
+/** 渲染错误 */
+interface RenderError {
+    message: string;
+    node?: ExpressionNode;
+    source?: SourceLocation;
+}
+/** 渲染钩子 */
+interface RenderHooks {
+    /** 渲染前转换 AST */
+    beforeRender?: (node: ExpressionNode) => ExpressionNode;
+    /** 渲染后处理结果 */
+    afterRender?: (result: RenderResult) => RenderResult;
+    /** 错误回调 */
+    onError?: (error: RenderError) => void;
+}
+/** 渲染选项 */
+interface RenderOptions {
+    /** 是否为 display 模式（块级公式） */
+    displayMode?: boolean;
+    /** 错误时是否抛异常 */
+    throwOnError?: boolean;
+    /** 自定义宏 */
+    macros?: Record<string, string>;
+    /** 渲染钩子 */
+    hooks?: RenderHooks;
+}
+/**
+ * 渲染器接口
+ *
+ * 所有渲染适配器的统一接口。
+ * 实现此接口即可将 AST 渲染为特定输出格式。
+ */
+interface IRenderer {
+    /** 渲染器唯一标识 */
+    readonly id: string;
+    /** 输出格式 */
+    readonly outputFormat: RenderOutputFormat;
+    /**
+     * 渲染 AST 为最终格式
+     * @param root AST 根节点
+     * @param options 渲染选项
+     */
+    render(root: ExpressionRoot, options?: RenderOptions): RenderResult;
+}
+/**
+ * 渲染器注册表
+ * 管理所有渲染器实例，支持按格式查找和注册自定义渲染器
+ */
+declare class RendererRegistry {
+    private renderers;
+    /** 注册渲染器 */
+    register(renderer: IRenderer): void;
+    /** 移除渲染器 */
+    unregister(id: string): boolean;
+    /** 按 ID 获取 */
+    get(id: string): IRenderer | undefined;
+    /** 按输出格式查找 */
+    findByFormat(format: RenderOutputFormat): IRenderer | undefined;
+    /**
+     * 渲染 AST
+     * @param root AST 根节点
+     * @param format 目标输出格式
+     * @param options 渲染选项
+     */
+    render(root: ExpressionRoot, format: RenderOutputFormat, options?: RenderOptions): RenderResult;
+    /** 列出所有已注册格式 */
+    listFormats(): RenderOutputFormat[];
+}
+
+/**
+ * AST → LaTeX 反向渲染器
+ *
+ * 将内部 AST 还原为 LaTeX 源码。
+ * 支持所有 AST 节点类型的双向转换。
+ */
+declare class LatexReverseRenderer implements IRenderer {
+    readonly id = "latex-reverse";
+    readonly outputFormat: "latex";
+    render(root: ExpressionRoot, _options?: RenderOptions): RenderResult;
+    private renderNode;
+}
+
+/**
+ * KaTeX HTML 渲染器
+ *
+ * 将 AST 先还原为 LaTeX，再通过 KaTeX 渲染为 HTML。
+ * KaTeX 为 peerDependency，使用方需自行安装。
+ */
+declare class KatexRenderer implements IRenderer {
+    readonly id = "katex";
+    readonly outputFormat: "html";
+    private latexRenderer;
+    private katexInstance;
+    constructor();
+    private loadKatex;
+    /** 手动设置 KaTeX 实例 */
+    setKatex(katex: any): void;
+    /** 检查 KaTeX 是否可用 */
+    isAvailable(): boolean;
+    render(root: ExpressionRoot, options?: RenderOptions): RenderResult;
+    private escapeHtml;
+}
+
+/**
+ * Unicode 纯文本渲染器
+ */
+declare class UnicodeRenderer implements IRenderer {
+    readonly id = "unicode";
+    readonly outputFormat: "unicode";
+    private static readonly GREEK_MAP;
+    private static readonly SUPER_DIGITS;
+    private static readonly SUB_DIGITS;
+    render(root: ExpressionRoot, _options?: RenderOptions): RenderResult;
+    private renderNode;
+    private toSuper;
+    private toSub;
+}
+
+/**
+ * MathML 渲染器
+ *
+ * 将 AST 渲染为 MathML 3.0 标准格式。
+ * 适用于无障碍场景、Word 导入和需要语义化公式的场合。
+ */
+declare class MathMLRenderer implements IRenderer {
+    readonly id = "mathml";
+    readonly outputFormat: "mathml";
+    render(root: ExpressionRoot, options?: RenderOptions): RenderResult;
+    private renderNode;
+    private escapeXml;
+}
+
+export { type IRenderer, KatexRenderer, LatexReverseRenderer, MathMLRenderer, type RenderError, type RenderHooks, type RenderOptions, type RenderOutputFormat, type RenderResult, type RenderWarning, RendererRegistry, UnicodeRenderer };

package/dist/index.d.ts

@@ -0,0 +1,151 @@
+import { ExpressionRoot, ExpressionNode, SourceLocation } from '@sciexpr/core';
+
+/** 渲染输出格式 */
+type RenderOutputFormat = 'html' | 'mathml' | 'latex' | 'unicode' | 'omml' | 'svg';
+/** 渲染结果 */
+interface RenderResult {
+    /** 渲染输出值 */
+    value: string;
+    /** 输出格式 */
+    format: RenderOutputFormat;
+    /** 警告信息 */
+    warnings?: RenderWarning[];
+}
+/** 渲染警告 */
+interface RenderWarning {
+    message: string;
+    code: string;
+}
+/** 渲染错误 */
+interface RenderError {
+    message: string;
+    node?: ExpressionNode;
+    source?: SourceLocation;
+}
+/** 渲染钩子 */
+interface RenderHooks {
+    /** 渲染前转换 AST */
+    beforeRender?: (node: ExpressionNode) => ExpressionNode;
+    /** 渲染后处理结果 */
+    afterRender?: (result: RenderResult) => RenderResult;
+    /** 错误回调 */
+    onError?: (error: RenderError) => void;
+}
+/** 渲染选项 */
+interface RenderOptions {
+    /** 是否为 display 模式（块级公式） */
+    displayMode?: boolean;
+    /** 错误时是否抛异常 */
+    throwOnError?: boolean;
+    /** 自定义宏 */
+    macros?: Record<string, string>;
+    /** 渲染钩子 */
+    hooks?: RenderHooks;
+}
+/**
+ * 渲染器接口
+ *
+ * 所有渲染适配器的统一接口。
+ * 实现此接口即可将 AST 渲染为特定输出格式。
+ */
+interface IRenderer {
+    /** 渲染器唯一标识 */
+    readonly id: string;
+    /** 输出格式 */
+    readonly outputFormat: RenderOutputFormat;
+    /**
+     * 渲染 AST 为最终格式
+     * @param root AST 根节点
+     * @param options 渲染选项
+     */
+    render(root: ExpressionRoot, options?: RenderOptions): RenderResult;
+}
+/**
+ * 渲染器注册表
+ * 管理所有渲染器实例，支持按格式查找和注册自定义渲染器
+ */
+declare class RendererRegistry {
+    private renderers;
+    /** 注册渲染器 */
+    register(renderer: IRenderer): void;
+    /** 移除渲染器 */
+    unregister(id: string): boolean;
+    /** 按 ID 获取 */
+    get(id: string): IRenderer | undefined;
+    /** 按输出格式查找 */
+    findByFormat(format: RenderOutputFormat): IRenderer | undefined;
+    /**
+     * 渲染 AST
+     * @param root AST 根节点
+     * @param format 目标输出格式
+     * @param options 渲染选项
+     */
+    render(root: ExpressionRoot, format: RenderOutputFormat, options?: RenderOptions): RenderResult;
+    /** 列出所有已注册格式 */
+    listFormats(): RenderOutputFormat[];
+}
+
+/**
+ * AST → LaTeX 反向渲染器
+ *
+ * 将内部 AST 还原为 LaTeX 源码。
+ * 支持所有 AST 节点类型的双向转换。
+ */
+declare class LatexReverseRenderer implements IRenderer {
+    readonly id = "latex-reverse";
+    readonly outputFormat: "latex";
+    render(root: ExpressionRoot, _options?: RenderOptions): RenderResult;
+    private renderNode;
+}
+
+/**
+ * KaTeX HTML 渲染器
+ *
+ * 将 AST 先还原为 LaTeX，再通过 KaTeX 渲染为 HTML。
+ * KaTeX 为 peerDependency，使用方需自行安装。
+ */
+declare class KatexRenderer implements IRenderer {
+    readonly id = "katex";
+    readonly outputFormat: "html";
+    private latexRenderer;
+    private katexInstance;
+    constructor();
+    private loadKatex;
+    /** 手动设置 KaTeX 实例 */
+    setKatex(katex: any): void;
+    /** 检查 KaTeX 是否可用 */
+    isAvailable(): boolean;
+    render(root: ExpressionRoot, options?: RenderOptions): RenderResult;
+    private escapeHtml;
+}
+
+/**
+ * Unicode 纯文本渲染器
+ */
+declare class UnicodeRenderer implements IRenderer {
+    readonly id = "unicode";
+    readonly outputFormat: "unicode";
+    private static readonly GREEK_MAP;
+    private static readonly SUPER_DIGITS;
+    private static readonly SUB_DIGITS;
+    render(root: ExpressionRoot, _options?: RenderOptions): RenderResult;
+    private renderNode;
+    private toSuper;
+    private toSub;
+}
+
+/**
+ * MathML 渲染器
+ *
+ * 将 AST 渲染为 MathML 3.0 标准格式。
+ * 适用于无障碍场景、Word 导入和需要语义化公式的场合。
+ */
+declare class MathMLRenderer implements IRenderer {
+    readonly id = "mathml";
+    readonly outputFormat: "mathml";
+    render(root: ExpressionRoot, options?: RenderOptions): RenderResult;
+    private renderNode;
+    private escapeXml;
+}
+
+export { type IRenderer, KatexRenderer, LatexReverseRenderer, MathMLRenderer, type RenderError, type RenderHooks, type RenderOptions, type RenderOutputFormat, type RenderResult, type RenderWarning, RendererRegistry, UnicodeRenderer };

package/dist/index.js

@@ -0,0 +1,448 @@
+// src/types.ts
+var RendererRegistry = class {
+  renderers = /* @__PURE__ */ new Map();
+  /** 注册渲染器 */
+  register(renderer) {
+    this.renderers.set(renderer.id, renderer);
+  }
+  /** 移除渲染器 */
+  unregister(id) {
+    return this.renderers.delete(id);
+  }
+  /** 按 ID 获取 */
+  get(id) {
+    return this.renderers.get(id);
+  }
+  /** 按输出格式查找 */
+  findByFormat(format) {
+    for (const r of this.renderers.values()) {
+      if (r.outputFormat === format) return r;
+    }
+    return void 0;
+  }
+  /**
+   * 渲染 AST
+   * @param root AST 根节点
+   * @param format 目标输出格式
+   * @param options 渲染选项
+   */
+  render(root, format, options) {
+    const renderer = this.findByFormat(format);
+    if (!renderer) {
+      throw new Error(`No renderer registered for format: ${format}`);
+    }
+    return renderer.render(root, options);
+  }
+  /** 列出所有已注册格式 */
+  listFormats() {
+    return Array.from(this.renderers.values()).map((r) => r.outputFormat);
+  }
+};
+
+// src/latex-renderer.ts
+var LatexReverseRenderer = class {
+  id = "latex-reverse";
+  outputFormat = "latex";
+  render(root, _options) {
+    const latex = this.renderNode(root);
+    return { value: latex, format: "latex" };
+  }
+  renderNode(node) {
+    const n = node;
+    switch (n.kind) {
+      case "root":
+        return n.children.map((c) => this.renderNode(c)).join("");
+      case "symbol":
+        return n.value;
+      case "frac":
+        return `\\frac{${this.renderNode(n.numerator)}}{${this.renderNode(n.denominator)}}`;
+      case "script": {
+        let result = this.renderNode(n.base);
+        if (n.sub) {
+          result += `_{${this.renderNode(n.sub)}}`;
+        }
+        if (n.super) {
+          result += `^{${this.renderNode(n.super)}}`;
+        }
+        return result;
+      }
+      case "radical": {
+        if (n.index) {
+          return `\\sqrt[${this.renderNode(n.index)}]{${this.renderNode(n.radicand)}}`;
+        }
+        return `\\sqrt{${this.renderNode(n.radicand)}}`;
+      }
+      case "delimiter":
+        return `${n.left}${this.renderNode(n.body)}${n.right}`;
+      case "matrix": {
+        const cols = n.columnAlign ? `{${n.columnAlign.join("")}}` : "";
+        const type = n.matrixType ?? "matrix";
+        const rows = n.rows.map((row) => row.map((cell) => this.renderNode(cell)).join(" & ")).join(" \\\\ ");
+        return `\\begin{${type}}${cols}${rows}\\end{${type}}`;
+      }
+      case "text":
+        return `\\text{${n.content}}`;
+      case "space":
+        return n.width === 1 ? "\\," : "\\quad";
+      case "accent":
+        return `\\${n.accentType}{${this.renderNode(n.base)}}`;
+      case "largeop": {
+        let result = `\\${n.opType}`;
+        if (n.lower) {
+          result += `_{${this.renderNode(n.lower)}}`;
+        }
+        if (n.upper) {
+          result += `^{${this.renderNode(n.upper)}}`;
+        }
+        if (n.body) {
+          result += `{${this.renderNode(n.body)}}`;
+        }
+        return result;
+      }
+      case "color":
+        return `\\color{${n.color}}{${this.renderNode(n.body)}}`;
+      case "group":
+        return `{${n.children.map((c) => this.renderNode(c)).join("")}}`;
+      case "chem-element": {
+        let result = n.symbol;
+        if (n.count && n.count > 1) {
+          result += n.count;
+        }
+        if (n.charge) {
+          result += `^{${n.charge}${n.chargeSign ?? "+"}}`;
+        }
+        return result;
+      }
+      case "chem-bond": {
+        const bondMap = {
+          single: "-",
+          double: "=",
+          triple: "\\equiv ",
+          aromatic: "~",
+          coordinate: "->"
+        };
+        return `${this.renderNode(n.left)}${bondMap[n.bondType] ?? "-"}${this.renderNode(n.right)}`;
+      }
+      case "chem-reaction": {
+        const arrowMap = {
+          "->": "->",
+          "<-": "<-",
+          "<=>": "<=>",
+          "<->": "<->",
+          "->[": "->[",
+          "<-[": "<-[",
+          "<=>>": "<=>>",
+          "<<=>": "<<=>"
+        };
+        const react = n.reactants.map((r) => this.renderNode(r)).join(" + ");
+        const prod = n.products.map((p) => this.renderNode(p)).join(" + ");
+        return `\\ce{${react} ${arrowMap[n.arrowType] ?? "->"} ${prod}}`;
+      }
+      case "chem-group":
+        return n.atoms.map((a) => this.renderNode(a)).join("");
+      default:
+        return "";
+    }
+  }
+};
+
+// src/katex-renderer.ts
+var KatexRenderer = class {
+  id = "katex";
+  outputFormat = "html";
+  latexRenderer = new LatexReverseRenderer();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  katexInstance = null;
+  constructor() {
+    this.loadKatex();
+  }
+  async loadKatex() {
+    try {
+      this.katexInstance = await import("katex");
+    } catch {
+      this.katexInstance = null;
+    }
+  }
+  /** 手动设置 KaTeX 实例 */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  setKatex(katex) {
+    this.katexInstance = katex;
+  }
+  /** 检查 KaTeX 是否可用 */
+  isAvailable() {
+    return this.katexInstance !== null;
+  }
+  render(root, options) {
+    if (!this.katexInstance) {
+      const latex = this.latexRenderer.render(root).value;
+      return {
+        value: `<code class="sciexpr-latex-fallback">${this.escapeHtml(latex)}</code>`,
+        format: "html",
+        warnings: [{ message: "KaTeX not available, showing LaTeX source", code: "KATEX_UNAVAILABLE" }]
+      };
+    }
+    const latexSource = this.latexRenderer.render(root).value;
+    try {
+      const html = this.katexInstance.renderToString(latexSource, {
+        displayMode: options?.displayMode ?? root.metadata?.displayMode ?? false,
+        throwOnError: options?.throwOnError ?? false,
+        macros: options?.macros,
+        trust: true
+      });
+      return { value: html, format: "html" };
+    } catch (err) {
+      const error = {
+        message: err instanceof Error ? err.message : String(err)
+      };
+      options?.hooks?.onError?.(error);
+      if (options?.throwOnError) {
+        throw error;
+      }
+      return {
+        value: `<span class="sciexpr-error">${this.escapeHtml(latexSource)}</span>`,
+        format: "html",
+        warnings: [{ message: error.message, code: "KATEX_RENDER_ERROR" }]
+      };
+    }
+  }
+  escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  }
+};
+
+// src/unicode-renderer.ts
+var UnicodeRenderer = class _UnicodeRenderer {
+  id = "unicode";
+  outputFormat = "unicode";
+  static GREEK_MAP = {
+    "\\alpha": "\u03B1",
+    "\\beta": "\u03B2",
+    "\\gamma": "\u03B3",
+    "\\delta": "\u03B4",
+    "\\pi": "\u03C0",
+    "\\theta": "\u03B8",
+    "\\lambda": "\u03BB",
+    "\\mu": "\u03BC",
+    "\\sigma": "\u03C3",
+    "\\omega": "\u03C9",
+    "\\infty": "\u221E",
+    "\\partial": "\u2202",
+    "\\nabla": "\u2207",
+    "\\forall": "\u2200",
+    "\\exists": "\u2203",
+    "\\times": "\xD7",
+    "\\pm": "\xB1",
+    "\\neq": "\u2260",
+    "\\leq": "\u2264",
+    "\\geq": "\u2265",
+    "\\approx": "\u2248",
+    "\\to": "\u2192",
+    "\\Rightarrow": "\u21D2",
+    "\\int": "\u222B",
+    "\\sum": "\u2211"
+  };
+  static SUPER_DIGITS = {
+    "0": "\u2070",
+    "1": "\xB9",
+    "2": "\xB2",
+    "3": "\xB3",
+    "4": "\u2074",
+    "5": "\u2075",
+    "6": "\u2076",
+    "7": "\u2077",
+    "8": "\u2078",
+    "9": "\u2079",
+    "+": "\u207A",
+    "-": "\u207B"
+  };
+  static SUB_DIGITS = {
+    "0": "\u2080",
+    "1": "\u2081",
+    "2": "\u2082",
+    "3": "\u2083",
+    "4": "\u2084",
+    "5": "\u2085",
+    "6": "\u2086",
+    "7": "\u2087",
+    "8": "\u2088",
+    "9": "\u2089",
+    "+": "\u208A",
+    "-": "\u208B"
+  };
+  render(root, _options) {
+    const unicode = this.renderNode(root);
+    return { value: unicode, format: "unicode" };
+  }
+  renderNode(node) {
+    const n = node;
+    switch (n.kind) {
+      case "root":
+        return n.children.map((c) => this.renderNode(c)).join("");
+      case "symbol":
+        return _UnicodeRenderer.GREEK_MAP[n.value] ?? n.value;
+      case "frac":
+        return `(${this.renderNode(n.numerator)})/(${this.renderNode(n.denominator)})`;
+      case "script": {
+        let result = this.renderNode(n.base);
+        if (n.sub) result += this.toSub(this.renderNode(n.sub));
+        if (n.super) result += this.toSuper(this.renderNode(n.super));
+        return result;
+      }
+      case "radical":
+        if (n.index) {
+          return `${this.toSuper(this.renderNode(n.index))}\u221A(${this.renderNode(n.radicand)})`;
+        }
+        return `\u221A(${this.renderNode(n.radicand)})`;
+      case "delimiter":
+        return n.left + this.renderNode(n.body) + n.right;
+      case "text":
+        return n.content;
+      case "space":
+        return " ";
+      case "accent":
+        return this.renderNode(n.base);
+      case "largeop":
+        return this.renderNode(n.body ?? { kind: "text", content: "" });
+      case "group":
+        return n.children.map((c) => this.renderNode(c)).join("");
+      case "chem-element": {
+        let result = n.symbol;
+        if (n.count && n.count > 1) result += this.toSub(String(n.count));
+        if (n.charge) result += this.toSuper(`${n.charge}${n.chargeSign ?? "+"}`);
+        return result;
+      }
+      case "chem-bond":
+        return this.renderNode(n.left) + "-" + this.renderNode(n.right);
+      case "chem-reaction":
+        return n.reactants.map((r) => this.renderNode(r)).join(" + ") + " \u2192 " + n.products.map((p) => this.renderNode(p)).join(" + ");
+      case "chem-group":
+        return n.atoms.map((a) => this.renderNode(a)).join("");
+      default:
+        return "";
+    }
+  }
+  toSuper(text) {
+    let r = "";
+    for (const ch of text) r += _UnicodeRenderer.SUPER_DIGITS[ch] ?? ch;
+    return r;
+  }
+  toSub(text) {
+    let r = "";
+    for (const ch of text) r += _UnicodeRenderer.SUB_DIGITS[ch] ?? ch;
+    return r;
+  }
+};
+
+// src/mathml-renderer.ts
+var MathMLRenderer = class {
+  id = "mathml";
+  outputFormat = "mathml";
+  render(root, options) {
+    const display = options?.displayMode ?? root.metadata?.displayMode ?? false;
+    const body = this.renderNode(root);
+    const mathml = display ? `<math xmlns="http://www.w3.org/1998/Math/MathML" display="block">${body}</math>` : `<math xmlns="http://www.w3.org/1998/Math/MathML">${body}</math>`;
+    return { value: mathml, format: "mathml" };
+  }
+  renderNode(node) {
+    const n = node;
+    switch (n.kind) {
+      case "root":
+        return n.children.length === 1 ? this.renderNode(n.children[0]) : `<mrow>${n.children.map((c) => this.renderNode(c)).join("")}</mrow>`;
+      case "symbol": {
+        const value = this.escapeXml(n.value);
+        const greek = {
+          "\\alpha": "\u03B1",
+          "\\beta": "\u03B2",
+          "\\gamma": "\u03B3",
+          "\\delta": "\u03B4",
+          "\\pi": "\u03C0",
+          "\\theta": "\u03B8",
+          "\\lambda": "\u03BB",
+          "\\mu": "\u03BC",
+          "\\sigma": "\u03C3",
+          "\\omega": "\u03C9",
+          "\\infty": "\u221E",
+          "\\partial": "\u2202"
+        };
+        if (greek[n.value]) {
+          return `<mi>${greek[n.value]}</mi>`;
+        }
+        if (/^\d+(\.\d+)?$/.test(value)) {
+          return `<mn>${value}</mn>`;
+        }
+        return `<mi>${value}</mi>`;
+      }
+      case "frac":
+        return `<mfrac><mrow>${this.renderNode(n.numerator)}</mrow><mrow>${this.renderNode(n.denominator)}</mrow></mfrac>`;
+      case "script": {
+        let result = this.renderNode(n.base);
+        if (n.sub) {
+          result = `<msub>${result}<mrow>${this.renderNode(n.sub)}</mrow></msub>`;
+        }
+        if (n.super) {
+          result = `<msup>${result}<mrow>${this.renderNode(n.super)}</mrow></msup>`;
+        }
+        if (n.sub && n.super) {
+          result = `<msubsup>${this.renderNode(n.base)}<mrow>${this.renderNode(n.sub)}</mrow><mrow>${this.renderNode(n.super)}</mrow></msubsup>`;
+        }
+        return result;
+      }
+      case "radical": {
+        if (n.index) {
+          return `<mroot><mrow>${this.renderNode(n.radicand)}</mrow><mrow>${this.renderNode(n.index)}</mrow></mroot>`;
+        }
+        return `<msqrt><mrow>${this.renderNode(n.radicand)}</mrow></msqrt>`;
+      }
+      case "delimiter":
+        return `<mfenced open="${this.escapeXml(n.left)}" close="${this.escapeXml(n.right)}">${this.renderNode(n.body)}</mfenced>`;
+      case "matrix": {
+        const rows = n.rows.map((row) => `<mtr>${row.map((cell) => `<mtd>${this.renderNode(cell)}</mtd>`).join("")}</mtr>`).join("");
+        return `<mtable>${rows}</mtable>`;
+      }
+      case "text":
+        return `<mtext>${this.escapeXml(n.content)}</mtext>`;
+      case "space":
+        return `<mspace width="${n.width}em"/>`;
+      case "accent": {
+        const accentMap = {
+          hat: "^",
+          tilde: "~",
+          bar: "\xAF",
+          dot: "\u02D9",
+          ddot: "\xA8",
+          vec: "\u2192"
+        };
+        return `<mover accent="true"><mrow>${this.renderNode(n.base)}</mrow><mo>${accentMap[n.accentType] ?? "^"}</mo></mover>`;
+      }
+      case "largeop": {
+        let result = `<mo>${n.opType}</mo>`;
+        if (n.body) {
+          result = `<mrow>${result}<mrow>${this.renderNode(n.body)}</mrow></mrow>`;
+        }
+        if (n.lower) {
+          result = `<munder>${result}<mrow>${this.renderNode(n.lower)}</mrow></munder>`;
+        }
+        if (n.upper) {
+          result = `<mover>${result}<mrow>${this.renderNode(n.upper)}</mrow></mover>`;
+        }
+        return result;
+      }
+      case "group":
+        return `<mrow>${n.children.map((c) => this.renderNode(c)).join("")}</mrow>`;
+      case "chem-element":
+        return `<mi mathvariant="normal">${this.escapeXml(n.symbol)}</mi>` + (n.count ? `<mn>${n.count}</mn>` : "");
+      default:
+        return "";
+    }
+  }
+  escapeXml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+  }
+};
+export {
+  KatexRenderer,
+  LatexReverseRenderer,
+  MathMLRenderer,
+  RendererRegistry,
+  UnicodeRenderer
+};

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@sciexpr/renderer",
+  "version": "0.1.0",
+  "description": "Scientific Expression Engine - Multi-format renderer (KaTeX, Unicode, MathML, LaTeX)",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "scientific",
+    "expression",
+    "renderer",
+    "katex",
+    "mathml",
+    "unicode"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "haoguodong09-svg",
+    "email": "haoguodong09@gmail.com"
+  },
+  "homepage": "https://github.com/haoguodong09-svg/scientific-expression-engine#readme",
+  "bugs": {
+    "url": "https://github.com/haoguodong09-svg/scientific-expression-engine/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/haoguodong09-svg/scientific-expression-engine",
+    "directory": "packages/renderer"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@sciexpr/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "katex": "^0.16.0"
+  },
+  "peerDependenciesMeta": {
+    "katex": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/katex": "^0.16.0",
+    "katex": "^0.16.47",
+    "rimraf": "^5.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "test": "vitest run"
+  }
+}