@conduction/nextcloud-vue 1.0.0-beta.20 → 1.0.0-beta.22

package/src/utils/resolveManifestSentinels.js

@@ -0,0 +1,268 @@
+/**
+ * Manifest `@resolve:` sentinel resolver.
+ *
+ * Implements the `manifest-resolve-sentinel` capability: walks the
+ * `pages[].config` subtrees of an assembled manifest and replaces every
+ * fully-matched `@resolve:<key>` string with the result of the consuming
+ * app's `IAppConfig` lookup for `<key>`. Other manifest paths
+ * (`route`, `id`, top-level fields, `menu[]`, `pages[].component` etc.)
+ * are intentionally untouched — sentinels there are router / registry
+ * invariants and the schema validator rejects them.
+ *
+ * Resolution source (canonical, per spec):
+ *
+ *  1. `@nextcloud/initial-state` provisioned key
+ *     `app-{appId}-{key}` — zero-network, preferred.
+ *  2. Runtime `GET /index.php/apps/{appId}/api/configs/{key}` — falls
+ *     through silently on 4xx / network error.
+ *  3. `null` — unresolved.
+ *
+ * Empty-state semantics: an unset / empty value substitutes `null` (not
+ * empty string) and is accumulated into the returned `unresolved` array
+ * so consumers can render an admin warning. A `console.warn` is emitted
+ * once per unresolved key with the offending sentinel.
+ *
+ * The resolver is intentionally split into a synchronous walk + an
+ * asynchronous batch resolution: every sentinel is collected first, then
+ * each unique `(appId, key)` is resolved exactly once (initial-state
+ * lookup is synchronous; runtime fetch is per-key cached for the page
+ * lifetime), and finally the manifest is rewritten in a second walk
+ * with the resolved values. This makes the substitution deterministic
+ * — five `@resolve:foo` references in five pages share one fetch.
+ *
+ * @module utils/resolveManifestSentinels
+ */
+
+const SENTINEL_PATTERN = /^@resolve:([a-z][a-z0-9_-]*)$/
+
+/**
+ * Process-wide cache of resolved IAppConfig values, keyed by
+ * `${appId}::${key}`. Cleared via `clearResolveCache()` (test-only).
+ *
+ * @type {Map<string, Promise<*>>}
+ */
+const resolveCache = new Map()
+
+/**
+ * Test-only helper to reset the per-page resolve cache between runs.
+ * Production callers do not need this — the cache is page-lifetime by
+ * design, consistent with the manifest's load-once model.
+ *
+ * @return {void}
+ */
+export function clearResolveCache() {
+	resolveCache.clear()
+}
+
+/**
+ * Walk the manifest's `pages[].config` subtrees and replace every
+ * `@resolve:<key>` sentinel with the resolved IAppConfig value.
+ *
+ * Returns a Promise resolving to `{ manifest, unresolved }`:
+ *  - `manifest` — a NEW manifest object with sentinels substituted; the
+ *    input is NOT mutated.
+ *  - `unresolved` — array of IAppConfig keys whose sentinels resolved
+ *    to `null` (unset / empty / fetch failure). Useful for surfacing
+ *    "n settings unconfigured" admin warnings.
+ *
+ * Sentinels OUTSIDE `pages[].config` are left intact; the schema
+ * validator rejects them downstream so consumers see a clear error
+ * rather than a silent substitution that breaks routing or registry
+ * lookups.
+ *
+ * @param {object} manifest The merged (bundled + backend) manifest.
+ *   Walked but not mutated.
+ * @param {string} appId Nextcloud app ID. Used to scope the
+ *   IAppConfig lookup namespace.
+ * @param {object} [options] Resolver overrides.
+ * @param {Function} [options.getAppConfigValue] Async (appId, key) =>
+ *   value resolver. Override for tests; defaults to the
+ *   initial-state-then-fetch chain documented above.
+ * @param {Function} [options.warn] Override for `console.warn`. Used in
+ *   tests to capture warning calls without polluting test output.
+ * @return {Promise<{ manifest: object, unresolved: string[] }>}
+ */
+export async function resolveManifestSentinels(manifest, appId, options = {}) {
+	if (!isPlainObject(manifest)) {
+		return { manifest, unresolved: [] }
+	}
+
+	const getAppConfigValue = options.getAppConfigValue ?? defaultGetAppConfigValue
+	const warn = options.warn ?? ((...args) => {
+		// eslint-disable-next-line no-console
+		console.warn(...args)
+	})
+
+	// Phase 1: scan for sentinels under pages[].config only. We only
+	// need the unique key set — the second walk does the substitution.
+	const keys = new Set()
+	const pages = Array.isArray(manifest.pages) ? manifest.pages : []
+	for (const page of pages) {
+		if (!isPlainObject(page) || !isPlainObject(page.config)) continue
+		collectSentinelKeys(page.config, keys)
+	}
+
+	if (keys.size === 0) {
+		return { manifest, unresolved: [] }
+	}
+
+	// Phase 2: resolve each unique (appId, key) exactly once.
+	const resolved = new Map()
+	const unresolved = []
+	await Promise.all(Array.from(keys).map(async (key) => {
+		const value = await getAppConfigValue(appId, key)
+		if (value === undefined || value === null || value === '') {
+			resolved.set(key, null)
+			unresolved.push(key)
+			warn(`[resolveManifestSentinels] Manifest sentinel '@resolve:${key}' resolved to null (key unset)`)
+		} else {
+			resolved.set(key, value)
+		}
+	}))
+
+	// Phase 3: rebuild the manifest immutably, substituting sentinels in
+	// pages[].config only. Other fields are passed through by reference.
+	const out = { ...manifest }
+	out.pages = pages.map((page) => {
+		if (!isPlainObject(page) || !isPlainObject(page.config)) return page
+		return { ...page, config: substituteInTree(page.config, resolved) }
+	})
+
+	return { manifest: out, unresolved }
+}
+
+/**
+ * Recursively scan a tree, accumulating every sentinel key into the
+ * provided `keys` Set. Plain objects + arrays are descended; primitive
+ * leaves are checked against the sentinel pattern.
+ *
+ * @param {*} node Current tree node (object, array, or primitive).
+ * @param {Set<string>} keys Accumulator for unique sentinel keys.
+ * @return {void}
+ */
+function collectSentinelKeys(node, keys) {
+	if (typeof node === 'string') {
+		const match = node.match(SENTINEL_PATTERN)
+		if (match) keys.add(match[1])
+		return
+	}
+	if (Array.isArray(node)) {
+		for (const item of node) collectSentinelKeys(item, keys)
+		return
+	}
+	if (isPlainObject(node)) {
+		for (const value of Object.values(node)) collectSentinelKeys(value, keys)
+	}
+}
+
+/**
+ * Recursively rebuild a tree, replacing each fully-matched sentinel
+ * with its resolved value. Returns a NEW tree; input is unchanged.
+ *
+ * @param {*} node Current tree node.
+ * @param {Map<string,*>} resolved Map of key → resolved value (or null).
+ * @return {*} New tree with sentinels substituted.
+ */
+function substituteInTree(node, resolved) {
+	if (typeof node === 'string') {
+		const match = node.match(SENTINEL_PATTERN)
+		if (match && resolved.has(match[1])) {
+			return resolved.get(match[1])
+		}
+		return node
+	}
+	if (Array.isArray(node)) {
+		return node.map((item) => substituteInTree(item, resolved))
+	}
+	if (isPlainObject(node)) {
+		const out = {}
+		for (const [key, value] of Object.entries(node)) {
+			out[key] = substituteInTree(value, resolved)
+		}
+		return out
+	}
+	return node
+}
+
+/**
+ * Default `getAppConfigValue` implementation: consult
+ * `@nextcloud/initial-state` first (zero-network), fall back to a
+ * runtime fetch with per-(appId, key) caching for the page lifetime.
+ *
+ * Returns `null` when neither source resolves a value. Network / 4xx
+ * errors are swallowed silently — the resolver downgrades to "key
+ * unset" in that case (consistent with the silent-fallback pattern in
+ * `useAppManifest`'s backend-merge step).
+ *
+ * @param {string} appId Nextcloud app ID.
+ * @param {string} key IAppConfig key (already validated as
+ *   lowercase + alphanumeric + `_-` by the sentinel regex).
+ * @return {Promise<*>} Resolved value or `null` when unset.
+ */
+async function defaultGetAppConfigValue(appId, key) {
+	const cacheKey = `${appId}::${key}`
+	if (resolveCache.has(cacheKey)) {
+		return resolveCache.get(cacheKey)
+	}
+	const promise = (async () => {
+		// Step 1: initial-state — synchronous, zero-network.
+		const initial = readInitialState(appId, key)
+		if (initial !== undefined && initial !== null && initial !== '') {
+			return initial
+		}
+		// Step 2: runtime fetch — silent fallback on any error.
+		try {
+			const { default: axios } = await import('@nextcloud/axios')
+			const { generateUrl } = await import('@nextcloud/router')
+			const url = generateUrl(`/apps/${appId}/api/configs/${key}`)
+			const response = await axios.get(url)
+			if (response && response.status === 200 && response.data !== undefined) {
+				const data = response.data
+				// API may return either a raw scalar or `{ value: ... }`.
+				if (isPlainObject(data) && 'value' in data) return data.value
+				return data
+			}
+		} catch (e) {
+			// Silent — caller treats as "unset".
+		}
+		return null
+	})()
+	resolveCache.set(cacheKey, promise)
+	return promise
+}
+
+/**
+ * Read a key from `@nextcloud/initial-state`. Looks up the conventional
+ * `app-{appId}-{key}` slot. Returns `undefined` when the package is not
+ * installed (e.g. older host) or the key is not provisioned.
+ *
+ * @param {string} appId Nextcloud app ID.
+ * @param {string} key IAppConfig key.
+ * @return {*} Provisioned value or `undefined`.
+ */
+function readInitialState(appId, key) {
+	try {
+		// `@nextcloud/initial-state` is an optional peer; the host page
+		// may not provision the slot at all. We resolve via require so
+		// jest mocks the import; bundle-side, the package is treeshaken
+		// when no caller pulls it in.
+		// eslint-disable-next-line global-require, import/no-unresolved, n/no-extraneous-require
+		const mod = require('@nextcloud/initial-state')
+		if (typeof mod.loadState === 'function') {
+			return mod.loadState(appId, key, undefined)
+		}
+	} catch (e) {
+		// Package not installed or no slot provisioned — fall through.
+	}
+	return undefined
+}
+
+/**
+ * Type guard — true when value is a plain (non-array, non-null) object.
+ *
+ * @param {*} value Candidate.
+ * @return {boolean} True when value is a plain object.
+ */
+function isPlainObject(value) {
+	return value !== null && typeof value === 'object' && !Array.isArray(value)
+}

package/src/utils/validateManifest.js

@@ -1,3 +1,26 @@
+/**
+ * Pattern matching the `manifest-resolve-sentinel` capability's
+ * sentinel — `@resolve:<key>` where `<key>` is lowercase alphanumeric
+ * with `_` / `-` separators. The full string IS the sentinel; partial
+ * substitution like `prefix-@resolve:foo` is NOT supported and is left
+ * as a plain string for downstream renderers.
+ *
+ * Build-time validation accepts this pattern as a valid `string` for
+ * any `string`-typed field UNDER `pages[].config`, regardless of any
+ * narrower per-field constraint. Other paths reject it explicitly.
+ */
+const SENTINEL_PATTERN = /^@resolve:[a-z][a-z0-9_-]*$/
+
+/**
+ * Test whether a string is a manifest `@resolve:` sentinel.
+ *
+ * @param {*} value Candidate value.
+ * @return {boolean} True when the value is a fully-matched sentinel.
+ */
+function isSentinel(value) {
+	return typeof value === 'string' && SENTINEL_PATTERN.test(value)
+}
+
 /**
  * Validate a manifest object against the manifest JSON Schema.
  *
@@ -15,6 +38,13 @@
  *  - `pages[].component` is required when `type` is "custom".
  *  - Per-type `config` shape rules for the built-in types `logs`,
  *    `settings`, `chat`, `files` (REQ from manifest-page-type-extensions).
+ *  - The `manifest-resolve-sentinel` sentinel `@resolve:<key>` is
+ *    permissively accepted under `pages[].config.*` and explicitly
+ *    REJECTED in `version`, `dependencies[]`, `menu[].route`,
+ *    `menu[].id`, `pages[].id`, `pages[].route`, `pages[].component`,
+ *    `pages[].headerComponent`, `pages[].actionsComponent`,
+ *    `pages[].slots.*` — those are router invariants or registry
+ *    keys.
  *
  * The richer schema constraints (`additionalProperties: false`, `format`
  * URI, etc.) are enforced by the BE / hydra CI validators that consume
@@ -42,6 +72,10 @@ export function validateManifest(manifest, options = {}) {
 
 	if (typeof manifest.version !== 'string') {
 		errors.push('/version must be a string')
+	} else if (isSentinel(manifest.version)) {
+		// `manifest-resolve-sentinel` REQ-MRS-004: sentinel is a router /
+		// registry invariant violation when used here.
+		errors.push(`/version "${manifest.version}" must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
 	} else if (!versionPattern.test(manifest.version)) {
 		errors.push(`/version "${manifest.version}" must match semver pattern`)
 	}
@@ -54,8 +88,15 @@ export function validateManifest(manifest, options = {}) {
 				errors.push(`/menu/${index} must be an object`)
 				return
 			}
-			if (typeof item.id !== 'string') errors.push(`/menu/${index}/id must be a string`)
+			if (typeof item.id !== 'string') {
+				errors.push(`/menu/${index}/id must be a string`)
+			} else if (isSentinel(item.id)) {
+				errors.push(`/menu/${index}/id must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+			}
 			if (typeof item.label !== 'string') errors.push(`/menu/${index}/label must be a string`)
+			if (item.route !== undefined && isSentinel(item.route)) {
+				errors.push(`/menu/${index}/route must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+			}
 			if (item.children !== undefined && !Array.isArray(item.children)) {
 				errors.push(`/menu/${index}/children must be an array`)
 			}
@@ -77,12 +118,18 @@ export function validateManifest(manifest, options = {}) {
 			}
 			if (typeof page.id !== 'string') {
 				errors.push(`/pages/${index}/id must be a string`)
+			} else if (isSentinel(page.id)) {
+				errors.push(`/pages/${index}/id must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
 			} else if (seenIds.has(page.id)) {
 				errors.push(`/pages/${index}/id "${page.id}" must be unique within pages[]`)
 			} else {
 				seenIds.add(page.id)
 			}
-			if (typeof page.route !== 'string') errors.push(`/pages/${index}/route must be a string`)
+			if (typeof page.route !== 'string') {
+				errors.push(`/pages/${index}/route must be a string`)
+			} else if (isSentinel(page.route)) {
+				errors.push(`/pages/${index}/route must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+			}
 			if (typeof page.title !== 'string') errors.push(`/pages/${index}/title must be a string`)
 			if (typeof page.type !== 'string' || page.type.length === 0) {
 				errors.push(`/pages/${index}/type must be a non-empty string`)
@@ -92,6 +139,25 @@ export function validateManifest(manifest, options = {}) {
 			if (page.type === 'custom' && typeof page.component !== 'string') {
 				errors.push(`/pages/${index}/component is required when type is "custom"`)
 			}
+			// `manifest-resolve-sentinel` REQ-MRS-004: registry-key
+			// fields cannot be dynamic — they resolve at module-load
+			// time against `customComponents`, before the loader runs.
+			if (page.component !== undefined && isSentinel(page.component)) {
+				errors.push(`/pages/${index}/component must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+			}
+			if (page.headerComponent !== undefined && isSentinel(page.headerComponent)) {
+				errors.push(`/pages/${index}/headerComponent must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+			}
+			if (page.actionsComponent !== undefined && isSentinel(page.actionsComponent)) {
+				errors.push(`/pages/${index}/actionsComponent must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+			}
+			if (isPlainObject(page.slots)) {
+				for (const [slotName, slotValue] of Object.entries(page.slots)) {
+					if (isSentinel(slotValue)) {
+						errors.push(`/pages/${index}/slots/${slotName} must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
+					}
+				}
+			}
 
 			// Per-type config-shape validation for built-in extended types.
 			// (`manifest-page-type-extensions` spec — covers logs/settings/chat/files.)
@@ -115,6 +181,8 @@ export function validateManifest(manifest, options = {}) {
 			manifest.dependencies.forEach((dep, index) => {
 				if (typeof dep !== 'string') {
 					errors.push(`/dependencies/${index} must be a string`)
+				} else if (isSentinel(dep)) {
+					errors.push(`/dependencies/${index} must not be a @resolve: sentinel (sentinels are only valid under pages[].config.*)`)
 				}
 			})
 		}
@@ -178,7 +246,70 @@ function validateTypeConfig(page, index, errors) {
 		break
 	}
 	case 'settings': {
-		if (!cfg || !Array.isArray(cfg.sections)) {
+		// `manifest-settings-orchestration` REQ-MSO-1: a settings page
+		// MUST declare EXACTLY ONE of `sections` | `tabs`. When both
+		// are set, emit the orchestration mutex error. When neither is
+		// set, fall through to the legacy `sections required` error
+		// (back-compat — REQ-MSO-7 / REQ-MSO-1 last scenario).
+		const hasSections = cfg && Array.isArray(cfg.sections)
+		const hasTabs = cfg && Array.isArray(cfg.tabs)
+
+		if (hasSections && hasTabs) {
+			errors.push(`${pathSlash}: ${pathBracket}: must declare exactly one of sections | tabs`)
+			break
+		}
+
+		if (hasTabs) {
+			// `manifest-settings-orchestration` REQ-MSO-2..4: validate
+			// the `tabs[]` orchestration shape.
+			if (cfg.tabs.length === 0) {
+				errors.push(`${pathSlash}/tabs: ${pathBracket}.tabs: must contain at least 1 tab`)
+				break
+			}
+			const seenTabIds = Object.create(null)
+			cfg.tabs.forEach((tab, tIndex) => {
+				if (!isPlainObject(tab)) {
+					errors.push(`${pathSlash}/tabs/${tIndex}: must be an object`)
+					return
+				}
+				if (typeof tab.id !== 'string' || tab.id.length === 0) {
+					errors.push(`${pathSlash}/tabs/${tIndex}/id: required, must be a non-empty string`)
+				}
+				if (typeof tab.label !== 'string' || tab.label.length === 0) {
+					errors.push(`${pathSlash}/tabs/${tIndex}/label: required, must be a non-empty string`)
+				}
+				// REQ-MSO-3: tab IDs must be unique within a page.
+				if (typeof tab.id === 'string' && tab.id.length > 0) {
+					if (seenTabIds[tab.id]) {
+						errors.push(`${pathSlash}/tabs/${tIndex}/id: ${pathBracket}.tabs[${tIndex}].id: duplicate id "${tab.id}" — tab IDs must be unique within a page`)
+					}
+					seenTabIds[tab.id] = true
+				}
+				// `tab.sections` MUST be a non-empty array.
+				if (!Array.isArray(tab.sections)) {
+					errors.push(`${pathSlash}/tabs/${tIndex}/sections: ${pathBracket}.tabs[${tIndex}].sections: required, must be an array`)
+					return
+				}
+				if (tab.sections.length === 0) {
+					errors.push(`${pathSlash}/tabs/${tIndex}/sections: ${pathBracket}.tabs[${tIndex}].sections: must contain at least 1 section`)
+					return
+				}
+				// REQ-MSO-4: each tab's sections follow the same rules
+				// as the flat case — share the per-section validator.
+				tab.sections.forEach((section, sIndex) => {
+					validateSettingsSection(
+						section,
+						`${pathSlash}/tabs/${tIndex}/sections/${sIndex}`,
+						`${pathBracket}.tabs[${tIndex}].sections[${sIndex}]`,
+						errors,
+					)
+				})
+			})
+			break
+		}
+
+		// Flat `sections[]` (existing path — REQ-MSRS-* + back-compat).
+		if (!hasSections) {
 			errors.push(`${pathSlash}/sections: ${pathBracket}.sections: required, must be an array`)
 			break
 		}
@@ -187,56 +318,12 @@ function validateTypeConfig(page, index, errors) {
 			break
 		}
 		cfg.sections.forEach((section, sIndex) => {
-			if (!isPlainObject(section)) {
-				errors.push(`${pathSlash}/sections/${sIndex}: must be an object`)
-				return
-			}
-			if (typeof section.title !== 'string') {
-				errors.push(`${pathSlash}/sections/${sIndex}/title: required, must be a string`)
-			}
-
-			// `manifest-settings-rich-sections` REQ-MSRS-1: each
-			// section MUST declare exactly one of fields | component
-			// | widgets. Mixed bodies confuse the renderer + duplicate
-			// the section chrome; empty bodies render nothing so they
-			// are a manifest-author bug.
-			const hasFields = Array.isArray(section.fields)
-			const hasComponent = typeof section.component === 'string' && section.component.length > 0
-			const hasWidgets = Array.isArray(section.widgets) && section.widgets.length > 0
-			const bodyCount = (hasFields ? 1 : 0) + (hasComponent ? 1 : 0) + (hasWidgets ? 1 : 0)
-
-			if (bodyCount !== 1) {
-				errors.push(`${pathSlash}/sections/${sIndex}: ${pathBracket}.sections[${sIndex}]: must declare exactly one of fields | component | widgets`)
-			}
-
-			// `widgets` set but not an array (string / object / etc.)
-			if (section.widgets !== undefined && !Array.isArray(section.widgets)) {
-				errors.push(`${pathSlash}/sections/${sIndex}/widgets: must be an array when set`)
-			}
-
-			// `component` set but not a string.
-			if (section.component !== undefined && typeof section.component !== 'string') {
-				errors.push(`${pathSlash}/sections/${sIndex}/component: must be a string when set`)
-			}
-
-			// Per-widget shape rules.
-			if (hasWidgets) {
-				section.widgets.forEach((widget, wIndex) => {
-					if (!isPlainObject(widget)) {
-						errors.push(`${pathSlash}/sections/${sIndex}/widgets/${wIndex}: must be an object`)
-						return
-					}
-					if (typeof widget.type !== 'string' || widget.type.length === 0) {
-						errors.push(`${pathSlash}/sections/${sIndex}/widgets/${wIndex}/type: must be a non-empty string`)
-					}
-				})
-			}
-
-			// `manifest-config-refs` REQ-MCR — when fields[] body is
-			// used, each entry must match the formField $def shape.
-			if (hasFields) {
-				validateFieldsArray(section.fields, `${pathSlash}/sections/${sIndex}/fields`, errors)
-			}
+			validateSettingsSection(
+				section,
+				`${pathSlash}/sections/${sIndex}`,
+				`${pathBracket}.sections[${sIndex}]`,
+				errors,
+			)
 		})
 		break
 	}
@@ -669,6 +756,82 @@ function validateLayoutArray(cfg, pathSlash, pathBracket, errors) {
 	})
 }
 
+/**
+ * Validate a single `sections[]` entry for `type:"settings"` pages.
+ * Shared between the flat `pages[].config.sections[]` path AND the
+ * tab-nested `pages[].config.tabs[].sections[]` path
+ * (`manifest-settings-orchestration` REQ-MSO-4).
+ *
+ * Enforces the rich-sections REQ-MSRS-1 mutex (`fields | component |
+ * widgets` exactly-one-of) plus per-widget shape rules. The new
+ * `widget.type === "component"` discriminator (REQ-MSO-6) requires
+ * `componentName: <non-empty string>`.
+ *
+ * @param {*} section The section under validation
+ * @param {string} pathSlash JSON-pointer-style path prefix for errors
+ * @param {string} pathBracket Human-readable bracket-path for errors
+ * @param {string[]} errors Accumulator
+ */
+function validateSettingsSection(section, pathSlash, pathBracket, errors) {
+	if (!isPlainObject(section)) {
+		errors.push(`${pathSlash}: must be an object`)
+		return
+	}
+	if (typeof section.title !== 'string') {
+		errors.push(`${pathSlash}/title: required, must be a string`)
+	}
+
+	// `manifest-settings-rich-sections` REQ-MSRS-1: exactly one of
+	// fields | component | widgets.
+	const hasFields = Array.isArray(section.fields)
+	const hasComponent = typeof section.component === 'string' && section.component.length > 0
+	const hasWidgets = Array.isArray(section.widgets) && section.widgets.length > 0
+	const bodyCount = (hasFields ? 1 : 0) + (hasComponent ? 1 : 0) + (hasWidgets ? 1 : 0)
+
+	if (bodyCount !== 1) {
+		errors.push(`${pathSlash}: ${pathBracket}: must declare exactly one of fields | component | widgets`)
+	}
+
+	// `widgets` set but not an array (string / object / etc.)
+	if (section.widgets !== undefined && !Array.isArray(section.widgets)) {
+		errors.push(`${pathSlash}/widgets: must be an array when set`)
+	}
+
+	// `component` set but not a string.
+	if (section.component !== undefined && typeof section.component !== 'string') {
+		errors.push(`${pathSlash}/component: must be a string when set`)
+	}
+
+	// Per-widget shape rules.
+	if (hasWidgets) {
+		section.widgets.forEach((widget, wIndex) => {
+			if (!isPlainObject(widget)) {
+				errors.push(`${pathSlash}/widgets/${wIndex}: must be an object`)
+				return
+			}
+			if (typeof widget.type !== 'string' || widget.type.length === 0) {
+				errors.push(`${pathSlash}/widgets/${wIndex}/type: must be a non-empty string`)
+				return
+			}
+			// `manifest-settings-orchestration` REQ-MSO-6: when the
+			// discriminator is "component", `componentName` MUST be a
+			// non-empty string. Other widget types ignore
+			// `componentName`.
+			if (widget.type === 'component') {
+				if (typeof widget.componentName !== 'string' || widget.componentName.length === 0) {
+					errors.push(`${pathSlash}/widgets/${wIndex}/componentName: required when type is "component", must be a non-empty string`)
+				}
+			}
+		})
+	}
+
+	// `manifest-config-refs` REQ-MCR — when fields[] body is used,
+	// each entry must match the formField $def shape.
+	if (hasFields) {
+		validateFieldsArray(section.fields, `${pathSlash}/fields`, errors)
+	}
+}
+
 /**
  * Validate `config.sections[].fields[]` for settings page type
  * (`manifest-config-refs` REQ-MCR). Each field MUST be an object with