bible-note 0.4.4 → 0.5.0

package/knowledge/development.md

@@ -0,0 +1,1927 @@
+# BibleNote — development guide
+
+> Generated by `npm run pack` for **bible-note@0.5.0** from the hand-written topics in `knowledge/development/` and the package's own type declarations. Do not edit this file — edit the sources and re-run the pack. End-user help for the editor UI lives in `ui-rag.md` next to it.
+
+## Contents
+
+1. [Overview](#dev-overview) — What the package is, what it bundles, and what the host supplies.
+2. [Installation and stylesheets](#dev-installation-and-stylesheets) — Peer dependencies and the stylesheet order the editor needs.
+3. [Quick start](#dev-quick-start) — A complete minimal host, plus the optional hooks.
+4. [Datasets and lookup managers](#dev-datasets-and-lookup-managers) — Feeding name and location data, translated datasets, per-dataset styling, building your own lookup UI.
+5. [Persistence and storage](#dev-persistence-and-storage) — Where the note and the editor's own state are stored, and when.
+6. [Host integration](#dev-host-integration) — Fonts, media files, Excalidraw libraries, the settings panel, footer modes and the Electron file bridge.
+7. [Working on the editor UI](#dev-working-on-the-editor-ui) — For contributors — repository layout, the plugin tree, the dev loop, verifying changes in the browser.
+8. [Building and releasing the package](#dev-building-and-releasing-the-package) — What npm run pack does, the hand-maintained files, versioning and publishing.
+9. [API reference](#dev-api-reference) — Every export of the package, generated from its type declarations.
+
+<a id="dev-overview"></a>
+
+## Overview
+
+`bible-note` is a Bible-study note editor packaged as a drop-in component. It
+extends the [Lexical playground](https://playground.lexical.dev/) editor with
+Bible-specific features:
+
+- person (`@`) and place (`#`) mentions backed by the host's datasets, with
+  hover cards and a draggable advanced panel;
+- Bible verse mentions created by pasting verse text after `^`;
+- a lookup panel for browsing both datasets;
+- sticky notes, comments, Excalidraw drawings, equations, tables, column
+  layouts, collapsibles, media and embeds;
+- a footer with Word (`.docx`) import and export, a lossless JSON backup, print
+  with page-size preview, read-only mode, and buttons the host adds itself.
+
+The MIT license and Meta's copyright carry over from upstream Lexical.
+
+### The pieces
+
+| Piece                                          | What it is                                                                                                                                    |
+| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BibleNote`                                    | The editor. `new BibleNote(props)` then `render(element)`. It mounts its own React root, so the host does not have to be a React app.         |
+| `NamesLookupManager`, `LocationsLookupManager` | The datasets behind every mention, hover card, panel and the lookup panel. They have no editor dependency — a host can use them on their own. |
+| `BibleNoteSettings`                            | The optional settings panel (gear button), passed to `render`.                                                                                |
+| `bible-note/styles.css`                        | The one stylesheet: editor, KaTeX and Excalidraw rules.                                                                                       |
+| `bible-note/knowledge/development.md`          | This guide.                                                                                                                                   |
+| `bible-note/knowledge/ui-rag.md`               | End-user help for the editor UI, chunked for a retrieval pipeline.                                                                            |
+
+### Bundled vs. supplied by the host
+
+React, React DOM, Bootstrap and bootstrap-icons are **peer dependencies**:
+
+- React must be the host's copy so there is a single instance — a second copy
+  breaks hooks.
+- Bootstrap and bootstrap-icons are global stylesheets. Shipping them inside the
+  package would fix their place in the host's cascade and pin a version the host
+  could not theme, so the host installs and imports them itself.
+
+Everything else — Lexical, Excalidraw, KaTeX, Shiki, the Word converters — is
+bundled. Lexical and Excalidraw are bundled on purpose: the editor is coupled to
+their module instances, and a separately resolved copy could be a different
+instance than the one the bundle talks to. `use-sync-external-store` is the one
+runtime dependency, left external only so the consumer's bundler converts it
+correctly.
+
+The package ships **no datasets**. The host fetches the name and location maps
+(and, optionally, verse text) and hands them to the editor.
+
+### Lifecycle in one paragraph
+
+Construct `BibleNote` with the datasets, the storage callbacks and any optional
+host hooks; call `render(container)`. Before the first render the editor reads
+its own state (settings, comments, read-only mode, zoom) from `storageManager`
+and the note itself from `loadData`. From then on every document change goes to
+`saveData`, and every other state change to `storageManager`. Methods such as
+`content`, `addText` and `searchText` may be called before `render`; writes are
+queued until the editor mounts. `unmount()` tears the React root down; the
+instance can be rendered again.
+
+<a id="dev-installation-and-stylesheets"></a>
+
+## Installation and stylesheets
+
+```bash
+npm install bible-note react react-dom bootstrap bootstrap-icons
+```
+
+The peer ranges are those in the package's `package.json`: React and React DOM
+`^19.2.8`, Bootstrap `^5.3.8`, bootstrap-icons `^1.13.1`.
+
+### Stylesheet order
+
+Import three stylesheets, in this order — Bootstrap first, then the icon font,
+then the editor's own stylesheet last so its overrides win:
+
+```ts
+import 'bootstrap/dist/css/bootstrap.min.css';
+import 'bootstrap-icons/font/bootstrap-icons.css';
+import 'bible-note/styles.css';
+```
+
+Skipping the first two does not throw — it renders a broken editor: the toolbar
+and footer lose their layout, and with no `@font-face` for the icon font every
+`bi bi-*` glyph renders as tofu. `bible-note/styles.css` needs no configuration.
+
+The package's `sideEffects` lists `**/*.css`, so bundlers keep the
+`bible-note/styles.css` import; if a custom build strips CSS side effects, the
+editor renders unstyled.
+
+### Module formats and entry points
+
+| Import                                                                  | Resolves to                                    |
+| ----------------------------------------------------------------------- | ---------------------------------------------- |
+| `import … from 'bible-note'`                                            | ES module bundle, with TypeScript declarations |
+| `require('bible-note')`                                                 | CommonJS bundle                                |
+| `bible-note/styles.css`                                                 | the stylesheet                                 |
+| `bible-note/knowledge/development.md`, `bible-note/knowledge/ui-rag.md` | the knowledge files                            |
+
+Shiki grammars, Excalidraw and KaTeX load lazily as separate chunks, so the
+initial bundle stays small and those parts load the first time they are used.
+
+### Colour scheme
+
+The editor themes itself through classes on `document.body`
+(`playground-theme-light` / `playground-theme-dark`) and Bootstrap's
+`data-bs-theme` attribute. Call `bibleNote.setColorScheme('dark')`, or let the
+settings panel's Dark Mode switch do it. `applyBibleNoteColorScheme` and
+`clearBibleNoteColorScheme` are the bare DOM steps for a host that manages the
+body classes itself.
+
+<a id="dev-quick-start"></a>
+
+## Quick start
+
+A minimal host: the stylesheets, two datasets, browser storage, and a render.
+
+```tsx
+import 'bootstrap/dist/css/bootstrap.min.css';
+import 'bootstrap-icons/font/bootstrap-icons.css';
+import 'bible-note/styles.css';
+
+import {
+  BibleNote,
+  BibleNoteSettings,
+  createBrowserStorageManager,
+  EDITOR_STATE_LOCAL_STORAGE_KEY,
+  LocationsLookupManager,
+  NamesLookupManager,
+} from 'bible-note';
+
+const [namesMap, locationsMap] = await Promise.all([
+  fetch('data/KJV/namesMap.json').then((res) => res.json()),
+  fetch('data/KJV/locationsMap.json').then((res) => res.json()),
+]);
+
+const storageManager = createBrowserStorageManager();
+
+const bibleNote = new BibleNote({
+  namesLookupManager: NamesLookupManager.fromRawDataset({ en: namesMap }, 'en'),
+  locationsLookupManager: LocationsLookupManager.fromRawDataset(
+    { en: locationsMap },
+    'en',
+  ),
+  getLangCode: (text) => (/[ក-៿]/u.test(text) ? 'km' : 'en'),
+  editorExtraFontFamilies: [],
+  stickyNoteExtraFontFamilies: [],
+  storageManager,
+  // The note itself: keep it wherever the host keeps documents.
+  loadData: async () =>
+    (await storageManager.getSetting<string>(EDITOR_STATE_LOCAL_STORAGE_KEY)) ??
+    '',
+  saveData: async (data) => {
+    if (data === '') {
+      await storageManager.deleteSetting(EDITOR_STATE_LOCAL_STORAGE_KEY);
+    } else {
+      await storageManager.setSetting(EDITOR_STATE_LOCAL_STORAGE_KEY, data);
+    }
+  },
+});
+
+bibleNote.render(document.getElementById('root')!, {
+  settings: (
+    <BibleNoteSettings
+      setColorScheme={(mode) => bibleNote.setColorScheme(mode)}
+    />
+  ),
+});
+```
+
+The `settings` option takes a React element, so a `.tsx` file is the natural
+host. A host without JSX can pass
+`React.createElement(BibleNoteSettings, { setColorScheme })` or leave `settings`
+out — the editor then simply has no settings panel.
+
+The required props are the two managers, `getLangCode`,
+`editorExtraFontFamilies`, `stickyNoteExtraFontFamilies`, `storageManager`,
+`loadData` and `saveData`. Everything else is optional and switches a feature
+on; the API reference lists each prop.
+
+### Working with a mounted editor
+
+```ts
+bibleNote.content; // serialized editor state (JSON string)
+bibleNote.content = savedState; // replace the document; '' clears it
+bibleNote.addText('^'); // insert as if pasted at the caret
+bibleNote.addText('(KJV) Genesis 1:1\n(1): In the beginning God created…');
+bibleNote.isReadOnly = true; // lock — the user cannot unlock it
+bibleNote.searchText('Moses'); // open the find bar on a query; null closes it
+bibleNote.getIsFocusing(); // is the caret in the editor right now?
+BibleNote.getAllShortVersesFromText(bibleNote.content); // ['GEN 1:1', …]
+```
+
+The two `addText` calls above create a Bible verse mention: verse text pasted
+right after a `^` becomes a verse mention instead of a collapsible block.
+
+### Host footer buttons
+
+```tsx
+bibleNote.prependFooterActionButton({
+  id: 'open-in-app',
+  description: 'Open in my app',
+  shortcutKey: 'Ctrl+Shift+K',
+  children: (
+    <button className="action-button" onClick={openInApp}>
+      <i className="bi bi-box-arrow-up-right" />
+    </button>
+  ),
+});
+bibleNote.removeFooterActionButton('open-in-app');
+```
+
+`prepend…` places a button before the built-in footer buttons, `append…` after
+them. Re-adding an `id` replaces that button in place. `description` becomes the
+tooltip when the element has no `title`; `shortcutKey` clicks the button from
+anywhere in the page and is shown in the tooltip. Give the button the
+`action-button` class to match the built-in ones.
+
+### Mounting without auto-mount
+
+`render` can be called any time after construction and again later — each call
+unmounts the previous root first. Call `unmount()` when the host view goes away;
+the instance keeps its props and footer buttons for the next `render`.
+
+<a id="dev-datasets-and-lookup-managers"></a>
+
+## Datasets and lookup managers
+
+The editor ships no data. Every person and place it can mention comes from two
+managers the host builds:
+
+```ts
+const names = NamesLookupManager.fromRawDataset({ en: namesMap }, 'en');
+const locations = LocationsLookupManager.fromRawDataset(
+  { en: locationsMap },
+  'en',
+);
+```
+
+`fromRawDataset` takes the generated dataset files exactly as fetched —
+`namesMap.json` (`{ version, namesMap, childrenTree, versePersonsMap }`) and
+`locationsMap.json` — keyed by a language code, and normalizes them. Records
+can be an id-keyed object or an array; anything unrecognised is dropped rather
+than trusted. Use the plain constructors only when you already hold normalized
+`MentionNameMatch` / `MentionLocationMatch` records.
+
+A manager may hold several languages (`{ en: …, km: … }`); `defaultLang` picks
+the one the editor uses, and every query method takes an optional `lang`. The
+constructor throws when the default language is missing from the map.
+
+### Records
+
+A name record (`MentionNameMatch`) carries the name, a one-line `title`, a
+`description`, family links (`parents`, `children`, `spouses`, `siblings`,
+`cousin` — record ids), `locations` (location ids), `verses`, `links`,
+`wikipedia`, `gender`, `age`, `years` and a `type` (`person`, `group`, `deity`,
+`place`, `concept`, `month`, `supernatural`, `life`, `unknown`). A location
+record (`MentionLocationMatch`) carries `type` (`city`, `region`, `mountain`, …),
+`coordinates`, `modernIdentification`, `relatedLocations`, `uncertainty` and the
+same text, verse and link fields.
+
+`title` and `description` may contain inline reference links the UI renders as
+clickable references:
+
+| Link                                 | Points to         |
+| ------------------------------------ | ----------------- |
+| `[Amram](name-id://<id>)`            | a name record     |
+| `[Egypt](location-id://<id>)`        | a location record |
+| `[Genesis 1:1](verse-key://GEN 1:1)` | a verse           |
+| `[Genesis](book-key://GEN)`          | a book            |
+| `[Genesis 14](chapter-key://GEN 14)` | a chapter         |
+
+Verse keys are short keys — a book code plus chapter and verse (`GEN 1:1`,
+`1SA 17:1-4`). Ranges are stored collapsed, so the length of `verses` is not a
+verse count.
+
+`matterRange` ranks importance: `0` is the most important record and larger is
+less important; records without a rank sort last. Every listing and every tie in
+a search is ordered by it, then alphabetically.
+
+### Searching
+
+```ts
+names.searchNames('Mos', { limit: 20 }); // ranked MentionNameMatch[]
+names.searchNames('', { type: 'deity' }); // filter applies before limit
+names.searchNamesPagination({ query: 'Mos', page: 2, pageSize: 20 });
+names.getRecordById(id);
+names.getRecordsByIds(record.children);
+names.getRecordsByName('Zechariah'); // names are not unique
+names.searchByShortVerse('EXO 6:23'); // the names that verse prints
+names.nameTypes; // types present, most common first
+locations.searchLocations('Jer', { limit: 10 });
+```
+
+Search is a case-insensitive substring match on the name, the KJV English name
+and the former name (`oldName`), ranked exact, then prefix, then substring, then
+by importance. An empty query lists everything in importance order. Indexes are
+built lazily per language on first use and recent queries are cached.
+
+`searchByShortVerse` needs the dataset's verse map (`versePersonsMap` /
+`verseLocationsMap`, both included in the generated files).
+
+### Translated datasets
+
+A record in a translated dataset (the Khmer and French mirrors of the KJV data)
+carries its translated `name` plus the KJV English name in `kjvName`. The
+managers index both, so the same manager answers a query in either language and
+ranks an English hit exactly like a native one:
+
+```ts
+const names = NamesLookupManager.fromRawDataset({ km: khmerNamesMap }, 'km');
+names.searchNames('Genesis'); // finds the record named "លោកុប្បត្តិ"
+```
+
+The built-in UI shows the English name beside the translated one in the lookup
+panel, the mention typeahead, the hover card and the advanced panel.
+`getMentionKjvName(record)` is the rule it uses: the English name, or `null`
+when there is nothing to add. An untranslated dataset carries no `kjvName`, and
+all of this is a no-op for it.
+
+### Styling a dataset
+
+Both managers take an optional third argument: a React-style CSS object merged
+into every surface that renders that dataset — the typeahead popup, the hover
+card, the advanced panel and the lookup panel's list and search box. Use it to
+give a dataset in another script its own font:
+
+```ts
+const locations = LocationsLookupManager.fromRawDataset(
+  { km: khmerLocationsMap },
+  'km',
+  { fontFamily: 'Battambang, serif' },
+);
+```
+
+The two managers are styled independently. `manager.style` can be read and
+reassigned, but plugins read it as they render, so a change only shows up on the
+next render. A hover card's own positioning always wins over the style.
+
+### Verse text
+
+The package bundles no Bible text. Three optional props let the host supply it:
+
+- `shortToVerseData(shortKey)` → `{ title, fullText, style? }` — labels verse
+  lists in the mention panels and fills the Word export's References appendix.
+- `verseFullTextToListShorts(fullText)` → short keys — lets a verse's advanced
+  panel show the people and places that verse mentions.
+- `changeBibleKey(event, fullText)` — makes the version label in a verse panel a
+  button that opens the same verse in another version.
+
+`fullText` is the shape the editor accepts when Bible text is pasted after `^`:
+a title line such as `(KJV) Genesis 1:1`, then one line per verse such as
+`(1): In the beginning…`.
+
+`BibleNote.getAllShortVersesFromText(text)` goes the other way: it lists every
+verse a note refers to — verse mentions and references typed in the prose — as
+short keys, in document order without duplicates. Ranges inside one chapter are
+expanded verse by verse; a range crossing chapters keeps only its endpoints.
+
+### Your own lookup UI
+
+The managers carry no editor dependency. To build a custom mention picker or a
+search page, construct them and call their methods — no `BibleNote` import is
+needed, and the results are exactly what the built-in UI shows.
+
+<a id="dev-persistence-and-storage"></a>
+
+## Persistence and storage
+
+The editor splits what it stores into two channels.
+
+| Channel      | Carries                                               | Host hook               |
+| ------------ | ----------------------------------------------------- | ----------------------- |
+| The note     | the serialized Lexical editor state of the document   | `loadData` / `saveData` |
+| Editor state | settings, comments, read-only mode, zoom, panel state | `storageManager`        |
+
+### The note: `loadData` and `saveData`
+
+`saveData(data)` is called on every change to the document with the serialized
+editor state — a JSON string, the same one `bibleNote.content` returns. It is
+called with `''` when a stored note turns out to be unreadable and is discarded.
+`loadData()` returns that string (or `null` / `''` for an empty editor) and may
+be async. Store it wherever the host keeps documents: a file, a database row, a
+server.
+
+Because `saveData` runs on every change, debounce it on the host side if the
+store is expensive. The string is also the lossless format: the footer's Export
+button downloads it, Import reads it back, and assigning `bibleNote.content`
+replaces the document with it.
+
+### Editor state: `storageManager`
+
+A `BibleNoteStorageManager` is three async methods — `getSetting`, `setSetting`,
+`deleteSetting` — over string values. `createBrowserStorageManager()` is the
+`localStorage` implementation; an Electron or server-backed host can implement
+the same three methods over its own store.
+
+Before the editor first renders it reads every key in
+`BIBLE_NOTE_STORAGE_MANAGER_KEYS` from the storage manager, then serves reads
+from memory; every write goes straight through to `setSetting`, fire-and-forget.
+The keys:
+
+| Key                                          | Holds                                                                      |
+| -------------------------------------------- | -------------------------------------------------------------------------- |
+| `lexical-playground-settings`                | the settings panel's switches                                              |
+| `lexical-playground-editor-state`            | the note — routed to `loadData` / `saveData`, never to the storage manager |
+| `lexical-playground-comments`                | comment threads                                                            |
+| `lexical-playground-comments-panel-open`     | whether the comments panel is open                                         |
+| `lexical-playground-block-text-links`        | the "link block text" connections                                          |
+| `lexical-playground-read-only-mode`          | whether the user locked the note                                           |
+| `lexical-playground-insert-character-picker` | the Emoji & HTML Character picker's state                                  |
+| `lexical-playground-editor-zoom-percent`     | the zoom level                                                             |
+
+The `lexical-playground-` prefix is inherited from the upstream playground; keep
+it when migrating stored data.
+
+The editor-state key is exported as `EDITOR_STATE_LOCAL_STORAGE_KEY`. The quick
+start reuses it to keep the note in the same store as everything else, which is
+fine for a single-note host; a multi-note host keeps each note under its own key
+or file and returns the right one from `loadData`.
+
+### Read-only mode
+
+The user can lock a note from the footer, and that choice persists under
+`lexical-playground-read-only-mode`. A host can force it: `bibleNote.isReadOnly
+= true` locks the note, turns the footer button into **Read-Only Mode Locked**,
+and the user cannot unlock it until the host assigns `false`.
+
+### Share links
+
+Outside an app (`isOnApp` false), the footer's **Share as Link** button encodes
+the note into the page URL's `editor-state` query parameter, optionally
+password-protected; opening such a URL loads that note. Hosts that embed the
+editor in an app set `isOnApp: true`, which hides the button.
+
+<a id="dev-host-integration"></a>
+
+## Host integration
+
+Every optional prop switches on one integration. This topic groups them by
+feature; the API reference has the exact signatures.
+
+### Fonts and languages
+
+- `editorExtraFontFamilies: [['Battambang', 'km'], …]` adds fonts to the
+  toolbar's font menu and to Excalidraw, each tagged with a language code. The
+  host loads the font faces itself (a `@font-face` or a webfont link).
+- `getLangCode(text)` returns a language code for a piece of text. When it
+  returns something other than `'en'`, pasted Bible text and Excalidraw text
+  switch to the first extra font registered for that language — so Khmer verse
+  text renders in a Khmer font automatically.
+- `stickyNoteExtraFontFamilies: ['"Fasthand"', …]` adds CSS font-family values
+  to the sticky-note font picker.
+- A lookup manager's style object (`{ fontFamily }`) styles one dataset across
+  the mention UI; see the datasets topic.
+
+### Media files
+
+By default a picked or dropped image, video, audio or PDF is embedded in the
+note as a data URL. Two hooks change that:
+
+- `resolveFilePath(file, { source })` returns a path or URL to store instead —
+  for example the file's location on disk in Electron, or an upload URL. `source`
+  is `'drop'` (dropped or pasted) or `'file-input'` (picked in the media dialog).
+  Return `null` to fall back to embedding.
+- `revealFile(path)` shows a local file to the user (Electron:
+  `shell.showItemInFolder`). With it, a selected media item whose source is a
+  local path gets a reveal button.
+
+### Excalidraw libraries
+
+The editor bundles a Christian-themed Excalidraw library. `excalidrawLibraryItems`
+adds library items of the host's own. To persist libraries the user imports
+inside Excalidraw, implement the trio:
+
+- `excalidrawSaveLibrariesFile(json)` — store one serialized library;
+- `excalidrawLoadLibrariesFileList()` — return the stored libraries, read when
+  the Excalidraw editor opens;
+- `excalidrawClearLibrariesFileList()` — forget them all.
+
+The demo host keeps the list as a JSON array in `localStorage`.
+
+### Settings panel
+
+`render(el, { settings: <BibleNoteSettings setColorScheme={…} /> })` adds the
+gear button and its switches. Without `settings` there is no settings panel and
+every setting keeps its default. `settingsContainerElement` portals the panel
+elsewhere in the page (the demo puts it in a fixed container of its own).
+Settings persist through the storage manager. The switches, their keys and
+defaults:
+
+| Switch | Setting | Default |
+| --- | --- | --- |
+| Measure Perf | `measureTypingPerf` | Off |
+| Debug View | `showTreeView` | Off |
+| Dark Mode | `isDarkMode` | Off |
+| Show invisible characters | `showInvisibleCharacters` | Off |
+| Nested Editors Debug View | `showNestedEditorTreeView` | Off |
+| Rich Text | `isRichText` | On |
+| Nested Tables | `hasNestedTables` | Off |
+| Char Limit | `isCharLimit` | Off |
+| Char Limit (UTF-8) | `isCharLimitUtf8` | Off |
+| Link Attributes | `hasLinkAttributes` | Off |
+| Max Length | `isMaxLength` | Off |
+| Autocomplete | `isAutocomplete` | On |
+| Table Of Contents | `showTableOfContents` | Off |
+| Use Lexical Context Menu | `shouldUseLexicalContextMenu` | Off |
+| Preserve newlines in Markdown | `shouldPreserveNewLinesInMarkdown` | Off |
+| Use Brackets for Highlighting | `shouldAllowHighlightingWithBrackets` | Off |
+| Retain selection | `selectionAlwaysOnDisplay` | Off |
+| Enable Code Highlighting | `isCodeHighlighted` | On |
+| Use Shiki for Code Highlighting | `isCodeShiki` | Off |
+
+Pass `setColorScheme={(mode) => bibleNote.setColorScheme(mode)}` so the
+instance's `colorScheme` follows the Dark Mode switch.
+
+### Footer modes
+
+- `isOnApp: true` — the editor runs inside an app, not a web page: hides
+  **Share as Link** and **Convert From Markdown**.
+- `isMinimize: true` — compact footer: Import, Export and Editor Information
+  move into a **More actions** menu.
+- `print()` — replaces the built-in printing (which lays the note out at the
+  selected page size and opens the print dialog).
+
+Host buttons go before or after the built-in ones with
+`prependFooterActionButton` / `appendFooterActionButton`.
+
+### Electron: native file dialogs
+
+When the page exposes `window.bibleNoteDesktop`, the footer's Word import/export
+and JSON Import/Export use native Open and Save dialogs instead of a browser
+file picker and download. The contract (this repository's
+`scripts/electron-preload.cjs` implements it with `contextBridge` and two
+`ipcMain` handlers):
+
+```ts
+window.bibleNoteDesktop = {
+  isElectron: true,
+  openFile(options: { filters: { name: string; extensions: string[] }[] }):
+    Promise<{ canceled: true } | { canceled: false; data: Uint8Array; fileName: string }>,
+  saveFile(options: {
+    data: Uint8Array | string;
+    defaultFileName: string;
+    filters: { name: string; extensions: string[] }[];
+  }): Promise<{ canceled: true } | { canceled: false; fileName: string }>,
+};
+```
+
+The bridge is detected by `isElectron === true`. It is independent of
+`isOnApp` — the demo host sets `isOnApp` from whether the bridge exists, which
+is a reasonable default.
+
+### Word round trips
+
+The footer's Word buttons export a standard `.docx` that also embeds a private
+BibleNote copy of the editor state; importing that file restores the full
+editable document. A `.docx` from elsewhere (or one Word has stripped) is
+converted from its Word content: text, headings, emphasis, lists, tables, links
+and images survive, Word-only layout may be simplified.
+
+Because a Word document has no hover cards, the export adds a **References**
+appendix: every person, place and verse mention links to an entry with the
+record's details and the verse text. Verse references are resolved through
+`shortToVerseData` and related people and places through
+`verseFullTextToListShorts`, so supply both for a complete appendix. Equations
+become editable Word equations; sticky notes, drawings and embed thumbnails
+become pictures.
+
+<a id="dev-working-on-the-editor-ui"></a>
+
+## Working on the editor UI
+
+This topic is for changing the editor itself, in its source repository.
+
+### Layout
+
+| Path                                         | What lives there                                                                       |
+| -------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `src/lib.ts`                                 | the package's public entry — only re-exports; everything it reaches is library code    |
+| `src/index.tsx`                              | the demo host (fetches datasets, wires every prop, mounts) — not part of the package   |
+| `src/BibleNote.ts`                           | the `BibleNote` class: queued editor actions, footer buttons, colour scheme            |
+| `src/bibleNoteHelpers.tsx`                   | `BibleNoteProps`, the storage split, `renderEditor`                                    |
+| `src/AppComp.tsx`                            | providers, storage hydration, the editor controller behind `BibleNote`'s methods       |
+| `src/Editor.tsx`                             | the plugin tree, zoom and the full-view layout                                         |
+| `src/plugins/<Name>Plugin/`                  | one Lexical plugin per folder                                                          |
+| `src/nodes/`                                 | custom Lexical nodes (`PlaygroundNodes.ts` registers them)                             |
+| `src/ui/`                                    | shared UI: modals, dropdowns, colour picker, Excalidraw modal, equation editor         |
+| `src/context/`                               | React contexts: settings, toolbar state, lookup managers, verse actions, media actions |
+| `src/themes/`                                | the Lexical editor themes and their SCSS                                               |
+| `src/LookupManager.ts`, `src/lookupTypes.ts` | the dataset managers and record types                                                  |
+| `test-packages/`                             | a consumer app that installs the built package from `../packages/bible-note`           |
+
+### The plugin tree
+
+`src/Editor.tsx` renders every plugin. The table below is generated from it;
+"mounted when" is the condition wrapping the element, usually a setting from the
+settings panel.
+
+| Plugin | Source | Mounted when |
+| --- | --- | --- |
+| `ToolbarPlugin` | `src/plugins/ToolbarPlugin` | `isRichText` |
+| `ShortcutsPlugin` | `src/plugins/ShortcutsPlugin` | `isRichText` |
+| `MaxLengthPlugin` | `src/plugins/MaxLengthPlugin` | `isMaxLength` |
+| `DragDropPaste` | `src/plugins/DragDropPastePlugin` | always |
+| `AutoFocusPlugin` | `@lexical/react/LexicalAutoFocusPlugin` | always |
+| `EditorStatePersistencePlugin` | `src/plugins/EditorStatePersistencePlugin` | always |
+| `SelectionAlwaysOnDisplay` | `@lexical/react/LexicalSelectionAlwaysOnDisplay` | `selectionAlwaysOnDisplay` |
+| `ClearEditorPlugin` | `@lexical/react/LexicalClearEditorPlugin` | always |
+| `FindPlugin` | `src/plugins/FindPlugin` | always |
+| `ComponentPickerPlugin` | `src/plugins/ComponentPickerPlugin` | always |
+| `EmojiPickerPlugin` | `src/plugins/EmojiPickerPlugin` | always |
+| `AutoEmbedPlugin` | `src/plugins/AutoEmbedPlugin` | always |
+| `MentionNamePlugin` | `src/plugins/MentionNamePlugin` | always |
+| `MentionLocationsPlugin` | `src/plugins/MentionLocationsPlugin` | always |
+| `MentionBibleVersesPlugin` | `src/plugins/MentionBibleVersesPlugin` | always |
+| `EmojisPlugin` | `src/plugins/EmojisPlugin` | always |
+| `KeywordsPlugin` | `src/plugins/KeywordsPlugin` | always |
+| `AutoLinkPlugin` | `src/plugins/AutoLinkPlugin` | always |
+| `DateTimePlugin` | `src/plugins/DateTimePlugin` | always |
+| `CommentPlugin` | `src/plugins/CommentPlugin` | always |
+| `LookupPlugin` | `src/plugins/LookupPlugin` | always |
+| `HistoryPlugin` | `@lexical/react/LexicalHistoryPlugin` | `isRichText` |
+| `RichTextPlugin` | `@lexical/react/LexicalRichTextPlugin` | `isRichText` |
+| `StickyPlugin` | `src/plugins/StickyPlugin` | `isRichText` |
+| `MarkdownShortcutPlugin` | `src/plugins/MarkdownShortcutPlugin` | `isRichText` |
+| `CodeHighlightShikiPlugin` | `src/plugins/CodeHighlightShikiPlugin` | `isRichText` and `isCodeHighlighted` and `isCodeShiki` |
+| `CodeHighlightPrismPlugin` | `src/plugins/CodeHighlightPrismPlugin` | `isRichText` and `isCodeHighlighted` and `!(isCodeShiki)` |
+| `ListPlugin` | `@lexical/react/LexicalListPlugin` | `isRichText` |
+| `CheckListPlugin` | `@lexical/react/LexicalCheckListPlugin` | `isRichText` |
+| `TablePlugin` | `@lexical/react/LexicalTablePlugin` | `isRichText` |
+| `TableCellResizer` | `src/plugins/TableCellResizer` | `isRichText` |
+| `TableScrollShadowPlugin` | `src/plugins/TableScrollShadowPlugin` | `isRichText` |
+| `MediaPlugin` | `src/plugins/MediaPlugin` | `isRichText` |
+| `LinkPlugin` | `src/plugins/LinkPlugin` | `isRichText` |
+| `PollPlugin` | `src/plugins/PollPlugin` | `isRichText` |
+| `YouTubePlugin` | `src/plugins/YouTubePlugin` | `isRichText` |
+| `WebsitePlugin` | `src/plugins/WebsitePlugin` | `isRichText` |
+| `ClickableLinkPlugin` | `@lexical/react/LexicalClickableLinkPlugin` | `isRichText` |
+| `HorizontalRulePlugin` | `@lexical/react/LexicalHorizontalRulePlugin` | `isRichText` |
+| `EquationsPlugin` | `src/plugins/EquationsPlugin` | `isRichText` |
+| `ExcalidrawPlugin` | `src/plugins/ExcalidrawPlugin` | `isRichText` |
+| `TabFocusPlugin` | `src/plugins/TabFocusPlugin` | `isRichText` |
+| `TabIndentationPlugin` | `@lexical/react/LexicalTabIndentationPlugin` | `isRichText` |
+| `CollapsiblePlugin` | `src/plugins/CollapsiblePlugin` | `isRichText` |
+| `PageBreakPlugin` | `src/plugins/PageBreakPlugin` | `isRichText` |
+| `LayoutPlugin` | `src/plugins/LayoutPlugin/LayoutPlugin` | `isRichText` |
+| `FloatingLinkEditorPlugin` | `src/plugins/FloatingLinkEditorPlugin` | `isRichText` and `floatingAnchorElem` |
+| `BlockTextLinkPlugin` | `src/plugins/BlockTextLinkPlugin` | `isRichText` and `floatingAnchorElem` |
+| `TableCellActionMenuPlugin` | `src/plugins/TableActionMenuPlugin` | `isRichText` and `floatingAnchorElem` |
+| `FloatingTextFormatToolbarPlugin` | `src/plugins/FloatingTextFormatToolbarPlugin` | `isRichText` and `floatingAnchorElem` |
+| `DraggableBlockPlugin` | `src/plugins/DraggableBlockPlugin` | `isRichText` and `floatingAnchorElem && hasPointerAffordances` |
+| `CodeActionMenuPlugin` | `src/plugins/CodeActionMenuPlugin` | `isRichText` and `floatingAnchorElem && hasPointerAffordances` |
+| `TableHoverActionsV2Plugin` | `src/plugins/TableHoverActionsV2Plugin` | `isRichText` and `floatingAnchorElem && hasPointerAffordances` |
+| `PlainTextPlugin` | `@lexical/react/LexicalPlainTextPlugin` | `!(isRichText)` |
+| `HistoryPlugin` | `@lexical/react/LexicalHistoryPlugin` | `!(isRichText)` |
+| `InvisibleCharactersPlugin` | `src/plugins/InvisibleCharactersPlugin` | always |
+| `CharacterLimitPlugin` | `@lexical/react/LexicalCharacterLimitPlugin` | `(isCharLimit \|\| isCharLimitUtf8)` |
+| `AutocompletePlugin` | `src/plugins/AutocompletePlugin` | `isAutocomplete` |
+| `PageSizePreviewPlugin` | `src/plugins/PageSizePreviewPlugin` | always |
+| `PaperPageNavigationPlugin` | `src/plugins/PaperPageNavigationPlugin` | always |
+| `TableOfContentsPlugin` | `src/plugins/TableOfContentsPlugin` | `showTableOfContents` |
+| `ContextMenuPlugin` | `src/plugins/ContextMenuPlugin` | `shouldUseLexicalContextMenu` |
+| `SpecialTextPlugin` | `src/plugins/SpecialTextPlugin` | `shouldAllowHighlightingWithBrackets` |
+| `ActionsPlugin` | `src/plugins/ActionsPlugin` | always |
+| `TreeViewPlugin` | `src/plugins/TreeViewPlugin` | `showTreeView` |
+
+`isRichText` is on by default; `floatingAnchorElem` is the editor's scroll
+container once it has mounted; `hasPointerAffordances` is true on a device with a
+fine, hovering pointer (mouse or trackpad), so drag handles and hover menus never
+appear on touch screens.
+
+### Adding a feature
+
+A typical new block or inline feature touches:
+
+1. a node in `src/nodes/`, registered in `src/nodes/PlaygroundNodes.ts`;
+2. a plugin folder in `src/plugins/`, mounted in `src/Editor.tsx` (behind a
+   setting if it is optional — add the key to `DEFAULT_SETTINGS` in
+   `src/appSettings.ts` and a `<Switch>` in `src/Settings.tsx`);
+3. a slash-menu option in `getBaseOptions()` in
+   `src/plugins/ComponentPickerPlugin/index.tsx` and/or an item in the toolbar's
+   Insert dropdown;
+4. a shortcut in `SHORTCUTS` (`src/plugins/ShortcutsPlugin/shortcuts.ts`) and its
+   handler in the shortcuts plugin, if it has one;
+5. theme classes in `src/themes/PlaygroundEditorTheme.ts` and SCSS;
+6. any persisted state through `getBibleNoteStorage()` (`src/storageManager.ts`),
+   with the key added to `BIBLE_NOTE_STORAGE_MANAGER_KEYS` so it is hydrated
+   before the first render;
+7. Word export/import handling in `src/utils/docx*` if the node needs a Word form;
+8. the user-facing description in `knowledge/ui/` (see "The knowledge files"
+   below).
+
+UI follows the existing conventions: Bootstrap utility classes, `bi bi-*` icons
+from bootstrap-icons (a peer dependency — never import its CSS from library
+code), and colours that work under both `playground-theme-light` and
+`playground-theme-dark`.
+
+### Running it
+
+- `npm run dev` — Vite on `http://localhost:3005` plus the Electron shell, with
+  remote debugging on `127.0.0.1:9225`.
+- `npm run vite` — the web app alone on port 3005.
+- If Electron dies at startup with a `BrowserWindow` export error, the shell
+  inherited `ELECTRON_RUN_AS_NODE=1` (VS Code's integrated terminal sets it);
+  clear it and run again.
+- `npm run test:unit` — Vitest + jsdom over `src/**/*.test.ts(x)`.
+- `npm run test:e2e` — Playwright.
+- `npm run lint:ts`, `npm run lint:es`, `npm run lint:pre` — types, ESLint,
+  Prettier.
+
+### Verifying UI changes in the browser
+
+Do not call a UI change done until it has been exercised in the running app.
+The repository's Chrome DevTools MCP server attaches to the Electron debug port
+(`9225`): select the `http://localhost:3005/` page, snapshot it, drive the flow
+with clicks and key presses, watch the console, and screenshot the result. The
+`bn-robot-test` skill runs a full regression battery this way — mentions, slash
+menu, toolbar, markdown shortcuts, tables, undo, persistence — and backs up and
+restores the open note around it.
+
+### The knowledge files
+
+`knowledge/development/*.md` and `knowledge/ui/*.md` are the hand-written
+sources of the two knowledge files; `npm run pack` builds them into
+`packages/bible-note/knowledge/` (`npm run build:knowledge` rebuilds just them).
+When a user-visible behaviour changes, update the matching `knowledge/ui/` topic;
+when the public API changes, update its JSDoc — the API reference is generated
+from the declarations. Catalogues such as the slash menu, shortcuts and the table
+above are extracted from source; if `pack` fails in an extractor, the source moved
+and `scripts/knowledge/extractUi.mjs` needs to follow it. `knowledge/README.md`
+has the authoring rules.
+
+<a id="dev-building-and-releasing-the-package"></a>
+
+## Building and releasing the package
+
+### `npm run pack`
+
+`scripts/pack.mjs` builds `packages/bible-note/`:
+
+1. wipes the generated directories — `dist/`, `types/`, `knowledge/`;
+2. bundles `src/lib.ts` twice with `vite.lib.config.ts`, once as ESM (`.mjs`)
+   and once as CommonJS (`.cjs`), plus the single `dist/bible-note.css`;
+3. emits declarations with `tsc -p tsconfig.lib.json` and prunes them to what
+   `types/lib.d.ts` actually reaches;
+4. builds `knowledge/development.md` and `knowledge/ui-rag.md`;
+5. checks the static `package.json` against the build and the root manifest —
+   every advertised path exists, `files` and `sideEffects` are right, peer
+   ranges match the root `package.json`, external packages are declared;
+6. checks the entry surface (required exports present, no peer CSS bundled, no
+   throwing `require()` polyfill in the ES build) and type-checks the packaged
+   declarations from outside the repository, as a consumer would see them.
+
+Any failure stops the run with the exact mismatch.
+
+### Hand-maintained files
+
+`packages/bible-note/package.json`, `README.md` and `LICENSE` are the only files
+in `packages/` that git tracks, and no script writes them:
+
+- bump `version` whenever library code changes — patch for fixes and internal
+  changes, minor for new exports, options or published files, major for a
+  breaking change to the public surface;
+- update the README when a change is visible to a consumer (a new export goes
+  in its Exports table);
+- edit `package.json` by hand when peer ranges change in the root manifest or
+  entry points move — `pack` reports the exact drift.
+
+### Testing the built package
+
+`test-packages/` installs `bible-note` from `../packages/bible-note`. After
+`npm run pack`, run `npm i` and `npm run vite` (port 3007) there to use the
+tarball contents exactly as a consumer would. `npm run copy-packages` mirrors
+the publishable files into the sibling `../bible-note-dist` checkout
+(`npm run pack:copy` does both).
+
+### Publishing
+
+From a clean `main`, with the package built:
+
+```bash
+npm pack --dry-run                          # check the file list
+npm whoami                                  # npm login if this fails
+npm version patch --tag-version-prefix=""   # or minor / major
+npm publish
+git push origin main --follow-tags
+npm view bible-note version
+```
+
+<a id="dev-api-reference"></a>
+
+## API reference
+
+Generated from the package's own declarations (`types/lib.d.ts`), so it lists
+exactly what `import … from 'bible-note'` provides. Descriptions are the JSDoc
+on the source; a member without one shows its signature only.
+
+The package's default export is [`BibleNote`](#api-biblenote); every name below is also a named export of `bible-note`.
+
+### Classes
+
+<a id="api-biblenote"></a>
+
+#### `BibleNote`
+
+The BibleNote editor. Construct it with the host's datasets and storage
+callbacks, then [`render`](#api-biblenote) it into an element.
+
+Every editor-backed method (`content`, `addText`, `searchText`, …) can be
+called before `render`: writes are queued and applied once the editor has
+mounted, and reads return an empty value until then.
+
+```ts
+new BibleNote(...)
+constructor(props: BibleNoteProps);
+```
+
+##### `BibleNote.VERSION`
+
+```ts
+static VERSION: string;
+```
+
+The package version this bundle was built from.
+
+##### `BibleNote.getAllShortVersesFromText()`
+
+```ts
+static getAllShortVersesFromText(lexicalText: string): Array<string>;
+```
+
+Every short verse reference (`GEN 1:1`) the given note content mentions, in
+document order and without duplicates. Takes what `content` returns — a
+serialized editor state — or plain text, and reads both the Bible verse
+mentions and any reference written in the prose. Ranges inside one chapter
+are expanded verse by verse; a range crossing a chapter boundary keeps only
+its endpoints, because per-chapter verse counts are not bundled here.
+
+##### `props`
+
+```ts
+props: Readonly<BibleNoteProps>;
+```
+
+The props the instance was constructed with.
+
+##### `colorScheme`
+
+```ts
+colorScheme: BibleNoteColorScheme;
+```
+
+The colour scheme last applied — by [`BibleNote.setColorScheme`](#api-biblenote) or the
+settings panel's Dark Mode switch. Read it; change it with `setColorScheme`.
+
+##### `content`
+
+```ts
+get content(): string;
+set content(value: string);
+```
+
+The note as a serialized Lexical editor state (a JSON string) — the same
+string `saveData` receives. Reads `''` until the editor has mounted.
+Assigning replaces the whole document; assigning `''` clears it.
+
+##### `isReadOnly`
+
+```ts
+get isReadOnly(): boolean;
+set isReadOnly(value: boolean);
+```
+
+Whether the note is locked against editing. Assigning `true` forces
+read-only mode: the footer's lock turns into **Read-Only Mode Locked** and
+the user cannot unlock it. Assigning `false` releases that lock and makes
+the note editable.
+
+##### `getIsFocusing()`
+
+```ts
+getIsFocusing(): boolean;
+```
+
+Whether the caret is in the editor right now: the window has focus, the
+editor is the active element, and the selection is a collapsed caret inside
+it. A host can use this to decide whether to send text to `addText`.
+
+##### `setColorScheme()`
+
+```ts
+setColorScheme(mode: BibleNoteColorScheme): void;
+```
+
+Switches the editor between light and dark. Applies the body classes at
+once (see `applyBibleNoteColorScheme`) and keeps the settings panel's Dark
+Mode switch in step.
+
+##### `addText()`
+
+```ts
+addText(text: string): void;
+```
+
+Inserts text at the caret, or at the end of the note when there is no
+selection, exactly as if the user had pasted it as plain text — so the
+paste rules apply: Bible text pasted right after a `^` becomes a verse
+mention. Ignored while the note is read-only or when `text` is empty.
+
+##### `appendFooterActionButton()`
+
+```ts
+appendFooterActionButton(actionButton: BibleNoteFooterActionButton): void;
+```
+
+Adds a host button after the footer's built-in buttons. A button whose `id`
+is already present is replaced in place, keeping its position.
+
+##### `prependFooterActionButton()`
+
+```ts
+prependFooterActionButton(actionButton: BibleNoteFooterActionButton): void;
+```
+
+Adds a host button before the footer's built-in buttons, ahead of any
+prepended earlier. A button whose `id` is already present is replaced in
+place, keeping its position.
+
+##### `getFooterActionButton()`
+
+```ts
+getFooterActionButton(id: string): BibleNoteFooterActionButton | null;
+```
+
+The host footer button with this `id`, or `null`.
+
+##### `removeFooterActionButton()`
+
+```ts
+removeFooterActionButton(id: string): boolean;
+```
+
+Removes the host footer button with this `id`; `false` when there was none.
+
+##### `searchText()`
+
+```ts
+searchText(query: string | null): void;
+```
+
+Drives the editor's find bar. A string opens the bar (or updates the query
+if it is already open); `null` closes it. Queued until the editor mounts,
+like the other editor-backed methods.
+
+##### `render()`
+
+```ts
+render(containerElement: HTMLElement, options?: BibleNoteRenderOptions): void;
+```
+
+Mounts the editor into `containerElement` with its own React root.
+Rendering again unmounts the previous root first, so an instance is only
+ever mounted once.
+
+##### `unmount()`
+
+```ts
+unmount(): void;
+```
+
+Unmounts the editor. The instance keeps its props and footer buttons and
+can be rendered again.
+
+<a id="api-locationslookupmanager"></a>
+
+#### `LocationsLookupManager`
+
+Owns the place/location dataset(s): ranked search, id and name lookup,
+pagination and verse → locations lookup. Has no editor dependency, so a host
+can use it to build its own UI. Indexes are built lazily per language on
+first use.
+
+```ts
+new LocationsLookupManager(...)
+constructor(dataMap: LocationsLookupManagerDataMap, defaultLang: string, style?: LookupManagerStyle);
+```
+
+##### `LocationsLookupManager.fromRawDataset()`
+
+```ts
+static fromRawDataset(rawDataMap: {
+    [langCode: string]: unknown;
+}, defaultLang: string, style?: LookupManagerStyle): LocationsLookupManager;
+```
+
+Builds a manager straight from the generated dataset files, i.e. whatever
+`fetch('data/KJV/locationsMap.json')` resolved to, keyed by language code.
+Older generated files stored the records under `namesMap`, so both keys are
+accepted.
+
+##### `LocationsLookupManager.createEmpty()`
+
+```ts
+static createEmpty(): LocationsLookupManager;
+```
+
+An empty manager, used wherever a host has not supplied a dataset yet.
+
+##### `searchLocations()`
+
+```ts
+searchLocations(query: string, options?: LookupSearchOptions): Array<MentionLocationMatch>;
+```
+
+Locations matching `query`. Case-insensitive substring match against the name, the KJV English
+name (translated datasets) and the former name. Ranked exact, then prefix,
+then substring — the better of the two names counts — and by importance
+(`matterRange`, then alphabetical) within a tier. An empty query returns
+every record in importance order.
+
+##### `searchLocationsPagination()`
+
+```ts
+searchLocationsPagination(options?: LookupPaginationOptions): LookupPaginationResult<MentionLocationMatch>;
+```
+
+`searchLocations`, one page at a time (20 records per page by default).
+
+##### `searchByShortVerse()`
+
+```ts
+searchByShortVerse(shortVerse: string, lang?: string): Array<MentionLocationMatch>;
+```
+
+The locations a short verse key (e.g. `"EXO 6:23"`) mentions.
+
+##### `style`
+
+```ts
+get style(): LookupManagerStyle | undefined;
+set style(style: LookupManagerStyle | undefined);
+```
+
+The host-supplied style for this dataset, or `undefined` when it gave none.
+The UI merges it into the containers that render these records; like
+`defaultLang` it is read at render time, so a host that changes it after
+mounting must also make the editor re-render.
+
+##### `defaultLang`
+
+```ts
+get defaultLang(): string;
+set defaultLang(lang: string);
+```
+
+The language used when a call names none (or names one this manager does
+not hold). Assigning a language the data map lacks throws.
+
+##### `langs`
+
+```ts
+get langs(): ReadonlyArray<string>;
+```
+
+The language codes this manager holds data for.
+
+##### `getRecordCount()`
+
+```ts
+getRecordCount(lang?: string): number;
+```
+
+Total number of records in a language, ignoring any query.
+
+##### `getAllRecords()`
+
+```ts
+getAllRecords(lang?: string): Array<TRecord>;
+```
+
+Every record in a language, in importance order.
+
+##### `getRecordById()`
+
+```ts
+getRecordById(id: string, lang?: string): TRecord | null;
+```
+
+The record with this id (whitespace-trimmed), or `null`.
+
+##### `getRecordsByIds()`
+
+```ts
+getRecordsByIds(ids: ReadonlyArray<string>, lang?: string): Array<TRecord>;
+```
+
+The records for these ids, in the order given; unknown and repeated ids
+are skipped.
+
+##### `getRecordsByName()`
+
+```ts
+getRecordsByName(name: string, lang?: string): Array<TRecord>;
+```
+
+Every record carrying exactly this name. Names are not unique in the
+datasets, so callers that need certainty check for a single result.
+
+<a id="api-nameslookupmanager"></a>
+
+#### `NamesLookupManager`
+
+Owns the person/name dataset(s): ranked search, id and name lookup,
+pagination, name-type counts and verse → names lookup. Has no editor
+dependency, so a host can use it to build its own UI. Indexes are built
+lazily per language on first use.
+
+```ts
+new NamesLookupManager(...)
+constructor(dataMap: NamesLookupManagerDataMap, defaultLang: string, style?: LookupManagerStyle);
+```
+
+##### `NamesLookupManager.fromRawDataset()`
+
+```ts
+static fromRawDataset(rawDataMap: {
+    [langCode: string]: unknown;
+}, defaultLang: string, style?: LookupManagerStyle): NamesLookupManager;
+```
+
+Builds a manager straight from the generated dataset files, i.e. whatever
+`fetch('data/KJV/namesMap.json')` resolved to, keyed by language code. Use this
+unless you already hold normalized [`MentionNameMatch`](#api-mentionnamematch) records.
+
+##### `NamesLookupManager.createEmpty()`
+
+```ts
+static createEmpty(): NamesLookupManager;
+```
+
+An empty manager, used wherever a host has not supplied a dataset yet.
+
+##### `getNameTypes()`
+
+```ts
+getNameTypes(lang?: string): ReadonlyArray<NameTypeCount>;
+```
+
+The name types actually present in the data, most common first, so a type
+filter only ever offers choices that would return results.
+
+##### `nameTypes`
+
+```ts
+get nameTypes(): ReadonlyArray<NameTypeCount>;
+```
+
+The name types present in the default language.
+
+##### `searchNames()`
+
+```ts
+searchNames(query: string, options?: NamesLookupSearchOptions): Array<MentionNameMatch>;
+```
+
+Names matching `query`. Case-insensitive substring match against the name, the KJV English
+name (translated datasets) and the former name. Ranked exact, then prefix,
+then substring — the better of the two names counts — and by importance
+(`matterRange`, then alphabetical) within a tier. An empty query returns
+every record in importance order.
+
+##### `searchNamesPagination()`
+
+```ts
+searchNamesPagination(options?: NamesLookupPaginationOptions): LookupPaginationResult<MentionNameMatch>;
+```
+
+`searchNames`, one page at a time (20 records per page by default).
+
+##### `searchByShortVerse()`
+
+```ts
+searchByShortVerse(shortVerse: string, lang?: string): Array<MentionNameMatch>;
+```
+
+The names a short verse key (e.g. `"EXO 6:23"`) mentions.
+
+##### `style`
+
+```ts
+get style(): LookupManagerStyle | undefined;
+set style(style: LookupManagerStyle | undefined);
+```
+
+The host-supplied style for this dataset, or `undefined` when it gave none.
+The UI merges it into the containers that render these records; like
+`defaultLang` it is read at render time, so a host that changes it after
+mounting must also make the editor re-render.
+
+##### `defaultLang`
+
+```ts
+get defaultLang(): string;
+set defaultLang(lang: string);
+```
+
+The language used when a call names none (or names one this manager does
+not hold). Assigning a language the data map lacks throws.
+
+##### `langs`
+
+```ts
+get langs(): ReadonlyArray<string>;
+```
+
+The language codes this manager holds data for.
+
+##### `getRecordCount()`
+
+```ts
+getRecordCount(lang?: string): number;
+```
+
+Total number of records in a language, ignoring any query.
+
+##### `getAllRecords()`
+
+```ts
+getAllRecords(lang?: string): Array<TRecord>;
+```
+
+Every record in a language, in importance order.
+
+##### `getRecordById()`
+
+```ts
+getRecordById(id: string, lang?: string): TRecord | null;
+```
+
+The record with this id (whitespace-trimmed), or `null`.
+
+##### `getRecordsByIds()`
+
+```ts
+getRecordsByIds(ids: ReadonlyArray<string>, lang?: string): Array<TRecord>;
+```
+
+The records for these ids, in the order given; unknown and repeated ids
+are skipped.
+
+##### `getRecordsByName()`
+
+```ts
+getRecordsByName(name: string, lang?: string): Array<TRecord>;
+```
+
+Every record carrying exactly this name. Names are not unique in the
+datasets, so callers that need certainty check for a single result.
+
+### Functions and components
+
+<a id="api-applybiblenotecolorscheme"></a>
+
+#### `applyBibleNoteColorScheme()`
+
+Applies a colour scheme to `body` (default `document.body`): toggles the
+`playground-theme-dark` / `playground-theme-light` classes and sets
+`data-bs-theme`, so Bootstrap's own components follow. Prefer
+`BibleNote#setColorScheme` on a mounted editor; this is the bare DOM step.
+
+```ts
+function applyBibleNoteColorScheme(mode: BibleNoteColorScheme, body?: HTMLElement): void;
+```
+
+<a id="api-biblenotesettings"></a>
+
+#### `BibleNoteSettings()`
+
+The editor's settings panel — a gear button that opens the switches (Dark
+Mode, Table Of Contents, …). Pass it to `render` as `options.settings`;
+settings persist through the storage manager.
+
+```ts
+default function BibleNoteSettings({ setColorScheme, }: BibleNoteSettingsProps): JSX.Element;
+```
+
+<a id="api-clearbiblenotecolorscheme"></a>
+
+#### `clearBibleNoteColorScheme()`
+
+Removes the theme classes `applyBibleNoteColorScheme` added (leaves `data-bs-theme`).
+
+```ts
+function clearBibleNoteColorScheme(body?: HTMLElement): void;
+```
+
+<a id="api-createbrowserstoragemanager"></a>
+
+#### `createBrowserStorageManager()`
+
+A `BibleNoteStorageManager` backed by `window.localStorage`. Non-string
+values are stored as JSON; when `localStorage` is unavailable every call is
+a no-op.
+
+```ts
+function createBrowserStorageManager(): BibleNoteStorageManager;
+```
+
+<a id="api-getlookuprecordvalues"></a>
+
+#### `getLookupRecordValues()`
+
+The records of a raw dataset collection, whether it is an id-keyed object or
+a plain array; `[]` for anything else.
+
+```ts
+function getLookupRecordValues(value: unknown): Array<unknown>;
+```
+
+<a id="api-getmentionkjvname"></a>
+
+#### `getMentionKjvName()`
+
+The English name worth showing beside a record's own name, or `null` when
+there is nothing to add — an untranslated (KJV) dataset, or a record whose
+translated name is the English one anyway. Display it the way a Bible book
+reads in a translated UI: `លោកុប្បត្តិ (Genesis)`.
+
+```ts
+function getMentionKjvName(record: {
+    name: string;
+    kjvName: string | null;
+}): string | null;
+```
+
+<a id="api-normalizementionnametype"></a>
+
+#### `normalizeMentionNameType()`
+
+Normalizes a raw record `type` value to one of the known [`MentionNameType`](#api-mentionnametype)
+keys. Unrecognized or empty values fall back to `person`, the neutral default
+used for untyped name records.
+
+```ts
+function normalizeMentionNameType(type: string | null | undefined): MentionNameType;
+```
+
+<a id="api-parsementionlocationmatch"></a>
+
+#### `parseMentionLocationMatch()`
+
+Normalizes one raw dataset entry into a [`MentionLocationMatch`](#api-mentionlocationmatch), or
+returns `null` when it carries no usable identity.
+
+```ts
+function parseMentionLocationMatch(value: unknown): MentionLocationMatch | null;
+```
+
+<a id="api-parsementionlocationmatches"></a>
+
+#### `parseMentionLocationMatches()`
+
+Parses a whole dataset value (array or id-keyed object) into location records.
+
+```ts
+function parseMentionLocationMatches(value: unknown): Array<MentionLocationMatch>;
+```
+
+<a id="api-parsementionnamematch"></a>
+
+#### `parseMentionNameMatch()`
+
+Normalizes one raw dataset entry into a [`MentionNameMatch`](#api-mentionnamematch), or returns
+`null` when it carries no usable identity. The literal id `'id'` is rejected
+because some generated files carry a header row.
+
+```ts
+function parseMentionNameMatch(value: unknown): MentionNameMatch | null;
+```
+
+<a id="api-parsementionnamematches"></a>
+
+#### `parseMentionNameMatches()`
+
+Parses a whole dataset value (array or id-keyed object) into name records.
+
+```ts
+function parseMentionNameMatches(value: unknown): Array<MentionNameMatch>;
+```
+
+### Constants
+
+<a id="api-bible_note_storage_manager_keys"></a>
+
+#### `BIBLE_NOTE_STORAGE_MANAGER_KEYS`
+
+Every key the editor reads from its storage manager before it renders. A
+host-side store that needs to know its keys up front (to prefetch or migrate
+them) can use this list.
+
+```ts
+const BIBLE_NOTE_STORAGE_MANAGER_KEYS: readonly ["lexical-playground-settings", "lexical-playground-editor-state", "lexical-playground-comments", "lexical-playground-comments-panel-open", "lexical-playground-block-text-links", "lexical-playground-read-only-mode", "lexical-playground-insert-character-picker", "lexical-playground-editor-zoom-percent"]
+```
+
+<a id="api-editor_state_local_storage_key"></a>
+
+#### `EDITOR_STATE_LOCAL_STORAGE_KEY`
+
+The storage key of the note itself. The editor never hands this key to the
+host's `storageManager`: reads and writes of it go to `loadData` / `saveData`
+instead.
+
+```ts
+const EDITOR_STATE_LOCAL_STORAGE_KEY = "lexical-playground-editor-state"
+```
+
+### Types
+
+<a id="api-biblenotecolorscheme"></a>
+
+#### `BibleNoteColorScheme`
+
+The editor's two colour schemes.
+
+```ts
+type BibleNoteColorScheme = 'dark' | 'light';
+```
+
+<a id="api-biblenotefooteractionbutton"></a>
+
+#### `BibleNoteFooterActionButton`
+
+A host-supplied button in the editor's footer.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | yes | Unique per editor; adding a button with an existing id replaces it in place. |
+| `description` | `string` | no | What the button does. Used as the button's tooltip when the button element has no `title` of its own. |
+| `shortcutKey` | `string` | no | A keyboard shortcut that clicks the button from anywhere in the page, written as modifiers plus one key joined by `+`: `"Ctrl+Shift+K"`, `"Cmd+Shift+K"`, `"Alt+Shift+K"` (`Ctrl`/`Control`, `Cmd`/`Command`/`Meta`, `Alt`/`Option`, `Shift`). It is appended to the tooltip and set as `aria-keyshortcuts`. |
+| `children` | `ReactNode` | yes | The button itself, normally a single `<button>`. When it is a single plain element, the editor adds the tooltip and `aria-keyshortcuts` to it. |
+
+<a id="api-biblenotefooteractionbuttonplacement"></a>
+
+#### `BibleNoteFooterActionButtonPlacement`
+
+Which side of the built-in footer buttons a host button sits on.
+
+```ts
+type BibleNoteFooterActionButtonPlacement = 'before' | 'after';
+```
+
+<a id="api-biblenotefooteractionbuttons"></a>
+
+#### `BibleNoteFooterActionButtons`
+
+The host footer buttons on each side of the built-in ones, in order.
+
+```ts
+type BibleNoteFooterActionButtons = Readonly<{
+    before: ReadonlyArray<BibleNoteFooterActionButton>;
+    after: ReadonlyArray<BibleNoteFooterActionButton>;
+}>;
+```
+
+<a id="api-biblenoteprops"></a>
+
+#### `BibleNoteProps`
+
+Everything `new BibleNote(props)` needs from the host application.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `namesLookupManager` | `NamesLookupManager` | yes | The person dataset behind `@` mentions, hover cards, the advanced panel and the lookup panel. Build it with `NamesLookupManager.fromRawDataset`. |
+| `locationsLookupManager` | `LocationsLookupManager` | yes | The place dataset behind `#` mentions, hover cards, the advanced panel and the lookup panel. Build it with `LocationsLookupManager.fromRawDataset`. |
+| `getLangCode` | `(text: string) => string` | yes | Returns the language code of a piece of text (`'en'` for English). Used to pick a font for pasted Bible text and Excalidraw text: when it returns a code other than `'en'`, the editor switches to the first font in `editorExtraFontFamilies` registered for that language. |
+| `editorExtraFontFamilies` | `ReadonlyArray<ExtraFontFamilyOption>` | yes | Fonts added to the toolbar's font menu and to Excalidraw, as `[fontFamily, languageCode]` pairs. The host must load the font faces itself; pass `[]` for the built-in fonts only. |
+| `excalidrawLibraryItems` | `LibraryItems` | no | Extra Excalidraw library items, offered next to the bundled Christian library. |
+| `excalidrawClearLibrariesFileList` | `() => void` | no | Forgets every Excalidraw library file `excalidrawSaveLibrariesFile` stored. |
+| `excalidrawLoadLibrariesFileList` | `() => string[]` | no | Returns the Excalidraw library files saved earlier (each a serialized library JSON string); read each time the Excalidraw editor opens. |
+| `excalidrawSaveLibrariesFile` | `(librariesFile: string) => void` | no | Persists a library the user imported in Excalidraw (a serialized library JSON string) so `excalidrawLoadLibrariesFileList` can return it next time. |
+| `stickyNoteExtraFontFamilies` | `ReadonlyArray<string>` | yes | Extra CSS font-family values offered in the sticky-note font picker, e.g. `'"Fasthand"'`. Pass `[]` for none. |
+| `storageManager` | `BibleNoteStorageManager` | yes | Stores every piece of editor state except the note itself: settings, comments, read-only mode, zoom, panel state. `createBrowserStorageManager()` keeps them in `localStorage`. The keys it receives are listed in `BIBLE_NOTE_STORAGE_MANAGER_KEYS`. |
+| `saveData` | `(data: string) => Promise<void> \| void` | yes | Saves the note: called with the serialized editor state (a JSON string) on every change to the document — the same string `BibleNote#content` returns. Called with `''` when the stored note could not be parsed and is discarded. |
+| `loadData` | `() => Promise<string \| null> \| string \| null` | yes | Loads the note saved by `saveData`. Return `null` or `''` for an empty editor. |
+| `resolveFilePath` | `FilePathResolver` | no | Maps a media file the user dropped or picked to a path or URL to store in the note instead of embedding it as a data URL. Return `null` to fall back to embedding. In a browser there is usually no path to give; in Electron this is where a file's location on disk comes from. |
+| `revealFile` | `FileRevealer` | no | Shows a media file's location to the user (e.g. Electron's `shell.showItemInFolder`). When provided, a selected image, video, audio or PDF whose source is a local file path gets a reveal button. |
+| `print` | `() => void` | no | Replaces the footer Print button's built-in printing, which prints the note laid out at the selected page size. |
+| `isOnApp` | `boolean` | no | The editor is embedded in an app rather than a web page: hides the footer's **Share as Link** and **Convert From Markdown** buttons. Defaults to `false`. |
+| `isMinimize` | `boolean` | no | Compact footer: folds Import, Export and Editor Information into a **More actions** menu. Defaults to `false`. |
+| `shortToVerseData` | `(shortText: string) => Promise<MentionedBibleDataType \| null>` | no | Resolves a short verse key (`GEN 1:1`) to its displayed title and text. Used for verse lists in mention panels and in the Word export's References appendix. Without it, those lists show the bare key. |
+| `verseFullTextToListShorts` | `(fullText: string) => Promise<string[] \| null>` | no | Lists the short verse keys a verse mention covers, given its full text. Enables the people and places mentioned in a verse, shown in that verse's advanced panel and in the Word export. |
+| `changeBibleKey` | `(event: React.MouseEvent<HTMLButtonElement>, verseFullText: string) => Promise<MentionedBibleDataType \| null>` | no | Offers the same verse in another Bible version. When provided, the version label in a verse's advanced panel becomes a button; resolve to the verse in the chosen version to open it in a new panel, or `null` to do nothing. |
+
+<a id="api-biblenoterenderoptions"></a>
+
+#### `BibleNoteRenderOptions`
+
+Options for `BibleNote#render`.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `settings` | `ReactNode` | no | The settings panel to mount, normally `<BibleNoteSettings />`. Omit it and the editor has no settings panel. |
+| `settingsContainerElement` | `Element \| DocumentFragment` | no | Where to portal the `settings` panel. Without it the panel renders inside the editor's own layout. |
+
+<a id="api-biblenotesettingsprops"></a>
+
+#### `BibleNoteSettingsProps`
+
+Props of `BibleNoteSettings`.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `setColorScheme` | `(mode: BibleNoteColorScheme) => void` | yes | Called when the Dark Mode switch flips. Pass `(mode) => bibleNote.setColorScheme(mode)` so the instance stays in step. |
+
+<a id="api-biblenotestoragemanager"></a>
+
+#### `BibleNoteStorageManager`
+
+Where the editor keeps its own state — settings, comments, read-only mode,
+zoom, panel state — as string values under the keys in
+`BIBLE_NOTE_STORAGE_MANAGER_KEYS`. The note itself goes through
+`loadData` / `saveData` instead. Every key is read once, before the editor
+first renders; writes are fire-and-forget.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `setSetting` | `setSetting(key: string, value: unknown): Promise<void>` | yes | Stores `value` (a string, or a value to `JSON.stringify`) under `key`. |
+| `getSetting` | `getSetting<T = unknown>(key: string): Promise<T \| null>` | yes | The value stored under `key`, or `null` when there is none. |
+| `deleteSetting` | `deleteSetting(key: string): Promise<void>` | yes | Removes `key`. |
+
+<a id="api-extrafontfamilyoption"></a>
+
+#### `ExtraFontFamilyOption`
+
+A host font added to the editor: `[fontFamily, languageCode]`, e.g.
+`['Battambang', 'km']`. The language code is what `getLangCode` returns
+for text that should use this font.
+
+```ts
+type ExtraFontFamilyOption = readonly [
+    fontFamily: string,
+    language: string
+];
+```
+
+<a id="api-filepathresolver"></a>
+
+#### `FilePathResolver`
+
+Maps a media file to the path or URL the note should reference. Return
+`null` (or throw) to let the editor embed the file as a data URL instead.
+
+```ts
+type FilePathResolver = (file: File, context: FilePathResolverContext) => Promise<string | null> | string | null;
+```
+
+<a id="api-filepathresolvercontext"></a>
+
+#### `FilePathResolverContext`
+
+Context passed to a `FilePathResolver`.
+
+```ts
+type FilePathResolverContext = Readonly<{
+    source: FilePathSource;
+}>;
+```
+
+<a id="api-filepathsource"></a>
+
+#### `FilePathSource`
+
+How a media file reached the editor: dropped/pasted, or picked in the media dialog.
+
+```ts
+type FilePathSource = 'drop' | 'file-input';
+```
+
+<a id="api-filerevealer"></a>
+
+#### `FileRevealer`
+
+Shows a local media file to the user, e.g. in the system file manager.
+
+```ts
+type FileRevealer = (filePath: string) => Promise<void> | void;
+```
+
+<a id="api-fontfamilyoption"></a>
+
+#### `FontFamilyOption`
+
+A font in the toolbar's font menu: `[fontFamily, label, languageCode]`.
+
+```ts
+type FontFamilyOption = readonly [
+    fontFamily: string,
+    label: string,
+    language: string
+];
+```
+
+<a id="api-locationslookupmanagerdatamap"></a>
+
+#### `LocationsLookupManagerDataMap`
+
+Location datasets keyed by language code, e.g. `{ en: …, km: … }`.
+
+```ts
+type LocationsLookupManagerDataMap = {
+    [langCode: string]: LocationsLookupManagerLangData;
+};
+```
+
+<a id="api-locationslookupmanagerlangdata"></a>
+
+#### `LocationsLookupManagerLangData`
+
+One language's location dataset, as `LocationsLookupManager`'s constructor takes it.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `records` | `ReadonlyArray<MentionLocationMatch>` | yes | The normalized records (see `parseMentionLocationMatches`). |
+| `verseLocationsMap` | `VerseRecordIdsMap` | no | Short verse key (e.g. `"EXO 6:23"`) to the ids of the locations it mentions. |
+
+<a id="api-lookupmanagerstyle"></a>
+
+#### `LookupManagerStyle`
+
+Extra inline style the UI applies wherever it renders one manager's records —
+the mention popup and hover card, the advanced panel, and the lookup list.
+Its purpose is a dataset-wide `fontFamily` for a language the editor's own
+font does not cover; anything a `style` attribute accepts works.
+
+```ts
+type LookupManagerStyle = CSSProperties;
+```
+
+<a id="api-lookuppaginationoptions"></a>
+
+#### `LookupPaginationOptions`
+
+Options for the `…Pagination` searches.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `query` | `string` | no | Search text; empty or omitted lists every record in importance order. |
+| `lang` | `string` | no | Language to search; falls back to `defaultLang` when absent or unknown. |
+| `page` | `number` | no | 1-based page number, clamped to the available pages. Defaults to 1. |
+| `pageSize` | `number` | no | Records per page (at least 1). Defaults to 20. |
+
+<a id="api-lookuppaginationresult"></a>
+
+#### `LookupPaginationResult`
+
+One page of search results.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `lang` | `string` | yes | The language actually searched. |
+| `totalRecords` | `number` | yes | Matches across all pages. |
+| `page` | `number` | yes | The page returned, after clamping. |
+| `totalPages` | `number` | yes | Number of pages; at least 1, even with no matches. |
+| `pageSize` | `number` | yes |  |
+| `records` | `Array<TRecord>` | yes | This page's records. |
+
+<a id="api-lookupsearchoptions"></a>
+
+#### `LookupSearchOptions`
+
+Options for `searchNames` / `searchLocations`.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `lang` | `string` | no | Language to search; falls back to `defaultLang` when absent or unknown. |
+| `limit` | `number` | no | Maximum number of results; all matches when omitted. |
+
+<a id="api-mentionlocationcoordinates"></a>
+
+#### `MentionLocationCoordinates`
+
+WGS 84 decimal degrees.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `latitude` | `number` | yes |  |
+| `longitude` | `number` | yes |  |
+
+<a id="api-mentionlocationlink"></a>
+
+#### `MentionLocationLink`
+
+An external reference about a location; same shape as [`MentionNameLink`](#api-mentionnamelink).
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `type` | `string` | yes |  |
+| `url` | `string` | yes |  |
+
+<a id="api-mentionlocationmatch"></a>
+
+#### `MentionLocationMatch`
+
+One place/location record — what `LocationsLookupManager` searches and
+returns, and what a `#` mention shows.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | yes | Stable record id; mentions in saved notes refer to it. |
+| `name` | `string` | yes | The name as printed in this dataset's Bible text. |
+| `kjvName` | `string \| null` | yes | The KJV English name; see [`MentionNameMatch.kjvName`](#api-mentionnamematch). |
+| `oldName` | `string \| null` | yes | A former name, searchable like `name`; `null` when none. |
+| `title` | `string` | yes | A one-line identification, with inline reference links like [`MentionNameMatch.title`](#api-mentionnamematch). |
+| `description` | `string` | yes | A paragraph about the place, with the same inline links. |
+| `type` | `string` | yes | The kind of place, e.g. `city`, `region`, `mountain`. |
+| `relatedLocations` | `Array<string>` | yes | Ids of other location records. |
+| `modernIdentification` | `string \| null` | yes | The modern site or name, when known. |
+| `coordinates` | `MentionLocationCoordinates \| null` | yes |  |
+| `verses` | `Array<string>` | yes | Short verse keys where the Bible prints the name; ranges are collapsed. |
+| `links` | `Array<MentionLocationLink>` | yes | External references (Wikipedia, Easton's, New Advent…). |
+| `wikipedia` | `string \| null` | yes | The record's Wikipedia URL, or `null`. |
+| `uncertainty` | `boolean` | yes | `true` when the identification or location is uncertain. |
+| `matterRange` | `number` | yes | Importance rank on the same scale as [`MentionNameMatch.matterRange`](#api-mentionnamematch). |
+
+<a id="api-mentionlocationpreview"></a>
+
+#### `MentionLocationPreview`
+
+A location record as the mention UI displays it: the dataset record, or a
+fallback built from what a mention in the note carries. `id` is `null` when
+the mention has no record id.
+
+```ts
+type MentionLocationPreview = Omit<MentionLocationMatch, 'id'> & {
+    id: string | null;
+};
+```
+
+<a id="api-mentionnamelink"></a>
+
+#### `MentionNameLink`
+
+An external reference about a record.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `type` | `string` | yes | The source, e.g. `wikipedia`, `easton`, `newadvent`. |
+| `url` | `string` | yes |  |
+
+<a id="api-mentionnamematch"></a>
+
+#### `MentionNameMatch`
+
+One person/name record — what `NamesLookupManager` searches and returns, and
+what an `@` mention shows. Fields holding other records (`parents`,
+`locations`, …) hold their ids; resolve them with `getRecordsByIds`.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | yes | Stable record id; mentions in saved notes refer to it. |
+| `name` | `string` | yes | The name as printed in this dataset's Bible text. |
+| `kjvName` | `string \| null` | yes | The KJV English name, carried only by translated datasets (the km-BFBS mirror and any future one) where `name` holds the translated form. `null` on the KJV dataset itself, whose `name` already is the English one. The lookup managers index it alongside `name`, so a translated dataset stays searchable by its English name, and the UI shows it beside the translated name the way a Bible book reads "លោកុប្បត្តិ (Genesis)". |
+| `oldName` | `string \| null` | yes | A former name (e.g. Abram for Abraham), searchable like `name`; `null` when none. |
+| `title` | `string` | yes | A one-line identification ("prophet who led Israel out of Egypt"). Like `description`, it may carry inline reference links: `[Egypt](location-id://…)`, `[Amram](name-id://…)`, `[Genesis 1:1](verse-key://GEN 1:1)`, `[Genesis](book-key://GEN)`, `[Genesis 14](chapter-key://GEN 14)`. |
+| `description` | `string` | yes | A paragraph about the person, with the same inline links as `title`. |
+| `gender` | `string` | yes | `male`, `female` or `unknown` in the generated datasets; `''` when absent. |
+| `age` | `string` | yes | Age as stated in the text (e.g. `120 years`); `''` when unknown. |
+| `years` | `Array<MentionNameYearRange>` | yes | Dated spans such as a king's reign; usually empty. |
+| `locations` | `Array<string>` | yes | Ids of location records tied to the person. |
+| `spouses` | `Array<string>` | yes | Ids of name records. |
+| `children` | `Array<string>` | yes | Ids of name records. |
+| `parents` | `Array<string>` | yes | Ids of name records. |
+| `siblings` | `Array<string>` | yes | Ids of name records. |
+| `cousin` | `Array<string>` | yes | Ids of name records. |
+| `type` | `string` | yes | The raw type; `normalizeMentionNameType` maps it to a [`MentionNameType`](#api-mentionnametype). |
+| `verses` | `Array<string>` | yes | Short verse keys where the Bible prints the name, e.g. `GEN 1:1` or a collapsed range `1SA 17:1-4` (so the array length is not a verse count). |
+| `links` | `Array<MentionNameLink>` | yes | External references (Wikipedia, Easton's, New Advent…). |
+| `wikipedia` | `string \| null` | yes | The record's Wikipedia URL, or `null`. |
+| `matterRange` | `number` | yes | How much the record matters, ascending: 0 is the most important on this dataset's scale. Orders every listing and breaks ties in search. Records without a rank get `Infinity` and sort to the very end. |
+
+<a id="api-mentionnamepreview"></a>
+
+#### `MentionNamePreview`
+
+A name record as the mention UI displays it: the dataset record, or a
+fallback built from what a mention in the note carries when the dataset has
+no such record. `id` is `null` when the mention has no record id.
+
+```ts
+type MentionNamePreview = Omit<MentionNameMatch, 'id'> & {
+    id: string | null;
+};
+```
+
+<a id="api-mentionnametype"></a>
+
+#### `MentionNameType`
+
+The set of name "types" carried by biblical name records. Each type maps to a
+distinct icon so mentions can be told apart at a glance in the editor pills,
+the typeahead menu, the hover card, and the advanced panel.
+
+When adding a new type here, add a matching `data-lexical-mention-name-type`
+mask rule in `AppComp.scss` so the editor pill icon stays in sync, and an
+entry in `NAME_TYPE_ICON_CLASS` in `plugins/MentionNamePlugin/nameTypeIcons`.
+
+```ts
+type MentionNameType = 'person' | 'concept' | 'place' | 'group' | 'deity' | 'month' | 'supernatural' | 'life' | 'unknown';
+```
+
+<a id="api-mentionnameyearrange"></a>
+
+#### `MentionNameYearRange`
+
+A dated span in a person's life, e.g. a reign.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `type` | `string` | yes | What the span is, e.g. `reign` or `coregency`. |
+| `start` | `number` | yes |  |
+| `end` | `number` | yes |  |
+
+<a id="api-nameslookupmanagerdatamap"></a>
+
+#### `NamesLookupManagerDataMap`
+
+Name datasets keyed by language code, e.g. `{ en: …, km: … }`.
+
+```ts
+type NamesLookupManagerDataMap = {
+    [langCode: string]: NamesLookupManagerLangData;
+};
+```
+
+<a id="api-nameslookupmanagerlangdata"></a>
+
+#### `NamesLookupManagerLangData`
+
+One language's name dataset, as `NamesLookupManager`'s constructor takes it.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `records` | `ReadonlyArray<MentionNameMatch>` | yes | The normalized records (see `parseMentionNameMatches`). |
+| `versePersonsMap` | `VerseRecordIdsMap` | no | Short verse key (e.g. `"EXO 6:23"`) to the ids of the names it mentions. |
+
+<a id="api-nameslookuppaginationoptions"></a>
+
+#### `NamesLookupPaginationOptions`
+
+`LookupPaginationOptions` plus a name-type filter.
+
+```ts
+type NamesLookupPaginationOptions = LookupPaginationOptions & {
+    /** Only records of this type. */
+    type?: MentionNameType;
+};
+```
+
+<a id="api-nameslookupsearchoptions"></a>
+
+#### `NamesLookupSearchOptions`
+
+`LookupSearchOptions` plus a name-type filter.
+
+```ts
+type NamesLookupSearchOptions = LookupSearchOptions & {
+    /** Only records of this type; applied before `limit`. */
+    type?: MentionNameType;
+};
+```
+
+<a id="api-nametypecount"></a>
+
+#### `NameTypeCount`
+
+How many records of one name type a dataset holds.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `type` | `MentionNameType` | yes |  |
+| `count` | `number` | yes |  |
+
+<a id="api-verserecordidsmap"></a>
+
+#### `VerseRecordIdsMap`
+
+```ts
+type VerseRecordIdsMap = Record<string, ReadonlyArray<string>>;
+```
+
+### Supporting types
+
+Not exported, but used by the public signatures above — shown so every shape a host has to produce or consume is spelled out.
+
+#### `LibraryItems`
+
+```ts
+type LibraryItems = readonly any[];
+```
+
+#### `MentionedBibleDataType`
+
+A Bible verse as the host renders it: a title line plus the full text.
+
+| Property | Type | Required | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | yes | The verse reference as displayed, e.g. `(KJV) Genesis 1:1`. |
+| `fullText` | `string` | yes | The title line followed by the verse lines, in the same shape the editor accepts when Bible text is pasted after `^`: `(KJV) Genesis 1:1\n(1): In the beginning…`. |
+| `style` | `CSSProperties` | no | Extra CSS for this verse's text, e.g. a font for a non-Latin version. |