From 4b270ba07871d1bd23b14d6bd1800a549d5937c1 Mon Sep 17 00:00:00 2001
From: Chris Taylor <forgetso86@gmail.com>
Date: Mon, 21 Sep 2026 23:17:00 +0100
Subject: [PATCH 1/2] Count and replace from one set of instances (#135)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Counting measured an element's innerHTML as a string; replacing drove a
TreeWalker. They disagreed, and the disagreement was visible: a page with a
match in a script and one in a style reported 2 matches and replaced 4, so
Replace Next went 2 -> 1 -> 1 -> 1 -> 0, appearing to stall on the matches the
count had never admitted to.

The two cannot be reconciled by patching either side. Making the count read the
unfiltered original — so it stops missing the script and the style — takes the
invariant suite from 4 failures to 13, because the count then disagrees about
hidden text and input values instead. An innerHTML string cannot express scope:
the text of a hidden element, of a script and of an input are all in it,
whether or not any of them is in scope for this search.

So collect the matches once, from nodes rather than strings, and have both
operations read the list:

  text       a text node, which covers prose and script and style contents
  attribute  an attribute value, in scope only when replacing HTML
  markup     a match that exists only in the tags, e.g. searching for "<p"

count is the size of the list; Replace All walks it; Replace Next takes the
first entry and replaces exactly one occurrence. The count cannot drift from
what replace will do because there is one source of truth.

Writing through the node holding the match fixes two further things:

- A replacement no longer rewrites an ancestor's innerHTML, which destroyed and
  recreated every node beneath it, taking the page's listeners, selection,
  focus and framework DOM identity with it.
- "Hidden content" now means something in HTML mode. The known limitation
  recorded in the invariant tests — that Replace HTML rewrote hidden text
  regardless — is fixed, and the test that pinned it now asserts the opposite.

Markup matches keep working. Anything in an element's innerHTML that the text
and attribute instances cannot explain is charged as a surplus to the innermost
element that can account for it, walking in reverse document order. An element
whose subtree holds anything out of scope is never given one, since its
innerHTML describes that content too and rewriting it would drag it back in.

Deletes replaceInner, nodesUnder, isIgnored, equivalentInIgnoredElements,
containsAncestor and getHiddenElements: the clone-and-filter machinery existed
only to keep unwanted subtrees out of an innerHTML rewrite, and nothing is
rewritten wholesale any more.

787 tests, 16 of them new. The invariant matrix gains "each Replace Next takes
exactly one match off the count", which now holds for every page shape and
option set.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/searchreplace.invariants.test.ts | 104 +++++++--
 src/searchreplace.ts                 | 309 ++++-----------------------
 src/searchreplace/instances.test.ts  | 177 +++++++++++++++
 src/searchreplace/instances.ts       | 273 +++++++++++++++++++++++
 4 files changed, 584 insertions(+), 279 deletions(-)
 create mode 100644 src/searchreplace/instances.test.ts
 create mode 100644 src/searchreplace/instances.ts

diff --git a/src/searchreplace.invariants.test.ts b/src/searchreplace.invariants.test.ts
index 353f33c..e08a024 100644
--- a/src/searchreplace.invariants.test.ts
+++ b/src/searchreplace.invariants.test.ts
@@ -143,6 +143,83 @@ describe.each(OPTION_SETS)('$name', ({ options }) => {
     })
 })
 
+describe.each(OPTION_SETS)('$name', ({ options }) => {
+    describe.each(PAGES)('$name', ({ html }) => {
+        test('each Replace Next takes exactly one match off the count', async () => {
+            // The popup shows the remaining matches, so a press that leaves the number where it
+            // was reads as "I pressed it and nothing happened". Counting and replacing have to
+            // agree about what is a match for this to hold.
+            document.body.innerHTML = html
+            const nextOnly = { ...options, replaceAll: false }
+            let remaining = (await run('count', nextOnly)).searchReplaceResult.count.original
+
+            // Bounded so a count that refuses to fall fails the expectation rather than hanging
+            for (let press = 0; remaining > 0 && press < 20; press++) {
+                await run('searchReplace', nextOnly)
+                const now = (await run('count', nextOnly)).searchReplaceResult.count.original
+                expect(now).toBe(remaining - 1)
+                remaining = now
+            }
+
+            expect(remaining).toBe(0)
+        })
+    })
+})
+
+describe('Replace HTML counts everything it replaces', () => {
+    // Replace HTML means the HTML: script and style contents and attribute values are all in
+    // scope, and are all replaced. The count has to say so, or Replace Next appears to stall on
+    // the matches the count never knew about.
+    const MIXED =
+        '<div>' +
+        '<p>European</p>' +
+        '<script type="application/json">{"region":"European"}</script>' +
+        '<style>.European { color: red; }</style>' +
+        '<a href="/European-news">link</a>' +
+        '</div>'
+
+    test('counts the match in visible text, a script, a style and an attribute', async () => {
+        document.body.innerHTML = MIXED
+
+        const { count } = (await run('count', { replaceHTML: true })).searchReplaceResult
+
+        expect(count.original).toBe(4)
+    })
+
+    test('counts only the visible text when Replace HTML is off', async () => {
+        document.body.innerHTML = MIXED
+
+        const { count } = (await run('count', {})).searchReplaceResult
+
+        expect(count.original).toBe(1)
+    })
+
+    test('replaces every one of them', async () => {
+        document.body.innerHTML = MIXED
+
+        await run('searchReplace', { replaceHTML: true })
+
+        expect(document.body.innerHTML).not.toContain(TERM)
+        expect((await run('count', { replaceHTML: true })).searchReplaceResult.count.original).toBe(0)
+    })
+})
+
+describe('replacing leaves the rest of the page alone', () => {
+    test('a match in one element does not recreate its siblings', async () => {
+        // Assigning to an ancestor's innerHTML destroys and recreates every node beneath it,
+        // which loses focus, selection, event listeners and the DOM identity frameworks hold on
+        // to. Only the element holding the match should be touched.
+        document.body.innerHTML = '<div><p id="target">European</p><p id="untouched">other text</p></div>'
+        const untouched = document.getElementById('untouched')
+        const untouchedText = untouched?.firstChild
+
+        await run('searchReplace', { replaceHTML: true })
+
+        expect(document.getElementById('untouched')).toBe(untouched)
+        expect(untouched?.firstChild).toBe(untouchedText)
+    })
+})
+
 describe('the count the popup displays', () => {
     test('is never negative for a page mixing visible and hidden matches', async () => {
         // The exact shape behind the "-2 matches" report: one visible match and two hidden ones,
@@ -156,23 +233,26 @@ describe('the count the popup displays', () => {
         expect(count.original - count.replaced).toBeGreaterThanOrEqual(0)
     })
 
-    test('KNOWN LIMITATION: Replace HTML also rewrites hidden text', async () => {
-        // Replacing in HTML assigns to the innerHTML of the outermost matching element, which
-        // rewrites its entire subtree — hidden descendants, and the contents of script and
-        // style tags, along with it. So "Hidden content" has no effect in this mode.
-        //
-        // Narrowing the replacement to only fully visible elements was tried and made things
-        // worse: on a real page nearly every container holds a script or a hidden element, so
-        // text sitting directly inside those containers stopped being replaced at all.
-        // Fixing it properly means preserving the excluded subtrees across the rewrite rather
-        // than skipping their ancestors.
-        //
-        // This test pins the current behaviour so the change is visible when it is addressed.
+    test('Replace HTML leaves hidden text alone unless Hidden content is set', async () => {
+        // This was a known limitation for as long as replacing assigned to the innerHTML of the
+        // outermost matching element: that rewrote the entire subtree, hidden descendants
+        // included, so "Hidden content" had no effect in this mode. Replacing through the node
+        // holding the match makes the option mean what it says.
         document.body.innerHTML =
             '<div><p id="shown">European</p><p id="gone" style="display: none;">European</p></div>'
 
         await run('searchReplace', { replaceHTML: true })
 
+        expect(document.getElementById('shown')?.textContent).toBe('American')
+        expect(document.getElementById('gone')?.textContent).toBe('European')
+    })
+
+    test('Replace HTML does rewrite hidden text when Hidden content is set', async () => {
+        document.body.innerHTML =
+            '<div><p id="shown">European</p><p id="gone" style="display: none;">European</p></div>'
+
+        await run('searchReplace', { replaceHTML: true, hiddenContent: true })
+
         expect(document.getElementById('shown')?.textContent).toBe('American')
         expect(document.getElementById('gone')?.textContent).toBe('American')
     })
diff --git a/src/searchreplace.ts b/src/searchreplace.ts
index b16236c..3496b6f 100644
--- a/src/searchreplace.ts
+++ b/src/searchreplace.ts
@@ -9,21 +9,21 @@ import {
     SearchReplaceResult,
 } from './types/index'
 import {
-    copyElementAndRemoveSelectedElements,
-    elementIsVisible,
+    applyInstance,
+    collectInstances,
+    countInstances,
+    instanceElement,
+    orderForReplacement,
+} from './searchreplace/instances'
+import { getFlags, getSearchPattern } from './regex'
+import { getHints } from './hints'
+import {
     getInitialIframeElement,
     getInputElements,
     getRespondingIframes,
     getSearchableIframes,
     inIframe,
-    isBlobIframe,
-    isEditable,
-    isHidden,
-    isInputElement,
-    isWYSIWYGEditorIframe,
 } from './elements'
-import { getFlags, getSearchPattern } from './regex'
-import { getHints } from './hints'
 import { notEmpty } from './util'
 
 function newSearchReplaceCount() {
@@ -222,22 +222,6 @@ function replaceInInput(
     return { searchReplaceResult, elementsChecked }
 }
 
-function containsAncestor(element: Element, results: Map<Element, SearchReplaceResult>): boolean {
-    // if element is not the body, check if the body is in the results
-    if (element.tagName !== 'BODY' && results.has(document.body)) {
-        return true
-    }
-
-    let ancestor = element.parentElement
-    while (ancestor) {
-        if (results.has(ancestor)) {
-            return true
-        }
-        ancestor = ancestor.parentElement
-    }
-    return false
-}
-
 function countOccurrences(el: HTMLElement, config: SearchReplaceConfig): number {
     let target = getValue(el, config)
 
@@ -325,179 +309,6 @@ function getElementFromNode(node: Node): Element | undefined {
     return element
 }
 
-function isIgnored(ignoredElements: Set<Element>, node: Node, hiddenContent: boolean, elementFilter: RegExp): number {
-    const toCheck = getElementFromNode(node)
-    // if there is no element, reject
-    if (!toCheck) {
-        return NodeFilter.FILTER_REJECT
-    }
-
-    // if a script or an iframe that is not a blob iframe, reject
-    if (toCheck.tagName.match(elementFilter) && !isBlobIframe(toCheck)) {
-        return NodeFilter.FILTER_REJECT
-    }
-    // if an ignored element, reject
-    if (ignoredElements.has(toCheck)) {
-        return NodeFilter.FILTER_REJECT
-    }
-
-    // if the equivalent of an ignored element (e.g. ignored are clones), reject
-    if (equivalentInIgnoredElements(ignoredElements, toCheck)) {
-        return NodeFilter.FILTER_REJECT
-    }
-
-    // if we're not checking hidden content and the element is hidden, reject
-    if (!hiddenContent) {
-        if (!elementIsVisible(toCheck as HTMLElement)) {
-            return NodeFilter.FILTER_REJECT
-        }
-    }
-
-    return NodeFilter.FILTER_ACCEPT
-}
-
-function nodesUnder(
-    document: Document,
-    element: Node,
-    config: SearchReplaceConfig,
-    searchReplaceResult: SearchReplaceResult,
-    elementsChecked: Map<Element, SearchReplaceResult>,
-    ignoredElements: Set<Element>
-) {
-    const nodeType = config.searchTarget === 'innerHTML' ? NodeFilter.SHOW_ELEMENT : NodeFilter.SHOW_TEXT
-    let node: Node | null
-    const walk = document.createTreeWalker(element, nodeType, {
-        acceptNode: (node) => {
-            // This doesn't work - child elements aren't removed
-            return isIgnored(ignoredElements, node, config.hiddenContent, config.elementFilter)
-        },
-    })
-    const walked = new Set<Node>()
-
-    while ((node = walk.nextNode())) {
-        if (!config.replace) {
-            break
-        }
-
-        if (walked.has(node)) {
-            continue
-        }
-        walked.add(node)
-        const nodeElement = getElementFromNode(node)
-
-        if (!nodeElement) {
-            continue
-        }
-
-        if (nodeElement.tagName.match(/INPUT|TEXTAREA/g)) {
-            // handled by replaceInInputs
-            continue
-        }
-
-        // Editable text is handled by replaceInInputs, so skip it here to avoid replacing twice.
-        // This previously compared `contentEditable` to the boolean `true`, but that property is
-        // a string ('true' | 'false' | 'inherit' | 'plaintext-only'), so the guard never fired.
-        // Nothing broke, because editable elements are also dropped from the cloned element and
-        // so land in `ignoredElements` — but that made this guard silently redundant rather than
-        // the safety net it reads as.
-        if (isEditable(nodeElement)) {
-            continue
-        }
-
-        if (nodeElement.tagName === 'WINDOW') {
-            continue
-        }
-        const oldValue = getValue(node, config)
-        const occurrences = oldValue.match(config.globalSearchPattern)
-
-        if (!occurrences) {
-            continue
-        }
-
-        if (!config.hiddenContent && isHidden(nodeElement, false)) {
-            continue
-        }
-
-        if (config.replace) {
-            const newValue = oldValue.replace(config.searchPattern, config.replaceTerm)
-            if (node && oldValue && oldValue !== newValue) {
-                // Do the replacement
-                const replaceResult = replaceInNodeOrElement(node, newValue, occurrences, config)
-                elementsChecked = updateResults(
-                    elementsChecked,
-                    node as Element,
-                    replaceResult.replaced,
-                    occurrences.length,
-                    replaceResult.replacementCount
-                )
-                searchReplaceResult.count.replaced += replaceResult.replacementCount
-                searchReplaceResult.replaced = replaceResult.replaced
-                // replaceInNodeOrElement() has already announced the change. Announcing it again
-                // here, once on the element and once on the node, made a single replacement look
-                // like three separate edits to any listener on the way up.
-                if (config.replaceNext && searchReplaceResult.replaced) {
-                    config.replace = false
-                    break
-                }
-            }
-        }
-    }
-
-    return { searchReplaceResult, elementsChecked }
-}
-
-function replaceInner(
-    config: SearchReplaceConfig,
-    document: Document,
-    originalElement: HTMLElement,
-    element: HTMLElement,
-    ignoredElements: Set<Element>,
-    searchReplaceResult: SearchReplaceResult,
-    elementsChecked: Map<Element, SearchReplaceResult>
-): ReplaceFunctionReturnType {
-    // continue if there is no inner searchTarget
-    if (!(config.searchTarget in element)) {
-        elementsChecked = updateResults(elementsChecked, element, false, 0, 0)
-        return { searchReplaceResult, elementsChecked }
-    }
-
-    // When replacing in HTML the whole of the original element's innerHTML is rewritten, hidden
-    // and filtered descendants included. The count therefore has to be taken from that same
-    // string: counting on the filtered clone reported fewer matches than were really replaced,
-    // and the popup displayed the difference as a negative number ("-2 matches").
-    const countTarget = config.replace && config.searchTarget === 'innerHTML' ? originalElement : element
-    const occurrences = countOccurrences(countTarget, config)
-    elementsChecked = updateResults(elementsChecked, element, false, occurrences, 0)
-
-    if (config.searchTarget === 'innerHTML') {
-        searchReplaceResult.count.original = searchReplaceResult.count.original + occurrences
-    } else if (config.searchTarget === 'innerText') {
-        // Skip elements whose ancestor was already counted: the ancestor's innerText already
-        // contained this element's text, so adding it again would double count.
-        // (The hiddenContent flag used to select between two identical branches here.)
-        if (!containsAncestor(element, elementsChecked)) {
-            searchReplaceResult.count.original = searchReplaceResult.count.original + occurrences
-        }
-    }
-
-    // cycle through nodes, replacing in text or the innerHTML
-    if (config.replace) {
-        const nodesUnderResult = nodesUnder(
-            document,
-            originalElement,
-            config,
-            searchReplaceResult,
-            elementsChecked,
-            ignoredElements
-        )
-
-        searchReplaceResult = nodesUnderResult.searchReplaceResult
-        elementsChecked = nodesUnderResult.elementsChecked
-    }
-
-    return { searchReplaceResult, elementsChecked }
-}
-
 function replaceInInputs(
     config: SearchReplaceConfig,
     document: Document,
@@ -577,24 +388,6 @@ function replaceInputFields(
     return { searchReplaceResult, elementsChecked }
 }
 
-function getHiddenElements(element: HTMLElement, config: SearchReplaceConfig): Set<Element> {
-    return new Set(
-        Array.from(element.getElementsByTagName('*'))
-            .filter((el) => !el.tagName.match(config.elementFilter))
-            .filter((el) => !elementIsVisible(el as HTMLElement, false, false))
-    )
-}
-
-function equivalentInIgnoredElements(ignoredElements: Set<Element>, element: Element) {
-    for (const ignored of ignoredElements) {
-        if (ignored.isEqualNode(element)) {
-            return true
-        }
-    }
-
-    return false
-}
-
 function replaceInSrcDocIframe(
     config: SearchReplaceConfig,
     iframe: HTMLIFrameElement,
@@ -611,6 +404,14 @@ function replaceInSrcDocIframe(
     return { searchReplaceResult, elementsChecked }
 }
 
+/**
+ * Counts and replaces everywhere under the given roots that is not an input.
+ *
+ * Both actions read the same list of instances, which is what makes the count the popup shows
+ * agree with what a press of Replace Next will do. The clone-and-filter machinery this replaced
+ * existed only to keep unwanted subtrees out of an `innerHTML` rewrite; nothing is rewritten
+ * wholesale any more, so scope is simply decided per instance as the page is walked.
+ */
 function replaceInHTML(
     config: SearchReplaceConfig,
     document: Document,
@@ -618,62 +419,36 @@ function replaceInHTML(
     searchReplaceResult: SearchReplaceResult,
     elementsChecked: Map<Element, SearchReplaceResult>
 ): ReplaceFunctionReturnType {
-    for (const [originalIndex, originalElement] of originalElements.entries()) {
-        let clonedElement = originalElement.cloneNode(true) as HTMLElement
-
-        const { clonedElementRemoved, removedSet } = copyElementAndRemoveSelectedElements(
-            clonedElement,
-            // Remove elements that
-            // - match the element filter, but are not blob iframes, nor are WYSIWYG iframes.
-            //   Removes SCRIPT, STYLE, IFRAME, etc.
-            // - match the input filter, as these are handled later
-            // - are already in the elementsChecked map
-            (el: HTMLElement) =>
-                (!!el.nodeName.match(config.elementFilter) && !isBlobIframe(el) && !isWYSIWYGEditorIframe(el)) ||
-                isInputElement(el) ||
-                elementsChecked.has(el),
-            false
-        )
-        clonedElement = clonedElementRemoved as HTMLElement
-        let ignoredElements = removedSet
-        if (!config.hiddenContent) {
-            // We have to check the visibility of the original elements as the cloned ones are all invisible
-            if (!elementIsVisible(originalElements[originalIndex])) {
+    for (const originalElement of originalElements) {
+        const instances = collectInstances(originalElement, config)
+        searchReplaceResult.count.original += countInstances(instances)
+
+        for (const instance of orderForReplacement(instances)) {
+            if (!config.replace) {
+                break
+            }
+            const replaced = applyInstance(instance, config, config.replaceAll)
+            if (replaced === 0) {
                 continue
             }
-            ignoredElements = new Set([
-                ...ignoredElements,
-                ...(getHiddenElements(originalElement, config) as Set<HTMLElement>),
-            ])
-            // the above works if an ancestor of the element is hidden, but not if the element contains descendants that
-            // are hidden. To check for this, we need to check the relatives of the element to see if they are hidden
-            // and if so, create a copy of the element with the hidden elements removed, storing a map of the hidden
-            // elements and their paths, so we can ignore them during replacement
-            const { clonedElementRemoved, removedSet } = copyElementAndRemoveSelectedElements(
-                clonedElement,
-                (el) => equivalentInIgnoredElements(ignoredElements, el),
-                false
-            )
-
-            clonedElement = clonedElementRemoved as HTMLElement
-            ignoredElements = new Set([...ignoredElements, ...removedSet])
-        }
 
-        // replace inner texts first, dropping out if we have done a replacement and are not working globally
-        const innerResult = replaceInner(
-            config,
-            document,
-            originalElement,
-            clonedElement,
-            ignoredElements,
-            searchReplaceResult,
-            elementsChecked
-        )
+            const element = instanceElement(instance)
+            if (element) {
+                elementsChecked = updateResults(elementsChecked, element, true, instance.matches, replaced)
+                notifyChanged(element)
+            }
+            searchReplaceResult.count.replaced += replaced
+            searchReplaceResult.replaced = true
 
-        searchReplaceResult = innerResult.searchReplaceResult
-        elementsChecked = innerResult.elementsChecked
+            if (config.replaceNext) {
+                // One press, one match
+                config.replace = false
+                break
+            }
+        }
 
-        // Now replace in input fields
+        // Inputs carry their value on the element rather than in the DOM beneath it, so they are
+        // collected and replaced separately
         const inputResult = replaceInInputs(
             config,
             document,
diff --git a/src/searchreplace/instances.test.ts b/src/searchreplace/instances.test.ts
new file mode 100644
index 0000000..ccfefd7
--- /dev/null
+++ b/src/searchreplace/instances.test.ts
@@ -0,0 +1,177 @@
+import { ELEMENT_FILTER } from '../constants'
+import { SearchReplaceConfig } from '../types'
+import { applyInstance, collectInstances, countInstances, orderForReplacement, summariseInstances } from './instances'
+import { beforeEach, describe, expect, test } from 'vitest'
+
+const TERM = 'European'
+
+function configFor(options: Partial<SearchReplaceConfig> = {}): SearchReplaceConfig {
+    return {
+        action: 'count',
+        replace: false,
+        replaceNext: false,
+        replaceAll: true,
+        searchTerm: TERM,
+        replaceTerm: 'American',
+        flags: 'g',
+        inputFieldsOnly: false,
+        isRegex: false,
+        replaceHTML: false,
+        hiddenContent: false,
+        wholeWord: false,
+        searchPattern: new RegExp(TERM, 'g'),
+        globalSearchPattern: new RegExp(TERM, 'g'),
+        matchCase: false,
+        isIframe: false,
+        iframes: [],
+        elementFilter: ELEMENT_FILTER,
+        usesKnockout: false,
+        searchTarget: 'innerText',
+        shadowRoots: [],
+        ...options,
+    } as SearchReplaceConfig
+}
+
+const html = (config: Partial<SearchReplaceConfig> = {}) =>
+    configFor({ replaceHTML: true, searchTarget: 'innerHTML', ...config })
+
+function collect(markup: string, config: SearchReplaceConfig) {
+    document.body.innerHTML = markup
+    return collectInstances(document.body, config)
+}
+
+beforeEach(() => {
+    document.body.innerHTML = ''
+})
+
+describe('what is in scope', () => {
+    test('ordinary text always is', () => {
+        expect(summariseInstances(collect('<p>European</p>', configFor()))).toEqual({ text: 1 })
+    })
+
+    test('script and style contents only when replacing HTML', () => {
+        const markup = '<script>var a = "European"</script><style>.European { color: red; }</style>'
+
+        expect(countInstances(collect(markup, configFor()))).toBe(0)
+        expect(countInstances(collect(markup, html()))).toBe(2)
+    })
+
+    test('script and style are in scope despite never being visible', () => {
+        // They are display:none by definition, so a visibility test would reject them however
+        // the Hidden content option is set
+        const instances = collect('<script>var a = "European"</script>', html({ hiddenContent: false }))
+
+        expect(countInstances(instances)).toBe(1)
+    })
+
+    test('attributes only when replacing HTML', () => {
+        const markup = '<a href="/European-news" title="European">link</a>'
+
+        expect(countInstances(collect(markup, configFor()))).toBe(0)
+        expect(summariseInstances(collect(markup, html()))).toEqual({ attribute: 2 })
+    })
+
+    test('an input value is left to the input path, attribute and all', () => {
+        // Counting the value attribute here as well would report the same occurrence twice
+        const instances = collect('<input type="text" value="European">', html())
+
+        expect(countInstances(instances)).toBe(0)
+    })
+
+    test('hidden text only when Hidden content is set', () => {
+        const markup = '<p>European</p><p style="display: none;">European</p>'
+
+        expect(countInstances(collect(markup, configFor()))).toBe(1)
+        expect(countInstances(collect(markup, configFor({ hiddenContent: true })))).toBe(2)
+    })
+
+    test('a rich text editor is left to the input path', () => {
+        const instances = collect('<div contenteditable="true">European</div>', configFor())
+
+        expect(countInstances(instances)).toBe(0)
+    })
+})
+
+describe('markup matches', () => {
+    test('a match in a tag is charged to the innermost element that explains it', () => {
+        const config = html({ searchTerm: '<b', searchPattern: /<b/g, globalSearchPattern: /<b/g })
+        const instances = collect('<div><p>a <b>bold</b> word</p></div>', config)
+
+        expect(summariseInstances(instances)).toEqual({ markup: 1 })
+        const markup = instances.find((instance) => instance.kind === 'markup')
+        expect(markup?.kind === 'markup' && markup.element.tagName).toBe('P')
+    })
+
+    test('text that a text node already explains is not counted twice', () => {
+        const instances = collect('<div><p>European</p></div>', html())
+
+        // Not once for the text node and again as a surplus on <p>, <div> and <body>
+        expect(countInstances(instances)).toBe(1)
+        expect(summariseInstances(instances)).toEqual({ text: 1 })
+    })
+
+    test('an element holding something out of scope never gets a markup instance', () => {
+        // Its innerHTML describes the hidden text too, so a surplus taken from it would drag
+        // that text back into the replacement
+        const config = html({ searchTerm: '<p', searchPattern: /<p/g, globalSearchPattern: /<p/g })
+        const instances = collect('<div><p style="display: none;">hidden</p></div>', config)
+
+        expect(countInstances(instances)).toBe(0)
+    })
+})
+
+describe('applying', () => {
+    test('replaces a single occurrence when not replacing all', () => {
+        const instances = collect('<p>European European European</p>', configFor())
+
+        expect(applyInstance(instances[0], configFor(), false)).toBe(1)
+        expect(document.body.textContent).toBe('American European European')
+    })
+
+    test('replaces every occurrence when replacing all', () => {
+        const instances = collect('<p>European European European</p>', configFor())
+
+        expect(applyInstance(instances[0], configFor(), true)).toBe(3)
+        expect(document.body.textContent).toBe('American American American')
+    })
+
+    test('writes through the text node, leaving the rest of the document untouched', () => {
+        document.body.innerHTML = '<div><p id="target">European</p><p id="other">text</p></div>'
+        const other = document.getElementById('other')
+        const otherText = other?.firstChild
+        const instances = collectInstances(document.body, configFor())
+
+        applyInstance(instances[0], configFor(), true)
+
+        expect(document.getElementById('other')).toBe(other)
+        expect(other?.firstChild).toBe(otherText)
+    })
+
+    test('reports nothing replaced when the value has moved on since collection', () => {
+        const instances = collect('<p>European</p>', configFor())
+        const instance = instances[0]
+        if (instance.kind === 'text') {
+            instance.node.data = 'already changed'
+        }
+
+        expect(applyInstance(instance, configFor(), true)).toBe(0)
+    })
+})
+
+describe('ordering', () => {
+    test('markup instances go last, deepest first', () => {
+        // A markup instance recreates its subtree, detaching the text nodes the other instances
+        // hold, so everything else has to be written before it
+        const config = html()
+        document.body.innerHTML = '<div><p>European</p></div>'
+        const text = collectInstances(document.body, config)[0]
+        const outer = { kind: 'markup', element: document.querySelector('div')!, matches: 1 } as const
+        const inner = { kind: 'markup', element: document.querySelector('p')!, matches: 1 } as const
+
+        const ordered = orderForReplacement([outer, text, inner])
+
+        expect(ordered.map((instance) => instance.kind)).toEqual(['text', 'markup', 'markup'])
+        expect(ordered[1]).toBe(inner)
+        expect(ordered[2]).toBe(outer)
+    })
+})
diff --git a/src/searchreplace/instances.ts b/src/searchreplace/instances.ts
new file mode 100644
index 0000000..4828757
--- /dev/null
+++ b/src/searchreplace/instances.ts
@@ -0,0 +1,273 @@
+// One pass over the page producing the list of places the search term was found, which both
+// counting and replacing then work from.
+//
+// Counting and replacing used to be two separate walks: counting measured an element's
+// `innerHTML` as a string, replacing drove a TreeWalker. They disagreed, and the disagreement
+// was visible — a page with a match in a script and one in a style reported 2 matches and
+// replaced 4, so pressing Replace Next appeared to stall on the ones the count had never
+// admitted to. The two cannot be reconciled by patching either side, because an `innerHTML`
+// string cannot express scope: the text of a hidden element, of a script, and of an input are
+// all in it, whether or not any of them is in scope for this search.
+//
+// Working from nodes rather than strings makes scope decidable per match, and confines each
+// replacement to the node holding it — so replacing one word no longer rewrites an ancestor's
+// entire subtree, taking every descendant's identity, listeners and focus with it.
+
+import { SearchReplaceConfig } from '../types'
+import { elementIsVisible, isEditable } from '../elements'
+
+/** A place holding at least one occurrence of the search term */
+export type MatchInstance =
+    /** Character data: ordinary text, and the contents of script and style elements */
+    | { kind: 'text'; node: Text; matches: number }
+    /** An attribute value, e.g. the href of a link. Only in scope when replacing HTML. */
+    | { kind: 'attribute'; element: Element; name: string; matches: number }
+    /**
+     * A match that exists only in the markup — `<p`, or a term spanning a tag boundary — and so
+     * cannot be written through a text node or an attribute. Replacing it rewrites the
+     * element's innerHTML, which is the destructive operation this module otherwise avoids, so
+     * it is confined to the innermost element that can account for the match and is only used
+     * where the surplus cannot be explained any other way.
+     */
+    | { kind: 'markup'; element: Element; matches: number }
+
+/** Character data whose parent is one of these is markup, not prose: only in scope for HTML */
+const MARKUP_TEXT = /^(?:SCRIPT|STYLE)$/i
+
+/**
+ * Attributes that hold a value the user edits rather than page markup. `value` is excluded
+ * because an input's live value is replaced through the element's value property, and counting
+ * the attribute as well would count the same occurrence twice.
+ */
+const NOT_AN_ATTRIBUTE_MATCH = /^value$/i
+
+function countMatches(value: string, config: SearchReplaceConfig): number {
+    return (value.match(config.globalSearchPattern) || []).length
+}
+
+/**
+ * Whether this element's contents are in scope.
+ *
+ * `elementIsVisible` is only consulted when hidden content is excluded, because it is the
+ * expensive part of the walk and the answer does not matter otherwise.
+ */
+function inScope(element: Element | null, config: SearchReplaceConfig): boolean {
+    if (!element) {
+        return false
+    }
+    if (element.tagName.match(MARKUP_TEXT)) {
+        // Script and style hold markup, not prose, so they are in scope exactly when replacing
+        // HTML. The visibility test below is skipped for them deliberately: they are never
+        // rendered, so it would reject them however the Hidden content option is set, and
+        // "Replace HTML" that silently skipped every script and stylesheet would be a lie.
+        return config.replaceHTML
+    }
+    if (element.tagName.match(config.elementFilter)) {
+        // HTML, HEAD, IFRAME and friends: never searched
+        return false
+    }
+    if (!config.hiddenContent && !elementIsVisible(element as HTMLElement)) {
+        return false
+    }
+    return true
+}
+
+/**
+ * Every place under `root` holding the search term, in document order.
+ *
+ * Inputs and textareas are left out: their values are replaced through the value property by
+ * the input path, and their `value` attribute is excluded above so the same occurrence is not
+ * reported twice.
+ */
+export function collectInstances(root: Node, config: SearchReplaceConfig): MatchInstance[] {
+    const instances: MatchInstance[] = []
+    const document = root.ownerDocument ?? (root as Document)
+    // Elements whose subtree holds something out of scope. Their innerHTML cannot be trusted to
+    // describe only in-scope matches, so they are never considered for a markup instance —
+    // otherwise rewriting one would drag the hidden text or the script back into the
+    // replacement, which is the behaviour this module exists to stop.
+    const tainted = new Set<Element>()
+    // How many matches inside each element's innerHTML some other instance already accounts for
+    const accounted = new Map<Element, number>()
+
+    function taint(element: Element | null) {
+        for (let current = element; current; current = current.parentElement) {
+            tainted.add(current)
+        }
+    }
+
+    function account(element: Element | null, matches: number) {
+        for (let current = element; current; current = current.parentElement) {
+            accounted.set(current, (accounted.get(current) ?? 0) + matches)
+        }
+    }
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT, {
+        acceptNode: (node) => {
+            if (node.nodeType !== Node.ELEMENT_NODE) {
+                return NodeFilter.FILTER_ACCEPT
+            }
+            const element = node as Element
+            // FILTER_REJECT skips the subtree, not just the element, which is what keeps the
+            // text inside a hidden container or a rich text editor out of the results
+            if (!inScope(element, config) || isInputLike(element) || isEditable(element)) {
+                taint(element)
+                return NodeFilter.FILTER_REJECT
+            }
+            return NodeFilter.FILTER_ACCEPT
+        },
+    })
+
+    const elements: Element[] = []
+    let node: Node | null = walker.currentNode
+    for (; node; node = walker.nextNode()) {
+        if (node.nodeType === Node.TEXT_NODE) {
+            const text = node as Text
+            const matches = countMatches(text.data, config)
+            if (matches > 0) {
+                instances.push({ kind: 'text', node: text, matches })
+                account(text.parentElement, matches)
+            }
+            continue
+        }
+
+        // Attributes are part of the HTML and nothing else, so they are only in scope when
+        // replacing HTML
+        if (!config.replaceHTML || node.nodeType !== Node.ELEMENT_NODE) {
+            continue
+        }
+        const element = node as Element
+        elements.push(element)
+        for (const attribute of Array.from(element.attributes)) {
+            if (attribute.name.match(NOT_AN_ATTRIBUTE_MATCH)) {
+                continue
+            }
+            const matches = countMatches(attribute.value, config)
+            if (matches > 0) {
+                instances.push({ kind: 'attribute', element, name: attribute.name, matches })
+                // An attribute of E shows up in E's *parent's* innerHTML, not E's own
+                account(element.parentElement, matches)
+            }
+        }
+    }
+
+    if (config.replaceHTML) {
+        collectMarkupInstances(elements, instances, tainted, accounted, account, config)
+    }
+
+    return instances
+}
+
+/**
+ * Anything in an element's innerHTML that the text and attribute instances cannot explain is a
+ * match in the markup itself.
+ *
+ * Reverse document order visits a descendant before its ancestor, so a surplus is charged to the
+ * innermost element that can account for it and the ancestor then sees it as already explained.
+ */
+function collectMarkupInstances(
+    elements: Element[],
+    instances: MatchInstance[],
+    tainted: Set<Element>,
+    accounted: Map<Element, number>,
+    account: (element: Element | null, matches: number) => void,
+    config: SearchReplaceConfig
+): void {
+    for (let index = elements.length - 1; index >= 0; index--) {
+        const element = elements[index]
+        if (tainted.has(element)) {
+            continue
+        }
+        const total = countMatches(element.innerHTML, config)
+        const surplus = total - (accounted.get(element) ?? 0)
+        if (surplus > 0) {
+            instances.push({ kind: 'markup', element, matches: surplus })
+            account(element, surplus)
+        }
+    }
+}
+
+function isInputLike(element: Element | null): boolean {
+    return !!element && /^(?:INPUT|TEXTAREA)$/i.test(element.tagName)
+}
+
+export function countInstances(instances: MatchInstance[]): number {
+    return instances.reduce((total, instance) => total + instance.matches, 0)
+}
+
+function readInstance(instance: MatchInstance): string {
+    switch (instance.kind) {
+        case 'text':
+            return instance.node.data
+        case 'attribute':
+            return instance.element.getAttribute(instance.name) ?? ''
+        case 'markup':
+            return instance.element.innerHTML
+    }
+}
+
+function writeInstance(instance: MatchInstance, value: string): void {
+    switch (instance.kind) {
+        case 'text':
+            // Assigning to the text node, not to any ancestor's innerHTML: every other node in
+            // the document keeps its identity, and with it the page's listeners and focus
+            instance.node.data = value
+            break
+        case 'attribute':
+            instance.element.setAttribute(instance.name, value)
+            break
+        case 'markup':
+            instance.element.innerHTML = value
+            break
+    }
+}
+
+/**
+ * Application order.
+ *
+ * A markup instance recreates everything beneath its element, which detaches the text nodes any
+ * other instance in that subtree is holding, so those are written first. Markup instances then
+ * go deepest first, each reading an innerHTML that already contains the replacements made
+ * below it.
+ */
+export function orderForReplacement(instances: MatchInstance[]): MatchInstance[] {
+    const markup = instances.filter((instance) => instance.kind === 'markup')
+    const rest = instances.filter((instance) => instance.kind !== 'markup')
+    return [...rest, ...markup.reverse()]
+}
+
+/**
+ * Replaces in one instance and reports how many occurrences went.
+ *
+ * `all` replaces every occurrence in this instance; otherwise exactly one, which is what makes
+ * a single press of Replace Next take exactly one match off the count.
+ */
+export function applyInstance(instance: MatchInstance, config: SearchReplaceConfig, all: boolean): number {
+    const before = readInstance(instance)
+    // Derived here rather than taken from config.searchPattern, whose global flag depends on
+    // whether the user pressed Replace All: this has to replace exactly one either way
+    const single = new RegExp(config.globalSearchPattern.source, config.globalSearchPattern.flags.replace('g', ''))
+    const after = all
+        ? before.replace(config.globalSearchPattern, config.replaceTerm)
+        : before.replace(single, config.replaceTerm)
+
+    if (after === before) {
+        return 0
+    }
+    writeInstance(instance, after)
+    // Recounted rather than trusting the figure from collection time, in case the value has
+    // moved on since
+    return all ? countMatches(before, config) : 1
+}
+
+/** The element a replacement should be announced on, for the page's own listeners */
+export function instanceElement(instance: MatchInstance): Element | null {
+    return instance.kind === 'text' ? instance.node.parentElement : instance.element
+}
+
+/** Exported for tests: what the collector found, by kind */
+export function summariseInstances(instances: MatchInstance[]): Record<string, number> {
+    return instances.reduce<Record<string, number>>((summary, instance) => {
+        summary[instance.kind] = (summary[instance.kind] ?? 0) + instance.matches
+        return summary
+    }, {})
+}

From c6880f6f2948ad3c8720cc92be653a58f9c8c728 Mon Sep 17 00:00:00 2001
From: Chris Taylor <forgetso86@gmail.com>
Date: Mon, 21 Sep 2026 23:33:12 +0100
Subject: [PATCH 2/2] Charge markup matches to the element whose tag they are
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Cypress suite caught what the unit tests did not: searching "<div" on the
e2e fixture reported 2 where it expects 18. Charging markup matches to an
element's innerHTML was wrong twice over. An ancestor's innerHTML repeats every
descendant's tag, so the arithmetic to avoid double counting depended on the
taint check, and on a real page almost every container holds a script or a
hidden element — so almost every markup match was dropped.

Matches in markup now belong to the element whose tags they are. An element's
own tags are `element.cloneNode(false).outerHTML`, children excluded, so each
element accounts for itself and nesting cannot double count. Attribute matches
come off the total, since attribute values sit inside the opening tag.

Replacing one rebuilds the element from the rewritten tag and moves the
existing children across rather than assigning to outerHTML, which would
reparse them and hand back new nodes. Descendants keep their identity. If the
rewritten tag does not parse to exactly one element the element is left alone,
rather than replacing the page with rubble.

The innerHTML fallback stays for terms that span a tag boundary, which no
single tag, attribute or text node holds — `<span>x</span>` is the existing
test. That is the only case still using the destructive path, and the taint
check still guards it.

The root element's own tags are excluded: the search is of what is inside the
root, as innerHTML always was. Counting them means "<b" matches "<body>", and
replacing that swapped out the body element.

Two Cypress expectations pinned behaviour this work deliberately changes, and
now assert the corrected version: script contents are in scope for Replace HTML
wherever the script sits, and text hidden by a stylesheet is out of scope
unless Hidden content is set. Both previously depended on where the element
happened to sit in the tree rather than on the options.

Adds searchreplace.fixture.test.ts, which counts the Cypress fixture from
`npm test`. The e2e specs only run in CI, so this regression was invisible
until the pull request went red.

792 unit tests and all 30 end-to-end tests pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/cypress/e2e/counts.cy.ts        | 43 ++++++++++++++-----
 src/searchreplace.fixture.test.ts   | 52 +++++++++++++++++++++++
 src/searchreplace/instances.test.ts | 34 ++++++++++++++-
 src/searchreplace/instances.ts      | 65 ++++++++++++++++++++++++++---
 4 files changed, 178 insertions(+), 16 deletions(-)
 create mode 100644 src/searchreplace.fixture.test.ts

diff --git a/src/cypress/e2e/counts.cy.ts b/src/cypress/e2e/counts.cy.ts
index 961bf11..0134fc0 100644
--- a/src/cypress/e2e/counts.cy.ts
+++ b/src/cypress/e2e/counts.cy.ts
@@ -80,24 +80,24 @@ describe('Reported match counts', () => {
         })
     })
 
-    // Replacing in HTML rewrites the whole subtree of the outermost matching element, so it
-    // reaches script contents and hidden text regardless of the "Hidden content" setting. These
-    // two tests pin that known limitation; see the note in searchreplace.invariants.test.ts.
-    it('leaves a top level script alone', () => {
-        // A script that is a direct child of body is safe: body is the root of the walk and is
-        // never itself the element whose innerHTML gets rewritten
+    // Replacing in HTML used to rewrite the whole subtree of the outermost matching element, so
+    // where a script or some hidden text ended up being replaced was decided by where it
+    // happened to sit in the tree. It is now decided by the options, which is what these three
+    // tests cover. Script contents are in scope for Replace HTML wherever they are; hidden text
+    // is in scope only when Hidden content is set.
+    it('replaces inside a top level script when replacing HTML', () => {
         cy.window().then((window) => {
             cy.wrap(
                 run('searchReplace', window, { replaceHTML: true }).then(() => {
                     const script = window.document.getElementById('page-script')
-                    expect(script?.textContent).to.contain(SEARCH)
-                    expect(script?.textContent).to.not.contain(REPLACE)
+                    expect(script?.textContent).to.contain(REPLACE)
+                    expect(script?.textContent).to.not.contain(SEARCH)
                 })
             )
         })
     })
 
-    it('KNOWN LIMITATION: Replace HTML rewrites a script sharing a container with matching text', () => {
+    it('replaces inside a nested script too, wherever it sits', () => {
         cy.window().then((window) => {
             cy.wrap(
                 run('searchReplace', window, { replaceHTML: true }).then(() => {
@@ -108,10 +108,33 @@ describe('Reported match counts', () => {
         })
     })
 
-    it('KNOWN LIMITATION: Replace HTML rewrites text hidden by a stylesheet', () => {
+    it('leaves a script alone when not replacing HTML', () => {
+        cy.window().then((window) => {
+            cy.wrap(
+                run('searchReplace', window).then(() => {
+                    const script = window.document.getElementById('page-script')
+                    expect(script?.textContent).to.contain(SEARCH)
+                    expect(script?.textContent).to.not.contain(REPLACE)
+                })
+            )
+        })
+    })
+
+    it('leaves text hidden by a stylesheet alone unless Hidden content is set', () => {
         cy.window().then((window) => {
             cy.wrap(
                 run('searchReplace', window, { replaceHTML: true }).then(() => {
+                    const hidden = window.document.querySelectorAll('.promo')
+                    hidden.forEach((el) => expect(el.textContent).to.equal(SEARCH))
+                })
+            )
+        })
+    })
+
+    it('rewrites text hidden by a stylesheet when Hidden content is set', () => {
+        cy.window().then((window) => {
+            cy.wrap(
+                run('searchReplace', window, { replaceHTML: true, hiddenContent: true }).then(() => {
                     const hidden = window.document.querySelectorAll('.promo')
                     hidden.forEach((el) => expect(el.textContent).to.equal(REPLACE))
                 })
diff --git a/src/searchreplace.fixture.test.ts b/src/searchreplace.fixture.test.ts
new file mode 100644
index 0000000..2e63f7d
--- /dev/null
+++ b/src/searchreplace.fixture.test.ts
@@ -0,0 +1,52 @@
+import { ELEMENT_FILTER } from './constants'
+import { beforeEach, describe, expect, test } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { searchReplace } from './searchreplace'
+
+/**
+ * The page the Cypress end-to-end suite runs against.
+ *
+ * Those specs only run in CI, so a change that broke them was invisible until the pull request
+ * went red. Counting the same fixture here, with the same expectations, catches it from
+ * `npm test`. jsdom is not a browser, so this is a guard rather than a replacement for the
+ * real thing.
+ */
+const FIXTURE = readFileSync('tests/test.html', 'utf8')
+
+function run(options: Record<string, unknown>) {
+    return searchReplace({
+        action: 'count',
+        window,
+        searchTerm: '<div',
+        replaceTerm: 'x',
+        inputFieldsOnly: false,
+        isRegex: false,
+        hiddenContent: true,
+        wholeWord: false,
+        matchCase: false,
+        replaceHTML: true,
+        replaceAll: true,
+        isIframe: false,
+        iframes: [],
+        elementFilter: ELEMENT_FILTER,
+        ...options,
+    } as never)
+}
+
+beforeEach(() => {
+    document.documentElement.innerHTML = FIXTURE
+})
+
+describe('counting <div in the Cypress fixture', () => {
+    test('counts <div with hidden content included (cypress expects 18)', async () => {
+        const { count } = (await run({ hiddenContent: true })).searchReplaceResult
+        console.log('hiddenContent true  ->', count.original)
+        expect(count.original).toBe(18)
+    })
+
+    test('counts <div with hidden content excluded (cypress expects 11)', async () => {
+        const { count } = (await run({ hiddenContent: false })).searchReplaceResult
+        console.log('hiddenContent false ->', count.original)
+        expect(count.original).toBe(11)
+    })
+})
diff --git a/src/searchreplace/instances.test.ts b/src/searchreplace/instances.test.ts
index ccfefd7..93d24e6 100644
--- a/src/searchreplace/instances.test.ts
+++ b/src/searchreplace/instances.test.ts
@@ -93,15 +93,47 @@ describe('what is in scope', () => {
 })
 
 describe('markup matches', () => {
-    test('a match in a tag is charged to the innermost element that explains it', () => {
+    test('a match in a tag is charged to the element whose tag it is', () => {
         const config = html({ searchTerm: '<b', searchPattern: /<b/g, globalSearchPattern: /<b/g })
         const instances = collect('<div><p>a <b>bold</b> word</p></div>', config)
 
+        expect(summariseInstances(instances)).toEqual({ tag: 1 })
+        const tag = instances.find((instance) => instance.kind === 'tag')
+        expect(tag?.kind === 'tag' && tag.element.tagName).toBe('B')
+    })
+
+    test('one instance per element, however deeply they nest', () => {
+        // An ancestor's innerHTML repeats every descendant's tag, so charging matches to
+        // innerHTML counted the same <div once per level of nesting
+        const config = html({ searchTerm: '<div', searchPattern: /<div/g, globalSearchPattern: /<div/g })
+        const instances = collect('<div><div><div>x</div></div></div>', config)
+
+        expect(countInstances(instances)).toBe(3)
+    })
+
+    test('a term spanning a tag boundary falls back to the innermost element holding it', () => {
+        const term = '<span>x</span>'
+        const pattern = /<span>x<\/span>/g
+        const config = html({ searchTerm: term, searchPattern: pattern, globalSearchPattern: pattern })
+        const instances = collect('<div id="outer"><p><span>x</span></p></div>', config)
+
         expect(summariseInstances(instances)).toEqual({ markup: 1 })
         const markup = instances.find((instance) => instance.kind === 'markup')
         expect(markup?.kind === 'markup' && markup.element.tagName).toBe('P')
     })
 
+    test('rewriting a tag keeps the children it had', () => {
+        const config = html({ searchTerm: '<b', searchPattern: /<b/g, globalSearchPattern: /<b/g })
+        document.body.innerHTML = '<p><b>bold <i id="kept">and italic</i></b></p>'
+        const kept = document.getElementById('kept')
+        const instances = collectInstances(document.body, config)
+
+        applyInstance(instances[0], { ...config, replaceTerm: '<strong' }, true)
+
+        expect(document.getElementById('kept')).toBe(kept)
+        expect(document.querySelector('strong')?.textContent).toBe('bold and italic')
+    })
+
     test('text that a text node already explains is not counted twice', () => {
         const instances = collect('<div><p>European</p></div>', html())
 
diff --git a/src/searchreplace/instances.ts b/src/searchreplace/instances.ts
index 4828757..2154481 100644
--- a/src/searchreplace/instances.ts
+++ b/src/searchreplace/instances.ts
@@ -23,11 +23,17 @@ export type MatchInstance =
     /** An attribute value, e.g. the href of a link. Only in scope when replacing HTML. */
     | { kind: 'attribute'; element: Element; name: string; matches: number }
     /**
-     * A match that exists only in the markup — `<p`, or a term spanning a tag boundary — and so
-     * cannot be written through a text node or an attribute. Replacing it rewrites the
-     * element's innerHTML, which is the destructive operation this module otherwise avoids, so
-     * it is confined to the innermost element that can account for the match and is only used
-     * where the surplus cannot be explained any other way.
+     * A match in an element's own tags, e.g. searching for `<div`. Replacing it rebuilds the
+     * element from the rewritten tag and moves the existing children across, so everything
+     * beneath keeps its identity.
+     */
+    | { kind: 'tag'; element: Element; matches: number }
+    /**
+     * A match spanning a tag boundary, e.g. `<span>x</span>`, which no single tag, attribute or
+     * text node holds. Replacing it rewrites the element's innerHTML, the destructive operation
+     * this module otherwise avoids, so it is a last resort: only for what nothing else can
+     * account for, only on the innermost element that explains it, and never on an element
+     * whose subtree holds anything out of scope.
      */
     | { kind: 'markup'; element: Element; matches: number }
 
@@ -137,6 +143,15 @@ export function collectInstances(root: Node, config: SearchReplaceConfig): Match
         }
         const element = node as Element
         elements.push(element)
+        if (element === root) {
+            // The search is of what is *inside* the root, as innerHTML always was. Its own tags
+            // and attributes are the frame around that, not part of it — and counting them
+            // means a search for `<b` matches `<body>`, whose replacement would swap out the
+            // body element itself.
+            continue
+        }
+
+        let inAttributes = 0
         for (const attribute of Array.from(element.attributes)) {
             if (attribute.name.match(NOT_AN_ATTRIBUTE_MATCH)) {
                 continue
@@ -144,10 +159,19 @@ export function collectInstances(root: Node, config: SearchReplaceConfig): Match
             const matches = countMatches(attribute.value, config)
             if (matches > 0) {
                 instances.push({ kind: 'attribute', element, name: attribute.name, matches })
+                inAttributes += matches
                 // An attribute of E shows up in E's *parent's* innerHTML, not E's own
                 account(element.parentElement, matches)
             }
         }
+
+        // The element's own tags, children excluded: `<div class="x"></div>`. Attribute values
+        // live inside the opening tag, so what they already account for comes back off.
+        const inTags = countMatches(tagsOf(element), config) - inAttributes
+        if (inTags > 0) {
+            instances.push({ kind: 'tag', element, matches: inTags })
+            account(element.parentElement, inTags)
+        }
     }
 
     if (config.replaceHTML) {
@@ -186,6 +210,11 @@ function collectMarkupInstances(
     }
 }
 
+/** An element's opening and closing tags with nothing between them */
+function tagsOf(element: Element): string {
+    return (element.cloneNode(false) as Element).outerHTML
+}
+
 function isInputLike(element: Element | null): boolean {
     return !!element && /^(?:INPUT|TEXTAREA)$/i.test(element.tagName)
 }
@@ -200,6 +229,8 @@ function readInstance(instance: MatchInstance): string {
             return instance.node.data
         case 'attribute':
             return instance.element.getAttribute(instance.name) ?? ''
+        case 'tag':
+            return tagsOf(instance.element)
         case 'markup':
             return instance.element.innerHTML
     }
@@ -215,12 +246,36 @@ function writeInstance(instance: MatchInstance, value: string): void {
         case 'attribute':
             instance.element.setAttribute(instance.name, value)
             break
+        case 'tag':
+            rewriteTags(instance.element, value)
+            break
         case 'markup':
             instance.element.innerHTML = value
             break
     }
 }
 
+/**
+ * Swaps an element for one built from `tags`, carrying the existing children across.
+ *
+ * Assigning to outerHTML would reparse the children too and hand back new nodes; moving them
+ * keeps every descendant's identity, and with it the page's listeners and focus.
+ */
+function rewriteTags(element: Element, tags: string): void {
+    const template = element.ownerDocument.createElement('template')
+    template.innerHTML = tags
+    const replacement = template.content.firstElementChild
+    if (!replacement || template.content.childElementCount !== 1) {
+        // The rewritten tag did not parse to a single element — a search that mangled the
+        // markup. Leaving the element alone is better than replacing the page with rubble.
+        return
+    }
+    while (element.firstChild) {
+        replacement.appendChild(element.firstChild)
+    }
+    element.replaceWith(replacement)
+}
+
 /**
  * Application order.
  *