smartrte-core 1.0.0-beta.1 → 1.0.0-beta.2

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.0.0-beta.2
+
+- Add an opt-in `renderFormulaHtml` option to `serializeCanonicalListHtml` that bakes real KaTeX-rendered HTML into exported formula elements, instead of leaving an empty placeholder — for consumers (e.g. a read-only preview) that display this HTML directly without also running KaTeX against it themselves. Off by default; no change for existing consumers.
+
 ## 1.0.0-beta.1
 
 **BREAKING CHANGE.** This is the first release built on the canonical, schema-driven document model. Every published version through 0.2.1 was built on the older discriminated-union model; none of the work below has shipped before.

package/dist/foundation/atom/formats.d.ts

@@ -1,5 +1,8 @@
+import "katex/contrib/mhchem";
 import type { SmartElementNode } from "../types.js";
-export declare const atomToHtml: (node: SmartElementNode) => string;
+export declare const atomToHtml: (node: SmartElementNode, options?: {
+    renderFormulaHtml?: boolean;
+}) => string;
 export declare const atomFromHtmlElement: (element: Element) => SmartElementNode | null;
 export declare const atomToMarkdown: (node: SmartElementNode) => string;
 export interface AtomDocxRun {

package/dist/foundation/atom/formats.js

@@ -1,16 +1,44 @@
+import katex from "katex";
+// Registers \ce{...} chemistry-equation notation on the shared katex module
+// instance, matching surface/renderer.ts's own live-render import - a
+// formula baked here via renderFormulaHtml must support the exact same
+// notation the live editor does, or a chemistry entry would render live but
+// fall back to plain text in the exported/baked HTML.
+import "katex/contrib/mhchem";
 import { createNodeId } from "../identity.js";
 import { sanitizeAtomSource } from "./security.js";
 const escape = (value) => String(value ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 const attr = (name, value) => value === undefined ? "" : ` ${name}="${escape(value)}"`;
 const dimensions = (node) => `${attr("width", node.attrs?.width)}${attr("height", node.attrs?.height)}`;
-export const atomToHtml = (node) => {
+// Mirrors surface/renderer.ts's KATEX_OPTIONS and try/catch-to-plain-text
+// fallback exactly - a formula that fails to render live must fail the same
+// way when baked into exported HTML, not throw and abort the whole export.
+const KATEX_OPTIONS = { trust: false, strict: "error" };
+const renderFormulaToHtml = (source) => {
+    try {
+        return katex.renderToString(source, KATEX_OPTIONS);
+    }
+    catch {
+        return escape(source);
+    }
+};
+export const atomToHtml = (node, options) => {
     if (node.type === "image" || node.type === "block_image") {
         const src = sanitizeAtomSource(String(node.attrs?.src || ""), { kind: "image", allowBlobPreview: node.attrs?.status === "pending" }) || "";
         return `<img data-smart-id="${escape(node.id)}" data-smart-type="${node.type}" src="${escape(src)}" alt="${escape(node.attrs?.alt)}"${dimensions(node)}${attr("data-smart-status", node.attrs?.status || "ready")}${node.attrs?.decorative === true ? ' data-smart-decorative="true"' : ""}${attr("data-smart-align", node.attrs?.align)}>`;
     }
     if (node.type === "formula" || node.type === "block_formula") {
         const tag = node.type === "formula" ? "span" : "div";
-        return `<${tag} data-smart-id="${escape(node.id)}" data-smart-type="${node.type}" data-smart-notation="${escape(node.attrs?.notation || "latex")}" data-smart-formula="${escape(node.attrs?.source)}" role="math" aria-label="${escape(`Mathematical formula: ${String(node.attrs?.source || "")}`)}"></${tag}>`;
+        const source = String(node.attrs?.source || "");
+        // The rendered KaTeX HTML is purely a self-contained visual convenience
+        // for consumers that display this HTML string directly without also
+        // running katex.render() against it themselves (docs/bugs/
+        // formula-not-rendered-in-static-html-consumers.md) - data-smart-formula
+        // stays the single source of truth for round-tripping back into the
+        // model (list/formats.ts's parser reads the attribute, never this
+        // inner content), so baking this in can never desync source vs. render.
+        const inner = options?.renderFormulaHtml ? renderFormulaToHtml(source) : "";
+        return `<${tag} data-smart-id="${escape(node.id)}" data-smart-type="${node.type}" data-smart-notation="${escape(node.attrs?.notation || "latex")}" data-smart-formula="${escape(source)}" role="math" aria-label="${escape(`Mathematical formula: ${source}`)}">${inner}</${tag}>`;
     }
     if (node.type === "video" || node.type === "audio") {
         const src = sanitizeAtomSource(String(node.attrs?.src || ""), { kind: node.type }) || "";

package/dist/foundation/list/formats.d.ts

@@ -2,6 +2,7 @@ import type { SmartDocument } from "../types.js";
 export declare const serializeCanonicalListHtml: (document: SmartDocument, options?: {
     clean?: boolean;
     fragment?: boolean;
+    renderFormulaHtml?: boolean;
 }) => string;
 export declare const parseCanonicalListHtml: (html: string) => SmartDocument;
 /** Alignment and indent are unsupported in Markdown; block content survives semantically. */

package/dist/foundation/list/formats.js

@@ -20,12 +20,14 @@ const isEditorUiNode = (node) => attr(node, "data-smart-ui") !== undefined || at
  * parseBlockList below for how they're unwrapped instead of swallowed.
  */
 const TRANSPARENT_CONTAINER_TAGS = ["div", "section", "article", "figure"];
+/** See serializeCanonicalListHtml's own doc comment for why this is a module-scoped flag rather than a threaded parameter. */
+let renderFormulaHtmlMode = false;
 const serializeInline = (node) => {
     if (!isTextNode(node)) {
         if (node.type === "hard_break")
             return `<br data-smart-id="${escapeHtml(node.id)}" data-smart-type="hard_break">`;
         if (["image", "formula"].includes(node.type))
-            return atomToHtml(node);
+            return atomToHtml(node, { renderFormulaHtml: renderFormulaHtmlMode });
         const raw = node.attrs?.raw;
         if (typeof raw?.html === "string")
             return raw.html;
@@ -91,7 +93,7 @@ const serializeBlock = (node, includeIds, listDepth = 0, tableCellA11y) => {
     }
     const id = includeIds ? ` data-smart-id="${escapeHtml(node.id)}"` : "";
     if (["block_image", "block_formula", "video", "audio", "divider"].includes(node.type))
-        return atomToHtml(node);
+        return atomToHtml(node, { renderFormulaHtml: renderFormulaHtmlMode });
     if (node.type === "paragraph" || node.type === "heading") {
         const tag = node.type === "heading" ? `h${String(node.attrs?.level || 1)}` : "p";
         return `<${tag}${id}${blockAttributes(node)}>${(node.children || []).map(serializeInline).join("")}</${tag}>`;
@@ -179,12 +181,28 @@ const serializeBlock = (node, includeIds, listDepth = 0, tableCellA11y) => {
     }
     return `<div${id}>${(node.children || []).map((child) => isTextNode(child) ? serializeInline(child) : serializeBlock(child, includeIds)).join("")}</div>`;
 };
-export const serializeCanonicalListHtml = (document, options = {}) => options.clean === true
-    ? document.children.map((node) => isTextNode(node) ? serializeInline(node) : serializeBlock(node, false)).join("")
-        .replace(/\sdata-smart-id=(?:"[^"]*"|'[^']*')/g, "")
-    : options.fragment === true
-        ? document.children.map((node) => isTextNode(node) ? serializeInline(node) : serializeBlock(node, true)).join("")
-        : `<div data-smart-document="true" data-smart-id="${escapeHtml(document.id)}">${document.children.map((node) => isTextNode(node) ? serializeInline(node) : serializeBlock(node, true)).join("")}</div>`;
+export const serializeCanonicalListHtml = (document, options = {}) => {
+    // A module-scoped flag, not a threaded parameter: serializeInline/
+    // serializeBlock recurse through dozens of call sites (lists, tables,
+    // blockquotes) - threading a new parameter through every one of them is
+    // exactly the kind of change that's easy to miss at one nested call site
+    // and silently break there. Safe here because serialization is
+    // synchronous, single-threaded, non-reentrant tree recursion - the flag
+    // is always restored in `finally` before this function ever returns.
+    const previous = renderFormulaHtmlMode;
+    renderFormulaHtmlMode = options.renderFormulaHtml === true;
+    try {
+        return options.clean === true
+            ? document.children.map((node) => isTextNode(node) ? serializeInline(node) : serializeBlock(node, false)).join("")
+                .replace(/\sdata-smart-id=(?:"[^"]*"|'[^']*')/g, "")
+            : options.fragment === true
+                ? document.children.map((node) => isTextNode(node) ? serializeInline(node) : serializeBlock(node, true)).join("")
+                : `<div data-smart-document="true" data-smart-id="${escapeHtml(document.id)}">${document.children.map((node) => isTextNode(node) ? serializeInline(node) : serializeBlock(node, true)).join("")}</div>`;
+    }
+    finally {
+        renderFormulaHtmlMode = previous;
+    }
+};
 const textWithMarks = (node, inherited = []) => {
     if (isEditorUiNode(node))
         return [];

package/dist/foundation/table/formats.d.ts

@@ -3,6 +3,7 @@ export declare const parseCanonicalTableHtml: (html: string) => SmartDocument;
 export declare const serializeCanonicalTableHtml: (document: SmartDocument, options?: {
     clean?: boolean;
     fragment?: boolean;
+    renderFormulaHtml?: boolean;
 }) => string;
 /** GFM is intentionally lossy: anchor content survives and covered coordinates are emitted empty. */
 export declare const serializeCanonicalTableMarkdown: (document: SmartDocument) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smartrte-core",
-  "version": "1.0.0-beta.1",
+  "version": "1.0.0-beta.2",
   "description": "Framework-agnostic document model and editing primitives for Smart RTE",
   "repository": {
     "type": "git",