@ossy/app 1.40.3 → 3.0.2

package/README.md

@@ -70,6 +70,12 @@ export default {
 }
 ```
 
+Optional flags:
+
+| Key | Default | Purpose |
+|-----|---------|---------|
+| `enablePushInvalidation` | `false` | App-wide SSE cache invalidation. Prefer `<PushInvalidationSubscriber />` on specific pages instead — see [@ossy/sdk-react README](../sdk-react/README.md#push-invalidation). |
+
 Config is loaded at build time and merged with request-time settings (e.g. user theme preference from cookies).
 
 ## API routes

package/cli/get-platform-files.task.js

@@ -40,7 +40,7 @@ export const TRANSLATIONS_FILE_PATTERN = /\.translations\.json$/
  * @property {PlatformEntry[]} forms         Discovered `*.form.{js,mjs,cjs}` entries.
  * @property {PlatformEntry[]} e2es          Discovered `*.e2e.{js,mjs,cjs}` entries (installed packages only).
  * @property {PlatformEntry[]} flows         Discovered `*.flow.{js,mjs,cjs}` entries (installed packages only).
- * @property {PlatformEntry[]} layouts       Discovered `*.layout.{jsx,tsx,...}` entries (app root `src/` only — never from installed packages).
+ * @property {PlatformEntry[]} layouts       Discovered `*.layout.{jsx,tsx,...}` entries (app and installed packages).
  */
 export function discoverFilesByPattern (srcDir, filePattern) {
   const dir = path.resolve(srcDir)
@@ -183,8 +183,7 @@ export function discoverInstalledPackageEntries (projectRoot) {
       ...discoverFilesByPattern(packageSrcDir, FORM_FILE_PATTERN),
       ...discoverFilesByPattern(packageSrcDir, E2E_FILE_PATTERN),
       ...discoverFilesByPattern(packageSrcDir, FLOW_FILE_PATTERN),
-      // Layouts are intentionally excluded: *.layout.jsx is an app-level
-      // primitive only. Feature packages must never define layouts.
+      ...discoverFilesByPattern(packageSrcDir, LAYOUT_FILE_PATTERN),
     ]
     for (const sourcePath of files) {
       const stat = fs.statSync(sourcePath)
@@ -237,9 +236,8 @@ export default async function getPlatformFiles (srcDir) {
   // from the local `src/` — to avoid pulling in per-project duplicates of the
   // same aggregate class or test suite that is canonically owned by the feature
   // package.
-  // Layouts are the opposite restriction: they are only discovered from the
-  // app's own `src/`, never from installed packages. Feature packages are pure
-  // content (pages, actions, tasks, etc.) and must never define layouts.
+  // Layouts are discovered from the app's `src/` and from installed packages
+  // (`@ossy/app` ships default layouts via `ossy.src`).
   const localFiles = [
     ...discoverFilesByPattern(srcDir, PAGE_FILE_PATTERN),
     ...discoverFilesByPattern(srcDir, API_FILE_PATTERN),

package/cli/manifest-plugin.js

@@ -3,9 +3,9 @@ import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 import { metadataIdFromFile, defaultPageRoute } from './get-platform-files.task.js'
-import { discoverPackageDefinitions } from '../src/manifest/discover-package-definitions.js'
-import { buildActionsSchema } from '../src/manifest/build-actions-schema.js'
-import { buildCapabilities } from '../src/manifest/build-capabilities.js'
+import { discoverPackageDefinitions } from '@ossy/manifest/discover-package-definitions'
+import { buildActionsSchema } from '@ossy/manifest/build-actions-schema'
+import { buildCapabilities } from '@ossy/manifest/build-capabilities'
 import { extractTaskCatalogEntry, buildTaskCatalogEdges } from '../src/manifest/extract-task-catalog.js'
 import {
   Schema,
@@ -14,6 +14,11 @@ import {
   CAPABILITY_SCHEMA_ID,
 } from '@ossy/schema'
 import { isCanonicalSchemaId } from '@ossy/schema'
+import {
+  resolvePageLayoutId,
+  resolvePageShellSlots,
+  isCanonicalLayoutId,
+} from '../src/manifest/resolve-page-layout.js'
 
 /**
  * @typedef {import('./get-platform-files.task.js').PlatformEntry} PlatformEntry
@@ -86,7 +91,7 @@ import { isCanonicalSchemaId } from '@ossy/schema'
  * @property {string} entry        URL the platform serves the form bundle from.
  *
  * @typedef {object} LayoutManifestEntry
- * @property {string} id      Unique layout id (e.g. `'app-shell'`).
+ * @property {string} id      Canonical layout id (e.g. `'@ossy/app/layout/default'`).
  * @property {string} entry   URL the platform serves the layout bundle from.
  * @property {Record<string, string>} [slots]
  *   App-controlled slot map (`slotName` → component `metadata.id`), from `export const slots` in `*.layout.jsx`.
@@ -164,6 +169,17 @@ function entryPackage (entryInfo, appPackageName) {
   return entryInfo.packageName || appPackageName
 }
 
+/** Repo-relative path for Storybook / dev tooling (Vite source imports). */
+function manifestSourcePath (entryInfo, projectRoot) {
+  if (!entryInfo?.sourcePath || !projectRoot) return undefined
+  return path.relative(projectRoot, entryInfo.sourcePath).split(path.sep).join('/')
+}
+
+function withSourcePath (obj, entryInfo, projectRoot) {
+  const sourcePath = manifestSourcePath(entryInfo, projectRoot)
+  return sourcePath ? { ...obj, sourcePath } : obj
+}
+
 export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configValue, appPackageName = '@ossy/app', manifestPath, projectRoot }) {
   return {
     name: 'ossy-manifest',
@@ -205,6 +221,8 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
       /** @type {LayoutManifestEntry[]} */
       const layouts = []
       const seenLayoutIds = new Set()
+      /** @type {Map<string, { rawMeta: object, packageName: string }>} */
+      const pageMetaById = new Map()
       /** @type {Array<{ mod: object, entryInfo: import('./get-platform-files.task.js').PlatformEntry, url: string, pkg: string }>} */
       const taskPending = []
       for (const fileName of Object.keys(bundle)) {
@@ -256,7 +274,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate integration id "${integrationId}"`)
           }
           seenIntegrationIds.add(integrationId)
-          integrations.push({ id: integrationId, entry: url, credentials, package: entryPackage(entryInfo, appPackageName) })
+          integrations.push(withSourcePath({ id: integrationId, entry: url, credentials, package: entryPackage(entryInfo, appPackageName) }, entryInfo, projectRoot))
           continue
         }
 
@@ -279,7 +297,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate startup id "${startupId}"`)
           }
           seenStartupIds.add(startupId)
-          startups.push({ id: startupId, entry: url, package: entryPackage(entryInfo, appPackageName) })
+          startups.push(withSourcePath({ id: startupId, entry: url, package: entryPackage(entryInfo, appPackageName) }, entryInfo, projectRoot))
           continue
         }
 
@@ -303,7 +321,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate email id "${emailId}"`)
           }
           seenEmailIds.add(emailId)
-          emails.push({ id: emailId, entry: url, package: entryPackage(entryInfo, appPackageName) })
+          emails.push(withSourcePath({ id: emailId, entry: url, package: entryPackage(entryInfo, appPackageName) }, entryInfo, projectRoot))
           continue
         }
 
@@ -330,7 +348,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             entryInfo.sourcePath,
           )
           seenActionIds.add(actionId)
-          actions.push({ id: actionId, entry: url, access, package: entryPackage(entryInfo, appPackageName) })
+          actions.push(withSourcePath({ id: actionId, entry: url, access, package: entryPackage(entryInfo, appPackageName) }, entryInfo, projectRoot))
           continue
         }
 
@@ -352,12 +370,12 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate form id "${formId}"`)
           }
           seenFormIds.add(formId)
-          forms.push({
+          forms.push(withSourcePath({
             id: formId,
             schemaId,
             entry: url,
             package: entryPackage(entryInfo, appPackageName),
-          })
+          }, entryInfo, projectRoot))
           continue
         }
 
@@ -381,7 +399,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate aggregate id "${aggregateId}"`)
           }
           seenAggregateIds.add(aggregateId)
-          aggregates.push({ id: aggregateId, entry: url, package: entryPackage(entryInfo, appPackageName) })
+          aggregates.push(withSourcePath({ id: aggregateId, entry: url, package: entryPackage(entryInfo, appPackageName) }, entryInfo, projectRoot))
           continue
         }
 
@@ -409,13 +427,13 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate e2e id "${e2eId}"`)
           }
           seenE2eIds.add(e2eId)
-          e2es.push({
+          e2es.push(withSourcePath({
             id: e2eId,
             feature: typeof feature === 'string' ? feature : '',
             requires: Array.isArray(requires) ? requires : [],
             entry: url,
             package: entryPackage(entryInfo, appPackageName),
-          })
+          }, entryInfo, projectRoot))
           continue
         }
 
@@ -439,26 +457,36 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate flow id "${flowId}"`)
           }
           seenFlowIds.add(flowId)
-          flows.push({
+          flows.push(withSourcePath({
             id: flowId,
             feature: typeof feature === 'string' ? feature : '',
             requires: Array.isArray(requires) ? requires : [],
             entry: url,
             package: entryPackage(entryInfo, appPackageName),
-          })
+          }, entryInfo, projectRoot))
           continue
         }
 
-        // Layouts wrap every page render. The bundle exports `id` and a default
-        // export (the React component). Only one `*.layout.jsx` per app is
-        // supported. They don't produce routable entries; they accumulate into
-        // `manifest.layouts` so the server can inject them at render time.
+        // Layouts wrap page renders. The bundle exports metadata.id, optional slots,
+        // and a default export (the React component). They accumulate into
+        // `manifest.layouts` so the server can inject them at render time per page.
         if (entryInfo.kind === 'layout') {
-          const layoutId = mod && mod.id
+          const layoutMeta = mod?.metadata ?? {}
+          const layoutId =
+            typeof layoutMeta.id === 'string' && layoutMeta.id.trim()
+              ? layoutMeta.id.trim()
+              : typeof mod?.id === 'string'
+                ? mod.id.trim()
+                : ''
           const component = mod && mod.default
-          if (typeof layoutId !== 'string' || layoutId.trim() === '') {
+          if (!layoutId) {
             this.error(
-              `[@ossy/app][build] layout entry ${entryInfo.sourcePath} must export a non-empty string "id"`,
+              `[@ossy/app][build] layout entry ${entryInfo.sourcePath} must export metadata.id (canonical layout id)`,
+            )
+          }
+          if (!isCanonicalLayoutId(layoutId)) {
+            this.error(
+              `[@ossy/app][build] layout entry ${entryInfo.sourcePath} id must match @{provider}/{feature}/layout/{concept} — got "${layoutId}"`,
             )
           }
           if (typeof component !== 'function') {
@@ -496,12 +524,12 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
               layoutSlots[sk] = cid
             }
           }
-          layouts.push({
+          layouts.push(withSourcePath({
             id: layoutId,
             entry: url,
             package: entryPackage(entryInfo, appPackageName),
             ...(layoutSlots && Object.keys(layoutSlots).length > 0 ? { slots: layoutSlots } : {}),
-          })
+          }, entryInfo, projectRoot))
           continue
         }
 
@@ -526,7 +554,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             this.error(`[@ossy/app][build] Duplicate schema id "${schema.id}"`)
           }
           seenResourceIds.add(schema.id)
-          schemas.push({ ...schema, package: entryPackage(entryInfo, appPackageName) })
+          schemas.push(withSourcePath({ ...schema, package: entryPackage(entryInfo, appPackageName) }, entryInfo, projectRoot))
           continue
         }
 
@@ -549,7 +577,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
           seenIds.task.add(taskId)
           const pkg = entryPackage(entryInfo, appPackageName)
           taskPending.push({ mod, entryInfo, url, pkg })
-          entries.push({ type: 'task', id: taskId, entry: url, package: pkg })
+          entries.push(withSourcePath({ type: 'task', id: taskId, entry: url, package: pkg }, entryInfo, projectRoot))
           continue
         }
 
@@ -559,6 +587,14 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
           this.error(`[@ossy/app][build] ${entryInfo.kind} entry missing metadata.id: ${entryInfo.sourcePath}`)
         }
         if (seenIds[entryInfo.kind].has(id)) {
+          // App-local components are discovered first. Allow the app to shadow
+          // the same component id from an installed package (e.g. brand logos).
+          if (entryInfo.kind === 'component' && entryInfo.packageName) {
+            console.warn(
+              `[@ossy/app][build] Skipping package component "${id}" from ${entryInfo.packageName} — app already provides it`,
+            )
+            continue
+          }
           this.error(`[@ossy/app][build] Duplicate ${entryInfo.kind} id "${id}"`)
         }
         seenIds[entryInfo.kind].add(id)
@@ -570,7 +606,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
               'Assign components to app slots in `*.layout.jsx` via `export const slots`.',
             )
           }
-          components.push({ id, entry: url, package: entryPackage(entryInfo, appPackageName) })
+          components.push(withSourcePath({ id, entry: url, package: entryPackage(entryInfo, appPackageName) }, entryInfo, projectRoot))
           continue
         }
 
@@ -589,13 +625,17 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
             ),
             entryInfo.sourcePath,
           )
-          entries.push({
+          entries.push(withSourcePath({
             type: 'page',
             id,
             path: pagePath,
             title: rawMeta.title,
             entry: url,
             package: entryPackage(entryInfo, appPackageName),
+          }, entryInfo, projectRoot))
+          pageMetaById.set(id, {
+            rawMeta,
+            packageName: entryPackage(entryInfo, appPackageName),
           })
         } else if (entryInfo.kind === 'api') {
           // APIs have no sensible default route (unlike pages where we can
@@ -626,7 +666,7 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
               ...(Array.isArray(rawMeta.query) && rawMeta.query.length ? { query: rawMeta.query } : {}),
             }
           }
-          entries.push(apiEntry)
+          entries.push(withSourcePath(apiEntry, entryInfo, projectRoot))
         }
       }
 
@@ -677,18 +717,53 @@ export function manifestPlugin ({ entriesByStub, srcDir, staticOutDir, configVal
 
       const taskGraphEdges = buildTaskCatalogEdges(taskCatalog)
 
-      if (layouts.length > 1) {
-        this.error(
-          `[@ossy/app][build] Only one *.layout.jsx per app is allowed (found ${layouts.length}). ` +
-          'Use conditional rendering inside the app layout for route-specific chrome.',
-        )
-      }
-
       /** @type {Manifest} */
       const definitions = projectRoot
         ? await discoverPackageDefinitions(projectRoot)
         : {}
 
+      const layoutIdSet = new Set(layouts.map((layout) => layout.id))
+      const componentIdSet = new Set(components.map((component) => component.id))
+
+      for (const entry of entries) {
+        if (entry.type !== 'page') continue
+        const meta = pageMetaById.get(entry.id)
+        const layoutId = resolvePageLayoutId({
+          pageMetadata: meta?.rawMeta ?? {},
+          appConfig: configValue ?? {},
+        })
+        if (!layoutIdSet.has(layoutId)) {
+          this.error(
+            `[@ossy/app][build] page "${entry.id}" references layout "${layoutId}" which is not in manifest.layouts`,
+          )
+        }
+        if (!isCanonicalLayoutId(layoutId)) {
+          this.error(
+            `[@ossy/app][build] page "${entry.id}" layout must match @{provider}/{feature}/layout/{concept} — got "${layoutId}"`,
+          )
+        }
+        entry.layout = layoutId
+        const layoutDef = layouts.find((layout) => layout.id === layoutId)
+        const mergedSlots = resolvePageShellSlots({
+          layoutSlots: layoutDef?.slots,
+          appSlots: configValue?.slots,
+          pageSlots: meta?.rawMeta?.slots,
+        })
+        if (Object.keys(mergedSlots).length > 0) {
+          entry.slots = mergedSlots
+        }
+        for (const [slotKey, spec] of Object.entries(mergedSlots)) {
+          if (spec?.view === null) continue
+          const componentId = typeof spec?.view === 'string' ? spec.view.trim() : ''
+          if (!componentId) continue
+          if (!componentIdSet.has(componentId)) {
+            this.error(
+              `[@ossy/app][build] page "${entry.id}" slot "${slotKey}" references unknown component id "${componentId}"`,
+            )
+          }
+        }
+      }
+
       const manifest = {
         entries,
         components,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/app",
-  "version": "1.40.3",
+  "version": "3.0.2",
   "description": "",
   "source": "./src/index.js",
   "main": "./src/index.js",
@@ -16,7 +16,12 @@
     "./manifest/build-actions-schema": "./src/manifest/build-actions-schema.js",
     "./manifest/build-capabilities": "./src/manifest/build-capabilities.js",
     "./manifest/discover-package-definitions": "./src/manifest/discover-package-definitions.js",
-    "./manifest/serialize-package-definition": "./src/manifest/serialize-package-definition.js"
+    "./manifest/serialize-package-definition": "./src/manifest/serialize-package-definition.js",
+    "./manifest/resolve-page-layout": "./src/manifest/resolve-page-layout.js",
+    "./runtime/merge-shell-slots": "./runtime/merge-shell-slots.js"
+  },
+  "ossy": {
+    "src": "./src/shell-registry"
   },
   "bin": {
     "app": "./cli/index.js"
@@ -44,17 +49,21 @@
     "@babel/eslint-parser": "^7.15.8",
     "@babel/preset-react": "^7.26.3",
     "@babel/register": "^7.25.9",
-    "@ossy/design-system": "^1.40.3",
-    "@ossy/locale": "^1.40.3",
-    "@ossy/pages": "^1.23.0",
-    "@ossy/platform": "^1.39.3",
-    "@ossy/router": "^1.40.3",
-    "@ossy/router-react": "^1.40.3",
-    "@ossy/schema": "^1.0.1",
-    "@ossy/sdk": "^1.40.3",
-    "@ossy/sdk-react": "^1.40.3",
-    "@ossy/themes": "^1.40.3",
-    "@ossy/workspaces": "^1.17.3",
+    "@ossy/authentication": "^3.0.2",
+    "@ossy/design-system": "^3.0.2",
+    "@ossy/locale": "^3.0.2",
+    "@ossy/manifest": "^3.0.2",
+    "@ossy/package-catalog": "^3.0.2",
+    "@ossy/pages": "^3.0.2",
+    "@ossy/platform": "^3.0.2",
+    "@ossy/resources": "^3.0.2",
+    "@ossy/router": "^3.0.2",
+    "@ossy/router-react": "^3.0.2",
+    "@ossy/schema": "^3.0.2",
+    "@ossy/sdk": "^3.0.2",
+    "@ossy/sdk-react": "^3.0.2",
+    "@ossy/themes": "^3.0.2",
+    "@ossy/workspaces": "^3.0.2",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-babel": "^7.0.0",
     "@rollup/plugin-commonjs": "^29.0.0",
@@ -88,5 +97,5 @@
     "README.md",
     "tsconfig.json"
   ],
-  "gitHead": "a0d89185a17f8de8ce328c3a648c108ff1d61d8f"
+  "gitHead": "f0a8af3c370bbaffe4f7388c14f9345a5c6c56e5"
 }

package/runtime/merge-shell-slots.js

@@ -0,0 +1,148 @@
+import { CONTENT_SLOT_NAME, normalizeAppSlotName } from './resolve-app-slots.js'
+
+/**
+ * @typedef {{ view?: string | null, props: Record<string, unknown> }} ShellSlotSpec
+ */
+
+/**
+ * Coerce a manifest/runtime slot value to {@link ShellSlotSpec}.
+ *
+ * @param {string | null | ShellSlotSpec | undefined} value
+ * @returns {ShellSlotSpec | undefined}
+ */
+export function coerceShellSlotSpec (value) {
+  if (value === null) return { view: null, props: {} }
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    return trimmed ? { view: trimmed, props: {} } : undefined
+  }
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    const { view, props: nestedProps, ...rest } = value
+    const propBag = {
+      ...(nestedProps && typeof nestedProps === 'object' && !Array.isArray(nestedProps) ? nestedProps : {}),
+      ...rest,
+    }
+    /** @type {ShellSlotSpec} */
+    const spec = { props: propBag }
+    if (view === null) spec.view = null
+    else if (typeof view === 'string') {
+      const trimmed = view.trim()
+      if (trimmed) spec.view = trimmed
+    }
+    return spec
+  }
+  return undefined
+}
+
+/**
+ * Apply one layer onto the accumulated slot spec (layout → app → page).
+ *
+ * - `null` / `{ view: null }` → unset
+ * - string → set view, keep inherited props
+ * - `{ …props }` → shallow-merge props, keep inherited view
+ * - `{ view, …props }` → set view + merge props
+ * - `{}` → no-op
+ *
+ * @param {ShellSlotSpec | undefined} current
+ * @param {string | null | Record<string, unknown> | undefined} value
+ * @returns {ShellSlotSpec | undefined}
+ */
+export function applyShellSlotLayer (current, value) {
+  if (value === null) {
+    return { view: null, props: {} }
+  }
+
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (!trimmed) return current
+    return {
+      view: trimmed,
+      props: current?.props ? { ...current.props } : {},
+    }
+  }
+
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    if (Object.keys(value).length === 0) {
+      return current
+    }
+
+    const { view, props: nestedProps, ...rest } = value
+    if (view === null) {
+      return { view: null, props: {} }
+    }
+
+    const restProps = {
+      ...(nestedProps && typeof nestedProps === 'object' && !Array.isArray(nestedProps) ? nestedProps : {}),
+      ...rest,
+    }
+    const nextProps = Object.keys(restProps).length > 0
+      ? { ...(current?.props ?? {}), ...restProps }
+      : { ...(current?.props ?? {}) }
+
+    /** @type {ShellSlotSpec} */
+    const next = { props: nextProps }
+    if (view !== undefined) {
+      if (typeof view === 'string') {
+        const trimmed = view.trim()
+        if (trimmed) next.view = trimmed
+      }
+    } else if (current?.view !== undefined) {
+      next.view = current.view
+    }
+
+    return next
+  }
+
+  return current
+}
+
+/**
+ * @param {ShellSlotSpec | string | null | undefined} spec
+ * @returns {boolean}
+ */
+export function shellSlotUnset (spec) {
+  const normalized = typeof spec === 'string' || spec === null ? coerceShellSlotSpec(spec) : spec
+  return normalized?.view === null
+}
+
+/**
+ * @param {ShellSlotSpec | string | null | undefined} spec
+ * @returns {string | undefined}
+ */
+export function shellSlotViewId (spec) {
+  const normalized = typeof spec === 'string' || spec === null ? coerceShellSlotSpec(spec) : spec
+  if (!normalized || normalized.view === null) return undefined
+  return typeof normalized.view === 'string' ? normalized.view : undefined
+}
+
+/**
+ * Merge shell slot maps per ADR 0012: layout defaults → app config → page metadata.
+ * Page layer wins for both view (when set) and props.
+ *
+ * @param {Record<string, string | null | Record<string, unknown>> | null | undefined} layoutSlots
+ * @param {Record<string, string | null | Record<string, unknown>> | null | undefined} appSlots
+ * @param {Record<string, string | null | Record<string, unknown>> | null | undefined} pageSlots
+ * @returns {Record<string, ShellSlotSpec>}
+ */
+export function mergeShellSlots (layoutSlots, appSlots, pageSlots) {
+  /** @type {Record<string, ShellSlotSpec>} */
+  const merged = {}
+
+  const apply = (map) => {
+    if (!map || typeof map !== 'object' || Array.isArray(map)) return
+    Object.entries(map).forEach(([rawKey, value]) => {
+      const key = normalizeAppSlotName(rawKey)
+      if (!key || key === CONTENT_SLOT_NAME) return
+      const next = applyShellSlotLayer(merged[key], value)
+      if (next !== undefined) {
+        merged[key] = next
+      }
+    })
+  }
+
+  apply(layoutSlots)
+  apply(appSlots)
+  apply(pageSlots)
+
+  return merged
+}