@dragon708/docmind-browser 1.2.0 → 1.5.0

package/dist/index.d.ts

@@ -1,17 +1,30 @@
 import { DocMindAnalyzeOptions, AnalysisResult, FileKind, RuntimeDescriptor, DocMindPublicIntent, AnalysisAnalyzer, ProcessingPlanDescriptor, ExplainAnalysisPlanOptions, GetCapabilitiesOptions } from '@dragon708/docmind-shared';
 export { AnalysisAnalyzer, AnalysisResult, CapabilityDescriptor, DetectFileKindInput, DocMindPublicIntent, DocxAnalysisCoreResult, ExplainAnalysisPlanOptions, ExplainAnalysisPlanResult, FileKind, FileKindMetadata, GenericAnalysisResult, GetCapabilitiesOptions, GetCapabilitiesResult, ImageAnalysisCoreResult, PdfAnalysisCoreResult, TextAnalysisResult, detectFileKind } from '@dragon708/docmind-shared';
-import { OcrOptions } from '@dragon708/docmind-ocr';
+import { OcrOptions, OcrTiffOptions, PreprocessImageOptions } from '@dragon708/docmind-ocr';
+import { AnalyzeDocxIncludeFlags, DocxToHtmlOptions } from '@dragon708/docmind-docx';
+export { AnalyzeDocxIncludeFlags } from '@dragon708/docmind-docx';
 
+/**
+ * Opciones DOCX para el facade browser (Mammoth + inclusiones v2 de `@dragon708/docmind-docx`; sin APIs Node-only).
+ */
+interface BrowserAnalyzeDocxOptionsSlice {
+    readonly include?: AnalyzeDocxIncludeFlags;
+    readonly html?: DocxToHtmlOptions;
+}
 /**
  * OCR behavior for browser intents that touch raster images.
  * - `off`: do not invoke Tesseract; text stays empty with an explanatory warning.
  * - `auto` (default): run OCR when the input is classified as an image.
  * - `force`: same as `auto` in the browser runtime (no PDF-style text layer to compare); reserved for parity with Node.
+ *
+ * Multipage TIFF (when sniffed): `maxPages` and `pageSeparator` match `OcrTiffOptions` in `@dragon708/docmind-ocr` (best-effort UTIF in-browser).
+ * Optional {@link PreprocessImageOptions} runs in-browser (canvas) on the normalized raster before Tesseract when using `ocrImageDetailed`.
  */
 type BrowserOcrMode = "off" | "auto" | "force";
-/** Browser OCR options: Tesseract knobs from `@dragon708/docmind-ocr` plus optional {@link BrowserOcrMode}. */
-interface BrowserOcrOptions extends OcrOptions {
+/** Browser OCR options: Tesseract knobs from `@dragon708/docmind-ocr` plus optional {@link BrowserOcrMode}, TIFF caps, and canvas preprocess. */
+interface BrowserOcrOptions extends OcrOptions, Pick<OcrTiffOptions, "maxPages" | "pageSeparator"> {
     readonly mode?: BrowserOcrMode;
+    readonly preprocess?: PreprocessImageOptions;
 }
 /**
  * Options for public browser methods (`analyzeFile`, intent APIs).
@@ -20,6 +33,8 @@ interface BrowserOcrOptions extends OcrOptions {
 interface BrowserAnalyzeOptions extends DocMindAnalyzeOptions {
     /** Image OCR only; no PDF in this runtime. See {@link BrowserOcrOptions.mode}. */
     readonly ocr?: BrowserOcrOptions;
+    /** Solo DOCX: ver {@link BrowserAnalyzeDocxOptionsSlice}. */
+    readonly docx?: BrowserAnalyzeDocxOptionsSlice;
 }
 
 /**
@@ -56,10 +71,49 @@ declare function extractMetadata(input: BrowserAnalyzeInput, options?: BrowserAn
 declare function convertToHtml(input: BrowserAnalyzeInput, options?: BrowserAnalyzeOptions): Promise<AnalysisResult>;
 /**
  * OCR-focused intent. Honors {@link BrowserAnalyzeOptions.ocr} **mode** (`off` | `auto` | `force`) for images.
+ * Raster path uses `normalizeImageForOcr` via `ocrImageDetailed` (or `ocrTiff` for TIFF); no Node-only libraries.
+ * HEIC/HEIF and hard failures yield empty text + warnings instead of throwing (abort still propagates).
  * DOCX returns structured extract with a notice (no OCR). Text decodes as UTF-8 (no OCR).
  */
 declare function runOcr(input: BrowserAnalyzeInput, options?: BrowserAnalyzeOptions): Promise<AnalysisResult>;
 
+/** High-level features the user can ask DocMind for (per input kind and runtime). */
+type PublicCapabilityId = "text" | "metadata" | "html" | "ocr" | "pages" | "image-normalization" | "gif-first-frame" | "bmp" | "heic" | "tiff";
+declare function docxIncludeRequested(flags?: AnalyzeDocxIncludeFlags): boolean;
+/** DOCX `word/media` en runtime browser (JSZip; sin pipeline Node). */
+interface DocxEmbeddedImageCapabilities {
+    readonly canExtractEmbeddedImages: true;
+    readonly documentsMayIncludeImagesRequiringWebConversion: true;
+    /** En browser no hay conversión EMF/WMF a PNG empaquetada; `convertDocxEmbeddedImageToWeb` devuelve bytes originales + avisos. */
+    readonly webFriendlyRasterConversionInBrowser: false;
+    readonly notes: readonly string[];
+}
+declare const DOCX_EMBEDDED_IMAGE_CAPABILITIES_BROWSER: DocxEmbeddedImageCapabilities;
+interface DocxStructuralCapabilities {
+    readonly ooxmlExtractorsAvailable: true;
+    readonly activatedViaDocxInclude: true;
+    readonly features: readonly string[];
+    readonly notes: readonly string[];
+}
+declare const DOCX_STRUCTURE_CAPABILITIES_BROWSER: DocxStructuralCapabilities;
+/** Whether a {@link PublicCapabilityId} applies to the detected file in this runtime. */
+interface PublicCapabilitySupport {
+    readonly id: PublicCapabilityId;
+    readonly supported: boolean;
+    readonly warnings?: readonly string[];
+}
+/**
+ * Result of {@link getCapabilities}: detected kind, runtime id, per-feature support for this input, and optional global warnings.
+ */
+interface GetCapabilitiesReport {
+    readonly kind: FileKind;
+    readonly runtime: RuntimeDescriptor;
+    readonly capabilities: readonly PublicCapabilitySupport[];
+    readonly docxEmbeddedImages?: DocxEmbeddedImageCapabilities;
+    readonly docxStructure?: DocxStructuralCapabilities;
+    readonly warnings?: readonly string[];
+}
+
 /**
  * Whether DocMind will try a non-OCR text/HTML path (e.g. Mammoth, UTF-8, PDF text layer — when available).
  */
@@ -91,40 +145,24 @@ interface ExplainAnalysisPlanReport {
     readonly limitations: readonly string[];
     /** Ordered pipeline steps (planned/skipped/done metadata only). */
     readonly plan: ProcessingPlanDescriptor;
+    readonly docxEmbeddedImages?: DocxEmbeddedImageCapabilities;
+    readonly docxStructure?: DocxStructuralCapabilities;
     readonly warnings?: readonly string[];
 }
 
-/** High-level features the user can ask DocMind for (per input kind and runtime). */
-type PublicCapabilityId = "text" | "metadata" | "html" | "ocr" | "pages";
-/** Whether a {@link PublicCapabilityId} applies to the detected file in this runtime. */
-interface PublicCapabilitySupport {
-    readonly id: PublicCapabilityId;
-    readonly supported: boolean;
-    readonly warnings?: readonly string[];
-}
-/**
- * Result of {@link getCapabilities}: detected kind, runtime id, per-feature support for this input, and optional global warnings.
- */
-interface GetCapabilitiesReport {
-    readonly kind: FileKind;
-    readonly runtime: RuntimeDescriptor;
-    readonly capabilities: readonly PublicCapabilitySupport[];
-    readonly warnings?: readonly string[];
-}
-
-/** Options for {@link explainAnalysisPlan}: shared fields plus optional `ocr` for accurate OCR-step preview. */
-type BrowserExplainAnalysisPlanOptions = ExplainAnalysisPlanOptions & Pick<BrowserAnalyzeOptions, "ocr">;
+/** Options for {@link explainAnalysisPlan}: shared fields plus optional `ocr` / `docx` for accurate step preview. */
+type BrowserExplainAnalysisPlanOptions = ExplainAnalysisPlanOptions & Pick<BrowserAnalyzeOptions, "ocr" | "docx">;
 
 /**
  * Epic 1 — **Capabilities:** detects kind from the same hints as `analyzeFile`, then lists which of
- * `text` | `metadata` | `html` | `ocr` | `pages` apply in the browser (PDF always unsupported).
- * No Mammoth/Tesseract/PDF parsing.
+ * `text` | `metadata` | `html` | `ocr` | `pages` and image-specific ids (`image-normalization`, `bmp`, `gif-first-frame`, `heic`, `tiff`) apply in the browser (PDF always unsupported).
+ * No Mammoth/Tesseract/PDF parsing. For DOCX, {@link GetCapabilitiesReport.docxStructure} / `docxEmbeddedImages` describe v2 opt-in features.
  */
 declare function getCapabilities(input: BrowserAnalyzeInput, options?: GetCapabilitiesOptions): Promise<GetCapabilitiesReport>;
 /**
  * Epic 1 — **Plan preview:** structured explanation (analyzer, native extraction vs OCR, `limitations`, `plan.steps`)
- * for a {@link DocMindPublicIntent}. Optional `ocr` in options refines image steps. No heavy I/O.
+ * for a {@link DocMindPublicIntent}. Optional `ocr` refines image steps; optional `docx.include` adds planned OOXML parallel steps for DOCX. No heavy I/O.
  */
 declare function explainAnalysisPlan(input: BrowserAnalyzeInput, options?: BrowserExplainAnalysisPlanOptions): Promise<ExplainAnalysisPlanReport>;
 
-export { BROWSER_PDF_UNSUPPORTED_WARNING, type BrowserAnalyzeInput, type BrowserAnalyzeOptions, type BrowserExplainAnalysisPlanOptions, type BrowserOcrMode, type BrowserOcrOptions, type ExplainAnalysisPlanReport, type GetCapabilitiesReport, type NativeExtractionPlan, type OcrPlan, type PublicCapabilityId, type PublicCapabilitySupport, analyzeFile, convertToHtml, explainAnalysisPlan, extractMetadata, extractText, getCapabilities, runOcr };
+export { BROWSER_PDF_UNSUPPORTED_WARNING, type BrowserAnalyzeDocxOptionsSlice, type BrowserAnalyzeInput, type BrowserAnalyzeOptions, type BrowserExplainAnalysisPlanOptions, type BrowserOcrMode, type BrowserOcrOptions, DOCX_EMBEDDED_IMAGE_CAPABILITIES_BROWSER, DOCX_STRUCTURE_CAPABILITIES_BROWSER, type DocxEmbeddedImageCapabilities, type DocxStructuralCapabilities, type ExplainAnalysisPlanReport, type GetCapabilitiesReport, type NativeExtractionPlan, type OcrPlan, type PublicCapabilityId, type PublicCapabilitySupport, analyzeFile, convertToHtml, docxIncludeRequested, explainAnalysisPlan, extractMetadata, extractText, getCapabilities, runOcr };

package/dist/index.js

@@ -1,7 +1,7 @@
-import { assertValidAnalyzeFileInput, detectFileKind, notImplementedResult, UNKNOWN_FORMAT_WARNING, analyzeText, toUint8Array, InvalidInputError } from '@dragon708/docmind-shared';
+import { assertValidAnalyzeFileInput, detectFileKind, notImplementedResult, UNKNOWN_FORMAT_WARNING, analyzeText, toUint8Array, InvalidInputError, getMimeType } from '@dragon708/docmind-shared';
 export { detectFileKind } from '@dragon708/docmind-shared';
 import { analyzeDocx } from '@dragon708/docmind-docx';
-import { ocr } from '@dragon708/docmind-ocr';
+import { preprocessHasEffect, resolveImageFormat, normalizeImageForOcr, ocrTiff, ocrImageDetailed } from '@dragon708/docmind-ocr';
 
 // src/analyzeFile.ts
 function assertBrowserInput(input) {
@@ -22,7 +22,41 @@ function prepareBrowserAnalyzeInput(input) {
   assertValidAnalyzeFileInput(input);
   return input;
 }
-async function analyzeDocxForBrowser(input, signal) {
+
+// src/docxBrowserMapper.ts
+function analyzeDocxOptionsFromBrowser(options) {
+  const sig = options?.signal;
+  const dx = options?.docx;
+  if (!dx?.include && !dx?.html && !sig) return void 0;
+  const out = { ...dx?.html ?? {} };
+  if (dx?.include) out.include = dx.include;
+  if (sig) out.signal = sig;
+  return out;
+}
+function docxPackageResultToAnalysisResult(r) {
+  const base = {
+    fileKind: "docx",
+    analyzer: "docx",
+    status: "ok",
+    kind: "docx",
+    text: r.text,
+    html: r.html,
+    warnings: [...r.warnings]
+  };
+  const v2 = {
+    ...r.structure !== void 0 ? { structure: r.structure } : {},
+    ...r.headings !== void 0 ? { headings: r.headings } : {},
+    ...r.tables !== void 0 ? { tables: r.tables } : {},
+    ...r.blocks !== void 0 ? { blocks: r.blocks } : {},
+    ...r.pagesApprox !== void 0 ? { pagesApprox: r.pagesApprox } : {},
+    ...r.embeddedImages !== void 0 ? { embeddedImages: r.embeddedImages } : {}
+  };
+  return { ...base, ...v2 };
+}
+
+// src/analyzers/docx.ts
+async function analyzeDocxForBrowser(input, options) {
+  const signal = options?.signal;
   if (signal?.aborted) {
     const err = new Error("The operation was aborted");
     err.name = "AbortError";
@@ -40,17 +74,97 @@ async function analyzeDocxForBrowser(input, signal) {
       warnings: ["No document bytes were provided for analysis."]
     };
   }
-  const r = await analyzeDocx(data);
-  return {
-    fileKind: "docx",
-    analyzer: "docx",
-    status: "ok",
-    kind: "docx",
-    text: r.text,
-    html: r.html,
-    warnings: [...r.warnings]
-  };
+  const docxOpts = analyzeDocxOptionsFromBrowser(options);
+  const r = docxOpts !== void 0 ? await analyzeDocx(data, docxOpts) : await analyzeDocx(data);
+  return docxPackageResultToAnalysisResult(r);
+}
+var BROWSER_TIFF_BEST_EFFORT_WARNING = "Browser TIFF support is best-effort: decoding uses UTIF in JavaScript/WebAssembly\u2014some compressions, color modes, very large or multipage files may fail, hang, or exhaust memory. For heavy TIFF workloads use @dragon708/docmind-node (optional sharp).";
+function meanPageConfidence(pages) {
+  if (pages.length === 0) return 0;
+  return pages.reduce((s, p) => s + p.confidence, 0) / pages.length;
+}
+function rethrowIfAbort(e) {
+  if (e instanceof Error && e.name === "AbortError") throw e;
+}
+function ocrFailureWarnings(prefix, e) {
+  const msg = e instanceof Error ? e.message : String(e);
+  return [`${prefix} ${msg}`];
+}
+async function runRasterOcrForBrowser(data, input, options) {
+  const signal = options?.ocr?.signal ?? options?.signal;
+  const langs = options?.ocr?.langs;
+  const mimeHint = getMimeType(input);
+  const format = resolveImageFormat(data, mimeHint);
+  if (format === "heic" || format === "heif") {
+    const norm = await normalizeImageForOcr(data, { signal, mimeHint });
+    return {
+      text: "",
+      confidence: 0,
+      ocrUsed: true,
+      warnings: [
+        "HEIC/HEIF cannot be OCR'd in the browser; convert to PNG or JPEG server-side (e.g. @dragon708/docmind-node with sharp), then retry.",
+        ...norm.warnings
+      ],
+      inputFormat: norm.format,
+      normalizedFormat: norm.normalizedFormat
+    };
+  }
+  if (format === "tiff") {
+    try {
+      const tiff = await ocrTiff(data, {
+        langs,
+        signal,
+        maxPages: options?.ocr?.maxPages,
+        pageSeparator: options?.ocr?.pageSeparator
+      });
+      return {
+        text: tiff.text.trim(),
+        confidence: meanPageConfidence(tiff.textByPage),
+        ocrUsed: true,
+        warnings: [BROWSER_TIFF_BEST_EFFORT_WARNING, ...tiff.warnings],
+        pages: tiff.pagesProcessed,
+        textByPage: tiff.textByPage
+      };
+    } catch (e) {
+      rethrowIfAbort(e);
+      return {
+        text: "",
+        confidence: 0,
+        ocrUsed: true,
+        warnings: [
+          BROWSER_TIFF_BEST_EFFORT_WARNING,
+          ...ocrFailureWarnings("TIFF OCR failed in the browser:", e)
+        ]
+      };
+    }
+  }
+  try {
+    const detailed = await ocrImageDetailed(data, {
+      langs,
+      signal,
+      preprocess: options?.ocr?.preprocess
+    });
+    return {
+      text: detailed.text.trim(),
+      confidence: detailed.confidence,
+      ocrUsed: true,
+      warnings: [...detailed.warnings],
+      pages: detailed.pages,
+      inputFormat: detailed.inputFormat,
+      normalizedFormat: detailed.normalizedFormat
+    };
+  } catch (e) {
+    rethrowIfAbort(e);
+    return {
+      text: "",
+      confidence: 0,
+      ocrUsed: true,
+      warnings: ocrFailureWarnings("OCR could not complete in the browser:", e)
+    };
+  }
 }
+
+// src/analyzers/image.ts
 var OCR_OFF_WARNING = 'OCR mode is "off"; no recognition was run. Use mode "auto" or "force" to extract text from images.';
 function resolveOcrMode(options) {
   return options?.ocr?.mode ?? "auto";
@@ -87,21 +201,26 @@ async function analyzeImageForBrowser(input, options) {
       warnings: [OCR_OFF_WARNING]
     };
   }
-  const ocrOpts = {
-    ...options?.ocr ?? {},
-    signal: options?.ocr?.signal ?? options?.signal
-  };
-  const r = await ocr(data, ocrOpts);
-  return {
+  const ocrPart = await runRasterOcrForBrowser(data, input, options);
+  const base = {
     fileKind: "image",
     analyzer: "image",
     status: "ok",
     kind: "image",
-    text: r.text,
-    confidence: r.confidence,
-    ocrUsed: r.ocrUsed,
-    warnings: []
+    text: ocrPart.text,
+    confidence: ocrPart.confidence,
+    ocrUsed: true,
+    warnings: ocrPart.warnings
   };
+  const extra = {};
+  if (ocrPart.pages !== void 0) extra.pages = ocrPart.pages;
+  if (ocrPart.textByPage !== void 0) extra.textByPage = ocrPart.textByPage;
+  if (ocrPart.inputFormat !== void 0) extra.inputFormat = ocrPart.inputFormat;
+  if (ocrPart.normalizedFormat !== void 0) extra.normalizedFormat = ocrPart.normalizedFormat;
+  if (Object.keys(extra).length > 0) {
+    return { ...base, ...extra };
+  }
+  return base;
 }
 
 // src/analyzeFile.ts
@@ -120,7 +239,7 @@ async function analyzeFile(input, options) {
     case "pdf":
       return notImplementedResult("pdf", "pdf", [BROWSER_PDF_UNSUPPORTED_WARNING]);
     case "docx":
-      return analyzeDocxForBrowser(bytesInput, options?.signal);
+      return analyzeDocxForBrowser(bytesInput, options);
     case "image":
       return analyzeImageForBrowser(bytesInput, options);
     case "text":
@@ -129,7 +248,7 @@ async function analyzeFile(input, options) {
       return notImplementedResult(fileKind, "none", [UNKNOWN_FORMAT_WARNING]);
   }
 }
-var DOCX_METADATA_STUB = "Structured document metadata for DOCX is not exposed as a separate API; use extractText or analyzeFile.";
+var DOCX_METADATA_STUB = "Structured document metadata for DOCX is not returned by extractMetadata; use analyzeFile, extractText, or convertToHtml with options.docx.include for OOXML structure, headings, tables, blocks, approximate pages, and embedded images.";
 var IMAGE_METADATA_NOTE = "Raster images have no document metadata bundle in this API.";
 function escapeHtmlMinimal(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -243,19 +362,16 @@ async function runOcr(input, options) {
           warnings: ["No document bytes were provided for analysis."]
         };
       }
-      const r = await analyzeDocx(data);
-      return {
-        fileKind: "docx",
-        analyzer: "docx",
-        status: "ok",
-        kind: "docx",
-        text: r.text,
-        html: r.html,
+      const opt = analyzeDocxOptionsFromBrowser(options);
+      const raw = opt !== void 0 ? await analyzeDocx(data, opt) : await analyzeDocx(data);
+      const withNote = {
+        ...raw,
         warnings: [
-          ...r.warnings,
+          ...raw.warnings,
           "OCR does not apply to DOCX; returned structured text/HTML extract."
         ]
       };
+      return docxPackageResultToAnalysisResult(withNote);
     }
     case "text":
       return analyzeText(bytesInput, { signal });
@@ -264,16 +380,164 @@ async function runOcr(input, options) {
   }
 }
 
+// src/capabilityReport.ts
+function docxIncludeRequested(flags) {
+  if (!flags) return false;
+  return !!(flags.structure || flags.headings || flags.tables || flags.blocks || flags.pagesApprox || flags.embeddedImages);
+}
+var DOCX_EMBEDDED_IMAGE_CAPABILITIES_BROWSER = {
+  canExtractEmbeddedImages: true,
+  documentsMayIncludeImagesRequiringWebConversion: true,
+  webFriendlyRasterConversionInBrowser: false,
+  notes: [
+    "`extractImagesFromDocx` from `@dragon708/docmind-docx` runs in-browser on the same ZIP bytes as Mammoth.",
+    "PNG, JPEG, GIF, WebP, SVG, TIFF, BMP, ICO are browser-embeddable; EMF/WMF need an external converter or server-side Node tooling."
+  ]
+};
+var DOCX_STRUCTURE_CAPABILITIES_BROWSER = {
+  ooxmlExtractorsAvailable: true,
+  activatedViaDocxInclude: true,
+  features: [
+    "OOXML structure (body blocks)",
+    "headings",
+    "tables",
+    "semantic blocks",
+    "approximate pages (OOXML page-break hints)",
+    "embedded images (word/media; mode web/both still browser-safe but EMF/WMF stay non-raster without a converter)"
+  ],
+  notes: [
+    "Use options.docx.include on analyzeFile, extractText, convertToHtml, or runOcr to merge Mammoth with selected `@dragon708/docmind-docx` extractors.",
+    "extractMetadata for DOCX stays a stub in the browser facade."
+  ]
+};
+var DOCX_META = "Structured document metadata is not exposed separately in the browser runtime; extractMetadata returns a stub for DOCX.";
+var IMAGE_META = "Raster images have no document metadata bundle; extractMetadata returns a stub.";
+var IMAGE_HTML = "No layout HTML for raster images; use extractText or runOcr for text.";
+var TEXT_META_NOTE = "Plain text has no structured document metadata; extractMetadata still returns decoded content.";
+var OCR_OFF_NOTE = 'Image OCR may be skipped when `ocr.mode` is "off" in analyze options.';
+var UNKNOWN_KIND = "Could not determine file kind from name, MIME, or bytes; all features are reported as unsupported until the kind is known.";
+function slot(id, supported, warnings) {
+  return warnings?.length ? { id, supported, warnings } : { id, supported };
+}
+function buildBrowserCapabilityReport(kind) {
+  const runtime = { id: "browser" };
+  const pdf = BROWSER_PDF_UNSUPPORTED_WARNING;
+  let capabilities;
+  const topWarnings = [];
+  switch (kind) {
+    case "pdf":
+      capabilities = [
+        slot("text", false, [pdf]),
+        slot("metadata", false, [pdf]),
+        slot("html", false, [pdf]),
+        slot("ocr", false, [pdf]),
+        slot("pages", false, [pdf])
+      ];
+      break;
+    case "docx":
+      capabilities = [
+        slot("text", true, [
+          "Mammoth plain text in analyzeFile; extractText clears html. Optional OOXML fields merge when options.docx.include is set."
+        ]),
+        slot("metadata", false, [
+          `${DOCX_META} Use analyzeFile-style routes with options.docx.include for OOXML structure, headings, tables, blocks, approximate pages, and embedded images.`
+        ]),
+        slot("html", true, [
+          "Mammoth HTML in-browser; docxImagesAsDataUri for web-safe images; EMF/WMF placeholders in HTML unless you handle media separately."
+        ]),
+        slot("ocr", false, ["OCR does not apply to DOCX in DocMind."]),
+        slot("pages", false, [
+          "No PDF page count; approximate DOCX pages via options.docx.include.pagesApprox (heuristic, not print layout)."
+        ])
+      ];
+      break;
+    case "image":
+      capabilities = [
+        slot("text", true, [
+          "Text via `@dragon708/docmind-ocr` when `ocr.mode` is not off: PNG, JPEG, WebP, BMP, GIF (first frame), TIFF (partial), after sniff/MIME."
+        ]),
+        slot("metadata", false, [IMAGE_META]),
+        slot("html", false, [IMAGE_HTML]),
+        slot("ocr", true, [
+          OCR_OFF_NOTE,
+          "Uses `ocrImageDetailed` (single-frame path) or multipage `ocrTiff` for TIFF; WASM Tesseract in-browser."
+        ]),
+        slot("image-normalization", true, [
+          "`normalizeImageForOcr` runs inside the OCR package (canvas/`createImageBitmap` in-browser for BMP, GIF, etc.; not HEIC)."
+        ]),
+        slot("bmp", true, [
+          "BMP is decoded via browser canvas/`createImageBitmap` into a PNG-oriented buffer before Tesseract."
+        ]),
+        slot("gif-first-frame", true, [
+          "Animated GIF: only the first decoded frame is normalized and OCR'd; see result warnings when multi-frame is detected."
+        ]),
+        slot("heic", false, [
+          "HEIC/HEIF is not decoded in the browser. `runOcr` / `analyzeFile` return empty text with explicit warnings; convert server-side (e.g. @dragon708/docmind-node)."
+        ]),
+        slot("tiff", true, [
+          "Partial / best-effort: multipage `ocrTiff` with UTIF in JS/WASM\u2014not all compressions or huge files; prefer Node for production TIFF."
+        ]),
+        slot("pages", true, [
+          "Multipage TIFF may populate `pages` and `textByPage` when OCR succeeds; other formats may expose `pages` when normalization reports it."
+        ])
+      ];
+      break;
+    case "text":
+      capabilities = [
+        slot("text", true),
+        slot("metadata", true, [TEXT_META_NOTE]),
+        slot("html", true),
+        slot("ocr", false, ["OCR does not apply to plain text files."]),
+        slot("pages", false)
+      ];
+      break;
+    default:
+      topWarnings.push(UNKNOWN_KIND);
+      capabilities = [
+        slot("text", false),
+        slot("metadata", false),
+        slot("html", false),
+        slot("ocr", false),
+        slot("pages", false)
+      ];
+  }
+  return {
+    kind,
+    runtime,
+    capabilities,
+    ...kind === "docx" ? {
+      docxEmbeddedImages: DOCX_EMBEDDED_IMAGE_CAPABILITIES_BROWSER,
+      docxStructure: DOCX_STRUCTURE_CAPABILITIES_BROWSER
+    } : {},
+    warnings: topWarnings.length > 0 ? topWarnings : void 0
+  };
+}
+
 // src/analysisPlanReport.ts
 function lim(...items) {
   return items.filter(Boolean);
 }
-function buildBrowserExplainReport(kind, intent, ocrMode, plan) {
+var DOCX_MAMMOTH_PLUS_OPTIONAL_BROWSER = "Mammoth (`analyzeDocx`) extracts text and HTML from OOXML in-browser; optional parallel OOXML/ZIP extractors run when options.docx.include is set.";
+var DOCX_ZIP_NOTE_BROWSER = "Embedded files under word/media are available via @dragon708/docmind-docx when options.docx.include requests embeddedImages (or call extractImagesFromDocx on the same bytes).";
+var BROWSER_TIFF_RASTER_NOTE = "TIFF (if detected): multipage OCR uses `ocrTiff` with UTIF in-browser\u2014best-effort only; failures return empty text + warnings (no throw). Prefer `@dragon708/docmind-node` for production TIFF.";
+var BROWSER_IMAGE_PIPELINE = "Browser raster OCR: sniff format \u2192 `normalizeImageForOcr` (canvas/`createImageBitmap` for BMP/GIF; not HEIC) \u2192 optional `preprocessImageForOcr` when `options.ocr.preprocess` applies \u2192 Tesseract via `ocrImageDetailed`, or `ocrTiff` for TIFF. HEIC/HEIF: no decode\u2014expect empty text and explicit warnings. GIF: first frame only.";
+var BROWSER_HEIC_NOTE = "HEIC/HEIF is never decoded in-browser; there is no `sharp` dependency. Convert server-side, then OCR PNG/JPEG bytes.";
+function finalizeBrowserDocxExplainReport(report) {
+  if (report.kind !== "docx") return report;
+  const limitations = report.limitations.includes(DOCX_ZIP_NOTE_BROWSER) ? report.limitations : [...report.limitations, DOCX_ZIP_NOTE_BROWSER];
+  return {
+    ...report,
+    docxEmbeddedImages: DOCX_EMBEDDED_IMAGE_CAPABILITIES_BROWSER,
+    docxStructure: DOCX_STRUCTURE_CAPABILITIES_BROWSER,
+    limitations
+  };
+}
+function buildBrowserExplainReport(kind, intent, ocrMode, plan, docxInclude, ocrSlice) {
   const runtime = { id: "browser" };
   const imageOcrActive = ocrMode !== "off";
   let primaryAnalyzer = kind === "pdf" ? "pdf" : kind === "docx" ? "docx" : kind === "image" ? "image" : kind === "text" ? "text" : "none";
   let nativeExtraction;
-  let ocr2;
+  let ocr;
   let limitations = [];
   const ocrOffNote = ocrMode === "off" ? 'Image OCR is skipped when ocr.mode is "off".' : "";
   if (kind === "pdf") {
@@ -282,40 +546,40 @@ function buildBrowserExplainReport(kind, intent, ocrMode, plan) {
       willAttempt: false,
       description: "PDF is not processed in the browser runtime; use @dragon708/docmind-node."
     };
-    ocr2 = {
+    ocr = {
       mayUse: false,
       description: "PDF OCR is not available in the browser."
     };
-    return {
+    return finalizeBrowserDocxExplainReport({
       kind,
       detectedKind: kind,
       runtime,
       intent,
       primaryAnalyzer: "pdf",
       nativeExtraction,
-      ocr: ocr2,
+      ocr,
       limitations,
       plan,
       warnings: [BROWSER_PDF_UNSUPPORTED_WARNING]
-    };
+    });
   }
   if (kind === "unknown") {
     limitations = lim(
       "Could not classify the file from name, MIME, or bytes; analysis will return not_implemented until hints improve."
     );
     nativeExtraction = { willAttempt: false, description: "No analyzer selected without a known file kind." };
-    ocr2 = { mayUse: false, description: "OCR is not used for unknown kinds." };
-    return {
+    ocr = { mayUse: false, description: "OCR is not used for unknown kinds." };
+    return finalizeBrowserDocxExplainReport({
       kind,
       detectedKind: kind,
       runtime,
       intent,
       primaryAnalyzer: "none",
       nativeExtraction,
-      ocr: ocr2,
+      ocr,
       limitations,
       plan
-    };
+    });
   }
   switch (intent) {
     case "analyzeFile":
@@ -323,25 +587,25 @@ function buildBrowserExplainReport(kind, intent, ocrMode, plan) {
       if (kind === "docx") {
         nativeExtraction = {
           willAttempt: true,
-          description: "Mammoth reads OOXML for text" + (intent === "extractText" ? " (HTML omitted in extractText)." : " and HTML.")
+          description: docxIncludeRequested(docxInclude) ? "Mammoth plus parallel OOXML extractors (per options.docx.include)." + (intent === "extractText" ? " HTML cleared in extractText." : "") : DOCX_MAMMOTH_PLUS_OPTIONAL_BROWSER + (intent === "extractText" ? " HTML omitted in extractText." : "")
         };
-        ocr2 = { mayUse: false, description: "DOCX does not use OCR in DocMind." };
+        ocr = { mayUse: false, description: "DOCX does not use OCR in DocMind." };
       } else if (kind === "image") {
         nativeExtraction = {
           willAttempt: false,
-          description: "Raster images have no native text layer in this pipeline."
+          description: BROWSER_IMAGE_PIPELINE
         };
-        ocr2 = {
+        ocr = {
           mayUse: imageOcrActive,
-          description: imageOcrActive ? "Tesseract.js may run to recover text (subject to format support)." : "OCR skipped while ocr.mode is off."
+          description: imageOcrActive ? "`ocrImageDetailed` (normalize + optional preprocess) for single-frame paths; TIFF \u2192 `ocrTiff` (UTIF, partial). HEIC unsupported in-browser." : "OCR skipped while ocr.mode is off."
         };
-        limitations = lim(ocrOffNote);
+        limitations = lim(ocrOffNote, BROWSER_TIFF_RASTER_NOTE, BROWSER_HEIC_NOTE);
       } else {
         nativeExtraction = {
           willAttempt: true,
           description: "Plain text is decoded as UTF-8 (BOM stripped, replacement on invalid bytes)."
         };
-        ocr2 = { mayUse: false, description: "OCR does not apply to text files." };
+        ocr = { mayUse: false, description: "OCR does not apply to text files." };
       }
       break;
     case "extractMetadata":
@@ -350,16 +614,16 @@ function buildBrowserExplainReport(kind, intent, ocrMode, plan) {
           willAttempt: false,
           description: "No heavy extractor; extractMetadata returns a stub with guidance."
         };
-        ocr2 = { mayUse: false, description: "OCR is not invoked for this metadata path." };
+        ocr = { mayUse: false, description: "OCR is not invoked for this metadata path." };
         limitations = lim(
-          kind === "docx" ? "Structured DOCX metadata is not exposed separately in the browser." : "Raster images have no document metadata bundle in this API."
+          kind === "docx" ? "Structured DOCX metadata is not exposed separately in the browser; use analyzeFile / extractText / convertToHtml with options.docx.include for OOXML fields." : "Raster images have no document metadata bundle. TIFF/HEIC caveats: see getCapabilities (`tiff` partial, `heic` unsupported) and runOcr warnings."
         );
       } else {
         nativeExtraction = {
           willAttempt: true,
           description: "Plain text is decoded; metadata is limited to decoded content."
         };
-        ocr2 = { mayUse: false, description: "OCR does not apply." };
+        ocr = { mayUse: false, description: "OCR does not apply." };
         limitations = lim("Plain text has no structured document metadata.");
       }
       break;
@@ -367,23 +631,23 @@ function buildBrowserExplainReport(kind, intent, ocrMode, plan) {
       if (kind === "docx") {
         nativeExtraction = {
           willAttempt: true,
-          description: "Mammoth produces HTML; images are not passed through analyzeFile for this intent."
+          description: docxIncludeRequested(docxInclude) ? "Mammoth HTML via analyzeFile plus optional OOXML extractors." : "Mammoth HTML via analyzeFile; optional OOXML v2 when options.docx.include is set."
         };
-        ocr2 = { mayUse: false, description: "DOCX path does not use OCR." };
+        ocr = { mayUse: false, description: "DOCX path does not use OCR." };
       } else if (kind === "text") {
         nativeExtraction = {
           willAttempt: true,
           description: "UTF-8 decode then wrap in a <pre> element."
         };
-        ocr2 = { mayUse: false, description: "OCR does not apply." };
+        ocr = { mayUse: false, description: "OCR does not apply." };
       } else {
         nativeExtraction = {
           willAttempt: false,
           description: "No rich HTML path for this kind in the browser."
         };
-        ocr2 = { mayUse: false, description: "OCR does not produce layout HTML here." };
+        ocr = { mayUse: false, description: "OCR does not produce layout HTML here." };
         limitations = lim(
-          kind === "image" ? "Raster images have no HTML representation; use extractText or runOcr." : ""
+          kind === "image" ? "Raster images have no HTML representation; use extractText or runOcr. Expect HEIC to yield warnings only; TIFF is best-effort." : ""
         );
       }
       break;
@@ -391,120 +655,77 @@ function buildBrowserExplainReport(kind, intent, ocrMode, plan) {
       if (kind === "image") {
         nativeExtraction = {
           willAttempt: false,
-          description: "No native text layer; recognition is OCR-only."
+          description: BROWSER_IMAGE_PIPELINE
         };
-        ocr2 = {
+        ocr = {
           mayUse: imageOcrActive,
-          description: imageOcrActive ? "Tesseract.js runs for raster text." : "OCR skipped while ocr.mode is off."
+          description: imageOcrActive ? "Same as analyzeFile: `normalizeImageForOcr` inside `ocrImageDetailed`, optional canvas preprocess, or `ocrTiff` for TIFF. Errors surface as warnings, not uncaught exceptions (except abort)." : "OCR skipped while ocr.mode is off."
         };
-        limitations = lim(ocrOffNote);
+        limitations = lim(ocrOffNote, BROWSER_TIFF_RASTER_NOTE, BROWSER_HEIC_NOTE);
       } else if (kind === "docx") {
         nativeExtraction = {
           willAttempt: true,
-          description: "Mammoth returns structured text/HTML (OCR does not apply to DOCX)."
+          description: docxIncludeRequested(docxInclude) ? "Mammoth text/HTML plus optional OOXML extractors; not OCR." : "Mammoth text/HTML; optional OOXML v2 via options.docx.include; not OCR."
         };
-        ocr2 = { mayUse: false, description: "DOCX is not OCR'd." };
+        ocr = { mayUse: false, description: "DOCX is not OCR'd." };
         limitations = lim("Returned content is structured extract, not OCR output.");
       } else {
         nativeExtraction = {
           willAttempt: true,
           description: "Plain text is UTF-8 decoded only."
         };
-        ocr2 = { mayUse: false, description: "OCR does not apply to text files." };
+        ocr = { mayUse: false, description: "OCR does not apply to text files." };
       }
       break;
     default:
       nativeExtraction = { willAttempt: false, description: "Intent not specialized in this runtime." };
-      ocr2 = { mayUse: false, description: "See plan steps." };
+      ocr = { mayUse: false, description: "See plan steps." };
   }
-  return {
+  if (kind === "image" && preprocessHasEffect(ocrSlice?.preprocess)) {
+    limitations = [
+      ...limitations,
+      "options.ocr.preprocess applies to the `ocrImageDetailed` path only; multipage TIFF (`ocrTiff`) does not run preprocess per frame."
+    ];
+  }
+  return finalizeBrowserDocxExplainReport({
     kind,
     detectedKind: kind,
     runtime,
     intent,
     primaryAnalyzer,
     nativeExtraction,
-    ocr: ocr2,
+    ocr,
     limitations,
     plan
-  };
+  });
 }
 
-// src/capabilityReport.ts
-var DOCX_META = "Structured document metadata is not exposed separately in the browser runtime; extractMetadata returns a stub for DOCX.";
-var IMAGE_META = "Raster images have no document metadata bundle; extractMetadata returns a stub.";
-var IMAGE_HTML = "No layout HTML for raster images; use extractText or runOcr for text.";
-var TEXT_META_NOTE = "Plain text has no structured document metadata; extractMetadata still returns decoded content.";
-var OCR_OFF_NOTE = 'Image OCR may be skipped when `ocr.mode` is "off" in analyze options.';
-var UNKNOWN_KIND = "Could not determine file kind from name, MIME, or bytes; all features are reported as unsupported until the kind is known.";
-function slot(id, supported, warnings) {
-  return warnings?.length ? { id, supported, warnings } : { id, supported };
+// src/introspection.ts
+function resolveOcrMode2(ocr) {
+  return ocr?.mode ?? "auto";
 }
-function buildBrowserCapabilityReport(kind) {
-  const runtime = { id: "browser" };
-  const pdf = BROWSER_PDF_UNSUPPORTED_WARNING;
-  let capabilities;
-  const topWarnings = [];
-  switch (kind) {
-    case "pdf":
-      capabilities = [
-        slot("text", false, [pdf]),
-        slot("metadata", false, [pdf]),
-        slot("html", false, [pdf]),
-        slot("ocr", false, [pdf]),
-        slot("pages", false, [pdf])
-      ];
-      break;
-    case "docx":
-      capabilities = [
-        slot("text", true),
-        slot("metadata", false, [DOCX_META]),
-        slot("html", true),
-        slot("ocr", false, ["OCR does not apply to DOCX in DocMind."]),
-        slot("pages", false)
-      ];
-      break;
-    case "image":
-      capabilities = [
-        slot("text", true, ["Text is obtained via OCR when enabled."]),
-        slot("metadata", false, [IMAGE_META]),
-        slot("html", false, [IMAGE_HTML]),
-        slot("ocr", true, [OCR_OFF_NOTE]),
-        slot("pages", false)
-      ];
-      break;
-    case "text":
-      capabilities = [
-        slot("text", true),
-        slot("metadata", true, [TEXT_META_NOTE]),
-        slot("html", true),
-        slot("ocr", false, ["OCR does not apply to plain text files."]),
-        slot("pages", false)
-      ];
-      break;
-    default:
-      topWarnings.push(UNKNOWN_KIND);
-      capabilities = [
-        slot("text", false),
-        slot("metadata", false),
-        slot("html", false),
-        slot("ocr", false),
-        slot("pages", false)
-      ];
+function imageBrowserPlanSteps(ocrMode, ocr) {
+  if (ocrMode === "off") {
+    return [
+      { id: "detect_kind", status: "done" },
+      { id: "image_format_detect", status: "skipped" },
+      { id: "normalize_image_for_ocr", status: "skipped" },
+      { id: "preprocess_image_for_ocr", status: "skipped" },
+      { id: "tesseract_ocr", status: "skipped" }
+    ];
   }
-  return {
-    kind,
-    runtime,
-    capabilities,
-    warnings: topWarnings.length > 0 ? topWarnings : void 0
-  };
-}
-
-// src/introspection.ts
-function resolveOcrMode2(ocr2) {
-  return ocr2?.mode ?? "auto";
+  return [
+    { id: "detect_kind", status: "done" },
+    { id: "image_format_detect", status: "planned" },
+    { id: "normalize_image_for_ocr", status: "planned" },
+    {
+      id: "preprocess_image_for_ocr",
+      status: preprocessHasEffect(ocr?.preprocess) ? "planned" : "skipped"
+    },
+    { id: "tesseract_ocr", status: "planned" }
+  ];
 }
-function planForAnalyzeFile(kind, ocrMode) {
+function planForAnalyzeFile(kind, ocrMode, docxInclude, ocr) {
   switch (kind) {
     case "pdf":
       return {
@@ -514,24 +735,21 @@ function planForAnalyzeFile(kind, ocrMode) {
           { id: "pdf_pipeline", status: "skipped" }
         ]
       };
-    case "docx":
+    case "docx": {
+      const parallel = docxIncludeRequested(docxInclude);
       return {
         intent: "analyzeFile",
         steps: [
           { id: "detect_kind", status: "done" },
-          { id: "docx_mammoth", status: "planned" }
+          { id: "docx_mammoth", status: "planned" },
+          ...parallel ? [{ id: "docx_ooxml_parallel", status: "planned" }] : []
         ]
       };
+    }
     case "image":
       return {
         intent: "analyzeFile",
-        steps: [
-          { id: "detect_kind", status: "done" },
-          {
-            id: "image_ocr",
-            status: ocrMode === "off" ? "skipped" : "planned"
-          }
-        ]
+        steps: imageBrowserPlanSteps(ocrMode, ocr)
       };
     case "text":
       return {
@@ -548,11 +766,11 @@ function planForAnalyzeFile(kind, ocrMode) {
       };
   }
 }
-function planForIntent(intentOpt, kind, ocrMode) {
+function planForIntent(intentOpt, kind, ocrMode, docxInclude, ocr) {
   const intent = intentOpt ?? "analyzeFile";
-  if (intent === "analyzeFile") return planForAnalyzeFile(kind, ocrMode);
+  if (intent === "analyzeFile") return planForAnalyzeFile(kind, ocrMode, docxInclude, ocr);
   if (intent === "extractText") {
-    const base = planForAnalyzeFile(kind, ocrMode);
+    const base = planForAnalyzeFile(kind, ocrMode, docxInclude, ocr);
     return { ...base, intent: "extractText" };
   }
   if (intent === "extractMetadata") {
@@ -575,11 +793,13 @@ function planForIntent(intentOpt, kind, ocrMode) {
   }
   if (intent === "convertToHtml") {
     if (kind === "docx") {
+      const parallel = docxIncludeRequested(docxInclude);
       return {
         intent: "convertToHtml",
         steps: [
           { id: "detect_kind", status: "done" },
-          { id: "docx_mammoth_html", status: "planned" }
+          { id: "docx_mammoth_html", status: "planned" },
+          ...parallel ? [{ id: "docx_ooxml_parallel", status: "planned" }] : []
         ]
       };
     }
@@ -605,18 +825,17 @@ function planForIntent(intentOpt, kind, ocrMode) {
     if (kind === "image") {
       return {
         intent: "runOcr",
-        steps: [
-          { id: "detect_kind", status: "done" },
-          { id: "tesseract_ocr", status: ocrMode === "off" ? "skipped" : "planned" }
-        ]
+        steps: imageBrowserPlanSteps(ocrMode, ocr)
       };
     }
     if (kind === "docx") {
+      const parallel = docxIncludeRequested(docxInclude);
       return {
         intent: "runOcr",
         steps: [
           { id: "detect_kind", status: "done" },
-          { id: "docx_structured_extract", status: "planned" }
+          { id: "docx_mammoth", status: "planned" },
+          ...parallel ? [{ id: "docx_ooxml_parallel", status: "planned" }] : []
         ]
       };
     }
@@ -628,7 +847,7 @@ function planForIntent(intentOpt, kind, ocrMode) {
       ]
     };
   }
-  return planForAnalyzeFile(kind, ocrMode);
+  return planForAnalyzeFile(kind, ocrMode, docxInclude, ocr);
 }
 async function getCapabilities(input, options) {
   throwIfAborted(options?.signal);
@@ -642,10 +861,12 @@ async function explainAnalysisPlan(input, options) {
   const kind = detectFileKind(input);
   const intent = options?.intent ?? "analyzeFile";
   const ocrMode = resolveOcrMode2(options?.ocr);
-  const plan = planForIntent(intent, kind, ocrMode);
-  return buildBrowserExplainReport(kind, intent, ocrMode, plan);
+  const docxInc = options?.docx?.include;
+  const ocrSlice = options?.ocr;
+  const plan = planForIntent(intent, kind, ocrMode, docxInc, ocrSlice);
+  return buildBrowserExplainReport(kind, intent, ocrMode, plan, docxInc, ocrSlice);
 }
 
-export { BROWSER_PDF_UNSUPPORTED_WARNING, analyzeFile, convertToHtml, explainAnalysisPlan, extractMetadata, extractText, getCapabilities, runOcr };
+export { BROWSER_PDF_UNSUPPORTED_WARNING, DOCX_EMBEDDED_IMAGE_CAPABILITIES_BROWSER, DOCX_STRUCTURE_CAPABILITIES_BROWSER, analyzeFile, convertToHtml, docxIncludeRequested, explainAnalysisPlan, extractMetadata, extractText, getCapabilities, runOcr };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dragon708/docmind-browser",
-  "version": "1.2.0",
+  "version": "1.5.0",
   "description": "Official DocMind browser facade: analyzeFile and intent APIs (DOCX, image OCR, text). PDF and fs paths use @dragon708/docmind-node.",
   "type": "module",
   "sideEffects": false,
@@ -33,8 +33,8 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@dragon708/docmind-docx": "^1.0.0",
-    "@dragon708/docmind-ocr": "^1.0.0",
+    "@dragon708/docmind-docx": "^1.7.0",
+    "@dragon708/docmind-ocr": "^1.1.0",
     "@dragon708/docmind-shared": "^1.1.0"
   },
   "devDependencies": {