@toaq-oss/omni-mdx 0.1.10 → 0.1.12

package/README.md

@@ -1,221 +1,140 @@
 # @toaq-oss/omni-mdx
 
-The React/Next.js visual rendering engine of the TOAQ-oss MDX ecosystem.
+**The high-performance MDX engine.** A unified React & Next.js rendering layer powered by a dual Rust backend (Native Node.js + WebAssembly).
 
 [![GitHub](https://img.shields.io/badge/GitHub-TOAQ--oss-181717?logo=github)](https://github.com/toaq-oss)
-
-
-This package consumes the ultra-fast Abstract Syntax Tree (AST) generated by our Rust core in WebAssembly (@toaq-oss/core-parser) and transforms it into interactive, secure, and highly customizable React components.
+[![Documentation](https://img.shields.io/badge/Docs-omni--core.org-blue)](https://omni-core.org/mdx)
 
 ---
 
-## Why this exists
-
-Most MDX pipelines (next-mdx-remote, @next/mdx, contentlayer) run at the JS level and require client-side hydration for math, syntax highlighting, and custom components. This means:
+## ⚡ Why Omni-MDX?
 
-- A large JS bundle sent to every visitor
-- Math rendered on the client (flash of unstyled content)
-- Custom components that can't be pure Server Components
+Traditional MDX pipelines are often slow or require complex client-side hydration. `omni-mdx` solves this by moving the heavy lifting to Rust, providing a seamless bridge between raw content and React components.
 
-`@toaq-oss/omni-mdx` solves this by moving the parse step into Rust and the render step into React Server Components. The result is **zero JS for content** — everything is HTML by the time it reaches the browser.
-
-The WASM build is available as a fallback for Edge runtimes or environments where native addons are not supported.
+- **Dual-Engine Architecture:** Uses native `.node` binaries on the server for maximum speed and **WASM** in the browser for instant live previews.
+- **Zero-Hydration Math:** LaTeX is pre-parsed by Rust and rendered via KaTeX with zero layout shift.
+- **RSC Optimized:** Built from the ground up for Next.js App Router and Server Components.
+- **Non-Blocking:** Offloads parsing from the Node.js main thread to Rust, keeping your server responsive even under heavy load.
 
 ---
 
-## Performance & Architecture
-
-`@toaq-oss/omni-mdx` is designed for scale. While traditional parsers block the Node.js main thread, our parser offloads the heavy lifting to a native Rust core via WebAssembly or N-API.
+## 📖 Documentation
 
-**1. Non-Blocking by Design**
-Parsing complex documents or extracting data from thousands of files for ML datasets won't freeze your server. Node.js remains completely free to handle other HTTP requests while Rust does the work in the background.
+For full guides, API references, and advanced configuration, visit:
+👉 **[omni-core.org/mdx](https://omni-core.org/mdx)**
 
-**2. Faster than the Standard**
-In a strict end-to-end benchmark (parsing raw text to an exploitable JSX AST) over 1,000 iterations of a complex document:
-- `@toaq-oss/omni-mdx` is consistently **~30% faster** than the official `@mdx-js/mdx` compiler.
-
-**3. Zero Client JS**
-Because the AST is generated on the server and maps directly to React Server Components, the client receives 0 bytes of parsing logic.
+---
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install @toaq-oss/omni-mdx
-# KaTeX is optional — only needed if your content has math
+# KaTeX is required for math rendering
 npm install katex
 ```
 
-Add the KaTeX stylesheet to your `layout.tsx`:
-
-```tsx
-import "katex/dist/katex.min.css";
+## Next.js Configuration
+To enable the WebAssembly engine for client-side rendering, update your `next.config.js`:
+```typescript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  webpack: (config) => {
+    config.experiments = { ...config.experiments, asyncWebAssembly: true };
+    config.module.rules.push({
+      test: /\.wasm$/,
+      type: "asset/resource",
+    });
+    return config;
+  },
+};
+
+export default nextConfig;
 ```
 
 ---
 
-## Usage
+## 🚀 Usage
+### 1. Server-Side Rendering (RSC)
+Recommended for documentation, blogs, and research papers.
 
-### Server Component (recommended)
+> Full example available here :
+> * Basic setup: [TOAQ-oss/omni-core-sandox](https://github.com/TOAQ-oss/omni-mdx-sandbox/tree/main/next/basic-setup)
+> * Advanced rendering : [TOAQ-oss/omni-core-sandox](https://github.com/TOAQ-oss/omni-mdx-sandbox/tree/main/next/advanced-rendering)
 
 ```tsx
 import { parseMdx, MDXServerRenderer } from "@toaq-oss/omni-mdx/server";
-import { Note, Details }               from "@/components/mdx";
-
-const COMPONENTS = { Note, Details };
-
-export default async function ArticlePage({ params }) {
-  const content = await getArticleContent(params.slug);
-  const ast     = await parseMdx(content);
-
-  return <MDXServerRenderer ast={ast} components={COMPONENTS} />;
-}
-```
-
-That's it. No `getStaticProps`, no serialisation workarounds, no client bundle for the content.
-
-### Static generation
+import { MyComponent } from "@/components/mdx";
 
-Because `parseMdx` is async and runs on the server, it works naturally with `generateStaticParams`:
-
-```tsx
-export async function generateStaticParams() {
-  const slugs = await getAllSlugs();
-  return slugs.map(slug => ({ slug }));
-}
+export default async function Page({ content }) {
+  // Parsed via Native Rust Addon (.node)
+  const ast = await parseMdx(content);
 
-export default async function ArticlePage({ params }) {
-  const content = await getArticleContent(params.slug);
-  const ast     = await parseMdx(content);
-  return <MDXServerRenderer ast={ast} components={COMPONENTS} />;
+  return (
+    <MDXServerRenderer 
+      ast={ast} 
+      components={{ MyComponent }} 
+    />
+  );
 }
 ```
 
-At `next build`, Next.js calls `parseMdx` once per article and pre-renders everything to static HTML. The Rust parser never runs in the browser.
+###  2. Live Client Editor (WASM)
+Perfect for real-time previews or CMS interfaces.
 
-### Live editor (client-side)
-
-For live MDX previews where the content changes in the browser:
+> Full example available here : [TOAQ-oss/omni-core-sandox](https://github.com/TOAQ-oss/omni-mdx-sandbox/tree/main/next/client-rendering)
 
 ```tsx
 "use client";
-import { MDXClientRenderer } from "@toaq-oss/omni-mdx/client";
-
-export function LivePreview({ ast, components }) {
-  return <MDXClientRenderer ast={ast} components={components} katex />;
+import { useState } from "react";
+import { parseMdx, MDXClientRenderer } from "@toaq-oss/omni-mdx/client";
+
+export default function Editor() {
+  const [ast, setAst] = useState(null);
+
+  const handleChange = async (text) => {
+    // Runs 100% locally in the browser via WebAssembly
+    const result = await parseMdx(text);
+    setAst(result);
+  };
+
+  return (
+    <div>
+      <textarea onChange={(e) => handleChange(e.target.value)} />
+      <MDXClientRenderer ast={ast} />
+    </div>
+  );
 }
 ```
 
-The `ast` prop should be computed server-side and passed down, or computed client-side by calling a Route Handler that runs `parseMdx`.
-
----
-
-## Import map
-
-|Import path|What you get|Where to use|
-|----|---|----|
-|`@toaq-oss/omni-mdx`|Types + `MDX_COMPONENTS` registry|Anywhere|
-|`@toaq-oss/omni-mdx/server`|`parseMdx`, `MDXServerRenderer`, `MDXParseError` |Server Components only|
-|`@toaq-oss/omni-mdx/client`|`MDXClientRenderer`, `MDXErrorBoundary`|Client Components only|
-
 ---
-
-## Custom components
-
-Register components by name — the key matches the JSX tag in the MDX source:
-
-```tsx
-// MDX source:
-// <Note type="warning" title="Heads up">
-//   Be careful with **this**.
-// </Note>
-
-import { Note }    from "@/components/Note";    // can be a Server Component
-import { Details } from "@/components/Details"; // can be a Server Component
-import { Chart }   from "@/components/Chart";   // "use client" inside
-
-const COMPONENTS = { Note, Details, Chart };
-
-const ast = await parseMdx(content);
-return <MDXServerRenderer ast={ast} components={COMPONENTS} />;
-```
-
-Server Components in the registry are rendered on the server with zero client JS. Client Components are hydrated normally.
+|Environment|Backend|Entry Point|
+|:---|:---|:---|
+|**Server** (Node.js)|Native Addon (`.node`)|`@toaq-oss/omni-mdx/server`|
+|**Client** (Browser)|WebAssembly (`.wasm`)|`@toaq-oss/omni-mdx/client`|
+|**Edge** (Vercel)|Native Addon (`.wasm`)|`@toaq-oss/omni-mdx/client`|
 
 ---
 
-## Error handling
-
-### Parse errors
-
+## 🧩 Features
+### 📐 Professional Math
+Math is handled via KaTeX. Simply include the CSS in your `layout.tsx`:
 ```tsx
-import { parseMdx, MDXParseError } from "@toaq-oss/omni-mdx/server";
-
-try {
-  const ast = await parseMdx(content);
-} catch (e) {
-  if (e instanceof MDXParseError) {
-    console.error("MDX syntax error:", e.message);
-    console.error("Source:", e.source);
-  }
-}
+import "katex/dist/katex.min.css";
 ```
+* **Inline:** $E=mc^2$
+* **Block:** $$\int f(x)dx$$
 
-### Component render errors
-
-In `MDXClientRenderer`, every custom component is automatically wrapped in `MDXErrorBoundary`. If a component throws, the error is isolated — the rest of the document continues to render.
-
-You can also use `MDXErrorBoundary` directly:
-
+### 🎨 Custom Components
+Register any React component (Server or Client) to handle custom tags:
 ```tsx
-import { MDXErrorBoundary } from "@toaq-oss/omni-mdx/client";
-
-<MDXErrorBoundary componentName="Chart">
-  <Chart data={maybeNull} />
-</MDXErrorBoundary>
+const components = {
+  Callout: ({ children }) => <div className="p-4 bg-blue-50">{children}</div>,
+  VocalDataset: dynamic(() => import('./VocalDataset'), { ssr: false })
+};
 ```
 
 ---
-
-## Math
-
-Math is handled entirely by the Rust parser — no remark-math or rehype-katex needed.
-
-| Syntax | Output |
-|---|---|
-| `$E = mc^2$`  | `<span class="math math-inline" data-math="…">` |
-| `$$…$$`       | `<div class="math math-display" data-math="…">` |
-
-KaTeX hydrates the `data-math` attributes on the client via `MDXClientRenderer`, or you can use any KaTeX auto-render script in your layout.
-
----
-
-## Runtime support
-
-| Runtime | Native `.node` | WASM fallback |
-|-----------------|:--------------:|:-------------:|
-| Node.js 18+ | ✅ | ✅ |
-| Next.js (RSC) | ✅ | ✅ |
-| Edge runtime | ❌ | ✅ |
-| Browser | ❌ | ✅ |
-
-The package auto-detects the environment and loads the appropriate backend. No configuration required.
-
----
-
-## Building the native addon
-
-The `.node` files are pre-built for common platforms. To build for your platform:
-
-```bash
-cd core-parser
-napi build --platform --release --features node --no-js
-cp toaq-parser-core.*.node ../packages/mdx-next/native/
-```
-
-To build the WASM fallback:
-
-```bash
-cd core-parser
-wasm-pack build --target bundler --features wasm
-mv pkg/* ../packages/mdx-next/wasm/
-```
+## 🤝 Contributing
+This package is part of the TOAQ open-source ecosystem.
+* **Core Parser (Rust):** [TOAQ-oss/omni-mdx-core](https://github.com/TOAQ-oss/omni-mdx-core)
+* **Reporting Issues:** Please use the GitHub issue tracker for bugs or feature requests.

package/dist/client.cjs

@@ -6,6 +6,9 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -28,11 +31,252 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// wasm/omni_mdx_core.js
+var omni_mdx_core_exports = {};
+__export(omni_mdx_core_exports, {
+  default: () => __wbg_init,
+  initSync: () => initSync,
+  parse_mdx_to_json: () => parse_mdx_to_json,
+  parse_mdx_to_json_pretty: () => parse_mdx_to_json_pretty,
+  parse_mdx_version: () => parse_mdx_version
+});
+function parse_mdx_to_json(input) {
+  let deferred3_0;
+  let deferred3_1;
+  try {
+    const ptr0 = passStringToWasm0(input, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.parse_mdx_to_json(ptr0, len0);
+    var ptr2 = ret[0];
+    var len2 = ret[1];
+    if (ret[3]) {
+      ptr2 = 0;
+      len2 = 0;
+      throw takeFromExternrefTable0(ret[2]);
+    }
+    deferred3_0 = ptr2;
+    deferred3_1 = len2;
+    return getStringFromWasm0(ptr2, len2);
+  } finally {
+    wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+  }
+}
+function parse_mdx_to_json_pretty(input) {
+  let deferred3_0;
+  let deferred3_1;
+  try {
+    const ptr0 = passStringToWasm0(input, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.parse_mdx_to_json_pretty(ptr0, len0);
+    var ptr2 = ret[0];
+    var len2 = ret[1];
+    if (ret[3]) {
+      ptr2 = 0;
+      len2 = 0;
+      throw takeFromExternrefTable0(ret[2]);
+    }
+    deferred3_0 = ptr2;
+    deferred3_1 = len2;
+    return getStringFromWasm0(ptr2, len2);
+  } finally {
+    wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+  }
+}
+function parse_mdx_version() {
+  let deferred1_0;
+  let deferred1_1;
+  try {
+    const ret = wasm.parse_mdx_version();
+    deferred1_0 = ret[0];
+    deferred1_1 = ret[1];
+    return getStringFromWasm0(ret[0], ret[1]);
+  } finally {
+    wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+  }
+}
+function __wbg_get_imports() {
+  const import0 = {
+    __proto__: null,
+    __wbg_Error_83742b46f01ce22d: function(arg0, arg1) {
+      const ret = Error(getStringFromWasm0(arg0, arg1));
+      return ret;
+    },
+    __wbindgen_init_externref_table: function() {
+      const table = wasm.__wbindgen_externrefs;
+      const offset = table.grow(4);
+      table.set(0, void 0);
+      table.set(offset + 0, void 0);
+      table.set(offset + 1, null);
+      table.set(offset + 2, true);
+      table.set(offset + 3, false);
+    }
+  };
+  return {
+    __proto__: null,
+    "./omni_mdx_core_bg.js": import0
+  };
+}
+function getStringFromWasm0(ptr, len) {
+  ptr = ptr >>> 0;
+  return decodeText(ptr, len);
+}
+function getUint8ArrayMemory0() {
+  if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) {
+    cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer);
+  }
+  return cachedUint8ArrayMemory0;
+}
+function passStringToWasm0(arg, malloc, realloc) {
+  if (realloc === void 0) {
+    const buf = cachedTextEncoder.encode(arg);
+    const ptr2 = malloc(buf.length, 1) >>> 0;
+    getUint8ArrayMemory0().subarray(ptr2, ptr2 + buf.length).set(buf);
+    WASM_VECTOR_LEN = buf.length;
+    return ptr2;
+  }
+  let len = arg.length;
+  let ptr = malloc(len, 1) >>> 0;
+  const mem = getUint8ArrayMemory0();
+  let offset = 0;
+  for (; offset < len; offset++) {
+    const code = arg.charCodeAt(offset);
+    if (code > 127) break;
+    mem[ptr + offset] = code;
+  }
+  if (offset !== len) {
+    if (offset !== 0) {
+      arg = arg.slice(offset);
+    }
+    ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0;
+    const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len);
+    const ret = cachedTextEncoder.encodeInto(arg, view);
+    offset += ret.written;
+    ptr = realloc(ptr, len, offset, 1) >>> 0;
+  }
+  WASM_VECTOR_LEN = offset;
+  return ptr;
+}
+function takeFromExternrefTable0(idx) {
+  const value = wasm.__wbindgen_externrefs.get(idx);
+  wasm.__externref_table_dealloc(idx);
+  return value;
+}
+function decodeText(ptr, len) {
+  numBytesDecoded += len;
+  if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) {
+    cachedTextDecoder = new TextDecoder("utf-8", { ignoreBOM: true, fatal: true });
+    cachedTextDecoder.decode();
+    numBytesDecoded = len;
+  }
+  return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len));
+}
+function __wbg_finalize_init(instance, module2) {
+  wasm = instance.exports;
+  wasmModule = module2;
+  cachedUint8ArrayMemory0 = null;
+  wasm.__wbindgen_start();
+  return wasm;
+}
+async function __wbg_load(module2, imports) {
+  if (typeof Response === "function" && module2 instanceof Response) {
+    if (typeof WebAssembly.instantiateStreaming === "function") {
+      try {
+        return await WebAssembly.instantiateStreaming(module2, imports);
+      } catch (e) {
+        const validResponse = module2.ok && expectedResponseType(module2.type);
+        if (validResponse && module2.headers.get("Content-Type") !== "application/wasm") {
+          console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e);
+        } else {
+          throw e;
+        }
+      }
+    }
+    const bytes = await module2.arrayBuffer();
+    return await WebAssembly.instantiate(bytes, imports);
+  } else {
+    const instance = await WebAssembly.instantiate(module2, imports);
+    if (instance instanceof WebAssembly.Instance) {
+      return { instance, module: module2 };
+    } else {
+      return instance;
+    }
+  }
+  function expectedResponseType(type) {
+    switch (type) {
+      case "basic":
+      case "cors":
+      case "default":
+        return true;
+    }
+    return false;
+  }
+}
+function initSync(module2) {
+  if (wasm !== void 0) return wasm;
+  if (module2 !== void 0) {
+    if (Object.getPrototypeOf(module2) === Object.prototype) {
+      ({ module: module2 } = module2);
+    } else {
+      console.warn("using deprecated parameters for `initSync()`; pass a single object instead");
+    }
+  }
+  const imports = __wbg_get_imports();
+  if (!(module2 instanceof WebAssembly.Module)) {
+    module2 = new WebAssembly.Module(module2);
+  }
+  const instance = new WebAssembly.Instance(module2, imports);
+  return __wbg_finalize_init(instance, module2);
+}
+async function __wbg_init(module_or_path) {
+  if (wasm !== void 0) return wasm;
+  if (module_or_path !== void 0) {
+    if (Object.getPrototypeOf(module_or_path) === Object.prototype) {
+      ({ module_or_path } = module_or_path);
+    } else {
+      console.warn("using deprecated parameters for the initialization function; pass a single object instead");
+    }
+  }
+  if (module_or_path === void 0) {
+    module_or_path = new URL("omni_mdx_core_bg.wasm", import_meta.url);
+  }
+  const imports = __wbg_get_imports();
+  if (typeof module_or_path === "string" || typeof Request === "function" && module_or_path instanceof Request || typeof URL === "function" && module_or_path instanceof URL) {
+    module_or_path = fetch(module_or_path);
+  }
+  const { instance, module: module2 } = await __wbg_load(await module_or_path, imports);
+  return __wbg_finalize_init(instance, module2);
+}
+var import_meta, cachedUint8ArrayMemory0, cachedTextDecoder, MAX_SAFARI_DECODE_BYTES, numBytesDecoded, cachedTextEncoder, WASM_VECTOR_LEN, wasmModule, wasm;
+var init_omni_mdx_core = __esm({
+  "wasm/omni_mdx_core.js"() {
+    "use strict";
+    import_meta = {};
+    cachedUint8ArrayMemory0 = null;
+    cachedTextDecoder = new TextDecoder("utf-8", { ignoreBOM: true, fatal: true });
+    cachedTextDecoder.decode();
+    MAX_SAFARI_DECODE_BYTES = 2146435072;
+    numBytesDecoded = 0;
+    cachedTextEncoder = new TextEncoder();
+    if (!("encodeInto" in cachedTextEncoder)) {
+      cachedTextEncoder.encodeInto = function(arg, view) {
+        const buf = cachedTextEncoder.encode(arg);
+        view.set(buf);
+        return {
+          read: arg.length,
+          written: buf.length
+        };
+      };
+    }
+    WASM_VECTOR_LEN = 0;
+  }
+});
+
 // src/client.ts
 var client_exports = {};
 __export(client_exports, {
   MDXClientRenderer: () => MDXClientRenderer,
-  MDXErrorBoundary: () => MDXErrorBoundary
+  MDXErrorBoundary: () => MDXErrorBoundary,
+  parseMdx: () => parseMdxClient
 });
 module.exports = __toCommonJS(client_exports);
 
@@ -227,4 +471,29 @@ function MDXClientRenderer({
   if (!ast || !Array.isArray(ast)) return null;
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "omni-mdx-root", children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(MDXClientContent, { ast, components }) });
 }
+
+// src/parse.client.ts
+var import_meta2 = {};
+var _parseClient = null;
+async function getClientParser() {
+  if (_parseClient) return _parseClient;
+  const wasm2 = await Promise.resolve().then(() => (init_omni_mdx_core(), omni_mdx_core_exports));
+  if (typeof wasm2.default === "function") {
+    const wasmUrl = new URL("./omni_mdx_core_bg.wasm", import_meta2.url);
+    await wasm2.default(wasmUrl);
+  }
+  _parseClient = (mdx) => wasm2.parse_mdx_to_json(mdx);
+  return _parseClient;
+}
+async function parseMdxClient(mdx) {
+  if (typeof window === "undefined") return [];
+  try {
+    const parse = await getClientParser();
+    const json = parse(mdx);
+    return JSON.parse(json);
+  } catch (err) {
+    console.error("[omni-mdx] WASM client parse error:", err);
+    return [];
+  }
+}
 //# sourceMappingURL=client.cjs.map