# What changed in @embedpdf/plugin-search

> 45 changes in @embedpdf/plugin-search 3 from its official release notes, upgrade guides and advisories: 15 breaking, 2 security, 22 new APIs and options. Each one cited. Sources checked 2026-11-07. HTML: https://unstale.sh/npm/@embedpdf/plugin-search/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## @embedpdf/plugin-search 3

### Breaking changes

- Replaces activeIndex as the state field for the active hit index. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- The state field is now named activeHitIndex. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- highlight.blendMode uses engine-core's BlendMode instead of the SearchBlendMode copy. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- findAll refuses a snippets request with permission-denied naming doc.text.copy, without asking the engine; search and findAll also require doc.text.search. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Lists pages with hits in document order, which changes when a page is moved. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Token methods that return promises reject with not-ready in every framework when no document is open, instead of throwing. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- The progress event is now named onProgressChanged. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Replaces onProgress and carries hitCount, pagesSearched, and pageCount whenever progress changes. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- refresh replaces rerun and resolves nothing; callers read results from state and events. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- The search operation formerly named rerun is now named refresh. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- search is awaitable and resolves with status and hitCount; it accepts a signal and a from page, and refuses without doc.text.search permission. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- The duplicate type is gone; highlight.blendMode uses engine-core's BlendMode. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Replaces SearchPluginConfig as the search configuration type. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- The configuration type is now named SearchConfig. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Declares search state for every framework, with activeHitIndex replacing activeIndex. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)

### Security

- Lets hosts gate search and snippet controls using the session's text-search and text-copy permissions. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Callers can request snippets with a boolean option; permission checks match whether result text will be returned. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)

### New APIs and options

- Search results expose a precomputed envelope that reveal passes directly to the stage. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Cancels search while keeping the hits found so far. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- A bundle-safe entry exposes search token, query validation, results, and capability types without scan, effect, or plugin wiring. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Selects the starting page; it accepts a PageRef or index, and a page absent from the document causes search to reject with not-found. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Returns the hit count, optionally for a page identified by PageRef or index. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Reads live search settings. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Accepts a hit itself as well as its index; stale hits are matched by covered characters, while hits absent from current results return null without changing state. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Search live settings include highlight options color, activeColor, and blendMode. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Progress reports the total page count. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Search hits carry a PageRef, and hitsForPage and startPage take a PageRef. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Progress reports the number of pages searched. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Resets live search settings. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Search live settings include reveal options anchor and behavior. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Provides defaults over which searchPlugin registers live settings. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- SearchMode is exported as a search type. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Registers live search settings over SEARCH_DEFAULTS, available before any document opens. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Names the search state type used by searchState and returned by useSearchState(). (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Search-hit geometry is represented as canonical TextSegment ranges, alongside a precomputed bounds envelope. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- search, refresh, and findAll accept an AbortSignal; cancellation stops engine work on the running slice. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Search-hit ranges are exposed as start and count. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- TextSegment is exported as a search type. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Updates live search settings across every document; reveal changes apply to the next nextHit(). (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)

### Behavior and default changes

- A search without from starts at the Stage's current page through its PageRef. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- The rebuilt plugin uses budgeted engine search, converts result geometry to viewer coordinates, prioritizes visible pages, and reveals the active result through the stage. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Lists hits with an optional filter; a page argument can be a PageRef or index, and a deleted page returns an empty list. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)

### Fixes and other changes

- Search result character ranges can be passed to selection and markup flows without offset drift. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Search result character offsets stay aligned with selection character space for non-printing and supplementary-plane characters, avoiding offset drift in selection and markup flows. (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)
- Search follows the stage contract and reveals with reveal(ref). (3.0.0) — [release notes](https://github.com/embedpdf/embed-pdf-viewer/blob/7c93291c80c6f784675c5a04589ea9a3a62f11ed/packages/plugin/search/CHANGELOG.md#300)