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

package/dist/nextcloud-vue.cjs.js

@@ -43033,7 +43033,7 @@ var isObject = function isObject(obj) {
 }; // Strict object type check
 // Only returns true for plain JavaScript objects
 
-var isPlainObject$2 = function isPlainObject(obj) {
+var isPlainObject$3 = function isPlainObject(obj) {
   return Object.prototype.toString.call(obj) === '[object Object]';
 };
 var isDate = function isDate(value) {
@@ -43115,7 +43115,7 @@ var cloneDeep = function cloneDeep(obj) {
     }, []);
   }
 
-  if (isPlainObject$2(obj)) {
+  if (isPlainObject$3(obj)) {
     return keys(obj).reduce(function (result, key) {
       return _objectSpread$8(_objectSpread$8({}, result), {}, _defineProperty$b({}, key, cloneDeep(obj[key], obj[key])));
     }, {});
@@ -43323,7 +43323,7 @@ var kebabCase = function kebabCase(str) {
 
 var toString = function toString(val) {
   var spaces = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 2;
-  return isUndefinedOrNull(val) ? '' : isArray(val) || isPlainObject$2(val) && val.toString === Object.prototype.toString ? JSON.stringify(val, null, spaces) : String(val);
+  return isUndefinedOrNull(val) ? '' : isArray(val) || isPlainObject$3(val) && val.toString === Object.prototype.toString ? JSON.stringify(val, null, spaces) : String(val);
 }; // Remove leading white space from a string
 
 var ELEMENT_PROTO = Element$1.prototype;
@@ -43591,7 +43591,7 @@ var BVTransition = /*#__PURE__*/extend({
         props = _ref.props;
     var transProps = props.transProps;
 
-    if (!isPlainObject$2(transProps)) {
+    if (!isPlainObject$3(transProps)) {
       transProps = props.noFade ? NO_FADE_PROPS : FADE_PROPS;
 
       if (props.appear) {
@@ -43652,7 +43652,7 @@ var encode = function encode(str) {
 // See: https://github.com/vuejs/vue-router/blob/dev/src/util/query.js
 
 var stringifyQueryObj = function stringifyQueryObj(obj) {
-  if (!isPlainObject$2(obj)) {
+  if (!isPlainObject$3(obj)) {
     return '';
   }
 
@@ -43743,7 +43743,7 @@ var computeHref = function computeHref() {
   } // Fallback to `to.path' + `to.query` + `to.hash` prop (if `to` is an object)
 
 
-  if (isPlainObject$2(to) && (to.path || to.query || to.hash)) {
+  if (isPlainObject$3(to) && (to.path || to.query || to.hash)) {
     var path = toString(to.path);
     var query = stringifyQueryObj(to.query);
     var hash = toString(to.hash);
@@ -55925,6 +55925,29 @@ function useContextMenu() {
 	}
 }
 
+/**
+ * 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$1 = /^@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$1.test(value)
+}
+
 /**
  * Validate a manifest object against the manifest JSON Schema.
  *
@@ -55942,6 +55965,13 @@ function useContextMenu() {
  *  - `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
@@ -55961,7 +55991,7 @@ function useContextMenu() {
 function validateManifest(manifest, options = {}) {
 	const errors = [];
 
-	if (!isPlainObject$1(manifest)) {
+	if (!isPlainObject$2(manifest)) {
 		return { valid: false, errors: ['manifest must be an object'] }
 	}
 
@@ -55969,6 +55999,10 @@ 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`);
 	}
@@ -55977,12 +56011,19 @@ function validateManifest(manifest, options = {}) {
 		errors.push('/menu must be an array');
 	} else {
 		manifest.menu.forEach((item, index) => {
-			if (!isPlainObject$1(item)) {
+			if (!isPlainObject$2(item)) {
 				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`);
 			}
@@ -55998,18 +56039,24 @@ function validateManifest(manifest, options = {}) {
 	} else {
 		const seenIds = new Set();
 		manifest.pages.forEach((page, index) => {
-			if (!isPlainObject$1(page)) {
+			if (!isPlainObject$2(page)) {
 				errors.push(`/pages/${index} must be an object`);
 				return
 			}
 			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`);
@@ -56019,6 +56066,25 @@ 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$2(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.)
@@ -56042,6 +56108,8 @@ 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.*)`);
 				}
 			});
 		}
@@ -56050,7 +56118,7 @@ function validateManifest(manifest, options = {}) {
 	return { valid: errors.length === 0, errors }
 }
 
-function isPlainObject$1(value) {
+function isPlainObject$2(value) {
 	return value !== null && typeof value === 'object' && !Array.isArray(value)
 }
 
@@ -56073,7 +56141,7 @@ function isPlainObject$1(value) {
  */
 function validateTypeConfig(page, index, errors) {
 	if (!page || typeof page.type !== 'string') return
-	const cfg = isPlainObject$1(page.config) ? page.config : null;
+	const cfg = isPlainObject$2(page.config) ? page.config : null;
 	const pathBracket = `pages[${index}].config`;
 	const pathSlash = `/pages/${index}/config`;
 
@@ -56127,7 +56195,7 @@ function validateTypeConfig(page, index, errors) {
 			}
 			const seenTabIds = Object.create(null);
 			cfg.tabs.forEach((tab, tIndex) => {
-				if (!isPlainObject$1(tab)) {
+				if (!isPlainObject$2(tab)) {
 					errors.push(`${pathSlash}/tabs/${tIndex}: must be an object`);
 					return
 				}
@@ -56270,12 +56338,12 @@ function validateTypeConfig(page, index, errors) {
  */
 function validateSidebarConfig(page, pageIndex, errors) {
 	const config = page.config;
-	if (!isPlainObject$1(config)) return
+	if (!isPlainObject$2(config)) return
 
 	// --- Index sidebar ---
 	if (page.type === 'index' && config.sidebar !== undefined) {
 		const path = `/pages/${pageIndex}/config/sidebar`;
-		if (!isPlainObject$1(config.sidebar)) {
+		if (!isPlainObject$2(config.sidebar)) {
 			errors.push(`${path} must be an object`);
 		} else {
 			if (config.sidebar.enabled !== undefined && typeof config.sidebar.enabled !== 'boolean') {
@@ -56288,13 +56356,13 @@ function validateSidebarConfig(page, pageIndex, errors) {
 			if (config.sidebar.columnGroups !== undefined && !Array.isArray(config.sidebar.columnGroups)) {
 				errors.push(`${path}/columnGroups must be an array`);
 			}
-			if (config.sidebar.facets !== undefined && !isPlainObject$1(config.sidebar.facets)) {
+			if (config.sidebar.facets !== undefined && !isPlainObject$2(config.sidebar.facets)) {
 				errors.push(`${path}/facets must be an object`);
 			}
 			if (config.sidebar.showMetadata !== undefined && typeof config.sidebar.showMetadata !== 'boolean') {
 				errors.push(`${path}/showMetadata must be a boolean`);
 			}
-			if (config.sidebar.search !== undefined && !isPlainObject$1(config.sidebar.search)) {
+			if (config.sidebar.search !== undefined && !isPlainObject$2(config.sidebar.search)) {
 				errors.push(`${path}/search must be an object`);
 			}
 		}
@@ -56309,7 +56377,7 @@ function validateSidebarConfig(page, pageIndex, errors) {
 		const path = `/pages/${pageIndex}/config/sidebar`;
 		const sb = config.sidebar;
 		const isBool = typeof sb === 'boolean';
-		const isObj = isPlainObject$1(sb);
+		const isObj = isPlainObject$2(sb);
 		if (!isBool && !isObj) {
 			errors.push(`${path} must be a boolean (legacy) or object`);
 		} else if (isObj) {
@@ -56349,7 +56417,7 @@ function validateSidebarConfig(page, pageIndex, errors) {
 	}
 
 	// --- Detail sidebar tabs (legacy sidebarProps.tabs path) ---
-	if (page.type === 'detail' && isPlainObject$1(config.sidebarProps) && config.sidebarProps.tabs !== undefined) {
+	if (page.type === 'detail' && isPlainObject$2(config.sidebarProps) && config.sidebarProps.tabs !== undefined) {
 		const tabsPath = `/pages/${pageIndex}/config/sidebarProps/tabs`;
 		validateDetailTabsArray(config.sidebarProps.tabs, tabsPath, errors);
 	}
@@ -56373,7 +56441,7 @@ function validateDetailTabsArray(tabs, tabsPath, errors) {
 	const seenIds = new Set();
 	tabs.forEach((tab, tabIndex) => {
 		const tabPath = `${tabsPath}/${tabIndex}`;
-		if (!isPlainObject$1(tab)) {
+		if (!isPlainObject$2(tab)) {
 			errors.push(`${tabPath} must be an object`);
 			return
 		}
@@ -56424,7 +56492,7 @@ function validateDetailTabsArray(tabs, tabsPath, errors) {
 function validatePageSidebar(page, pageIndex, errors) {
 	if (page.sidebar === undefined) return
 	const path = `/pages/${pageIndex}/sidebar`;
-	if (!isPlainObject$1(page.sidebar)) {
+	if (!isPlainObject$2(page.sidebar)) {
 		errors.push(`${path} must be an object`);
 		return
 	}
@@ -56462,7 +56530,7 @@ function validateColumnsArray(cfg, pathSlash, pathBracket, errors) {
 			// Legacy shorthand — accepted as-is.
 			return
 		}
-		if (!isPlainObject$1(col)) {
+		if (!isPlainObject$2(col)) {
 			errors.push(`${colPath}: must be a string (legacy shorthand) or object`);
 			return
 		}
@@ -56494,7 +56562,7 @@ function validateActionsArray(cfg, pathSlash, pathBracket, errors) {
 	}
 	cfg.actions.forEach((action, aIndex) => {
 		const actionPath = `${pathSlash}/actions/${aIndex}`;
-		if (!isPlainObject$1(action)) {
+		if (!isPlainObject$2(action)) {
 			errors.push(`${actionPath}: must be an object`);
 			return
 		}
@@ -56551,7 +56619,7 @@ function validateWidgetsArray(cfg, pathSlash, pathBracket, errors) {
 	}
 	cfg.widgets.forEach((widget, wIndex) => {
 		const widgetPath = `${pathSlash}/widgets/${wIndex}`;
-		if (!isPlainObject$1(widget)) {
+		if (!isPlainObject$2(widget)) {
 			errors.push(`${widgetPath}: must be an object`);
 			return
 		}
@@ -56586,7 +56654,7 @@ function validateLayoutArray(cfg, pathSlash, pathBracket, errors) {
 	}
 	cfg.layout.forEach((item, lIndex) => {
 		const layoutPath = `${pathSlash}/layout/${lIndex}`;
-		if (!isPlainObject$1(item)) {
+		if (!isPlainObject$2(item)) {
 			errors.push(`${layoutPath}: must be an object`);
 			return
 		}
@@ -56627,7 +56695,7 @@ function validateLayoutArray(cfg, pathSlash, pathBracket, errors) {
  * @param {string[]} errors Accumulator
  */
 function validateSettingsSection(section, pathSlash, pathBracket, errors) {
-	if (!isPlainObject$1(section)) {
+	if (!isPlainObject$2(section)) {
 		errors.push(`${pathSlash}: must be an object`);
 		return
 	}
@@ -56659,7 +56727,7 @@ function validateSettingsSection(section, pathSlash, pathBracket, errors) {
 	// Per-widget shape rules.
 	if (hasWidgets) {
 		section.widgets.forEach((widget, wIndex) => {
-			if (!isPlainObject$1(widget)) {
+			if (!isPlainObject$2(widget)) {
 				errors.push(`${pathSlash}/widgets/${wIndex}: must be an object`);
 				return
 			}
@@ -56702,7 +56770,7 @@ function validateFieldsArray(fields, fieldsPath, errors) {
 	if (!Array.isArray(fields)) return
 	fields.forEach((field, fIndex) => {
 		const fieldPath = `${fieldsPath}/${fIndex}`;
-		if (!isPlainObject$1(field)) {
+		if (!isPlainObject$2(field)) {
 			errors.push(`${fieldPath}: must be an object`);
 			return
 		}
@@ -56721,17 +56789,292 @@ function validateFieldsArray(fields, fieldsPath, errors) {
 }
 
 /**
- * Composable that loads and validates a Conduction app manifest.
+ * 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):
  *
- * The composable implements the three-phase flow specified in
- * REQ-JMR-002 of the json-manifest-renderer capability:
+ *  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}
+ */
+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[] }>}
+ */
+async function resolveManifestSentinels(manifest, appId, options = {}) {
+	if (!isPlainObject$1(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$1(page) || !isPlainObject$1(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$1(page) || !isPlainObject$1(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$1(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$1(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$1(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$1(value) {
+	return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/**
+ * Composable that loads, resolves, and validates a Conduction app manifest.
+ *
+ * The composable implements the four-phase flow specified in
+ * REQ-JMR-002 of the json-manifest-renderer capability + the
+ * substitution step from the `manifest-resolve-sentinel` capability:
  *
  *  1. Synchronous bundled load — `bundledManifest` is the immediate value.
  *  2. Async backend merge — fetches `/index.php/apps/{appId}/api/manifest`
  *     and deep-merges any 200 response over the bundled manifest. 4xx /
  *     5xx / network errors are silently ignored so apps work without a
  *     backend endpoint.
- *  3. Validation — the merged result is validated against
+ *  3. Sentinel resolution — `@resolve:<key>` strings under
+ *     `pages[].config` are substituted with `IAppConfig` values via the
+ *     `resolveManifestSentinels` utility (see its module docs for the
+ *     resolution source chain). Unresolved keys surface on the
+ *     returned `unresolvedSentinels` ref.
+ *  4. Validation — the resolved result is validated against
  *     `app-manifest.schema.json`. On failure, the bundled manifest is
  *     kept and a `console.warn` is emitted with the error list.
  *
@@ -56739,7 +57082,8 @@ function validateFieldsArray(fields, fieldsPath, errors) {
  * can hot-swap the manifest without a page reload.
  *
  * @param {string} appId Nextcloud app ID. Used to build the default
- *   backend endpoint URL via `@nextcloud/router`.
+ *   backend endpoint URL via `@nextcloud/router` and to scope
+ *   IAppConfig lookups for `@resolve:<key>` sentinels.
  * @param {object} bundledManifest The manifest shipped with the app (the
  *   default value, available synchronously).
  * @param {object} [options] Configuration options.
@@ -56749,7 +57093,10 @@ function validateFieldsArray(fields, fieldsPath, errors) {
  *   return a promise resolving to `{ status: number, data: object }`.
  *   Defaults to `axios.get` from `@nextcloud/axios` (which inherits the
  *   Nextcloud CSRF token automatically).
- * @return {{ manifest: import('vue').Ref<object>, isLoading: import('vue').Ref<boolean>, validationErrors: import('vue').Ref<string[]|null> }}
+ * @param {Function} [options.getAppConfigValue] Override the
+ *   IAppConfig resolver consumed by `resolveManifestSentinels`. Useful
+ *   for tests that want to mount a fixture-driven config map.
+ * @return {{ manifest: import('vue').Ref<object>, isLoading: import('vue').Ref<boolean>, validationErrors: import('vue').Ref<string[]|null>, unresolvedSentinels: import('vue').Ref<string[]> }}
  *
  * @example Basic usage (Composition API)
  * const { manifest, isLoading } = useAppManifest('decidesk', bundled)
@@ -56766,11 +57113,17 @@ function validateFieldsArray(fields, fieldsPath, errors) {
  *   endpoint: '/custom/manifest/url',
  *   fetcher: (url) => Promise.resolve({ status: 200, data: { ... } }),
  * })
+ *
+ * @example With sentinel resolution + admin warning surface
+ * const { manifest, unresolvedSentinels } = useAppManifest('softwarecatalog', bundled)
+ * // unresolvedSentinels.value is e.g. ['voorzieningen_register']
+ * // when that IAppConfig key is unset on the tenant.
  */
 function useAppManifest(appId, bundledManifest, options = {}) {
 	const manifest = Vue.ref(bundledManifest);
 	const isLoading = Vue.ref(true);
 	const validationErrors = Vue.ref(null);
+	const unresolvedSentinels = Vue.ref([]);
 
 	const endpoint = options.endpoint ?? router.generateUrl(`/apps/${appId}/api/manifest`);
 	const fetcher = options.fetcher ?? ((url) => axios.get(url))
@@ -56782,7 +57135,18 @@ function useAppManifest(appId, bundledManifest, options = {}) {
 				return
 			}
 			const merged = deepMerge(bundledManifest, response.data);
-			const result = validateManifest(merged);
+
+			// Sentinel resolution runs BEFORE validation per
+			// REQ-MRS-002: the validator MUST NEVER observe an
+			// unresolved sentinel at runtime. Resolution failures
+			// (unset IAppConfig keys) substitute null and accumulate
+			// on `unresolvedSentinels`; they do NOT block validation.
+			const { manifest: resolved, unresolved } = await resolveManifestSentinels(merged, appId, {
+				getAppConfigValue: options.getAppConfigValue,
+			});
+			unresolvedSentinels.value = unresolved;
+
+			const result = validateManifest(resolved);
 			if (!result.valid) {
 				validationErrors.value = result.errors;
 				// eslint-disable-next-line no-console
@@ -56792,7 +57156,7 @@ function useAppManifest(appId, bundledManifest, options = {}) {
 				);
 				return
 			}
-			manifest.value = merged;
+			manifest.value = resolved;
 		} catch (err) {
 			// Silent fallback on 404, network errors, non-200 responses.
 			// Apps without a backend endpoint should keep working.
@@ -56801,7 +57165,7 @@ function useAppManifest(appId, bundledManifest, options = {}) {
 		}
 	})();
 
-	return { manifest, isLoading, validationErrors }
+	return { manifest, isLoading, validationErrors, unresolvedSentinels }
 }
 
 /**
@@ -112612,6 +112976,7 @@ exports.SEARCH_TYPE = SEARCH_TYPE;
 exports.auditTrailsPlugin = auditTrailsPlugin;
 exports.buildHeaders = buildHeaders;
 exports.buildQueryString = buildQueryString;
+exports.clearResolveCache = clearResolveCache;
 exports.columnsFromSchema = columnsFromSchema;
 exports.createCrudStore = createCrudStore;
 exports.createObjectStore = createObjectStore;
@@ -112639,6 +113004,7 @@ exports.registerMappingPlugin = registerMappingPlugin;
 exports.registerTranslations = registerTranslations;
 exports.relationsPlugin = relationsPlugin;
 exports.resetVisibilityCache = resetVisibilityCache;
+exports.resolveManifestSentinels = resolveManifestSentinels;
 exports.searchPlugin = searchPlugin;
 exports.selectionPlugin = selectionPlugin;
 exports.useAppManifest = useAppManifest;