docxodus 5.4.1 → 5.5.0

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import type { ConversionOptions, CompareOptions, Revision, VersionInfo, ErrorResponse, CompareResult, GetRevisionsOptions, FormatChangeDetails, Annotation, AddAnnotationRequest, AddAnnotationResponse, RemoveAnnotationResponse, AnnotationOptions, DocumentStructure, DocumentElement, TableColumnInfo, AnnotationTarget, AddAnnotationWithTargetRequest, DocumentMetadata, SectionMetadata, OpenContractDocExport, PawlsPage, PawlsPageBoundary, PawlsToken, OpenContractsAnnotation, OpenContractsSinglePageAnnotation, BoundingBox, TokenId, TextSpan, OpenContractsRelationship, AnnotationLabel, ExternalAnnotationSet, ExternalAnnotationValidationResult, ExternalAnnotationValidationIssue, ExternalAnnotationProjectionSettings } from "./types.js";
-import { CommentRenderMode, PaginationMode, AnnotationLabelMode, RevisionType, DocumentElementType, isInsertion, isDeletion, isMove, isMoveSource, isMoveDestination, findMovePair, isFormatChange, findElementById, findElementsByType, getParagraphs, getTables, getTableColumns, targetElement, targetParagraph, targetParagraphRange, targetRun, targetTable, targetTableRow, targetTableCell, targetTableColumn, targetSearch, targetSearchInElement } from "./types.js";
+import type { ConversionOptions, CompareOptions, Revision, VersionInfo, ErrorResponse, CompareResult, GetRevisionsOptions, FormatChangeDetails, Annotation, AddAnnotationRequest, AddAnnotationResponse, RemoveAnnotationResponse, AnnotationOptions, DocumentStructure, DocumentElement, TableColumnInfo, AnnotationTarget, AddAnnotationWithTargetRequest, DocumentMetadata, SectionMetadata, OpenContractDocExport, PawlsPage, PawlsPageBoundary, PawlsToken, OpenContractsAnnotation, OpenContractsSinglePageAnnotation, BoundingBox, TokenId, TextSpan, OpenContractsRelationship, AnnotationLabel, ExternalAnnotationSet, ExternalAnnotationValidationResult, ExternalAnnotationValidationIssue, ExternalAnnotationProjectionSettings, ComparisonLogEntry, CompareResultWithLog, CompareToHtmlResultWithLog } from "./types.js";
+import { CommentRenderMode, PaginationMode, AnnotationLabelMode, RevisionType, DocumentElementType, ComparisonLogLevel, ComparisonLogCodes, isInsertion, isDeletion, isMove, isMoveSource, isMoveDestination, findMovePair, isFormatChange, findElementById, findElementsByType, getParagraphs, getTables, getTableColumns, targetElement, targetParagraph, targetParagraphRange, targetRun, targetTable, targetTableRow, targetTableCell, targetTableColumn, targetSearch, targetSearchInElement } from "./types.js";
 export type { PageDimensions, MeasuredBlock, PageInfo, PaginationResult, PaginationOptions, } from "./pagination.js";
 export { PaginationEngine, paginateHtml } from "./pagination.js";
-export type { ConversionOptions, CompareOptions, Revision, VersionInfo, ErrorResponse, CompareResult, GetRevisionsOptions, FormatChangeDetails, Annotation, AddAnnotationRequest, AddAnnotationResponse, RemoveAnnotationResponse, AnnotationOptions, DocumentStructure, DocumentElement, TableColumnInfo, AnnotationTarget, AddAnnotationWithTargetRequest, DocumentMetadata, SectionMetadata, OpenContractDocExport, PawlsPage, PawlsPageBoundary, PawlsToken, OpenContractsAnnotation, OpenContractsSinglePageAnnotation, BoundingBox, TokenId, TextSpan, OpenContractsRelationship, AnnotationLabel, ExternalAnnotationSet, ExternalAnnotationValidationResult, ExternalAnnotationValidationIssue, ExternalAnnotationProjectionSettings, };
-export { CommentRenderMode, PaginationMode, AnnotationLabelMode, RevisionType, DocumentElementType, isInsertion, isDeletion, isMove, isMoveSource, isMoveDestination, findMovePair, isFormatChange, findElementById, findElementsByType, getParagraphs, getTables, getTableColumns, targetElement, targetParagraph, targetParagraphRange, targetRun, targetTable, targetTableRow, targetTableCell, targetTableColumn, targetSearch, targetSearchInElement, };
+export type { ConversionOptions, CompareOptions, Revision, VersionInfo, ErrorResponse, CompareResult, GetRevisionsOptions, FormatChangeDetails, Annotation, AddAnnotationRequest, AddAnnotationResponse, RemoveAnnotationResponse, AnnotationOptions, DocumentStructure, DocumentElement, TableColumnInfo, AnnotationTarget, AddAnnotationWithTargetRequest, DocumentMetadata, SectionMetadata, OpenContractDocExport, PawlsPage, PawlsPageBoundary, PawlsToken, OpenContractsAnnotation, OpenContractsSinglePageAnnotation, BoundingBox, TokenId, TextSpan, OpenContractsRelationship, AnnotationLabel, ExternalAnnotationSet, ExternalAnnotationValidationResult, ExternalAnnotationValidationIssue, ExternalAnnotationProjectionSettings, ComparisonLogEntry, CompareResultWithLog, CompareToHtmlResultWithLog, };
+export { CommentRenderMode, PaginationMode, AnnotationLabelMode, RevisionType, DocumentElementType, ComparisonLogLevel, ComparisonLogCodes, isInsertion, isDeletion, isMove, isMoveSource, isMoveDestination, findMovePair, isFormatChange, findElementById, findElementsByType, getParagraphs, getTables, getTableColumns, targetElement, targetParagraph, targetParagraphRange, targetRun, targetTable, targetTableRow, targetTableCell, targetTableColumn, targetSearch, targetSearchInElement, };
 /**
  * Current base path for WASM files.
  * Empty string means auto-detect from module URL.
@@ -92,6 +92,63 @@ export declare function compareDocuments(original: File | Uint8Array, modified:
  * @throws Error if comparison fails
  */
 export declare function compareDocumentsToHtml(original: File | Uint8Array, modified: File | Uint8Array, options?: CompareOptions): Promise<string>;
+/**
+ * Compare two DOCX documents with logging enabled.
+ * Returns both the redlined document and a log of any warnings/errors encountered.
+ * This allows the comparison to continue past recoverable issues (like orphaned footnotes)
+ * while providing visibility into what was fixed or skipped.
+ *
+ * @param original - Original DOCX document
+ * @param modified - Modified DOCX document
+ * @param options - Comparison options
+ * @returns Result with document bytes and log entries
+ *
+ * @example
+ * ```typescript
+ * const result = await compareDocumentsWithLog(original, modified, {
+ *   authorName: "Reviewer",
+ *   detailThreshold: 0.15
+ * });
+ *
+ * if (result.success) {
+ *   // Use result.document (Uint8Array)
+ *   if (result.hasWarnings) {
+ *     console.log("Warnings during comparison:");
+ *     for (const entry of result.log) {
+ *       console.log(`  [${entry.level}] ${entry.code}: ${entry.message}`);
+ *     }
+ *   }
+ * } else {
+ *   console.error(`Comparison failed: ${result.error}`);
+ * }
+ * ```
+ */
+export declare function compareDocumentsWithLog(original: File | Uint8Array, modified: File | Uint8Array, options?: CompareOptions): Promise<CompareResultWithLog>;
+/**
+ * Compare two DOCX documents to HTML with logging enabled.
+ * Returns both the HTML output and a log of any warnings/errors encountered.
+ *
+ * @param original - Original DOCX document
+ * @param modified - Modified DOCX document
+ * @param options - Comparison options
+ * @returns Result with HTML and log entries
+ *
+ * @example
+ * ```typescript
+ * const result = await compareDocumentsToHtmlWithLog(original, modified, {
+ *   authorName: "Reviewer",
+ *   renderTrackedChanges: true
+ * });
+ *
+ * if (result.success) {
+ *   document.getElementById("viewer").innerHTML = result.html;
+ *   if (result.hasWarnings) {
+ *     console.log(`${result.log.length} warnings during comparison`);
+ *   }
+ * }
+ * ```
+ */
+export declare function compareDocumentsToHtmlWithLog(original: File | Uint8Array, modified: File | Uint8Array, options?: CompareOptions): Promise<CompareToHtmlResultWithLog>;
 /**
  * Get revisions from a compared document.
  *
@@ -551,4 +608,114 @@ export declare function findTextOccurrences(documentText: string, searchText: st
     start: number;
     end: number;
 }>;
+/**
+ * Project external annotations onto already-converted HTML.
+ * This avoids full DOCX re-conversion when only annotations change.
+ *
+ * Workflow:
+ * 1. Convert DOCX to HTML once using `convertDocxToHtml()`
+ * 2. Use this function to overlay annotations on the cached HTML
+ * 3. When annotations change, call this again with the same base HTML
+ *
+ * @param html - HTML string (previously converted via convertDocxToHtml)
+ * @param annotationSet - The external annotation set to project
+ * @param projectionOptions - Projection settings (CSS prefix, label mode, etc.)
+ * @returns HTML string with annotations projected
+ * @throws Error if projection fails
+ *
+ * @example
+ * ```typescript
+ * // Step 1: Convert once
+ * const baseHtml = await convertDocxToHtml(docxFile);
+ *
+ * // Step 2: Project annotations (fast, no DOCX re-conversion)
+ * const annotatedHtml = await projectAnnotationsOntoHtml(baseHtml, annotationSet);
+ *
+ * // Step 3: When annotations change, project again on the same base HTML
+ * annotationSet.labelledText.push(newAnnotation);
+ * const updatedHtml = await projectAnnotationsOntoHtml(baseHtml, annotationSet);
+ * ```
+ */
+export declare function projectAnnotationsOntoHtml(html: string, annotationSet: ExternalAnnotationSet, projectionOptions?: ExternalAnnotationProjectionSettings): Promise<string>;
+/**
+ * Add a single annotation to existing HTML without re-converting the document.
+ * This is the fastest way to add one annotation to already-rendered HTML.
+ *
+ * @param html - HTML string (with or without existing annotations)
+ * @param annotation - The annotation to add
+ * @param label - Label definition for the annotation (optional, for color/text)
+ * @param projectionOptions - Projection settings
+ * @returns HTML string with the annotation added
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const annotation = createAnnotation("ann-new", "CLAUSE", set.content, 100, 150);
+ * const label = { id: "CLAUSE", text: "Clause", color: "#FF5722" };
+ * const updatedHtml = await addAnnotationToHtml(currentHtml, annotation, label);
+ * ```
+ */
+export declare function addAnnotationToHtml(html: string, annotation: OpenContractsAnnotation, label?: AnnotationLabel, projectionOptions?: ExternalAnnotationProjectionSettings): Promise<string>;
+/**
+ * Remove a single annotation from HTML by annotation ID.
+ * Unwraps annotation spans back to plain text.
+ *
+ * @param html - HTML string with annotations
+ * @param annotationId - ID of the annotation to remove
+ * @param cssClassPrefix - CSS class prefix used for annotations (default: "ext-annot-")
+ * @returns HTML string with the annotation removed
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const updatedHtml = await removeAnnotationFromHtml(currentHtml, "ann-001");
+ * ```
+ */
+export declare function removeAnnotationFromHtml(html: string, annotationId: string, cssClassPrefix?: string): Promise<string>;
+/**
+ * Generate CSS to hide annotations with specific label IDs.
+ * Enables CSS-based label filtering without re-rendering HTML.
+ *
+ * Apply the returned CSS to your document (e.g., via a `<style>` element)
+ * to hide/show annotations by label. This is much faster than re-projecting
+ * all annotations.
+ *
+ * @param hiddenLabelIds - Array of label IDs to hide
+ * @param cssClassPrefix - CSS class prefix (default: "ext-annot-")
+ * @returns CSS string that hides the specified labels
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * // Hide annotations with label "DRAFT" and "INTERNAL"
+ * const css = await generateAnnotationVisibilityCss(["DRAFT", "INTERNAL"]);
+ *
+ * // Apply to a <style> element in the DOM
+ * const styleEl = document.getElementById("visibility-overrides");
+ * styleEl.textContent = css;
+ *
+ * // To show all annotations again, clear the style:
+ * styleEl.textContent = "";
+ * ```
+ */
+export declare function generateAnnotationVisibilityCss(hiddenLabelIds: string[], cssClassPrefix?: string): Promise<string>;
+/**
+ * Generate annotation CSS for a set of labels.
+ * Useful when managing CSS separately from HTML content.
+ *
+ * @param labels - Label definitions (keyed by label ID)
+ * @param projectionOptions - Projection settings
+ * @returns CSS string for the annotation styles
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const labels = {
+ *   "CLAUSE": { id: "CLAUSE", text: "Clause", color: "#FF5722" },
+ *   "TERM": { id: "TERM", text: "Term", color: "#2196F3" },
+ * };
+ * const css = await generateAnnotationCss(labels);
+ * ```
+ */
+export declare function generateAnnotationCss(labels: Record<string, AnnotationLabel>, projectionOptions?: ExternalAnnotationProjectionSettings): Promise<string>;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,6 +1,6 @@
-import { CommentRenderMode, PaginationMode, AnnotationLabelMode, RevisionType, DocumentElementType, isInsertion, isDeletion, isMove, isMoveSource, isMoveDestination, findMovePair, isFormatChange, findElementById, findElementsByType, getParagraphs, getTables, getTableColumns, targetElement, targetParagraph, targetParagraphRange, targetRun, targetTable, targetTableRow, targetTableCell, targetTableColumn, targetSearch, targetSearchInElement, } from "./types.js";
+import { CommentRenderMode, PaginationMode, AnnotationLabelMode, RevisionType, DocumentElementType, ComparisonLogLevel, ComparisonLogCodes, isInsertion, isDeletion, isMove, isMoveSource, isMoveDestination, findMovePair, isFormatChange, findElementById, findElementsByType, getParagraphs, getTables, getTableColumns, targetElement, targetParagraph, targetParagraphRange, targetRun, targetTable, targetTableRow, targetTableCell, targetTableColumn, targetSearch, targetSearchInElement, } from "./types.js";
 export { PaginationEngine, paginateHtml } from "./pagination.js";
-export { CommentRenderMode, PaginationMode, AnnotationLabelMode, RevisionType, DocumentElementType, isInsertion, isDeletion, isMove, isMoveSource, isMoveDestination, findMovePair, isFormatChange, 
+export { CommentRenderMode, PaginationMode, AnnotationLabelMode, RevisionType, DocumentElementType, ComparisonLogLevel, ComparisonLogCodes, isInsertion, isDeletion, isMove, isMoveSource, isMoveDestination, findMovePair, isFormatChange, 
 // Document structure helpers
 findElementById, findElementsByType, getParagraphs, getTables, getTableColumns, 
 // Annotation target factory functions
@@ -287,15 +287,122 @@ export async function compareDocumentsToHtml(original, modified, options) {
     const modifiedBytes = await toBytes(modified);
     // Yield to browser before heavy WASM work - allows loading states to render
     await yieldToMain();
-    // Use the new options method if renderTrackedChanges is explicitly set
     const renderTrackedChanges = options?.renderTrackedChanges ?? true;
-    const result = exports.DocumentComparer.CompareDocumentsToHtmlWithOptions(originalBytes, modifiedBytes, options?.authorName ?? "Docxodus", renderTrackedChanges);
+    let result;
+    // Use full method when detailThreshold or caseInsensitive are specified
+    if (options?.detailThreshold !== undefined || options?.caseInsensitive !== undefined) {
+        result = exports.DocumentComparer.CompareDocumentsToHtmlFull(originalBytes, modifiedBytes, options?.authorName ?? "Docxodus", options?.detailThreshold ?? 0.15, options?.caseInsensitive ?? false, renderTrackedChanges);
+    }
+    else {
+        result = exports.DocumentComparer.CompareDocumentsToHtmlWithOptions(originalBytes, modifiedBytes, options?.authorName ?? "Docxodus", renderTrackedChanges);
+    }
     if (isErrorResponse(result)) {
         const error = parseError(result);
         throw new Error(`Comparison failed: ${error.error}`);
     }
     return result;
 }
+/**
+ * Compare two DOCX documents with logging enabled.
+ * Returns both the redlined document and a log of any warnings/errors encountered.
+ * This allows the comparison to continue past recoverable issues (like orphaned footnotes)
+ * while providing visibility into what was fixed or skipped.
+ *
+ * @param original - Original DOCX document
+ * @param modified - Modified DOCX document
+ * @param options - Comparison options
+ * @returns Result with document bytes and log entries
+ *
+ * @example
+ * ```typescript
+ * const result = await compareDocumentsWithLog(original, modified, {
+ *   authorName: "Reviewer",
+ *   detailThreshold: 0.15
+ * });
+ *
+ * if (result.success) {
+ *   // Use result.document (Uint8Array)
+ *   if (result.hasWarnings) {
+ *     console.log("Warnings during comparison:");
+ *     for (const entry of result.log) {
+ *       console.log(`  [${entry.level}] ${entry.code}: ${entry.message}`);
+ *     }
+ *   }
+ * } else {
+ *   console.error(`Comparison failed: ${result.error}`);
+ * }
+ * ```
+ */
+export async function compareDocumentsWithLog(original, modified, options) {
+    const exports = ensureInitialized();
+    const originalBytes = await toBytes(original);
+    const modifiedBytes = await toBytes(modified);
+    await yieldToMain();
+    const result = exports.DocumentComparer.CompareDocumentsWithLog(originalBytes, modifiedBytes, options?.authorName ?? "Docxodus", options?.detailThreshold ?? 0.15, options?.caseInsensitive ?? false);
+    const parsed = JSON.parse(result);
+    return {
+        success: parsed.Success ?? parsed.success ?? false,
+        document: parsed.DocumentBase64 || parsed.documentBase64
+            ? Uint8Array.from(atob(parsed.DocumentBase64 || parsed.documentBase64), c => c.charCodeAt(0))
+            : undefined,
+        error: parsed.Error ?? parsed.error,
+        log: convertLogEntries(parsed.Log || parsed.log || []),
+        hasWarnings: parsed.HasWarnings ?? parsed.hasWarnings ?? false,
+        hasErrors: parsed.HasErrors ?? parsed.hasErrors ?? false,
+    };
+}
+/**
+ * Compare two DOCX documents to HTML with logging enabled.
+ * Returns both the HTML output and a log of any warnings/errors encountered.
+ *
+ * @param original - Original DOCX document
+ * @param modified - Modified DOCX document
+ * @param options - Comparison options
+ * @returns Result with HTML and log entries
+ *
+ * @example
+ * ```typescript
+ * const result = await compareDocumentsToHtmlWithLog(original, modified, {
+ *   authorName: "Reviewer",
+ *   renderTrackedChanges: true
+ * });
+ *
+ * if (result.success) {
+ *   document.getElementById("viewer").innerHTML = result.html;
+ *   if (result.hasWarnings) {
+ *     console.log(`${result.log.length} warnings during comparison`);
+ *   }
+ * }
+ * ```
+ */
+export async function compareDocumentsToHtmlWithLog(original, modified, options) {
+    const exports = ensureInitialized();
+    const originalBytes = await toBytes(original);
+    const modifiedBytes = await toBytes(modified);
+    await yieldToMain();
+    const result = exports.DocumentComparer.CompareDocumentsToHtmlWithLog(originalBytes, modifiedBytes, options?.authorName ?? "Docxodus", options?.detailThreshold ?? 0.15, options?.caseInsensitive ?? false, options?.renderTrackedChanges ?? true);
+    const parsed = JSON.parse(result);
+    return {
+        success: parsed.Success ?? parsed.success ?? false,
+        html: parsed.Html ?? parsed.html,
+        error: parsed.Error ?? parsed.error,
+        log: convertLogEntries(parsed.Log || parsed.log || []),
+        hasWarnings: parsed.HasWarnings ?? parsed.hasWarnings ?? false,
+        hasErrors: parsed.HasErrors ?? parsed.hasErrors ?? false,
+    };
+}
+/**
+ * Convert log entries from PascalCase to camelCase.
+ */
+function convertLogEntries(entries) {
+    return entries.map((e) => ({
+        level: e.Level ?? e.level ?? "Info",
+        code: e.Code ?? e.code ?? "",
+        message: e.Message ?? e.message ?? "",
+        details: e.Details ?? e.details,
+        location: e.Location ?? e.location,
+    }));
+}
 /**
  * Get revisions from a compared document.
  *
@@ -1329,4 +1436,170 @@ function convertExternalAnnotationSet(parsed) {
         docLabelDefinitions,
     };
 }
+// ============================================================================
+// Incremental Annotation Overlay API (Issue #106)
+// ============================================================================
+/**
+ * Project external annotations onto already-converted HTML.
+ * This avoids full DOCX re-conversion when only annotations change.
+ *
+ * Workflow:
+ * 1. Convert DOCX to HTML once using `convertDocxToHtml()`
+ * 2. Use this function to overlay annotations on the cached HTML
+ * 3. When annotations change, call this again with the same base HTML
+ *
+ * @param html - HTML string (previously converted via convertDocxToHtml)
+ * @param annotationSet - The external annotation set to project
+ * @param projectionOptions - Projection settings (CSS prefix, label mode, etc.)
+ * @returns HTML string with annotations projected
+ * @throws Error if projection fails
+ *
+ * @example
+ * ```typescript
+ * // Step 1: Convert once
+ * const baseHtml = await convertDocxToHtml(docxFile);
+ *
+ * // Step 2: Project annotations (fast, no DOCX re-conversion)
+ * const annotatedHtml = await projectAnnotationsOntoHtml(baseHtml, annotationSet);
+ *
+ * // Step 3: When annotations change, project again on the same base HTML
+ * annotationSet.labelledText.push(newAnnotation);
+ * const updatedHtml = await projectAnnotationsOntoHtml(baseHtml, annotationSet);
+ * ```
+ */
+export async function projectAnnotationsOntoHtml(html, annotationSet, projectionOptions) {
+    const exports = ensureInitialized();
+    await yieldToMain();
+    const annotationSetJson = JSON.stringify(annotationSet);
+    const result = exports.DocumentConverter.ProjectAnnotationsOntoHtml(html, annotationSetJson, projectionOptions?.cssClassPrefix ?? "ext-annot-", projectionOptions?.labelMode ?? AnnotationLabelMode.Above);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to project annotations: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return parsed.Html ?? parsed.html;
+}
+/**
+ * Add a single annotation to existing HTML without re-converting the document.
+ * This is the fastest way to add one annotation to already-rendered HTML.
+ *
+ * @param html - HTML string (with or without existing annotations)
+ * @param annotation - The annotation to add
+ * @param label - Label definition for the annotation (optional, for color/text)
+ * @param projectionOptions - Projection settings
+ * @returns HTML string with the annotation added
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const annotation = createAnnotation("ann-new", "CLAUSE", set.content, 100, 150);
+ * const label = { id: "CLAUSE", text: "Clause", color: "#FF5722" };
+ * const updatedHtml = await addAnnotationToHtml(currentHtml, annotation, label);
+ * ```
+ */
+export async function addAnnotationToHtml(html, annotation, label, projectionOptions) {
+    const exports = ensureInitialized();
+    await yieldToMain();
+    const annotationJson = JSON.stringify(annotation);
+    const labelJson = label ? JSON.stringify(label) : "";
+    const result = exports.DocumentConverter.AddAnnotationToHtml(html, annotationJson, labelJson, projectionOptions?.cssClassPrefix ?? "ext-annot-", projectionOptions?.labelMode ?? AnnotationLabelMode.Above);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to add annotation to HTML: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return parsed.Html ?? parsed.html;
+}
+/**
+ * Remove a single annotation from HTML by annotation ID.
+ * Unwraps annotation spans back to plain text.
+ *
+ * @param html - HTML string with annotations
+ * @param annotationId - ID of the annotation to remove
+ * @param cssClassPrefix - CSS class prefix used for annotations (default: "ext-annot-")
+ * @returns HTML string with the annotation removed
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const updatedHtml = await removeAnnotationFromHtml(currentHtml, "ann-001");
+ * ```
+ */
+export async function removeAnnotationFromHtml(html, annotationId, cssClassPrefix) {
+    const exports = ensureInitialized();
+    await yieldToMain();
+    const result = exports.DocumentConverter.RemoveAnnotationFromHtml(html, annotationId, cssClassPrefix ?? "ext-annot-");
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to remove annotation from HTML: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return parsed.Html ?? parsed.html;
+}
+/**
+ * Generate CSS to hide annotations with specific label IDs.
+ * Enables CSS-based label filtering without re-rendering HTML.
+ *
+ * Apply the returned CSS to your document (e.g., via a `<style>` element)
+ * to hide/show annotations by label. This is much faster than re-projecting
+ * all annotations.
+ *
+ * @param hiddenLabelIds - Array of label IDs to hide
+ * @param cssClassPrefix - CSS class prefix (default: "ext-annot-")
+ * @returns CSS string that hides the specified labels
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * // Hide annotations with label "DRAFT" and "INTERNAL"
+ * const css = await generateAnnotationVisibilityCss(["DRAFT", "INTERNAL"]);
+ *
+ * // Apply to a <style> element in the DOM
+ * const styleEl = document.getElementById("visibility-overrides");
+ * styleEl.textContent = css;
+ *
+ * // To show all annotations again, clear the style:
+ * styleEl.textContent = "";
+ * ```
+ */
+export async function generateAnnotationVisibilityCss(hiddenLabelIds, cssClassPrefix) {
+    const exports = ensureInitialized();
+    await yieldToMain();
+    const result = exports.DocumentConverter.GenerateAnnotationVisibilityCss(JSON.stringify(hiddenLabelIds), cssClassPrefix ?? "ext-annot-");
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to generate visibility CSS: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return parsed.Css ?? parsed.css;
+}
+/**
+ * Generate annotation CSS for a set of labels.
+ * Useful when managing CSS separately from HTML content.
+ *
+ * @param labels - Label definitions (keyed by label ID)
+ * @param projectionOptions - Projection settings
+ * @returns CSS string for the annotation styles
+ * @throws Error if operation fails
+ *
+ * @example
+ * ```typescript
+ * const labels = {
+ *   "CLAUSE": { id: "CLAUSE", text: "Clause", color: "#FF5722" },
+ *   "TERM": { id: "TERM", text: "Term", color: "#2196F3" },
+ * };
+ * const css = await generateAnnotationCss(labels);
+ * ```
+ */
+export async function generateAnnotationCss(labels, projectionOptions) {
+    const exports = ensureInitialized();
+    await yieldToMain();
+    const result = exports.DocumentConverter.GenerateAnnotationCss(JSON.stringify(labels), projectionOptions?.cssClassPrefix ?? "ext-annot-", projectionOptions?.labelMode ?? AnnotationLabelMode.Above);
+    if (isErrorResponse(result)) {
+        const error = parseError(result);
+        throw new Error(`Failed to generate annotation CSS: ${error.error}`);
+    }
+    const parsed = JSON.parse(result);
+    return parsed.Css ?? parsed.css;
+}
 //# sourceMappingURL=index.js.map