From 8771716c1cb0a3afbea22b22f38726bb68529ede Mon Sep 17 00:00:00 2001
From: Peter Ringelmann <peter.ringelmann@nextcloud.com>
Date: Fri, 10 Jul 2026 15:19:44 +0200
Subject: [PATCH 1/3] feat(core): forward per-category filter params in unified
 search controller

Signed-off-by: Peter Ringelmann <peter.ringelmann@nextcloud.com>
---
 core/src/services/UnifiedSearchController.ts  | 21 +++++-
 .../services/UnifiedSearchController.spec.ts  | 70 +++++++++++++++++++
 2 files changed, 89 insertions(+), 2 deletions(-)

diff --git a/core/src/services/UnifiedSearchController.ts b/core/src/services/UnifiedSearchController.ts
index bad5e20a78113..53bffdf08da31 100644
--- a/core/src/services/UnifiedSearchController.ts
+++ b/core/src/services/UnifiedSearchController.ts
@@ -15,6 +15,14 @@ interface CategorySearchState {
 	loadMoreFailed: boolean
 }
 
+interface CategorySearchParams {
+	type?: string
+	since?: string
+	until?: string
+	person?: string
+	extraQueries?: object
+}
+
 export const REVEAL_INTERVAL_MS = 1500
 
 /**
@@ -23,6 +31,7 @@ export const REVEAL_INTERVAL_MS = 1500
  */
 export class UnifiedSearchController {
 	private query: string = ''
+	private params: Record<string, CategorySearchParams> = {}
 	private searchStates: Record<string, CategorySearchState> = {}
 	private searchGeneration: number = 0
 	private revealTimer: ReturnType<typeof setTimeout> | null = null
@@ -33,14 +42,16 @@ export class UnifiedSearchController {
 	 *
 	 * @param query the search term
 	 * @param categories category ids in priority order
+	 * @param params optional per-category search parameters
 	 * @return resolves once every category has settled
 	 */
-	async search(query: string, categories: string[]): Promise<void> {
+	async search(query: string, categories: string[], params?: Record<string, CategorySearchParams>): Promise<void> {
 		this.cancelPendingRequests()
 		this.searchStates = {}
 		this.searchGeneration++
 		const generation = this.searchGeneration
 		this.query = query
+		this.params = params || {}
 
 		this.startRevealTimer()
 
@@ -67,6 +78,7 @@ export class UnifiedSearchController {
 			type: category,
 			query: this.query,
 			cursor: categoryState.cursor,
+			...this.params[category],
 		})
 
 		this.pendingCancels.push(cancel)
@@ -107,7 +119,11 @@ export class UnifiedSearchController {
 		this.stopRevealTimer()
 	}
 
-	private async searchCategory(category: string, generation: number, categories: string[]): Promise<void> {
+	private async searchCategory(
+		category: string,
+		generation: number,
+		categories: string[],
+	): Promise<void> {
 		this.searchStates[category] = {
 			status: 'loading',
 			entries: [],
@@ -119,6 +135,7 @@ export class UnifiedSearchController {
 			type: category,
 			query: this.query,
 			cursor: null,
+			...this.params[category],
 		})
 
 		this.pendingCancels.push(cancel)
diff --git a/core/src/tests/services/UnifiedSearchController.spec.ts b/core/src/tests/services/UnifiedSearchController.spec.ts
index 74378147dd53d..af5daca8fcbe7 100644
--- a/core/src/tests/services/UnifiedSearchController.spec.ts
+++ b/core/src/tests/services/UnifiedSearchController.spec.ts
@@ -427,6 +427,76 @@ describe('UnifiedSearchController', () => {
 		})
 	})
 
+	describe('filter pass-through', () => {
+		it('forwards per-category filter params on the initial search', async () => {
+			const files = pagedProvider()
+			service.search.mockReturnValue(files)
+
+			const searchController = new UnifiedSearchController()
+			searchController.search('query', ['files'], {
+				files: { since: '2026-01-01', until: '2026-02-01', person: 'alice', extraQueries: { tag: 'important' } },
+			})
+
+			expect(service.search).toHaveBeenCalledWith(expect.objectContaining({
+				type: 'files',
+				query: 'query',
+				cursor: null,
+				since: '2026-01-01',
+				until: '2026-02-01',
+				person: 'alice',
+				extraQueries: { tag: 'important' },
+			}))
+		})
+
+		it('reuses the stored filter params when paginating', async () => {
+			const files = pagedProvider()
+			service.search.mockReturnValue(files)
+
+			const searchController = new UnifiedSearchController()
+			searchController.search('query', ['files'], {
+				files: { since: '2026-01-01', until: '2026-02-01', person: 'alice', extraQueries: { tag: 'important' } },
+			})
+
+			files.resolvePage(0, { entries: ['a'], cursor: 'cursor-1', hasMore: true })
+			await vi.advanceTimersByTimeAsync(0)
+
+			searchController.loadMore('files')
+
+			// Page 2 must carry the same filters as page 1, not just type/query/cursor.
+			expect(service.search).toHaveBeenLastCalledWith(expect.objectContaining({
+				type: 'files',
+				query: 'query',
+				cursor: 'cursor-1',
+				since: '2026-01-01',
+				until: '2026-02-01',
+				person: 'alice',
+				extraQueries: { tag: 'important' },
+			}))
+		})
+
+		it('dispatches the type override on both requests while keying state by category id', async () => {
+			const files = pagedProvider()
+			service.search.mockReturnValue(files)
+
+			const searchController = new UnifiedSearchController()
+			// 'in-folder' is a searchFrom-style alias that dispatches to the 'files' backend.
+			searchController.search('query', ['in-folder'], { 'in-folder': { type: 'files' } })
+
+			// The request dispatches to the override type...
+			expect(service.search).toHaveBeenCalledWith(expect.objectContaining({ type: 'files' }))
+			// ...but the category stays keyed by its own id, so two aliases can't collide.
+			expect(Object.keys(searchController.getSnapshot())).toEqual(['in-folder'])
+
+			files.resolvePage(0, { entries: ['a'], cursor: 'cursor-1', hasMore: true })
+			await vi.advanceTimersByTimeAsync(0)
+
+			searchController.loadMore('in-folder')
+
+			// loadMore carries the override too, not the category id.
+			expect(service.search).toHaveBeenLastCalledWith(expect.objectContaining({ type: 'files', cursor: 'cursor-1' }))
+		})
+	})
+
 	describe('reveal timer', () => {
 		it('marks blocked categories as loaded after a certain amount of time has elapsed', async () => {
 			const providers = mockProviders(['files', 'talk', 'deck'])

From 41168e1938584a6a1f2f4e1d34e787b4c3d857cf Mon Sep 17 00:00:00 2001
From: Peter Ringelmann <peter.ringelmann@nextcloud.com>
Date: Mon, 13 Jul 2026 15:30:30 +0200
Subject: [PATCH 2/3] feat(core): add reactive adapter for the unified search
 controller

Signed-off-by: Peter Ringelmann <peter.ringelmann@nextcloud.com>
---
 core/src/composables/useUnifiedSearch.ts      |  28 ++++
 core/src/services/UnifiedSearchController.ts  |  49 +++---
 .../composables/useUnifiedSearch.spec.ts      | 136 ++++++++++++++++
 .../services/UnifiedSearchController.spec.ts  | 149 ++++++++++++++++++
 4 files changed, 344 insertions(+), 18 deletions(-)
 create mode 100644 core/src/composables/useUnifiedSearch.ts
 create mode 100644 core/src/tests/composables/useUnifiedSearch.spec.ts

diff --git a/core/src/composables/useUnifiedSearch.ts b/core/src/composables/useUnifiedSearch.ts
new file mode 100644
index 0000000000000..5100968f6ed59
--- /dev/null
+++ b/core/src/composables/useUnifiedSearch.ts
@@ -0,0 +1,28 @@
+/*!
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import { onUnmounted, shallowRef } from 'vue'
+import { UnifiedSearchController } from '../services/UnifiedSearchController.ts'
+
+/**
+ * Reactive adapter over UnifiedSearchController for use in an SFC.
+ */
+export function useUnifiedSearch() {
+	const searchStates = shallowRef({})
+
+	const controller = new UnifiedSearchController((states) => {
+		searchStates.value = states
+	})
+
+	onUnmounted(() => {
+		controller.dispose()
+	})
+
+	return {
+		searchStates,
+		search: controller.search.bind(controller),
+		loadMore: controller.loadMore.bind(controller),
+	}
+}
diff --git a/core/src/services/UnifiedSearchController.ts b/core/src/services/UnifiedSearchController.ts
index 53bffdf08da31..136de96fbceeb 100644
--- a/core/src/services/UnifiedSearchController.ts
+++ b/core/src/services/UnifiedSearchController.ts
@@ -37,6 +37,8 @@ export class UnifiedSearchController {
 	private revealTimer: ReturnType<typeof setTimeout> | null = null
 	private pendingCancels: (() => void)[] = []
 
+	constructor(private onChange?: (states: Record<string, CategorySearchState>) => void) {}
+
 	/**
 	 * Start a search. Cancels and replaces any search already in flight.
 	 *
@@ -67,12 +69,12 @@ export class UnifiedSearchController {
 	 */
 	async loadMore(category: string): Promise<void> {
 		const generation = this.searchGeneration
-		const categoryState = this.searchStates[category]
-		if (!categoryState || !categoryState.hasMore || categoryState.status !== 'loaded') {
+		const categoryState = { ...this.searchStates[category] }
+		if (!categoryState.hasMore || categoryState.status !== 'loaded') {
 			return
 		}
-		categoryState.status = 'loading'
-		categoryState.loadMoreFailed = false
+
+		this.patchStates({ [category]: { status: 'loading', loadMoreFailed: false } })
 
 		const { request, cancel } = unifiedSearch({
 			type: category,
@@ -89,17 +91,19 @@ export class UnifiedSearchController {
 				return
 			}
 			const { entries, cursor, hasMore } = response.data.ocs.data
-			categoryState.entries.push(...entries)
-			categoryState.cursor = cursor
-			categoryState.hasMore = hasMore
+
+			this.patchStates({[category]: {
+				entries: [...categoryState.entries, ...entries],
+				cursor,
+				hasMore,
+				status: 'loaded',
+			}})
 		} catch {
 			if (this.searchGeneration !== generation) {
 				return
 			}
-			categoryState.loadMoreFailed = true
+			this.patchStates({ [category]: { status: 'loaded', loadMoreFailed: true } })
 		}
-
-		categoryState.status = 'loaded'
 	}
 
 	/**
@@ -124,13 +128,14 @@ export class UnifiedSearchController {
 		generation: number,
 		categories: string[],
 	): Promise<void> {
-		this.searchStates[category] = {
+		this.patchStates({ [category]: {
 			status: 'loading',
 			entries: [],
 			cursor: null,
 			hasMore: false,
 			loadMoreFailed: false,
-		}
+		} })
+
 		const { request, cancel } = unifiedSearch({
 			type: category,
 			query: this.query,
@@ -148,24 +153,24 @@ export class UnifiedSearchController {
 			}
 
 			const { entries, cursor, hasMore } = response.data.ocs.data
-			this.searchStates[category] = {
+			this.patchStates({ [category]: {
 				status: 'loaded',
 				entries,
 				cursor,
 				hasMore,
 				loadMoreFailed: false,
-			}
+			} })
 		} catch {
 			if (this.searchGeneration !== generation) {
 				return
 			}
-			this.searchStates[category] = {
+			this.patchStates({ [category]: {
 				status: 'failed',
 				entries: [],
 				cursor: null,
 				hasMore: false,
 				loadMoreFailed: false,
-			}
+			}})
 		}
 
 		this.reconcileCategoryStatuses(categories)
@@ -176,7 +181,7 @@ export class UnifiedSearchController {
 			if (['loading', 'failed'].includes(this.searchStates[category].status)) {
 				return
 			}
-			this.searchStates[category].status = this.shouldBlockCategory(category, categories) ? 'blocked' : 'loaded'
+			this.patchStates({ [category]: { status: this.shouldBlockCategory(category, categories) ? 'blocked' : 'loaded' } })
 		})
 	}
 
@@ -207,7 +212,7 @@ export class UnifiedSearchController {
 	private unblockAllCategories(categories: string[]): void {
 		categories.forEach((category) => {
 			if (this.searchStates[category].status === 'blocked') {
-				this.searchStates[category].status = 'loaded'
+				this.patchStates({ [category]: { status: 'loaded' } })
 			}
 		})
 	}
@@ -222,4 +227,12 @@ export class UnifiedSearchController {
 			return categoryState && ['loading', 'blocked'].includes(categoryState.status)
 		})
 	}
+
+	private patchStates(next: Record<string, Partial<CategorySearchState>>): void {
+		Object.keys(next).forEach((category) => {
+			const categoryState = { ...this.searchStates[category], ...next[category] }
+			this.searchStates[category] = categoryState
+		})
+		this.onChange?.(this.getSnapshot())
+	}
 }
diff --git a/core/src/tests/composables/useUnifiedSearch.spec.ts b/core/src/tests/composables/useUnifiedSearch.spec.ts
new file mode 100644
index 0000000000000..9dea450f22cc9
--- /dev/null
+++ b/core/src/tests/composables/useUnifiedSearch.spec.ts
@@ -0,0 +1,136 @@
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { mount } from '@vue/test-utils'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, h } from 'vue'
+
+const service = vi.hoisted(() => ({
+	search: vi.fn(),
+	getProviders: vi.fn(),
+	getContacts: vi.fn(),
+}))
+vi.mock('../../services/UnifiedSearchService.js', () => service)
+
+import { useUnifiedSearch } from '../../composables/useUnifiedSearch.ts'
+
+/**
+ * Deferred stand-in for a provider's `search()` return value. Resolve it to
+ * make that provider arrive on demand. Mirrors the controller spec's helper.
+ */
+function deferredProvider() {
+	const { promise, resolve, reject } = Promise.withResolvers<{ entries: unknown[] }>()
+	return {
+		cancel: vi.fn(),
+		request: async () => {
+			const { entries } = await promise
+			return { data: { ocs: { data: { entries } } } }
+		},
+		resolve: (entries: unknown[] = []) => resolve({ entries }),
+		reject,
+	}
+}
+
+/**
+ * Deferred stand-in that serves successive pages, for exercising loadMore.
+ */
+function pagedProvider() {
+	const pages: ReturnType<typeof Promise.withResolvers<{ entries: unknown[], cursor: string | null, hasMore: boolean }>>[] = []
+	const pageAt = (index: number) => (pages[index] ??= Promise.withResolvers())
+	let call = 0
+	return {
+		cancel: vi.fn(),
+		request: async () => {
+			const data = await pageAt(call++).promise
+			return { data: { ocs: { data } } }
+		},
+		resolvePage: (index: number, data: { entries: unknown[], cursor: string | null, hasMore: boolean }) => pageAt(index).resolve(data),
+	}
+}
+
+/**
+ * Register one deferred provider per category type on the mocked service.
+ */
+function mockProviders(types: string[]) {
+	const providers = Object.fromEntries(types.map((type) => [type, deferredProvider()]))
+	service.search.mockImplementation(({ type }: { type: string }) => providers[type])
+	return providers
+}
+
+/**
+ * Run the composable inside a real setup context (so onBeforeUnmount is wired)
+ * and hand the returned API plus the wrapper back to the test.
+ */
+function mountComposable() {
+	let api!: ReturnType<typeof useUnifiedSearch>
+	const wrapper = mount(defineComponent({
+		setup() {
+			api = useUnifiedSearch()
+			return () => h('div')
+		},
+	}))
+	return { wrapper, api }
+}
+
+beforeEach(() => {
+	vi.useFakeTimers()
+})
+
+afterEach(() => {
+	vi.clearAllMocks()
+	vi.useRealTimers()
+})
+
+describe('useUnifiedSearch', () => {
+	it('exposes an empty snapshot before any search', () => {
+		const { api } = mountComposable()
+
+		expect(api.searchStates.value).toEqual({})
+	})
+
+	it('reflects controller state reactively as a search resolves', async () => {
+		const providers = mockProviders(['files'])
+		const { api } = mountComposable()
+
+		api.search('query', ['files'])
+		providers.files.resolve(['a result'])
+		await vi.advanceTimersByTimeAsync(0)
+
+		expect(api.searchStates.value.files).toMatchObject({
+			status: 'loaded',
+			entries: ['a result'],
+		})
+	})
+
+	it('appends a page through loadMore and reflects it', async () => {
+		const files = pagedProvider()
+		service.search.mockReturnValue(files)
+		const { api } = mountComposable()
+
+		api.search('query', ['files'])
+		files.resolvePage(0, { entries: ['a'], cursor: 'cursor-1', hasMore: true })
+		await vi.advanceTimersByTimeAsync(0)
+
+		api.loadMore('files')
+		files.resolvePage(1, { entries: ['b'], cursor: 'cursor-2', hasMore: false })
+		await vi.advanceTimersByTimeAsync(0)
+
+		expect(api.searchStates.value.files).toMatchObject({
+			status: 'loaded',
+			entries: ['a', 'b'],
+			hasMore: false,
+		})
+	})
+
+	it('cancels in-flight requests when the component unmounts', () => {
+		const providers = mockProviders(['files'])
+		const { wrapper, api } = mountComposable()
+
+		api.search('query', ['files'])
+		wrapper.destroy()
+
+		// Unmount must dispose the controller, which cancels the pending request.
+		expect(providers.files.cancel).toHaveBeenCalledOnce()
+	})
+})
diff --git a/core/src/tests/services/UnifiedSearchController.spec.ts b/core/src/tests/services/UnifiedSearchController.spec.ts
index af5daca8fcbe7..6b499f93133dd 100644
--- a/core/src/tests/services/UnifiedSearchController.spec.ts
+++ b/core/src/tests/services/UnifiedSearchController.spec.ts
@@ -307,6 +307,84 @@ describe('UnifiedSearchController', () => {
 		})
 	})
 
+	describe('change notification', () => {
+		it('notifies once the initial loading states are set, before any provider resolves', () => {
+			service.search.mockImplementation(() => deferredProvider())
+			const onChange = vi.fn()
+
+			const searchController = new UnifiedSearchController(onChange)
+			searchController.search('query', ['files', 'talk'])
+
+			// The adapter must be able to paint the loading spinners straight away,
+			// without waiting for the first response to land.
+			expect(onChange).toHaveBeenCalled()
+			expect(searchController.getSnapshot()).toEqual({ files: loading, talk: loading })
+		})
+
+		it('notifies when a category resolves', async () => {
+			const providers = mockProviders(['files'])
+			const onChange = vi.fn()
+
+			const searchController = new UnifiedSearchController(onChange)
+			searchController.search('query', ['files'])
+			onChange.mockClear()
+
+			providers.files.resolve(['Files result'])
+			await vi.advanceTimersByTimeAsync(0)
+
+			expect(onChange).toHaveBeenCalled()
+		})
+
+		it('notifies when loadMore appends a page', async () => {
+			const files = pagedProvider()
+			service.search.mockReturnValue(files)
+			const onChange = vi.fn()
+
+			const searchController = new UnifiedSearchController(onChange)
+			searchController.search('query', ['files'])
+			files.resolvePage(0, { entries: ['a'], cursor: 'cursor-1', hasMore: true })
+			await vi.advanceTimersByTimeAsync(0)
+			onChange.mockClear()
+
+			searchController.loadMore('files')
+			files.resolvePage(1, { entries: ['b'], cursor: 'cursor-2', hasMore: false })
+			await vi.advanceTimersByTimeAsync(0)
+
+			expect(onChange).toHaveBeenCalled()
+		})
+
+		it('notifies when the reveal timer unblocks a category', async () => {
+			const providers = mockProviders(['files', 'talk'])
+			const onChange = vi.fn()
+
+			const searchController = new UnifiedSearchController(onChange)
+			searchController.search('query', ['files', 'talk'])
+
+			// talk arrives out of order and is blocked behind files (still loading).
+			providers.talk.resolve(['Talk result'])
+			await vi.advanceTimersByTimeAsync(0)
+			expect(searchController.getSnapshot().talk.status).toBe('blocked')
+			onChange.mockClear()
+
+			// The timer flush promotes it to loaded; the adapter must hear about it.
+			await vi.advanceTimersByTimeAsync(REVEAL_INTERVAL_MS)
+			expect(searchController.getSnapshot().talk.status).toBe('loaded')
+			expect(onChange).toHaveBeenCalled()
+		})
+
+		it('works without an onChange callback', async () => {
+			const providers = mockProviders(['files'])
+
+			const searchController = new UnifiedSearchController()
+			searchController.search('query', ['files'])
+			providers.files.resolve(['Files result'])
+
+			// The callback is optional; a headless controller must still run.
+			await expect(vi.advanceTimersByTimeAsync(0)).resolves.not.toThrow()
+			expect(searchController.getSnapshot().files.status).toBe('loaded')
+		})
+	})
+
 	describe('pagination', () => {
 		it('appends the next page of results when loadMore is called', async () => {
 			const files = pagedProvider()
@@ -340,6 +418,33 @@ describe('UnifiedSearchController', () => {
 			})
 		})
 
+		it('reports a loading state, with page 1 still visible, while the next page is in flight', async () => {
+			const files = pagedProvider()
+			service.search.mockReturnValue(files)
+			const onChange = vi.fn()
+
+			const searchController = new UnifiedSearchController(onChange)
+			searchController.search('query', ['files'])
+
+			files.resolvePage(0, { entries: ['a'], cursor: 'cursor-1', hasMore: true })
+			await vi.advanceTimersByTimeAsync(0)
+			onChange.mockClear()
+
+			// Page 2 is requested but has not resolved yet.
+			searchController.loadMore('files')
+
+			// The view needs a loading signal for the paging spinner, without losing
+			// the results already on screen, and the adapter must be told at the start.
+			expect(searchController.getSnapshot().files).toEqual({
+				status: 'loading',
+				entries: ['a'],
+				cursor: 'cursor-1',
+				hasMore: true,
+				loadMoreFailed: false,
+			})
+			expect(onChange).toHaveBeenCalled()
+		})
+
 		it('re-dispatches with the stored cursor', async () => {
 			const files = pagedProvider()
 			service.search.mockReturnValue(files)
@@ -425,6 +530,50 @@ describe('UnifiedSearchController', () => {
 			// The initial search is the only dispatch; loadMore must not fire another.
 			expect(service.search).toHaveBeenCalledTimes(1)
 		})
+
+		it('does not mutate a snapshot already handed out when a later page loads', async () => {
+			const files = pagedProvider()
+			service.search.mockReturnValue(files)
+
+			const searchController = new UnifiedSearchController()
+			searchController.search('query', ['files'])
+
+			files.resolvePage(0, { entries: ['a'], cursor: 'cursor-1', hasMore: true })
+			await vi.advanceTimersByTimeAsync(0)
+
+			// A consumer reads and holds the snapshot, the way the Vue adapter does.
+			const firstPage = searchController.getSnapshot()
+
+			searchController.loadMore('files')
+			files.resolvePage(1, { entries: ['b'], cursor: 'cursor-2', hasMore: false })
+			await vi.advanceTimersByTimeAsync(0)
+
+			// loadMore must not reach back into an array a previous getSnapshot()
+			// already exposed; the earlier snapshot stays frozen.
+			expect(firstPage.files.entries).toEqual(['a'])
+		})
+
+		it('hands out fresh state and entries references across a loadMore', async () => {
+			const files = pagedProvider()
+			service.search.mockReturnValue(files)
+
+			const searchController = new UnifiedSearchController()
+			searchController.search('query', ['files'])
+
+			files.resolvePage(0, { entries: ['a'], cursor: 'cursor-1', hasMore: true })
+			await vi.advanceTimersByTimeAsync(0)
+			const before = searchController.getSnapshot()
+
+			searchController.loadMore('files')
+			files.resolvePage(1, { entries: ['b'], cursor: 'cursor-2', hasMore: false })
+			await vi.advanceTimersByTimeAsync(0)
+			const after = searchController.getSnapshot()
+
+			// A new object and array identity on each change is what lets the adapter's
+			// ref reassignment re-render instead of aliasing a mutated object.
+			expect(after.files).not.toBe(before.files)
+			expect(after.files.entries).not.toBe(before.files.entries)
+		})
 	})
 
 	describe('filter pass-through', () => {

From c3ee5c22d8b20dbd976316a60f09ae3b6d3dc135 Mon Sep 17 00:00:00 2001
From: Peter Ringelmann <peter.ringelmann@nextcloud.com>
Date: Tue, 14 Jul 2026 10:25:30 +0200
Subject: [PATCH 3/3] feat(core): drive the unified search modal from the
 search controller

Signed-off-by: Peter Ringelmann <peter.ringelmann@nextcloud.com>
---
 .../UnifiedSearch/UnifiedSearchModal.vue      | 228 ++++++++----------
 core/src/composables/useUnifiedSearch.ts      |   4 +-
 core/src/services/UnifiedSearchController.ts  |  16 +-
 .../components/UnifiedSearchModal.spec.ts     | 218 ++++++++++++++++-
 .../services/UnifiedSearchController.spec.ts  |  46 ++++
 5 files changed, 376 insertions(+), 136 deletions(-)

diff --git a/core/src/components/UnifiedSearch/UnifiedSearchModal.vue b/core/src/components/UnifiedSearch/UnifiedSearchModal.vue
index a91d0138a4894..b3078b633d325 100644
--- a/core/src/components/UnifiedSearch/UnifiedSearchModal.vue
+++ b/core/src/components/UnifiedSearch/UnifiedSearchModal.vue
@@ -153,7 +153,7 @@
 								v-bind="result" />
 						</ul>
 						<div class="result-footer">
-							<NcButton v-if="providerResult.results.length === providerResult.limit" variant="tertiary-no-background" @click="loadMoreResultsForProvider(providerResult)">
+							<NcButton v-if="providerResult.hasMore" variant="tertiary-no-background" @click="loadMoreResultsForProvider(providerResult)">
 								{{ t('core', 'Load more results') }}
 								<template #icon>
 									<IconDotsHorizontal :size="20" />
@@ -183,7 +183,7 @@
 									v-bind="result" />
 							</ul>
 							<div class="result-footer">
-								<NcButton v-if="providerResult.results.length === providerResult.limit" variant="tertiary-no-background" @click="loadMoreResultsForProvider(providerResult)">
+								<NcButton v-if="providerResult.hasMore" variant="tertiary-no-background" @click="loadMoreResultsForProvider(providerResult)">
 									{{ t('core', 'Load more results') }}
 									<template #icon>
 										<IconDotsHorizontal :size="20" />
@@ -207,6 +207,7 @@
 
 <script lang="ts">
 import type { FocusTrap } from 'focus-trap'
+import type { CategorySearchParams } from '../../services/UnifiedSearchController.ts'
 
 import { subscribe } from '@nextcloud/event-bus'
 import { loadState } from '@nextcloud/initial-state'
@@ -235,8 +236,9 @@ import CustomDateRangeModal from './CustomDateRangeModal.vue'
 import SearchableList from './SearchableList.vue'
 import FilterChip from './SearchFilterChip.vue'
 import SearchResult from './SearchResult.vue'
+import { useUnifiedSearch } from '../../composables/useUnifiedSearch.ts'
 import { unifiedSearchLogger } from '../../logger.js'
-import { getContacts, getProviders, search as unifiedSearch } from '../../services/UnifiedSearchService.js'
+import { getContacts, getProviders } from '../../services/UnifiedSearchService.js'
 import { useSearchStore } from '../../store/unified-search-external-filters.js'
 
 export default defineComponent({
@@ -299,9 +301,14 @@ export default defineComponent({
 		const currentLocation = useBrowserLocation()
 		const searchStore = useSearchStore()
 		const isSmallMobile = useIsSmallMobile()
+
+		const { searchStates, search, loadMore } = useUnifiedSearch()
+
 		return {
 			t,
-
+			searchStates,
+			search,
+			loadMore,
 			currentLocation,
 			externalFilters: searchStore.externalFilters,
 			isSmallMobile,
@@ -313,7 +320,6 @@ export default defineComponent({
 			providers: [],
 			providerActionMenuIsOpen: false,
 			dateActionMenuIsOpen: false,
-			providerResultLimit: 5,
 			dateFilter: {
 				id: 'date',
 				type: 'date',
@@ -324,13 +330,10 @@ export default defineComponent({
 
 			personFilter: { id: 'person', type: 'person', name: '' },
 			filteredProviders: [],
-			searching: false,
 			searchQuery: '',
-			lastSearchQuery: '',
 			placessearchTerm: '',
 			dateTimeFilter: null,
 			filters: [],
-			results: [],
 			contacts: [],
 			showDateRangeModal: false,
 			initialized: false,
@@ -347,6 +350,11 @@ export default defineComponent({
 			return this.searchQuery.length === 0
 		},
 
+		// True while any category is still fetching.
+		searching() {
+			return Object.values(this.searchStates).some((state) => state.status === 'loading')
+		},
+
 		hasNoResults() {
 			return !this.isEmptySearch && this.results.length === 0
 		},
@@ -356,14 +364,12 @@ export default defineComponent({
 		},
 
 		showEmptyContentInfo() {
-			return this.isEmptySearch || this.hasNoResults
+			// A too-short query never searches, so any results still held are stale for it.
+			return this.isEmptySearch || this.isSearchQueryTooShort || this.hasNoResults
 		},
 
 		emptyContentMessage() {
-			if (this.searching && this.hasNoResults) {
-				return t('core', 'Searching …')
-			}
-
+			// Order matters: a query shrinking below the minimum mid-search shows the prompt, not "searching".
 			if (this.isSearchQueryTooShort) {
 				switch (this.minSearchLength) {
 					case 1:
@@ -373,6 +379,11 @@ export default defineComponent({
 				}
 			}
 
+			// Also "searching" before providers load: a query is pending but nothing is in flight yet.
+			if ((this.searching || !this.initialized) && this.hasNoResults) {
+				return t('core', 'Searching …')
+			}
+
 			return t('core', 'No matching results')
 		},
 
@@ -402,6 +413,25 @@ export default defineComponent({
 			return this.providerActionMenuIsOpen || this.dateActionMenuIsOpen || this.showDateRangeModal
 		},
 
+		results() {
+			const contentFilterTypes = this.filters
+				.filter((filter) => filter.type !== 'provider')
+				.map((filter) => filter.type)
+
+			return Object.entries(this.searchStates)
+				.filter(([, state]) => state.entries.length > 0 && (state.status === 'loaded' || state.status === 'loading'))
+				.map(([providerId, state]) => {
+					const provider = this.providers.find((p) => p.id === providerId)
+					const supportsActiveFilters = this.providerIsCompatibleWithFilters(provider, contentFilterTypes)
+					return {
+						...provider,
+						results: state.entries,
+						hasMore: state.hasMore,
+						supportsActiveFilters,
+					}
+				})
+		},
+
 		filteredResults() {
 			const isInFolderAtRoot = (result) => {
 				if (result.id !== 'in-folder') {
@@ -457,9 +487,15 @@ export default defineComponent({
 							this.contacts = this.mapContacts(contacts)
 							unifiedSearchLogger.debug('Search providers and contacts initialized:', { providers: this.providers, contacts: this.contacts })
 							this.initialized = true
+							// Run any query find() deferred while providers were still loading.
+							if (this.open && this.searchQuery) {
+								this.find(this.searchQuery)
+							}
 						})
 						.catch((error) => {
 							unifiedSearchLogger.error(error)
+							// Mark init done even on failure, so the empty state shows "no results" not a stuck "searching".
+							this.initialized = true
 						})
 				}
 				if (this.searchQuery) {
@@ -604,129 +640,65 @@ export default defineComponent({
 			this.$emit('update:open', false)
 		},
 
-		find(query: string, providersToSearchOverride = null) {
+		find(query: string) {
 			if (this.isSearchQueryTooShort) {
-				this.results = []
-				this.searching = false
 				return
 			}
 
-			// Reset the provider result limit when performing a new search
-			if (query !== this.lastSearchQuery) {
-				this.providerResultLimit = 5
+			// Providers load asynchronously on open. Searching before they arrive dispatches an
+			// empty list and lands on "no results", so defer; the init handler re-runs once ready.
+			if (!this.initialized) {
+				return
 			}
-			this.lastSearchQuery = query
-
-			this.searching = true
-			const newResults = []
-			const providersToSearch = providersToSearchOverride || (this.filteredProviders.length > 0 ? this.filteredProviders : this.providers)
-			const searchProvider = (provider) => {
-				const params = {
-					type: provider.searchFrom ?? provider.id,
-					query,
-					cursor: null,
-					extraQueries: provider.extraParams,
-				}
-
-				// This block of filter checks should be dynamic somehow and should be handled in
-				// nextcloud/search lib
-				const contentFilterTypes = this.filters
-					.filter((f) => f.type !== 'provider')
-					.map((f) => f.type)
-				const supportsActiveFilters = contentFilterTypes.length === 0
-					|| contentFilterTypes.every((type) => this.providerIsCompatibleWithFilters(provider, [type]))
 
-				const baseProvider = provider.searchFrom
-					? this.providers.find((p) => p.id === provider.searchFrom) ?? provider
-					: provider
+			// With provider filters, search exactly those (opted in even if external).
+			// Otherwise search all providers except external ones not switched on.
+			const searchable = this.filteredProviders.length > 0
+				? this.filteredProviders
+				: this.providers.filter((provider) => this.searchExternalResources || !provider.isExternalProvider)
+
+			// One param set per category, keyed by provider id, for the controller to
+			// dispatch. It reuses the same params on loadMore, so filters page correctly.
+			const params = {}
+			searchable.forEach((provider) => {
+				params[provider.id] = this.buildCategoryParams(provider)
+			})
 
-				const activeFilters = this.filters.filter((filter) => {
-					return filter.type !== 'provider' && this.providerIsCompatibleWithFilters(provider, [filter.type])
-				})
+			this.search(query, searchable.map((provider) => provider.id), params)
+		},
 
-				activeFilters.forEach((filter) => {
-					switch (filter.type) {
-						case 'date':
-							if (baseProvider.filters?.since && baseProvider.filters?.until) {
-								params.since = this.dateFilter.startFrom
-								params.until = this.dateFilter.endAt
-							}
-							break
-						case 'person':
-							if (baseProvider.filters?.person) {
-								params.person = this.personFilter.user
-							}
-							break
-					}
-				})
+		/**
+		 * Translate a provider plus the active filters into controller search params.
+		 *
+		 * @param provider the provider to build params for
+		 */
+		buildCategoryParams(provider): CategorySearchParams {
+			const params: CategorySearchParams = {
+				extraQueries: provider.extraParams,
+			}
 
-				if (this.providerResultLimit > 5) {
-					params.limit = this.providerResultLimit
-					unifiedSearchLogger.debug('Limiting search to', params.limit)
-				}
+			// `searchFrom` aliases a provider onto another provider's backend. The
+			// controller dispatches on this `type` override; a plain provider sends none.
+			if (provider.searchFrom) {
+				params.type = provider.searchFrom
+			}
 
-				const shouldSkipSearch = !this.searchExternalResources && provider.isExternalProvider
-				const wasManuallySelected = this.filteredProviders.some((filteredProvider) => filteredProvider.id === provider.id)
-				// if the provider is an external resource and the user has not manually selected it, skip the search
-				if (shouldSkipSearch && !wasManuallySelected) {
-					this.searching = false
+			// Only attach a filter the provider supports. providerIsCompatibleWithFilters resolves
+			// the backing provider (via searchFrom) and checks its capabilities, so it's enough here.
+			this.filters.forEach((filter) => {
+				if (filter.type === 'provider' || !this.providerIsCompatibleWithFilters(provider, [filter.type])) {
 					return
 				}
-
-				const request = unifiedSearch(params).request
-
-				request().then((response) => {
-					newResults.push({
-						...provider,
-						results: response.data.ocs.data.entries,
-						limit: params.limit ?? 5,
-						supportsActiveFilters,
-					})
-
-					unifiedSearchLogger.debug('Unified search results:', { results: this.results, newResults })
-
-					this.updateResults(newResults)
-					this.searching = false
-				})
-			}
-
-			providersToSearch.forEach(searchProvider)
-		},
-
-		updateResults(newResults) {
-			let updatedResults = [...this.results]
-			// If filters are applied, remove any previous results for providers that are not in current filters
-			if (this.filters.length > 0) {
-				updatedResults = updatedResults.filter((result) => {
-					return this.filters.some((filter) => filter.id === result.id)
-				})
-			}
-			// Process the new results
-			newResults.forEach((newResult) => {
-				const existingResultIndex = updatedResults.findIndex((result) => result.id === newResult.id)
-				if (existingResultIndex !== -1) {
-					if (newResult.results.length === 0) {
-						// If the new results data has no matches for and existing result, remove the existing result
-						updatedResults.splice(existingResultIndex, 1)
-					} else {
-						// If input triggered a change in existing results, update existing result
-						updatedResults.splice(existingResultIndex, 1, newResult)
-					}
-				} else if (newResult.results.length > 0) {
-					// Push the new result to the array only if its results array is not empty
-					updatedResults.push(newResult)
+				if (filter.type === 'date') {
+					// The controller/API expect ISO strings, not Date objects.
+					params.since = this.dateFilter.startFrom?.toISOString()
+					params.until = this.dateFilter.endAt?.toISOString()
+				} else if (filter.type === 'person') {
+					params.person = this.personFilter.user
 				}
 			})
-			const sortedResults = updatedResults.slice(0)
-			// Order results according to provider preference
-			sortedResults.sort((a, b) => {
-				const aProvider = this.providers.find((provider) => provider.id === a.id)
-				const bProvider = this.providers.find((provider) => provider.id === b.id)
-				const aOrder = aProvider ? aProvider.order : 0
-				const bOrder = bProvider ? bProvider.order : 0
-				return aOrder - bOrder
-			})
-			this.results = sortedResults
+
+			return params
 		},
 
 		mapContacts(contacts) {
@@ -768,13 +740,14 @@ export default defineComponent({
 			unifiedSearchLogger.debug('Person filter applied', { person })
 		},
 
-		async loadMoreResultsForProvider(provider) {
-			this.providerResultLimit += 5
-			this.find(this.searchQuery, [provider])
+		loadMoreResultsForProvider(provider) {
+			// The controller pages from its stored cursor and reuses the original
+			// per-category params, so we only need to hand it the provider id.
+			this.loadMore(provider.id)
 		},
 
-		addProviderFilter(providerFilter, loadMoreResultsForProvider = false) {
-			unifiedSearchLogger.debug('Applying provider filter', { providerFilter, loadMoreResultsForProvider })
+		addProviderFilter(providerFilter) {
+			unifiedSearchLogger.debug('Applying provider filter', { providerFilter })
 			if (!providerFilter.id) {
 				return
 			}
@@ -786,7 +759,6 @@ export default defineComponent({
 				const isProviderFilterApplied = this.filteredProviders.some((provider) => provider.id === providerFilter.id)
 				providerFilter.callback(!isProviderFilterApplied)
 			}
-			this.providerResultLimit = loadMoreResultsForProvider ? this.providerResultLimit : 5
 			this.providerActionMenuIsOpen = false
 			// With the possibility for other apps to add new filters
 			// Resulting in a possible id/provider collision
diff --git a/core/src/composables/useUnifiedSearch.ts b/core/src/composables/useUnifiedSearch.ts
index 5100968f6ed59..a3fdb3f258d83 100644
--- a/core/src/composables/useUnifiedSearch.ts
+++ b/core/src/composables/useUnifiedSearch.ts
@@ -3,6 +3,8 @@
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 
+import type { CategorySearchState } from '../services/UnifiedSearchController.ts'
+
 import { onUnmounted, shallowRef } from 'vue'
 import { UnifiedSearchController } from '../services/UnifiedSearchController.ts'
 
@@ -10,7 +12,7 @@ import { UnifiedSearchController } from '../services/UnifiedSearchController.ts'
  * Reactive adapter over UnifiedSearchController for use in an SFC.
  */
 export function useUnifiedSearch() {
-	const searchStates = shallowRef({})
+	const searchStates = shallowRef<Record<string, CategorySearchState>>({})
 
 	const controller = new UnifiedSearchController((states) => {
 		searchStates.value = states
diff --git a/core/src/services/UnifiedSearchController.ts b/core/src/services/UnifiedSearchController.ts
index 136de96fbceeb..d4eb483063702 100644
--- a/core/src/services/UnifiedSearchController.ts
+++ b/core/src/services/UnifiedSearchController.ts
@@ -7,7 +7,7 @@ import { search as unifiedSearch } from './UnifiedSearchService.js'
 
 type CategorySearchStatus = 'loading' | 'loaded' | 'failed' | 'blocked'
 
-interface CategorySearchState {
+export interface CategorySearchState {
 	status: CategorySearchStatus
 	entries: unknown[]
 	cursor: string | null
@@ -15,7 +15,7 @@ interface CategorySearchState {
 	loadMoreFailed: boolean
 }
 
-interface CategorySearchParams {
+export interface CategorySearchParams {
 	type?: string
 	since?: string
 	until?: string
@@ -153,8 +153,10 @@ export class UnifiedSearchController {
 			}
 
 			const { entries, cursor, hasMore } = response.data.ocs.data
+			// Decide blocked vs loaded once, here at settle. Reconcile only promotes after this
+			// (never re-blocks), so this is the only place a category becomes blocked.
 			this.patchStates({ [category]: {
-				status: 'loaded',
+				status: this.shouldBlockCategory(category, categories) ? 'blocked' : 'loaded',
 				entries,
 				cursor,
 				hasMore,
@@ -178,10 +180,14 @@ export class UnifiedSearchController {
 
 	private reconcileCategoryStatuses(categories: string[]): void {
 		categories.forEach((category) => {
-			if (['loading', 'failed'].includes(this.searchStates[category].status)) {
+			// Promotion only: reveal a blocked category once its predecessors clear, never demote.
+			// A revealed category must stay revealed, else it flickers when a slower one settles.
+			if (this.searchStates[category].status !== 'blocked') {
 				return
 			}
-			this.patchStates({ [category]: { status: this.shouldBlockCategory(category, categories) ? 'blocked' : 'loaded' } })
+			if (!this.shouldBlockCategory(category, categories)) {
+				this.patchStates({ [category]: { status: 'loaded' } })
+			}
 		})
 	}
 
diff --git a/core/src/tests/components/UnifiedSearchModal.spec.ts b/core/src/tests/components/UnifiedSearchModal.spec.ts
index 33e2ed8318b45..7a033a1b6e651 100644
--- a/core/src/tests/components/UnifiedSearchModal.spec.ts
+++ b/core/src/tests/components/UnifiedSearchModal.spec.ts
@@ -11,12 +11,20 @@ vi.mock('@nextcloud/vue/composables/useIsMobile', () => ({
 	useIsSmallMobile: () => mobile,
 	useIsMobile: () => ref(false),
 }))
+// Controllable stand-in for the composable so tests can drive searchStates and
+// spy on the commands the modal issues to the controller.
+const composable = vi.hoisted(() => ({ api: {} as Record<string, unknown> }))
+vi.mock('../../composables/useUnifiedSearch.ts', () => ({
+	useUnifiedSearch: () => composable.api,
+}))
 vi.mock('@nextcloud/event-bus', () => ({ subscribe: vi.fn(), emit: vi.fn() }))
-vi.mock('@nextcloud/initial-state', () => ({ loadState: vi.fn(() => ([])) }))
+vi.mock('@nextcloud/initial-state', () => ({
+	loadState: vi.fn((_app: string, _key: string, fallback: unknown) => fallback),
+}))
 vi.mock('../../services/UnifiedSearchService.js', () => ({
 	getProviders: vi.fn(() => Promise.resolve([])),
 	getContacts: vi.fn(() => Promise.resolve([])),
-	search: vi.fn(() => ({ request: Promise.resolve({ data: { ocs: { data: { entries: [] } } } }), cancel: vi.fn() })),
+	search: vi.fn(() => ({ request: () => Promise.resolve({ data: { ocs: { data: { entries: [] } } } }), cancel: vi.fn() })),
 }))
 vi.mock('../../store/unified-search-external-filters.js', () => ({
 	useSearchStore: () => ({ externalFilters: [], scopeToApp: false }),
@@ -24,6 +32,21 @@ vi.mock('../../store/unified-search-external-filters.js', () => ({
 
 import UnifiedSearchModal from '../../components/UnifiedSearch/UnifiedSearchModal.vue'
 
+let searchSpy: ReturnType<typeof vi.fn>
+let loadMoreSpy: ReturnType<typeof vi.fn>
+let searchStates: ReturnType<typeof ref>
+
+// VTU v1 (the legacy Vue 2.7 project) has no flushPromises export; drain the
+// microtask + timer queue so resolved provider fetches and their .then run.
+const flushPromises = () => new Promise((resolve) => setTimeout(resolve))
+
+/**
+ * A loaded, non-empty category state for the snapshot.
+ */
+function loaded(entries: unknown[], hasMore = false) {
+	return { status: 'loaded', entries, cursor: hasMore ? 'cursor-1' : null, hasMore, loadMoreFailed: false }
+}
+
 function factory(open = true) {
 	return shallowMount(UnifiedSearchModal, {
 		propsData: { open, query: '', localSearch: false },
@@ -33,6 +56,10 @@ function factory(open = true) {
 
 beforeEach(() => {
 	mobile.value = false
+	searchSpy = vi.fn()
+	loadMoreSpy = vi.fn()
+	searchStates = ref({})
+	composable.api = { searchStates, search: searchSpy, loadMore: loadMoreSpy }
 })
 afterEach(() => vi.clearAllMocks())
 
@@ -73,3 +100,190 @@ describe('UnifiedSearchModal mobile input', () => {
 		expect(wrapper.vm.searchQuery).toBe('5')
 	})
 })
+
+describe('UnifiedSearchModal controller wiring', () => {
+	it('renders a group per loaded, non-empty category and withholds the rest', async () => {
+		const wrapper = factory()
+		wrapper.vm.providers = [
+			{ id: 'files', name: 'Files', order: 0 },
+			{ id: 'talk', name: 'Talk', order: 1 },
+			{ id: 'deck', name: 'Deck', order: 2 },
+		]
+		searchStates.value = {
+			files: loaded([{ resourceUrl: '/a' }]),
+			talk: { status: 'blocked', entries: [{ resourceUrl: '/b' }], cursor: null, hasMore: false, loadMoreFailed: false },
+			deck: loaded([]),
+		}
+		wrapper.vm.searchQuery = 'query'
+		await wrapper.vm.$nextTick()
+
+		// files: loaded + non-empty -> shown. talk: blocked -> withheld. deck: empty -> dropped.
+		const titles = wrapper.findAll('.result-title').wrappers.map((w) => w.text())
+		expect(titles).toEqual(['Files'])
+	})
+
+	it('keeps a paging category on screen while its next page loads', async () => {
+		const wrapper = factory()
+		wrapper.vm.providers = [{ id: 'files', name: 'Files', order: 0 }]
+		// loadMore keeps page 1 visible but flips the category to 'loading' for the
+		// paging spinner. The group (and its rows) must not disappear during the refetch.
+		searchStates.value = {
+			files: { status: 'loading', entries: [{ resourceUrl: '/a' }], cursor: 'cursor-1', hasMore: true, loadMoreFailed: false },
+		}
+		wrapper.vm.searchQuery = 'query'
+		await wrapper.vm.$nextTick()
+
+		expect(wrapper.findAll('.result-title').wrappers.map((w) => w.text())).toEqual(['Files'])
+		expect(wrapper.vm.showEmptyContentInfo).toBe(false)
+	})
+
+	it('find() searches the provider ids in order and delegates to the controller', () => {
+		const wrapper = factory()
+		wrapper.vm.providers = [
+			{ id: 'files', name: 'Files', order: 0 },
+			{ id: 'talk', name: 'Talk', order: 1 },
+		]
+		wrapper.vm.initialized = true
+		wrapper.vm.searchQuery = 'hello'
+		wrapper.vm.find('hello')
+
+		expect(searchSpy).toHaveBeenCalledOnce()
+		const [query, categories] = searchSpy.mock.calls[0]
+		expect(query).toBe('hello')
+		expect(categories).toEqual(['files', 'talk'])
+	})
+
+	it('find() forwards a searchFrom type override and extraQueries per provider', () => {
+		const wrapper = factory()
+		wrapper.vm.providers = [
+			{ id: 'files', name: 'Files', order: 0, extraParams: { foo: 'bar' } },
+			{ id: 'in-folder', name: 'In folder', order: 1, searchFrom: 'files' },
+		]
+		wrapper.vm.initialized = true
+		wrapper.vm.searchQuery = 'hello'
+		wrapper.vm.find('hello')
+
+		const params = searchSpy.mock.calls[0][2]
+		// searchFrom alias dispatches to 'files' via the type override...
+		expect(params['in-folder']).toMatchObject({ type: 'files' })
+		// ...a plain provider carries no override, and extraParams flow through as extraQueries.
+		expect(params.files).toMatchObject({ extraQueries: { foo: 'bar' } })
+		expect(params.files.type).toBeUndefined()
+	})
+
+	it('find() converts the date filter to ISO strings and forwards person for compatible providers', () => {
+		const wrapper = factory()
+		wrapper.vm.providers = [
+			{ id: 'files', name: 'Files', order: 0, filters: { since: true, until: true, person: true } },
+		]
+		wrapper.vm.initialized = true
+		wrapper.vm.dateFilter = {
+			id: 'date',
+			type: 'date',
+			text: '',
+			startFrom: new Date('2026-01-01T00:00:00.000Z'),
+			endAt: new Date('2026-02-01T00:00:00.000Z'),
+		}
+		wrapper.vm.personFilter = { id: 'person', type: 'person', name: 'Alice', user: 'alice' }
+		wrapper.vm.filters = [wrapper.vm.dateFilter, wrapper.vm.personFilter]
+		wrapper.vm.searchQuery = 'hello'
+		wrapper.vm.find('hello')
+
+		expect(searchSpy.mock.calls[0][2].files).toMatchObject({
+			since: '2026-01-01T00:00:00.000Z',
+			until: '2026-02-01T00:00:00.000Z',
+			person: 'alice',
+		})
+	})
+
+	it('find() omits external providers that were not manually selected', () => {
+		const wrapper = factory()
+		wrapper.vm.providers = [
+			{ id: 'files', name: 'Files', order: 0 },
+			{ id: 'ext', name: 'External', order: 1, isExternalProvider: true },
+		]
+		wrapper.vm.initialized = true
+		wrapper.vm.searchExternalResources = false
+		wrapper.vm.filteredProviders = []
+		wrapper.vm.searchQuery = 'hello'
+		wrapper.vm.find('hello')
+
+		expect(searchSpy.mock.calls[0][1]).toEqual(['files'])
+	})
+
+	it('loadMore delegates to the controller with the provider id', () => {
+		const wrapper = factory()
+		wrapper.vm.loadMoreResultsForProvider({ id: 'files' })
+
+		expect(loadMoreSpy).toHaveBeenCalledWith('files')
+	})
+
+	it('hides stale results and shows the prompt when the query drops below the minimum length', async () => {
+		const wrapper = factory()
+		wrapper.vm.providers = [{ id: 'files', name: 'Files', order: 0 }]
+		wrapper.vm.minSearchLength = 3
+		// The controller still holds results from a previous, longer query...
+		searchStates.value = { files: loaded([{ resourceUrl: '/a' }]) }
+		wrapper.vm.searchQuery = 'ab'
+		await wrapper.vm.$nextTick()
+
+		// ...but they must not render for a query too short to have produced them.
+		expect(wrapper.findAll('.result-title')).toHaveLength(0)
+		expect(wrapper.vm.showEmptyContentInfo).toBe(true)
+	})
+
+	it('keeps the minimum-length prompt over "searching" when a query shrinks mid-flight', async () => {
+		const wrapper = factory()
+		wrapper.vm.providers = [{ id: 'files', name: 'Files', order: 0 }]
+		wrapper.vm.minSearchLength = 3
+		// A search started for a longer query is still loading when the query shrinks.
+		searchStates.value = { files: { status: 'loading', entries: [], cursor: null, hasMore: false, loadMoreFailed: false } }
+		wrapper.vm.searchQuery = 'ab'
+		await wrapper.vm.$nextTick()
+
+		expect(wrapper.vm.searching).toBe(true)
+		// The too-short prompt wins over the "searching" message.
+		expect(wrapper.vm.emptyContentMessage).toContain('Minimum search length')
+	})
+
+	it('defers a search until providers are initialized and reports it as searching', () => {
+		const wrapper = factory()
+		wrapper.vm.providers = [{ id: 'files', name: 'Files', order: 0 }]
+		wrapper.vm.searchQuery = 'hello'
+
+		// Providers have not loaded yet: a search here would dispatch against an empty
+		// list and settle instantly into "no results". It must be withheld instead...
+		wrapper.vm.find('hello')
+		expect(searchSpy).not.toHaveBeenCalled()
+		// ...and the empty state reads as searching, not "no results".
+		expect(wrapper.vm.emptyContentMessage).toContain('Searching')
+
+		// Once initialized, the same query dispatches normally.
+		wrapper.vm.initialized = true
+		wrapper.vm.find('hello')
+		expect(searchSpy).toHaveBeenCalledOnce()
+		expect(searchSpy.mock.calls[0][1]).toEqual(['files'])
+	})
+
+	it('runs a query typed before providers finished loading, once initialized', async () => {
+		const { getProviders } = await import('../../services/UnifiedSearchService.js')
+		;(getProviders as unknown as ReturnType<typeof vi.fn>).mockResolvedValueOnce([{ id: 'files', name: 'Files', order: 0 }])
+
+		// Open with a query already present: the open() handler starts the async provider
+		// fetch and calls find() before it resolves, so nothing is dispatched yet.
+		const wrapper = shallowMount(UnifiedSearchModal, {
+			propsData: { open: false, query: 'hello', localSearch: false },
+			global: { mocks: { t: (_: string, s: string) => s, n: (_: string, s: string) => s } },
+		})
+		// The focus trap needs a tabbable node the stubbed panel lacks; skip it here.
+		vi.spyOn(wrapper.vm, 'activateFocusTrap').mockImplementation(() => {})
+		await wrapper.setProps({ open: true })
+		expect(searchSpy).not.toHaveBeenCalled()
+
+		// Providers resolve -> the deferred query runs on its own, no extra keystroke.
+		await flushPromises()
+		expect(searchSpy).toHaveBeenCalledOnce()
+		expect(searchSpy.mock.calls[0][0]).toBe('hello')
+		expect(searchSpy.mock.calls[0][1]).toEqual(['files'])
+	})
+})
diff --git a/core/src/tests/services/UnifiedSearchController.spec.ts b/core/src/tests/services/UnifiedSearchController.spec.ts
index 6b499f93133dd..d958acd1929a2 100644
--- a/core/src/tests/services/UnifiedSearchController.spec.ts
+++ b/core/src/tests/services/UnifiedSearchController.spec.ts
@@ -245,6 +245,29 @@ describe('UnifiedSearchController', () => {
 		})
 	})
 
+	describe('result ordering', () => {
+		it('keeps categories in the order passed to search, regardless of which resolve first', async () => {
+			const providers = mockProviders(['files', 'talk', 'deck'])
+
+			const searchController = new UnifiedSearchController()
+			searchController.search('query', ['files', 'talk', 'deck'])
+
+			// Resolve in reverse priority order: lowest-priority provider first,
+			// highest-priority one last. If order followed arrival, this would flip it.
+			providers.deck.resolve(['deck result'])
+			await vi.advanceTimersByTimeAsync(0)
+			providers.talk.resolve(['talk result'])
+			await vi.advanceTimersByTimeAsync(0)
+			providers.files.resolve(['files result'])
+			await vi.advanceTimersByTimeAsync(0)
+
+			// Keys still follow the categories array: each category's slot is inserted
+			// synchronously (the 'loading' patch) before any request resolves, so
+			// arrival order cannot reorder the snapshot.
+			expect(Object.keys(searchController.getSnapshot())).toEqual(['files', 'talk', 'deck'])
+		})
+	})
+
 	describe('resetting between searches', () => {
 		it('drops categories that are not part of a newer, narrower search', async () => {
 			mockProviders(['files', 'talk', 'deck'])
@@ -734,5 +757,28 @@ describe('UnifiedSearchController', () => {
 
 			expect(searchController.getSnapshot().deck.status).toBe('blocked')
 		})
+
+		it('does not re-block a revealed category when a later category settles behind a still-loading one', async () => {
+			const providers = mockProviders(['files', 'talk', 'deck'])
+
+			const searchController = new UnifiedSearchController()
+			searchController.search('query', ['files', 'talk', 'deck'])
+
+			// talk arrives out of order and is blocked behind files (still loading).
+			providers.talk.resolve(['Talk result'])
+			await vi.advanceTimersByTimeAsync(0)
+			expect(searchController.getSnapshot().talk.status).toBe('blocked')
+
+			// The reveal timer promotes talk to loaded.
+			await vi.advanceTimersByTimeAsync(REVEAL_INTERVAL_MS)
+			expect(searchController.getSnapshot().talk.status).toBe('loaded')
+
+			// deck now settles while files is still loading. Reconcile must not push the
+			// already-revealed talk back to blocked (that flip-flop is the on-screen flicker);
+			// talk stays loaded.
+			providers.deck.resolve(['Deck result'])
+			await vi.advanceTimersByTimeAsync(0)
+			expect(searchController.getSnapshot().talk.status).toBe('loaded')
+		})
 	})
 })