@salesforce/templates 66.13.6 → 66.13.7

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/README.md

@@ -0,0 +1,246 @@
+# Search feature
+
+Explains how this search feature is structured and how to customize it — which
+files own configuration, how sObject and CMS sources differ, how CMS search is
+wired end to end, and how to mount the UI. Read it before changing anything
+under this directory.
+
+## 1. What this feature is / where sources live
+
+- `config.json` (co-located here) declares `sources: SourceConfig[]` — a
+  discriminated union on `kind` — plus an optional `pagination` block. The
+  shipped default has 3 `"sobject"` sources (`accounts`, `contacts`,
+  `opportunities`) and one `"cms"` source (`key: "content"`).
+- `loadConfig.ts` re-exports `config.json`, typed as `SearchConfig`. For a
+  pure config change (add/remove a source, tweak fields), **edit
+  `config.json` directly — no code changes required.**
+- `types.ts` is the source of truth for `SourceConfig` (`SObjectSourceConfig |
+CmsSourceConfig`) and `SearchConfig`.
+
+## 2. Choosing sObject vs CMS per source
+
+- **sObject source** (`kind: "sobject"`): requires `objectName`, `label`,
+  `searchableFields`, `displayFields`. Optional: `labelSingular`, `idField`
+  (defaults `"Id"`), `routePattern`, `filterBy`, `sortBy`, `defaultSort`,
+  `whereTypeName`/`orderByTypeName`. Queried via the `uiapi` GraphQL bridge
+  (`adapters/sobject`).
+- **CMS source** (`kind: "cms"`): deliberately minimal — only `kind`, `key`,
+  `label`, and optionally `labelSingular`/`routePattern`
+  (`adapters/cms/types.ts`, `CmsSourceConfig`). No `channelId`, no content
+  types, no `displayFields` — all of that is resolved at runtime. Routed via
+  `adapters/registry.ts` to `cmsAdapter` (`adapters/cms/index.ts`).
+- `adapters/registry.ts` maps `kind` → adapter (`sobject → sObjectAdapter`,
+  `cms → cmsAdapter`). Adding a new backend `kind` means registering an
+  adapter here plus extending the `SourceConfig` union in `types.ts` — out of
+  scope for typical customization; most tasks only touch `config.json`.
+
+## 3. Enabling sObject search
+
+sObject sources work out of the box — no runtime id resolution and no gating.
+They query the org's `uiapi` GraphQL bridge through `adapters/sobject`.
+
+- **Declare the source** in `config.json`: `kind: "sobject"`, `objectName` (the
+  API name, e.g. `"Account"`), `label`, `searchableFields` (the fields the
+  free-text term matches against), and `displayFields` (what each result row
+  shows). A `displayFields` entry is a plain field name (`"Name"`), a
+  `{ name, raw }` (use the raw value, skip display formatting), or a
+  `{ name, subfields }` for a parent relationship
+  (`{ "name": "Owner", "subfields": ["Name"] }`).
+- **Optional per-source knobs:** `labelSingular`, `idField` (defaults `"Id"`),
+  `filterBy` (facets — `picklist` / `numeric` / `daterange`), `sortBy` +
+  `defaultSort`, and `routePattern` (see §6). `whereTypeName` / `orderByTypeName`
+  override the generated GraphQL input type names for objects whose where/orderBy
+  types don't follow the default `<Object>` naming.
+- **Query construction:** `buildSearchQuery` (`api/buildSearchQuery.ts`)
+  assembles the GraphQL from the source config, `buildOrderBy` builds the sort
+  clause, and picklist filter values come from `useDistinctValues` /
+  `fetchDistinctValues`. The whole path runs through the platform data SDK — no
+  enablement step beyond declaring the source.
+- **FLS caveat:** a field the running user can't read is silently dropped by the
+  platform, so an sObject source that "returns nothing" usually means the app's
+  permission set is missing field access, not a config error.
+
+## 4. Enabling CMS search
+
+This is the part most likely to be missed — read all of it before assuming
+CMS search "just works" after adding a `cms` source to `config.json`.
+
+- **API version requirement.** Search on CMS content is supported only when the
+  bundle is built against **API version 68.0 or greater**. The build-time
+  version (`__SF_API_VERSION__`, injected from the resolved org's API version)
+  is the version every SDK request is actually issued at, so it is the gate.
+- **No static id in config.** The UIBundle id is resolved at runtime by
+  `adapters/cms/searchChannel.ts::getUIBundleId()`, which calls
+  `@salesforce/platform-sdk`'s `getCurrentApp()` and reads
+  `identity.bundleId` — the UIBundle **record id** (a `9YE...` id). This is
+  only populated when running on the WebApp surface (the runtime injects
+  `SFDC_ENV`, per `packages/sdk/platform-sdk/src/core/app.ts`). Locally, or on
+  any non-WebApp surface, `bundleId` is `undefined`/`""`, and the CMS source
+  is skipped with no error — by design.
+- **The gate:** `hooks/useSearch.ts` resolves `getUIBundleId()` **and**
+  `getOrgSupportsCmsSearch()` once per fetch and, for the CMS source, includes
+  the CMS request only when BOTH pass: `isConfiguredUIBundleId(uiBundleId)`
+  (`adapters/cms/searchChannel.ts`) and the build API-version check (above).
+  `isConfiguredUIBundleId` validates the `9YE` shape
+  (`UI_BUNDLE_ID_PATTERN = /^9YE[a-zA-Z0-9]{12,15}$/`) — an empty or malformed
+  id, or a build below v68, causes the CMS source to be silently dropped from
+  the request (no per-source error banner), not sent to the server.
+- **CMS UI surfaces hide on a gated build too.** When CMS search is skipped for
+  the build-version reason, its scope entry and result section would only ever
+  be empty, so both are hidden using the SAME gate as the fetch skip —
+  `isCmsSearchSupported()` (the synchronous core of `getOrgSupportsCmsSearch()`,
+  in `adapters/cms/api/orgApiVersionService.ts`). Two minimal guards read it:
+  `ScopeSelector` skips the CMS `<SelectItem>` ("Content") and `SearchResults`
+  skips the CMS `SourceSection` ("Content" heading + empty state). Both are safe
+  during render because the gate reads only the build-time API version. (The
+  runtime `bundleId` gate above is _not_ build-constant — it can differ per
+  surface — so it stays a per-fetch skip and does not hide the UI; a CMS source
+  skipped only for a missing `bundleId` still shows its section, empty.)
+- **The query field:** `adapters/cms/cmsQueryFragment.ts` sends the resolved
+  `$UIBundleId` into `searchIdentifiers.uibundleIds` (NOT `channelIds`) on
+  `managed_content.search.searchContentInChannels`. Content-type filtering
+  (`$cmsContentTypeFQNs`) is omitted on the bootstrap call and supplied once
+  discovery completes.
+  - **Why `uibundleIds` (evidence from core).** `ContentSearchIdentifiersInput`
+    has three id-space fields — `channelIds` (`0ap` Managed Content channel ids),
+    `siteIds`, and `uibundleIds` — and the `9YE` UIBundle **record id** belongs
+    only in `uibundleIds`. In core (`core-2206/core-266-public`): the schema
+    `ui-services-private/.../graphql-schemas/mcontent-search.graphqls` documents
+    `uibundleIds` as _"Each UI bundle ID is resolved to its associated Managed
+    Content channel(s)"_; the resolver
+    `mcontent-impl/.../ManagedContentGraphQLSearchServiceImpl.resolveChannelIdsFromSitesAndUiBundles()`
+    resolves each id via `getManagedContentChannelsByTarget(uibundleId)` (the id
+    is the channel's **TargetEntityId**, i.e. a UIBundle record id); the UDD
+    `lwr-udd/.../UIBundle.entity.xml` sets `keyPrefix="9YE"`; and the unit test
+    `ManagedContentGraphQLSearchServiceImplTest.testUiBundleId_resolvesToChannelIds_andIsSearched()`
+    passes a `9YE…` id into `uibundleIds` and asserts it resolves (W-23364628).
+    `channelIds` values are validated as channel/site ids and never run through
+    the target-entity resolver, so a `9YE` id sent there fails with
+    `"9YE… isn't a valid managed content channel ID or a site ID"` — the exact
+    error this wiring fixes. (Server-side, resolution of `uibundleIds`/`siteIds`
+    is gated by the core feature flag `isAllowTargetEntityIdsEnabled()`.)
+- **Content-type discovery:** after the first CMS result returns,
+  `adapters/cms/channelResolver.ts::resolveChannelId()` extracts the `0ap`
+  managed-content-channel id from
+  `nodes[0].managedContentChannelDeliveryDetails[0].managedContentChannelDetails.id`.
+  `adapters/cms/hooks/useSearchableContentTypes.ts` (session-cached) then
+  fetches `GET /connect/cms/channels/{channelId}/searchable-content-types` to
+  populate the scope dropdown's per-content-type entries. Note: this `0ap` id
+  is a _different_ id space from the `9YE` UIBundle id above — don't confuse
+  the two when debugging.
+- **Seeding content:** the resolved `bundleId` only surfaces content published
+  to the UIBundle's own channel (WebApp type), so CMS content must be published
+  there — not to the Experience Site COMMUNITY channel. Content published to
+  the wrong channel returns zero results even when the id/gate/query wiring is
+  correct, so empty CMS results with everything else in place usually points at
+  the publishing target rather than the code.
+- **Mounting:** add a `{ "kind": "cms", "key": "...", "label": "..." }` entry
+  to `config.sources` (in `config.json`, or a custom `SearchConfig` object at
+  runtime), then render `<Search config={config} />` somewhere routed — see
+  the next section.
+
+## 5. Mounting `<Search>` — the routing caveat
+
+- `GlobalSearchBox` (`components/GlobalSearchBox.tsx`) is a **pure
+  launcher** — a text input + button that calls `navigate('/search?q=...')`
+  on submit. **It renders no results itself.**
+- **`GlobalSearchBox` only routes to `/search`; you must mount `<Search>` at
+  that route for results to render.** In this template, `routes.tsx` does
+  exactly that: `path: "search"` renders `<GlobalSearch config={config} .../>`
+  (`GlobalSearch` is `Search` aliased on import). If an app drops in
+  `GlobalSearchBox` without also mounting `<Search>` (or a custom results UI
+  built on `useSearch`) at the route it navigates to, searches will appear to
+  do nothing.
+- `<Search>` itself (`components/Search.tsx`) is the batteries-included
+  drop-in. For narrower customizations (e.g. a single-object search page),
+  see its prop JSDoc for `restrictTo` (lock to one source), `renderResult` /
+  `renderFilters` (per-source overrides), and `showScopeSelector`.
+
+## 6. Adding a detail page (object detail / CMS content detail)
+
+**By default, result cards are NOT clickable** — the feature renders each row as
+plain (non-linked) text (see the final `return <div>…` branch in
+`DefaultResultRow.tsx` / `CmsResultRow.tsx`). Making a card clickable is a
+two-part change, and **both parts are required** — one without the other either
+does nothing or 404s:
+
+1. **In this feature** (`config.json`): give the source a `routePattern`. This is
+   the _only_ thing that turns the row into a `<Link>`. Without it the row stays
+   non-clickable no matter what routes the app defines.
+2. **In the app** (`src/routes.tsx`): the detail page must actually exist and be
+   registered at a matching dynamic route. The feature only builds the href
+   (e.g. `/accounts/001…`); it does not own any route. If that route isn't in the
+   app's `routes.tsx`, the (now-clickable) card navigates to a dead URL and 404s.
+
+So: `routePattern` present **and** a matching detail route/page in the app →
+clickable card that opens a detail page. `routePattern` absent → non-clickable
+card (the default). `routePattern` present but no app route → clickable card that
+404s.
+
+- **How the link is built:** `routePattern` is a path template with `:token`
+  placeholders resolved per result.
+  - **sObject rows** (`components/results/DefaultResultRow.tsx`,
+    `resolveRoute(routePattern, node, idField)`): `:fieldName` tokens are
+    substituted from the record's field values, and a bare `:id` maps to the
+    source's `idField` (default `Id`). The shipped `accounts` source uses
+    `"/accounts/:id"`.
+  - **CMS rows** (`components/results/CmsResultRow.tsx`): tokens are `:id`
+    (the `managedContentId`) and `:key`; when no `routePattern` is set it falls
+    back to `/content/:contentType/:id`.
+- **Authoring the app-side route + page** (part 2 above): register the matching
+  dynamic route in the app's `routes.tsx` (e.g. `path: "accounts/:id"` /
+  `path: "content/:contentType/:id"`). That route's component reads the route
+  param (`useParams`) and fetches the single record/content item — sObject
+  detail: fetch the one record by id via the platform data SDK (see the
+  `experience-ui-bundle-salesforce-data-access` skill — do not hand-roll
+  `fetch`); CMS detail: fetch the content item by `managedContentId` through the
+  CMS delivery API.
+- **Generating the page:** whichever kind of detail page you need, nothing inside
+  this search feature changes beyond setting `routePattern` — the page and route
+  live in the app, not in this directory. Pick the skill by source type:
+  - **sObject object-detail page** — a normal routed page; generate it with the
+    `experience-ui-bundle-frontend-generate` skill (its page types include "detail
+    view"; record data is fetched via the platform Data SDK per the
+    `experience-ui-bundle-salesforce-data-access` skill).
+  - **CMS content-detail page** — generate it with the
+    `experience-cms-content-render` skill. That skill owns CMS content _fetch +
+    render_ (the delivery API, `contentKey`/`contentType`, RichText, and image
+    resolution) and **takes precedence** over `experience-ui-bundle-frontend-generate`
+    for the rendering portion — the UI skill owns only the page/layout shell. Its
+    Detail Page branch writes `src/pages/<type>/<PageName>.tsx` and inserts the
+    route, so the app gets both the page and the matching route wired for you. (It
+    is scoped to _rendering existing_ content — use this search feature, not that
+    skill, for the search itself.)
+
+## 7. Config knobs reference
+
+| Knob                                      | Values / notes                                                                                                                                                                                                             |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pagination.mode`                         | `"per-source"` (default; one section per source) vs `"merged"` (one combined grid, single global pager) — `types.ts`                                                                                                       |
+| `pagination.mergeOrder`                   | `"sequential" \| "interleaved" \| "proportional"` — merged mode only                                                                                                                                                       |
+| `pagination.pageSize` / `pageSizeOptions` | shared across every source, every scope                                                                                                                                                                                    |
+| Per-sobject-source                        | `objectName`, `label`/`labelSingular`, `idField`, `routePattern`, `searchableFields`, `displayFields` (`string \| {name,raw} \| {name,subfields}`), `filterBy`, `sortBy`, `defaultSort`, `whereTypeName`/`orderByTypeName` |
+| Per-cms-source                            | `key`, `label`, `labelSingular?`, `routePattern?` — nothing else, by design                                                                                                                                                |
+| `MIN_QUERY_LENGTH`                        | `constants.ts`, currently `3`. Both backends reject shorter terms server-side; gated client-side in `useSearch.ts` and `GlobalSearchBox.tsx` so the UI never shows a spurious failure for a too-short query                |
+
+## 8. Public API pointers
+
+Import from the barrel (`index.ts`) rather than reaching into internals. The
+main extension points, grouped by concern:
+
+- **Core (both source types):** `useSearch` — the hook (state, fetch,
+  pagination) behind `<Search>`; `runSearch` — the underlying fetch;
+  `buildSearchQuery` — assembles the query payload; `getAdapter` — resolves a
+  source `kind` to its adapter; `config` — the loaded `SearchConfig`.
+- **sObject sources:** `useDistinctValues` / `fetchDistinctValues` — picklist
+  filter values; `buildOrderBy` — sort clause construction; the filter inputs
+  (`TextFilter`, `SelectFilter`, `MultiSelectFilter`, `NumericRangeFilter`,
+  `BooleanFilter`, `DateRangeFilter`) and `DefaultResultRow` for rendering.
+- **CMS source:** `cmsAdapter`; `useSearchableContentTypes` — content-type
+  discovery; `isValidCmsFqn` / `formatContentTypeLabel` — content-type FQN
+  helpers; `CmsResultRow` for rendering.
+- **Types:** `SearchConfig`, `SourceConfig`, `SObjectSourceConfig`,
+  `CmsSourceConfig`, `SourceAdapter`, `SearchHandle`, and related runtime types.
+
+See `index.ts` for the full exported surface (all components, filter inputs,
+utils) — this list is intentionally short.

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/adapters/cms/api/apiUtils.ts

@@ -0,0 +1,56 @@
+/**
+ * Self-contained CMS Connect REST helpers (URL builder + authenticated GET).
+ */
+
+import { createDataSDK } from "@salesforce/platform-sdk";
+
+// The build injects the org's API version via `__SF_API_VERSION__`; the literal
+// is only a fallback for environments (e.g. unit tests) where it is undefined.
+declare const __SF_API_VERSION__: string;
+
+/** Project-standard API version, mirroring `@salesforce/ui-bundle/api`'s clients. */
+const API_VERSION: string = typeof __SF_API_VERSION__ !== "undefined" ? __SF_API_VERSION__ : "65.0";
+
+/**
+ * The bundle's build-time API version as a number (e.g. `68.0`), i.e. the
+ * version the SDK's GraphQL/REST requests are actually issued at. `0` when it
+ * cannot be parsed. Distinct from the org's advertised max version.
+ */
+export function getBuildApiVersion(): number {
+	const v = Number.parseFloat(API_VERSION);
+	return Number.isFinite(v) ? v : 0;
+}
+
+/**
+ * Percent-encodes a single path segment (SSRF / path-injection guard). Mirrors
+ * the reference `safeEncodePath`.
+ */
+export function safeEncodePath(segment: string): string {
+	return encodeURIComponent(segment);
+}
+
+/** Builds an absolute Connect REST URL from a version-relative sub-path. */
+export function connectUrl(subPath: string): string {
+	const normalized = subPath.startsWith("/") ? subPath : `/${subPath}`;
+	return `/services/data/v${API_VERSION}/connect${normalized}`;
+}
+
+/**
+ * GETs a Connect JSON resource via the platform SDK's authenticated `fetch`
+ * and returns the parsed body. Throws on SDK-init failure or a non-OK response
+ * (the caller decides how a whole-request failure surfaces).
+ */
+export async function connectGetJson<T = unknown>(url: string): Promise<T> {
+	const sdk = await createDataSDK();
+	if (!sdk?.fetch) {
+		throw new Error("Failed to initialize data SDK for CMS REST call");
+	}
+	const response = await sdk.fetch(url, {
+		method: "GET",
+		headers: { Accept: "application/json" },
+	});
+	if (!response.ok) {
+		throw new Error(`CMS REST request failed: ${response.status} ${response.statusText}`);
+	}
+	return (await response.json()) as T;
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/adapters/cms/api/orgApiVersionService.ts

@@ -0,0 +1,37 @@
+/** Service to gate CMS search on the bundle's build-time API version. */
+
+import { getBuildApiVersion } from "./apiUtils";
+
+/** Minimum API version that supports CMS search. */
+export const MIN_CMS_API_VERSION = 68;
+
+/**
+ * Whether CMS search can run — the synchronous core of the gate. Gated on the
+ * bundle's build-time API version (`__SF_API_VERSION__`, injected from the
+ * resolved org's API version at build time) being >= {@link MIN_CMS_API_VERSION}.
+ *
+ * The build version is the version every SDK GraphQL/REST request is actually
+ * issued at, so it already reflects a concrete, org-supported API version: a
+ * bundle built against an org resolves that org's max version, and a bundle
+ * built below v68 sends its CMS query to `/services/data/v67.0/graphql` where
+ * the v68 CMS backend is unavailable. Gating on the build version alone is
+ * therefore both necessary and sufficient — and, unlike a runtime probe of the
+ * bare `/services/data/` version-listing endpoint (which is not routed on guest
+ * Experience Sites and would fail-close there), it works on every surface.
+ *
+ * Because it reads only the baked build version, it is safe to call during
+ * render — e.g. to hide the CMS source's scope entry and result section when
+ * the backend isn't available (see `ScopeSelector` and `SearchResults`).
+ */
+export function isCmsSearchSupported(): boolean {
+	return getBuildApiVersion() >= MIN_CMS_API_VERSION;
+}
+
+/**
+ * Resolves whether CMS search can run. Thin async wrapper over
+ * {@link isCmsSearchSupported} that preserves the existing fetch-path call-site
+ * contract (the fetch effect awaits it alongside the async UIBundle-id lookup).
+ */
+export function getOrgSupportsCmsSearch(): Promise<boolean> {
+	return Promise.resolve(isCmsSearchSupported());
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/adapters/cms/api/searchableContentTypesService.ts

@@ -0,0 +1,116 @@
+/**
+ * Connect REST caller for a CMS channel's searchable content types:
+ *   GET /connect/cms/channels/{channelId}/searchable-content-types?page=N&pageSize=25
+ * Returns the validated content types (FQN + server label) that populate the
+ * content-type scope entries.
+ */
+
+import { connectGetJson, connectUrl, safeEncodePath } from "./apiUtils";
+import {
+	isValidCmsFqn,
+	formatContentTypeLabel,
+	type DiscoveredContentType,
+} from "../contentTypeUtils";
+
+/** Hard-coded REST page size. NEVER user input. */
+const REST_PAGE_SIZE = 25;
+
+/** Safety cap so a misbehaving backend cannot spin an unbounded loop. */
+const MAX_PAGES = 100;
+
+/** Channel id shape guard — `0ap` + 12–15 alphanumerics — validates the discovery channel id before the searchable-content-types REST call. */
+export const CHANNEL_ID_PATTERN = /^0ap[a-zA-Z0-9]{12,15}$/;
+
+/** One raw entry from the Connect response. */
+interface RawContentTypeEntry {
+	/** FQN with the `sfdc_cms__` prefix (e.g. "sfdc_cms__news"). */
+	id?: string;
+	/** Server-provided display name (e.g. "News"). */
+	label?: string;
+	/** Bare developer name without the prefix (e.g. "news"). */
+	name?: string;
+	// Legacy/alternate FQN field names kept as fallbacks.
+	contentType?: string;
+	fqn?: string;
+	developerName?: string;
+	isSearchable?: boolean;
+	searchable?: boolean;
+}
+
+/** Loose shape of one page of the Connect response. */
+interface RawContentTypesPage {
+	items?: RawContentTypeEntry[];
+	contentTypes?: RawContentTypeEntry[];
+}
+
+/** Reads the entries array from a page payload (array or object form). */
+function pageItems(payload: unknown): RawContentTypeEntry[] {
+	if (Array.isArray(payload)) return payload as RawContentTypeEntry[];
+	const obj = payload as RawContentTypesPage | null;
+	if (obj?.items && Array.isArray(obj.items)) return obj.items;
+	if (obj?.contentTypes && Array.isArray(obj.contentTypes)) return obj.contentTypes;
+	return [];
+}
+
+/** True when the entry is not explicitly marked non-searchable. */
+function isSearchable(entry: RawContentTypeEntry): boolean {
+	if (typeof entry.isSearchable === "boolean") return entry.isSearchable;
+	if (typeof entry.searchable === "boolean") return entry.searchable;
+	// No flag present → do not exclude on searchability (FQN validity still gates).
+	return true;
+}
+
+/**
+ * Extracts the prefixed FQN from an entry. `id` is the current field; the
+ * others are fallbacks for alternate/legacy payloads. `name` is intentionally
+ * NOT read here — it is the bare (unprefixed) developer name and would fail
+ * `isValidCmsFqn`.
+ */
+function entryFqn(entry: RawContentTypeEntry): string | undefined {
+	return entry.id ?? entry.contentType ?? entry.fqn ?? entry.developerName;
+}
+
+/**
+ * Fetches every searchable content type for `channelId`, paginating the
+ * Connect endpoint until a short page is returned, then filtering to searchable
+ * entries whose FQN passes `isValidCmsFqn`. Each result carries the FQN and the
+ * server-provided display `label` (falling back to a derived label only when
+ * the response omits one). De-duplicates by FQN, preserving first-seen order.
+ *
+ * @throws when `channelId` fails the shape guard (before any network call).
+ */
+export async function fetchSearchableContentTypes(
+	channelId: string,
+): Promise<DiscoveredContentType[]> {
+	if (!CHANNEL_ID_PATTERN.test(channelId)) {
+		throw new Error(`Invalid CMS channel id "${channelId}".`);
+	}
+
+	const encoded = safeEncodePath(channelId);
+	const collected: DiscoveredContentType[] = [];
+	const seen = new Set<string>();
+
+	for (let page = 0; page < MAX_PAGES; page++) {
+		const url = connectUrl(
+			`/cms/channels/${encoded}/searchable-content-types?page=${page}&pageSize=${REST_PAGE_SIZE}`,
+		);
+		const payload = await connectGetJson(url);
+		const items = pageItems(payload);
+
+		for (const entry of items) {
+			const fqn = entryFqn(entry);
+			if (!fqn || !isSearchable(entry) || !isValidCmsFqn(fqn) || seen.has(fqn)) {
+				continue;
+			}
+			seen.add(fqn);
+			// Prefer the server label; fall back to a label derived from the FQN.
+			const label = entry.label?.trim() || formatContentTypeLabel(fqn);
+			collected.push({ fqn, label });
+		}
+
+		// Last page reached when fewer than a full page came back.
+		if (items.length < REST_PAGE_SIZE) break;
+	}
+
+	return collected;
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/adapters/cms/channelResolver.ts

@@ -0,0 +1,40 @@
+/**
+ * Extracts the CMS channel id from a search result so it can feed the
+ * searchable-content-types Connect endpoint. There is one CMS channel for the
+ * app, so any result carries it:
+ *
+ *   nodes[0].managedContentChannelDeliveryDetails[0].managedContentChannelDetails.id
+ *
+ * Returns `null` when any hop is missing (empty nodes, missing delivery
+ * details, missing channel details / id) — the caller simply skips discovery.
+ */
+
+import type { SourceResult } from "../../types";
+import type { CmsSearchResponse, CmsSearchItem } from "./types";
+
+/** Accepts either a normalised `SourceResult` or a raw `CmsSearchResponse`. */
+type ChannelSource = SourceResult | CmsSearchResponse | null | undefined;
+
+function getNodes(result: ChannelSource): unknown[] {
+	if (!result) return [];
+	// SourceResult carries `nodes`; CmsSearchResponse carries `items`.
+	if ("nodes" in result && Array.isArray(result.nodes)) return result.nodes;
+	if ("items" in result && Array.isArray(result.items)) return result.items;
+	return [];
+}
+
+/**
+ * Returns the channel id derived from the first result's delivery details, or
+ * `null` when any level is absent. Validate the returned id's shape before it
+ * enters a REST path (the discovery service does this).
+ */
+export function resolveChannelId(result: ChannelSource): string | null {
+	const nodes = getNodes(result);
+	const first = nodes[0] as Partial<CmsSearchItem> | undefined;
+	if (!first) return null;
+
+	const delivery = first.managedContentChannelDeliveryDetails?.[0];
+	const id = delivery?.managedContentChannelDetails?.id;
+
+	return typeof id === "string" && id.length > 0 ? id : null;
+}

package/lib/templates/project/reactexternalapp/_p_/_m_/_w_/_a_/src/_f_/search/adapters/cms/cmsQueryFragment.ts

@@ -0,0 +1,97 @@
+/**
+ * Builds the CMS `managed_content { search { searchContentInChannels … } }`
+ * fragment as a {@link QueryFragmentContribution} with `placement: "root"` — a
+ * sibling of the `uiapi` block in the combined document.
+ *
+ * The `$cmsContentTypeFQNs` declaration, its `contentTypeFQNs:` argument, and
+ * its variable value are all emitted only when a non-empty content-type list is
+ * passed; on the bootstrap call (no types known) they are omitted entirely.
+ */
+
+import type { QueryFragmentContribution } from "../types";
+
+export interface BuildCmsFragmentParams {
+	/** Search keyword → `$cmsKeyword`. */
+	keyword: string;
+	/** UIBundle Id fed into the query → `$UIBundleId` (from `getUIBundleId()`). */
+	uiBundleId: string;
+	/** Pagination offset → `$cmsOffset` (already clamped `>= 0` by the caller). */
+	offset: number;
+	/** Page size → `$cmsLimit` (validated against `pageSizeOptions` upstream). */
+	limit: number;
+	/**
+	 * Discovered/selected content-type FQNs → the schema's `contentTypeFQNs`
+	 * argument (via `$cmsContentTypeFQNs`). When absent, null, or empty, those
+	 * pieces are omitted entirely (bootstrap call). Callers pass ONLY
+	 * `isValidCmsFqn`-validated values.
+	 */
+	contentTypes?: string[] | null;
+}
+
+/**
+ * Builds the CMS fragment contribution. The content-type filter pieces are
+ * included only when `params.contentTypes` is a non-empty array.
+ */
+export function buildCmsQueryFragment(params: BuildCmsFragmentParams): QueryFragmentContribution {
+	const { keyword, uiBundleId, offset, limit, contentTypes } = params;
+
+	const hasContentTypes = Array.isArray(contentTypes) && contentTypes.length > 0;
+
+	const variableDeclarations = [
+		"$cmsKeyword: String!",
+		"$UIBundleId: ID!",
+		"$cmsOffset: Int!",
+		"$cmsLimit: Int!",
+	];
+
+	const variables: Record<string, unknown> = {
+		cmsKeyword: keyword,
+		UIBundleId: uiBundleId,
+		cmsOffset: offset,
+		cmsLimit: limit,
+	};
+
+	// CONDITIONAL: declare + pass + supply the content-type filter only when a
+	// non-empty list is provided. Otherwise these three pieces are all absent.
+	// The schema argument is `contentTypeFQNs` (a list of content-type FQNs) —
+	// NOT `contentTypes`; the latter is rejected as an unknown field argument.
+	const contentTypesArg = hasContentTypes ? "\n          contentTypeFQNs: $cmsContentTypeFQNs" : "";
+	if (hasContentTypes) {
+		variableDeclarations.push("$cmsContentTypeFQNs: [String!]");
+		variables.cmsContentTypeFQNs = contentTypes;
+	}
+
+	const fragment = `managed_content {
+  search {
+    searchContentInChannels(
+      searchIdentifiers: { uibundleIds: [$UIBundleId] }
+      keyword: $cmsKeyword
+      pagination: { limit: $cmsLimit, offset: $cmsOffset }${contentTypesArg}
+    ) {
+      total
+      offset
+      pageSize
+      items {
+        managedContentId
+        managedContentKey
+        title
+        contentType
+        language
+        highlightedSnippet
+        managedContentChannelDeliveryDetails {
+          contentUrl
+          publishedDate
+          managedContentChannelDetails { id name type }
+        }
+      }
+    }
+  }
+}`;
+
+	return {
+		variableDeclarations,
+		variables,
+		placement: "root",
+		fragment,
+	};
+}