@drghaliasri/butex 4.1.0 → 4.3.0

package/README.md

@@ -61,7 +61,8 @@ Peer dependency: `mathjax` ^4.x (aligned with MathJax 4 components). If you use
 2. Load BuTeX’s IIFE bundle (`dist/index.global.js` exposes global `BuTeX`).
 3. In `MathJax.startup.ready`, call `BuTeX.registerBuTeX(MathJax)` before `MathJax.startup.defaultReady()`.
 4. Inject styles once: `BuTeX.injectBuTeXStyles()` (or embed `BuTeX.BUTEX_CHROME_CSS` yourself).
-5. Render math with `renderBuTeXMathIsland(tex, options?)` or mount into a host element via `mountBuTeXMathIsland(host, tex, options?)`. Pass `output: 'svg'` when the host loads `tex-svg.js`, or `output: 'chtml'` with `tex-chtml.js`. For raw Arabic TeX that did not come from the editor AST, pass `mirrorOperators: true` to wrap directional operators according to BuTeX's shared operator table. `ButexEditor` picks SVG vs CHTML automatically from the loaded MathJax bundle (`tex2svg` vs `tex2chtml`).
+5. When using **SVG** (`tex-svg.js`), call `BuTeX.registerBuTeXSvgTextWrapper(MathJax)` **after** `defaultReady()` so Takween/Diwani text, `\ad`, and Arabic atomic commands (`\arsin`, etc.) render in the preview with the correct fonts. CommonHTML (`tex-chtml.js`) uses the injected CSS classes instead.
+6. Render math with `renderBuTeXMathIsland(tex, options?)` or mount into a host element via `mountBuTeXMathIsland(host, tex, options?)`. Pass `output: 'svg'` when the host loads `tex-svg.js`, or `output: 'chtml'` with `tex-chtml.js`. For raw Arabic TeX that did not come from the editor AST, pass `mirrorOperators: true` to wrap directional operators according to BuTeX's shared operator table. `ButexEditor` picks SVG vs CHTML automatically from the loaded MathJax bundle (`tex2svg` vs `tex2chtml`).
 
 Ensure TeX `packages` includes `butex-arabic-math` (use `BUTEX_TEX_PACKAGE` in config when using `{ '[+]': [...] }`).
 
@@ -127,7 +128,7 @@ Use this when you want the same editor UX as the demo:
 - Optionally pass `buttonElements` (undo/redo/copy/cut/split toggle) for auto button state refresh.
 - Wire your toolbar/actions to runtime methods (`toggleSide`, `insertDelimiterByKind`, `addSup`, `addSub`, `removeSup`, `removeSub`, `deleteStructure`, `performUndo`, `performRedo`, `performCopy`, `performCut`, `performPaste`).
 - Use `onSessionChange(session)` to render external previews (e.g., MathJax pane, status labels).
-- **Imported `MathObject` / `CharObject` for the editor:** document LaTeX preview treats `CharObject.expr` as already-rendered Arabic TeX (e.g. `\text{م}`). When opening an imported equation in `<ButexEditor />` via `mathObjectToEditorSession`, BuTeX unwraps supported LaTeX text/font wrappers into plain glyph `expr` plus editor `characterFont`. Supported patterns: `\text{…}`, `\takween{…}`, `\diwani{…}`, `\butextakween{…}`, `\butexdiwani{…}`, `\butexdiwanioutline{…}`, and nested forms such as `\text{\takween{…}}`. BuTeX’s own save path already stores plain glyphs; upstream converters may emit wrapped `expr` and do not need to change for document render.
+- **Imported `MathObject` / `CharObject` for the editor:** document LaTeX preview treats `CharObject.expr` as already-rendered Arabic TeX (e.g. `\text{م}`). When opening an imported equation in `<ButexEditor />` via `mathObjectToEditorSession`, BuTeX unwraps supported LaTeX text/font wrappers into plain glyph `expr` plus editor `characterFont`. Supported patterns: `\text{…}`, `\takween{…}`, `\diwani{…}`, `\butextakween{…}`, `\butexdiwani{…}`, `\butexdiwanioutline{…}`, and nested forms such as `\text{\takween{…}}`. On save, default-font chars stay plain `CharObject` nodes; non-default fonts are stored as font `CommandObject` wrappers so editor round-trip preserves `characterFont`. Upstream converters may still emit wrapped `expr` on import.
 
 Minimal browser example:
 
@@ -230,6 +231,60 @@ const preview = document2Preview(documentNode, 'svg');
 
 V2 exports Arabic TeX by default for equations saved from the embedded editor. Imported raw-only math is preserved as raw source and marked non-editable until a structured equation object is attached.
 
+### Document JSON contract (`value` + `math_objects`)
+
+Both document layers import the same shape. A text field holds `value` (the full string, **with math delimiters kept in place**) and an optional parallel `math_objects` array that supplies the structured equation AST for each math span found in that string.
+
+Rules:
+
+- **Detect, then align.** The importer scans `value` for delimiters (`$…$`, `\(…\)`, `\[…\]`, `$$…$$`, and math environments) and binds each detected span to `math_objects` **in reading order (left-to-right)**.
+- **Count and order must match.** Extra or missing entries produce a diagnostic; the browser never silently remaps. `math_mode`/`closing` on each `MathObject` must match the delimiter in `value`.
+- **Per field, not per document.** Each paragraph, heading, and list `item` carries its own `math_objects`.
+- **Tables are the exception:** one flat `math_objects` array lives on the `\begin{tabular}` block and is consumed **row-major** across all cells (each cell takes as many entries as it has spans).
+- **Missing `math_objects`** → the span renders as a non-editable raw math chip from its delimited source.
+- The browser **does not** parse equation LaTeX bodies into `ChainClass`; structured chains come from `math_objects` (import) or the equation editor (GUI).
+
+Paragraph with one inline span:
+
+```json
+{
+  "command": "\\paragraph",
+  "value": "لدينا $x^2$ ثابت.",
+  "math_objects": [
+    { "node_type": "MathObject", "math_mode": "$",
+      "lines": [{ "node_type": "ChainClass", "chain": [] }], "closing": "$" }
+  ]
+}
+```
+
+List item with a display span (`math_mode`/`closing` match the delimiter in `value`):
+
+```json
+{
+  "value": "الحل \\[a+b\\]",
+  "math_objects": [
+    { "node_type": "MathObject", "math_mode": "\\[",
+      "lines": [{ "node_type": "ChainClass", "chain": [] }], "closing": "\\]" }
+  ]
+}
+```
+
+Table: one flat array, consumed row-major (here `$x$`, then `$y$`):
+
+```json
+{
+  "command": "\\begin{tabular}",
+  "columns": "cc",
+  "rows": [["الرمز $x$", "القيمة"], ["الرمز $y$", "القيمة"]],
+  "math_objects": [
+    { "node_type": "MathObject", "math_mode": "$",
+      "lines": [{ "node_type": "ChainClass", "chain": [] }], "closing": "$" },
+    { "node_type": "MathObject", "math_mode": "$",
+      "lines": [{ "node_type": "ChainClass", "chain": [] }], "closing": "$" }
+  ]
+}
+```
+
 ### Document React widget v2 (`butex/react-document2`)
 
 Use this entry for the new document editor integration. It opens embedded `<ButexEditor />` sessions in Arabic/RTL mode by default and renders document preview math islands with MathJax **SVG** by default (`mathOutput` defaults to `'svg'`; pass `mathOutput="chtml"` only if the host loads `tex-chtml.js`).
@@ -253,7 +308,7 @@ export default function Page() {
 }
 ```
 
-Host apps still register BuTeX with MathJax before preview rendering. `uiLocale` selects Arabic (`"ar"`, the default) or English (`"en"`) document-editor chrome and is passed to the embedded equation editor. `documentDirection` independently controls prose inputs and preview flow without creating a second document tree. `equationSide` independently controls whether structured equations open, render, and save from the `"english"` or `"arabic"` side. Set `editableEquations={false}` to show math islands without equation insertion, deletion, or editor access. Raw-only equations keep their original source because the browser does not parse raw LaTeX into equation ASTs. Document editor v2 defaults to **`tex-svg.js`**; use `tex-chtml.js` only if you pass `mathOutput="chtml"`.
+Host apps still register BuTeX with MathJax before preview rendering. `uiLocale` selects Arabic (`"ar"`, the default) or English (`"en"`) document-editor chrome and is passed to the embedded equation editor. `documentDirection` independently controls prose inputs and preview flow without creating a second document tree. `equationSide` independently controls whether structured equations open, render, and save from the `"english"` or `"arabic"` side. Set `editableEquations={false}` to show math islands without equation insertion, deletion, or editor access. Set `previewOnly={true}` to render only the read-only document preview with no toolbar, editor panel, or equation drawer. Raw-only equations keep their original source because the browser does not parse raw LaTeX into equation ASTs. Document editor v2 defaults to **`tex-svg.js`**; use `tex-chtml.js` only if you pass `mathOutput="chtml"`.
 
 ### Styling/theming contract
 
@@ -274,7 +329,7 @@ Open:
 
 - `http://localhost:4173/demo/` (MathJax + `\arabsqrt`)
 - `http://localhost:4173/demo/parser.html` (parser-only normalize preview)
-- **Equation editor (React):** run `cd demo/editor-app && npm install && npm run dev`, then open the URL Vite prints (see `demo/editor.html` for a short pointer).
+- **Equation editor (React):** run `cd demo/editor-app && npm install && npm run dev`, then open the URL Vite prints (see `demo/editor.html` for a short pointer). The equation editor demo loads MathJax SVG from `public/vendor/`, matching document editor v2.
 - **Document editor (React):** run `cd demo/document-editor-app && npm install && npm run dev`, then open the URL Vite prints (see `demo/document.html` for a short pointer).
 - **Document editor v2 (React):** run `cd demo/document-editor-app2 && npm install && npm run dev`, then open the URL Vite prints. The v2 demo loads MathJax SVG and includes grouped insert controls (sections, lists, tables, figures, equations), per-block delete, list item controls, and editor/preview toggles. Optional bottom dev panels (LaTeX + AST) appear only if you append `?debug=1` to the URL or pass the `debug` prop from your host app.
 

package/dist/document.js

@@ -1020,6 +1020,16 @@ var ATOMIC_COMMANDS = {
     arabicLabel: "\u0645\u062D\u062F\u062F",
     title: "\u0645\u062D\u062F\u062F"
   },
+  ////////////////////// Derivatives ////////////////////////////////
+  ad: {
+    id: "ad",
+    category: "derivative",
+    englishTex: "\\mathrm{d}",
+    englishLabel: "d",
+    arabicTex: "\\ad",
+    arabicLabel: "\u0621",
+    title: "\u0639\u0644\u0627\u0645\u0629 \u0627\u0644\u0627\u0634\u062A\u0642\u0627\u0642"
+  },
   ////////////////////// Groups /////////////////////////////////
   N: {
     id: "N",
@@ -1611,6 +1621,16 @@ function atomicOperatorCommandSpec(id) {
   return Object.prototype.hasOwnProperty.call(ATOMIC_OPERATOR_COMMANDS, id) ? ATOMIC_OPERATOR_COMMANDS[id] : null;
 }
 
+// src/editor/divideOperator.ts
+var DIVIDE_OPERATOR_EN = "/";
+var DIVIDE_OPERATOR_AR = "\\";
+function isDivideOperatorExpr(expr) {
+  return expr === DIVIDE_OPERATOR_EN || expr === DIVIDE_OPERATOR_AR;
+}
+function renderDivideOperatorLatex(side) {
+  return side === "arabic" ? "\\backslash" : DIVIDE_OPERATOR_EN;
+}
+
 // src/editor/digits.ts
 var WESTERN = "0123456789";
 var ARABIC_INDIC = "\u0660\u0661\u0662\u0663\u0664\u0665\u0666\u0667\u0668\u0669";
@@ -1733,6 +1753,9 @@ function renderNodeArabic(node, options) {
     const content = renderCharContent(node, options);
     return arabicScripts(node, (node.characterFont ?? "default") === "default" ? `\\text{${escapeText(expr)}}` : content, options);
   }
+  if (node.kind === "operator" && isDivideOperatorExpr(node.expr)) {
+    return arabicScripts(node, renderDivideOperatorLatex("arabic"), options);
+  }
   return arabicScripts(node, formatDigits(node.expr, selectedDigitForm(options)), options);
 }
 function renderChainArabic(chain, options) {
@@ -2304,6 +2327,19 @@ ${ATOMIC_OPERATOR_COMMAND_CSS}
 `.trim();
 
 // src/document/mathEditorAdapter.ts
+var CHAR_FONT_EXPORT_TEX = {
+  takween: "\\butextakween",
+  diwani: "\\butexdiwani",
+  diwaniOutline: "\\butexdiwanioutline"
+};
+function charEditorNodeToAstNode(node) {
+  const font = node.characterFont ?? "default";
+  const charNode = new CharNode(node.expr);
+  if (font === "default") {
+    return charNode;
+  }
+  return new CommandNode(CHAR_FONT_EXPORT_TEX[font], [], [new ChainNode([charNode])]);
+}
 function attachAstScripts(editorNode, astNode) {
   if (editorNode.superscript) {
     const sup = editorChainToAstChain(editorNode.superscript);
@@ -2359,7 +2395,7 @@ function editorEnvToAstNode(node) {
 function editorNodeToAstNode(node) {
   let astNode;
   if (node.kind === "char") {
-    astNode = new CharNode(node.expr);
+    astNode = charEditorNodeToAstNode(node);
   } else if (node.kind === "number") {
     astNode = new NumberNode(node.expr);
   } else if (node.kind === "operator") {