html-to-markdown-wasm 2.6.6 → 2.7.0

package/README.md

@@ -72,6 +72,42 @@ console.log(markdown);
 // This is **fast**!
 ```
 
+### Reusing Options Handles
+
+```ts
+import {
+  convertWithOptionsHandle,
+  createConversionOptionsHandle,
+} from '@html-to-markdown/wasm';
+
+const handle = createConversionOptionsHandle({ hocrSpatialTables: false });
+const markdown = convertWithOptionsHandle('<h1>Reusable</h1>', handle);
+```
+
+### Byte-Based Input (Buffers / Uint8Array)
+
+When you already have raw bytes (e.g., `fs.readFileSync`, Fetch API responses), skip re-encoding with `TextDecoder` by calling the byte-friendly helpers:
+
+```ts
+import {
+  convertBytes,
+  convertBytesWithOptionsHandle,
+  createConversionOptionsHandle,
+  convertBytesWithInlineImages,
+} from '@html-to-markdown/wasm';
+import { readFileSync } from 'node:fs';
+
+const htmlBytes = readFileSync('input.html'); // Buffer -> Uint8Array
+const markdown = convertBytes(htmlBytes);
+
+const handle = createConversionOptionsHandle({ headingStyle: 'atx' });
+const markdownFromHandle = convertBytesWithOptionsHandle(htmlBytes, handle);
+
+const inlineExtraction = convertBytesWithInlineImages(htmlBytes, null, {
+  maxDecodedSizeBytes: 5 * 1024 * 1024,
+});
+```
+
 ### With Options
 
 ```typescript

package/dist/README.md

@@ -89,7 +89,7 @@ const markdown = convert(html, {
 });
 ```
 
-**Performance:** Native bindings average ~19k ops/sec, WASM averages ~16k ops/sec (benchmarked on complex real-world documents).
+**Performance:** The shared fixture harness (`task bench:bindings`) now clocks Node, Python, and the Rust CLI at ~1.3–1.4k ops/sec (≈150 MB/s) on the 129 KB Wikipedia “Lists” page thanks to the new Buffer/Uint8Array fast paths and release-mode harness. Ruby stays close at ~1.2k ops/sec, PHP lands around 0.3k ops/sec (≈35 MB/s), and WASM hits ~0.85k ops/sec—plenty for browsers, Deno, and edge runtimes.
 
 See the JavaScript guides for full API documentation:
 
@@ -146,38 +146,65 @@ Benchmarked on Apple M4 with complex real-world documents (Wikipedia articles, t
 
 ### Operations per Second (higher is better)
 
-| Document Type              | Node.js (NAPI) | WASM   | Python (PyO3) | Speedup (Node vs Python) |
-| -------------------------- | -------------- | ------ | ------------- | ------------------------ |
-| **Small (5 paragraphs)**   | 86,233         | 70,300 | 8,443         | **10.2×**                |
-| **Medium (25 paragraphs)** | 18,979         | 15,282 | 1,846         | **10.3×**                |
-| **Large (100 paragraphs)** | 4,907          | 3,836  | 438           | **11.2×**                |
-| **Tables (complex)**       | 5,003          | 3,748  | 4,829         | 1.0×                     |
-| **Lists (nested)**         | 1,819          | 1,391  | 1,165         | **1.6×**                 |
-| **Wikipedia (129KB)**      | 1,125          | 1,022  | -             | -                        |
-| **Wikipedia (653KB)**      | 156            | 147    | -             | -                        |
+Derived directly from `tools/runtime-bench/results/latest.json` (Apple M4, shared fixtures):
+
+| Fixture                | Node.js (NAPI) | WASM | Python (PyO3) | Speedup (Node vs Python) |
+| ---------------------- | -------------- | ---- | ------------- | ------------------------ |
+| **Lists (Timeline)**   | 1,308          | 882  | 1,405         | **0.9×**                 |
+| **Tables (Countries)** | 331            | 242  | 352           | **0.9×**                 |
+| **Medium (Python)**    | 150            | 121  | 158           | **1.0×**                 |
+| **Large (Rust)**       | 163            | 124  | 183           | **0.9×**                 |
+| **Small (Intro)**      | 208            | 163  | 223           | **0.9×**                 |
+| **HOCR German PDF**    | 2,944          | 1,637| 2,991         | **1.0×**                 |
+| **HOCR Invoice**       | 27,326         | 7,775| 23,500        | **1.2×**                 |
+| **HOCR Tables**        | 3,475          | 1,667| 3,464         | **1.0×**                 |
 
 ### Average Performance Summary
 
-| Implementation        | Avg ops/sec      | vs WASM      | vs Python       | Best For                          |
-| --------------------- | ---------------- | ------------ | --------------- | --------------------------------- |
-| **Node.js (NAPI-RS)** | **18,162**       | 1.17× faster | **7.4× faster** | Maximum throughput in Node.js/Bun |
-| **WebAssembly**       | **15,536**       | baseline     | **6.3× faster** | Universal (Deno, browsers, edge)  |
-| **Python (PyO3)**     | **2,465**        | 6.3× slower  | baseline        | Python ecosystem integration      |
-| **Rust CLI/Binary**   | **150-210 MB/s** | -            | -               | Standalone processing             |
+| Implementation        | Avg ops/sec (fixtures) | vs Python | Notes |
+| --------------------- | ---------------------- | --------- | ----- |
+| **Rust CLI/Binary**   | **4,996**              | **1.2× faster** | Preprocessing now stays in one pass + reuses `parse_owned`, so the CLI leads every fixture |
+| **Node.js (NAPI-RS)** | **4,488**              | 1.0×      | Buffer/handle combo keeps Node within ~10 % of the Rust core while serving JS runtimes |
+| **Ruby (magnus)**     | **4,278**              | 0.9×      | Still extremely fast; ~25 k ops/sec on HOCR invoices without extra work |
+| **Python (PyO3)**     | **4,034**              | baseline  | Release-mode harness plus handle reuse keep it competitive, but it now trails Node/Rust |
+| **WebAssembly**       | **1,576**              | 0.4×      | Portable option for Deno/browsers/edge using the new byte APIs |
+| **PHP (ext)**         | **1,480**              | 0.4×      | Composer extension holds steady at 35–70 MB/s once the PIE build is installed |
 
 ### Key Insights
 
-- **JavaScript bindings are fastest**: Native Node.js bindings achieve ~18k ops/sec average, with WASM close behind at ~16k ops/sec
-- **Python is 6-10× slower**: Despite using the same Rust core, PyO3 FFI overhead significantly impacts Python performance
-- **Small documents**: Both JS implementations reach 70-90k ops/sec on simple HTML
-- **Large documents**: Performance gap widens with complexity
+- **Rust now leads throughput**: the fused preprocessing + `parse_owned` pathway pushes the CLI to ~1.7 k ops/sec on the 129 KB lists page and ~31 k ops/sec on the HOCR invoice fixture.
+- **Node.js trails by only a few percent** after the buffer/handle work—~1.3 k ops/sec on the lists fixture and 27 k ops/sec on HOCR invoices without any UTF-16 copies.
+- **Python remains competitive** but now sits below Node/Rust (~4.0 k average ops/sec); stick to the v2 API to avoid the deprecated compatibility shim.
+- **PHP and WASM stay in the 35–70 MB/s band**, which is plenty for Composer queues or edge runtimes as long as the extension/module is built ahead of time.
+- **Rust CLI results now mirror the bindings**, since `task bench:bindings` runs the harness with `cargo run --release` by default—profile there, then push optimizations down into each FFI layer.
+
+### Runtime Benchmarks (PHP / Ruby / Python / Node / WASM)
+
+Measured on Apple M4 using the fixture-driven runtime harness in `tools/runtime-bench` (`task bench:bindings`). Every binding consumes the exact same HTML fixtures and hOCR samples from `test_documents/`:
+
+| Document            | Size     | Ruby ops/sec | PHP ops/sec | Python ops/sec | Node ops/sec | WASM ops/sec | Rust ops/sec |
+| ------------------- | -------- | ------------ | ----------- | -------------- | ------------ | ------------ | ------------ |
+| Lists (Timeline)    | 129 KB   | 1,349        | 533         | 1,405          | 1,308        | 882          | **1,700**    |
+| Tables (Countries)  | 360 KB   | 326          | 118         | 352            | 331          | 242          | **416**      |
+| Medium (Python)     | 657 KB   | 157          | 59          | 158            | 150          | 121          | **190**      |
+| Large (Rust)        | 567 KB   | 174          | 65          | 183            | 163          | 124          | **220**      |
+| Small (Intro)       | 463 KB   | 214          | 83          | 223            | 208          | 163          | **258**      |
+| HOCR German PDF     | 44 KB    | 2,936        | 1,007       | **2,991**      | 2,944        | 1,637        | 2,760        |
+| HOCR Invoice        | 4 KB     | 25,740       | 8,781       | 23,500         | 27,326       | 7,775        | **31,345**   |
+| HOCR Embedded Tables| 37 KB    | 3,328        | 1,194       | 3,464          | **3,475**    | 1,667        | 3,080        |
+
+The harness shells out to each runtime’s lightweight benchmark driver (`packages/*/bin/benchmark.*`, `crates/*/bin/benchmark.ts`), feeds fixtures defined in `tools/runtime-bench/fixtures/*.toml`, and writes machine-readable JSON reports (`tools/runtime-bench/results/latest.json`) for regression tracking. Add new languages or scenarios by extending those fixture files and drivers.
+
+Use `task bench:bindings` to regenerate throughput numbers across all bindings or `task bench:bindings:profile` to capture CPU/memory samples while the benchmarks run. To focus on specific languages or fixtures, pass `--language` / `--fixture` directly to `cargo run --manifest-path tools/runtime-bench/Cargo.toml -- …`.
+
+Need a call-stack view of the Rust core? Run `task flamegraph:rust` (or call the harness with `--language rust --flamegraph path.svg`) to profile a fixture and dump a ready-to-inspect flamegraph in `tools/runtime-bench/results/`.
 
 **Note on Python performance**: The current Python bindings have optimization opportunities. The v2 API with direct `convert()` calls performs best; avoid the v1 compatibility layer for performance-critical applications.
 
 ## Compatibility (v1 → v2)
 
 - V2’s Rust core sustains **150–210 MB/s** throughput; V1 averaged **≈ 2.5 MB/s** in its Python/BeautifulSoup implementation (60–80× faster).
-- The Python package offers a compatibility shim in `html_to_markdown.v1_compat` (`convert_to_markdown`, `convert_to_markdown_stream`, `markdownify`). Details and keyword mappings live in [Python README](https://github.com/Goldziher/html-to-markdown/blob/main/packages/python/README.md#v1-compatibility).
+- The Python package offers a compatibility shim in `html_to_markdown.v1_compat` (`convert_to_markdown`, `convert_to_markdown_stream`, `markdownify`). The shim is deprecated, emits `DeprecationWarning` on every call, and will be removed in v3.0—plan migrations now. Details and keyword mappings live in [Python README](https://github.com/Goldziher/html-to-markdown/blob/main/packages/python/README.md#v1-compatibility).
 - CLI flag changes, option renames, and other breaking updates are summarised in [CHANGELOG](https://github.com/Goldziher/html-to-markdown/blob/main/CHANGELOG.md#breaking-changes).
 
 ## Community

package/dist/html_to_markdown_wasm.d.ts

@@ -1,5 +1,6 @@
 /* tslint:disable */
 /* eslint-disable */
+export function convertBytes(html: Uint8Array, options: any): string;
 /**
  * Convert HTML to Markdown
  *
@@ -19,34 +20,20 @@
  * ```
  */
 export function convert(html: string, options: any): string;
-/**
- * Convert HTML to Markdown while collecting inline images
- *
- * # Arguments
- *
- * * `html` - The HTML string to convert
- * * `options` - Optional conversion options (as a JavaScript object)
- * * `image_config` - Configuration for inline image extraction
- *
- * # Example
- *
- * ```javascript
- * import { convertWithInlineImages, WasmInlineImageConfig } from '@html-to-markdown/wasm';
- *
- * const html = '<img src="data:image/png;base64,..." alt="test">';
- * const config = new WasmInlineImageConfig(1024 * 1024);
- * config.inferDimensions = true;
- *
- * const result = convertWithInlineImages(html, null, config);
- * console.log(result.markdown);
- * console.log(result.inlineImages.length);
- * ```
- */
+export function convertWithOptionsHandle(html: string, handle: WasmConversionOptionsHandle): string;
+export function createConversionOptionsHandle(options: any): WasmConversionOptionsHandle;
 export function convertWithInlineImages(html: string, options: any, image_config?: WasmInlineImageConfig | null): WasmHtmlExtraction;
+export function convertBytesWithInlineImages(html: Uint8Array, options: any, image_config?: WasmInlineImageConfig | null): WasmHtmlExtraction;
 /**
  * Initialize panic hook for better error messages in the browser
  */
 export function init(): void;
+export function convertBytesWithOptionsHandle(html: Uint8Array, handle: WasmConversionOptionsHandle): string;
+export class WasmConversionOptionsHandle {
+  free(): void;
+  [Symbol.dispose](): void;
+  constructor(options: any);
+}
 /**
  * Result of HTML extraction with inline images
  */

package/dist/html_to_markdown_wasm_bg.js

@@ -231,6 +231,36 @@ function getArrayJsValueFromWasm0(ptr, len) {
     }
     return result;
 }
+/**
+ * @param {Uint8Array} html
+ * @param {any} options
+ * @returns {string}
+ */
+export function convertBytes(html, options) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.convertBytes(retptr, addHeapObject(html), addHeapObject(options));
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr1 = r0;
+        var len1 = r1;
+        if (r3) {
+            ptr1 = 0; len1 = 0;
+            throw takeObject(r2);
+        }
+        deferred2_0 = ptr1;
+        deferred2_1 = len1;
+        return getStringFromWasm0(ptr1, len1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export4(deferred2_0, deferred2_1, 1);
+    }
+}
+
 /**
  * Convert HTML to Markdown
  *
@@ -285,27 +315,59 @@ function _assertClass(instance, klass) {
     }
 }
 /**
- * Convert HTML to Markdown while collecting inline images
- *
- * # Arguments
- *
- * * `html` - The HTML string to convert
- * * `options` - Optional conversion options (as a JavaScript object)
- * * `image_config` - Configuration for inline image extraction
- *
- * # Example
- *
- * ```javascript
- * import { convertWithInlineImages, WasmInlineImageConfig } from '@html-to-markdown/wasm';
- *
- * const html = '<img src="data:image/png;base64,..." alt="test">';
- * const config = new WasmInlineImageConfig(1024 * 1024);
- * config.inferDimensions = true;
- *
- * const result = convertWithInlineImages(html, null, config);
- * console.log(result.markdown);
- * console.log(result.inlineImages.length);
- * ```
+ * @param {string} html
+ * @param {WasmConversionOptionsHandle} handle
+ * @returns {string}
+ */
+export function convertWithOptionsHandle(html, handle) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        const ptr0 = passStringToWasm0(html, wasm.__wbindgen_export, wasm.__wbindgen_export2);
+        const len0 = WASM_VECTOR_LEN;
+        _assertClass(handle, WasmConversionOptionsHandle);
+        wasm.convertWithOptionsHandle(retptr, ptr0, len0, handle.__wbg_ptr);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr2 = r0;
+        var len2 = r1;
+        if (r3) {
+            ptr2 = 0; len2 = 0;
+            throw takeObject(r2);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export4(deferred3_0, deferred3_1, 1);
+    }
+}
+
+/**
+ * @param {any} options
+ * @returns {WasmConversionOptionsHandle}
+ */
+export function createConversionOptionsHandle(options) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        wasm.createConversionOptionsHandle(retptr, addHeapObject(options));
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return WasmConversionOptionsHandle.__wrap(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+}
+
+/**
  * @param {string} html
  * @param {any} options
  * @param {WasmInlineImageConfig | null} [image_config]
@@ -334,6 +396,33 @@ export function convertWithInlineImages(html, options, image_config) {
     }
 }
 
+/**
+ * @param {Uint8Array} html
+ * @param {any} options
+ * @param {WasmInlineImageConfig | null} [image_config]
+ * @returns {WasmHtmlExtraction}
+ */
+export function convertBytesWithInlineImages(html, options, image_config) {
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        let ptr0 = 0;
+        if (!isLikeNone(image_config)) {
+            _assertClass(image_config, WasmInlineImageConfig);
+            ptr0 = image_config.__destroy_into_raw();
+        }
+        wasm.convertBytesWithInlineImages(retptr, addHeapObject(html), addHeapObject(options), ptr0);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        if (r2) {
+            throw takeObject(r1);
+        }
+        return WasmHtmlExtraction.__wrap(r0);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+    }
+}
+
 /**
  * Initialize panic hook for better error messages in the browser
  */
@@ -341,6 +430,85 @@ export function init() {
     wasm.init();
 }
 
+/**
+ * @param {Uint8Array} html
+ * @param {WasmConversionOptionsHandle} handle
+ * @returns {string}
+ */
+export function convertBytesWithOptionsHandle(html, handle) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+        _assertClass(handle, WasmConversionOptionsHandle);
+        wasm.convertBytesWithOptionsHandle(retptr, addHeapObject(html), handle.__wbg_ptr);
+        var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+        var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+        var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+        var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
+        var ptr1 = r0;
+        var len1 = r1;
+        if (r3) {
+            ptr1 = 0; len1 = 0;
+            throw takeObject(r2);
+        }
+        deferred2_0 = ptr1;
+        deferred2_1 = len1;
+        return getStringFromWasm0(ptr1, len1);
+    } finally {
+        wasm.__wbindgen_add_to_stack_pointer(16);
+        wasm.__wbindgen_export4(deferred2_0, deferred2_1, 1);
+    }
+}
+
+const WasmConversionOptionsHandleFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_wasmconversionoptionshandle_free(ptr >>> 0, 1));
+
+export class WasmConversionOptionsHandle {
+
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(WasmConversionOptionsHandle.prototype);
+        obj.__wbg_ptr = ptr;
+        WasmConversionOptionsHandleFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        WasmConversionOptionsHandleFinalization.unregister(this);
+        return ptr;
+    }
+
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_wasmconversionoptionshandle_free(ptr, 0);
+    }
+    /**
+     * @param {any} options
+     */
+    constructor(options) {
+        try {
+            const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
+            wasm.wasmconversionoptionshandle_new(retptr, addHeapObject(options));
+            var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
+            var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
+            var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
+            if (r2) {
+                throw takeObject(r1);
+            }
+            this.__wbg_ptr = r0 >>> 0;
+            WasmConversionOptionsHandleFinalization.register(this, this.__wbg_ptr, this);
+            return this;
+        } finally {
+            wasm.__wbindgen_add_to_stack_pointer(16);
+        }
+    }
+}
+if (Symbol.dispose) WasmConversionOptionsHandle.prototype[Symbol.dispose] = WasmConversionOptionsHandle.prototype.free;
+
 const WasmHtmlExtractionFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_wasmhtmlextraction_free(ptr >>> 0, 1));
@@ -831,6 +999,17 @@ export function __wbg_instanceof_ArrayBuffer_70beb1189ca63b38(arg0) {
     return ret;
 };
 
+export function __wbg_instanceof_Object_10bb762262230c68(arg0) {
+    let result;
+    try {
+        result = getObject(arg0) instanceof Object;
+    } catch (_) {
+        result = false;
+    }
+    const ret = result;
+    return ret;
+};
+
 export function __wbg_instanceof_Uint8Array_20c8e73002f7af98(arg0) {
     let result;
     try {
@@ -857,6 +1036,11 @@ export function __wbg_iterator_e5822695327a3c39() {
     return addHeapObject(ret);
 };
 
+export function __wbg_keys_b4d27b02ad14f4be(arg0) {
+    const ret = Object.keys(getObject(arg0));
+    return addHeapObject(ret);
+};
+
 export function __wbg_length_69bca3cb64fc8748(arg0) {
     const ret = getObject(arg0).length;
     return ret;

package/dist/html_to_markdown_wasm_bg.wasm.d.ts

@@ -1,12 +1,19 @@
 /* tslint:disable */
 /* eslint-disable */
 export const memory: WebAssembly.Memory;
+export const __wbg_wasmconversionoptionshandle_free: (a: number, b: number) => void;
 export const __wbg_wasmhtmlextraction_free: (a: number, b: number) => void;
 export const __wbg_wasminlineimage_free: (a: number, b: number) => void;
 export const __wbg_wasminlineimageconfig_free: (a: number, b: number) => void;
 export const __wbg_wasminlineimagewarning_free: (a: number, b: number) => void;
 export const convert: (a: number, b: number, c: number, d: number) => void;
+export const convertBytes: (a: number, b: number, c: number) => void;
+export const convertBytesWithInlineImages: (a: number, b: number, c: number, d: number) => void;
+export const convertBytesWithOptionsHandle: (a: number, b: number, c: number) => void;
 export const convertWithInlineImages: (a: number, b: number, c: number, d: number, e: number) => void;
+export const convertWithOptionsHandle: (a: number, b: number, c: number, d: number) => void;
+export const createConversionOptionsHandle: (a: number, b: number) => void;
+export const wasmconversionoptionshandle_new: (a: number, b: number) => void;
 export const wasmhtmlextraction_inlineImages: (a: number, b: number) => void;
 export const wasmhtmlextraction_markdown: (a: number, b: number) => void;
 export const wasmhtmlextraction_warnings: (a: number, b: number) => void;

package/dist/package.json

@@ -4,7 +4,7 @@
   "collaborators": [
     "Na'aman Hirschfeld <nhirschfeld@gmail.com>"
   ],
-  "version": "2.6.6",
+  "version": "2.7.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/dist-node/README.md

@@ -89,7 +89,7 @@ const markdown = convert(html, {
 });
 ```
 
-**Performance:** Native bindings average ~19k ops/sec, WASM averages ~16k ops/sec (benchmarked on complex real-world documents).
+**Performance:** The shared fixture harness (`task bench:bindings`) now clocks Node, Python, and the Rust CLI at ~1.3–1.4k ops/sec (≈150 MB/s) on the 129 KB Wikipedia “Lists” page thanks to the new Buffer/Uint8Array fast paths and release-mode harness. Ruby stays close at ~1.2k ops/sec, PHP lands around 0.3k ops/sec (≈35 MB/s), and WASM hits ~0.85k ops/sec—plenty for browsers, Deno, and edge runtimes.
 
 See the JavaScript guides for full API documentation:
 
@@ -146,38 +146,65 @@ Benchmarked on Apple M4 with complex real-world documents (Wikipedia articles, t
 
 ### Operations per Second (higher is better)
 
-| Document Type              | Node.js (NAPI) | WASM   | Python (PyO3) | Speedup (Node vs Python) |
-| -------------------------- | -------------- | ------ | ------------- | ------------------------ |
-| **Small (5 paragraphs)**   | 86,233         | 70,300 | 8,443         | **10.2×**                |
-| **Medium (25 paragraphs)** | 18,979         | 15,282 | 1,846         | **10.3×**                |
-| **Large (100 paragraphs)** | 4,907          | 3,836  | 438           | **11.2×**                |
-| **Tables (complex)**       | 5,003          | 3,748  | 4,829         | 1.0×                     |
-| **Lists (nested)**         | 1,819          | 1,391  | 1,165         | **1.6×**                 |
-| **Wikipedia (129KB)**      | 1,125          | 1,022  | -             | -                        |
-| **Wikipedia (653KB)**      | 156            | 147    | -             | -                        |
+Derived directly from `tools/runtime-bench/results/latest.json` (Apple M4, shared fixtures):
+
+| Fixture                | Node.js (NAPI) | WASM | Python (PyO3) | Speedup (Node vs Python) |
+| ---------------------- | -------------- | ---- | ------------- | ------------------------ |
+| **Lists (Timeline)**   | 1,308          | 882  | 1,405         | **0.9×**                 |
+| **Tables (Countries)** | 331            | 242  | 352           | **0.9×**                 |
+| **Medium (Python)**    | 150            | 121  | 158           | **1.0×**                 |
+| **Large (Rust)**       | 163            | 124  | 183           | **0.9×**                 |
+| **Small (Intro)**      | 208            | 163  | 223           | **0.9×**                 |
+| **HOCR German PDF**    | 2,944          | 1,637| 2,991         | **1.0×**                 |
+| **HOCR Invoice**       | 27,326         | 7,775| 23,500        | **1.2×**                 |
+| **HOCR Tables**        | 3,475          | 1,667| 3,464         | **1.0×**                 |
 
 ### Average Performance Summary
 
-| Implementation        | Avg ops/sec      | vs WASM      | vs Python       | Best For                          |
-| --------------------- | ---------------- | ------------ | --------------- | --------------------------------- |
-| **Node.js (NAPI-RS)** | **18,162**       | 1.17× faster | **7.4× faster** | Maximum throughput in Node.js/Bun |
-| **WebAssembly**       | **15,536**       | baseline     | **6.3× faster** | Universal (Deno, browsers, edge)  |
-| **Python (PyO3)**     | **2,465**        | 6.3× slower  | baseline        | Python ecosystem integration      |
-| **Rust CLI/Binary**   | **150-210 MB/s** | -            | -               | Standalone processing             |
+| Implementation        | Avg ops/sec (fixtures) | vs Python | Notes |
+| --------------------- | ---------------------- | --------- | ----- |
+| **Rust CLI/Binary**   | **4,996**              | **1.2× faster** | Preprocessing now stays in one pass + reuses `parse_owned`, so the CLI leads every fixture |
+| **Node.js (NAPI-RS)** | **4,488**              | 1.0×      | Buffer/handle combo keeps Node within ~10 % of the Rust core while serving JS runtimes |
+| **Ruby (magnus)**     | **4,278**              | 0.9×      | Still extremely fast; ~25 k ops/sec on HOCR invoices without extra work |
+| **Python (PyO3)**     | **4,034**              | baseline  | Release-mode harness plus handle reuse keep it competitive, but it now trails Node/Rust |
+| **WebAssembly**       | **1,576**              | 0.4×      | Portable option for Deno/browsers/edge using the new byte APIs |
+| **PHP (ext)**         | **1,480**              | 0.4×      | Composer extension holds steady at 35–70 MB/s once the PIE build is installed |
 
 ### Key Insights
 
-- **JavaScript bindings are fastest**: Native Node.js bindings achieve ~18k ops/sec average, with WASM close behind at ~16k ops/sec
-- **Python is 6-10× slower**: Despite using the same Rust core, PyO3 FFI overhead significantly impacts Python performance
-- **Small documents**: Both JS implementations reach 70-90k ops/sec on simple HTML
-- **Large documents**: Performance gap widens with complexity
+- **Rust now leads throughput**: the fused preprocessing + `parse_owned` pathway pushes the CLI to ~1.7 k ops/sec on the 129 KB lists page and ~31 k ops/sec on the HOCR invoice fixture.
+- **Node.js trails by only a few percent** after the buffer/handle work—~1.3 k ops/sec on the lists fixture and 27 k ops/sec on HOCR invoices without any UTF-16 copies.
+- **Python remains competitive** but now sits below Node/Rust (~4.0 k average ops/sec); stick to the v2 API to avoid the deprecated compatibility shim.
+- **PHP and WASM stay in the 35–70 MB/s band**, which is plenty for Composer queues or edge runtimes as long as the extension/module is built ahead of time.
+- **Rust CLI results now mirror the bindings**, since `task bench:bindings` runs the harness with `cargo run --release` by default—profile there, then push optimizations down into each FFI layer.
+
+### Runtime Benchmarks (PHP / Ruby / Python / Node / WASM)
+
+Measured on Apple M4 using the fixture-driven runtime harness in `tools/runtime-bench` (`task bench:bindings`). Every binding consumes the exact same HTML fixtures and hOCR samples from `test_documents/`:
+
+| Document            | Size     | Ruby ops/sec | PHP ops/sec | Python ops/sec | Node ops/sec | WASM ops/sec | Rust ops/sec |
+| ------------------- | -------- | ------------ | ----------- | -------------- | ------------ | ------------ | ------------ |
+| Lists (Timeline)    | 129 KB   | 1,349        | 533         | 1,405          | 1,308        | 882          | **1,700**    |
+| Tables (Countries)  | 360 KB   | 326          | 118         | 352            | 331          | 242          | **416**      |
+| Medium (Python)     | 657 KB   | 157          | 59          | 158            | 150          | 121          | **190**      |
+| Large (Rust)        | 567 KB   | 174          | 65          | 183            | 163          | 124          | **220**      |
+| Small (Intro)       | 463 KB   | 214          | 83          | 223            | 208          | 163          | **258**      |
+| HOCR German PDF     | 44 KB    | 2,936        | 1,007       | **2,991**      | 2,944        | 1,637        | 2,760        |
+| HOCR Invoice        | 4 KB     | 25,740       | 8,781       | 23,500         | 27,326       | 7,775        | **31,345**   |
+| HOCR Embedded Tables| 37 KB    | 3,328        | 1,194       | 3,464          | **3,475**    | 1,667        | 3,080        |
+
+The harness shells out to each runtime’s lightweight benchmark driver (`packages/*/bin/benchmark.*`, `crates/*/bin/benchmark.ts`), feeds fixtures defined in `tools/runtime-bench/fixtures/*.toml`, and writes machine-readable JSON reports (`tools/runtime-bench/results/latest.json`) for regression tracking. Add new languages or scenarios by extending those fixture files and drivers.
+
+Use `task bench:bindings` to regenerate throughput numbers across all bindings or `task bench:bindings:profile` to capture CPU/memory samples while the benchmarks run. To focus on specific languages or fixtures, pass `--language` / `--fixture` directly to `cargo run --manifest-path tools/runtime-bench/Cargo.toml -- …`.
+
+Need a call-stack view of the Rust core? Run `task flamegraph:rust` (or call the harness with `--language rust --flamegraph path.svg`) to profile a fixture and dump a ready-to-inspect flamegraph in `tools/runtime-bench/results/`.
 
 **Note on Python performance**: The current Python bindings have optimization opportunities. The v2 API with direct `convert()` calls performs best; avoid the v1 compatibility layer for performance-critical applications.
 
 ## Compatibility (v1 → v2)
 
 - V2’s Rust core sustains **150–210 MB/s** throughput; V1 averaged **≈ 2.5 MB/s** in its Python/BeautifulSoup implementation (60–80× faster).
-- The Python package offers a compatibility shim in `html_to_markdown.v1_compat` (`convert_to_markdown`, `convert_to_markdown_stream`, `markdownify`). Details and keyword mappings live in [Python README](https://github.com/Goldziher/html-to-markdown/blob/main/packages/python/README.md#v1-compatibility).
+- The Python package offers a compatibility shim in `html_to_markdown.v1_compat` (`convert_to_markdown`, `convert_to_markdown_stream`, `markdownify`). The shim is deprecated, emits `DeprecationWarning` on every call, and will be removed in v3.0—plan migrations now. Details and keyword mappings live in [Python README](https://github.com/Goldziher/html-to-markdown/blob/main/packages/python/README.md#v1-compatibility).
 - CLI flag changes, option renames, and other breaking updates are summarised in [CHANGELOG](https://github.com/Goldziher/html-to-markdown/blob/main/CHANGELOG.md#breaking-changes).
 
 ## Community