@dragon708/docmind-browser 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -1,22 +1,130 @@
-import { AnalysisResult } from '@dragon708/docmind-shared';
-export { AnalysisAnalyzer, AnalysisResult, DetectFileKindInput, DocxAnalysisCoreResult, FileKind, FileKindMetadata, GenericAnalysisResult, ImageAnalysisCoreResult, PdfAnalysisCoreResult, TextAnalysisResult } from '@dragon708/docmind-shared';
+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';
 
-/** Options for {@link analyzeFile} in the browser entry (no PDF pipeline). */
-interface BrowserAnalyzeOptions {
-    readonly signal?: AbortSignal;
-    readonly ocr?: OcrOptions;
+/**
+ * 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.
+ */
+type BrowserOcrMode = "off" | "auto" | "force";
+/** Browser OCR options: Tesseract knobs from `@dragon708/docmind-ocr` plus optional {@link BrowserOcrMode}. */
+interface BrowserOcrOptions extends OcrOptions {
+    readonly mode?: BrowserOcrMode;
+}
+/**
+ * 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 {
+    /** Image OCR only; no PDF in this runtime. See {@link BrowserOcrOptions.mode}. */
+    readonly ocr?: BrowserOcrOptions;
 }
 
-/** 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.";
 /**
  * Inputs supported by the browser entry (DOM types only — no `fs`, no Node `Buffer` in the public surface).
  */
 type BrowserAnalyzeInput = File | Blob | ArrayBuffer;
+
 /**
- * Browser-only router: DOCX, images (OCR), and text. PDF yields `not_implemented` with a clear warning.
+ * 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}.
  */
 declare function analyzeFile(input: BrowserAnalyzeInput, options?: BrowserAnalyzeOptions): Promise<AnalysisResult>;
 
-export { BROWSER_PDF_UNSUPPORTED_WARNING, type BrowserAnalyzeInput, type BrowserAnalyzeOptions, analyzeFile };
+/**
+ * Full text extraction using the same document pipeline as {@link analyzeFile} (not ad-hoc DOCX/OCR calls).
+ * Plain-text inputs still decode via the shared text analyzer inside `analyzeFile`.
+ */
+declare function extractText(input: BrowserAnalyzeInput, options?: BrowserAnalyzeOptions): Promise<AnalysisResult>;
+/**
+ * Metadata-oriented view. Does not run heavy extractors for DOCX/images (stubs only).
+ * Plain-text files use the same `analyzeFile` path as {@link extractText} for consistency.
+ */
+declare function extractMetadata(input: BrowserAnalyzeInput, options?: BrowserAnalyzeOptions): Promise<AnalysisResult>;
+/**
+ * HTML-oriented view. Uses {@link analyzeFile} for DOCX and plain text only so raster images never trigger OCR.
+ * PDF and unknown kinds follow the same stubs as other intents.
+ */
+declare function convertToHtml(input: BrowserAnalyzeInput, options?: BrowserAnalyzeOptions): Promise<AnalysisResult>;
+/**
+ * OCR-focused intent. Honors {@link BrowserAnalyzeOptions.ocr} **mode** (`off` | `auto` | `force`) for images.
+ * 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>;
+
+/**
+ * Whether DocMind will try a non-OCR text/HTML path (e.g. Mammoth, UTF-8, PDF text layer — when available).
+ */
+interface NativeExtractionPlan {
+    readonly willAttempt: boolean;
+    readonly description: string;
+}
+/** Whether raster/PDF OCR could run for this intent + kind (subject to options). */
+interface OcrPlan {
+    readonly mayUse: boolean;
+    readonly description: string;
+}
+/**
+ * Structured explanation of what DocMind would do for a public intent (no heavy I/O).
+ * Suitable for playgrounds and debug UIs.
+ */
+interface ExplainAnalysisPlanReport {
+    /** Detected {@link FileKind} from name/MIME/sniff hints. */
+    readonly kind: FileKind;
+    /** Same as {@link kind}; kept for symmetry with older `ExplainAnalysisPlanResult` consumers. */
+    readonly detectedKind: FileKind;
+    readonly runtime: RuntimeDescriptor;
+    readonly intent: DocMindPublicIntent | (string & {});
+    /** Router target analyzer for this kind (`none` when unknown or PDF in browser). */
+    readonly primaryAnalyzer: AnalysisAnalyzer;
+    readonly nativeExtraction: NativeExtractionPlan;
+    readonly ocr: OcrPlan;
+    /** User-facing caveats (PDF unsupported, unknown kind, OCR off, etc.). */
+    readonly limitations: readonly string[];
+    /** Ordered pipeline steps (planned/skipped/done metadata only). */
+    readonly plan: ProcessingPlanDescriptor;
+    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">;
+
+/**
+ * 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.
+ */
+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.
+ */
+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 };

package/dist/index.js

@@ -1,8 +1,27 @@
-import { assertValidAnalyzeFileInput, detectFileKind, notImplementedResult, UNKNOWN_FORMAT_WARNING, analyzeText, InvalidInputError, toUint8Array } from '@dragon708/docmind-shared';
+import { assertValidAnalyzeFileInput, detectFileKind, notImplementedResult, UNKNOWN_FORMAT_WARNING, analyzeText, toUint8Array, InvalidInputError } from '@dragon708/docmind-shared';
+export { detectFileKind } from '@dragon708/docmind-shared';
 import { analyzeDocx } from '@dragon708/docmind-docx';
 import { ocr } from '@dragon708/docmind-ocr';
 
 // src/analyzeFile.ts
+function assertBrowserInput(input) {
+  const ok = input instanceof File || input instanceof Blob || input instanceof ArrayBuffer;
+  if (!ok) {
+    throw new InvalidInputError("Expected a File, Blob, or ArrayBuffer.");
+  }
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    const err = new Error("The operation was aborted");
+    err.name = "AbortError";
+    throw err;
+  }
+}
+function prepareBrowserAnalyzeInput(input) {
+  assertBrowserInput(input);
+  assertValidAnalyzeFileInput(input);
+  return input;
+}
 async function analyzeDocxForBrowser(input, signal) {
   if (signal?.aborted) {
     const err = new Error("The operation was aborted");
@@ -32,6 +51,10 @@ async function analyzeDocxForBrowser(input, signal) {
     warnings: [...r.warnings]
   };
 }
+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";
+}
 async function analyzeImageForBrowser(input, options) {
   if (options?.signal?.aborted) {
     const err = new Error("The operation was aborted");
@@ -51,6 +74,19 @@ async function analyzeImageForBrowser(input, options) {
       warnings: ["No image bytes were provided for analysis."]
     };
   }
+  const mode = resolveOcrMode(options);
+  if (mode === "off") {
+    return {
+      fileKind: "image",
+      analyzer: "image",
+      status: "ok",
+      kind: "image",
+      text: "",
+      confidence: 0,
+      ocrUsed: false,
+      warnings: [OCR_OFF_WARNING]
+    };
+  }
   const ocrOpts = {
     ...options?.ocr ?? {},
     signal: options?.ocr?.signal ?? options?.signal
@@ -70,12 +106,6 @@ async function analyzeImageForBrowser(input, options) {
 
 // src/analyzeFile.ts
 var BROWSER_PDF_UNSUPPORTED_WARNING = "PDF text extraction is not available in the browser runtime; use @dragon708/docmind-node on the server.";
-function assertBrowserInput(input) {
-  const ok = input instanceof File || input instanceof Blob || input instanceof ArrayBuffer;
-  if (!ok) {
-    throw new InvalidInputError("Expected a File, Blob, or ArrayBuffer.");
-  }
-}
 async function analyzeFile(input, options) {
   if (options?.signal?.aborted) {
     const err = new Error("The operation was aborted");
@@ -99,7 +129,523 @@ 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 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;");
+}
+function toExtractTextResult(full) {
+  if (full.status !== "ok") return full;
+  if (full.fileKind === "docx") {
+    return { ...full, html: "" };
+  }
+  return full;
+}
+async function extractText(input, options) {
+  throwIfAborted(options?.signal);
+  prepareBrowserAnalyzeInput(input);
+  const full = await analyzeFile(input, options);
+  return toExtractTextResult(full);
+}
+async function extractMetadata(input, options) {
+  throwIfAborted(options?.signal);
+  const resolved = prepareBrowserAnalyzeInput(input);
+  const kind = detectFileKind(resolved);
+  options?.signal;
+  switch (kind) {
+    case "pdf":
+      return notImplementedResult("pdf", "pdf", [BROWSER_PDF_UNSUPPORTED_WARNING]);
+    case "docx":
+      return {
+        fileKind: "docx",
+        analyzer: "docx",
+        status: "ok",
+        kind: "docx",
+        text: "",
+        html: "",
+        warnings: [DOCX_METADATA_STUB]
+      };
+    case "image":
+      return {
+        fileKind: "image",
+        analyzer: "image",
+        status: "ok",
+        kind: "image",
+        text: "",
+        confidence: 0,
+        ocrUsed: true,
+        warnings: [IMAGE_METADATA_NOTE]
+      };
+    case "text":
+      return analyzeFile(input, options);
+    default:
+      return notImplementedResult(kind, "none", [UNKNOWN_FORMAT_WARNING]);
+  }
+}
+async function convertToHtml(input, options) {
+  throwIfAborted(options?.signal);
+  const resolved = prepareBrowserAnalyzeInput(input);
+  const kind = detectFileKind(resolved);
+  if (kind === "pdf") {
+    return notImplementedResult("pdf", "pdf", [BROWSER_PDF_UNSUPPORTED_WARNING]);
+  }
+  if (kind === "image") {
+    return {
+      fileKind: "image",
+      analyzer: "image",
+      status: "ok",
+      kind: "image",
+      text: "",
+      confidence: 0,
+      ocrUsed: true,
+      warnings: ["No HTML representation for raster images; use extractText / runOcr."]
+    };
+  }
+  if (kind === "unknown") {
+    return notImplementedResult(kind, "none", [UNKNOWN_FORMAT_WARNING]);
+  }
+  const r = await analyzeFile(input, options);
+  if (r.status !== "ok") return r;
+  if (r.fileKind === "text") {
+    const html = `<pre>${escapeHtmlMinimal(r.text)}</pre>`;
+    return {
+      ...r,
+      html,
+      warnings: [
+        ...r.warnings,
+        "HTML for plain text is a <pre> wrapper around decoded UTF-8 content."
+      ]
+    };
+  }
+  return r;
+}
+async function runOcr(input, options) {
+  throwIfAborted(options?.signal);
+  const resolved = prepareBrowserAnalyzeInput(input);
+  const kind = detectFileKind(resolved);
+  const bytesInput = input;
+  const signal = options?.signal;
+  switch (kind) {
+    case "pdf":
+      return notImplementedResult("pdf", "pdf", [BROWSER_PDF_UNSUPPORTED_WARNING]);
+    case "image":
+      return analyzeImageForBrowser(bytesInput, options);
+    case "docx": {
+      const data = await toUint8Array(bytesInput);
+      if (data.byteLength === 0) {
+        return {
+          fileKind: "docx",
+          analyzer: "docx",
+          status: "ok",
+          kind: "docx",
+          text: "",
+          html: "",
+          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,
+          "OCR does not apply to DOCX; returned structured text/HTML extract."
+        ]
+      };
+    }
+    case "text":
+      return analyzeText(bytesInput, { signal });
+    default:
+      return notImplementedResult(kind, "none", [UNKNOWN_FORMAT_WARNING]);
+  }
+}
+
+// src/analysisPlanReport.ts
+function lim(...items) {
+  return items.filter(Boolean);
+}
+function buildBrowserExplainReport(kind, intent, ocrMode, plan) {
+  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 limitations = [];
+  const ocrOffNote = ocrMode === "off" ? 'Image OCR is skipped when ocr.mode is "off".' : "";
+  if (kind === "pdf") {
+    limitations = lim(BROWSER_PDF_UNSUPPORTED_WARNING);
+    nativeExtraction = {
+      willAttempt: false,
+      description: "PDF is not processed in the browser runtime; use @dragon708/docmind-node."
+    };
+    ocr2 = {
+      mayUse: false,
+      description: "PDF OCR is not available in the browser."
+    };
+    return {
+      kind,
+      detectedKind: kind,
+      runtime,
+      intent,
+      primaryAnalyzer: "pdf",
+      nativeExtraction,
+      ocr: ocr2,
+      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 {
+      kind,
+      detectedKind: kind,
+      runtime,
+      intent,
+      primaryAnalyzer: "none",
+      nativeExtraction,
+      ocr: ocr2,
+      limitations,
+      plan
+    };
+  }
+  switch (intent) {
+    case "analyzeFile":
+    case "extractText":
+      if (kind === "docx") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "Mammoth reads OOXML for text" + (intent === "extractText" ? " (HTML omitted in extractText)." : " and HTML.")
+        };
+        ocr2 = { 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."
+        };
+        ocr2 = {
+          mayUse: imageOcrActive,
+          description: imageOcrActive ? "Tesseract.js may run to recover text (subject to format support)." : "OCR skipped while ocr.mode is off."
+        };
+        limitations = lim(ocrOffNote);
+      } 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." };
+      }
+      break;
+    case "extractMetadata":
+      if (kind === "docx" || kind === "image") {
+        nativeExtraction = {
+          willAttempt: false,
+          description: "No heavy extractor; extractMetadata returns a stub with guidance."
+        };
+        ocr2 = { 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."
+        );
+      } else {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "Plain text is decoded; metadata is limited to decoded content."
+        };
+        ocr2 = { mayUse: false, description: "OCR does not apply." };
+        limitations = lim("Plain text has no structured document metadata.");
+      }
+      break;
+    case "convertToHtml":
+      if (kind === "docx") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "Mammoth produces HTML; images are not passed through analyzeFile for this intent."
+        };
+        ocr2 = { 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." };
+      } 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." };
+        limitations = lim(
+          kind === "image" ? "Raster images have no HTML representation; use extractText or runOcr." : ""
+        );
+      }
+      break;
+    case "runOcr":
+      if (kind === "image") {
+        nativeExtraction = {
+          willAttempt: false,
+          description: "No native text layer; recognition is OCR-only."
+        };
+        ocr2 = {
+          mayUse: imageOcrActive,
+          description: imageOcrActive ? "Tesseract.js runs for raster text." : "OCR skipped while ocr.mode is off."
+        };
+        limitations = lim(ocrOffNote);
+      } else if (kind === "docx") {
+        nativeExtraction = {
+          willAttempt: true,
+          description: "Mammoth returns structured text/HTML (OCR does not apply to DOCX)."
+        };
+        ocr2 = { 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." };
+      }
+      break;
+    default:
+      nativeExtraction = { willAttempt: false, description: "Intent not specialized in this runtime." };
+      ocr2 = { mayUse: false, description: "See plan steps." };
+  }
+  return {
+    kind,
+    detectedKind: kind,
+    runtime,
+    intent,
+    primaryAnalyzer,
+    nativeExtraction,
+    ocr: ocr2,
+    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 };
+}
+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)
+      ];
+  }
+  return {
+    kind,
+    runtime,
+    capabilities,
+    warnings: topWarnings.length > 0 ? topWarnings : void 0
+  };
+}
+
+// src/introspection.ts
+function resolveOcrMode2(ocr2) {
+  return ocr2?.mode ?? "auto";
+}
+function planForAnalyzeFile(kind, ocrMode) {
+  switch (kind) {
+    case "pdf":
+      return {
+        intent: "analyzeFile",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "pdf_pipeline", status: "skipped" }
+        ]
+      };
+    case "docx":
+      return {
+        intent: "analyzeFile",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "docx_mammoth", status: "planned" }
+        ]
+      };
+    case "image":
+      return {
+        intent: "analyzeFile",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          {
+            id: "image_ocr",
+            status: ocrMode === "off" ? "skipped" : "planned"
+          }
+        ]
+      };
+    case "text":
+      return {
+        intent: "analyzeFile",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "utf8_decode", status: "planned" }
+        ]
+      };
+    default:
+      return {
+        intent: "analyzeFile",
+        steps: [{ id: "detect_kind", status: "done" }, { id: "route", status: "failed" }]
+      };
+  }
+}
+function planForIntent(intentOpt, kind, ocrMode) {
+  const intent = intentOpt ?? "analyzeFile";
+  if (intent === "analyzeFile") return planForAnalyzeFile(kind, ocrMode);
+  if (intent === "extractText") {
+    const base = planForAnalyzeFile(kind, ocrMode);
+    return { ...base, intent: "extractText" };
+  }
+  if (intent === "extractMetadata") {
+    if (kind === "text") {
+      return {
+        intent: "extractMetadata",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "utf8_decode", status: "planned" }
+        ]
+      };
+    }
+    return {
+      intent: "extractMetadata",
+      steps: [
+        { id: "detect_kind", status: "done" },
+        { id: "metadata_stub", status: kind === "docx" || kind === "image" ? "planned" : "skipped" }
+      ]
+    };
+  }
+  if (intent === "convertToHtml") {
+    if (kind === "docx") {
+      return {
+        intent: "convertToHtml",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "docx_mammoth_html", status: "planned" }
+        ]
+      };
+    }
+    if (kind === "text") {
+      return {
+        intent: "convertToHtml",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "utf8_decode", status: "planned" },
+          { id: "wrap_pre", status: "planned" }
+        ]
+      };
+    }
+    return {
+      intent: "convertToHtml",
+      steps: [
+        { id: "detect_kind", status: "done" },
+        { id: "rich_html", status: "skipped" }
+      ]
+    };
+  }
+  if (intent === "runOcr") {
+    if (kind === "image") {
+      return {
+        intent: "runOcr",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "tesseract_ocr", status: ocrMode === "off" ? "skipped" : "planned" }
+        ]
+      };
+    }
+    if (kind === "docx") {
+      return {
+        intent: "runOcr",
+        steps: [
+          { id: "detect_kind", status: "done" },
+          { id: "docx_structured_extract", status: "planned" }
+        ]
+      };
+    }
+    return {
+      intent: "runOcr",
+      steps: [
+        { id: "detect_kind", status: "done" },
+        { id: "ocr", status: "skipped" }
+      ]
+    };
+  }
+  return planForAnalyzeFile(kind, ocrMode);
+}
+async function getCapabilities(input, options) {
+  throwIfAborted(options?.signal);
+  prepareBrowserAnalyzeInput(input);
+  const kind = detectFileKind(input);
+  return buildBrowserCapabilityReport(kind);
+}
+async function explainAnalysisPlan(input, options) {
+  throwIfAborted(options?.signal);
+  prepareBrowserAnalyzeInput(input);
+  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);
+}
 
-export { BROWSER_PDF_UNSUPPORTED_WARNING, analyzeFile };
+export { BROWSER_PDF_UNSUPPORTED_WARNING, analyzeFile, convertToHtml, explainAnalysisPlan, extractMetadata, extractText, getCapabilities, runOcr };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dragon708/docmind-browser",
-  "version": "1.0.0",
-  "description": "Browser DocMind entry: DOCX, OCR, text (no PDF; use @dragon708/docmind-node on the server).",
+  "version": "1.2.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,
   "main": "./dist/index.js",
@@ -15,7 +15,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
   ],
   "publishConfig": {
     "access": "public"
@@ -34,7 +35,7 @@
   "dependencies": {
     "@dragon708/docmind-docx": "^1.0.0",
     "@dragon708/docmind-ocr": "^1.0.0",
-    "@dragon708/docmind-shared": "^1.0.0"
+    "@dragon708/docmind-shared": "^1.1.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.37",

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/analyzers/docx.ts","../src/analyzers/image.ts","../src/analyzeFile.ts"],"names":["extractDocx","toUint8Array"],"mappings":"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","file":"index.js","sourcesContent":["import { analyzeDocx as extractDocx } from \"@dragon708/docmind-docx\";\nimport type { AnalysisResult, FileLikeInput } from \"@dragon708/docmind-shared\";\nimport { toUint8Array } from \"@dragon708/docmind-shared\";\n\n/**\n * DOCX → `@dragon708/docmind-docx` (browser-safe: Mammoth + JSZip).\n */\nexport async function analyzeDocxForBrowser(\n  input: FileLikeInput,\n  signal?: AbortSignal,\n): Promise<AnalysisResult> {\n  if (signal?.aborted) {\n    const err = new Error(\"The operation was aborted\");\n    err.name = \"AbortError\";\n    throw err;\n  }\n\n  const data = await toUint8Array(input);\n  if (data.byteLength === 0) {\n    return {\n      fileKind: \"docx\",\n      analyzer: \"docx\",\n      status: \"ok\",\n      kind: \"docx\",\n      text: \"\",\n      html: \"\",\n      warnings: [\"No document bytes were provided for analysis.\"],\n    };\n  }\n\n  const r = await extractDocx(data);\n  return {\n    fileKind: \"docx\",\n    analyzer: \"docx\",\n    status: \"ok\",\n    kind: \"docx\",\n    text: r.text,\n    html: r.html,\n    warnings: [...r.warnings],\n  };\n}\n","import { ocr } from \"@dragon708/docmind-ocr\";\nimport type { AnalysisResult, FileLikeInput } from \"@dragon708/docmind-shared\";\nimport { toUint8Array } from \"@dragon708/docmind-shared\";\nimport type { BrowserAnalyzeOptions } from \"../browserAnalyzeOptions.js\";\n\n/**\n * Image → `@dragon708/docmind-ocr` (Tesseract in WASM / browser).\n */\nexport async function analyzeImageForBrowser(\n  input: FileLikeInput,\n  options?: BrowserAnalyzeOptions,\n): Promise<AnalysisResult> {\n  if (options?.signal?.aborted) {\n    const err = new Error(\"The operation was aborted\");\n    err.name = \"AbortError\";\n    throw err;\n  }\n\n  const data = await toUint8Array(input);\n  if (data.byteLength === 0) {\n    return {\n      fileKind: \"image\",\n      analyzer: \"image\",\n      status: \"ok\",\n      kind: \"image\",\n      text: \"\",\n      confidence: 0,\n      ocrUsed: true,\n      warnings: [\"No image bytes were provided for analysis.\"],\n    };\n  }\n\n  const ocrOpts = {\n    ...(options?.ocr ?? {}),\n    signal: options?.ocr?.signal ?? options?.signal,\n  };\n\n  const r = await ocr(data, ocrOpts);\n  return {\n    fileKind: \"image\",\n    analyzer: \"image\",\n    status: \"ok\",\n    kind: \"image\",\n    text: r.text,\n    confidence: r.confidence,\n    ocrUsed: r.ocrUsed,\n    warnings: [],\n  };\n}\n","import type { AnalysisResult, FileLikeInput } from \"@dragon708/docmind-shared\";\r\nimport {\r\n  analyzeText,\r\n  assertValidAnalyzeFileInput,\r\n  detectFileKind,\r\n  InvalidInputError,\r\n  notImplementedResult,\r\n  UNKNOWN_FORMAT_WARNING,\r\n} from \"@dragon708/docmind-shared\";\r\nimport type { DetectFileKindInput } from \"@dragon708/docmind-shared\";\r\nimport type { BrowserAnalyzeOptions } from \"./browserAnalyzeOptions.js\";\r\nimport { analyzeDocxForBrowser } from \"./analyzers/docx.js\";\r\nimport { analyzeImageForBrowser } from \"./analyzers/image.js\";\r\n\r\n/** PDF is not processed in the browser; use `@dragon708/docmind-node` on the server. */\r\nexport const BROWSER_PDF_UNSUPPORTED_WARNING =\r\n  \"PDF text extraction is not available in the browser runtime; use @dragon708/docmind-node on the server.\";\r\n\r\n/**\r\n * Inputs supported by the browser entry (DOM types only — no `fs`, no Node `Buffer` in the public surface).\r\n */\r\nexport type BrowserAnalyzeInput = File | Blob | ArrayBuffer;\r\n\r\nfunction assertBrowserInput(input: unknown): asserts input is BrowserAnalyzeInput {\r\n  const ok =\r\n    input instanceof File ||\r\n    input instanceof Blob ||\r\n    input instanceof ArrayBuffer;\r\n  if (!ok) {\r\n    throw new InvalidInputError(\"Expected a File, Blob, or ArrayBuffer.\");\r\n  }\r\n}\r\n\r\n/**\r\n * Browser-only router: DOCX, images (OCR), and text. PDF yields `not_implemented` with a clear warning.\r\n */\r\nexport async function analyzeFile(\r\n  input: BrowserAnalyzeInput,\r\n  options?: BrowserAnalyzeOptions,\r\n): Promise<AnalysisResult> {\r\n  if (options?.signal?.aborted) {\r\n    const err = new Error(\"The operation was aborted\");\r\n    err.name = \"AbortError\";\r\n    throw err;\r\n  }\r\n\r\n  assertBrowserInput(input);\r\n  assertValidAnalyzeFileInput(input);\r\n\r\n  const fileKind = detectFileKind(input as DetectFileKindInput);\r\n\r\n  const bytesInput = input as FileLikeInput;\r\n\r\n  switch (fileKind) {\r\n    case \"pdf\":\r\n      return notImplementedResult(\"pdf\", \"pdf\", [BROWSER_PDF_UNSUPPORTED_WARNING]);\r\n    case \"docx\":\r\n      return analyzeDocxForBrowser(bytesInput, options?.signal);\r\n    case \"image\":\r\n      return analyzeImageForBrowser(bytesInput, options);\r\n    case \"text\":\r\n      return analyzeText(bytesInput, { signal: options?.signal });\r\n    default:\r\n      return notImplementedResult(fileKind, \"none\", [UNKNOWN_FORMAT_WARNING]);\r\n  }\r\n}\r\n"]}