@ossy/app 1.39.6 → 1.40.0

package/cli/merge-translations.task.js

@@ -0,0 +1,170 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { mergeTranslationFiles, pageIdToDocumentTitleKey } from '@ossy/locale'
+import {
+  discoverTranslationFiles,
+  validateTranslationLocales,
+} from './discover-translation-files.js'
+
+/**
+ * @param {Array<{ type: string, id: string, path?: string | Record<string, string> }>} entries
+ * @param {string[]} supportedLanguages
+ * @param {string | undefined} defaultLanguage
+ * @param {(message: string) => void} error
+ * @param {(message: string) => void} warn
+ */
+export function validateLanguageConfig ({ entries, supportedLanguages, defaultLanguage, error, warn }) {
+  if (!Array.isArray(supportedLanguages) || supportedLanguages.length === 0) return
+
+  if (defaultLanguage && !supportedLanguages.includes(defaultLanguage)) {
+    error(
+      `[@ossy/app][build] config.defaultLanguage "${defaultLanguage}" is not in supportedLanguages`,
+    )
+  }
+
+  for (const entry of entries.filter((e) => e.type === 'page')) {
+    if (typeof entry.path !== 'object' || !entry.path) continue
+
+    for (const lang of Object.keys(entry.path)) {
+      if (!supportedLanguages.includes(lang)) {
+        error(
+          `[@ossy/app][build] Page "${entry.id}" metadata.path key "${lang}" is not in supportedLanguages`,
+        )
+      }
+    }
+
+    for (const lang of supportedLanguages) {
+      if (!(lang in entry.path)) {
+        warn(
+          `[@ossy/app][build] Page "${entry.id}" metadata.path is missing key for supported language "${lang}"`,
+        )
+      }
+    }
+  }
+}
+
+/**
+ * @param {Array<{ type: string, id: string, title?: string }>} entries
+ * @param {Record<string, Record<string, string>>} catalogs
+ * @param {string | undefined} defaultLanguage
+ * @param {(message: string) => void} warn
+ */
+export function validatePageDocumentTitles ({ entries, catalogs, defaultLanguage, warn }) {
+  if (!defaultLanguage) return
+  const catalog = catalogs[defaultLanguage] || {}
+
+  for (const entry of entries.filter((e) => e.type === 'page')) {
+    if (entry.title) continue
+    const key = pageIdToDocumentTitleKey(entry.id)
+    if (!catalog[key]) {
+      warn(
+        `[@ossy/app][build] Page "${entry.id}" document title key "${key}" missing in default language "${defaultLanguage}" catalog`,
+      )
+    }
+  }
+}
+
+/**
+ * @param {{ actions?: Array<{ id: string }> }} manifest
+ * @param {Record<string, Record<string, string>>} catalogs
+ * @param {string | undefined} defaultLanguage
+ * @param {(message: string) => void} warn
+ */
+export function validateActionTranslationKeys ({ manifest, catalogs, defaultLanguage, warn }) {
+  if (!defaultLanguage) return
+  const catalog = catalogs[defaultLanguage] || {}
+  const actions = Array.isArray(manifest?.actions) ? manifest.actions : []
+
+  for (const action of actions) {
+    const actionId = action.id
+    if (!actionId) continue
+    if (!catalog[`${actionId}.label`]) {
+      warn(
+        `[@ossy/app][build] Action "${actionId}" missing "${actionId}.label" in default language catalog`,
+      )
+    }
+    if (!catalog[`${actionId}.description`]) {
+      warn(
+        `[@ossy/app][build] Action "${actionId}" missing "${actionId}.description" in default language catalog`,
+      )
+    }
+  }
+}
+
+/**
+ * Discover, merge, validate, and emit per-locale translation catalogs.
+ *
+ * @param {{
+ *   srcDir: string
+ *   projectRoot: string
+ *   publicOutDir: string
+ *   manifestPath: string
+ *   configValue: object
+ *   log?: (message: string) => void
+ *   warn?: (message: string) => void
+ * }} options
+ */
+export function mergeAndEmitTranslations ({
+  srcDir,
+  projectRoot,
+  publicOutDir,
+  manifestPath,
+  configValue,
+  log = () => {},
+  warn = (message) => log(message),
+}) {
+  const supportedLanguages = Array.isArray(configValue?.supportedLanguages)
+    ? configValue.supportedLanguages
+    : []
+  const defaultLanguage = typeof configValue?.defaultLanguage === 'string'
+    ? configValue.defaultLanguage
+    : undefined
+
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+  const entries = Array.isArray(manifest.entries) ? manifest.entries : []
+
+  /** @type {string[]} */
+  const errors = []
+  validateLanguageConfig({
+    entries,
+    supportedLanguages,
+    defaultLanguage,
+    error: (message) => errors.push(message),
+    warn,
+  })
+
+  const discovered = discoverTranslationFiles({ srcDir, projectRoot })
+  validateTranslationLocales(discovered)
+
+  const catalogs = mergeTranslationFiles(discovered, supportedLanguages, {
+    readFileSync: (filePath, encoding) => fs.readFileSync(filePath, encoding),
+  })
+
+  for (const lang of supportedLanguages) {
+    const keys = Object.keys(catalogs[lang] || {})
+    if (keys.length === 0) {
+      warn(
+        `[@ossy/app][build] No translation keys merged for supported language "${lang}"`,
+      )
+    }
+  }
+
+  validatePageDocumentTitles({ entries, catalogs, defaultLanguage, warn })
+  validateActionTranslationKeys({ manifest, catalogs, defaultLanguage, warn })
+
+  /** @type {Record<string, string>} */
+  const files = {}
+  for (const lang of supportedLanguages) {
+    const outPath = path.join(publicOutDir, `${lang}.translations.json`)
+    fs.writeFileSync(outPath, JSON.stringify(catalogs[lang] || {}, null, 2) + '\n', 'utf8')
+    files[lang] = `/${lang}.translations.json`
+  }
+
+  if (errors.length > 0) {
+    throw new Error(errors.join('\n'))
+  }
+
+  manifest.translations = { files }
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf8')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/app",
-  "version": "1.39.6",
+  "version": "1.40.0",
   "description": "",
   "source": "./src/index.js",
   "main": "./src/index.js",
@@ -9,8 +9,12 @@
     ".": "./src/index.js",
     "./shell": "./src/shell/index.js",
     "./runtime/page-runtime": "./runtime/page-runtime.js",
+    "./runtime/resolve-shell-slots": "./runtime/resolve-shell-slots.js",
     "./runtime/api-runtime": "./runtime/api-runtime.js",
-    "./runtime/task-runtime": "./runtime/task-runtime.js"
+    "./runtime/task-runtime": "./runtime/task-runtime.js",
+    "./manifest/build-manifest-summary": "./src/manifest/build-manifest-summary.js",
+    "./manifest/discover-package-definitions": "./src/manifest/discover-package-definitions.js",
+    "./manifest/serialize-package-definition": "./src/manifest/serialize-package-definition.js"
   },
   "bin": {
     "app": "./cli/index.js"
@@ -38,14 +42,15 @@
     "@babel/eslint-parser": "^7.15.8",
     "@babel/preset-react": "^7.26.3",
     "@babel/register": "^7.25.9",
-    "@ossy/design-system": "^1.39.6",
+    "@ossy/design-system": "^1.40.0",
+    "@ossy/locale": "^1.40.0",
     "@ossy/pages": "^1.23.0",
-    "@ossy/platform": "^1.38.6",
-    "@ossy/router": "^1.39.6",
-    "@ossy/router-react": "^1.39.6",
-    "@ossy/sdk": "^1.39.6",
-    "@ossy/sdk-react": "^1.39.6",
-    "@ossy/themes": "^1.39.6",
+    "@ossy/platform": "^1.39.0",
+    "@ossy/router": "^1.40.0",
+    "@ossy/router-react": "^1.40.0",
+    "@ossy/sdk": "^1.40.0",
+    "@ossy/sdk-react": "^1.40.0",
+    "@ossy/themes": "^1.40.0",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-babel": "^7.0.0",
     "@rollup/plugin-commonjs": "^29.0.0",
@@ -79,5 +84,5 @@
     "README.md",
     "tsconfig.json"
   ],
-  "gitHead": "72d150cf20ff7ba25b328bc5b429b065c2840b2b"
+  "gitHead": "d9d31182be64a448d575da432af2830d909ad4b9"
 }

package/runtime/page-runtime.js

@@ -1,5 +1,7 @@
 import { createElement } from 'react'
+import { pageIdToDocumentTitleKey, resolveMessage } from '@ossy/locale'
 import { App } from '../src/shell/App.jsx'
+import { resolvePageSlots } from './resolve-shell-slots.js'
 
 /**
  * Dynamically imports each component bundle listed in `entries` and returns a
@@ -40,13 +42,42 @@ export async function loadLayout (layoutEntry) {
   try {
     const mod = await import(layoutEntry)
     return mod?.default ?? null
-  } catch {
+  } catch (err) {
+    if (typeof console !== 'undefined' && typeof console.error === 'function') {
+      console.error('[@ossy/app][page-runtime] Failed to load layout bundle:', layoutEntry, err)
+    }
     return null
   }
 }
 
+function resolveDocumentTitle (metadata, props) {
+  if (metadata.id && props.messages) {
+    const key = pageIdToDocumentTitleKey(metadata.id)
+    const hasTranslation =
+      props.messages[key] != null || props.fallbackMessages?.[key] != null
+    if (hasTranslation) {
+      return resolveMessage(props.messages, key, {
+        fallbackCatalog: props.fallbackMessages,
+        onMissingKey: (missingKey) => {
+          if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+            console.warn(
+              `[@ossy/app][page-runtime] Missing document title key "${missingKey}" for page "${metadata.id}"`,
+            )
+          }
+        },
+      })
+    }
+    if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+      console.warn(
+        `[@ossy/app][page-runtime] Missing document title key "${key}" for page "${metadata.id}"; falling back to metadata.title`,
+      )
+    }
+  }
+  return metadata.title || props.documentTitle || ''
+}
+
 function buildTree ({ Component, Layout, metadata, props }) {
-  const lang = props.htmlLang || props.defaultLanguage || 'en'
+  const lang = props.language || props.defaultLanguage || 'en'
   const pageEl = createElement(Component, props)
   const contentEl = Layout ? createElement(Layout, props, pageEl) : pageEl
   return createElement(
@@ -56,9 +87,9 @@ function buildTree ({ Component, Layout, metadata, props }) {
       'head',
       null,
       createElement('meta', { charSet: 'utf-8' }),
-      createElement('title', null, metadata.title || props.documentTitle || ''),
+      createElement('title', null, resolveDocumentTitle(metadata, props)),
     ),
-    createElement(App, props, contentEl),
+    createElement('body', null, createElement(App, props, contentEl)),
   )
 }
 
@@ -96,8 +127,13 @@ export function createPageEntry (pageModule, options = {}) {
       import('node:stream'),
     ])
 
-    const { Layout = null, componentEntries = [], ...pageProps } = props
-    const components = await loadComponents(componentEntries)
+    const { Layout = null, componentEntries = [], layoutSlots = {}, ...pageProps } = props
+    const componentsById = await loadComponents(componentEntries)
+    const components = resolvePageSlots({
+      layoutSlots,
+      componentsById,
+      pageComponent: Component,
+    })
     const tree = buildTree({ Component, Layout, metadata, props: { ...pageProps, components } })
     const bootstrapUrl = toBootstrapUrl(entryUrl)
     const bootstrapModules = bootstrapUrl ? [bootstrapUrl] : []
@@ -133,13 +169,22 @@ export function createPageEntry (pageModule, options = {}) {
     if (typeof document === 'undefined' || typeof window === 'undefined') return
     hydrated = true
     const props = window.__OSSY__ || {}
-    const { layoutEntry = null, componentEntries = [], ...pageProps } = props
+    const { layoutEntry = null, componentEntries = [], layoutSlots = {}, ...pageProps } = props
     Promise.all([
       import('react-dom/client'),
       loadComponents(componentEntries),
       loadLayout(layoutEntry),
-    ]).then(([{ hydrateRoot }, components, Layout]) => {
+    ]).then(([{ hydrateRoot }, componentsById, Layout]) => {
+      const components = resolvePageSlots({
+        layoutSlots,
+        componentsById,
+        pageComponent: Component,
+      })
       hydrateRoot(document, buildTree({ Component, Layout, metadata, props: { ...pageProps, components } }))
+    }).catch((err) => {
+      if (typeof console !== 'undefined' && typeof console.error === 'function') {
+        console.error('[@ossy/app][page-runtime] Hydration failed:', err)
+      }
     })
   }
 

package/runtime/resolve-shell-slots.js

@@ -0,0 +1,112 @@
+/** Canonical shell slot names (namespaced). App layout maps chrome only — not content. */
+export const SHELL_SLOT_NAMES = [
+  'shell:header',
+  'shell:sidebar',
+  'shell:toolbar',
+  'shell:notifications',
+  'shell:system-messages',
+]
+
+/** Platform-owned slot filled with the current route page component. */
+export const CONTENT_SLOT_NAME = 'shell:content'
+
+/** Bare shell region → namespaced key (legacy fallback for app components only). */
+const BARE_SHELL_REGION = {
+  header: 'shell:header',
+  sidebar: 'shell:sidebar',
+  toolbar: 'shell:toolbar',
+  notifications: 'shell:notifications',
+  'system-messages': 'shell:system-messages',
+  content: CONTENT_SLOT_NAME,
+}
+
+/**
+ * Normalize a slot map key to the canonical namespaced form when it is a bare shell region.
+ *
+ * @param {string} slotName
+ * @returns {string}
+ */
+export function normalizeShellSlotName (slotName) {
+  const key = typeof slotName === 'string' ? slotName.trim() : ''
+  return BARE_SHELL_REGION[key] ?? key
+}
+
+/**
+ * Build `Record<slotName, Component>` from the app layout's static `slots` map
+ * (`slotName → componentId`) and components loaded by `metadata.id`.
+ *
+ * One component per slot. Optional fallback (app components only): if the layout
+ * map omits a slot, use a component whose id equals the slot name (e.g. `shell:header`)
+ * or the bare region name (e.g. `header`).
+ *
+ * Does not resolve `shell:content` — use {@link resolvePageSlots}.
+ *
+ * @param {Record<string, string> | null | undefined} layoutSlotsMap
+ * @param {Record<string, import('react').ComponentType>} componentsById
+ * @returns {Record<string, import('react').ComponentType>}
+ */
+export function resolveShellSlots (layoutSlotsMap, componentsById) {
+  /** @type {Record<string, import('react').ComponentType>} */
+  const resolved = {}
+
+  const map = layoutSlotsMap && typeof layoutSlotsMap === 'object' ? layoutSlotsMap : {}
+  for (const [rawSlot, componentId] of Object.entries(map)) {
+    const slotName = normalizeShellSlotName(rawSlot)
+    const id = typeof componentId === 'string' ? componentId.trim() : ''
+    if (!slotName || !id || slotName === CONTENT_SLOT_NAME) continue
+    const Component = componentsById[id]
+    if (Component) resolved[slotName] = Component
+  }
+
+  for (const slotName of SHELL_SLOT_NAMES) {
+    if (resolved[slotName]) continue
+    if (componentsById[slotName]) {
+      resolved[slotName] = componentsById[slotName]
+      continue
+    }
+    const bare = slotName.slice('shell:'.length)
+    if (componentsById[bare]) resolved[slotName] = componentsById[bare]
+  }
+
+  return resolved
+}
+
+const RESOURCE_SLOT_PREFIX = 'resource:'
+
+/**
+ * Map manifest components whose `metadata.id` is a `resource:{type}/{view}` key.
+ *
+ * @param {Record<string, import('react').ComponentType>} componentsById
+ * @returns {Record<string, import('react').ComponentType>}
+ */
+export function resolveResourceSlots (componentsById) {
+  /** @type {Record<string, import('react').ComponentType>} */
+  const resolved = {}
+  for (const [id, Component] of Object.entries(componentsById || {})) {
+    if (typeof id === 'string' && id.startsWith(RESOURCE_SLOT_PREFIX) && Component) {
+      resolved[id] = Component
+    }
+  }
+  return resolved
+}
+
+/**
+ * Full provider slot map for a page request: shell chrome, resource views, and page content.
+ *
+ * @param {{
+ *   layoutSlots?: Record<string, string> | null,
+ *   componentsById?: Record<string, import('react').ComponentType>,
+ *   pageComponent?: import('react').ComponentType | null,
+ * }} options
+ * @returns {Record<string, import('react').ComponentType>}
+ */
+export function resolvePageSlots ({ layoutSlots, componentsById = {}, pageComponent = null } = {}) {
+  const shellSlots = resolveShellSlots(layoutSlots, componentsById)
+  const resourceSlots = resolveResourceSlots(componentsById)
+  /** @type {Record<string, import('react').ComponentType>} */
+  const resolved = { ...componentsById, ...shellSlots, ...resourceSlots }
+  if (pageComponent) {
+    resolved[CONTENT_SLOT_NAME] = pageComponent
+  }
+  return resolved
+}

package/src/manifest/build-manifest-summary.js

@@ -0,0 +1,115 @@
+/**
+ * @param {string} packageName npm package name (e.g. `@ossy/booking`).
+ * @returns {string} URL slug (e.g. `booking`).
+ */
+export function packageNameToSlug (packageName) {
+  const slash = packageName.indexOf('/')
+  return slash === -1 ? packageName : packageName.slice(slash + 1)
+}
+
+/**
+ * @param {string} slug URL slug (e.g. `booking`).
+ * @returns {string} Scoped package name (e.g. `@ossy/booking`).
+ */
+export function slugToPackageName (slug) {
+  return `@ossy/${slug}`
+}
+
+/**
+ * @param {object} manifest Loaded manifest from `@ossy/platform` `loadManifest`.
+ * @returns {{ packages: Array<object> }} Grouped, JSON-serializable package summary.
+ */
+export function buildManifestSummary (manifest) {
+  /** @type {Map<string, object>} */
+  const groups = new Map()
+
+  const ensure = (pkg) => {
+    if (!groups.has(pkg)) {
+      groups.set(pkg, {
+        package: pkg,
+        slug: packageNameToSlug(pkg),
+        pages: [],
+        apis: [],
+        actions: [],
+        components: [],
+        resourceTemplates: [],
+        tasks: [],
+        integrations: [],
+        emails: [],
+        aggregates: [],
+      })
+    }
+    return groups.get(pkg)
+  }
+
+  const add = (pkg, key, item) => {
+    ensure(pkg || '@ossy/app')[key].push(item)
+  }
+
+  for (const page of manifest.pages || []) {
+    add(page.package, 'pages', {
+      id: page.id,
+      path: page.path,
+      ...(page.title ? { title: page.title } : {}),
+    })
+  }
+
+  for (const api of manifest.apis || []) {
+    add(api.package, 'apis', { id: api.id, path: api.path })
+  }
+
+  for (const action of manifest.actions || []) {
+    add(action.package, 'actions', {
+      id: action.id,
+      ...(action.access ? { access: action.access } : {}),
+    })
+  }
+
+  for (const component of manifest.components || []) {
+    add(component.package, 'components', { id: component.id })
+  }
+
+  for (const template of manifest.resourceTemplates || []) {
+    add(template.package, 'resourceTemplates', {
+      id: template.id,
+      ...(template.title ? { title: template.title } : {}),
+    })
+  }
+
+  for (const task of manifest.tasks || []) {
+    add(task.package, 'tasks', { id: task.id })
+  }
+
+  for (const integration of manifest.integrations || []) {
+    add(integration.package, 'integrations', {
+      id: integration.id,
+      ...(integration.credentials?.length ? { credentials: integration.credentials } : {}),
+    })
+  }
+
+  for (const email of manifest.emails || []) {
+    add(email.package, 'emails', { id: email.id })
+  }
+
+  for (const aggregate of manifest.aggregates || []) {
+    add(aggregate.package, 'aggregates', { id: aggregate.id })
+  }
+
+  const packages = Array.from(groups.values())
+    .sort((a, b) => a.package.localeCompare(b.package))
+
+  for (const pkg of packages) {
+    for (const key of Object.keys(pkg)) {
+      if (Array.isArray(pkg[key])) {
+        pkg[key].sort((a, b) => a.id.localeCompare(b.id))
+      }
+    }
+  }
+
+  const definitions =
+    manifest.definitions && typeof manifest.definitions === 'object' && !Array.isArray(manifest.definitions)
+      ? manifest.definitions
+      : {}
+
+  return { packages, definitions }
+}

package/src/manifest/discover-package-definitions.js

@@ -0,0 +1,100 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { packageNameToSlug } from './build-manifest-summary.js'
+import { serializePackageDefinition } from './serialize-package-definition.js'
+
+/**
+ * @param {string} projectRoot
+ * @returns {string[]}
+ */
+function collectNodeModulesDirs (projectRoot) {
+  const dirs = []
+  let current = projectRoot
+  while (true) {
+    const nm = path.join(current, 'node_modules')
+    if (fs.existsSync(nm) && fs.statSync(nm).isDirectory()) dirs.push(nm)
+    const parent = path.dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return dirs
+}
+
+/**
+ * Load `Definition.js` from disk only — never import the package main entry,
+ * which may pull CLI side effects (e.g. `@ossy/cli` runs on import).
+ *
+ * @param {string} pkgDir
+ * @param {object} pkg
+ * @returns {Promise<object | null>}
+ */
+async function loadPackageDefinition (pkgDir, pkg) {
+  if (!pkg.ossy?.src) return null
+
+  const defPath = path.join(pkgDir, pkg.ossy.src, 'Definition.js')
+  if (!fs.existsSync(defPath)) return null
+
+  try {
+    const mod = await import(pathToFileURL(defPath).href + `?t=${Date.now()}`)
+    if (mod?.Definition && typeof mod.Definition === 'object') {
+      return mod.Definition
+    }
+  } catch {
+    // skip packages without a readable Definition
+  }
+
+  return null
+}
+
+/**
+ * Discover `Definition.js` from installed `@ossy/*` packages.
+ *
+ * @param {string} projectRoot Absolute path to the consuming app root.
+ * @returns {Promise<Record<string, object>>} Map keyed by package slug.
+ */
+export async function discoverPackageDefinitions (projectRoot) {
+  const nmDirs = collectNodeModulesDirs(projectRoot)
+  /** @type {Record<string, object>} */
+  const definitions = {}
+  const seen = new Set()
+
+  const tryPackageDir = async (pkgDir) => {
+    const real = fs.realpathSync(pkgDir)
+    if (seen.has(real)) return
+    seen.add(real)
+
+    const pkgJsonPath = path.join(pkgDir, 'package.json')
+    if (!fs.existsSync(pkgJsonPath)) return
+
+    let pkg
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'))
+    } catch {
+      return
+    }
+
+    const name = typeof pkg.name === 'string' ? pkg.name.trim() : ''
+    if (!name.startsWith('@ossy/')) return
+
+    const slug = packageNameToSlug(name)
+    if (!slug || definitions[slug]) return
+
+    const raw = await loadPackageDefinition(real, pkg)
+    const serialized = serializePackageDefinition(raw)
+    if (serialized) definitions[slug] = serialized
+  }
+
+  for (const nmDir of nmDirs) {
+    const scopeDir = path.join(nmDir, '@ossy')
+    if (!fs.existsSync(scopeDir) || !fs.statSync(scopeDir).isDirectory()) continue
+
+    for (const entry of fs.readdirSync(scopeDir, { withFileTypes: true })) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+      await tryPackageDir(path.join(scopeDir, entry.name))
+    }
+  }
+
+  return definitions
+}

package/src/manifest/serialize-package-definition.js

@@ -0,0 +1,30 @@
+/**
+ * Pick JSON-serializable Definition fields for manifest / SSR bootstrap.
+ * Definition holds module presentation metadata only — capabilities live in manifestSummary.
+ *
+ * @param {object | null | undefined} definition
+ * @returns {object | null}
+ */
+export function serializePackageDefinition (definition) {
+  if (!definition || typeof definition !== 'object' || Array.isArray(definition)) return null
+
+  /** @type {Record<string, unknown>} */
+  const out = {}
+
+  if (typeof definition.id === 'string' && definition.id.trim()) out.id = definition.id.trim()
+  if (typeof definition.title === 'string' && definition.title.trim()) out.title = definition.title.trim()
+  if (typeof definition.description === 'string' && definition.description.trim()) {
+    out.description = definition.description.trim()
+  }
+  if (typeof definition.icon === 'string' && definition.icon.trim()) out.icon = definition.icon.trim()
+  if (typeof definition.navOrder === 'number' && Number.isFinite(definition.navOrder)) {
+    out.navOrder = definition.navOrder
+  }
+  if (definition.entitlementRequired === false) out.entitlementRequired = false
+  if (typeof definition.status === 'string' && definition.status.trim()) out.status = definition.status.trim()
+  if (Array.isArray(definition.statuses) && definition.statuses.length) {
+    out.statuses = definition.statuses.filter((s) => typeof s === 'string' && s.trim()).map((s) => s.trim())
+  }
+
+  return Object.keys(out).length ? out : null
+}