@dragon708/docmind-browser 1.8.6 → 1.9.0

package/README.md

@@ -0,0 +1,179 @@
+# `@dragon708/docmind-browser`
+
+**Cliente oficial de DocMind para el navegador** (API pública de alto nivel): mismos **intents** que en Node (`analyzeFile`, `extractText`, `extractMetadata`, `convertToHtml`, `runOcr`, `extractStructuredData`, `extractMarkdown`, `extractLlmContent`, `extractStructuredChunks`, `detectFileKind`, `getCapabilities`, `explainAnalysisPlan`) pero con un **alcance de runtime** distinto: aquí hay **DOCX**, **imágenes (OCR con Tesseract.js / WASM)** y **texto UTF-8**. **No** hay motor PDF completo ni **conversión binaria pesada a Markdown** (PDF/HTML/CSV/Excel desde bytes) en el navegador: esas rutas viven en Node.
+
+---
+
+## Instalación
+
+```bash
+npm install @dragon708/docmind-browser
+```
+
+Incluye `@dragon708/docmind-ocr` (Tesseract.js), `@dragon708/docmind-docx`, `@dragon708/docmind-markdown` y `@dragon708/docmind-shared`. El bundle será pesado por WASM y modelos de OCR si los cargas.
+
+---
+
+## Alcance: navegador vs Node
+
+| Capacidad | En navegador (`docmind-browser`) | En Node (`docmind-node`) |
+|-----------|-----------------------------------|---------------------------|
+| PDF texto/metadata/OCR/pdf.js | No (PDF → `not_implemented` o envelope vacío según API) | Sí |
+| DOCX texto/HTML/structured | Sí (Mammoth) | Sí |
+| Imagen OCR | Sí (Tesseract.js) | Sí |
+| `extractMarkdown` con bytes PDF/HTML/CSV/XLSX | No (en cliente: fallback estructurado o vacío con avisos) | Sí (motor de conversión en Node) |
+| `extractLlmContent` / chunks | Sobre structured disponible (DOCX/imagen/texto) | Igual + PDF |
+
+Las funciones **`convertHtmlToMarkdown`**, **`convertCsvToMarkdown`**, **`convertSpreadsheetToMarkdown`** y **`detectBinaryFormat`** se re-exportan para **imports isomórficos**; en navegador devuelven rutas “unsupported runtime” con `warnings` (no lanzan por defecto en el patrón de markdown package).
+
+---
+
+## Uso rápido
+
+### Analizar un `File` del `<input type="file">`
+
+```ts
+import { analyzeFile } from "@dragon708/docmind-browser";
+
+input.addEventListener("change", async () => {
+  const file = input.files?.[0];
+  if (!file) return;
+  const result = await analyzeFile(file);
+  console.log(result.text, result.warnings);
+});
+```
+
+### Structured opcional en `analyzeFile`
+
+```ts
+import { analyzeFile } from "@dragon708/docmind-browser";
+import { analyzeFileRequestsStructured } from "@dragon708/docmind-shared";
+
+const result = await analyzeFile(file, {
+  structuredOutput: true,
+});
+if ("structured" in result && result.structured) {
+  console.log(result.structured.blocks.length);
+}
+```
+
+### Documento estructurado
+
+```ts
+import { extractStructuredData } from "@dragon708/docmind-browser";
+
+const structured = await extractStructuredData({
+  data: await file.arrayBuffer(),
+  name: file.name,
+  mimeType: file.type,
+});
+```
+
+Para **PDF**, el resultado suele ser un envelope con advertencias de soporte (`BROWSER_PDF_STRUCTURED_UNSUPPORTED_WARNING`, etc.); no uses este paquete como sustituto de `@dragon708/docmind-node` para PDF.
+
+### OCR en imagen
+
+```ts
+import { runOcr, analyzeFile } from "@dragon708/docmind-browser";
+
+// runOcr respeta BrowserAnalyzeOptions.ocr.mode: off | auto | force
+const ocrResult = await runOcr(file, { ocr: { mode: "auto" } });
+```
+
+### Markdown / LLM / chunks en navegador
+
+```ts
+import {
+  extractMarkdown,
+  extractLlmContent,
+  extractStructuredChunks,
+} from "@dragon708/docmind-browser";
+
+// DOCX/imagen/texto: structured → Markdown (Turndown/serialización según ruta)
+const md = await extractMarkdown(file, { /* BrowserExtractMarkdownOptions */ });
+const llm = await extractLlmContent(file, { /* … */ });
+const sections = await extractStructuredChunks(file, {
+  chunks: { includeMarkdown: true },
+});
+```
+
+### Introspección
+
+```ts
+import { getCapabilities, explainAnalysisPlan } from "@dragon708/docmind-browser";
+
+const caps = await getCapabilities({ /* … */ });
+const plan = await explainAnalysisPlan({ /* … */ });
+```
+
+### Clasificación
+
+```ts
+import { detectFileKind } from "@dragon708/docmind-browser";
+```
+
+### Extractores por formato (sin PDF)
+
+```ts
+import {
+  extractStructuredDataFromDocx,
+  extractStructuredDataFromImage,
+} from "@dragon708/docmind-browser";
+```
+
+---
+
+## Opciones (`BrowserAnalyzeOptions`)
+
+Incluyen cortes alineados con Node donde aplica:
+
+- **`ocr`**: `BrowserOcrOptions` con `mode` `off` | `auto` | `force`.
+- **`docx`**: `include` (headings, tables, blocks, …) como en Node.
+- **`structuredOutput` / `output`**: merge de `structured` en `analyzeFile`.
+
+Para Markdown/LLM/chunks: **`BrowserExtractMarkdownOptions`**, **`BrowserExtractLlmContentOptions`**, **`BrowserExtractStructuredChunksOptions`**.
+
+---
+
+## Constantes útiles
+
+- **`BROWSER_PDF_UNSUPPORTED_WARNING`**: texto de aviso cuando se intenta PDF en rutas que no lo implementan.
+- **`BROWSER_PDF_STRUCTURED_UNSUPPORTED_WARNING`**: structured PDF no disponible en browser.
+
+---
+
+## Capacidades declarativas
+
+- **`DOCX_EMBEDDED_IMAGE_CAPABILITIES_BROWSER`**, **`DOCX_STRUCTURE_CAPABILITIES_BROWSER`**, **`docxIncludeRequested`**: para informes tipo `getCapabilities`.
+
+---
+
+## Rendimiento y UX
+
+- **Tesseract.js** descarga idiomas y WASM en el cliente; primer uso puede ser lento.
+- **TIFF multipage**: soporte best-effort (UTIF) con limitaciones documentadas en warnings y `explainAnalysisPlan`.
+
+---
+
+## Paquetes relacionados
+
+| Paquete | Rol |
+|---------|-----|
+| `@dragon708/docmind-node` | PDF, conversión binaria a Markdown en servidor |
+| `@dragon708/docmind-shared` | Tipos compartidos |
+| `@dragon708/docmind-markdown` | Lógica Markdown/LLM/chunks (en browser sin rutas binarias pesadas) |
+| `@dragon708/docmind-docx` | DOCX |
+| `@dragon708/docmind-ocr` | OCR raster |
+
+---
+
+## Seguridad
+
+- No insertes HTML de `convertToHtml` sin sanitizar si el documento no es de confianza.
+- Los modelos OCR y WASM se ejecutan en el cliente; valora privacidad y tamaño de descarga.
+
+---
+
+## Licencia
+
+MIT (monorepo DocMind).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dragon708/docmind-browser",
-  "version": "1.8.6",
+  "version": "1.9.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,10 +33,10 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@dragon708/docmind-docx": "^1.8.0",
-    "@dragon708/docmind-markdown": "^1.2.9",
-    "@dragon708/docmind-ocr": "^1.1.4",
-    "@dragon708/docmind-shared": "^1.2.0"
+    "@dragon708/docmind-docx": "^1.9.0",
+    "@dragon708/docmind-markdown": "^1.3.0",
+    "@dragon708/docmind-ocr": "^1.2.0",
+    "@dragon708/docmind-shared": "^1.3.0"
   },
   "devDependencies": {
     "@types/node": "^20.19.37",