### CDN Usage Example

Source: https://github.com/jsv4/docxodus/blob/main/docs/npm-package.md

Demonstrates how to use Docxodus directly from a Content Delivery Network (CDN) without needing to install it via npm, including initialization and document conversion.

```APIDOC
## CDN Usage

### Description
Docxodus can be used directly from a CDN, eliminating the need for local installation.

### Usage
```html
<script type="module">
  import { initialize, convertDocxToHtml, CommentRenderMode } from 'https://cdn.jsdelivr.net/npm/docxodus@latest/dist/index.js';

  await initialize();

  const response = await fetch('document.docx');
  const docxBytes = new Uint8Array(await response.arrayBuffer());

  const html = await convertDocxToHtml(docxBytes, {
    commentRenderMode: CommentRenderMode.EndnoteStyle
  });

  document.getElementById('content').innerHTML = html;
</script>
```

### Available Functions via CDN
- `initialize()`: Initializes the Docxodus library.
- `convertDocxToHtml(docxBytes: Uint8Array, options?: object)`: Converts DOCX bytes to HTML.
- `CommentRenderMode`: Enum for specifying comment rendering style.
```

--------------------------------

### Install docx2html Tool

Source: https://github.com/jsv4/docxodus/blob/main/tools/docx2html/README.md

Installs the docx2html .NET global tool. This command is required before using the tool.

```bash
dotnet tool install -g Docx2Html
```

--------------------------------

### Install Docxodus Library

Source: https://github.com/jsv4/docxodus/blob/main/README.md

Install the Docxodus library using the .NET CLI. This command adds the package to your project.

```bash
dotnet add package Docxodus
```

--------------------------------

### Install Redline as a .NET Global Tool

Source: https://github.com/jsv4/docxodus/blob/main/tools/redline/README.md

Use this command to install the Redline tool globally on your system. Ensure you have the .NET SDK installed.

```bash
dotnet tool install --global Redline
```

--------------------------------

### Install and Use Redline CLI for DOCX Comparison

Source: https://context7.com/jsv4/docxodus/llms.txt

Compares two DOCX files and writes a redlined DOCX. Installs as a global .NET tool. Custom author names and help are supported.

```bash
# Install globally
dotnet tool install -g Redline

# Basic comparison
redline original.docx modified.docx output.docx

# With a custom author name
redline original.docx modified.docx output.docx --author="Legal Review"

# Show help
redline --help
```

--------------------------------

### Install Docx2Html CLI Tool

Source: https://github.com/jsv4/docxodus/blob/main/README.md

Install the Docx2Html command-line tool globally using the .NET CLI. This tool converts DOCX files to HTML.

```bash
# Install globally
dotnet tool install -g Docx2Html
```

--------------------------------

### Install Docxodus npm Package

Source: https://github.com/jsv4/docxodus/blob/main/README.md

Install the Docxodus npm package for client-side usage in browsers via WebAssembly.

```bash
npm install docxodus
```

--------------------------------

### Setup and Run Playwright Browser Tests

Source: https://github.com/jsv4/docxodus/blob/main/README.md

Configure and run Playwright tests for the npm/WASM components of Docxodus. This involves installing dependencies, building the project, and executing tests.

```bash
# Need to be in npm subdirectory
cd npm

# Install dependencies (first time only)
npm install
npx playwright install chromium

# Build WASM and TypeScript (required before tests)
npm run build

# Run all Playwright tests (~62 tests)
npm test

# Run specific test by name pattern
npx playwright test --grep "Document Structure"

# Run tests with browser visible
npx playwright test --headed

# TypeScript type checking
npx tsc --noEmit
```

--------------------------------

### Install Docx2OC CLI Tool

Source: https://github.com/jsv4/docxodus/blob/main/CHANGELOG.md

Installs the `docx2oc` command-line tool globally using the .NET CLI. This tool facilitates easy conversion of DOCX files to OpenContracts format.

```bash
dotnet tool install --global Docx2OC
```

--------------------------------

### Install Redline CLI Tool

Source: https://github.com/jsv4/docxodus/blob/main/README.md

Install the Redline command-line tool globally using the .NET CLI. This tool is used for document comparison.

```bash
# Install globally
dotnet tool install -g Redline
```

--------------------------------

### Custom ImageHandler Callback Example

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/docx_converter.md

Provides a C# example of a custom ImageHandler callback used to process and save images during conversion. It demonstrates saving the image and returning an XElement for an img tag.

```csharp
settings.ImageHandler = imageInfo =>
{
    // Save image to file
    var filename = $"image_{Guid.NewGuid()}.png";
    imageInfo.SaveImage(filename, SKEncodedImageFormat.Png);

    return new XElement(Xhtml.img,
        new XAttribute("src", filename),
        new XAttribute("alt", imageInfo.AltText ?? ""),
        imageInfo.ImgStyleAttribute);
};
```

--------------------------------

### Complete Export Example

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/opencontracts_export.md

Demonstrates how to perform a complete export and access content, structural elements, and layout data using the exported object.

```typescript
import { exportToOpenContract } from 'docxodus';

const export = await exportToOpenContract(docxFile);

// Access complete text
console.log(`Total characters: ${export.content.length}`);

// Access structural elements
const sections = export.labelledText.filter(a => a.annotationLabel === 'SECTION');
const paragraphs = export.labelledText.filter(a => a.annotationLabel === 'PARAGRAPH');

// Access layout data
for (const page of export.pawlsFileContent) {
  console.log(`Page ${page.page.index}: ${page.page.width}x${page.page.height}pt`);
  console.log(`  ${page.tokens.length} tokens`);
}
```

--------------------------------

### HTML Output Structure for Annotations

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/custom_annotations.md

Example HTML structure demonstrating how annotations are rendered with labels and metadata.

```APIDOC
## HTML Output Structure

This section shows the typical HTML structure generated for custom annotations, including highlights, labels, and metadata attributes.

### Example 1: Annotation with Floating Label

```html
<span class="annot-highlight"
      data-annotation-id="ann-001"
      data-label-id="CLAUSE_TYPE_A"
      data-label="Important Clause"
      data-author="AI Model"
      data-created="2025-11-29T20:00:00Z"
      style="--annot-color: #FFEB3B;">
  <span class="annot-label">Important Clause</span>
  WHEREAS, the Party of the First Part agrees to...
</span>
```

### Example 2: Multi-paragraph Annotation

This example shows how an annotation spanning multiple paragraphs is structured using `annot-start`, `annot-continuation`, and `annot-end` classes.

```html
<p>
  <span class="annot-highlight annot-start"
        data-annotation-id="ann-001"
        style="--annot-color: #FFEB3B;">
    <span class="annot-label">Important Clause</span>
    First paragraph of annotated content...
  </span>
</p>
<p>
  <span class="annot-highlight annot-continuation"
        data-annotation-id="ann-001"
        style="--annot-color: #FFEB3B;">
    Continuation of annotated content...
  </span>
</p>
<p>
  <span class="annot-highlight annot-end"
        data-annotation-id="ann-001"
        style="--annot-color: #FFEB3B;">
    Final paragraph of annotated content.
  </span>
</p>
```
```

--------------------------------

### WASM Initialization and Setup

Source: https://github.com/jsv4/docxodus/blob/main/npm/tests/profiling-harness.html

Initializes the WebAssembly module using `dotnet.js`. It measures the time taken for WASM initialization, `dotnet.create()`, and `getAssemblyExports()`, logging the results.

```javascript
// Initialize WASM
log('Starting WASM initialization...');
const wasmInitStart = performance.now();

import('./_framework/dotnet.js').then(async ({ dotnet }) => {
  const dotnetCreateStart = performance.now();
  const { getAssemblyExports, getConfig } = await dotnet
    .withDiagnosticTracing(false)
    .create();
  const dotnetCreateTime = performance.now() - dotnetCreateStart;
  log(` dotnet.create(): ${formatMs(dotnetCreateTime)}`);

  const getExportsStart = performance.now();
  const config = getConfig();
  const exports = await getAssemblyExports(config.mainAssemblyName);
  const getExportsTime = performance.now() - getExportsStart;
  log(` getAssemblyExports(): ${formatMs(getExportsTime)}`);

  const wasmInitTime = performance.now() - wasmInitStart;
  Profiler.results['WASM Initialization'] = wasmInitTime;
  log(`✅ WASM ready in ${formatMs(wasmInitTime)}`);
  log('');

  window.Docxodus = {
    DocumentConverter: exports.DocxodusWasm.DocumentConverter,
    DocumentComparer: exports.DocxodusWasm.DocumentComparer,
  };

  runProfileBtn.disabled = false;
  runIterationsBtn.disabled = f
```

--------------------------------

### TypeScript Usage Examples

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/custom_annotations.md

Demonstrates how to use the docxodus library in TypeScript to add annotations with various targeting methods.

```APIDOC
### TypeScript Usage

```typescript
import {
  getDocumentStructure,
  addAnnotationWithTarget,
  targetParagraph,
  targetTableCell,
  targetElement,
  findElementsByType,
  DocumentElementType
} from 'docxodus';

// Get document structure
const structure = await getDocumentStructure(docxBytes);

// Find all paragraphs
const paragraphs = findElementsByType(structure, DocumentElementType.Paragraph);

// Add annotation to first paragraph
const result = await addAnnotationWithTarget(docxBytes, {
  Id: 'ann-1',
  LabelId: 'IMPORTANT',
  Label: 'Important Section',
  Color: '#FFEB3B',
  ...targetParagraph(0)
});

// Add annotation to table cell
const cellResult = await addAnnotationWithTarget(docxBytes, {
  Id: 'ann-2',
  LabelId: 'DATA',
  Label: 'Key Data',
  Color: '#81C784',
  ...targetTableCell(0, 1, 2)  // table 0, row 1, cell 2
});

// Add annotation by element ID
const result3 = await addAnnotationWithTarget(docxBytes, {
  Id: 'ann-3',
  LabelId: 'REF',
  Label: 'Reference',
  Color: '#64B5F6',
  ...targetElement(paragraphs[0].Id)
});
```
```

--------------------------------

### C# Annotation Usage Examples

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/custom_annotations.md

Demonstrates how to create and use AnnotationTarget objects to add annotations to specific parts of a document using the AnnotationManager.

```csharp
// Target a specific paragraph
var target1 = AnnotationTarget.Paragraph(2);

// Target a table cell
var target2 = AnnotationTarget.TableCell(tableIndex: 0, rowIndex: 1, cellIndex: 2);

// Target by element ID from structure analysis
var structure = DocumentStructureAnalyzer.Analyze(doc);
var cellId = structure.ElementsById.Keys.First(k => k.Contains("/tc-"));
var target3 = AnnotationTarget.Element(cellId);

// Search within a specific element
var target4 = AnnotationTarget.SearchInElement("doc/p-0", "important", occurrence: 1);

// Add annotation with target
var annotation = new DocumentAnnotation { Id = "ann-1", Label = "My Label", Color = "#FFEB3B" };
var result = AnnotationManager.AddAnnotation(doc, annotation, target1);
```

--------------------------------

### CSS Font Family Examples

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/docx_converter.md

Demonstrates common font family mappings from Word to CSS, including fallbacks.

```css
font-family: 'Arial', 'sans-serif'
```

```css
font-family: 'Times New Roman', 'serif'
```

```css
font-family: 'Courier New'
```

--------------------------------

### Bookmark Hyperlink HTML Example

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/docx_converter.md

Demonstrates the HTML representation of a bookmark link within a DOCX document.

```html
<a href="#bookmarkName" style="text-decoration: none">link text</a>
```

--------------------------------

### Initialize Docxodus WASM

Source: https://github.com/jsv4/docxodus/blob/main/npm/tests/test-harness.html

Initializes the Docxodus WebAssembly module and exposes its APIs to the window object for testing purposes. This setup is required before using any Docxodus functionalities.

```javascript
import { dotnet } from './\_framework/dotnet.js';
const { getAssemblyExports, getConfig } = await dotnet
  .withDiagnosticTracing(false)
  .create();
const config = getConfig();
const exports = await getAssemblyExports(config.mainAssemblyName);
// Expose Docxodus APIs to window for testing
window.Docxodus = {
  DocumentConverter: exports.DocxodusWasm.DocumentConverter,
  DocumentComparer: exports.DocxodusWasm.DocumentComparer
};
```

--------------------------------

### C#: Full Annotation Workflow

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/incremental_annotation_overlay.md

Demonstrates the complete workflow for converting DOCX to HTML, setting up annotations, projecting them, and performing incremental add and remove operations. Includes CSS generation for visibility toggling.

```csharp
// Convert once
var htmlSettings = new WmlToHtmlConverterSettings();
var baseHtml = WmlToHtmlConverter.ConvertToHtml(doc, htmlSettings).ToString();

// Create annotation set
var annotationSet = ExternalAnnotationManager.CreateAnnotationSet(doc, "doc-123");
annotationSet.TextLabels["CLAUSE"] = new AnnotationLabel
{
    Id = "CLAUSE", Text = "Clause", Color = "#FF5722"
};

// Create annotations
var ann = ExternalAnnotationManager.CreateAnnotation(
    "ann-1", "CLAUSE", annotationSet.Content, 100, 250);
annotationSet.LabelledText.Add(ann);

// Project all
string annotatedHtml = ExternalAnnotationProjector.ProjectAnnotationsOntoHtml(
    baseHtml, annotationSet);

// Incremental add
var ann2 = ExternalAnnotationManager.CreateAnnotation(
    "ann-2", "CLAUSE", annotationSet.Content, 300, 350);
annotatedHtml = ExternalAnnotationProjector.AddAnnotationToHtml(
    annotatedHtml, ann2, annotationSet.TextLabels["CLAUSE"]);

// Incremental remove
annotatedHtml = ExternalAnnotationProjector.RemoveAnnotationFromHtml(
    annotatedHtml, "ann-1");

// Visibility toggle
string css = ExternalAnnotationProjector.GenerateVisibilityCss(
    new[] { "CLAUSE" });
```

--------------------------------

### HTML Output for Annotations

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/custom_annotations.md

Examples of HTML structure for rendered annotations. Includes variations for floating labels, multi-paragraph spans, and different annotation states (start, continuation, end).

```html
<!-- Annotation with floating label -->
<span class="annot-highlight"
      data-annotation-id="ann-001"
      data-label-id="CLAUSE_TYPE_A"
      data-label="Important Clause"
      data-author="AI Model"
      data-created="2025-11-29T20:00:00Z"
      style="--annot-color: #FFEB3B;">
  <span class="annot-label">Important Clause</span>
  WHEREAS, the Party of the First Part agrees to...
</span>

<!-- Multi-paragraph annotation spans multiple elements -->
<p>
  <span class="annot-highlight annot-start"
        data-annotation-id="ann-001"
        style="--annot-color: #FFEB3B;">
    <span class="annot-label">Important Clause</span>
    First paragraph of annotated content...
  </span>
</p>
<p>
  <span class="annot-highlight annot-continuation"
        data-annotation-id="ann-001"
        style="--annot-color: #FFEB3B;">
    Continuation of annotated content...
  </span>
</p>
<p>
  <span class="annot-highlight annot-end"
        data-annotation-id="ann-001"
        style="--annot-color: #FFEB3B;">
    Final paragraph of annotated content.
  </span>
</p>
```

--------------------------------

### Initialize Docxodus WASM Test Harness

Source: https://github.com/jsv4/docxodus/blob/main/npm/tests/test-harness.html

Sets the status to 'Ready' and marks the Docxodus WASM test harness as available. Logs the version of the loaded Docxodus WASM.

```javascript
document.getElementById('status').textContent = 'Ready';
window.DocxodusReady = true;
console.log('Docxodus WASM Test Harness Ready');
console.log('Version:', window.DocxodusTests.getVersion());
```

--------------------------------

### Build docx2oc from Source

Source: https://github.com/jsv4/docxodus/blob/main/tools/docx2oc/README.md

Builds the docx2oc tool from its source code. Navigate to the tool's directory and run the build command.

```bash
cd tools/docx2oc
dotnet build
```

--------------------------------

### OOXML Comment Range Start Element

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/comment_rendering.md

Represents the start of a commented text range in the main document XML.

```xml
<w:p>
  <w:commentRangeStart w:id="0"/>
  <w:r>
    <w:t>This text has a comment</w:t>
  </w:r>
  <w:commentRangeEnd w:id="0"/>
  <w:r>
    <w:rPr>
      <w:rStyle w:val="CommentReference"/>
    </w:rPr>
    <w:commentReference w:id="0"/>
  </w:r>
</w:p>
```

--------------------------------

### Build Docxodus from Source

Source: https://github.com/jsv4/docxodus/blob/main/README.md

Clone the Docxodus repository and build the solution using the .NET CLI. This process prepares the project for local development or custom builds.

```bash
# Clone the repository
git clone https://github.com/JSv4/Docxodus.git
cd Docxodus

# Build
dotnet build Docxodus.sln

# Run the CLI
dotnet run --project tools/redline/redline.csproj -- --help
```

--------------------------------

### Convert DOCX to HTML and Project Annotations

Source: https://github.com/jsv4/docxodus/blob/main/docs/npm-package.md

Demonstrates the convert-once-then-project pattern. First, convert the DOCX to HTML, then build an annotation set, and finally project the annotations onto the HTML. This is followed by examples of incrementally adding or removing annotations.

```typescript
import {
  initialize,
  convertDocxToHtml,
  createExternalAnnotationSet,
  createAnnotationFromSearch,
  projectAnnotationsOntoHtml,
  addAnnotationToHtml,
  removeAnnotationFromHtml,
  generateAnnotationVisibilityCss,
  generateAnnotationCss,
} from 'docxodus';

await initialize();

// Step 1: Convert DOCX to HTML once (expensive, ~892ms)
const baseHtml = await convertDocxToHtml(docxFile);

// Step 2: Build your annotation set
const annotationSet = await createExternalAnnotationSet(docxFile, "doc-123");
annotationSet.textLabels["CLAUSE"] = {
  id: "CLAUSE", text: "Clause", color: "#FF5722",
  description: "Contract clause", icon: "", labelType: "text"
};
const ann = createAnnotationFromSearch(
  "ann-001", "CLAUSE", annotationSet.content, "shall not be liable"
);
if (ann) annotationSet.labelledText.push(ann);

// Step 3: Project annotations onto cached HTML (fast, ~56ms)
let html = await projectAnnotationsOntoHtml(baseHtml, annotationSet);

// Step 4: Incrementally add/remove without re-projecting the full set
const newAnn = createAnnotationFromSearch(
  "ann-002", "CLAUSE", annotationSet.content, "indemnify"
);
if (newAnn) {
  const label = annotationSet.textLabels["CLAUSE"];
  html = await addAnnotationToHtml(html, newAnn, label);  // ~0.3ms
}

html = await removeAnnotationFromHtml(html, "ann-001");  // ~0.3ms
```

--------------------------------

### Build the Entire Docxodus Solution

Source: https://github.com/jsv4/docxodus/blob/main/CLAUDE.md

Use `dotnet build Docxodus.sln` to compile the entire C# solution. This command is used for a full build of the project.

```bash
# Build the entire solution
dotnet build Docxodus.sln
```

--------------------------------

### Example OpenContracts JSON Output

Source: https://github.com/jsv4/docxodus/blob/main/tools/docx2oc/README.md

An example of the JSON structure produced by docx2oc, compatible with the OpenContracts platform. Includes document title, content, page count, token positions, and structural annotations.

```json
{
  "title": "Sample Contract",
  "content": "This is the document content...",
  "pageCount": 5,
  "pawlsFileContent": [
    {
      "page": { "width": 612, "height": 792, "index": 0 },
      "tokens": [
        { "x": 72, "y": 72, "width": 30, "height": 12, "text": "This" }
      ]
    }
  ],
  "labelledText": [
    {
      "id": "section-0",
      "annotationLabel": "SECTION",
      "structural": true
    }
  ]
}
```

--------------------------------

### Client-Side Rendering with Virtualization

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/wasm-optimization-plan.md

Demonstrates client-side rendering of DOCX to HTML, leveraging browser-native content-visibility for efficient rendering of large documents.

```typescript
// Simple, fast, minimal API
const html = await convertDocxToHtml(docxFile, {
  paginationMode: PaginationMode.Paginated,
  renderFootnotesAndEndnotes: true
});

// Let browser handle "virtualization" natively
container.style.contentVisibility = 'auto';
container.style.containIntrinsicSize = '0 50000px';
container.innerHTML = html;
```

--------------------------------

### LibreOffice Empty Paragraph HTML

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/wml_to_html_converter_gaps.md

Example of how LibreOffice renders an empty paragraph.

```html
<p><br/></p>
```

--------------------------------

### TypeScript: Full Annotation Workflow

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/incremental_annotation_overlay.md

Demonstrates the complete workflow for converting DOCX to HTML, setting up annotations, projecting them, and performing incremental add and remove operations. Includes CSS generation for visibility toggling.

```typescript
import {
  convertDocxToHtml,
  createExternalAnnotationSet,
  projectAnnotationsOntoHtml,
  addAnnotationToHtml,
  removeAnnotationFromHtml,
  generateAnnotationVisibilityCss,
  createAnnotation,
} from "docxodus";

// Step 1: Convert once and cache
const baseHtml = await convertDocxToHtml(docxBytes);
const annotationSet = await createExternalAnnotationSet(docxBytes, "doc-123");

// Step 2: Define labels
annotationSet.textLabels["CLAUSE"] = {
  id: "CLAUSE",
  text: "Clause",
  color: "#FF5722",
};
annotationSet.textLabels["TERM"] = {
  id: "TERM",
  text: "Term",
  color: "#2196F3",
};

// Step 3: Create annotations and project all at once
const ann1 = createAnnotation("ann-1", "CLAUSE", annotationSet.content, 100, 250);
const ann2 = createAnnotation("ann-2", "TERM", annotationSet.content, 300, 320);
annotationSet.labelledText.push(ann1, ann2);

let html = await projectAnnotationsOntoHtml(baseHtml, annotationSet);

// Step 4: Incrementally add one more
const ann3 = createAnnotation("ann-3", "TERM", annotationSet.content, 500, 530);
const termLabel = annotationSet.textLabels["TERM"];
html = await addAnnotationToHtml(html, ann3, termLabel);

// Step 5: Remove one
html = await removeAnnotationFromHtml(html, "ann-1");

// Step 6: Toggle visibility by label (CSS only, no HTML change)
const hideCss = await generateAnnotationVisibilityCss(["TERM"]);
// Apply hideCss to a <style> element in the DOM
```

--------------------------------

### Comment Render Modes

Source: https://github.com/jsv4/docxodus/blob/main/docs/npm-package.md

Enum and examples for controlling how comments are rendered in HTML output.

```APIDOC
## `CommentRenderMode` Enum

### Description
The `CommentRenderMode` enum controls how Word document comments are rendered in HTML.

### Enum Values
| Mode | Value | Description |
|------|-------|-------------|
| `Disabled` | -1 | Don't render comments (default) |
| `EndnoteStyle` | 0 | Comments at end of document with `[1]` style bidirectional links |
| `Inline` | 1 | Tooltips via `title` and `data-comment` attributes |
| `Margin` | 2 | Side column using CSS flexbox layout |

### Usage Example
```typescript
import { CommentRenderMode } from 'docxodus';

// Example for EndnoteStyle
const htmlEndnote = await convertDocxToHtml(docxFile, {
  commentRenderMode: CommentRenderMode.EndnoteStyle
});
// Produces: highlighted text with [1] links, comments section at bottom

// Example for Inline
const htmlInline = await convertDocxToHtml(docxFile, {
  commentRenderMode: CommentRenderMode.Inline
});
// Produces: highlighted text with title="Author: comment text" attributes

// Example for Margin
const htmlMargin = await convertDocxToHtml(docxFile, {
  commentRenderMode: CommentRenderMode.Margin
});
// Produces: flexbox layout with main content on left, comments in right column
```
```

--------------------------------

### LibreOffice Simple Border HTML

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/wml_to_html_converter_gaps.md

Example of how LibreOffice renders a paragraph with a bottom border.

```html
<p style="border-bottom: 1px solid #cccccc">...</p>
```

--------------------------------

### Element ID Format Examples

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/custom_annotations.md

Illustrates the path-based, stable identifier format for document elements.

```plaintext
doc                     # Document root
doc/p-0                 # First paragraph
doc/p-0/r-0             # First run in first paragraph
doc/p-0/hl-0            # First hyperlink in first paragraph
doc/tbl-0               # First table
doc/tbl-0/tr-0          # First row in first table
doc/tbl-0/tr-0/tc-0     # First cell in first row
doc/tbl-0/tr-0/tc-0/p-0 # First paragraph in that cell
```

--------------------------------

### Initialize and Use Docxodus Core Functions

Source: https://github.com/jsv4/docxodus/blob/main/npm/README.md

Initialize the WASM runtime once at application startup, then use functions to convert DOCX to HTML or compare documents.

```javascript
import { initialize, convertDocxToHtml, compareDocuments } from 'docxodus';

// Initialize the WASM runtime (call once at app startup)
await initialize('/path/to/wasm/');

// Convert DOCX to HTML
const html = await convertDocxToHtml(docxFile);

// Compare two documents
const redlinedDocx = await compareDocuments(originalFile, modifiedFile, {
  authorName: 'Reviewer'
});
```

--------------------------------

### External Hyperlink HTML Example

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/docx_converter.md

Shows the HTML output for an external hyperlink defined in DOCX.

```html
<a href="https://example.com">link text</a>
```

--------------------------------

### npm: initialize and convertDocxToHtml

Source: https://context7.com/jsv4/docxodus/llms.txt

Initializes the WebAssembly runtime and converts DOCX files to HTML. Supports basic and advanced conversion options.

```APIDOC
## npm: initialize and convertDocxToHtml — Browser/WASM HTML conversion

The `docxodus` npm package bundles a .NET 8 WebAssembly runtime. Call `initialize()` once, then use any conversion or comparison function. All functions accept `File` or `Uint8Array` inputs.

```typescript
import {
  initialize, convertDocxToHtml,
  CommentRenderMode, PaginationMode, AnnotationLabelMode
} from 'docxodus';

// Initialize WASM runtime (auto-detects WASM file location)
await initialize();

// Basic conversion
const html = await convertDocxToHtml(docxFile);

// Full-featured conversion
const richHtml = await convertDocxToHtml(docxFile, {
  pageTitle:                       "Contract",
  cssPrefix:                       "docx-",
  fabricateClasses:                true,
  commentRenderMode:               CommentRenderMode.Margin,
  paginationMode:                  PaginationMode.Paginated,
  paginationScale:                 1.0,
  renderAnnotations:               true,
  annotationLabelMode:             AnnotationLabelMode.Tooltip,
  renderFootnotesAndEndnotes:      true,
  renderHeadersAndFooters:         true,
  renderTrackedChanges:            true,
  showDeletedContent:              true,
  renderUnsupportedContentPlaceholders: true,
});

document.getElementById('viewer')!.innerHTML = richHtml;
```
```

--------------------------------

### HYPERLINK Field HTML Example

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/docx_converter.md

Represents the HTML output for a HYPERLINK field detected in a DOCX document.

```html
<a href="url-from-field">field content</a>
```

--------------------------------

### Overlay Pattern Diagram

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/incremental_annotation_overlay.md

Illustrates the workflow of the incremental annotation overlay system, showing the initial full conversion and subsequent incremental annotation operations.

```text
                  DOCX file
                      |
                      v
          +-----------------------+
          | WmlToHtmlConverter    |  ~892ms (one time)
          | (full conversion)     |
          +-----------------------+
                      |
                      v
                 Base HTML  <--- cache this
                      |
        +-------------+-------------+
        |             |             |
        v             v             v
  ProjectAll()   Add()         Remove()
   ~56ms         ~0.3ms        ~18ms
        |             |             |
        v             v             v
              Annotated HTML
```

--------------------------------

### CDN Usage for Docxodus

Source: https://github.com/jsv4/docxodus/blob/main/docs/npm-package.md

Integrate Docxodus directly from a CDN without needing npm. This example shows how to initialize the library and convert a DOCX file to HTML using a provided document.

```html
<script type="module">
  import { initialize, convertDocxToHtml, CommentRenderMode } from 'https://cdn.jsdelivr.net/npm/docxodus@latest/dist/index.js';

  await initialize();

  const response = await fetch('document.docx');
  const docxBytes = new Uint8Array(await response.arrayBuffer());

  const html = await convertDocxToHtml(docxBytes, {
    commentRenderMode: CommentRenderMode.EndnoteStyle
  });

  document.getElementById('content').innerHTML = html;
</script>
```

--------------------------------

### Initialize and Use Docxodus in JavaScript

Source: https://github.com/jsv4/docxodus/blob/main/README.md

Initialize the Docxodus library and demonstrate common operations like DOCX to HTML conversion, document comparison, and revision analysis. Requires asynchronous initialization.

```javascript
import {
  initialize,
  convertDocxToHtml,
  compareDocuments,
  getRevisions,
  getDocumentMetadata,
  isMove,
  isMoveSource,
  isFormatChange,
  findMovePair,
  CommentRenderMode,
  PaginationMode
} from 'docxodus';

await initialize();

// Convert DOCX to HTML with comments and pagination
const html = await convertDocxToHtml(docxFile, {
  commentRenderMode: CommentRenderMode.EndnoteStyle,
  paginationMode: PaginationMode.Paginated,
  renderHeadersAndFooters: true
});

// Compare two documents
const redlinedDocx = await compareDocuments(originalFile, modifiedFile);

// Get revisions with move and format change detection
const revisions = await getRevisions(redlinedDocx);
for (const rev of revisions) {
  if (isMove(rev)) {
    const pair = findMovePair(rev, revisions);
    if (isMoveSource(rev)) {
      console.log(`Content moved from: "${rev.text}" to: "${pair?.text}"`);
    }
  } else if (isFormatChange(rev)) {
    console.log(`Format changed: ${rev.formatChange?.changedPropertyNames?.join(', ')}`);
  }
}

// Get document metadata for lazy loading
const metadata = await getDocumentMetadata(docxFile);
console.log(`${metadata.totalParagraphs} paragraphs, ${metadata.estimatedPageCount} pages`);
```

--------------------------------

### Initialize Docxodus Worker

Source: https://github.com/jsv4/docxodus/blob/main/npm/tests/worker-test-harness.html

Imports the worker proxy and sets up global variables for the worker instance and its readiness status. Call createDocxodusWorker() to initialize the worker.

```javascript
import { createWorkerDocxodus, isWorkerSupported } from './worker-proxy.js';

window.DocxodusWorker = null;
window.DocxodusWorkerReady = false;
window.DocxodusWorkerError = null;

window.createDocxodusWorker = async function() {
  try {
    window.DocxodusWorker = await createWorkerDocxodus({ wasmBasePath: './' });
    window.DocxodusWorkerReady = true;
    document.getElementById('status').textContent = 'Worker Ready';
    console.log('Docxodus Worker Ready');
    return window.DocxodusWorker;
  } catch (error) {
    window.DocxodusWorkerError = error;
    document.getElementById('status').textContent = 'Worker Error: ' + error.message;
    console.error('Failed to create worker:', error);
    throw error;
  }
};
```

--------------------------------

### Get All Annotations from Document

Source: https://github.com/jsv4/docxodus/blob/main/docs/npm-package.md

Retrieves all annotations present in a DOCX document. Useful for iterating and processing existing annotations.

```typescript
import { getAnnotations } from 'docxodus';

const annotations = await getAnnotations(docxBytes);
for (const annot of annotations) {
  console.log(`${annot.label}: "${annot.annotatedText}"`);
}
```

--------------------------------

### CSS Positioning Styles

Source: https://github.com/jsv4/docxodus/blob/main/TestFiles/T1030.html

Defines styles for body, paragraphs, spans, and positioned elements. Use this for layout setup.

```css
body {
  display: block;
  font-size:12px;
  line-height: 200%;
  width: 400px;
  height: 400px;
}

p {
  display: block;
}

span {
  display: inline;
}

#outer {
  position: relative;
  color: red;
}

#inner {
  position: absolute;
  top: 200px;
  left: -100px;
  height: 130px;
  width: 130px;
  color: blue;
}
```

--------------------------------

### Publish ReadyToRun for Performance

Source: https://github.com/jsv4/docxodus/blob/main/CHANGELOG.md

Configures the .NET project to publish with ReadyToRun compilation enabled. This pre-compiles native code, reducing cold-start times.

```xml
<PublishReadyToRun>true</PublishReadyToRun>
```

--------------------------------

### Tab Character HTML Example

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/docx_converter.md

Illustrates how tab characters are converted into span elements with specific styling for alignment and spacing.

```html
<span style="margin: 0 0 0 0.75in; padding: 0 0 0 0">&#x00a0;</span>
```

--------------------------------

### Performance Comparison: Session vs Direct API

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/profiling-results.md

Illustrates the performance difference between the old direct API (parsing twice) and the new session-based API (parsing once). The session API offers significant time savings and speedup.

```text
════════════════════════════════════════════════════════════════
PERFORMANCE COMPARISON: Session vs Direct API
════════════════════════════════════════════════════════════════
OLD APPROACH (direct API, parses document twice):
  GetDocumentMetadata:     541.40ms (document parsed)
  RenderPageRange:         231.40ms (document parsed AGAIN)
  Total:                   772.80ms

NEW APPROACH (session-based, parses once):
  CreateDocumentSession:   200.50ms (document parsed + cached)
  GetSessionMetadata:        0.00ms (instant, from cache)
  RenderSessionPageRange:   31.40ms (uses cached document)
  Total:                   231.90ms

SAVINGS: 540.90ms (70%)
SPEEDUP: 3.33x
════════════════════════════════════════════════════════════════
```

--------------------------------

### Get Docxodus Version Info

Source: https://github.com/jsv4/docxodus/blob/main/npm/tests/test-harness.html

Retrieves the version information of the Docxodus library as a JSON string, which is then parsed into a JavaScript object.

```javascript
getVersion: function() {
  return JSON.parse(window.Docxodus.DocumentConverter.GetVersion());
}
```

--------------------------------

### Web Worker Configuration Options

Source: https://github.com/jsv4/docxodus/blob/main/docs/architecture/ui_responsiveness.md

Allows customization of the Web Worker setup, such as specifying the base path for WASM files.

```typescript
const docxodus = await createWorkerDocxodus({
  // Custom WASM path (defaults to auto-detection)
  wasmBasePath: '/assets/wasm/'
});
```

--------------------------------

### redline CLI

Source: https://context7.com/jsv4/docxodus/llms.txt

Compares two DOCX files and writes a redlined DOCX. Installs as a global .NET tool or self-contained binary.

```APIDOC
## CLI: redline — Command-line document comparison

The `redline` CLI tool compares two DOCX files and writes a redlined DOCX. It installs as a global .NET tool or can be downloaded as a self-contained binary.

```bash
# Install globally
dotnet tool install -g Redline

# Basic comparison
redline original.docx modified.docx output.docx

# With a custom author name
redline original.docx modified.docx output.docx --author="Legal Review"

# Show help
redline --help
```
```

--------------------------------

### Get Revisions

Source: https://github.com/jsv4/docxodus/blob/main/docs/npm-package.md

Extracts revision information (insertions, deletions, moves) from a compared document. Move detection is enabled by default and can be configured.

```APIDOC
## `getRevisions(document, options?)`

### Description
Extract revision information from a compared document. Revisions include insertions, deletions, and moves (relocated content).

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **document** (any) - The document to extract revisions from.
- **options** (object) - Optional configuration for move detection.
  - **detectMoves** (boolean) - Enable/disable move detection. Defaults to `true`.
  - **moveSimilarityThreshold** (number) - Jaccard similarity threshold (0.0-1.0) for move detection. Defaults to `0.8`.
  - **moveMinimumWordCount** (number) - Minimum word count for move detection. Defaults to `3`.
  - **caseInsensitive** (boolean) - Whether to perform case-insensitive matching. Defaults to `false`.

### Request Example
```typescript
import { getRevisions, isMove, isMoveSource, findMovePair, RevisionType } from 'docxodus';

const revisions = await getRevisions(comparedDocx);

// Filter by type
const insertions = revisions.filter(r => r.revisionType === RevisionType.Inserted);
const deletions = revisions.filter(r => r.revisionType === RevisionType.Deleted);
const moves = revisions.filter(isMove);

// Work with move pairs
for (const rev of revisions.filter(isMoveSource)) {
  const destination = findMovePair(rev, revisions);
  console.log(`\"${rev.text}\" moved to \"${destination?.text}\"`);
}
```

### Response
#### Success Response (200)
- **Promise<Revision[]>**: A promise that resolves to an array of Revision objects.

**Revision Interface:**
```typescript
interface Revision {
  author: string;           // Author who made the change
  date: string;             // ISO 8601 date string
  revisionType: RevisionType | string;  // "Inserted", "Deleted", or "Moved"
  text: string;             // The revised text content
  moveGroupId?: number;     // For moves: links source and destination
  isMoveSource?: boolean;   // For moves: true = moved FROM, false = moved TO
}
```

### Response Example
```json
[
  {
    "author": "John Doe",
    "date": "2023-10-27T10:00:00Z",
    "revisionType": "Inserted",
    "text": "This is new content."
  },
  {
    "author": "Jane Smith",
    "date": "2023-10-27T10:05:00Z",
    "revisionType": "Moved",
    "text": "This content was moved.",
    "moveGroupId": 1,
    "isMoveSource": true
  },
  {
    "author": "Jane Smith",
    "date": "2023-10-27T10:06:00Z",
    "revisionType": "Moved",
    "text": "This content was moved.",
    "moveGroupId": 1,
    "isMoveSource": false
  }
]
```
```

--------------------------------

### Get Annotations from Document

Source: https://github.com/jsv4/docxodus/blob/main/npm/tests/test-harness.html

Extracts annotations from a DOCX document and returns them as a JSON object. Handles potential errors during extraction and parsing.

```javascript
getAnnotations: function(bytes) {
  try {
    const result = window.Docxodus.DocumentConverter.GetAnnotations(bytes);
    if (result.startsWith('{') && result.includes('"Error"')) {
      return { error: JSON.parse(result) };
    }
    const parsed = JSON.parse(result);
    return { annotations: parsed.Annotations || [] };
  } catch (e) {
    return { error: { message: e.message } };
  }
}
```