fix(superdoc): restore find input focus after match navigation (SD-3045) (#3240)

* fix(superdoc): restore find input focus after match navigation (SD-3045)

The Search extension's goToSearchResult calls editor.view.focus() so the
new selection is visible. When the user pressed Enter in the built-in find
input, the synchronous focus steal blurred the input — subsequent Enter
keystrokes were swallowed by the ProseMirror editor, splitting paragraphs
at the match position, invalidating the search session, and resetting the
active match index. The user had to click back into the input between
every navigation.

Re-focus the find input synchronously after goNext / goPrev so repeated
Enter / Shift+Enter keeps advancing through matches and the editor never
receives the keystroke.

* fix(superdoc): scroll cross-page search matches into view reliably (SD-3045)

Pressing Enter or clicking next/prev on a search match that lives on a
different page often left the match just below the visible area, slightly
above the viewport, or didn't scroll at all. Three races were colluding:

1. The Vue surface lives in the document's normal flow, so any focus or
   .select() on its input or buttons triggers the browser's
   scroll-element-into-view behaviour and snaps the document back to the
   find bar — undoing the goNext scroll. Drop .select() (cmd+A still
   works), focus with preventScroll: true, and pin every scrollable
   ancestor's scrollTop across the focus call. Route the button clicks
   through the same goNext/goPrev → focusFindInput path so all three
   navigation entry points (Enter, Shift+Enter, button click) have the
   same focus-restore guarantee.

2. PresentationEditor.scrollToPosition runs after dispatch(setSelection),
   but the selectionUpdate emitted by that dispatch sets
   #shouldScrollSelectionIntoView = true. The next #updateSelection then
   calls #scrollActiveEndIntoView and snaps the caret to its
   minimum-visibility position (often 20px from the viewport edge),
   visibly displacing the match. Consume the flag inside
   scrollToPosition.

3. A later selectionUpdate (focus blur as the user moves focus back to
   the find input, or async PM events) re-sets the flag to true after we
   consumed it, and the RAF-deferred #updateSelection scrolls the caret
   again. Re-assert the scrollIntoView on the next animation frame so any
   such late displacement is corrected; the no-op case is cheap.

Tests cover all three: Enter / Shift+Enter / button-click focus restore
use { preventScroll: true } on the find input. Manual repro on Luccas's
finding1.docx fixture: 4 'titlePg' matches across 3 pages — every click
now lands with the match in the centre of the viewport.

* fix(superdoc): make search highlight win over inline background-color (SD-3045)

Search matches were invisible on runs whose source rPr carried a highlight
mark (e.g. `<w:highlight w:val="white"/>`). The DomPainter writes
`style.backgroundColor = run.highlight` inline on the same span the
DecorationBridge later tags with `.ProseMirror-search-match`, and inline
styles win over class selectors — so the find colour was painted over.

Add `!important` to both search-match background rules (the `.superdoc`
scope used in presentation mode and the `.sd-editor-scoped` scope used by
the hidden editor) so the transient find colour overrides any source-doc
highlight while a search session is live. The class is only present during
a search; clearing it restores the original highlight.

Repro: load `basic/advanced-text.docx` from the corpus, search for "Oscar".
5 of 8 matches sit in runs imported as `highlight: { color: '#FFFFFF' }`
and had no visible find highlight pre-fix. All 8 are now correctly coloured.

Regression test asserts !important is present in both CSS files plus a
JSDOM specificity sanity check showing the rule wins over an inline white.

Author: tupizz

packages/super-editor/src/editors/v1/assets/styles/elements/prosemirror.css

@@ -432,11 +432,15 @@ https://github.com/ProseMirror/prosemirror-tables/blob/master/demo/index.html
   margin-top: -5px;
 }
 
+/* AIDEV-NOTE: SD-3045. `!important` so the transient search highlight wins
+ * over any inline `style.backgroundColor` painted from a source-doc highlight
+ * mark on the same span. See packages/superdoc/src/assets/styles/elements/superdoc.css
+ * for the full rationale. */
 .sd-editor-scoped .ProseMirror-search-match {
-  background-color: #ffff0054;
+  background-color: #ffff0054 !important;
 }
 .sd-editor-scoped .ProseMirror-active-search-match {
-  background-color: #ff6a0054;
+  background-color: #ff6a0054 !important;
 }
 .sd-editor-scoped .ProseMirror span.sd-custom-selection::selection {
   background: transparent;

packages/super-editor/src/editors/v1/core/presentation-editor/PresentationEditor.ts

@@ -3534,7 +3534,37 @@ export class PresentationEditor extends EventEmitter {
         if (pageEl) {
           // Find the specific element containing this position for precise centering
           const targetEl = this.#findElementAtPosition(pageEl, clampedPos);
-          (targetEl ?? pageEl).scrollIntoView({ block, inline: 'nearest', behavior });
+          const elToScroll = targetEl ?? pageEl;
+          elToScroll.scrollIntoView({ block, inline: 'nearest', behavior });
+          // AIDEV-NOTE: SD-3045. Search nav (and any other caller of
+          // scrollToPosition) places the viewport intentionally — usually
+          // centring the match. The next #updateSelection that runs as part
+          // of the dispatched setSelection transaction would otherwise call
+          // #scrollActiveEndIntoView and re-scroll the caret to its minimal
+          // visible position (often the top of the viewport), undoing our
+          // centring. Consume the pending scroll-into-view request so that
+          // selection sync renders the caret overlay without moving the
+          // scroll back. Other selection updates (Shift+Arrow, typing) re-set
+          // this flag themselves before they need scroll, so this consume is
+          // safe.
+          this.#shouldScrollSelectionIntoView = false;
+          // Re-assert the scroll on the next animation frame. The flag we
+          // cleared above defends against handleSelection that has already
+          // run, but a *later* selectionUpdate (e.g. focus blur fired when
+          // the user moves focus back to the find input) re-sets the flag to
+          // true before the RAF-scheduled #updateSelection fires, and that
+          // pass scrolls the caret to its minimal-visibility position —
+          // visibly snapping the match out of view. Re-running scrollIntoView
+          // on the same element a frame later overrides that snap; the no-op
+          // case (no late scroll happened) just re-centres the same element
+          // and is cheap.
+          const win = this.#visibleHost.ownerDocument?.defaultView;
+          if (win) {
+            win.requestAnimationFrame(() => {
+              elToScroll.scrollIntoView({ block, inline: 'nearest', behavior });
+              this.#shouldScrollSelectionIntoView = false;
+            });
+          }
           return true;
         }
       }

packages/superdoc/src/assets/styles/elements/search-match-precedence.test.js

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// SD-3045 (cross-package CSS invariant). The DomPainter writes
+// `style.backgroundColor = run.highlight` inline on the same span the search
+// DecorationBridge tags with `.ProseMirror-search-match`. Without `!important`,
+// the inline style wins and the search highlight is invisible on every run
+// whose source rPr carries a highlight mark (e.g. `<w:highlight w:val="white"/>`).
+// These tests guard the two CSS sites that paint the transient search colour.
+
+const repoRoot = join(__dirname, '..', '..', '..', '..', '..', '..');
+
+const superdocCss = readFileSync(
+  join(repoRoot, 'packages', 'superdoc', 'src', 'assets', 'styles', 'elements', 'superdoc.css'),
+  'utf8',
+);
+
+const editorScopedCss = readFileSync(
+  join(repoRoot, 'packages', 'super-editor', 'src', 'editors', 'v1', 'assets', 'styles', 'elements', 'prosemirror.css'),
+  'utf8',
+);
+
+const extractRuleBody = (css, selector) => {
+  const idx = css.indexOf(selector);
+  if (idx === -1) return null;
+  const open = css.indexOf('{', idx);
+  const close = css.indexOf('}', open);
+  if (open === -1 || close === -1) return null;
+  return css.slice(open + 1, close);
+};
+
+describe('search-match CSS precedence (SD-3045)', () => {
+  describe('packages/superdoc/src/assets/styles/elements/superdoc.css', () => {
+    it('`.superdoc .ProseMirror-search-match` background uses !important', () => {
+      const body = extractRuleBody(superdocCss, '.superdoc .ProseMirror-search-match');
+      expect(body, '.superdoc .ProseMirror-search-match rule must exist').not.toBeNull();
+      expect(body).toMatch(/background\s*:[^;]*!important/);
+    });
+
+    it('`.superdoc .ProseMirror-active-search-match` background uses !important', () => {
+      const body = extractRuleBody(superdocCss, '.superdoc .ProseMirror-active-search-match');
+      expect(body, '.superdoc .ProseMirror-active-search-match rule must exist').not.toBeNull();
+      expect(body).toMatch(/background\s*:[^;]*!important/);
+    });
+  });
+
+  describe('packages/super-editor/.../prosemirror.css', () => {
+    it('`.sd-editor-scoped .ProseMirror-search-match` background-color uses !important', () => {
+      const body = extractRuleBody(editorScopedCss, '.sd-editor-scoped .ProseMirror-search-match');
+      expect(body, '.sd-editor-scoped .ProseMirror-search-match rule must exist').not.toBeNull();
+      expect(body).toMatch(/background-color\s*:[^;]*!important/);
+    });
+
+    it('`.sd-editor-scoped .ProseMirror-active-search-match` background-color uses !important', () => {
+      const body = extractRuleBody(editorScopedCss, '.sd-editor-scoped .ProseMirror-active-search-match');
+      expect(body, '.sd-editor-scoped .ProseMirror-active-search-match rule must exist').not.toBeNull();
+      expect(body).toMatch(/background-color\s*:[^;]*!important/);
+    });
+  });
+
+  describe('JSDOM specificity sanity check', () => {
+    it('class-level `background !important` beats inline `style="background-color: white"`', () => {
+      const styleEl = document.createElement('style');
+      styleEl.textContent = `.search-test { background: rgba(255, 213, 0, 0.4) !important; }`;
+      document.head.appendChild(styleEl);
+
+      const span = document.createElement('span');
+      span.className = 'search-test';
+      span.setAttribute('style', 'background-color: rgb(255, 255, 255);');
+      document.body.appendChild(span);
+
+      const bg = getComputedStyle(span).backgroundColor;
+
+      styleEl.remove();
+      span.remove();
+
+      expect(bg).toBe('rgba(255, 213, 0, 0.4)');
+    });
+
+    it('without !important, inline `background-color: white` overrides class background', () => {
+      const styleEl = document.createElement('style');
+      styleEl.textContent = `.search-test-noimp { background: rgba(255, 213, 0, 0.4); }`;
+      document.head.appendChild(styleEl);
+
+      const span = document.createElement('span');
+      span.className = 'search-test-noimp';
+      span.setAttribute('style', 'background-color: rgb(255, 255, 255);');
+      document.body.appendChild(span);
+
+      const bg = getComputedStyle(span).backgroundColor;
+
+      styleEl.remove();
+      span.remove();
+
+      expect(bg).toBe('rgb(255, 255, 255)');
+    });
+  });
+});

packages/superdoc/src/assets/styles/elements/superdoc.css

@@ -40,12 +40,21 @@
 
 /* --- Search highlights (transient, used in both editor and presentation mode) --- */
 
+/* AIDEV-NOTE: SD-3045. The DomPainter writes `style.backgroundColor = run.highlight`
+ * inline on the same span the search DecorationBridge tags. Inline styles win over
+ * class selectors, so on every run whose source rPr carries a highlight mark
+ * (e.g. `<w:highlight w:val="white"/>`), the search highlight was invisible —
+ * the inline background painted over the class's transient yellow/orange.
+ * `!important` is the desired semantic here: while a search session is live, the
+ * find-match colour must override any source-doc highlight. The class is only
+ * present during a search; clearing the session removes it and the original
+ * highlight is restored. */
 .superdoc .ProseMirror-search-match {
-  background: var(--sd-ui-search-match-bg);
+  background: var(--sd-ui-search-match-bg) !important;
 }
 
 .superdoc .ProseMirror-active-search-match {
-  background: var(--sd-ui-search-match-active-bg);
+  background: var(--sd-ui-search-match-active-bg) !important;
 }
 
 /* Contained Mode - fixed-height container embedding with internal scrolling */