@kreuzberg/html-to-markdown-wasm 2.29.0 → 3.0.0

package/README.md

@@ -17,63 +17,9 @@ Runs anywhere: Node.js, Deno, Bun, browsers, and edge runtimes.
 [![RubyGems](https://badge.fury.io/rb/html-to-markdown.svg)](https://rubygems.org/gems/html-to-markdown)
 [![NuGet](https://img.shields.io/nuget/v/KreuzbergDev.HtmlToMarkdown.svg)](https://www.nuget.org/packages/KreuzbergDev.HtmlToMarkdown/)
 [![Maven Central](https://img.shields.io/maven-central/v/dev.kreuzberg/html-to-markdown.svg)](https://central.sonatype.com/artifact/dev.kreuzberg/html-to-markdown)
-[![Go Reference](https://pkg.go.dev/badge/github.com/kreuzberg-dev/html-to-markdown/packages/go/v2/htmltomarkdown.svg)](https://pkg.go.dev/github.com/kreuzberg-dev/html-to-markdown/packages/go/v2/htmltomarkdown)
+[![Go Reference](https://pkg.go.dev/badge/github.com/kreuzberg-dev/html-to-markdown/packages/go/v3/htmltomarkdown.svg)](https://pkg.go.dev/github.com/kreuzberg-dev/html-to-markdown/packages/go/v3/htmltomarkdown)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/kreuzberg-dev/html-to-markdown/blob/main/LICENSE)
 
-## Migration Guide (v2.18.x → v2.19.0)
-
-> **⚠️ BREAKING CHANGE: Package Namespace Update**
->
-> In v2.19.0, the npm package namespace changed from `html-to-markdown-wasm` to `@kreuzberg/html-to-markdown-wasm` to reflect the new Kreuzberg.dev organization.
-
-### Install Updated Package
-
-**Before (v2.18.x):**
-```bash
-npm install html-to-markdown-wasm
-```
-
-**After (v2.19.0+):**
-```bash
-npm install @kreuzberg/html-to-markdown-wasm
-```
-
-### Update Import Statements
-
-**Before:**
-```typescript
-import { convert } from 'html-to-markdown-wasm';
-// or
-import { convert } from "npm:html-to-markdown-wasm";  // Deno
-```
-
-**After:**
-```typescript
-import { convert } from '@kreuzberg/html-to-markdown-wasm';
-// or
-import { convert } from "npm:@kreuzberg/html-to-markdown-wasm";  // Deno
-```
-
-### Update Browser ESM Imports
-
-**Before:**
-```javascript
-import init, { convert } from 'https://unpkg.com/html-to-markdown-wasm/dist-web/html_to_markdown_wasm.js';
-```
-
-**After:**
-```javascript
-import init, { convert } from 'https://unpkg.com/@kreuzberg/html-to-markdown-wasm/dist-web/html_to_markdown_wasm.js';
-```
-
-### Summary of Changes
-
-- Package renamed from `html-to-markdown-wasm` to `@kreuzberg/html-to-markdown-wasm`
-- All APIs remain identical
-- Full backward compatibility after updating package name and imports
-
----
-
 ## Performance
 
 Universal WebAssembly bindings with **excellent performance** across all JavaScript runtimes.
@@ -94,8 +40,8 @@ Universal WebAssembly bindings with **excellent performance** across all JavaScr
 
 ### Comparison
 
-- **vs Native NAPI**: ~1.17× slower (WASM has minimal overhead)
-- **vs Python**: ~6.3× faster (no FFI overhead)
+- **vs Native NAPI**: ~1.17x slower (WASM has minimal overhead)
+- **vs Python**: ~6.3x faster (no FFI overhead)
 - **Best for**: Universal deployment (browsers, Deno, edge runtimes, cross-platform apps)
 
 ### Benchmark Fixtures (Apple M4)
@@ -109,9 +55,6 @@ Numbers captured via the shared fixture harness in `tools/benchmark-harness`:
 | Medium (Python)        | 657 KB | 121            |
 | Large (Rust)           | 567 KB | 124            |
 | Small (Intro)          | 463 KB | 163            |
-| hOCR German PDF        | 44 KB  | 1,637          |
-| hOCR Invoice           | 4 KB   | 7,775          |
-| hOCR Embedded Tables   | 37 KB  | 1,667          |
 
 > Expect slightly higher numbers in long-lived browser/Deno workers once the WASM module is warm.
 
@@ -142,8 +85,8 @@ import { convert } from "npm:@kreuzberg/html-to-markdown-wasm";
 import { convert } from '@kreuzberg/html-to-markdown-wasm';
 
 const html = '<h1>Hello World</h1><p>This is <strong>fast</strong>!</p>';
-const markdown = convert(html);
-console.log(markdown);
+const result = convert(html);
+console.log(result.content);
 // # Hello World
 //
 // This is **fast**!
@@ -151,45 +94,34 @@ console.log(markdown);
 
 > **Heads up for edge runtimes:** Cloudflare Workers, Vite dev servers, and other environments that instantiate `.wasm` files asynchronously must call `await initWasm()` (or `await wasmReady`) once during startup before invoking `convert`. Traditional bundlers (Webpack, Rollup) and Deno/Node imports continue to work without manual initialization.
 
-**Working Examples:**
-- [**Browser with Rollup**](https://github.com/kreuzberg-dev/html-to-markdown/tree/main/examples/wasm-rollup) - Using dist-web target in browser
-- [**Node.js**](https://github.com/kreuzberg-dev/html-to-markdown/tree/main/examples/wasm-node) - Using dist-node target
-- [**Cloudflare Workers**](https://github.com/kreuzberg-dev/html-to-markdown/tree/main/examples/wasm-cloudflare) - Using bundler target with Wrangler
+### WasmConversionResult Fields
 
-### Reusing Options Handles
+Every call to `convert()` returns a `WasmConversionResult` object with six fields:
 
-```ts
-import {
-  convertWithOptionsHandle,
-  createConversionOptionsHandle,
-} from '@kreuzberg/html-to-markdown-wasm';
+```typescript
+import { convert } from '@kreuzberg/html-to-markdown-wasm';
+
+const result = convert(html);
 
-const handle = createConversionOptionsHandle({ hocrSpatialTables: false });
-const markdown = convertWithOptionsHandle('<h1>Reusable</h1>', handle);
+result.content;   // string | null  -- converted Markdown (or djot/plain text)
+result.document;  // string | null  -- structured document tree as JSON
+result.metadata;  // string | null  -- extracted HTML metadata as JSON
+result.tables;    // Array          -- all tables found in document order
+result.images;    // Array          -- extracted inline images (data URIs, SVGs)
+result.warnings;  // Array          -- non-fatal processing warnings
 ```
 
 ### 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:
+When you already have raw bytes (e.g., `fs.readFileSync`, Fetch API responses), skip re-encoding with `TextDecoder` by calling the byte-friendly helper:
 
 ```ts
-import {
-  convertBytes,
-  convertBytesWithOptionsHandle,
-  createConversionOptionsHandle,
-  convertBytesWithInlineImages,
-} from '@kreuzberg/html-to-markdown-wasm';
+import { convertBytes } from '@kreuzberg/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,
-});
+const result = convertBytes(htmlBytes);
+console.log(result.content);
 ```
 
 ### With Options
@@ -197,7 +129,7 @@ const inlineExtraction = convertBytesWithInlineImages(htmlBytes, null, {
 ```typescript
 import { convert } from '@kreuzberg/html-to-markdown-wasm';
 
-const markdown = convert(html, {
+const result = convert(html, {
   headingStyle: 'atx',
   codeBlockStyle: 'backticks',
   listIndentWidth: 2,
@@ -205,9 +137,10 @@ const markdown = convert(html, {
   wrap: true,
   wrapWidth: 80
 });
+console.log(result.content);
 ```
 
-### Preserve Complex HTML (NEW in v2.5)
+### Preserve Complex HTML
 
 ```typescript
 import { convert } from '@kreuzberg/html-to-markdown-wasm';
@@ -220,22 +153,23 @@ const html = `
 </table>
 `;
 
-const markdown = convert(html, {
+const result = convert(html, {
   preserveTags: ['table'] // Keep tables as HTML
 });
+console.log(result.content);
 ```
 
 ### Deno
 
 ```typescript
-import { convert } from "npm:html-to-markdown-wasm";
+import { convert } from "npm:@kreuzberg/html-to-markdown-wasm";
 
 const html = await Deno.readTextFile("input.html");
-const markdown = convert(html, { headingStyle: "atx" });
-await Deno.writeTextFile("output.md", markdown);
+const result = convert(html, { headingStyle: "atx" });
+await Deno.writeTextFile("output.md", result.content ?? "");
 ```
 
-> **Performance Tip:** For Node.js/Bun, use [@kreuzberg/html-to-markdown-node](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-node) for 1.17× better performance with native bindings.
+> **Performance Tip:** For Node.js/Bun, use [@kreuzberg/html-to-markdown-node](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-node) for 1.17x better performance with native bindings.
 
 ### Browser (ESM)
 
@@ -253,10 +187,10 @@ await Deno.writeTextFile("output.md", markdown);
     await init();
 
     const html = '<h1>Hello World</h1><p>This runs in the <strong>browser</strong>!</p>';
-    const markdown = convert(html, { headingStyle: 'atx' });
+    const result = convert(html, { headingStyle: 'atx' });
 
-    console.log(markdown);
-    document.body.innerHTML = `<pre>${markdown}</pre>`;
+    console.log(result.content);
+    document.body.innerHTML = `<pre>${result.content}</pre>`;
   </script>
 </body>
 </html>
@@ -267,10 +201,11 @@ await Deno.writeTextFile("output.md", markdown);
 ```typescript
 import { convert } from '@kreuzberg/html-to-markdown-wasm';
 
-const markdown = convert('<h1>Hello</h1>', {
+const result = convert('<h1>Hello</h1>', {
   headingStyle: 'atx',
   codeBlockStyle: 'backticks'
 });
+console.log(result.content);
 ```
 
 ### Cloudflare Workers
@@ -286,28 +221,22 @@ export default {
   async fetch(request: Request): Promise<Response> {
     await ready;
     const html = await request.text();
-    const markdown = convert(html, { headingStyle: 'atx' });
+    const result = convert(html, { headingStyle: 'atx' });
 
-    return new Response(markdown, {
+    return new Response(result.content ?? "", {
       headers: { 'Content-Type': 'text/markdown' }
     });
   }
 };
 ```
 
-> See the full [Cloudflare Workers example](https://github.com/kreuzberg-dev/html-to-markdown/tree/main/examples/wasm-cloudflare) with Wrangler configuration.
 
 ## TypeScript
 
 Full TypeScript support with type definitions:
 
 ```typescript
-import {
-  convert,
-  convertWithInlineImages,
-  WasmInlineImageConfig,
-  type WasmConversionOptions
-} from '@kreuzberg/html-to-markdown-wasm';
+import { convert, type WasmConversionOptions } from '@kreuzberg/html-to-markdown-wasm';
 
 const options: WasmConversionOptions = {
   headingStyle: 'atx',
@@ -317,40 +246,16 @@ const options: WasmConversionOptions = {
   wrapWidth: 80
 };
 
-const markdown = convert('<h1>Hello</h1>', options);
+const result = convert('<h1>Hello</h1>', options);
+console.log(result.content);
 ```
 
-## Inline Images
+## Metadata and Tables
 
-Extract and decode inline images (data URIs, SVG):
+Extract document metadata and structured tables from the conversion result:
 
 ```typescript
-import { convertWithInlineImages, WasmInlineImageConfig } from '@kreuzberg/html-to-markdown-wasm';
-
-const html = '<img src="data:image/png;base64,iVBORw0..." alt="Logo">';
-
-const config = new WasmInlineImageConfig(5 * 1024 * 1024); // 5MB max
-config.inferDimensions = true;
-config.filenamePrefix = 'img_';
-config.captureSvg = true;
-
-const result = convertWithInlineImages(html, null, config);
-
-console.log(result.markdown);
-console.log(`Extracted ${result.inlineImages.length} images`);
-
-for (const img of result.inlineImages) {
-  console.log(`${img.filename}: ${img.format}, ${img.data.length} bytes`);
-  // img.data is a Uint8Array - save to file or upload
-}
-```
-
-## Metadata Extraction
-
-Extract document metadata (headers, links, images, structured data) alongside Markdown conversion:
-
-```typescript
-import { convertWithMetadata, WasmMetadataConfig } from '@kreuzberg/html-to-markdown-wasm';
+import { convert } from '@kreuzberg/html-to-markdown-wasm';
 
 const html = `
   <html lang="en">
@@ -359,97 +264,23 @@ const html = `
       <h1>Main Title</h1>
       <p>Content with <a href="https://example.com">a link</a></p>
       <img src="https://example.com/image.jpg" alt="Example image">
+      <table>
+        <tr><th>Name</th><th>Value</th></tr>
+        <tr><td>Foo</td><td>42</td></tr>
+      </table>
     </body>
   </html>
 `;
 
-const config = new WasmMetadataConfig();
-config.extractHeaders = true;
-config.extractLinks = true;
-config.extractImages = true;
-config.extractStructuredData = true;
-config.maxStructuredDataSize = 1_000_000; // 1MB limit
-
-const result = convertWithMetadata(html, null, config);
-
-console.log(result.markdown);
-console.log('Document metadata:', result.metadata.document);
-// {
-//   title: 'My Article',
-//   language: 'en',
-//   ...
-// }
-
-console.log('Headers:', result.metadata.headers);
-// [
-//   { level: 1, text: 'Main Title', id: undefined, depth: 0, htmlOffset: ... }
-// ]
-
-console.log('Links:', result.metadata.links);
-// [
-//   {
-//     href: 'https://example.com',
-//     text: 'a link',
-//     linkType: 'external',
-//     rel: [],
-//     ...
-//   }
-// ]
-
-console.log('Images:', result.metadata.images);
-// [
-//   {
-//     src: 'https://example.com/image.jpg',
-//     alt: 'Example image',
-//     imageType: 'external',
-//     ...
-//   }
-// ]
-```
-
-### Metadata Configuration
-
-The `WasmMetadataConfig` class controls what metadata is extracted:
-
-```typescript
-import { WasmMetadataConfig } from '@kreuzberg/html-to-markdown-wasm';
-
-const config = new WasmMetadataConfig();
-
-// Enable/disable extraction types
-config.extractHeaders = true;              // h1-h6 elements
-config.extractLinks = true;                // <a> elements with link type classification
-config.extractImages = true;               // <img> and <svg> elements
-config.extractStructuredData = true;       // JSON-LD, Microdata, RDFa
-
-// Limit structured data size to prevent memory exhaustion
-config.maxStructuredDataSize = 1_000_000;  // 1MB default
-```
-
-### Metadata Structure
-
-The returned metadata object includes:
-
-- **document**: Document-level metadata (title, description, keywords, language, OG tags, Twitter cards, etc.)
-- **headers**: Array of header elements with level, text, id, and document position
-- **links**: Array of links with href, text, type (anchor/internal/external/email/phone), and rel attributes
-- **images**: Array of images with src, alt text, dimensions, and type classification (dataUri/external/relative/svg)
-- **structuredData**: Array of JSON-LD, Microdata, and RDFa blocks
-
-### Byte-Based Input
-
-Convert bytes directly with metadata extraction:
-
-```typescript
-import { convertBytesWithMetadata, WasmMetadataConfig } from '@kreuzberg/html-to-markdown-wasm';
-import { readFileSync } from 'node:fs';
-
-const htmlBytes = readFileSync('article.html');
-const config = new WasmMetadataConfig();
+const result = convert(html, {
+  extractMetadata: true,
+});
 
-const result = convertBytesWithMetadata(htmlBytes, null, config);
-console.log(result.markdown);
-console.log(result.metadata);
+console.log(result.content);            // Markdown output
+console.log(result.metadata);           // JSON string with title, links, headers, etc.
+console.log(result.tables.length);      // Number of tables found
+console.log(result.images.length);      // Number of inline images extracted
+console.log(result.warnings);           // Any processing warnings
 ```
 
 ## Build Targets
@@ -466,33 +297,33 @@ Three build targets are provided for different environments:
 
 | Runtime                   | Support                      | Package        |
 | ------------------------- | ---------------------------- | -------------- |
-| ✅ **Node.js** 18+        | Full support                 | `dist-node`    |
-| ✅ **Deno**               | Full support                 | npm: specifier |
-| ✅ **Bun**                | Full support (prefer native) | Default export |
-| ✅ **Browsers**           | Full support                 | `dist-web`     |
-| ✅ **Cloudflare Workers** | Full support                 | Default export |
-| ✅ **Deno Deploy**        | Full support                 | npm: specifier |
+| **Node.js** 18+           | Full support                 | `dist-node`    |
+| **Deno**                  | Full support                 | npm: specifier |
+| **Bun**                   | Full support (prefer native) | Default export |
+| **Browsers**              | Full support                 | `dist-web`     |
+| **Cloudflare Workers**    | Full support                 | Default export |
+| **Deno Deploy**           | Full support                 | npm: specifier |
 
 ## When to Use
 
 Choose `@kreuzberg/html-to-markdown-wasm` when:
 
-- 🌐 Running in browsers or edge runtimes
-- 🦕 Using Deno
-- ☁️ Deploying to Cloudflare Workers, Deno Deploy
-- 📦 Building universal libraries
-- 🔄 Need consistent behavior across all platforms
+- Running in browsers or edge runtimes
+- Using Deno
+- Deploying to Cloudflare Workers, Deno Deploy
+- Building universal libraries
+- Need consistent behavior across all platforms
 
 Use [@kreuzberg/html-to-markdown-node](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-node) for:
 
-- ⚡ Maximum performance in Node.js/Bun (~3× faster)
-- 🖥️ Server-side only applications
+- Maximum performance in Node.js/Bun (~3x faster)
+- Server-side only applications
 
 ## Visitor Pattern Support
 
 **The WebAssembly binding does not support the visitor pattern.** The visitor pattern requires callbacks and stateful execution across the WebAssembly/JavaScript boundary, which has fundamental limitations:
 
-### Why WASM Doesn't Support Visitors
+### Why WASM Does Not Support Visitors
 
 1. **Memory safety across FFI boundary**: The WASM/JS boundary cannot safely pass mutable function callbacks that maintain state across multiple invocations
 2. **Single-threaded execution model**: WASM runs on a single thread with no equivalent to Node.js's `ThreadsafeFunction` FFI primitive
@@ -504,10 +335,11 @@ Use [@kreuzberg/html-to-markdown-node](https://www.npmjs.com/package/@kreuzberg/
 Choose one of these approaches:
 
 #### 1. Use Node.js Binding (Recommended)
+
 For best performance with visitor support, use the native Node.js binding:
 
 ```typescript
-import { convertWithVisitor, type Visitor } from '@kreuzberg/html-to-markdown-node';
+import { convert, type Visitor } from '@kreuzberg/html-to-markdown-node';
 
 const visitor: Visitor = {
   visitLink(ctx, href, text, title) {
@@ -516,28 +348,32 @@ const visitor: Visitor = {
   },
 };
 
-const markdown = convertWithVisitor(html, { visitor });
+const result = convert(html, undefined, visitor);
+console.log(result.content);
 ```
 
-**Performance:** ~3× faster than WASM, full visitor pattern support.
+**Performance:** ~3x faster than WASM, full visitor pattern support.
 **Use when:** Running on Node.js or Bun server-side.
 
 #### 2. Use Server-Side Bindings
+
 For other platforms, use Python, Ruby, or PHP bindings with visitor support:
 
 **Python:**
+
 ```python
-from html_to_markdown import convert_with_visitor
+from html_to_markdown import convert
 
 class MyVisitor:
     def visit_link(self, ctx, href, text, title):
         # Your visitor logic here
         return {"type": "continue"}
 
-markdown = convert_with_visitor(html, visitor=MyVisitor())
+result = convert(html, None, MyVisitor())
 ```
 
 **Ruby:**
+
 ```ruby
 require 'html_to_markdown'
 
@@ -547,10 +383,11 @@ class MyVisitor
   end
 end
 
-markdown = HtmlToMarkdown.convert_with_visitor(html, visitor: MyVisitor.new)
+result = HtmlToMarkdown.convert(html, nil, MyVisitor.new)
 ```
 
 **PHP:**
+
 ```php
 use HtmlToMarkdown\Converter;
 
@@ -560,10 +397,11 @@ class MyVisitor {
     }
 }
 
-$markdown = Converter::convertWithVisitor($html, new MyVisitor());
+$result = Converter::convert($html, null, new MyVisitor());
 ```
 
 #### 3. Preprocess HTML Before Conversion
+
 For simple transformations, manipulate the HTML before passing to WASM:
 
 ```typescript
@@ -575,18 +413,20 @@ const processedHtml = html.replace(
   'https://new-cdn.com'
 );
 
-const markdown = convert(processedHtml);
+const result = convert(processedHtml);
+console.log(result.content);
 ```
 
 **Use when:** Only simple text replacements are needed.
 
 #### 4. Post-Process Markdown
+
 Transform the output Markdown after conversion:
 
 ```typescript
 import { convert } from '@kreuzberg/html-to-markdown-wasm';
 
-const markdown = convert(html);
+const markdown = convert(html).content ?? "";
 
 // Post-process the markdown
 const transformed = markdown
@@ -600,30 +440,30 @@ const transformed = markdown
 
 | Binding | Visitor Support | Best For |
 |---------|-----------------|----------|
-| **Rust** | ✅ Yes | Core library, performance-critical code |
-| **Python** | ✅ Yes (sync & async) | Server-side, bulk processing |
-| **TypeScript/Node.js** | ✅ Yes (sync & async) | Server-side Node.js/Bun, best performance |
-| **Ruby** | ✅ Yes | Server-side Ruby on Rails, Sinatra |
-| **PHP** | ✅ Yes | Server-side PHP, content management |
-| **Go** | ❌ No | Basic conversion only |
-| **Java** | ❌ No | Basic conversion only |
-| **C#** | ❌ No | Basic conversion only |
-| **Elixir** | ❌ No | Basic conversion only |
-| **WebAssembly** | ❌ No | Browser, Edge, Deno (see alternatives above) |
-
-For comprehensive visitor pattern documentation with examples, see [Visitor Pattern Guide](../../examples/visitor-pattern/).
+| **Rust** | Yes | Core library, performance-critical code |
+| **Python** | Yes (sync and async) | Server-side, bulk processing |
+| **TypeScript/Node.js** | Yes (sync and async) | Server-side Node.js/Bun, best performance |
+| **Ruby** | Yes | Server-side Ruby on Rails, Sinatra |
+| **PHP** | Yes | Server-side PHP, content management |
+| **Go** | No | Basic conversion only |
+| **Java** | No | Basic conversion only |
+| **C#** | No | Basic conversion only |
+| **Elixir** | No | Basic conversion only |
+| **WebAssembly** | No | Browser, Edge, Deno (see alternatives above) |
+
+For comprehensive visitor pattern documentation with examples, see the [full documentation](https://docs.html-to-markdown.kreuzberg.dev).
 
 ## Configuration Options
 
-See the [TypeScript definitions](./dist-node/html_to_markdown_wasm.d.ts) for all available options:
+Available options:
 
 - Heading styles (atx, underlined, atxClosed)
 - Code block styles (indented, backticks, tildes)
 - List formatting (indent width, bullet characters)
 - Text escaping and formatting
 - Tag preservation (`preserveTags`) and stripping (`stripTags`)
+- Metadata extraction (`extractMetadata`)
 - Preprocessing for web scraping
-- hOCR table extraction
 - And more...
 
 ## Examples
@@ -644,35 +484,36 @@ const html = `
 <p>After table</p>
 `;
 
-const markdown = convert(html, {
+const result = convert(html, {
   preserveTags: ['table']
 });
 
-// Result includes the table as HTML
+// result.content includes the table as HTML
 ```
 
 Combine with `stripTags`:
 
 ```typescript
-const markdown = convert(html, {
+const result = convert(html, {
   preserveTags: ['table', 'form'],  // Keep as HTML
   stripTags: ['script', 'style']    // Remove entirely
 });
+console.log(result.content);
 ```
 
 ### Deno Web Server
 
 ```typescript
-import { convert } from "npm:html-to-markdown-wasm";
+import { convert } from "npm:@kreuzberg/html-to-markdown-wasm";
 
-Deno.serve((req) => {
+Deno.serve(async (req) => {
   const url = new URL(req.url);
 
   if (url.pathname === "/convert" && req.method === "POST") {
     const html = await req.text();
-    const markdown = convert(html, { headingStyle: "atx" });
+    const result = convert(html, { headingStyle: "atx" });
 
-    return new Response(markdown, {
+    return new Response(result.content ?? "", {
       headers: { "Content-Type": "text/markdown" }
     });
   }
@@ -696,8 +537,8 @@ Deno.serve((req) => {
   window.convertFile = async () => {
     const file = document.getElementById('htmlFile').files[0];
     const html = await file.text();
-    const markdown = convert(html, { headingStyle: 'atx' });
-    document.getElementById('output').textContent = markdown;
+    const result = convert(html, { headingStyle: 'atx' });
+    document.getElementById('output').textContent = result.content ?? "";
   };
 </script>
 ```
@@ -705,42 +546,39 @@ Deno.serve((req) => {
 ### Web Scraping (Deno)
 
 ```typescript
-import { convert } from "npm:html-to-markdown-wasm";
+import { convert } from "npm:@kreuzberg/html-to-markdown-wasm";
 
 const response = await fetch("https://example.com");
 const html = await response.text();
 
-const markdown = convert(html, {
-  preprocessing: {
-    enabled: true,
-    preset: "aggressive",
-    removeNavigation: true,
-    removeForms: true
-  },
+const result = convert(html, {
+  preprocess: true,
+  preset: "aggressive",
+  keepNavigation: false,
   headingStyle: "atx",
   codeBlockStyle: "backticks"
 });
 
-console.log(markdown);
+console.log(result.content);
 ```
 
 ## Other Runtimes
 
 The same Rust engine ships as native bindings for other ecosystems:
 
-- 🖥️ Node.js / Bun: [`html-to-markdown-node`](https://www.npmjs.com/package/html-to-markdown-node)
-- 🐍 Python: [`html-to-markdown`](https://pypi.org/project/html-to-markdown/)
-- 💎 Ruby: [`html-to-markdown`](https://rubygems.org/gems/html-to-markdown)
-- 🐘 PHP: [`kreuzberg-dev/html-to-markdown`](https://packagist.org/packages/kreuzberg-dev/html-to-markdown)
-- 🦀 Rust crate & CLI: [`html-to-markdown-rs`](https://crates.io/crates/html-to-markdown-rs)
+- Node.js / Bun: [`@kreuzberg/html-to-markdown-node`](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-node)
+- Python: [`html-to-markdown`](https://pypi.org/project/html-to-markdown/)
+- Ruby: [`html-to-markdown`](https://rubygems.org/gems/html-to-markdown)
+- PHP: [`kreuzberg-dev/html-to-markdown`](https://packagist.org/packages/kreuzberg-dev/html-to-markdown)
+- Rust crate and CLI: [`html-to-markdown-rs`](https://crates.io/crates/html-to-markdown-rs)
 
 ## Links
 
 - [GitHub Repository](https://github.com/kreuzberg-dev/html-to-markdown)
 - [Full Documentation](https://github.com/kreuzberg-dev/html-to-markdown/blob/main/README.md)
-- [Native Node Package](https://www.npmjs.com/package/html-to-markdown-node)
+- [Native Node Package](https://www.npmjs.com/package/@kreuzberg/html-to-markdown-node)
 - [Python Package](https://pypi.org/project/html-to-markdown/)
-- [PHP Extension & Helpers](https://packagist.org/packages/kreuzberg-dev/html-to-markdown)
+- [PHP Extension and Helpers](https://packagist.org/packages/kreuzberg-dev/html-to-markdown)
 - [Rust Crate](https://crates.io/crates/html-to-markdown-rs)
 
 ## License