@salesforce/templates 66.17.4 → 66.18.0

package/lib/templates/project/vueinternalapp/_p_/_m_/_w_/_a_/src/_f_/search/composables/useSearch.ts

@@ -0,0 +1,906 @@
+/**
+ * useSearch — Vue composable orchestrating configuration-driven multi-source search.
+ *
+ * Owns:
+ *  - global `q` (one search box drives all sources)
+ *  - per-source filters / sort / pagination (independent state per source)
+ *  - URL sync (debounced; namespace `s.<key>.f.<field>=...`)
+ *  - one batched GraphQL fetch on every state change
+ *
+ * Returns a per-source `controller` map plus aggregate loading/error flags.
+ * Rendering and routing are the caller's responsibility.
+ */
+
+import { computed, getCurrentScope, onScopeDispose, reactive, ref, watch } from "vue";
+import { useRoute, useRouter, type LocationQuery } from "vue-router";
+import { runSearch } from "../api/searchService";
+import {
+	GLOBAL_QUERY_KEY,
+	readSourceParams,
+	writeSourceParams,
+	type ActiveFilterValue,
+} from "../utils/filterUtils";
+import type { SortState } from "../utils/sortUtils";
+import { debounce } from "../utils/debounce";
+import type {
+	SourceConfig,
+	SourceController,
+	SourceResult,
+	SearchConfig,
+	SearchHandle,
+	SearchScope,
+	GlobalPagination,
+	MergedResultItem,
+} from "../types";
+import { ALL_SCOPE, parseScope } from "../types";
+import type { SourceRequest } from "../adapters/types";
+import { MIN_QUERY_LENGTH } from "../constants";
+// `getUIBundleId` supplies the search-query UIBundle id (the isolated swap
+// point) and is resolved by this caller BEFORE the sync query builder runs;
+// `resolveChannelId` derives the discovery channel id from a CMS result;
+// `useSearchableContentTypes` is the session-cached discovery hook;
+// `isValidCmsFqn` validates a selected FQN before it enters state or a query.
+import {
+	getUIBundleId,
+	getUserLanguage,
+	isConfiguredUIBundleId,
+} from "../adapters/cms/searchChannel";
+import { getOrgSupportsCmsSearch } from "../adapters/cms/api/orgApiVersionService";
+import { resolveChannelId } from "../adapters/cms/channelResolver";
+import { useSearchableContentTypes } from "../adapters/cms/composables/useSearchableContentTypes";
+import { isValidCmsFqn } from "../adapters/cms/contentTypeUtils";
+import { readLastChannelId, writeLastChannelId } from "../adapters/cms/contentTypeSessionCache";
+
+const URL_SYNC_DEBOUNCE_MS = 300;
+
+/**
+ * Returns true when `source` should participate in the current scope. Only the
+ * scope's `base` (`"all"` or a source key) decides membership — a
+ * `"<cmsKey>:<fqn>"` scope has `base === <cmsKey>`, so it naturally includes ONLY
+ * that CMS source and drops every SObject source (CMS-only search).
+ */
+function isSourceInScope(scope: SearchScope, sourceKey: string): boolean {
+	const { base } = parseScope(scope);
+	return base === ALL_SCOPE || base === sourceKey;
+}
+
+/**
+ * Validates a raw scope string against the config. Accepts `"all"`, any source
+ * key, and the `"<cmsKey>:<fqn>"` form (base must be a CMS source and the FQN
+ * must pass `isValidCmsFqn`). Returns a safe scope, falling back to `"all"`.
+ */
+function validateScope(config: SearchConfig, raw: string): SearchScope {
+	if (raw === ALL_SCOPE) return ALL_SCOPE;
+	const { base, cmsFqn } = parseScope(raw);
+	const source = config.sources.find((s) => s.key === base);
+	if (!source) return ALL_SCOPE;
+	if (cmsFqn !== undefined) {
+		// A content-type scope is only valid on a CMS source with a well-formed FQN.
+		return source.kind === "cms" && isValidCmsFqn(cmsFqn) ? raw : ALL_SCOPE;
+	}
+	return raw;
+}
+
+interface SourceLocalState {
+	filters: ActiveFilterValue[];
+	sort: SortState | null;
+	pageSize: number;
+	pageIndex: number;
+	afterCursor: string | undefined;
+	cursorStack: string[];
+}
+
+/** Defaults applied when `config.pagination` is omitted. */
+const DEFAULT_PAGE_SIZE = 10;
+const DEFAULT_PAGE_SIZE_OPTIONS = [10, 25, 50];
+
+interface ResolvedPagination {
+	mode: "per-source" | "merged";
+	mergeOrder: "sequential" | "interleaved" | "proportional";
+	pageSize: number;
+	pageSizeOptions: number[];
+}
+
+/** Resolves the single global pagination config, filling in defaults. */
+export function resolvePagination(config: SearchConfig): ResolvedPagination {
+	const p = config.pagination;
+	const pageSizeOptions =
+		p?.pageSizeOptions && p.pageSizeOptions.length > 0
+			? p.pageSizeOptions
+			: DEFAULT_PAGE_SIZE_OPTIONS;
+	return {
+		mode: p?.mode ?? "per-source",
+		mergeOrder: p?.mergeOrder ?? "sequential",
+		pageSize: p?.pageSize ?? pageSizeOptions[0] ?? DEFAULT_PAGE_SIZE,
+		pageSizeOptions,
+	};
+}
+
+/** Clamps a requested size to the configured options. */
+function validatePageSize(pagination: ResolvedPagination, size: number): number {
+	const valid = pagination.pageSizeOptions;
+	if (valid.length === 0) return size;
+	return valid.includes(size) ? size : pagination.pageSize;
+}
+
+export function initSourceState(
+	source: SourceConfig,
+	params: URLSearchParams,
+	pagination: ResolvedPagination,
+): SourceLocalState {
+	// `filterBy` / `defaultSort` are SObject-only — a CMS source has neither, so
+	// it seeds with no filters and no default sort.
+	const filterBy = source.kind === "sobject" ? (source.filterBy ?? []) : [];
+	const defaultSort = source.kind === "sobject" ? (source.defaultSort ?? null) : null;
+	const read = readSourceParams(params, source.key, filterBy);
+	const sort = read.sort ?? defaultSort;
+	const pageSize = validatePageSize(pagination, read.pageSize ?? pagination.pageSize);
+	return {
+		filters: read.filters,
+		sort,
+		pageSize,
+		// Cursors aren't persisted to the URL, so always seed the first page (page param ignored on read).
+		pageIndex: 0,
+		afterCursor: undefined,
+		cursorStack: [],
+	};
+}
+
+export interface UseSearchOptions {
+	/**
+	 * Lock the search to a single source key (or "all"). When set:
+	 *   - `scope` is forced to this value and `setScope` becomes a no-op.
+	 *   - The URL never writes `?scope=` (it's implicit in the page route).
+	 *   - The dropdown should be hidden by the caller.
+	 *
+	 * Use when you embed the search inside a page that already represents
+	 * the source (e.g. `/accounts/search` rendering only Accounts).
+	 */
+	lockedScope?: SearchScope;
+}
+
+/** Flattens a vue-router query object into URLSearchParams (repeated keys preserved). */
+function queryToParams(query: LocationQuery): URLSearchParams {
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) {
+		const values = Array.isArray(value) ? value : [value];
+		for (const v of values) if (v != null) params.append(key, v);
+	}
+	return params;
+}
+
+export function useSearch(config: SearchConfig, options?: UseSearchOptions): SearchHandle {
+	const route = useRoute();
+	const router = useRouter();
+	const lockedScope = options?.lockedScope;
+
+	// Single global pagination config — page size, options, mode, merge order.
+	// There is no per-source pagination; this applies to every scope, including
+	// locked single-object pages and dropdown-narrowed scope. The config is
+	// stable for the composable's lifetime.
+	const pagination = resolvePagination(config);
+
+	// One-time seed from URL.
+	const searchParams = queryToParams(route.query);
+	const initialSourceStates: Record<string, SourceLocalState> = {};
+	for (const source of config.sources) {
+		initialSourceStates[source.key] = initSourceState(source, searchParams, pagination);
+	}
+	const initialQ = searchParams.get(GLOBAL_QUERY_KEY) ?? "";
+	// When the caller locks the scope, that always wins. A locked scope is
+	// always a plain source key (or "all") — never a content-type form.
+	// Otherwise a fresh load always starts in "All" scope. We deliberately do NOT
+	// restore a persisted `?scope=` — a narrowed scope (especially a CMS
+	// content-type scope) depends on runtime-discovered content types that
+	// aren't known yet on first paint, so restoring it would show a blank or
+	// orphaned selection.
+	const initialScope: SearchScope =
+		lockedScope !== undefined && lockedScope !== ALL_SCOPE
+			? config.sources.some((s) => s.key === lockedScope)
+				? lockedScope
+				: ALL_SCOPE
+			: ALL_SCOPE;
+
+	const q = ref(initialQ);
+	const scope = ref<SearchScope>(initialScope);
+	const sourceStates = ref<Record<string, SourceLocalState>>(initialSourceStates);
+
+	// Merged pagination treats the cumulative result set as one fixed-size-paged
+	// list (see SearchPaginationConfig). It needs a single global page index +
+	// size rather than the per-source cursors above; per-source state is still
+	// kept (for filters / sort) but its cursors stay at page 0.
+	const mergedMode = pagination.mode === "merged";
+	const mergeOrder = pagination.mergeOrder;
+
+	const globalPageIndex = ref(0);
+	const globalPageSize = ref(pagination.pageSize);
+
+	let disposed = false;
+	if (getCurrentScope()) {
+		onScopeDispose(() => {
+			disposed = true;
+		});
+	}
+
+	// -- URL sync --------------------------------------------------------------
+
+	const syncToUrl = (
+		nextQ: string,
+		nextScope: SearchScope,
+		nextStates: Record<string, SourceLocalState>,
+	) => {
+		// A debounced sync may fire after the host unmounted / navigated away;
+		// never write a stale query onto another route.
+		if (disposed) return;
+		const params = new URLSearchParams();
+		if (nextQ) params.set(GLOBAL_QUERY_KEY, nextQ);
+		// Intentionally NOT persisting `?scope=`: a fresh load always starts in
+		// "All" (see `initialScope`), so writing the scope would leave a stale
+		// param the next load ignores. `nextScope` is kept in the signature for
+		// call-site compatibility.
+		void nextScope;
+		for (const source of config.sources) {
+			const state = nextStates[source.key];
+			if (!state) continue;
+			writeSourceParams(
+				params,
+				source.key,
+				state.filters,
+				state.sort,
+				state.pageSize,
+				state.pageIndex,
+				// Omit sort / page size from the URL when they equal the
+				// defaults, so a reset (or untouched source) leaves a clean
+				// query string instead of echoing the defaults. `defaultSort` is
+				// SObject-only (CMS has none).
+				{
+					sort: source.kind === "sobject" ? (source.defaultSort ?? null) : null,
+					pageSize: pagination.pageSize,
+				},
+			);
+		}
+		const query: Record<string, string> = {};
+		params.forEach((value, key) => {
+			query[key] = value;
+		});
+		void router.replace({ query }).catch(() => {
+			// Navigation failures (e.g. duplicated navigation) are non-fatal here.
+		});
+	};
+
+	const debouncedSync = debounce(syncToUrl, URL_SYNC_DEBOUNCE_MS);
+
+	const resetCursors = (state: SourceLocalState): SourceLocalState => ({
+		...state,
+		pageIndex: 0,
+		afterCursor: undefined,
+		cursorStack: [],
+	});
+
+	const resetAllCursors = (): Record<string, SourceLocalState> => {
+		const next: Record<string, SourceLocalState> = {};
+		for (const [key, state] of Object.entries(sourceStates.value)) next[key] = resetCursors(state);
+		return next;
+	};
+
+	// Update one source's state and (optionally) reset its pagination.
+	const updateSource = (
+		sourceKey: string,
+		updater: (prev: SourceLocalState) => SourceLocalState,
+		resetPagination: boolean,
+	) => {
+		// A filter / sort / page-size change reshapes the result set, so the
+		// global merged page returns to the first page too.
+		if (resetPagination) globalPageIndex.value = 0;
+		const prev = sourceStates.value;
+		const prior = prev[sourceKey];
+		if (!prior) return;
+		let next = updater(prior);
+		if (resetPagination) next = resetCursors(next);
+		const merged = { ...prev, [sourceKey]: next };
+		sourceStates.value = merged;
+		debouncedSync(q.value, scope.value, merged);
+	};
+
+	// -- Global q --------------------------------------------------------------
+
+	const setQ = (nextQ: string) => {
+		q.value = nextQ;
+		// A new term changes the whole result set — back to the first page.
+		globalPageIndex.value = 0;
+		// Changing the global term invalidates every cursor.
+		const next = resetAllCursors();
+		sourceStates.value = next;
+		debouncedSync(nextQ, scope.value, next);
+	};
+
+	// -- Scope -----------------------------------------------------------------
+
+	const setScope = (nextScope: SearchScope) => {
+		// Locked scope wins over user input — silently no-op.
+		if (lockedScope !== undefined) return;
+		// Reject unknown scope values; fall back to "all". Accepts a plain
+		// source key, "all", or the CMS-only "<cmsKey>:<fqn>" form.
+		const validated: SearchScope = validateScope(config, nextScope);
+		scope.value = validated;
+		// The visible set changes — reset the global page too.
+		globalPageIndex.value = 0;
+		// Narrowing or widening invalidates every cursor.
+		const next = resetAllCursors();
+		sourceStates.value = next;
+		debouncedSync(q.value, validated, next);
+	};
+
+	// -- Reset all -------------------------------------------------------------
+
+	const resetAll = () => {
+		q.value = "";
+		globalPageIndex.value = 0;
+		// Preserve locked scope; otherwise widen back to "all".
+		const nextScope: SearchScope = lockedScope ?? ALL_SCOPE;
+		scope.value = nextScope;
+		const empty: Record<string, SourceLocalState> = {};
+		for (const source of config.sources) {
+			empty[source.key] = {
+				filters: [],
+				// `defaultSort` is SObject-only; CMS resets to no sort.
+				sort: source.kind === "sobject" ? (source.defaultSort ?? null) : null,
+				pageSize: pagination.pageSize,
+				pageIndex: 0,
+				afterCursor: undefined,
+				cursorStack: [],
+			};
+		}
+		sourceStates.value = empty;
+		globalPageSize.value = pagination.pageSize;
+		syncToUrl("", nextScope, empty);
+	};
+
+	// -- CMS content-type discovery --------------------------------------------
+	//
+	// The channel id used to DISCOVER content types is derived FROM a CMS search
+	// result (the permanent path — distinct from the temporary `getUIBundleId()`
+	// fed INTO the query). After a CMS result arrives, the fetch watcher resolves
+	// it via `resolveChannelId` and stores it here; the session-cached composable
+	// then fetches the searchable content types ONCE per channel. The discovered
+	// FQNs (a) refine every subsequent all/cms-scope request to `contentTypes` and
+	// (b) are exposed for the scope dropdown to append per-type entries.
+	// Seeded from the last discovered channel persisted in sessionStorage (keyed
+	// by UIBundle id) so a hard reload rehydrates the content-type scope entries.
+	const discoveryChannelId = ref<string | null>(null);
+	getUIBundleId()
+		.then((uiBundleId) => {
+			if (disposed || !isConfiguredUIBundleId(uiBundleId)) return;
+			const seeded = readLastChannelId(uiBundleId);
+			if (seeded && discoveryChannelId.value == null) discoveryChannelId.value = seeded;
+		})
+		.catch(() => {
+			// Seeding is best-effort; a CMS result will still drive discovery.
+		});
+	const { contentTypes: discoveredContentTypes } = useSearchableContentTypes(discoveryChannelId);
+	// The query filter and request key work in FQNs only; the `{ fqn, label }`
+	// objects are threaded to the handle for the scope dropdown's display labels.
+	const discoveredContentTypeFqns = computed(() =>
+		discoveredContentTypes.value.map((ct) => ct.fqn),
+	);
+
+	const requestKey = computed(() => {
+		// Stable string key that changes only when something fetch-relevant changes.
+		// Sources outside the current scope are listed (with `skip: true`) so
+		// the key still changes when scope toggles, but they don't contribute
+		// per-source state to the diff.
+		return JSON.stringify({
+			q: q.value,
+			// `scope` already carries the selected CMS content-type fqn (the
+			// "<cmsKey>:<fqn>" form), so a content-type selection re-fires the fetch.
+			scope: scope.value,
+			// Discovered content types are part of the key so that once discovery
+			// completes, the watcher re-fires and every in-scope CMS request
+			// switches from the bootstrap call to the discovered set.
+			ct: discoveredContentTypeFqns.value,
+			// Merged mode paginates globally: the global page/size drive the fetch
+			// rather than per-source cursors.
+			m: mergedMode ? { gp: globalPageIndex.value, gs: globalPageSize.value } : null,
+			s: config.sources.map((source) => {
+				if (!isSourceInScope(scope.value, source.key)) {
+					return { k: source.key, skip: true };
+				}
+				const st = sourceStates.value[source.key];
+				return {
+					k: source.key,
+					f: st?.filters,
+					o: st?.sort,
+					// In merged mode per-source size/cursor are overridden below.
+					p: mergedMode ? undefined : st?.pageSize,
+					a: mergedMode ? undefined : (st?.afterCursor ?? null),
+				};
+			}),
+		});
+	});
+
+	const results = ref<Record<string, SourceResult>>({});
+	// Per-source errors, keyed by `source.key`. A source that failed while a
+	// sibling succeeded surfaces its own message here without blanking others.
+	const sourceErrors = ref<Record<string, string>>({});
+	const loading = ref(true);
+	// Page-level error — set ONLY when EVERY in-scope source failed, or on a
+	// whole-request / network failure (`runSearch` throwing).
+	const error = ref<string | null>(null);
+	let fetchGen = 0;
+
+	watch(
+		requestKey,
+		(_key, _prev, onCleanup) => {
+			const generation = ++fetchGen;
+			loading.value = true;
+			error.value = null;
+			sourceErrors.value = {};
+
+			const currentQ = q.value;
+			const currentScope = scope.value;
+			const states = sourceStates.value;
+			const pageIdx = globalPageIndex.value;
+			const pageSz = globalPageSize.value;
+			const fqns = discoveredContentTypeFqns.value;
+
+			const activeSources = config.sources.filter((source) =>
+				isSourceInScope(currentScope, source.key),
+			);
+
+			// All sources gated out — clear results and exit without firing a request.
+			if (activeSources.length === 0) {
+				results.value = {};
+				loading.value = false;
+				return;
+			}
+
+			// Keyword gate: only fire a search once the user has typed at least
+			// MIN_QUERY_LENGTH characters. On landing (or after clearing the box) `q`
+			// is empty, so we clear results and exit WITHOUT firing a request — no
+			// unfiltered "browse the first page" query, and no CMS bootstrap call
+			// until there's a keyword. The SObject and CMS search backends reject
+			// terms shorter than MIN_QUERY_LENGTH, which would otherwise surface as
+			// "Search failed for this source." across every source.
+			if (currentQ.trim().length < MIN_QUERY_LENGTH) {
+				results.value = {};
+				loading.value = false;
+				return;
+			}
+
+			// A "<cmsKey>:<fqn>" scope narrows to one content type. Because its `base`
+			// is the CMS source key, `activeSources` already excludes every SObject
+			// source (CMS-only search); the fqn flows through as `contentTypes = [fqn]`.
+			const { cmsFqn } = parseScope(currentScope);
+
+			// Merged mode: fetch the whole front-anchored window — (page + 1) * size
+			// rows — from every in-scope source, with no cursor. Concatenating these
+			// and slicing [page*size, (page+1)*size) yields the exact global page.
+			const mergedFetchSize = (pageIdx + 1) * pageSz;
+
+			// Resolve the async CMS preconditions ONCE, up front, then thread them into
+			// each CMS request so the synchronous query builder never resolves a promise.
+			let cancelled = false;
+			onCleanup(() => {
+				cancelled = true;
+			});
+			// True once this run's request set is a DISCOVERY-driven refetch: an
+			// all/cms-scope search that auto-applies the content-type FQNs discovered
+			// from a prior successful CMS result. Such a refetch only NARROWS an
+			// already-successful bootstrap, so if it fails it must not destroy the
+			// good bootstrap results or raise a page-level error.
+			let isDiscoveryRefetch = false;
+			Promise.all([getUIBundleId(), getUserLanguage(), getOrgSupportsCmsSearch()])
+				.then(([uiBundleId, userLanguage, orgSupportsCmsSearch]) => {
+					if (cancelled || generation !== fetchGen) return;
+
+					const requests: SourceRequest[] = activeSources.flatMap((source) => {
+						const st = states[source.key]!;
+						const base: SourceRequest = {
+							source,
+							q: currentQ,
+							filters: st.filters,
+							sort: st.sort,
+							pageSize: mergedMode ? mergedFetchSize : st.pageSize,
+							afterCursor: mergedMode ? undefined : st.afterCursor,
+						};
+						if (source.kind !== "cms") return [base];
+						// CMS is gated on (a) a CONFIGURED (9YE-shaped) UIBundle id and
+						// (b) a build-time API version with the CMS search backend (v68+,
+						// core 264+). Skip silently when either is absent.
+						if (!isConfiguredUIBundleId(uiBundleId) || !orgSupportsCmsSearch) {
+							return [];
+						}
+						// CMS request: attach the resolved channel id and content types.
+						//   - specific fqn selected → exactly that type.
+						//   - all / cms-key scope → the discovered set if known, else
+						//     omit `contentTypes` entirely (the bootstrap call).
+						const contentTypes = cmsFqn ? [cmsFqn] : fqns.length > 0 ? fqns : undefined;
+						if (!cmsFqn && fqns.length > 0) {
+							isDiscoveryRefetch = true;
+						}
+						return [{ ...base, uiBundleId, language: userLanguage, contentTypes }];
+					});
+
+					// Every in-scope source was gated out (e.g. a CMS-only scope while CMS
+					// is not yet configured): nothing to fetch.
+					if (requests.length === 0) {
+						results.value = {};
+						loading.value = false;
+						return;
+					}
+
+					// The sources actually queried (CMS may have been skipped above). Used
+					// for the all-failed check so a skipped CMS source is never a failure.
+					const requestedSources = requests.map((r) => r.source);
+
+					return runSearch(requests).then((outcome) => {
+						if (cancelled || generation !== fetchGen) return;
+						const { results: nextResults, errors: nextErrors } = outcome;
+
+						// Discovery-driven refetch that came back with a failed source:
+						// keep the bootstrap results, fall back to the prior result for
+						// any source this refetch failed to produce, drop the error.
+						if (isDiscoveryRefetch && requestedSources.some((s) => nextErrors[s.key] != null)) {
+							const merged = { ...results.value };
+							for (const source of requestedSources) {
+								if (nextResults[source.key] != null) merged[source.key] = nextResults[source.key];
+							}
+							results.value = merged;
+							return;
+						}
+
+						results.value = nextResults;
+						sourceErrors.value = nextErrors;
+
+						// Page-level error only when EVERY queried source failed; a mix of
+						// success + failure surfaces per-source with the grid intact.
+						const allFailed =
+							requestedSources.length > 0 &&
+							requestedSources.every((source) => nextErrors[source.key] != null);
+						if (allFailed) {
+							// De-duplicate identical messages so a shared backend error is
+							// shown once rather than repeated per source.
+							const combined = [
+								...new Set(
+									requestedSources
+										.map((source) => nextErrors[source.key])
+										.filter((m): m is string => !!m),
+								),
+							].join("; ");
+							error.value = combined || "Unified search failed";
+						}
+
+						// Content-type discovery: once a CMS source returns data, derive the
+						// discovery channel id from it and hand it to the cached composable.
+						for (const source of requestedSources) {
+							if (source.kind !== "cms") continue;
+							const channelId = resolveChannelId(nextResults[source.key]);
+							if (channelId) {
+								if (discoveryChannelId.value !== channelId) discoveryChannelId.value = channelId;
+								// Persist the pointer keyed by THIS UIBundle so a reload seeds
+								// only this bundle's channel — never a different bundle's.
+								writeLastChannelId(uiBundleId, channelId);
+								break;
+							}
+						}
+					});
+				})
+				.catch((err: unknown) => {
+					if (cancelled || generation !== fetchGen) return;
+					console.error(err);
+					// A failed discovery-driven refetch must NOT blank the good bootstrap
+					// results or raise a page-level error.
+					if (isDiscoveryRefetch) return;
+					// A whole-request / network failure is page-level.
+					error.value = err instanceof Error ? err.message : "Unified search failed";
+					// Clear stale rows so a prior page's results don't linger under the
+					// error banner.
+					results.value = {};
+					sourceErrors.value = {};
+				})
+				.finally(() => {
+					if (cancelled || generation !== fetchGen) return;
+					loading.value = false;
+				});
+		},
+		{ immediate: true },
+	);
+
+	// -- Per-source controllers ------------------------------------------------
+
+	const controllers = computed(() => {
+		const out: Record<string, SourceController> = {};
+		for (const source of config.sources) {
+			const state = sourceStates.value[source.key];
+			const result = results.value[source.key] ?? null;
+
+			const setFilter = (field: string, value: ActiveFilterValue | undefined) => {
+				updateSource(
+					source.key,
+					(prev) => {
+						const filtered = prev.filters.filter((f) => f.field !== field);
+						if (value) filtered.push(value);
+						return { ...prev, filters: filtered };
+					},
+					true,
+				);
+			};
+			const removeFilter = (field: string) => {
+				updateSource(
+					source.key,
+					(prev) => ({
+						...prev,
+						filters: prev.filters.filter((f) => f.field !== field),
+					}),
+					true,
+				);
+			};
+			const setSort = (sort: SortState | null) => {
+				updateSource(source.key, (prev) => ({ ...prev, sort }), true);
+			};
+			const setPageSize = (size: number) => {
+				updateSource(
+					source.key,
+					(prev) => ({ ...prev, pageSize: validatePageSize(pagination, size) }),
+					true,
+				);
+			};
+			const goToNextPage = () => {
+				const cursor = result?.pageInfo?.endCursor;
+				if (!cursor) return;
+				updateSource(
+					source.key,
+					(prev) => ({
+						...prev,
+						cursorStack: [...prev.cursorStack, cursor],
+						afterCursor: cursor,
+						pageIndex: prev.pageIndex + 1,
+					}),
+					false,
+				);
+			};
+			const goToPreviousPage = () => {
+				updateSource(
+					source.key,
+					(prev) => {
+						if (prev.pageIndex === 0) return prev;
+						const nextStack = prev.cursorStack.slice(0, -1);
+						return {
+							...prev,
+							cursorStack: nextStack,
+							afterCursor: nextStack[nextStack.length - 1],
+							pageIndex: Math.max(0, prev.pageIndex - 1),
+						};
+					},
+					false,
+				);
+			};
+
+			out[source.key] = {
+				config: source,
+				result,
+				loading: loading.value,
+				// Per-source error (set only when THIS source failed) — not the
+				// page-level `error` (which is set only when every source failed).
+				error: sourceErrors.value[source.key] ?? null,
+				filters: {
+					active: state?.filters ?? [],
+					set: setFilter,
+					remove: removeFilter,
+				},
+				sort: {
+					current: state?.sort ?? null,
+					set: setSort,
+				},
+				pagination: {
+					pageSize: state?.pageSize ?? pagination.pageSize,
+					pageSizeOptions: pagination.pageSizeOptions,
+					pageIndex: state?.pageIndex ?? 0,
+					hasNextPage: result?.pageInfo?.hasNextPage ?? false,
+					hasPreviousPage: (state?.pageIndex ?? 0) > 0,
+					setPageSize,
+					goToNextPage,
+					goToPreviousPage,
+				},
+			};
+		}
+		return out;
+	});
+
+	const scopeLocked = lockedScope !== undefined;
+
+	// -- Aggregate (cross-source) view -----------------------------------------
+
+	const inScopeSources = computed(() =>
+		config.sources
+			.map((s) => controllers.value[s.key])
+			.filter((c): c is SourceController => !!c && isSourceInScope(scope.value, c.config.key)),
+	);
+
+	// Cumulative result count is mode-independent: sum the in-scope totals.
+	const totalCount = computed(() =>
+		inScopeSources.value.reduce(
+			(sum, c) => sum + (c.result?.totalCount ?? c.result?.nodes.length ?? 0),
+			0,
+		),
+	);
+
+	// Every in-scope source's fetched nodes flattened into one list, ordered per
+	// `mergeOrder`:
+	//   - sequential: all of source 1, then source 2, … (config order).
+	//   - interleaved: round-robin, one node per source per round — equal priority.
+	//   - proportional: each item gets a key (i + 0.5) / weight (weight = source's
+	//     totalCount); sorting by key spreads each source evenly across the list
+	//     in proportion to its size, so larger sources appear more often.
+	// All three stay exact in merged mode (each source fetched (page + 1) * size
+	// rows from its front, so the first (page + 1) * size items are the true
+	// cumulative prefix). Proportional uses the true totalCount as the weight.
+	const concatenatedNodes = computed<MergedResultItem[]>(() => {
+		const lists = inScopeSources.value.map((c) => ({
+			key: c.config.key,
+			nodes: c.result?.nodes ?? [],
+			weight: c.result?.totalCount ?? c.result?.nodes.length ?? 0,
+		}));
+		const out: MergedResultItem[] = [];
+
+		if (mergeOrder === "interleaved") {
+			const maxLen = lists.reduce((m, l) => Math.max(m, l.nodes.length), 0);
+			for (let round = 0; round < maxLen; round++) {
+				for (const l of lists) {
+					if (round < l.nodes.length) out.push({ sourceKey: l.key, node: l.nodes[round] });
+				}
+			}
+		} else if (mergeOrder === "proportional") {
+			const tagged = lists.flatMap((l, sIdx) =>
+				l.nodes.map((node, i) => ({
+					sourceKey: l.key,
+					node,
+					sIdx,
+					i,
+					sortKey: (i + 0.5) / (l.weight > 0 ? l.weight : 1),
+				})),
+			);
+			tagged.sort((a, b) => a.sortKey - b.sortKey || a.sIdx - b.sIdx || a.i - b.i);
+			for (const t of tagged) out.push({ sourceKey: t.sourceKey, node: t.node });
+		} else {
+			for (const l of lists) {
+				for (const node of l.nodes) out.push({ sourceKey: l.key, node });
+			}
+		}
+		return out;
+	});
+
+	// -- Merged mode: one fixed-size-paged list over the cumulative results -----
+
+	const mergedGlobalPagination = computed<GlobalPagination>(() => {
+		// Options come from the global pagination config, NOT the in-scope source —
+		// so narrowing the dropdown to one object keeps the global page sizes.
+		const pageSizeOptions = pagination.pageSizeOptions;
+		const pageCount =
+			totalCount.value === 0 ? 0 : Math.ceil(totalCount.value / globalPageSize.value);
+		// Clamp in case totalCount shrank (e.g. a filter) below the current page.
+		const pageIndex = pageCount === 0 ? 0 : Math.min(globalPageIndex.value, pageCount - 1);
+		return {
+			pageIndex,
+			pageCount,
+			pageSize: globalPageSize.value,
+			pageSizeOptions,
+			hasNextPage: pageIndex + 1 < pageCount,
+			hasPreviousPage: pageIndex > 0,
+			totalCount: totalCount.value,
+			goToNextPage: () => {
+				globalPageIndex.value += 1;
+			},
+			goToPreviousPage: () => {
+				globalPageIndex.value = Math.max(0, globalPageIndex.value - 1);
+			},
+			goToPage: (next: number) => {
+				globalPageIndex.value = Math.max(0, Math.floor(next));
+			},
+			// Validate the requested size against the configured options before it
+			// becomes `$cmsLimit` / `first`, matching the per-source setter.
+			setPageSize: (size: number) => {
+				globalPageSize.value = validatePageSize(pagination, size);
+				globalPageIndex.value = 0;
+			},
+		};
+	});
+
+	const mergedModeResults = computed<MergedResultItem[]>(() => {
+		const start = mergedGlobalPagination.value.pageIndex * globalPageSize.value;
+		return concatenatedNodes.value.slice(start, start + globalPageSize.value);
+	});
+
+	// -- Per-source mode: independent cursors, "global page" = furthest source --
+	//
+	// Sources paginate with independent cursors (there is no global offset), so a
+	// "global page" is the furthest-advanced in-scope source's page. A source
+	// that runs out of pages is left behind at a lower pageIndex and stops
+	// contributing nodes — its last page was already shown on an earlier global
+	// page, so re-emitting it would duplicate rows in the merged list.
+
+	const perSourceGlobalPagination = computed<GlobalPagination>(() => {
+		const sources = inScopeSources.value;
+		const lead = sources[0];
+		const pageSize = lead?.pagination.pageSize ?? pagination.pageSize;
+		const pageSizeOptions = pagination.pageSizeOptions;
+
+		const pageIndex = sources.reduce((max, c) => Math.max(max, c.pagination.pageIndex), 0);
+
+		// Pages a source spans: prefer totalCount; otherwise a lower bound from its
+		// own position (current page, plus one more if it reports a next page).
+		const pageCount = sources.reduce((max, c) => {
+			const tc = c.result?.totalCount;
+			const span =
+				tc != null && pageSize > 0
+					? Math.max(1, Math.ceil(tc / pageSize))
+					: c.pagination.pageIndex + (c.pagination.hasNextPage ? 2 : 1);
+			return Math.max(max, span);
+		}, 0);
+
+		const hasNextPage = sources.some((c) => c.pagination.hasNextPage);
+		const hasPreviousPage = pageIndex > 0;
+
+		const goToNextPage = () =>
+			sources.forEach((c) => {
+				if (c.pagination.hasNextPage) c.pagination.goToNextPage();
+			});
+		const goToPreviousPage = () =>
+			sources.forEach((c) => {
+				if (c.pagination.pageIndex === pageIndex) c.pagination.goToPreviousPage();
+			});
+
+		return {
+			pageIndex,
+			pageCount: totalCount.value === 0 ? 0 : pageCount,
+			pageSize,
+			pageSizeOptions,
+			hasNextPage,
+			hasPreviousPage,
+			totalCount: totalCount.value,
+			goToNextPage,
+			goToPreviousPage,
+			// Cursors can't seek to an arbitrary offset — honour adjacent pages only.
+			goToPage: (next: number) => {
+				if (next === pageIndex + 1 && hasNextPage) goToNextPage();
+				else if (next === pageIndex - 1 && hasPreviousPage) goToPreviousPage();
+			},
+			setPageSize: (size: number) => sources.forEach((c) => c.pagination.setPageSize(size)),
+		};
+	});
+
+	const perSourceResults = computed<MergedResultItem[]>(() => {
+		const idx = perSourceGlobalPagination.value.pageIndex;
+		return concatenatedNodes.value.filter((item) => {
+			const c = controllers.value[item.sourceKey];
+			// Only sources caught up to the current global page contribute; a
+			// left-behind source already showed its final page earlier.
+			return c?.pagination.pageIndex === idx;
+		});
+	});
+
+	const globalPagination = computed(() =>
+		mergedMode ? mergedGlobalPagination.value : perSourceGlobalPagination.value,
+	);
+	const mergedResults = computed(() =>
+		mergedMode ? mergedModeResults.value : perSourceResults.value,
+	);
+
+	// Reactive handle: refs/computeds are auto-unwrapped, so consumers (and
+	// templates) read plain `search.q`, `search.loading`, … like the React hook.
+	return reactive({
+		q,
+		setQ,
+		scope,
+		setScope,
+		scopeLocked,
+		sources: controllers,
+		inScopeSources,
+		mergedResults,
+		globalPagination,
+		loading,
+		error,
+		discoveredContentTypes,
+		resetAll,
+	}) as unknown as SearchHandle;
+}