@dragon708/docmind-browser 1.5.1 → 1.6.0

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-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 { DocMindAnalyzeOptions, AnalyzeFileOutputOptions, AnalysisResult, NormalizeStructuredOptions, StructuredDocumentResult, FileKind, RuntimeDescriptor, DocMindPublicIntent, AnalysisAnalyzer, ProcessingPlanDescriptor, ExplainAnalysisPlanOptions, GetCapabilitiesOptions } from '@dragon708/docmind-shared';
+export { AnalysisAnalyzer, AnalysisResult, CapabilityDescriptor, DetectFileKindInput, DocMindPublicIntent, DocumentBlock, DocumentImageRef, DocumentPage, DocumentTable, DocxAnalysisCoreResult, ExplainAnalysisPlanOptions, ExplainAnalysisPlanResult, FileKind, FileKindMetadata, GenericAnalysisResult, GetCapabilitiesOptions, GetCapabilitiesResult, ImageAnalysisCoreResult, PdfAnalysisCoreResult, StructuredDocumentResult, TextAnalysisResult, analyzeFileRequestsStructured, detectFileKind, isStructuredDocumentResult } from '@dragon708/docmind-shared';
 import { OcrOptions, OcrTiffOptions, PreprocessImageOptions } from '@dragon708/docmind-ocr';
+export { ExtractStructuredDataFromImageOptions, extractStructuredDataFromImage } from '@dragon708/docmind-ocr';
 import { AnalyzeDocxIncludeFlags, DocxToHtmlOptions } from '@dragon708/docmind-docx';
-export { AnalyzeDocxIncludeFlags } from '@dragon708/docmind-docx';
+export { AnalyzeDocxIncludeFlags, ExtractStructuredDataFromDocxOptions, extractStructuredDataFromDocx } from '@dragon708/docmind-docx';
 
 /**
  * Opciones DOCX para el facade browser (Mammoth + inclusiones v2 de `@dragon708/docmind-docx`; sin APIs Node-only).
@@ -30,7 +31,7 @@ interface BrowserOcrOptions extends OcrOptions, Pick<OcrTiffOptions, "maxPages"
  * Options for public browser methods (`analyzeFile`, intent APIs).
  * There is no PDF pipeline in the browser; {@link BrowserOcrOptions.mode} applies to images only.
  */
-interface BrowserAnalyzeOptions extends DocMindAnalyzeOptions {
+interface BrowserAnalyzeOptions extends DocMindAnalyzeOptions, AnalyzeFileOutputOptions {
     /** Image OCR only; no PDF in this runtime. See {@link BrowserOcrOptions.mode}. */
     readonly ocr?: BrowserOcrOptions;
     /** Solo DOCX: ver {@link BrowserAnalyzeDocxOptionsSlice}. */
@@ -42,15 +43,21 @@ interface BrowserAnalyzeOptions extends DocMindAnalyzeOptions {
  */
 type BrowserAnalyzeInput = File | Blob | ArrayBuffer;
 
+/** PDF is not processed in the browser; use `@dragon708/docmind-node` on the server. */
+declare const BROWSER_PDF_UNSUPPORTED_WARNING = "PDF text extraction is not available in the browser runtime; use @dragon708/docmind-node on the server.";
+/** PDF structured extraction is not available in the browser; use the Node PDF helpers. */
+declare const BROWSER_PDF_STRUCTURED_UNSUPPORTED_WARNING = "PDF text extraction is not available in the browser runtime; use @dragon708/docmind-node on the server. Structured document extraction for PDF is not available in the browser; use @dragon708/docmind-node (e.g. extractStructuredDataFromPdf).";
+
 /**
  * Browser `analyzeFile` router. Package-level scope and limitations are documented on the package entry (`index.ts`).
  */
 
-/** PDF is not processed in the browser; use `@dragon708/docmind-node` on the server. */
-declare const BROWSER_PDF_UNSUPPORTED_WARNING = "PDF text extraction is not available in the browser runtime; use @dragon708/docmind-node on the server.";
 /**
  * Full-document router: DOCX (text + HTML), images (OCR subject to {@link BrowserOcrOptions.mode}),
  * plain text (UTF-8 decode). PDF yields `not_implemented` with {@link BROWSER_PDF_UNSUPPORTED_WARNING}.
+ *
+ * When `structuredOutput` is true or `output` includes `"structured"`, successful results may include
+ * optional `structured` (see `@dragon708/docmind-shared` DocMindV2Extensions).
  */
 declare function analyzeFile(input: BrowserAnalyzeInput, options?: BrowserAnalyzeOptions): Promise<AnalysisResult>;
 
@@ -77,8 +84,27 @@ declare function convertToHtml(input: BrowserAnalyzeInput, options?: BrowserAnal
  */
 declare function runOcr(input: BrowserAnalyzeInput, options?: BrowserAnalyzeOptions): Promise<AnalysisResult>;
 
+/**
+ * Browser-safe structured extraction: DOCX and images delegate to `@dragon708/docmind-docx` /
+ * `@dragon708/docmind-ocr`; plain text is normalized via `@dragon708/docmind-shared`.
+ * PDF is not supported in this runtime (clear warnings, no PDF package import).
+ */
+
+/** Options for {@link extractStructuredData}: same as {@link BrowserAnalyzeOptions} plus shared normalize knobs. */
+type BrowserExtractStructuredDataOptions = BrowserAnalyzeOptions & {
+    readonly normalize?: NormalizeStructuredOptions;
+};
+/**
+ * Returns a {@link StructuredDocumentResult} for inputs the browser runtime actually supports:
+ * **DOCX** (`extractStructuredDataFromDocx`), **images** (`extractStructuredDataFromImage` when OCR is not off),
+ * **plain text** (UTF-8 decode + `normalizeToStructuredResult`).
+ *
+ * **PDF** yields an empty structured envelope plus `BROWSER_PDF_STRUCTURED_UNSUPPORTED_WARNING` from the facade (no PDF parser in this runtime).
+ */
+declare function extractStructuredData(input: BrowserAnalyzeInput, options?: BrowserExtractStructuredDataOptions): Promise<StructuredDocumentResult>;
+
 /** 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";
+type PublicCapabilityId = "text" | "metadata" | "html" | "ocr" | "pages" | "structured-output" | "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 {
@@ -151,18 +177,18 @@ interface ExplainAnalysisPlanReport {
 }
 
 /** Options for {@link explainAnalysisPlan}: shared fields plus optional `ocr` / `docx` for accurate step preview. */
-type BrowserExplainAnalysisPlanOptions = ExplainAnalysisPlanOptions & Pick<BrowserAnalyzeOptions, "ocr" | "docx">;
+type BrowserExplainAnalysisPlanOptions = ExplainAnalysisPlanOptions & Pick<BrowserAnalyzeOptions, "ocr" | "docx" | "structuredOutput" | "output">;
 
 /**
  * Epic 1 — **Capabilities:** detects kind from the same hints as `analyzeFile`, then lists which of
- * `text` | `metadata` | `html` | `ocr` | `pages` and image-specific ids (`image-normalization`, `bmp`, `gif-first-frame`, `heic`, `tiff`) apply in the browser (PDF always unsupported).
+ * `text` | `metadata` | `html` | `ocr` | `pages` | `structured-output` 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` refines image steps; optional `docx.include` adds planned OOXML parallel steps for DOCX. No heavy I/O.
+ * for a {@link DocMindPublicIntent} (including `extractStructuredData`). 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 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 };
+export { BROWSER_PDF_STRUCTURED_UNSUPPORTED_WARNING, BROWSER_PDF_UNSUPPORTED_WARNING, type BrowserAnalyzeDocxOptionsSlice, type BrowserAnalyzeInput, type BrowserAnalyzeOptions, type BrowserExplainAnalysisPlanOptions, type BrowserExtractStructuredDataOptions, 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, extractStructuredData, extractText, getCapabilities, runOcr };

package/dist/index.js

@@ -1,7 +1,9 @@
-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 { preprocessHasEffect, resolveImageFormat, normalizeImageForOcr, ocrTiff, ocrImageDetailed } from '@dragon708/docmind-ocr';
+import { detectFileKind, normalizeToStructuredResult, UNKNOWN_FORMAT_WARNING, analyzeText, toUint8Array, assertValidAnalyzeFileInput, notImplementedResult, analyzeFileRequestsStructured, InvalidInputError, getMimeType } from '@dragon708/docmind-shared';
+export { analyzeFileRequestsStructured, detectFileKind, isStructuredDocumentResult } from '@dragon708/docmind-shared';
+import { extractStructuredDataFromDocx, analyzeDocx } from '@dragon708/docmind-docx';
+export { extractStructuredDataFromDocx } from '@dragon708/docmind-docx';
+import { extractStructuredDataFromImage, preprocessHasEffect, resolveImageFormat, normalizeImageForOcr, ocrTiff, ocrImageDetailed } from '@dragon708/docmind-ocr';
+export { extractStructuredDataFromImage } from '@dragon708/docmind-ocr';
 
 // src/analyzeFile.ts
 function assertBrowserInput(input) {
@@ -223,8 +225,125 @@ async function analyzeImageForBrowser(input, options) {
   return base;
 }
 
-// src/analyzeFile.ts
+// src/browserPdfWarnings.ts
 var BROWSER_PDF_UNSUPPORTED_WARNING = "PDF text extraction is not available in the browser runtime; use @dragon708/docmind-node on the server.";
+var BROWSER_PDF_STRUCTURED_UNSUPPORTED_WARNING = `${BROWSER_PDF_UNSUPPORTED_WARNING} Structured document extraction for PDF is not available in the browser; use @dragon708/docmind-node (e.g. extractStructuredDataFromPdf).`;
+var OCR_OFF_STRUCTURED_WARNING = 'Structured image extraction uses OCR; ocr.mode is "off". Use "auto" or "force" to run Tesseract.';
+function resolveOcrMode2(ocr) {
+  return ocr?.mode ?? "auto";
+}
+async function extractStructuredData(input, options) {
+  throwIfAborted(options?.signal);
+  prepareBrowserAnalyzeInput(input);
+  const kind = detectFileKind(input);
+  const bytesInput = input;
+  const norm = options?.normalize;
+  switch (kind) {
+    case "pdf":
+      return normalizeToStructuredResult(
+        {
+          kind: "pdf",
+          text: "",
+          blocks: [],
+          warnings: [BROWSER_PDF_STRUCTURED_UNSUPPORTED_WARNING],
+          metadata: {
+            extra: { browserStructuredPdfUnsupported: true }
+          }
+        },
+        norm
+      );
+    case "docx": {
+      const data = await toUint8Array(bytesInput);
+      if (data.byteLength === 0) {
+        return normalizeToStructuredResult(
+          {
+            kind: "docx",
+            text: "",
+            blocks: [],
+            warnings: ["No document bytes were provided for analysis."]
+          },
+          norm
+        );
+      }
+      const docxOpts = analyzeDocxOptionsFromBrowser(options);
+      return extractStructuredDataFromDocx(data, {
+        ...docxOpts ?? {},
+        normalize: norm
+      });
+    }
+    case "image": {
+      const data = await toUint8Array(bytesInput);
+      if (data.byteLength === 0) {
+        return normalizeToStructuredResult(
+          {
+            kind: "image",
+            text: "",
+            blocks: [],
+            tables: [],
+            pages: [],
+            images: [],
+            warnings: ["No image bytes were provided for analysis."]
+          },
+          norm
+        );
+      }
+      if (resolveOcrMode2(options?.ocr) === "off") {
+        return normalizeToStructuredResult(
+          {
+            kind: "image",
+            text: "",
+            blocks: [],
+            tables: [],
+            pages: [],
+            images: [],
+            warnings: [OCR_OFF_STRUCTURED_WARNING],
+            metadata: {
+              extra: { ocrSkipped: true }
+            }
+          },
+          norm
+        );
+      }
+      const ocr = options?.ocr;
+      return extractStructuredDataFromImage(input, {
+        signal: options?.signal,
+        normalize: norm,
+        langs: ocr?.langs,
+        preprocess: ocr?.preprocess,
+        maxPages: ocr?.maxPages,
+        pageSeparator: ocr?.pageSeparator
+      });
+    }
+    case "text": {
+      const textResult = await analyzeText(bytesInput, { signal: options?.signal });
+      const blocks = textResult.text.length > 0 ? [{ type: "paragraph", id: "p-0", text: textResult.text }] : [];
+      return normalizeToStructuredResult(
+        {
+          kind: "text",
+          text: textResult.text,
+          blocks,
+          warnings: [...textResult.warnings],
+          metadata: {
+            extra: { plainTextUtf8: true }
+          }
+        },
+        norm
+      );
+    }
+    default:
+      return normalizeToStructuredResult(
+        {
+          kind: "unknown",
+          text: "",
+          blocks: [],
+          warnings: [UNKNOWN_FORMAT_WARNING]
+        },
+        norm
+      );
+  }
+}
+
+// src/analyzeFile.ts
 async function analyzeFile(input, options) {
   if (options?.signal?.aborted) {
     const err = new Error("The operation was aborted");
@@ -235,17 +354,38 @@ async function analyzeFile(input, options) {
   assertValidAnalyzeFileInput(input);
   const fileKind = detectFileKind(input);
   const bytesInput = input;
+  let result;
   switch (fileKind) {
     case "pdf":
-      return notImplementedResult("pdf", "pdf", [BROWSER_PDF_UNSUPPORTED_WARNING]);
+      result = notImplementedResult("pdf", "pdf", [BROWSER_PDF_UNSUPPORTED_WARNING]);
+      break;
     case "docx":
-      return analyzeDocxForBrowser(bytesInput, options);
+      result = await analyzeDocxForBrowser(bytesInput, options);
+      break;
     case "image":
-      return analyzeImageForBrowser(bytesInput, options);
+      result = await analyzeImageForBrowser(bytesInput, options);
+      break;
     case "text":
-      return analyzeText(bytesInput, { signal: options?.signal });
+      result = await analyzeText(bytesInput, { signal: options?.signal });
+      break;
     default:
-      return notImplementedResult(fileKind, "none", [UNKNOWN_FORMAT_WARNING]);
+      result = notImplementedResult(fileKind, "none", [UNKNOWN_FORMAT_WARNING]);
+  }
+  if (!analyzeFileRequestsStructured(options) || result.status !== "ok") {
+    return result;
+  }
+  try {
+    const structured = await extractStructuredData(input, {
+      signal: options?.signal,
+      ocr: options?.ocr,
+      docx: options?.docx
+    });
+    return { ...result, structured };
+  } catch (e) {
+    if (e instanceof Error && e.name === "AbortError") throw e;
+    const msg = e instanceof Error ? e.message : String(e);
+    const prev = "warnings" in result && Array.isArray(result.warnings) ? [...result.warnings] : [];
+    return { ...result, warnings: [...prev, `warning: analyzeFile structured merge failed: ${msg}`] };
   }
 }
 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.";
@@ -415,6 +555,7 @@ var IMAGE_META = "Raster images have no document metadata bundle; extractMetadat
 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 STRUCTURED_OCR_OFF = 'Structured image output uses OCR; when `ocr.mode` is "off", `extractStructuredData` returns an empty envelope with a warning.';
 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 };
@@ -431,7 +572,8 @@ function buildBrowserCapabilityReport(kind) {
         slot("metadata", false, [pdf]),
         slot("html", false, [pdf]),
         slot("ocr", false, [pdf]),
-        slot("pages", false, [pdf])
+        slot("pages", false, [pdf]),
+        slot("structured-output", false, [BROWSER_PDF_STRUCTURED_UNSUPPORTED_WARNING])
       ];
       break;
     case "docx":
@@ -448,6 +590,9 @@ function buildBrowserCapabilityReport(kind) {
         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)."
+        ]),
+        slot("structured-output", true, [
+          "`extractStructuredData` uses `@dragon708/docmind-docx` (Mammoth + OOXML) and returns `StructuredDocumentResult`; optional `options.docx` slices are forwarded."
         ])
       ];
       break;
@@ -479,6 +624,11 @@ function buildBrowserCapabilityReport(kind) {
         ]),
         slot("pages", true, [
           "Multipage TIFF may populate `pages` and `textByPage` when OCR succeeds; other formats may expose `pages` when normalization reports it."
+        ]),
+        slot("structured-output", true, [
+          "`extractStructuredData` uses `extractStructuredDataFromImage` (same OCR path as analyzeFile when `ocr.mode` is not off).",
+          STRUCTURED_OCR_OFF,
+          "HEIC/HEIF and TIFF limitations match `getCapabilities` (`heic`, `tiff`) and OCR warnings."
         ])
       ];
       break;
@@ -488,7 +638,10 @@ function buildBrowserCapabilityReport(kind) {
         slot("metadata", true, [TEXT_META_NOTE]),
         slot("html", true),
         slot("ocr", false, ["OCR does not apply to plain text files."]),
-        slot("pages", false)
+        slot("pages", false),
+        slot("structured-output", true, [
+          "`extractStructuredData` decodes UTF-8 (via `analyzeText`) and normalizes to `StructuredDocumentResult` (paragraph block rollup)."
+        ])
       ];
       break;
     default:
@@ -498,7 +651,8 @@ function buildBrowserCapabilityReport(kind) {
         slot("metadata", false),
         slot("html", false),
         slot("ocr", false),
-        slot("pages", false)
+        slot("pages", false),
+        slot("structured-output", false, [UNKNOWN_KIND])
       ];
   }
   return {
@@ -541,7 +695,10 @@ function buildBrowserExplainReport(kind, intent, ocrMode, plan, docxInclude, ocr
   let limitations = [];
   const ocrOffNote = ocrMode === "off" ? 'Image OCR is skipped when ocr.mode is "off".' : "";
   if (kind === "pdf") {
-    limitations = lim(BROWSER_PDF_UNSUPPORTED_WARNING);
+    limitations = lim(
+      BROWSER_PDF_UNSUPPORTED_WARNING,
+      intent === "extractStructuredData" ? "`extractStructuredData` only returns an empty `StructuredDocumentResult` with warnings for PDF in-browser; use @dragon708/docmind-node for real PDF structured extraction." : ""
+    );
     nativeExtraction = {
       willAttempt: false,
       description: "PDF is not processed in the browser runtime; use @dragon708/docmind-node."
@@ -565,7 +722,8 @@ function buildBrowserExplainReport(kind, intent, ocrMode, plan, docxInclude, ocr
   }
   if (kind === "unknown") {
     limitations = lim(
-      "Could not classify the file from name, MIME, or bytes; analysis will return not_implemented until hints improve."
+      "Could not classify the file from name, MIME, or bytes; analysis will return not_implemented until hints improve.",
+      intent === "extractStructuredData" ? "`extractStructuredData` needs a known kind (text, DOCX, or image) to produce structured output." : ""
     );
     nativeExtraction = { willAttempt: false, description: "No analyzer selected without a known file kind." };
     ocr = { mayUse: false, description: "OCR is not used for unknown kinds." };
@@ -677,6 +835,32 @@ function buildBrowserExplainReport(kind, intent, ocrMode, plan, docxInclude, ocr
         ocr = { mayUse: false, description: "OCR does not apply to text files." };
       }
       break;
+    case "extractStructuredData":
+      if (kind === "docx") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "`extractStructuredDataFromDocx`: Mammoth plus required OOXML extractors (structure, headings, tables, blocks, pagesApprox, embeddedImages unless disabled), then `normalizeToStructuredResult`. Optional `options.docx` is forwarded."
+        };
+        ocr = { mayUse: false, description: "DOCX structured path does not use OCR." };
+        limitations = lim(DOCX_ZIP_NOTE_BROWSER);
+      } else if (kind === "image") {
+        nativeExtraction = {
+          willAttempt: false,
+          description: BROWSER_IMAGE_PIPELINE
+        };
+        ocr = {
+          mayUse: imageOcrActive,
+          description: imageOcrActive ? "`extractStructuredDataFromImage` mirrors the OCR pipeline (normalize \u2192 optional preprocess \u2192 Tesseract, or `ocrTiff` for TIFF)." : "OCR skipped while ocr.mode is off; structured output will be empty with a warning."
+        };
+        limitations = lim(ocrOffNote, BROWSER_TIFF_RASTER_NOTE, BROWSER_HEIC_NOTE);
+      } else {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "UTF-8 decode via `analyzeText`, then `normalizeToStructuredResult` with a paragraph block rollup."
+        };
+        ocr = { mayUse: false, description: "OCR does not apply to text files." };
+      }
+      break;
     default:
       nativeExtraction = { willAttempt: false, description: "Intent not specialized in this runtime." };
       ocr = { mayUse: false, description: "See plan steps." };
@@ -701,7 +885,7 @@ function buildBrowserExplainReport(kind, intent, ocrMode, plan, docxInclude, ocr
 }
 
 // src/introspection.ts
-function resolveOcrMode2(ocr) {
+function resolveOcrMode3(ocr) {
   return ocr?.mode ?? "auto";
 }
 function imageBrowserPlanSteps(ocrMode, ocr) {
@@ -766,9 +950,76 @@ function planForAnalyzeFile(kind, ocrMode, docxInclude, ocr) {
       };
   }
 }
-function planForIntent(intentOpt, kind, ocrMode, docxInclude, ocr) {
+function planForIntent(intentOpt, kind, ocrMode, docxInclude, ocr, analyzeFileOutput) {
   const intent = intentOpt ?? "analyzeFile";
-  if (intent === "analyzeFile") return planForAnalyzeFile(kind, ocrMode, docxInclude, ocr);
+  if (intent === "extractStructuredData") {
+    switch (kind) {
+      case "pdf":
+        return {
+          intent: "extractStructuredData",
+          steps: [
+            { id: "detect_kind", status: "done" },
+            { id: "pdf_pipeline", status: "skipped" },
+            { id: "structured_output", status: "skipped" }
+          ]
+        };
+      case "docx":
+        return {
+          intent: "extractStructuredData",
+          steps: [
+            { id: "detect_kind", status: "done" },
+            { id: "docx_mammoth", status: "planned" },
+            { id: "docx_ooxml_parallel", status: "planned" },
+            { id: "structured_normalize", status: "planned" }
+          ]
+        };
+      case "image": {
+        if (ocrMode === "off") {
+          return {
+            intent: "extractStructuredData",
+            steps: [
+              { 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" },
+              { id: "structured_normalize", status: "skipped" }
+            ]
+          };
+        }
+        const imgSteps = imageBrowserPlanSteps(ocrMode, ocr);
+        return {
+          intent: "extractStructuredData",
+          steps: [...imgSteps, { id: "structured_normalize", status: "planned" }]
+        };
+      }
+      case "text":
+        return {
+          intent: "extractStructuredData",
+          steps: [
+            { id: "detect_kind", status: "done" },
+            { id: "utf8_decode", status: "planned" },
+            { id: "structured_normalize", status: "planned" }
+          ]
+        };
+      default:
+        return {
+          intent: "extractStructuredData",
+          steps: [
+            { id: "detect_kind", status: "done" },
+            { id: "route", status: "failed" }
+          ]
+        };
+    }
+  }
+  if (intent === "analyzeFile") {
+    const base = planForAnalyzeFile(kind, ocrMode, docxInclude, ocr);
+    if (!analyzeFileRequestsStructured(analyzeFileOutput)) return base;
+    return {
+      ...base,
+      steps: [...base.steps ?? [], { id: "structured_merge", status: "planned" }]
+    };
+  }
   if (intent === "extractText") {
     const base = planForAnalyzeFile(kind, ocrMode, docxInclude, ocr);
     return { ...base, intent: "extractText" };
@@ -860,13 +1111,16 @@ async function explainAnalysisPlan(input, options) {
   prepareBrowserAnalyzeInput(input);
   const kind = detectFileKind(input);
   const intent = options?.intent ?? "analyzeFile";
-  const ocrMode = resolveOcrMode2(options?.ocr);
+  const ocrMode = resolveOcrMode3(options?.ocr);
   const docxInc = options?.docx?.include;
   const ocrSlice = options?.ocr;
-  const plan = planForIntent(intent, kind, ocrMode, docxInc, ocrSlice);
+  const plan = planForIntent(intent, kind, ocrMode, docxInc, ocrSlice, {
+    structuredOutput: options?.structuredOutput,
+    output: options?.output
+  });
   return buildBrowserExplainReport(kind, intent, ocrMode, plan, docxInc, ocrSlice);
 }
 
-export { BROWSER_PDF_UNSUPPORTED_WARNING, DOCX_EMBEDDED_IMAGE_CAPABILITIES_BROWSER, DOCX_STRUCTURE_CAPABILITIES_BROWSER, analyzeFile, convertToHtml, docxIncludeRequested, explainAnalysisPlan, extractMetadata, extractText, getCapabilities, runOcr };
+export { BROWSER_PDF_STRUCTURED_UNSUPPORTED_WARNING, BROWSER_PDF_UNSUPPORTED_WARNING, DOCX_EMBEDDED_IMAGE_CAPABILITIES_BROWSER, DOCX_STRUCTURE_CAPABILITIES_BROWSER, analyzeFile, convertToHtml, docxIncludeRequested, explainAnalysisPlan, extractMetadata, extractStructuredData, extractText, getCapabilities, runOcr };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dragon708/docmind-browser",
-  "version": "1.5.1",
+  "version": "1.6.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,9 +33,9 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@dragon708/docmind-docx": "^1.7.1",
-    "@dragon708/docmind-ocr": "^1.1.3",
-    "@dragon708/docmind-shared": "^1.1.1"
+    "@dragon708/docmind-docx": "^1.8.0",
+    "@dragon708/docmind-ocr": "^1.1.4",
+    "@dragon708/docmind-shared": "^1.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.37",