@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/providers/FileSystemMediaProvider.d.ts

@@ -0,0 +1,403 @@
+/**
+ * FileSystemMediaProvider - Filesystem-based implementation of BaseMediaProvider
+ *
+ * Scans configured directories for media files, extracts EXIF/IPTC/XMP metadata
+ * via exiftool-vendored, generates thumbnails via Sharp, and maintains a
+ * persistent JSON index.
+ *
+ * Dependencies:
+ * - exiftool-vendored — EXIF/IPTC/XMP metadata extraction
+ * - sharp — thumbnail generation (already installed)
+ * - fs-extra — filesystem helpers
+ *
+ * @module FileSystemMediaProvider
+ */
+import { type MediaPathExplanation, type MediaSkipReport } from '../utils/explainMediaPath.js';
+import BaseMediaProvider, { MediaItem, ScanResult } from './BaseMediaProvider.js';
+import type { AssetMetadataPatch } from '../types/Asset.js';
+/**
+ * Configuration for FileSystemMediaProvider.
+ */
+export interface FileSystemMediaProviderConfig {
+    /** Absolute paths to the root media folders to scan */
+    folders: string[];
+    /** Directory names to skip during scan (e.g. [".dtrash", ".ts"]) */
+    ignoreDirs: string[];
+    /** Maximum directory depth to recurse into (0 = unlimited) */
+    maxDepth: number;
+    /** Absolute path to the media-index.json file */
+    indexFile: string;
+    /** Absolute path to the thumbnail cache directory */
+    thumbnailDir: string;
+    /** Comma-separated thumbnail size specs (e.g. "300x300,150x150") */
+    thumbnailSizes: string;
+    /** Metadata extraction priority order (e.g. ["EXIF", "IPTC", "XMP"]) */
+    metadataPriority: string[];
+    /** Whether the provider may write to source media folders (always false) */
+    readonly: boolean;
+    /** Set of file extensions (lowercase, no dot) to index */
+    extensions: Set<string>;
+}
+/** Default supported media file extensions — used when no config override is provided */
+export declare const DEFAULT_MEDIA_EXTENSIONS: string[];
+/**
+ * Filesystem-based media provider.
+ *
+ * Scans configured folders, extracts metadata with ExifTool, and maintains a
+ * persistent JSON index. Thumbnails are generated on demand via Sharp and cached
+ * to thumbnailDir.
+ */
+declare class FileSystemMediaProvider extends BaseMediaProvider {
+    readonly id = "media-library";
+    readonly displayName = "Media Library";
+    readonly capabilities: import('../types/Asset.js').ProviderCapability[];
+    private readonly config;
+    /** In-memory index: id → MediaIndexEntry */
+    private index;
+    /** Single ExifTool worker process reused across all reads */
+    private readonly exiftoolInstance;
+    constructor(config: FileSystemMediaProviderConfig);
+    /**
+     * Load the persisted index from disk so queries work immediately
+     * (before the first background scan).
+     */
+    initialize(): Promise<void>;
+    /**
+     * Release the ExifTool worker process.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Verify that at least one configured media folder is accessible.
+     *
+     * Returns false when every configured folder is unreachable — e.g. a NAS or
+     * SLOW_STORAGE volume that has been unmounted or an SMB share that has dropped.
+     * A partial failure (some folders gone, others present) still returns true so
+     * the provider continues serving what it can; the warning log indicates which
+     * folders are missing.
+     */
+    healthCheck(): Promise<boolean>;
+    /**
+     * The configured folders this process cannot read (#1167): missing, unmounted
+     * or without read permission. Read-only — it never touches the files.
+     */
+    unreachableFolders(): Promise<string[]>;
+    /**
+     * Rebuild the media index from scratch.
+     *
+     * Clears the in-memory index and deletes the persisted index file, then
+     * runs a forced full scan so the result reflects only files currently on disk.
+     *
+     * @param onProgress - Optional callback invoked periodically with (processed, total).
+     */
+    rebuild(onProgress?: (processed: number, total: number) => void): Promise<ScanResult>;
+    /**
+     * Scan all configured folders, extract metadata for new/changed files,
+     * save the updated index, and return a summary.
+     *
+     * Phase 1: recursively collect all matching file paths (fast, no ExifTool).
+     * Phase 2: process files concurrently in batches of BATCH_SIZE, calling
+     *          ExifTool for each file that needs metadata extraction.
+     *
+     * @param force      - Re-process every file even if mtime is unchanged.
+     * @param onProgress - Optional callback invoked after each batch with (processed, total).
+     */
+    scan(force?: boolean, onProgress?: (processed: number, total: number) => void): Promise<ScanResult>;
+    /**
+     * Remove index entries whose file path is not among the primaries found in
+     * this scan, restricted to folders that were fully walked (#867).
+     *
+     * @param presentPaths    - All primary file paths collected in this scan.
+     * @param prunableFolders - Folders that exist and were walked without read errors.
+     * @param counters        - Scan counters; `removed` is incremented per pruned entry.
+     */
+    private pruneStaleEntries;
+    /**
+     * Return the list of years that have at least one item, sorted descending.
+     */
+    getYears(): Promise<number[]>;
+    /**
+     * Every item with a year, in one pass over the index (#1741).
+     */
+    getItemCount(): Promise<number>;
+    /**
+     * Retrieve a single item by id.
+     */
+    getItem(id: string): Promise<MediaItem | null>;
+    /**
+     * Return all items for a given year, sorted by filename.
+     */
+    getItemsByYear(year: number): Promise<MediaItem[]>;
+    /**
+     * Return all items whose capture timestamp falls in [after, before],
+     * sorted ascending by capture date (#864 — Dawarich date-window queries).
+     * Bounds are ISO-ish strings compared against `metadata.dateTimeOriginal`
+     * ("YYYY-MM-DD HH:MM:SS"); either bound may be omitted. Items without a
+     * capture date are never returned.
+     */
+    getItemsByDateRange(after?: string, before?: string): Promise<MediaItem[]>;
+    /**
+     * Retrieve all items whose EXIF/XMP keywords include the page name — the
+     * only association between a media item and a page (#1427).
+     */
+    getItemsByPage(pageName: string): Promise<MediaItem[]>;
+    getItemsByKeyword(keyword: string): Promise<MediaItem[]>;
+    /**
+     * #895: distinct keywords across the media index with item counts. O(n)
+     * over the in-memory index; scalar keyword values count as one-element
+     * arrays (#545 shape tolerance).
+     */
+    getAllKeywordCounts(): Promise<Record<string, number>>;
+    /**
+     * #917: library-wide leaf→path map built from every item's hierarchical
+     * `keywordPaths`. Keys and values are canonical-value forms; a leaf with no
+     * genuine hierarchy (only a root-level occurrence) is omitted. #918 uses this
+     * to place a newly-added keyword at its known hierarchical home.
+     */
+    getKeywordLeafPaths(): Promise<Record<string, string>>;
+    /**
+     * Find the first item whose filename (basename) exactly matches.
+     *
+     * Iterates the in-memory index; O(n) but the index is small enough that
+     * this is acceptable for the ad-hoc `media://` URI resolution path.
+     *
+     * @param filename - Basename to match exactly (e.g. "IMG_1234.jpg").
+     */
+    findByFilename(filename: string): Promise<MediaItem | null>;
+    /**
+     * Full-text keyword search across filename, year, title,
+     * description, and keywords fields.
+     *
+     * All query tokens must match (AND semantics).
+     */
+    searchItems(query: string): Promise<MediaItem[]>;
+    /**
+     * Write a metadata patch into the source file (and its alternate-format
+     * siblings, so e.g. a HEIC+JPG pair stays in sync), then refresh the index
+     * entry by re-reading the file — the index always reflects what is actually
+     * on disk, not what we intended to write.
+     *
+     * ExifTool's default backup behaviour is kept deliberately: the first write
+     * to a file leaves a `<name>_original` sibling. Those extensions are not in
+     * the indexable set, so scans ignore them.
+     *
+     * The re-extract records the file's new mtime, so the next scheduled scan
+     * sees an unchanged file and skips it (no churn). `alternates` is
+     * re-attached afterwards because processFile builds entries without it.
+     */
+    updateItemMetadata(id: string, patch: AssetMetadataPatch): Promise<MediaItem | null>;
+    /**
+     * Return a thumbnail buffer (webp) for the given item and size.
+     *
+     * Thumbnails are cached on disk in config.thumbnailDir. Image items run
+     * through Sharp directly. Video items (#722 Slice 1) have a poster frame
+     * extracted via ffmpeg-static at the 1-second mark, then fed through the
+     * same Sharp pipeline so the on-disk cache layout and `/media/thumb/:id`
+     * endpoint are unchanged. Other item types (audio, docs) return null and
+     * fall back to the generic icon in the asset-picker / media library.
+     *
+     * @param id   - Item identifier.
+     * @param size - Size string in the form "WxH" (e.g. "300x300").
+     */
+    getThumbnailBuffer(id: string, size: string): Promise<Buffer | null>;
+    /**
+     * Group files by directory+stem and keep only the highest-priority format per group.
+     * Alternate paths are returned separately so they can be stored on the primary entry.
+     */
+    private deduplicateFormats;
+    /**
+     * Recursively collect all matching media file paths under dirPath.
+     *
+     * Applies ignoreDirs, maxDepth, extension filter, and .ngdpbaseignore patterns.
+     * Does NOT call ExifTool — that happens in Phase 2 (processFile).
+     */
+    private collectFilePaths;
+    /**
+     * Read and parse `.ngdpbaseignore` from the given directory if it exists.
+     * Returns an array of pattern strings (blank lines and `#` comments stripped).
+     */
+    private loadIgnorePatterns;
+    /**
+     * Test a filename against a list of .ngdpbaseignore patterns.
+     * Patterns ending with `/` are directory-only; all others match both files and dirs.
+     */
+    private matchesIgnorePattern;
+    /**
+     * Process a single media file: stat, EXIF read, index update.
+     */
+    private processFile;
+    /**
+     * Explain why one absolute path is, or is not, in the media index (#848).
+     *
+     * #814 reported media "often not discovered" and triage found zero indexing
+     * bugs — every missing file was correctly skipped by a rule that leaves no
+     * visible trace. This answers the question for a single path.
+     *
+     * The rule ORDER lives in `explainMediaPath`, deliberately: the scanner
+     * decides the same things inline as `continue` statements, which is fine for
+     * scanning and useless for explaining. Keeping the classifier pure also lets
+     * a future skipped-file report (#1056) reuse it instead of adding a third
+     * copy of rules that already exist in two places.
+     *
+     * Facts are gathered in two passes so the expensive ones are not paid for a
+     * file that is already explained: index lookups are cheap, reading
+     * `.ngdpbaseignore` files and EXIF is not. Only a path that survives every
+     * cheap rule triggers the second pass.
+     */
+    explainPath(target: string): Promise<MediaPathExplanation>;
+    /**
+     * First `.ngdpbaseignore` pattern matching the file or any directory between
+     * it and its scan root, or undefined.
+     *
+     * Walks root-downward because that is the order the scanner encounters the
+     * ignore files, so the pattern reported is the one that actually stopped it.
+     */
+    private findIgnorePatternMatch;
+    /** Whether the file carries the `ngdpbaseignore` EXIF/XMP keyword. */
+    private hasIgnoreKeyword;
+    /**
+     * Generate a stable 32-character hex ID from the file path.
+     */
+    private generateId;
+    /**
+     * Ordered capture-date field names checked for both year extraction and
+     * full-timestamp extraction. Order matches ExifTool's own precedence:
+     * `DateTimeOriginal` is the photographer's intent (image EXIF), the
+     * `*CreateDate` variants are the file/container creation timestamps that
+     * video formats use (issue #750: QuickTime:CreationDate flattens to
+     * `CreationDate` in exiftool-vendored's Tags shape).
+     */
+    private static readonly CAPTURE_DATE_FIELDS;
+    /**
+     * Extract the formatted capture-date timestamp ("YYYY-MM-DD HH:MM:SS") from
+     * EXIF/QuickTime tags, falling back through `DateTimeOriginal` →
+     * `CreateDate` → `MediaCreateDate` → `CreationDate`.
+     *
+     * The first three already covered images; `CreationDate` is the
+     * QuickTime/Apple variant that video containers populate when the camera
+     * didn't write `DateTimeOriginal` (#750). Without this fallback, videos
+     * indexed `dateTimeOriginal: null` and silently dropped out of any
+     * capture-date sort/filter — only the year facet worked (via `extractYear`).
+     *
+     * Also reports whether the source tag was a **partial** date — the year was
+     * present but the month and/or day were missing and got defaulted to `01`
+     * (#808). A partial date is still stored (defaulted to Jan 1, which preserves
+     * the year facet and gives a usable sort key), but the caller surfaces it to
+     * admins at WARN level — distinct from a file with no capture date at all
+     * (ERROR). A missing **time** component (HH:MM:SS) does NOT count as partial:
+     * defaulting to `00:00:00` is harmless for day-granularity sorting.
+     *
+     * Returns `null` when no field provides a usable `.year`.
+     */
+    private extractCaptureDate;
+    /**
+     * Ordered duration-tag fallback chain. Walked by `extractDuration()` until
+     * one yields a strictly positive value. Order is most-reliable-first.
+     *
+     * Why each field is in the chain:
+     *   - `Duration` — container-level top tag, present in QuickTime/MP4/MOV,
+     *     MKV, AVI, WAV, AIFF, FLAC, MPEG. Single value per file.
+     *   - `TrackDuration` — per-track fallback when the container doesn't
+     *     expose its own. exiftool-vendored flattens N tracks into one tag,
+     *     keeping the last non-empty value seen.
+     *   - `MediaDuration` — same per-track shape as TrackDuration, but often
+     *     zero on Pixel/Android `.TS.mp4` files where track-N is metadata-only
+     *     (this is the bug that motivated the chain — exiftool reported
+     *     `Duration: 15.87 s` but `MediaDuration: 0 s` for the same file).
+     *   - `AudioDuration` — audio-only fallback (rarely useful alone, but
+     *     present in some streaming formats).
+     *   - `GoogleTrackDuration` — Pixel-specific QuickTime extension.
+     *   - `StreamDuration` — streaming containers (HLS chunks, etc.).
+     *   - `TotalDuration` — MPEG-1/MPEG-2 alternative top-level tag.
+     *
+     * Excluded as not-a-playback-duration: `PreviewDuration`, `SelectionDuration`,
+     * `BulbDuration`, `ContrastFlowDuration`, `SampleDuration`, `BlockDuration`,
+     * `ClusterDuration`, `DefaultDuration`, `SlowMotionRegions*Duration*`, and
+     * all DICOM `*Duration` variants. Those are either codec-internal sub-sample
+     * markers or non-media (medical imaging, slow-mo region metadata, edit
+     * selection state).
+     */
+    private static readonly DURATION_FIELDS;
+    /**
+     * Extract playback duration from ExifTool's duration tags and normalise to
+     * ISO 8601 duration format (e.g. "PT1M30S").
+     *
+     * Walks `DURATION_FIELDS` and accepts the first tag that yields a strictly
+     * positive number of seconds. Zero values are skipped — Pixel `.TS.mp4`
+     * files set `MediaDuration: 0 s` while `Duration: 15.87 s` is the real
+     * length, and prior versions of this method picked up the zero via
+     * `??` short-circuit (#758 follow-up).
+     *
+     * Accepted raw shapes per candidate field:
+     *   - number of seconds (most common for QuickTime / MP4)
+     *   - string like "0:01:30" / "00:01:30" / "30" (HH:MM:SS / MM:SS / SS)
+     *   - already-ISO string like "PT1M30S"
+     *   - exiftool-vendored Duration object (`.seconds` property)
+     *
+     * Returns null when no candidate field yields a positive duration.
+     */
+    private extractDuration;
+    /**
+     * Extract average bitrate (bits/second) from ExifTool AvgBitrate tag.
+     *
+     * exiftool-vendored returns AvgBitrate as either:
+     *   - a number (raw bits/second)
+     *   - a string like "5.00 Mbps" or "192 kbps" — parse the magnitude + unit
+     *
+     * Returns null when no usable bitrate is present.
+     */
+    private extractBitrate;
+    /**
+     * Extract the four-digit year from tags, filename, path, or mtime.
+     *
+     * Priority:
+     * 1. EXIF/QuickTime date fields (DateTimeOriginal / CreateDate /
+     *    MediaCreateDate / CreationDate — see CAPTURE_DATE_FIELDS)
+     * 2. Filename prefix YYYY- or YYYY_
+     * 3. Directory path component matching /^\d{4}$/
+     * 4. File mtime year
+     */
+    private extractYear;
+    /**
+     * Load the persisted index from disk into memory.
+     */
+    private loadIndex;
+    /**
+     * Tally every skip before the list is capped (#1056).
+     *
+     * Runs on the full list, never the truncated one — that ordering is the
+     * whole point. On the reference library the cap drops 93% of the entries,
+     * so counts derived after capping would understate `extension` by 13,714.
+     */
+    private tallySkips;
+    /**
+     * Path of the skip report, beside the index file (#1056).
+     *
+     * Null when no `indexFile` is configured — an in-memory-only provider has
+     * nowhere to keep it, and the report must not silently outlive the index it
+     * describes.
+     */
+    private get skipReportFile();
+    /**
+     * Persist the skip report for the scan that just finished (#1056).
+     *
+     * On disk rather than in memory because the question it answers — "where did
+     * my file go?" — is usually asked long after the scan, and often after a
+     * restart. An in-memory report reads as "no files were skipped" to anyone who
+     * did not personally trigger the last scan.
+     *
+     * Overwrites: it describes the CURRENT state of the library, so accumulating
+     * history would mean showing an operator files that a config change already
+     * un-skipped.
+     */
+    private saveSkipReport;
+    /**
+     * The skip report from the most recent scan, or null if none has been
+     * written (fresh install, or no `indexFile` configured).
+     */
+    getSkipReport(): Promise<MediaSkipReport | null>;
+    /**
+     * Save the in-memory index to disk.
+     */
+    private saveIndex;
+}
+export default FileSystemMediaProvider;

package/lib/src/providers/LunrSearchProvider.d.ts

@@ -0,0 +1,280 @@
+/**
+ * LunrSearchProvider - Full-text search provider using Lunr.js
+ *
+ * Provides client-side full-text search with stemming, stopwords, and field boosting.
+ * Suitable for small to medium-sized wikis (<10,000 pages).
+ *
+ * Configuration keys (all lowercase):
+ * - ngdpbase.search.provider.lunr.indexdir - Directory for persisted index
+ * - ngdpbase.search.provider.lunr.stemming - Enable/disable stemming
+ * - ngdpbase.search.provider.lunr.boost.title - Title field boost factor
+ * - ngdpbase.search.provider.lunr.boost.systemcategory - System category boost
+ * - ngdpbase.search.provider.lunr.boost.userkeywords - User keywords boost
+ * - ngdpbase.search.provider.lunr.boost.tags - Tags boost
+ * - ngdpbase.search.provider.lunr.maxresults - Maximum results to return
+ * - ngdpbase.search.provider.lunr.snippetlength - Snippet length in characters
+ * - ngdpbase.search.provider.lunr.flushinterval - Document persistence flush interval (ms)
+ *
+ * Related: GitHub Issue #102 - Configuration reorganization
+ * Related: GitHub Issue #267 - Incremental search index + document persistence
+ */
+import BaseSearchProvider, { SearchResult, SearchOptions, SearchCriteria, SearchStatistics, BackupData, WikiEngine } from './BaseSearchProvider.js';
+/**
+ * Document structure for indexing
+ */
+/**
+ * Widen the last term of a query to a prefix match (#884).
+ *
+ * Lunr's `*` wildcard, applied only to the final term: someone mid-word wants
+ * completions, someone who submitted a finished query does not. Earlier terms
+ * are words the user has already finished typing and stay exact.
+ *
+ * Left alone when the last term already carries Lunr syntax — a wildcard, a
+ * field scope (`title:x`), or a presence operator (`+`/`-`). Appending `*` to
+ * those either duplicates an existing wildcard or corrupts the operator, and
+ * silently mangling a query the caller wrote deliberately is worse than not
+ * helping.
+ *
+ * @param query - Raw user query
+ * @returns The query with its last term widened, or unchanged
+ */
+export declare function applyPrefixToLastTerm(query: string): string;
+/**
+ * Split URLs found in page content into searchable word tokens (#884).
+ *
+ * A URL indexed as one opaque string only ever matches if the reader types it
+ * in full. Splitting on the separators that carry no meaning — `[/:._\-?&=#]`
+ * — turns `https://en.wikipedia.org/wiki/Volcano` into `en wikipedia org wiki
+ * volcano`, so the domain and the path words each become findable terms.
+ *
+ * Deliberately conservative about what counts as a URL: only `http(s)://`
+ * matches. Bare domains would drag in ordinary prose containing dots, and
+ * abbreviations like "e.g." would tokenise into noise.
+ *
+ * Numeric-only and single-character fragments are dropped — port numbers, path
+ * ids and `v2`-style noise add index weight without ever being searched for.
+ *
+ * @param content - Page body
+ * @returns Space-joined tokens, or '' when the page links nowhere
+ */
+export declare function tokenizeUrls(content: string): string;
+/**
+ * LunrSearchProvider - Full-text search using Lunr.js
+ */
+declare class LunrSearchProvider extends BaseSearchProvider {
+    private searchIndex;
+    private persistTimer;
+    private documents;
+    private config;
+    private flushInterval;
+    private documentsPath;
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the Lunr search provider
+     * Loads configuration from ConfigurationManager
+     * @returns {Promise<void>}
+     */
+    initialize(): Promise<void>;
+    /**
+     * Load persisted documents from disk
+     */
+    private loadPersistedDocuments;
+    /**
+     * Is this document a private page's (#1458)? Either its name is a private
+     * path (#1456) or the document itself says so — a document written before
+     * private pages left the shared indexes has the flag and an ordinary title.
+     */
+    private static isPrivateDocument;
+    /**
+     * The documents that may be written to a shared place — `documents.json`
+     * and the backup that carries it off this host (#1458).
+     *
+     * Private page text sat in both in plaintext before #1456. This is the one
+     * rule that keeps it out, whatever put it in the map: a private page's text
+     * lives in its own store's search index and nowhere else.
+     */
+    private sharedDocuments;
+    /**
+     * Persist documents to disk — the shared ones only (#1458).
+     */
+    private persistDocuments;
+    /**
+     * A term as both the index and a query read it: lower-cased, stop words
+     * dropped, and stemmed with Lunr's English stemmer when stemming is on, so a
+     * word matches what it matched under Lunr (#1736).
+     */
+    private processTerm;
+    /**
+     * Build the index from the in-memory documents: at start-up and after a
+     * restore. A save changes one document (`updatePageInIndex`), never this.
+     */
+    private rebuildSearchIndexFromDocuments;
+    /** The configured field boosts, for every search. Content is the 1.0 baseline. */
+    private fieldBoosts;
+    /**
+     * Write `documents.json` shortly after the last change rather than on every
+     * save (#1736). The interval flush and `close()` still write it.
+     */
+    private schedulePersist;
+    /**
+     * Convert page data from WikiRoutes into a LunrDocument
+     */
+    private buildDocumentFromPageData;
+    /**
+     * Get provider information
+     * @returns {Object} Provider metadata
+     */
+    getProviderInfo(): {
+        name: string;
+        version: string;
+        description: string;
+        features: string[];
+    };
+    /**
+     * Build search index from all pages
+     * @returns {Promise<void>}
+     */
+    buildIndex(): Promise<void>;
+    /**
+     * Search for pages matching the query
+     * @param {string} query - Search query
+     * @param {SearchOptions} options - Search options
+     * @returns {Promise<SearchResult[]>} Search results
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Private-page visibility (#731/#716, #1382). Used by both the text path in
+     * search() and the no-text advancedSearch branch. A private page lives in its
+     * owner's private container: it is found only by its owner — no role, and no
+     * frontmatter audience, reaches in (docs/private-stores.md, Access;
+     * the same rule PolicyInformationPoint applies at Tier 0).
+     */
+    private isDocVisible;
+    /**
+     * Advanced search with multiple criteria
+     * @param {SearchCriteria} options - Search criteria
+     * @returns {Promise<SearchResult[]>} Search results
+     */
+    advancedSearch(options?: SearchCriteria): Promise<SearchResult[]>;
+    /**
+     * Generate a snippet with highlighted search terms
+     * @param {string} content - Full content
+     * @param {string} query - Search query
+     * @returns {string} Content snippet
+     */
+    private generateSnippet;
+    /**
+     * Get search suggestions for autocomplete
+     * @param {string} partial - Partial search term
+     * @returns {Promise<string[]>} Suggested completions
+     */
+    getSuggestions(partial: string): Promise<string[]>;
+    /**
+     * Suggest similar pages based on content
+     * @param {string} pageName - Source page name
+     * @param {number} limit - Maximum suggestions
+     * @returns {Promise<SearchResult[]>} Suggested pages
+     */
+    suggestSimilarPages(pageName: string, limit?: number): Promise<SearchResult[]>;
+    /**
+     * Add or update a page in the search index incrementally
+     * @param {string} pageName - Page name
+     * @param {Record<string, unknown>} pageData - Page data
+     * @returns {Promise<void>}
+     */
+    updatePageInIndex(pageName: string, pageData: Record<string, unknown>): Promise<void>;
+    /**
+     * Remove a page from the search index
+     * @param {string} pageName - Page name to remove
+     * @returns {Promise<void>}
+     */
+    removePageFromIndex(pageName: string): Promise<void>;
+    /**
+     * True rebuild from disk — mirrors MediaManager.rebuildIndex().
+     *
+     * #724: buildIndex() has a fast path that, when this.documents is
+     * non-empty (always, in steady state), rebuilds Lunr from the persisted
+     * map WITHOUT re-reading pages from disk. That makes a deleted page's
+     * index entry ("ghost") unkillable — a normal reindex can never drop it.
+     * rebuild() is the missing "Rebuild" half (vs the "Reindex"/rescan that
+     * buildIndex provides): it clears the in-memory map AND deletes the
+     * persisted documents.json, then forces the cold disk-scan path. Pages
+     * that no longer exist on disk are dropped by construction.
+     *
+     * documents.json is a derived cache (regenerated here from PageManager),
+     * never source data — deleting it is safe and not the data/-tree rule.
+     */
+    rebuild(): Promise<void>;
+    /**
+     * Get all unique categories from indexed documents
+     * @returns {Promise<string[]>} List of categories
+     */
+    getAllCategories(): Promise<string[]>;
+    /**
+     * Split a document's `userKeywords` string back into keywords.
+     *
+     * #862: `buildDocumentFromPageData` joins user-keywords with commas (the
+     * only safe separator — keywords may contain spaces, e.g. "grow system").
+     * Every consumer must split on commas too; the previous whitespace splits
+     * meant a page with more than one keyword NEVER matched
+     * `searchByUserKeywords`, and multi-word keywords shattered into words.
+     */
+    private splitUserKeywords;
+    /**
+     * Get all unique user keywords from indexed documents
+     * @returns {Promise<string[]>} List of user keywords
+     */
+    getAllUserKeywords(): Promise<string[]>;
+    /**
+     * #893: all unique system keywords (machine bucket) from indexed documents.
+     * Mirrors getAllUserKeywords — same comma-join contract (#862). Previously
+     * ES-only; needed on Lunr so the asset-picker system-keywords facet includes
+     * index-derived terms like 'capture'.
+     */
+    getAllSystemKeywords(): Promise<string[]>;
+    /**
+     * Search by category only
+     * @param {string} category - Category to search for
+     * @returns {Promise<SearchResult[]>} Pages in category
+     */
+    getAllDocuments(): Promise<SearchResult[]>;
+    searchByCategory(category: string): Promise<SearchResult[]>;
+    /**
+     * Search by user keywords only
+     * @param {string} keyword - Keyword to search for
+     * @returns {Promise<SearchResult[]>} Pages with keyword
+     */
+    searchByUserKeywords(keyword: string): Promise<SearchResult[]>;
+    /**
+     * Get search statistics
+     * @returns {Promise<SearchStatistics>} Search statistics
+     */
+    getStatistics(): Promise<SearchStatistics>;
+    /**
+     * Get the total number of indexed documents
+     * @returns {Promise<number>} Number of documents
+     */
+    getDocumentCount(): Promise<number>;
+    /**
+     * Check if the search provider is healthy/functional
+     * @returns {Promise<boolean>} True if healthy
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Close/cleanup the search provider, flushing documents to disk
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+    /**
+     * Backup search index and configuration
+     * @returns {Promise<BackupData>} Backup data
+     */
+    backup(): Promise<BackupData>;
+    /**
+     * Restore search index from backup
+     * @param {BackupData} backupData - Backup data
+     * @returns {Promise<void>}
+     */
+    restore(backupData: BackupData): Promise<void>;
+}
+export default LunrSearchProvider;