@drghaliasri/butex 3.2.2

package/README.md

@@ -0,0 +1,311 @@
+# BuTeX
+
+**Integrators:** treat [**Integration contract (host apps)**](#integration-contract-host-apps) as the source of truth for wiring MathJax and BuTeX. The **npm package** ships `dist/` and this `README.md` only; design notes and ADRs live in the GitHub repo under `docs/` (they are not included in the published tarball).
+
+BuTeX is a browser-side foundation for Arabic mathematical typography and equation editing on top of [MathJax](https://www.mathjax.org/). It ships thin MathJax extensions such as `\arabsqrt` (Arabic-style mirrored radical; CommonHTML uses CSS mirror/unmirror, SVG uses the MathJax SVG pipeline plus BuTeX SVG helpers where applicable), optional GUI/document layers, and helpers such as `parseBuTeX`. The longer-term direction is a GUI editor driven by structured equation ASTs.
+
+The vendored **[MathJax-src/](MathJax-src/)** folder in this repo is **reference only** — runtime integration uses the **`mathjax`** npm package.
+
+## Project direction
+
+The intended editor model is **AST-first**:
+
+- A GUI edits equation nodes rather than raw LaTeX strings.
+- BuTeX will maintain local TypeScript ASTs for English and Arabic equation structures so users can switch views.
+- A remote service may send equations as JSON compatible with the local ASTs; the browser imports that JSON and renders/edit it locally.
+- Arabic/English TeX strings are generated from the AST for MathJax rendering. Remote-rendered strings can be useful for testing/debugging, but should not be the editor state.
+- The Python files in **[references/](references/)** are reference material for the emerging JSON shape and conversion behavior.
+
+## Rendering outputs and MVP scope
+
+- **CommonHTML (`chtml`)** and **SVG** are supported. Load the matching MathJax 4 bundle (`tex-chtml.js` vs `tex-svg.js`) and pass the same mode as `output` to `renderBuTeXMathIsland` / `mountBuTeXMathIsland`. `<ButexEditor />` and document math preview follow the loaded bundle when possible (`tex2chtml` vs `tex2svg`).
+- `\arabsqrt`: optional index + mandatory radicand (same argument shape as `\sqrt`).
+- Compatibility macros: `\arsqrt` aliases `\arabsqrt`; `\unit{...}` and `\idx{...}` are browser-side passthrough wrappers for imported/reference TeX.
+- **Arabic surface parser** (`parseBuTeX`) — optional helper that maps a tiny subset of Arabic command names to MathJax-safe TeX before rendering (see below). Long-term editor state is structured AST/JSON, not this string transform alone.
+
+## Arabic preprocessor (`parseBuTeX`)
+
+Convert Arabic-friendly math surface syntax to plain MathJax TeX:
+
+
+| Input               | Output                           |
+| ------------------- | -------------------------------- |
+| `\جذر[3]{س}`        | `\arabsqrt[3]{\text{س}}`         |
+| `\كسر{1}{2}`        | `\frac{1}{2}`                    |
+| `\كسر{\جذر{س}}{10}` | `\frac{\arabsqrt{\text{س}}}{10}` |
+| `\جتا`              | `\arcos`                         |
+
+
+Pure string transform — call `parseBuTeX(tex)`, pass the result to MathJax.
+
+```ts
+import { parseBuTeX } from 'butex';
+
+const mjTex = parseBuTeX(String.raw`\جذر[3]{س}`);
+// await renderBuTeXMathIsland(mjTex, { display: true, output: 'chtml' }) ...
+```
+
+Run tests with `npm test`. Live parser demo: `demo/parser.html` (after `npm run build`; serve the repo root).
+
+## Install
+
+```bash
+npm install butex mathjax
+```
+
+Peer dependency: `mathjax` ^4.x (aligned with MathJax 4 components). If you use **`butex/react`**, also install **`react`** and **`react-dom`** (^18 or ^19).
+
+## Usage (browser)
+
+1. Load MathJax (e.g. `tex-chtml.js` or `tex-svg.js`) **after** setting `window.MathJax` config.
+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`).
+
+Ensure TeX `packages` includes `butex-arabic-math` (use `BUTEX_TEX_PACKAGE` in config when using `{ '[+]': [...] }`).
+
+## Usage (npm / bundler)
+
+### MathJax entrypoints (bundlers)
+
+Exact import strings depend on your bundler and how it resolves the `mathjax` package. Typical ESM imports for MathJax 4 components:
+
+| Desired output | Typical import |
+| -------------- | -------------- |
+| CommonHTML     | `import MathJax from 'mathjax/tex-chtml.js'` |
+| SVG            | `import MathJax from 'mathjax/tex-svg.js'`   |
+
+Use the same mode in `renderBuTeXMathIsland` / `mountBuTeXMathIsland` via `output: 'chtml'` or `output: 'svg'`. If resolution fails, point your import at whatever path your build resolves to the same component bundle (see MathJax’s docs for your version).
+
+```ts
+import MathJax from 'mathjax/tex-chtml.js'; // or tex-svg.js — match `output` in render calls
+import {
+  registerBuTeX,
+  injectBuTeXStyles,
+  renderBuTeXMathIsland,
+  BUTEX_TEX_PACKAGE,
+} from 'butex';
+
+// Before startup resolves — same timing rules as browser:
+MathJax.startup.ready = () => {
+  registerBuTeX(MathJax);
+  injectBuTeXStyles();
+  MathJax.startup.defaultReady();
+};
+MathJax.config.tex = {
+  packages: { '[+]': ['ams', BUTEX_TEX_PACKAGE] },
+};
+```
+
+Maintainer-facing design notes live in the GitHub repo under `docs/` (not shipped on npm).
+
+## Integration contract (host apps)
+
+BuTeX supports two integration modes. Keep this contract for stable behavior.
+
+### 1) Render-only contract (MathJax + BuTeX macros)
+
+Use this when you only need to render LaTeX strings:
+
+- Register BuTeX with MathJax via `registerBuTeX(MathJax)`.
+- Include `butex-arabic-math` in TeX packages.
+- Inject BuTeX MathJax styles once via `injectBuTeXStyles(document)` (or embed `BUTEX_CHROME_CSS`).
+- Render expressions with `renderBuTeXMathIsland` / `mountBuTeXMathIsland` (set `output` to match the host bundle: `tex-svg.js` vs `tex-chtml.js`).
+- For raw Arabic TeX, set `mirrorOperators: true` or call `mirrorBuTeXOperatorsInTex(tex)` before non-island MathJax typesetting. Leave it off for editor-generated TeX because the editor already emits `\butexmirror{...}`.
+- For Arabic-friendly surface strings, optionally preprocess with `parseBuTeX(...)` before rendering.
+
+This mode does not require the GUI editor runtime.
+
+### 2) GUI editor contract (shippable editor UX)
+
+Use this when you want the same editor UX as the demo:
+
+- Inject editor styles once via `injectBuTeXEditorStyles(document)` (or embed `BUTEX_EDITOR_CSS`).
+- Create runtime with `Editor.createEditorRuntime({ ... })`.
+- Pass your editor surface element as `surfaceEl`.
+- 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).
+
+Minimal browser example:
+
+```ts
+BuTeX.injectBuTeXEditorStyles(document);
+const runtime = BuTeX.Editor.createEditorRuntime({
+  surfaceEl: document.getElementById('surface'),
+  onSessionChange: (session) => {
+    // host-render math preview/status here
+  },
+});
+```
+
+### React widget (`butex/react`)
+
+Shipped as a separate entry so apps that do not use React never pull it in.
+
+- Import: `import { ButexEditor } from 'butex/react'`.
+- Peer dependencies when using this entry: `react` and `react-dom` (^18 or ^19).
+- The component wraps `Editor.createEditorRuntime` (toolbar, surface, MathJax preview strip, optional dev panels via `debug`).
+- Load MathJax and register BuTeX **before** relying on the preview (same timing as the GUI contract above). Equation preview in `ButexEditor` uses the same `renderBuTeXMathIsland` path as document math islands (output follows the loaded bundle: SVG when `tex2svg` is available, otherwise CHTML). Optional legacy `mountBuTeXMathTypeset` (`typesetPromise`) remains exported for hosts that still rely on it.
+- Next.js App Router: put BuTeX in a **client component** (`'use client'`).
+
+```tsx
+'use client';
+
+import { ButexEditor } from 'butex/react';
+
+export default function Page() {
+  return <ButexEditor />;
+}
+```
+
+### Document AST (`butex/document`)
+
+Use this headless entry when a host app or remote service already has `DocumentObject` JSON and needs a structured import/export layer.
+
+```ts
+import {
+  fromDocumentJson,
+  createEmptyDocument,
+  renderDocumentLatex,
+  buildDocumentPreview,
+} from 'butex/document';
+
+const documentNode = fromDocumentJson({
+  node_type: 'DocumentObject',
+  blocks: [{ command: '\\section', value: 'Intro $x$' }],
+});
+
+const emptyDocument = createEmptyDocument();
+const latex = renderDocumentLatex(documentNode);
+const preview = buildDocumentPreview(documentNode);
+```
+
+V1 supports simple headings, paragraphs, `itemize` / `enumerate`, `tabular`, `includegraphics`, raw blocks, and math spans detected inside text. The document layer detects math delimiters and can align them with ordered imported `MathObject` JSON; it does not parse arbitrary equation LaTeX into chain nodes in the browser.
+
+### Document React widget (`butex/react-document`)
+
+Use this entry for the first document-editor UI. It edits supported document blocks, shows a live semantic preview, and opens the equation editor for supported imported math islands.
+
+```tsx
+'use client';
+
+import { ButexDocumentEditor } from 'butex/react-document';
+
+export default function Page() {
+  return (
+    <ButexDocumentEditor
+      debug
+      onLatexChange={(latex) => console.log(latex)}
+    />
+  );
+}
+```
+
+The preview is semantic HTML for document structure. Math is emitted as escaped per-span islands, so host apps still need the normal MathJax + BuTeX registration when they want typeset math preview rather than TeX placeholders.
+
+### Document AST v2 (`butex/document2`)
+
+Use this parallel v2 headless entry for the token-owned document model. Imported delimited math is converted into math tokens between prose tokens; normal editing should mutate text tokens and math tokens separately rather than treating raw delimited TeX as one textarea value.
+
+```ts
+import {
+  fromDocumentJson2,
+  document2Latex,
+  document2Preview,
+} from 'butex/document2';
+
+const documentNode = fromDocumentJson2({
+  node_type: 'DocumentObject',
+  blocks: [{ command: '\\paragraph', value: 'نص $x$' }],
+});
+
+const latex = document2Latex(documentNode);
+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 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`).
+
+```tsx
+'use client';
+
+import { ButexDocumentEditor2 } from 'butex/react-document2';
+
+export default function Page() {
+  return (
+    <ButexDocumentEditor2
+      debug
+      onLatexChange={(latex) => console.log(latex)}
+    />
+  );
+}
+```
+
+Host apps still register BuTeX with MathJax before preview rendering. Document editor v2 defaults to **`tex-svg.js`**; use `tex-chtml.js` only if you pass `mathOutput="chtml"`.
+
+### Styling/theming contract
+
+- Core editor classes (`.surface`, `.chain`, `.slot`, `.node`, `.scripts`, `.delim*`, etc.) are shipped from `src/editor/styles.ts`.
+- Theme with **one namespace**, `--butex-*`, on `.butex-widget` (or an ancestor of the editor surface). Defaults are set on `ButexEditor`’s root; hosts override accents, borders, **`--butex-surface-bg` / `--butex-surface-fg`**, **`--butex-preview-bg` / `--butex-preview-fg`**, focus/slot/selection, scripts, optional **`--butex-dev-*`** / **`--butex-dev-inset-*`** when using `debug`, etc., without redefining structure classes.
+- Document editor theming is scoped under `.butex-document-widget`. Override `--butex-document-*` variables on that root or an ancestor, especially `--butex-document-bg`, `--butex-document-fg`, `--butex-document-panel`, `--butex-document-border`, `--butex-document-accent`, `--butex-document-preview-bg`, `--butex-document-drawer-bg`, `--butex-document-input-bg`, `--butex-document-table-border`, `--butex-document-math-bg`, and `--butex-document-dev-bg`.
+- Document editor v2 theming is scoped under `.butex-document2-widget`. Override `--butex-document2-*` variables on that root or an ancestor; defaults inherit from the existing `--butex-*` variables where practical, including accent, panel, border, preview, focus, danger/error, and debug colors. The embedded equation editor opens as a centered modal (backdrop + panel); its BuTeX chrome reads the same `--butex-document2-*` tokens via a scoped bridge, so hosts normally theme once on `.butex-document2-widget` without a second equation theme. The built-in editor uses a **sticky compact icon toolbar** (heading glyphs, inline `$…$` vs display `\[…\]` math buttons with tooltips, table size popover), **focus-aware block insertion** after the active block, **↑/↓ block reorder**, **math delete** (chip × and drawer button), **document undo/redo** (toolbar + Ctrl/⌘Z, Ctrl/⌘Shift+Z, Ctrl+Y) via AST snapshots, and theme-tinted block cards. Preview tables use fixed black cell borders; raw `\raw` blocks stay out of preview until dedicated rendering exists.
+
+## Demo
+
+From repo root (after `npm run build`):
+
+```bash
+npm run demo
+```
+
+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).
+- **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.
+
+### Editor MVP notes (`demo/editor-app`)
+
+- Editing is AST-first (not raw LaTeX text editing).
+- End-user UI is Arabic-first.
+- Supported structures in this MVP: chars, numbers, operators, delimiter pairs `()`, `[]`, `{}`, fractions (`\frac`), and sup/sub chains.
+- Caret: **Left/Right** walk every insertion gap in a fixed depth-first order (baseline and nested chains). **Up/Down** move between superscript and subscript where applicable (from the baseline, Up prefers superscript and Down prefers subscript when both exist). On the Arabic surface, arrow keys follow RTL progression.
+- Char/number typing: by default keystrokes **merge into the same leaf** along the caret gap (digits only extend `number`, letters only extend `char`). Use the **Split leaf typing** toolbar control to toggle **split mode** (one new leaf per keystroke). **Delete/Backspace** trim inside the merged string when split mode is off.
+- Structural edits are mirrored across Arabic/English trees; text edits apply to the active side.
+- **Undo/redo:** full-session snapshots (`createUndoRedoStacks`, `pushUndoRedoSnapshot`, `restoreUndo`, `restoreRedo`). The demo exposes toolbar buttons plus **Ctrl+Z** / **⌘Z** for undo and **Ctrl+Shift+Z** / **⌘⇧Z** / **Ctrl+Y** for redo while the editing surface is focused. Caret moves and language switching are not recorded so undo targets content edits only. History caps at ~100 steps by default (`DEFAULT_UNDO_HISTORY_MAX_DEPTH`).
+- **Selection + copy/cut/paste:** range selection lives at the slot level inside a single chain (no cross-chain selection in the MVP). Whole nodes are the copy unit, so superscripts/subscripts/inner subtrees always travel with their owner.
+  - **Keyboard:** **Shift+ArrowLeft/ArrowRight** extend selection (RTL-aware), **Ctrl/⌘+C/X/V** copy/cut/paste, **Backspace/Delete** and typing **replace** an active selection.
+  - **Mouse:** click-drag from one slot to another inside the same chain. Cross-chain mouse moves are ignored.
+  - **Clipboard format:** `application/x-butex-fragment+json` with both EN and AR mirrored nodes (`EditorFragment` v1) plus a **plain-text LaTeX fallback** for cross-app pasting. External plain text re-enters through the typing path so split/merge mode applies.
+  - **Future node types:** the single helper `nodeChildChains(node)` enumerates a node's nested chains. Adding command, env, or math-object kinds (see `[references/nodes.py](references/nodes.py)`) only requires extending this helper; selection, copy, paste, and id-remap stay unchanged.
+- Debug panels are dev-only (`debug` prop on `<ButexEditor />`, or `?debug=1` in the Vite demo URL).
+  - Includes LaTeX dump, passive chain preview, and copyable command/render log.
+
+### Editor theming (CSS variables)
+
+Override these on `:root` (or a host container) to customize colors:
+
+- `--butex-bg`
+- `--butex-fg`
+- `--butex-muted`
+- `--butex-accent`
+- `--butex-border`
+- `--butex-panel`
+- `--butex-caret`
+- `--butex-selected`
+- `--butex-error`
+- `--butex-error-bg`
+- `--butex-accent-hover` (optional, demo toolbar)
+- `--butex-shadow-sm` / `--butex-shadow-md` (optional, panels)
+- `--butex-dev-bg` / `--butex-dev-border` / `--butex-dev-badge` / `--butex-dev-muted` (optional, developer-only strips when `debug` is on)
+
+## License
+
+ISC (BuTeX package). MathJax is Apache-2.0 — see upstream.

package/dist/document.d.mts

@@ -0,0 +1,307 @@
+type ArabicNodeJson = {
+    node_type: string;
+    expr?: string;
+    name?: string;
+    superscript?: ChainJson | null;
+    subscript?: ChainJson | null;
+    left_delim_expr?: string;
+    right_delim_expr?: string;
+    inner_expr?: ChainJson;
+    optional_args?: ChainJson[];
+    mandatory_args?: ChainJson[];
+    opening?: string;
+    closing?: string;
+    lines?: ChainJson[];
+};
+type ChainJson = {
+    node_type: 'ChainClass';
+    chain: ArabicNodeJson[];
+};
+declare class State {
+}
+declare class BaseAstNode {
+    state: State;
+    superscript: ChainNode | null;
+    subscript: ChainNode | null;
+    nodeType: string;
+    constructor(state?: State | null);
+    latex(): string;
+    arabicLatex(): string;
+    toArabicLatex(): string;
+    /** Latin-style scripts: `^{...}` and `_{...}` for english_json rendering. */
+    latexScripts(): string;
+    /**
+     * Arabic scripts use \\prescript{sup}{sub}{content} (matches reference Python output).
+     * Call with rendered strings for sup/sub chains (may be empty strings).
+     */
+    arabicLatexScripts(sup: string, sub: string, content: string): string;
+}
+declare class ChainNode {
+    chain: BaseAstNode[];
+    constructor(chain?: BaseAstNode[]);
+    latex(): string;
+    toEnglishLatex(): string;
+    /** RTL: reverse order relative to Latin chain (see test/ref_tests.txt). */
+    arabicLatex(): string;
+    toArabicLatex(): string;
+}
+
+type DocumentParseMode = 'english' | 'arabic';
+type MathObjectJson = {
+    node_type: 'MathObject';
+    math_mode: string;
+    lines: ChainJson[];
+    closing: string;
+};
+type DocumentJson = {
+    node_type: 'DocumentObject';
+    blocks: DocumentBlockJson[];
+};
+type DocumentBlockJson = {
+    command: string;
+    value?: string;
+    math_objects?: MathObjectJson[];
+    options?: Record<string, string>;
+    closing?: string;
+    items?: DocumentListItemJson[];
+    rows?: string[][];
+    columns?: string;
+};
+type DocumentListItemJson = {
+    value: string;
+    math_objects?: MathObjectJson[];
+    blocks?: DocumentBlockJson[];
+};
+type DocumentCommand = '\\section' | '\\subsection' | '\\subsubsection' | '\\paragraph' | '\\begin{itemize}' | '\\begin{enumerate}' | '\\begin{tabular}' | '\\includegraphics' | '\\raw';
+type MathNode = {
+    nodeType: 'MathObject';
+    mathMode: string;
+    lines: ChainNode[];
+    closing: string;
+};
+type TextInline = {
+    kind: 'text';
+    text: string;
+};
+type MathInline = {
+    kind: 'math';
+    source: string;
+    math: MathNode | null;
+};
+type DocumentInline = TextInline | MathInline;
+type TextBlockNode = {
+    kind: 'textBlock';
+    command: '\\section' | '\\subsection' | '\\subsubsection' | '\\paragraph';
+    value: string;
+    inlines: DocumentInline[];
+};
+type ListItemNode = {
+    value: string;
+    inlines: DocumentInline[];
+    blocks: DocumentBlockNode[];
+};
+type ListBlockNode = {
+    kind: 'list';
+    command: '\\begin{itemize}' | '\\begin{enumerate}';
+    closing: '\\end{itemize}' | '\\end{enumerate}';
+    items: ListItemNode[];
+};
+type TableBlockNode = {
+    kind: 'table';
+    command: '\\begin{tabular}';
+    closing: '\\end{tabular}';
+    columns: string;
+    rows: DocumentInline[][][];
+};
+type ImageBlockNode = {
+    kind: 'image';
+    command: '\\includegraphics';
+    value: string;
+    options: Record<string, string>;
+};
+type RawBlockNode = {
+    kind: 'raw';
+    command: '\\raw';
+    value: string;
+};
+type DocumentBlockNode = TextBlockNode | ListBlockNode | TableBlockNode | ImageBlockNode | RawBlockNode;
+type DocumentNode = {
+    nodeType: 'DocumentObject';
+    blocks: DocumentBlockNode[];
+};
+type DetectedMathSpan = {
+    start: number;
+    end: number;
+    source: string;
+    mathMode: string;
+    closing: string;
+};
+type DocumentPreviewMathIsland = {
+    id: string;
+    tex: string;
+    display: boolean;
+};
+type DocumentPreview = {
+    html: string;
+    mathIslands: DocumentPreviewMathIsland[];
+};
+
+declare function fromDocumentJson(json: unknown, mode?: DocumentParseMode): DocumentNode;
+declare function createEmptyDocument(): DocumentNode;
+declare function createTextBlock(command: TextBlockNode['command'], value?: string): TextBlockNode;
+declare function createRawBlock(value?: string): RawBlockNode;
+declare function createListBlock(command: ListBlockNode['command'], items?: string[]): ListBlockNode;
+declare function createTableBlock(rows?: string[][], columns?: string): TableBlockNode;
+declare function createImageBlock(value?: string, options?: Record<string, string>): ImageBlockNode;
+declare function isSupportedDocumentCommand(command: string): command is DocumentCommand;
+
+declare function fromMathObjectJson(json: unknown, mode?: DocumentParseMode): MathNode;
+declare function renderMathNodeLatex(math: MathNode): string;
+declare function isDisplayMathNode(math: MathNode): boolean;
+
+type EditorSide = 'english' | 'arabic';
+type EditorNodeKind = 'char' | 'number' | 'operator' | 'delimiter' | 'frac' | 'sqrt' | 'env' | 'atomicCommand' | 'atomicOperatorCommand';
+type MatrixEnvStyle = 'matrix' | 'pmatrix' | 'bmatrix' | 'Bmatrix' | 'vmatrix' | 'Vmatrix';
+type GridEnvName = MatrixEnvStyle | 'array' | 'aligned';
+type EnvColumnAlignment = 'l' | 'c' | 'r';
+type CharacterFontId = 'default' | 'takween' | 'diwani' | 'diwaniOutline';
+type DigitFormId = 'western' | 'arabicIndic' | 'persianIndic';
+type EditorSyncState = 'synced' | 'diverged';
+type EditorChain = {
+    id: string;
+    nodes: EditorNode[];
+};
+type EditorNode = {
+    id: string;
+    kind: EditorNodeKind;
+    expr: string;
+    characterFont?: CharacterFontId;
+    superscript: EditorChain | null;
+    subscript: EditorChain | null;
+    leftDelimExpr: string;
+    rightDelimExpr: string;
+    innerExpr: EditorChain | null;
+    numerator: EditorChain | null;
+    denominator: EditorChain | null;
+    radicand: EditorChain | null;
+    rootIndex: EditorChain | null;
+    envName: GridEnvName | null;
+    matrixStyle: MatrixEnvStyle | null;
+    matrixRows: EditorChain[][] | null;
+    columnAlignments: EnvColumnAlignment[] | null;
+};
+type EditorCaret = {
+    chainId: string;
+    index: number;
+};
+type EditorSelectionRange = {
+    chainId: string;
+    anchorIndex: number;
+    focusIndex: number;
+};
+type EditorSyncMap = Record<string, {
+    expr: EditorSyncState;
+}>;
+type EditorDebugEntry = {
+    timestamp: string;
+    command: string;
+    activeSide: EditorSide;
+    englishLatex: string;
+    arabicLatex: string;
+    renderOk: boolean;
+    renderError: string | null;
+    note: string;
+};
+type EditorSession = {
+    englishTree: EditorChain;
+    arabicTree: EditorChain;
+    activeSide: EditorSide;
+    /** When true, each typed letter/digit inserts a new char/number leaf; when false, merge into adjacent same-kind leaves. */
+    splitLeafTyping: boolean;
+    /** One-shot: when true, the next insertChar/insertNumber bypasses leaf-merge (used by Space in merge mode). */
+    forceSplitNextLeaf: boolean;
+    /** When true and active side is Arabic, merged number typing prepends digits (RTL-style); still mirrored on EN/AR. */
+    arabicReverseNumberTyping: boolean;
+    /** Font applied to newly typed char nodes. */
+    currentCharacterFont: CharacterFontId;
+    /** Digit glyph form used for editor display and LaTeX preview output. */
+    currentDigitForm: DigitFormId;
+    caret: EditorCaret;
+    /** Whole-node range selection inside a single chain (anchor==focus means no selection). */
+    selection: EditorSelectionRange | null;
+    selectedNodeId: string | null;
+    selectedStructureNodeId: string | null;
+    sync: EditorSyncMap;
+    debugLog: EditorDebugEntry[];
+};
+
+type MathNodeFromEditorResult = {
+    ok: true;
+    math: MathNode;
+} | {
+    ok: false;
+    reason: string;
+};
+declare function mathNodeFromEditorSession(session: EditorSession, mathMode?: string, closing?: string): MathNodeFromEditorResult;
+/** Delimited Arabic TeX for document text/preview — matches `<ButexEditor />` arabic output. */
+declare function mathSourceFromEditorSession(session: EditorSession, mathMode?: string, closing?: string): string;
+
+declare function detectMathSpans(value: string): DetectedMathSpan[];
+declare function buildInlines(value: string, mathObjects?: MathObjectJson[], mode?: DocumentParseMode): DocumentInline[];
+
+declare function renderDocumentLatex(document: DocumentNode): string;
+declare function buildDocumentPreview(document: DocumentNode): DocumentPreview;
+
+type NewDocumentBlockKind = 'section' | 'subsection' | 'subsubsection' | 'paragraph' | 'itemize' | 'enumerate' | 'table' | 'image' | 'raw';
+type DocumentMathTarget = {
+    scope: 'block';
+    blockIndex: number;
+    spanIndex: number;
+} | {
+    scope: 'listItem';
+    blockIndex: number;
+    itemIndex: number;
+    spanIndex: number;
+} | {
+    scope: 'tableCell';
+    blockIndex: number;
+    rowIndex: number;
+    columnIndex: number;
+    spanIndex: number;
+};
+type DocumentInlineTarget = {
+    scope: 'block';
+    blockIndex: number;
+} | {
+    scope: 'listItem';
+    blockIndex: number;
+    itemIndex: number;
+} | {
+    scope: 'tableCell';
+    blockIndex: number;
+    rowIndex: number;
+    columnIndex: number;
+};
+declare function createDocumentBlock(kind: NewDocumentBlockKind): DocumentBlockNode;
+declare function addDocumentBlock(document: DocumentNode, kind: NewDocumentBlockKind): DocumentNode;
+declare function removeDocumentBlock(document: DocumentNode, blockIndex: number): DocumentNode;
+declare function moveDocumentBlock(document: DocumentNode, blockIndex: number, direction: -1 | 1): DocumentNode;
+declare function updateTextBlockValue(document: DocumentNode, blockIndex: number, value: string): DocumentNode;
+declare function updateRawBlockValue(document: DocumentNode, blockIndex: number, value: string): DocumentNode;
+declare function updateImageBlock(document: DocumentNode, blockIndex: number, value: string, options: Record<string, string>): DocumentNode;
+declare function updateListItemValue(document: DocumentNode, blockIndex: number, itemIndex: number, value: string): DocumentNode;
+declare function addListItem(document: DocumentNode, blockIndex: number): DocumentNode;
+declare function removeListItem(document: DocumentNode, blockIndex: number, itemIndex: number): DocumentNode;
+declare function addNestedListBlock(document: DocumentNode, blockIndex: number, itemIndex: number, kind: 'itemize' | 'enumerate'): DocumentNode;
+declare function updateTableCell(document: DocumentNode, blockIndex: number, rowIndex: number, columnIndex: number, value: string): DocumentNode;
+declare function updateTableColumns(document: DocumentNode, blockIndex: number, columns: string): DocumentNode;
+declare function addTableRow(document: DocumentNode, blockIndex: number): DocumentNode;
+declare function removeTableRow(document: DocumentNode, blockIndex: number): DocumentNode;
+declare function addTableColumn(document: DocumentNode, blockIndex: number): DocumentNode;
+declare function removeTableColumn(document: DocumentNode, blockIndex: number): DocumentNode;
+declare function replaceMathSpanSource(document: DocumentNode, target: DocumentMathTarget, source: string): DocumentNode;
+declare function replaceMathSpanFromEditor(document: DocumentNode, target: DocumentMathTarget, math: MathNode, source?: string): DocumentNode;
+declare function insertMathSpanFromEditor(document: DocumentNode, target: DocumentInlineTarget, insertAt: number, math: MathNode, source?: string): DocumentNode;
+declare function documentInlineText(inlines: DocumentInline[]): string;
+
+export { type DetectedMathSpan, type DocumentBlockJson, type DocumentBlockNode, type DocumentCommand, type DocumentInline, type DocumentInlineTarget, type DocumentJson, type DocumentListItemJson, type DocumentMathTarget, type DocumentNode, type DocumentParseMode, type DocumentPreview, type DocumentPreviewMathIsland, type ImageBlockNode, type ListBlockNode, type ListItemNode, type MathInline, type MathNode, type MathObjectJson, type NewDocumentBlockKind, type RawBlockNode, type TableBlockNode, type TextBlockNode, type TextInline, addDocumentBlock, addListItem, addNestedListBlock, addTableColumn, addTableRow, buildDocumentPreview, buildInlines, createDocumentBlock, createEmptyDocument, createImageBlock, createListBlock, createRawBlock, createTableBlock, createTextBlock, detectMathSpans, documentInlineText, fromDocumentJson, fromMathObjectJson, insertMathSpanFromEditor, isDisplayMathNode, isSupportedDocumentCommand, mathNodeFromEditorSession, mathSourceFromEditorSession, moveDocumentBlock, removeDocumentBlock, removeListItem, removeTableColumn, removeTableRow, renderDocumentLatex, renderMathNodeLatex, replaceMathSpanFromEditor, replaceMathSpanSource, updateImageBlock, updateListItemValue, updateRawBlockValue, updateTableCell, updateTableColumns, updateTextBlockValue };