hazo_pdf 1.6.6 → 1.7.0

package/README.md

@@ -21,6 +21,7 @@ A React component library for viewing and annotating PDF documents with support
 - ☁️ **Remote Storage** - Load and save PDFs from Google Drive, Dropbox, or local storage (via hazo_files)
 - 🖼️ **Dialog Component** - Ready-to-use modal dialog wrapper (`PdfViewerDialog`)
 - 🔧 **Server Utilities** - Server-side extraction utilities via `hazo_pdf/server` entry point
+- 🔎 **Text Snippet Extraction** - Server-side: find text in a PDF, highlight it, and return a cropped image snippet
 
 ## Installation
 
@@ -54,6 +55,14 @@ npm install hazo_llm_api
 
 The `hazo_llm_api` package is an optional peer dependency. When installed, it enables server-side document data extraction via the `hazo_pdf/server` entry point. See [Server-Side Extraction](#server-side-extraction) for details.
 
+**@napi-rs/canvas** (optional): For server-side text snippet extraction
+
+```bash
+npm install @napi-rs/canvas
+```
+
+Required only for the `extract_text_snippet()` server utility. Already installed as a transitive dependency of `pdfjs-dist` in most environments. See [Text Snippet Extraction](#text-snippet-extraction) for details.
+
 ## CSS Import Options
 
 The library provides two CSS files to choose from:
@@ -924,7 +933,8 @@ You can override any or all of these on a per-highlight basis.
 | `doc_data` | `Record<string, unknown>` | `undefined` | General document data to display in the File Info sidepanel. Shown in the "Document Data" section. Can contain any structured data from extraction (strings, numbers, arrays, objects). |
 | `highlight_fields_info` | `HighlightFieldInfo[]` | `undefined` | Array of highlighted/extracted fields to display with special styling. Shown in the "Highlighted Fields" section with field count. Each item has `field_name` (converted to Title Case) and `value` (displayed string). |
 | `file_metadata` | `FileMetadataInput` | `undefined` | Legacy format: Array of file metadata items with filename matching. Each item has `filename` (to match current file) and `file_data` (flexible JSON object with string fields or table arrays). See [File Info Sidepanel](#file-info-sidepanel) section for details. |
-| `show_file_info_button` | `boolean` | `true` | Show file info sidepanel button in toolbar. Button only appears when at least one of: `doc_data`, `highlight_fields_info`, or `file_metadata` is provided. |
+| `extractions` | `ExtractionEntry[]` | `undefined` | Extraction entries from hazo_files `file_data.raw_data`. Each entry has `id?`, `extracted_at?` (ISO timestamp), `source?` (e.g., "autofill"), and `data` (key-value pairs). Shown in a collapsible "Extractions" section. |
+| `show_file_info_button` | `boolean` | `true` | Show file info sidepanel button in toolbar. Button only appears when at least one of: `doc_data`, `highlight_fields_info`, `file_metadata`, or `extractions` is provided. |
 
 ##### Custom Stamps
 
@@ -1002,7 +1012,7 @@ Props for managing multiple PDF files. Mutually exclusive with `url` prop.
 | `on_upload` | `(file: File, converted_pdf?: Uint8Array) => Promise<UploadResult>` | `undefined` | Callback for file upload. Receives original file and optional converted PDF (for non-PDF files). Must return `{ success: boolean, file_id?: string, url?: string, error?: string }`. |
 | `on_files_change` | `(files: FileItem[]) => void` | `undefined` | Callback when files array changes (file added, deleted, or reordered). |
 | `direct_upload` | `boolean` | `false` | When `true`, clicking "+ Add file" opens the native file picker directly (1-click). The button also accepts drag & drop. When `false` (default), clicking shows a dropzone modal first (2-click). Can also be set via `file_upload.direct_upload` in INI config. |
-| `enable_popout` | `boolean` | `false` | Enable popout to new tab feature. Shows popout button in toolbar. |
+| `enable_popout` | `boolean` | `false` | Enable popout to new tab feature. Shows "Open in new tab" and "Download" buttons in toolbar. In single-file mode, opens the PDF URL directly; in multi-file mode, uses sessionStorage-based popout. |
 | `popout_route` | `string` | `'/pdf-viewer'` | Route path for popout viewer. Used to construct new tab URL. |
 | `on_popout` | `(context: PopoutContext) => void` | `undefined` | Custom popout handler. Overrides default sessionStorage behavior. Receives context with file info and annotations. |
 | `viewer_title` | `string` | `undefined` | Title for the viewer (shown in dialog mode or popout window). |
@@ -2199,7 +2209,8 @@ function CompleteSidepanelExample() {
 1. **Extracted Data** (from `file_metadata`) - if provided
 2. **Document Data** (from `doc_data`) - if provided
 3. **Highlighted Fields** (from `highlight_fields_info`) - if provided
-4. **File System Info** - filename and path
+4. **Extractions** (from `extractions`) - if provided, collapsible entries with source/timestamp
+5. **File System Info** - filename and path
 
 ### Integration with Data Extraction
 
@@ -2459,6 +2470,80 @@ interface ExtractDocumentResult {
 
 ---
 
+## Text Snippet Extraction
+
+Extract a cropped image snippet from a PDF with the search text highlighted. Useful for attaching contextual evidence from documents.
+
+### Basic Usage
+
+```typescript
+import { extract_text_snippet } from 'hazo_pdf/server';
+
+const result = await extract_text_snippet(
+  { file_path: '/path/to/document.pdf' },
+  {
+    search_text: 'invoice total',
+    snippet_size: 'half',       // 'full' | 'half' | 'quarter'
+    match_mode: 'first',        // 'first' | 'all'
+  }
+);
+
+if (result.success) {
+  for (const snippet of result.snippets) {
+    // snippet.image_buffer  - PNG Buffer (for saving to file or API response)
+    // snippet.image_base64  - Base64 PNG (for embedding in HTML/JSON)
+    // snippet.page_index    - Which page (0-based)
+    // snippet.matches       - Array of match positions
+    // snippet.highlight_approximate - true for image-based PDFs
+  }
+}
+```
+
+### Snippet Sizes
+
+All snippet sizes use the full page width. Only the height varies:
+
+| Size | Dimensions |
+|------|-----------|
+| `full` | Full page (W x H) |
+| `half` | Full width, half height (W x H/2) |
+| `quarter` | Full width, quarter height (W x H/4) |
+
+The snippet is centered on the matched text. If multiple matches are found on the same page, the snippet expands to cover all of them.
+
+### Match Modes
+
+| Mode | Behavior |
+|------|----------|
+| `first` | Returns a single snippet from the first page where text is found |
+| `all` | Returns one snippet per page that contains the text |
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `search_text` | `string` | Required | Text to search for |
+| `page_index` | `number` | `0` | Page to start searching (0-based) |
+| `snippet_size` | `SnippetSize` | `'half'` | Crop size relative to page |
+| `match_mode` | `SnippetMatchMode` | `'first'` | Return first match or all pages |
+| `render_scale` | `number` | `2.0` | Rendering quality (higher = sharper, larger file) |
+| `highlight_color` | `string` | `'rgba(255, 255, 0, 0.35)'` | Highlight color (CSS color string) |
+| `use_llm_for_image_pdf` | `boolean` | `false` | Use LLM vision for image-based PDFs |
+
+### Image-Based PDFs
+
+For scanned/image PDFs where text cannot be extracted from the text layer:
+
+- **Without LLM** (default): Returns full page as the snippet, no highlighting
+- **With LLM** (`use_llm_for_image_pdf: true`): Uses `hazo_llm_api` vision to find approximate text location and draw a rough highlight
+
+### Requirements
+
+- **`@napi-rs/canvas`**: Required for server-side canvas rendering. Usually already installed as a transitive dependency of `pdfjs-dist`.
+- **Server-only**: This utility runs in Node.js only (not in the browser).
+
+---
+
 ## Development
 
 ### Setup

package/dist/{chunk-LQTYLVBH.js → chunk-4JJOUQ62.js}

@@ -2047,7 +2047,8 @@ var FileInfoSidepanel = ({
   file_metadata,
   current_filename,
   doc_data,
-  highlight_fields_info
+  highlight_fields_info,
+  extractions
 }) => {
   const [expanded_tables, setExpandedTables] = useState7(/* @__PURE__ */ new Set());
   const resize_ref = useRef8(null);
@@ -2116,6 +2117,7 @@ var FileInfoSidepanel = ({
   const has_file_info = item !== null;
   const has_doc_data = doc_data && Object.keys(doc_data).length > 0;
   const has_highlight_info = highlight_fields_info && highlight_fields_info.length > 0;
+  const has_extractions = extractions && extractions.length > 0;
   return /* @__PURE__ */ jsxs7(Fragment4, { children: [
     !is_open && /* @__PURE__ */ jsx8(
       "button",
@@ -2213,7 +2215,74 @@ var FileInfoSidepanel = ({
                   /* @__PURE__ */ jsx8("span", { className: "cls_file_metadata_field_value cls_highlight_value", children: field.value })
                 ] }, idx)) })
               ] }),
-              (has_extracted_data || has_doc_data || has_highlight_info) && has_file_info && /* @__PURE__ */ jsx8("div", { className: "cls_file_info_divider" }),
+              has_extractions && /* @__PURE__ */ jsxs7("div", { className: "cls_file_info_extractions_section", children: [
+                (has_extracted_data || has_doc_data || has_highlight_info) && /* @__PURE__ */ jsx8("div", { className: "cls_file_info_divider" }),
+                /* @__PURE__ */ jsxs7("div", { className: "cls_file_info_section_header", children: [
+                  "Extractions (",
+                  extractions.length,
+                  ")"
+                ] }),
+                extractions.map((entry, idx) => {
+                  const entry_key = entry.id || `extraction_${idx}`;
+                  const is_expanded = expanded_tables.has(entry_key);
+                  const timestamp = entry.extracted_at ? new Date(entry.extracted_at).toLocaleString() : void 0;
+                  const data_entries = Object.entries(entry.data);
+                  return /* @__PURE__ */ jsxs7("div", { className: "cls_file_metadata_table_section", children: [
+                    /* @__PURE__ */ jsxs7(
+                      "button",
+                      {
+                        type: "button",
+                        onClick: () => toggle_table(entry_key),
+                        className: "cls_file_metadata_table_header",
+                        "aria-expanded": is_expanded,
+                        children: [
+                          /* @__PURE__ */ jsx8("span", { className: "cls_file_metadata_table_name", children: entry.source || `Extraction ${idx + 1}` }),
+                          timestamp && /* @__PURE__ */ jsx8("span", { className: "cls_file_metadata_table_count", children: timestamp }),
+                          is_expanded ? /* @__PURE__ */ jsx8(ChevronUp2, { className: "cls_file_metadata_table_icon", size: 16 }) : /* @__PURE__ */ jsx8(ChevronDown3, { className: "cls_file_metadata_table_icon", size: 16 })
+                        ]
+                      }
+                    ),
+                    is_expanded && /* @__PURE__ */ jsx8("div", { className: "cls_file_metadata_fields", children: data_entries.map(([key, value]) => {
+                      if (is_table(value)) {
+                        const table_key = `${entry_key}_${key}`;
+                        const table_expanded = expanded_tables.has(table_key);
+                        return /* @__PURE__ */ jsxs7("div", { className: "cls_file_metadata_table_section", children: [
+                          /* @__PURE__ */ jsxs7(
+                            "button",
+                            {
+                              type: "button",
+                              onClick: () => toggle_table(table_key),
+                              className: "cls_file_metadata_table_header",
+                              "aria-expanded": table_expanded,
+                              children: [
+                                /* @__PURE__ */ jsx8("span", { className: "cls_file_metadata_table_name", children: format_field_name(key) }),
+                                /* @__PURE__ */ jsxs7("span", { className: "cls_file_metadata_table_count", children: [
+                                  "(",
+                                  value.length,
+                                  " ",
+                                  value.length === 1 ? "item" : "items",
+                                  ")"
+                                ] }),
+                                table_expanded ? /* @__PURE__ */ jsx8(ChevronUp2, { className: "cls_file_metadata_table_icon", size: 16 }) : /* @__PURE__ */ jsx8(ChevronDown3, { className: "cls_file_metadata_table_icon", size: 16 })
+                              ]
+                            }
+                          ),
+                          table_expanded && /* @__PURE__ */ jsx8("div", { className: "cls_file_metadata_table_content", children: value.map((row, row_index) => /* @__PURE__ */ jsx8("div", { className: "cls_file_metadata_table_row", children: /* @__PURE__ */ jsx8("table", { className: "cls_file_metadata_row_table", children: /* @__PURE__ */ jsx8("tbody", { children: Object.entries(row).map(([field_name, field_value]) => /* @__PURE__ */ jsxs7("tr", { className: "cls_file_metadata_row_tr", children: [
+                            /* @__PURE__ */ jsx8("td", { className: "cls_file_metadata_row_label", children: format_field_name(field_name) }),
+                            /* @__PURE__ */ jsx8("td", { className: "cls_file_metadata_row_value", children: field_value })
+                          ] }, field_name)) }) }) }, row_index)) })
+                        ] }, key);
+                      }
+                      const display_value = typeof value === "object" && value !== null ? JSON.stringify(value, null, 2) : String(value ?? "");
+                      return /* @__PURE__ */ jsxs7("div", { className: "cls_file_metadata_field", children: [
+                        /* @__PURE__ */ jsx8("span", { className: "cls_file_metadata_field_label", children: format_field_name(key) }),
+                        /* @__PURE__ */ jsx8("span", { className: "cls_file_metadata_field_value", children: display_value })
+                      ] }, key);
+                    }) })
+                  ] }, entry_key);
+                })
+              ] }),
+              (has_extracted_data || has_doc_data || has_highlight_info || has_extractions) && has_file_info && /* @__PURE__ */ jsx8("div", { className: "cls_file_info_divider" }),
               has_file_info && item && /* @__PURE__ */ jsxs7("div", { className: "cls_file_info_system_section", children: [
                 /* @__PURE__ */ jsx8("div", { className: "cls_file_info_section_header", children: "File" }),
                 /* @__PURE__ */ jsxs7("div", { className: "cls_file_info_properties", children: [
@@ -2227,7 +2296,7 @@ var FileInfoSidepanel = ({
                   ] })
                 ] })
               ] }),
-              !has_extracted_data && !has_doc_data && !has_highlight_info && !has_file_info && /* @__PURE__ */ jsx8("div", { className: "cls_file_info_no_data", children: "No file information available" })
+              !has_extracted_data && !has_doc_data && !has_highlight_info && !has_extractions && !has_file_info && /* @__PURE__ */ jsx8("div", { className: "cls_file_info_no_data", children: "No file information available" })
             ] })
           ] })
         ]
@@ -2321,8 +2390,8 @@ async function load_pdf_config_async(config_file) {
     return load_config_browser(config_file);
   }
   try {
-    const { HazoConfig } = __require("hazo_config");
-    const hazo_config = new HazoConfig({ filePath: config_file });
+    const { AppConfig } = __require("hazo_config");
+    const hazo_config = new AppConfig({ filePath: config_file });
     logger.debug(`Using hazo_config to load: ${config_file}`);
     const get_value = (section, key) => {
       return hazo_config.get(section, key);
@@ -2931,8 +3000,8 @@ function load_pdf_config(config_file) {
     return default_config;
   }
   try {
-    const { HazoConfig } = __require("hazo_config");
-    const hazo_config = new HazoConfig({ filePath: config_file });
+    const { AppConfig } = __require("hazo_config");
+    const hazo_config = new AppConfig({ filePath: config_file });
     const get_value = (section, key) => {
       return hazo_config.get(section, key);
     };
@@ -4531,6 +4600,7 @@ var PdfViewer = forwardRef(({
   // File info sidepanel data props
   doc_data,
   highlight_fields_info,
+  extractions,
   // Auto-highlight props
   auto_highlight_enabled,
   auto_highlight_options,
@@ -5222,6 +5292,12 @@ ${suffix_line}`;
     return { updatedRow, allData };
   };
   const handle_popout = useCallback5(() => {
+    if (!is_multi_file_mode) {
+      if (effective_url) {
+        window.open(effective_url, "_blank");
+      }
+      return;
+    }
     if (!files || files.length === 0) {
       pdf_logger.warn("No files to popout");
       return;
@@ -5242,7 +5318,7 @@ ${suffix_line}`;
     } catch (err) {
       pdf_logger.error("Failed to popout", { error: err });
     }
-  }, [files, current_file, viewer_title, on_popout, popout_route]);
+  }, [is_multi_file_mode, effective_url, files, current_file, viewer_title, on_popout, popout_route]);
   useEffect10(() => {
     const should_auto_highlight = auto_highlight_enabled !== false && // Default true
     highlight_fields_info && highlight_fields_info.length > 0 && pdf_document;
@@ -5258,7 +5334,7 @@ ${suffix_line}`;
     });
     setAutoHighlightIds(/* @__PURE__ */ new Set());
     const perform_auto_highlights = async () => {
-      const { find_text_in_pdf } = await import("./text_search-GW2VYMU6.js");
+      const { find_text_in_pdf } = await import("./text_search-I2KZ7DTW.js");
       const new_ids = /* @__PURE__ */ new Set();
       const auto_config = config_ref.current?.auto_highlight || default_config.auto_highlight;
       const search_opts = {
@@ -5888,7 +5964,7 @@ ${suffix_line}`;
               children: /* @__PURE__ */ jsx15(PanelRight, { className: "cls_pdf_viewer_toolbar_icon", size: 16 })
             }
           ) }),
-          (file_metadata && file_metadata.length > 0 || hazo_files_available || doc_data || highlight_fields_info) && toolbar_config.toolbar_show_file_info_button && /* @__PURE__ */ jsx15("div", { className: "cls_pdf_viewer_toolbar_group", children: /* @__PURE__ */ jsx15(
+          (file_metadata && file_metadata.length > 0 || hazo_files_available || doc_data || highlight_fields_info || extractions && extractions.length > 0) && toolbar_config.toolbar_show_file_info_button && /* @__PURE__ */ jsx15("div", { className: "cls_pdf_viewer_toolbar_group", children: /* @__PURE__ */ jsx15(
             "button",
             {
               type: "button",
@@ -5914,27 +5990,57 @@ ${suffix_line}`;
               children: /* @__PURE__ */ jsx15(Info, { className: "cls_pdf_viewer_toolbar_icon", size: 16 })
             }
           ) }),
-          is_multi_file_mode && enable_popout && /* @__PURE__ */ jsx15("div", { className: "cls_pdf_viewer_toolbar_group", children: /* @__PURE__ */ jsx15(
-            "button",
-            {
-              type: "button",
-              onClick: handle_popout,
-              className: "cls_pdf_viewer_toolbar_button",
-              "aria-label": "Open in new tab",
-              title: "Open in new tab",
-              style: {
-                backgroundColor: toolbar_config.toolbar_button_background_color,
-                color: toolbar_config.toolbar_button_text_color
-              },
-              onMouseEnter: (e) => {
-                e.currentTarget.style.backgroundColor = toolbar_config.toolbar_button_background_color_hover;
-              },
-              onMouseLeave: (e) => {
-                e.currentTarget.style.backgroundColor = toolbar_config.toolbar_button_background_color;
-              },
-              children: /* @__PURE__ */ jsx15(ExternalLink, { className: "cls_pdf_viewer_toolbar_icon", size: 16 })
-            }
-          ) }),
+          enable_popout && /* @__PURE__ */ jsxs14("div", { className: "cls_pdf_viewer_toolbar_group", children: [
+            /* @__PURE__ */ jsx15(
+              "button",
+              {
+                type: "button",
+                onClick: handle_popout,
+                className: "cls_pdf_viewer_toolbar_button",
+                "aria-label": "Open in new tab",
+                title: "Open in new tab",
+                style: {
+                  backgroundColor: toolbar_config.toolbar_button_background_color,
+                  color: toolbar_config.toolbar_button_text_color
+                },
+                onMouseEnter: (e) => {
+                  e.currentTarget.style.backgroundColor = toolbar_config.toolbar_button_background_color_hover;
+                },
+                onMouseLeave: (e) => {
+                  e.currentTarget.style.backgroundColor = toolbar_config.toolbar_button_background_color;
+                },
+                children: /* @__PURE__ */ jsx15(ExternalLink, { className: "cls_pdf_viewer_toolbar_icon", size: 16 })
+              }
+            ),
+            /* @__PURE__ */ jsx15(
+              "button",
+              {
+                type: "button",
+                onClick: handle_download,
+                disabled: downloading || !pdf_document,
+                className: cn(
+                  "cls_pdf_viewer_toolbar_button",
+                  (downloading || !pdf_document) && "cls_pdf_viewer_toolbar_button_disabled"
+                ),
+                "aria-label": "Download PDF",
+                title: downloading ? "Downloading..." : "Download PDF",
+                style: {
+                  backgroundColor: toolbar_config.toolbar_button_background_color,
+                  color: toolbar_config.toolbar_button_text_color,
+                  opacity: downloading || !pdf_document ? toolbar_config.toolbar_button_disabled_opacity : 1
+                },
+                onMouseEnter: (e) => {
+                  if (!(downloading || !pdf_document)) {
+                    e.currentTarget.style.backgroundColor = toolbar_config.toolbar_button_background_color_hover;
+                  }
+                },
+                onMouseLeave: (e) => {
+                  e.currentTarget.style.backgroundColor = toolbar_config.toolbar_button_background_color;
+                },
+                children: /* @__PURE__ */ jsx15(Download, { className: "cls_pdf_viewer_toolbar_icon", size: 16 })
+              }
+            )
+          ] }),
           on_close && /* @__PURE__ */ jsx15("div", { className: "cls_pdf_viewer_toolbar_group", children: /* @__PURE__ */ jsx15(
             "button",
             {
@@ -5962,7 +6068,7 @@ ${suffix_line}`;
       const any_sidepanel_open = sidepanel_open || file_info_sidepanel_open;
       const total_sidepanel_width = (sidepanel_open ? sidepanel_width : 0) + (file_info_sidepanel_open ? file_info_sidepanel_width : 0);
       const has_metadata_sidepanel = sidepanel_metadata_enabled && metadata_input;
-      const has_file_info_sidepanel = (file_metadata && file_metadata.length > 0 || hazo_files_available || doc_data || highlight_fields_info) && toolbar_config.toolbar_show_file_info_button;
+      const has_file_info_sidepanel = (file_metadata && file_metadata.length > 0 || hazo_files_available || doc_data || highlight_fields_info || extractions && extractions.length > 0) && toolbar_config.toolbar_show_file_info_button;
       const any_sidepanel_available = has_metadata_sidepanel || has_file_info_sidepanel;
       return /* @__PURE__ */ jsxs14("div", { className: cn("cls_pdf_viewer_content_wrapper", any_sidepanel_open && "cls_pdf_viewer_content_wrapper_with_sidepanel"), children: [
         any_sidepanel_available && !any_sidepanel_open && /* @__PURE__ */ jsxs14(
@@ -6061,7 +6167,7 @@ ${suffix_line}`;
             on_width_change: handle_sidepanel_width_change
           }
         ),
-        (file_metadata && file_metadata.length > 0 || hazo_files_available || doc_data || highlight_fields_info) && /* @__PURE__ */ jsx15(
+        (file_metadata && file_metadata.length > 0 || hazo_files_available || doc_data || highlight_fields_info || extractions && extractions.length > 0) && /* @__PURE__ */ jsx15(
           FileInfoSidepanel,
           {
             is_open: file_info_sidepanel_open,
@@ -6083,7 +6189,8 @@ ${suffix_line}`;
             file_metadata,
             current_filename: current_file?.name || display_filename || (url ? url.split("/").pop() || "" : ""),
             doc_data,
-            highlight_fields_info
+            highlight_fields_info,
+            extractions
           }
         )
       ] });
@@ -6258,6 +6365,7 @@ PdfViewer.displayName = "PdfViewer";
 var pdf_viewer_default = PdfViewer;
 
 export {
+  cn,
   load_pdf_document,
   create_coordinate_mapper,
   get_viewport_dimensions,
@@ -6293,4 +6401,4 @@ export {
   PdfViewer,
   pdf_viewer_default
 };
-//# sourceMappingURL=chunk-LQTYLVBH.js.map
+//# sourceMappingURL=chunk-4JJOUQ62.js.map