@dragon708/docmind-browser 1.5.1 → 1.7.0

package/dist/index.d.ts

@@ -1,8 +1,11 @@
-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, OcrTiffOptions, PreprocessImageOptions } from '@dragon708/docmind-ocr';
+import { DocMindAnalyzeOptions, AnalyzeFileOutputOptions, NormalizeStructuredOptions, AnalysisResult, 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 { RenderLlmTextOptions, RenderMarkdownOptions, RenderMarkdownSectionsOptions, MarkdownSection } from '@dragon708/docmind-markdown';
+export { MarkdownSection } from '@dragon708/docmind-markdown';
 import { AnalyzeDocxIncludeFlags, DocxToHtmlOptions } from '@dragon708/docmind-docx';
-export { AnalyzeDocxIncludeFlags } from '@dragon708/docmind-docx';
+export { AnalyzeDocxIncludeFlags, ExtractStructuredDataFromDocxOptions, extractStructuredDataFromDocx } from '@dragon708/docmind-docx';
+import { OcrOptions, OcrTiffOptions, PreprocessImageOptions } from '@dragon708/docmind-ocr';
+export { ExtractStructuredDataFromImageOptions, extractStructuredDataFromImage } from '@dragon708/docmind-ocr';
 
 /**
  * Opciones DOCX para el facade browser (Mammoth + inclusiones v2 de `@dragon708/docmind-docx`; sin APIs Node-only).
@@ -30,27 +33,51 @@ 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}. */
     readonly docx?: BrowserAnalyzeDocxOptionsSlice;
 }
+/** Options for {@link extractStructuredData}: same as {@link BrowserAnalyzeOptions} plus shared normalize knobs. */
+type BrowserExtractStructuredDataOptions = BrowserAnalyzeOptions & {
+    readonly normalize?: NormalizeStructuredOptions;
+};
+/**
+ * {@link extractMarkdown}: structured options plus `markdown` for `renderMarkdown` (`@dragon708/docmind-markdown`).
+ */
+interface BrowserExtractMarkdownOptions extends BrowserExtractStructuredDataOptions {
+    readonly markdown?: RenderMarkdownOptions;
+}
+/** {@link extractLlmContent}: optional `llm` passed to `renderLlmText`. */
+interface BrowserExtractLlmContentOptions extends BrowserExtractStructuredDataOptions {
+    readonly llm?: RenderLlmTextOptions;
+}
+/** {@link extractStructuredChunks}: optional `chunks` (split / section sizing). */
+interface BrowserExtractStructuredChunksOptions extends BrowserExtractStructuredDataOptions {
+    readonly chunks?: RenderMarkdownSectionsOptions;
+}
 
 /**
  * Inputs supported by the browser entry (DOM types only — no `fs`, no Node `Buffer` in the public surface).
  */
 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 +104,40 @@ 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).
+ */
+
+/**
+ * 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>;
+
+/**
+ * {@link extractStructuredData} → `renderMarkdown` (browser-safe; no Node-only APIs).
+ * PDF: empty structured stub → usually empty output; see {@link getCapabilities} capability `markdown`.
+ *
+ * @param input - `File` / `Blob` / bytes as accepted by the browser facade.
+ * @param options - `markdown` render options plus structured/`ocr`/`docx` routing (same as {@link extractStructuredData}).
+ */
+declare function extractMarkdown(input: BrowserAnalyzeInput, options?: BrowserExtractMarkdownOptions): Promise<string>;
+/**
+ * Same as {@link extractMarkdown} but `renderLlmText` (compact plain text for LLM prompts).
+ */
+declare function extractLlmContent(input: BrowserAnalyzeInput, options?: BrowserExtractLlmContentOptions): Promise<string>;
+/**
+ * Structured extract → `renderMarkdownSections` for sectioned Markdown in the browser.
+ */
+declare function extractStructuredChunks(input: BrowserAnalyzeInput, options?: BrowserExtractStructuredChunksOptions): Promise<readonly MarkdownSection[]>;
+
 /** 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" | "markdown" | "llm-text" | "structured-chunks" | "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 {
@@ -150,19 +209,24 @@ interface ExplainAnalysisPlanReport {
     readonly warnings?: readonly string[];
 }
 
+/** Browser facade intents that run `@dragon708/docmind-markdown` after structured extraction. */
+type BrowserMarkdownFacadeIntent = "extractMarkdown" | "extractLlmContent" | "extractStructuredChunks";
 /** Options for {@link explainAnalysisPlan}: shared fields plus optional `ocr` / `docx` for accurate step preview. */
-type BrowserExplainAnalysisPlanOptions = ExplainAnalysisPlanOptions & Pick<BrowserAnalyzeOptions, "ocr" | "docx">;
+type BrowserExplainAnalysisPlanOptions = Omit<ExplainAnalysisPlanOptions, "intent"> & Pick<BrowserAnalyzeOptions, "ocr" | "docx" | "structuredOutput" | "output"> & {
+    readonly intent?: DocMindPublicIntent | BrowserMarkdownFacadeIntent;
+};
 
 /**
  * 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` | `markdown` | `llm-text` | `structured-chunks`
+ * and image-specific ids (`image-normalization`, `bmp`, `gif-first-frame`, `heic`, `tiff`) apply in the browser (PDF always unsupported for meaningful content).
  * 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 BrowserExtractLlmContentOptions, type BrowserExtractMarkdownOptions, type BrowserExtractStructuredChunksOptions, type BrowserExtractStructuredDataOptions, type BrowserMarkdownFacadeIntent, 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, extractLlmContent, extractMarkdown, extractMetadata, extractStructuredChunks, extractStructuredData, extractText, getCapabilities, runOcr };

package/dist/index.js

@@ -1,7 +1,10 @@
-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';
+import { renderMarkdown, renderLlmText, renderMarkdownSections } from '@dragon708/docmind-markdown';
 
 // src/analyzeFile.ts
 function assertBrowserInput(input) {
@@ -223,8 +226,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 +355,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.";
@@ -379,6 +520,24 @@ async function runOcr(input, options) {
       return notImplementedResult(kind, "none", [UNKNOWN_FORMAT_WARNING]);
   }
 }
+async function extractMarkdown(input, options) {
+  throwIfAborted(options?.signal);
+  const { markdown: markdownOpts, ...structuredOpts } = options ?? {};
+  const structured = await extractStructuredData(input, structuredOpts);
+  return renderMarkdown(structured, markdownOpts);
+}
+async function extractLlmContent(input, options) {
+  throwIfAborted(options?.signal);
+  const { llm: llmOpts, ...structuredOpts } = options ?? {};
+  const structured = await extractStructuredData(input, structuredOpts);
+  return renderLlmText(structured, llmOpts);
+}
+async function extractStructuredChunks(input, options) {
+  throwIfAborted(options?.signal);
+  const { chunks: chunkOpts, ...structuredOpts } = options ?? {};
+  const structured = await extractStructuredData(input, structuredOpts);
+  return renderMarkdownSections(structured, chunkOpts);
+}
 
 // src/capabilityReport.ts
 function docxIncludeRequested(flags) {
@@ -415,7 +574,10 @@ 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.";
+var MARKDOWN_PDF_BROWSER = "PDF: no parser in-browser \u2014 extractMarkdown / extractLlmContent / extractStructuredChunks only render an empty structured stub; use @dragon708/docmind-node for real PDF \u2192 Markdown / LLM text / chunks.";
+var MARKDOWN_IMAGE_OCR_OFF = 'Same as structured-output: when ocr.mode is "off", structured (and thus Markdown/LLM/chunk exports) are empty aside from warnings.';
 function slot(id, supported, warnings) {
   return warnings?.length ? { id, supported, warnings } : { id, supported };
 }
@@ -431,7 +593,11 @@ 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]),
+        slot("markdown", false, [MARKDOWN_PDF_BROWSER]),
+        slot("llm-text", false, [MARKDOWN_PDF_BROWSER]),
+        slot("structured-chunks", false, [MARKDOWN_PDF_BROWSER])
       ];
       break;
     case "docx":
@@ -448,6 +614,18 @@ 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."
+        ]),
+        slot("markdown", true, [
+          "extractMarkdown: structured DOCX \u2192 Markdown via `@dragon708/docmind-markdown` (browser-safe, no Node APIs)."
+        ]),
+        slot("llm-text", true, [
+          "extractLlmContent: structured \u2192 compact plain text for prompts (same pipeline as Markdown export)."
+        ]),
+        slot("structured-chunks", true, [
+          "extractStructuredChunks: structured \u2192 Markdown sections (`splitStructuredIntoChunks` in markdown package)."
         ])
       ];
       break;
@@ -479,6 +657,23 @@ 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."
+        ]),
+        slot("markdown", true, [
+          "extractMarkdown: OCR structured layout \u2192 Markdown when OCR runs; HEIC unsupported; TIFF best-effort.",
+          MARKDOWN_IMAGE_OCR_OFF
+        ]),
+        slot("llm-text", true, [
+          "extractLlmContent: OCR structured \u2192 LLM plain text under the same OCR and format limits.",
+          MARKDOWN_IMAGE_OCR_OFF
+        ]),
+        slot("structured-chunks", true, [
+          "extractStructuredChunks: OCR structured \u2192 sectioned Markdown; empty when OCR is off or HEIC.",
+          MARKDOWN_IMAGE_OCR_OFF
         ])
       ];
       break;
@@ -488,7 +683,17 @@ 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)."
+        ]),
+        slot("markdown", true, [
+          "extractMarkdown: UTF-8 structured rollup \u2192 Markdown (`@dragon708/docmind-markdown`)."
+        ]),
+        slot("llm-text", true, ["extractLlmContent: UTF-8 structured \u2192 LLM-oriented plain text."]),
+        slot("structured-chunks", true, [
+          "extractStructuredChunks: typically a single Markdown section when only paragraph rollup exists."
+        ])
       ];
       break;
     default:
@@ -498,7 +703,11 @@ function buildBrowserCapabilityReport(kind) {
         slot("metadata", false),
         slot("html", false),
         slot("ocr", false),
-        slot("pages", false)
+        slot("pages", false),
+        slot("structured-output", false, [UNKNOWN_KIND]),
+        slot("markdown", false, [UNKNOWN_KIND]),
+        slot("llm-text", false, [UNKNOWN_KIND]),
+        slot("structured-chunks", false, [UNKNOWN_KIND])
       ];
   }
   return {
@@ -541,7 +750,11 @@ 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);
+    const structuredLikeIntent = intent === "extractStructuredData" || intent === "extractMarkdown" || intent === "extractLlmContent" || intent === "extractStructuredChunks";
+    limitations = lim(
+      BROWSER_PDF_UNSUPPORTED_WARNING,
+      structuredLikeIntent ? "`extractStructuredData` / extractMarkdown / extractLlmContent / extractStructuredChunks only see an empty structured envelope in-browser for PDF; use @dragon708/docmind-node for real PDF extraction and Markdown/LLM/chunk exports." : ""
+    );
     nativeExtraction = {
       willAttempt: false,
       description: "PDF is not processed in the browser runtime; use @dragon708/docmind-node."
@@ -564,8 +777,10 @@ function buildBrowserExplainReport(kind, intent, ocrMode, plan, docxInclude, ocr
     });
   }
   if (kind === "unknown") {
+    const structuredLikeIntent = intent === "extractStructuredData" || intent === "extractMarkdown" || intent === "extractLlmContent" || intent === "extractStructuredChunks";
     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.",
+      structuredLikeIntent ? "Structured and Markdown/LLM/chunk exports need a known kind (text, DOCX, or image) in the browser runtime." : ""
     );
     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 +892,51 @@ function buildBrowserExplainReport(kind, intent, ocrMode, plan, docxInclude, ocr
         ocr = { mayUse: false, description: "OCR does not apply to text files." };
       }
       break;
+    case "extractStructuredData":
+    case "extractMarkdown":
+    case "extractLlmContent":
+    case "extractStructuredChunks":
+      if (kind === "docx") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: intent === "extractStructuredData" ? "`extractStructuredDataFromDocx`: Mammoth plus required OOXML extractors (structure, headings, tables, blocks, pagesApprox, embeddedImages unless disabled), then `normalizeToStructuredResult`. Optional `options.docx` is forwarded." : `${String(intent)}: same structured DOCX pipeline as extractStructuredData, then \`@dragon708/docmind-markdown\` (browser-safe).`
+        };
+        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: intent === "extractStructuredData" ? "UTF-8 decode via `analyzeText`, then `normalizeToStructuredResult` with a paragraph block rollup." : `${String(intent)}: UTF-8 structured envelope, then \`@dragon708/docmind-markdown\`.`
+        };
+        ocr = { mayUse: false, description: "OCR does not apply to text files." };
+      }
+      if (intent === "extractMarkdown") {
+        limitations = [
+          ...limitations,
+          ...lim("Output: Markdown string via renderMarkdown.")
+        ];
+      } else if (intent === "extractLlmContent") {
+        limitations = [
+          ...limitations,
+          ...lim("Output: compact plain text via renderLlmText.")
+        ];
+      } else if (intent === "extractStructuredChunks") {
+        limitations = [
+          ...limitations,
+          ...lim("Output: MarkdownSection[] via renderMarkdownSections.")
+        ];
+      }
+      break;
     default:
       nativeExtraction = { willAttempt: false, description: "Intent not specialized in this runtime." };
       ocr = { mayUse: false, description: "See plan steps." };
@@ -701,7 +961,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 +1026,93 @@ 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 === "extractMarkdown" || intent === "extractLlmContent" || intent === "extractStructuredChunks") {
+    const sub = planForIntent(
+      "extractStructuredData",
+      kind,
+      ocrMode,
+      docxInclude,
+      ocr,
+      analyzeFileOutput
+    );
+    return {
+      intent,
+      steps: [
+        ...sub.steps ?? [],
+        { id: "docmind_markdown_render", status: "planned" }
+      ]
+    };
+  }
+  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 +1204,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, extractLlmContent, extractMarkdown, extractMetadata, extractStructuredChunks, 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.7.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,10 @@
   ],
   "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-markdown": "^1.0.0",
+    "@dragon708/docmind-ocr": "^1.1.4",
+    "@dragon708/docmind-shared": "^1.2.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.37",