@ossy/app 1.40.3 → 3.0.1

package/runtime/resolve-app-slots.js

@@ -1,10 +1,15 @@
+import { createElement } from 'react'
+import { coerceShellSlotSpec, shellSlotViewId } from './merge-shell-slots.js'
+
 /** Canonical app chrome slot names (namespaced). App layout maps chrome only — not content. */
 export const APP_SLOT_NAMES = [
+  'app:head',
   'app:header',
   'app:sidebar',
   'app:toolbar',
   'app:notifications',
   'app:system-messages',
+  'app:footer',
 ]
 
 /** Platform-owned slot filled with the current route page component. */
@@ -14,14 +19,29 @@ const APP_SLOT_PREFIX = 'app'
 
 /** Bare app region → namespaced key (legacy fallback for app components only). */
 const BARE_APP_REGION = {
+  head: 'app:head',
   header: 'app:header',
   sidebar: 'app:sidebar',
   toolbar: 'app:toolbar',
   notifications: 'app:notifications',
   'system-messages': 'app:system-messages',
+  footer: 'app:footer',
   content: CONTENT_SLOT_NAME,
 }
 
+/**
+ * @param {import('react').ComponentType<any>} Component
+ * @param {Record<string, unknown>} defaultProps
+ * @returns {import('react').ComponentType<any>}
+ */
+function withShellSlotProps (Component, defaultProps) {
+  function ShellSlotTarget (props) {
+    return createElement(Component, { ...defaultProps, ...props })
+  }
+  ShellSlotTarget.displayName = `ShellSlot(${Component.displayName || Component.name || 'Component'})`
+  return ShellSlotTarget
+}
+
 /**
  * Normalize a slot map key to the canonical namespaced form when it is a bare app region.
  *
@@ -34,10 +54,10 @@ export function normalizeAppSlotName (slotName) {
 }
 
 /**
- * Build `Record<slotName, Component>` from the app layout's static `slots` map
- * (`slotName → componentId`) and components loaded by `metadata.id`.
+ * Build `Record<slotName, Component>` from merged shell slot specs
+ * (`slotName → component id + default props`) and components loaded by `metadata.id`.
  *
- * @param {Record<string, string> | null | undefined} layoutSlotsMap
+ * @param {Record<string, string | null | import('./merge-shell-slots.js').ShellSlotSpec | undefined> | null | undefined} layoutSlotsMap
  * @param {Record<string, import('react').ComponentType>} componentsById
  * @returns {Record<string, import('react').ComponentType>}
  */
@@ -46,16 +66,33 @@ export function resolveAppSlots (layoutSlotsMap, componentsById) {
   const resolved = {}
 
   const map = layoutSlotsMap && typeof layoutSlotsMap === 'object' ? layoutSlotsMap : {}
-  for (const [rawSlot, componentId] of Object.entries(map)) {
+  for (const [rawSlot, rawSpec] of Object.entries(map)) {
     const slotName = normalizeAppSlotName(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
+    if (!slotName || slotName === CONTENT_SLOT_NAME) continue
+
+    const spec = coerceShellSlotSpec(rawSpec) ?? (
+      rawSpec && typeof rawSpec === 'object' && !Array.isArray(rawSpec) ? rawSpec : undefined
+    )
+
+    if (spec?.view === null) {
+      resolved[slotName] = null
+      continue
+    }
+
+    const componentId = shellSlotViewId(spec ?? rawSpec)
+    if (!componentId) continue
+
+    const Component = componentsById[componentId]
+    if (!Component) continue
+
+    const defaultProps = spec?.props ?? {}
+    resolved[slotName] = Object.keys(defaultProps).length > 0
+      ? withShellSlotProps(Component, defaultProps)
+      : Component
   }
 
   for (const slotName of APP_SLOT_NAMES) {
-    if (resolved[slotName]) continue
+    if (slotName in resolved) continue
     if (componentsById[slotName]) {
       resolved[slotName] = componentsById[slotName]
       continue
@@ -69,10 +106,10 @@ export function resolveAppSlots (layoutSlotsMap, componentsById) {
 
 /**
  * Full provider slot map for a page request: app chrome and page content.
- * Feature components register at canonical ADR 0006 ids (`@ossy/…/view|form/…`).
+ * Feature components register at canonical ADR 0006 ids (`@ossy/…/view|form|…`).
  *
  * @param {{
- *   layoutSlots?: Record<string, string> | null,
+ *   layoutSlots?: Record<string, string | null | import('./merge-shell-slots.js').ShellSlotSpec> | null,
  *   componentsById?: Record<string, import('react').ComponentType>,
  *   pageComponent?: import('react').ComponentType | null,
  * }} options

package/src/en.translations.json

@@ -0,0 +1,8 @@
+{
+  "app.shell.sidebar.expand": "Expand sidebar",
+  "app.shell.sidebar.collapse": "Collapse sidebar",
+  "app.shell.header.languagePicker": "Language",
+  "app.shell.footer.languages": "Languages",
+  "app.shell.header.themeSwitch": "{theme} theme. Switch theme.",
+  "app.shell.header.profile": "Profile"
+}

package/src/manifest/resolve-page-layout.js

@@ -0,0 +1,51 @@
+import { mergeShellSlots } from '../../runtime/merge-shell-slots.js'
+
+const LAYOUT_ID_PATTERN = /^@([^/]+)\/([^/]+)\/layout\/([^/]+)$/
+
+/**
+ * @param {string} layoutId
+ * @returns {boolean}
+ */
+export function isCanonicalLayoutId (layoutId) {
+  return typeof layoutId === 'string' && LAYOUT_ID_PATTERN.test(layoutId.trim())
+}
+
+/**
+ * Resolve layout id for a page at build time (ADR 0012).
+ *
+ * @param {{
+ *   pageMetadata?: { layout?: string },
+ *   appConfig?: { layout?: string },
+ * }} options
+ * @returns {string}
+ */
+export function resolvePageLayoutId ({
+  pageMetadata = {},
+  appConfig = {},
+} = {}) {
+  const pageLayout = pageMetadata?.layout
+  if (typeof pageLayout === 'string' && pageLayout.trim()) return pageLayout.trim()
+
+  const appLayout = appConfig?.layout
+  if (typeof appLayout === 'string' && appLayout.trim()) return appLayout.trim()
+
+  return '@ossy/app/layout/default'
+}
+
+/**
+ * Merge layout, app, and page slot maps for a single page render.
+ *
+ * @param {{
+ *   layoutSlots?: Record<string, string>,
+ *   appSlots?: Record<string, string | null>,
+ *   pageSlots?: Record<string, string | null>,
+ * }} options
+ * @returns {Record<string, import('../../runtime/merge-shell-slots.js').ShellSlotSpec>}
+ */
+export function resolvePageShellSlots ({
+  layoutSlots,
+  appSlots,
+  pageSlots,
+} = {}) {
+  return mergeShellSlots(layoutSlots, appSlots, pageSlots)
+}

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

@@ -21,9 +21,8 @@ export function serializePackageDefinition (definition) {
     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())
+  if (Array.isArray(definition.status) && definition.status.length) {
+    out.status = definition.status.filter((s) => typeof s === 'string' && s.trim()).map((s) => s.trim())
   }
 
   return Object.keys(out).length ? out : null

package/src/shell/App.jsx

@@ -2,20 +2,22 @@ import React from 'react'
 import { SDK } from '@ossy/sdk'
 import { WorkspaceProvider } from '@ossy/sdk-react'
 import { Theme, ComponentSlotsProvider, LocaleProvider, DEFAULT_FORM_FIELD_SLOTS } from '@ossy/design-system'
+import { DEFAULT_SCHEMA_VIEW_SLOTS } from '@ossy/resources/schemaViewSlots.js'
+import { DEFAULT_SCHEMA_FORM_SLOTS } from '@ossy/resources/schemaFormSlots.js'
 import { SchemasReadBootstrap } from '@ossy/workspaces/SchemasReadBootstrap'
 import { ThemeEditor } from './ThemeEditor.jsx'
+import { WorkspaceAppSettingsSync } from './WorkspaceAppSettingsSync.jsx'
 import { defaultAppSettings } from './AppSettings.jsx'
 import { Router } from '@ossy/router-react'
 import { AppContext } from './AppContext.js'
 
-export const App = ({ children, language, messages, fallbackMessages, ..._appSettings }) => {
+export const App = ({ children, language, messages, fallbackMessages, sdk: sdkOverride, ..._appSettings }) => {
   const appSettings = { ...defaultAppSettings(), ..._appSettings }
 
-  // `components` holds resolved ComponentType values — not JSON-serializable,
-  // so we keep them out of AppContext and provide them via ComponentSlotsProvider.
-  const { components, ...contextSettings } = appSettings
+  // `components` and `sdk` are not JSON-serializable — keep them out of AppContext.
+  const { components, sdk: _sdkFromSettings, ...contextSettings } = appSettings
 
-  const sdk = SDK.of({
+  const sdk = sdkOverride ?? SDK.of({
     apiUrl: appSettings.apiUrl,
     workspaceId: appSettings.workspaceId,
     actionRoutes: appSettings.actionRoutes,
@@ -30,10 +32,14 @@ export const App = ({ children, language, messages, fallbackMessages, ..._appSet
       supportedLanguages={appSettings.supportedLanguages}
     >
       <AppContext.Provider value={contextSettings}>
-        <ComponentSlotsProvider slots={{ ...DEFAULT_FORM_FIELD_SLOTS, ...(components || {}) }}>
+        <ComponentSlotsProvider slots={{ ...DEFAULT_FORM_FIELD_SLOTS, ...DEFAULT_SCHEMA_VIEW_SLOTS, ...DEFAULT_SCHEMA_FORM_SLOTS, ...(components || {}) }}>
           <Theme theme={appSettings.theme} themes={appSettings.themes}>
-            <WorkspaceProvider sdk={sdk}>
+            <WorkspaceProvider
+              sdk={sdk}
+              enablePushInvalidation={appSettings.enablePushInvalidation === true}
+            >
               <SchemasReadBootstrap schemas={appSettings.schemas} />
+              <WorkspaceAppSettingsSync />
               <Router {...appSettings} pages={appSettings.pages || []}>
                 {children}
                 {appSettings.devMode && <ThemeEditor />}

package/src/shell/AppSettings.jsx

@@ -38,5 +38,11 @@ export function defaultAppSettings() {
       taskGraphEdges: undefined,
       /** Action id → HTTP route map for sdk.invoke transport routing. */
       actionRoutes: undefined,
+      /**
+       * When true, the app shell opens SSE push invalidation for every page.
+       * Default false — mount `PushInvalidationSubscriber` only on pages that
+       * need live cross-tab cache updates (see @ossy/sdk-react README).
+       */
+      enablePushInvalidation: false,
     }
   }

package/src/shell/HeaderAuthActions.jsx

@@ -0,0 +1,49 @@
+import React from 'react'
+import { Button, useLocale } from '@ossy/design-system'
+import { useRouter } from '@ossy/router-react'
+import { OpenSignIn, OpenSignUp } from '@ossy/authentication'
+import { useApp } from './AppContext.js'
+
+/**
+ * Profile link when authenticated; sign-in / sign-up when not.
+ */
+export function HeaderAuthActions ({ compact = false }) {
+  const app = useApp()
+  const router = useRouter()
+  const { t } = useLocale()
+
+  if (app?.isAuthenticated) {
+    return (
+      <Button
+        variant="link"
+        suffix="profile"
+        href={router.getHref('@profile')}
+        aria-label={t('app.shell.header.profile') || 'Profile'}
+        style={{ flexShrink: 0 }}
+      >
+        {compact ? null : (t('app.shell.header.profile') || 'Profile')}
+      </Button>
+    )
+  }
+
+  return (
+    <>
+      <Button
+        variant="link"
+        suffix={OpenSignIn.suffix}
+        href={router.getHref('@sign-in')}
+        label={compact ? undefined : OpenSignIn.label}
+        aria-label={t(OpenSignIn.label)}
+        style={{ flexShrink: 0 }}
+      />
+      <Button
+        variant="cta"
+        suffix={OpenSignUp.suffix}
+        href={router.getHref('@sign-up')}
+        label={compact ? undefined : OpenSignUp.label}
+        aria-label={t(OpenSignUp.label)}
+        style={{ flexShrink: 0 }}
+      />
+    </>
+  )
+}

package/src/shell/LanguageList.jsx

@@ -0,0 +1,83 @@
+import React, { useMemo } from 'react'
+import { Text, View, useLocale } from '@ossy/design-system'
+import { useRouter } from '@ossy/router-react'
+import { languageDisplayName } from './languageCode.js'
+
+const listItemStyle = {
+  display: 'block',
+  width: '100%',
+  textAlign: 'left',
+}
+
+/**
+ * Footer language column when multiple locales are configured.
+ */
+export function LanguageList () {
+  const router = useRouter()
+  const { t } = useLocale()
+  const { language, supportedLanguages, getHref } = router
+
+  const displayNames = useMemo(
+    () => new Intl.DisplayNames([language], { type: 'language' }),
+    [language],
+  )
+
+  if (!supportedLanguages?.length || supportedLanguages.length <= 1) {
+    return null
+  }
+
+  const listLabel = t('app.shell.footer.languages') || 'Languages'
+
+  return (
+    <View layout="column" gap="s" alignItems="flex-start" style={{ minWidth: 0 }}>
+      <Text variant="heading-tertiary" as="h2" style={listItemStyle}>
+        {listLabel}
+      </Text>
+      <View
+        as="nav"
+        aria-label={listLabel}
+        style={{ width: '100%' }}
+      >
+        <View
+          as="ul"
+          layout="column"
+          gap="xs"
+          alignItems="flex-start"
+          style={{ listStyle: 'none', margin: 0, padding: 0, width: '100%' }}
+        >
+          {supportedLanguages.map((lang) => {
+            const isActive = lang === language
+            const label = displayNames.of(lang) ?? languageDisplayName(lang, language)
+
+            if (isActive) {
+              return (
+                <View as="li" key={lang} style={{ width: '100%' }}>
+                  <Text variant="small" as="span" aria-current="true" style={listItemStyle}>
+                    {label}
+                  </Text>
+                </View>
+              )
+            }
+
+            return (
+              <View as="li" key={lang} style={{ width: '100%' }}>
+                <Text
+                  variant="small"
+                  as="a"
+                  href={getHref({ language: lang })}
+                  style={{
+                    ...listItemStyle,
+                    textDecoration: 'underline',
+                    cursor: 'pointer',
+                  }}
+                >
+                  {label}
+                </Text>
+              </View>
+            )
+          })}
+        </View>
+      </View>
+    </View>
+  )
+}

package/src/shell/LanguageSelect.jsx

@@ -0,0 +1,73 @@
+import React from 'react'
+import {
+  Button,
+  ContextMenu,
+  Dropdown,
+  View,
+  useLocale,
+} from '@ossy/design-system'
+import { useRouter } from '@ossy/router-react'
+import { languageCode } from './languageCode.js'
+
+/**
+ * Language switcher for app shell header — cycle when two locales, dropdown when more.
+ */
+export function LanguageSelect () {
+  const router = useRouter()
+  const { t } = useLocale()
+  const { language, supportedLanguages, getHref } = router
+
+  if (!supportedLanguages?.length || supportedLanguages.length <= 1) {
+    return null
+  }
+
+  const pickerLabel = t('app.shell.header.languagePicker') || 'Language'
+
+  if (supportedLanguages.length === 2) {
+    const other = supportedLanguages.find((lang) => lang !== language) ?? supportedLanguages[0]
+
+    return (
+      <Button
+        variant="link"
+        prefix="select"
+        href={getHref({ language: other })}
+        aria-label={pickerLabel}
+        style={{ flexShrink: 0 }}
+      >
+        {languageCode(language)}
+      </Button>
+    )
+  }
+
+  return (
+    <Dropdown
+      trigger={(
+        <Button
+          prefix="select"
+          variant="link"
+          aria-label={pickerLabel}
+          style={{ flexShrink: 0 }}
+        >
+          {languageCode(language)}
+        </Button>
+      )}
+    >
+      <View inset="xs" surface="primary" roundness="s">
+        <ContextMenu roundness="s" surface="primary">
+          {supportedLanguages.map((lang) => {
+            const isActive = lang === language
+            return (
+              <ContextMenu.Item
+                key={lang}
+                href={isActive ? undefined : getHref({ language: lang })}
+                aria-current={isActive ? 'true' : undefined}
+              >
+                {languageCode(lang)}
+              </ContextMenu.Item>
+            )
+          })}
+        </ContextMenu>
+      </View>
+    </Dropdown>
+  )
+}

package/src/shell/ThemeEditor.jsx

@@ -1,5 +1,5 @@
 import React, { useState, useCallback, useEffect } from 'react'
-import { updateResourceContent } from '@ossy/resources'
+import { updateResourceContent } from '@ossy/resources/resource.helpers.js'
 import { useSdk } from '@ossy/sdk-react'
 import { Overlay, Button, useTheme, View, Text } from '@ossy/design-system'
 import { DevPagesPanel } from './DevPagesPanel.jsx'
@@ -68,7 +68,7 @@ export const ThemeEditor = () => {
         isEditorOpen && (
           <Overlay isVisible={true} onClose={onToggle}>
             <View layout="off-center" data-component="theme-editor-overlay">
-              <View slot="content" data-component="theme-editor-panel">
+              <View data-region="content" data-component="theme-editor-panel">
                 <View surface="primary" roundness="m" gap="m" inset="l">
                   <DevPagesPanel />
                   <View as="form" gap="s" onSubmit={onSaveTheme} onChange={onThemeChange}>

package/src/shell/ThemeSelect.jsx

@@ -0,0 +1,101 @@
+import React, { useCallback } from 'react'
+import {
+  Button,
+  ContextMenu,
+  Dropdown,
+  View,
+  useLocale,
+  useTheme,
+} from '@ossy/design-system'
+import { patchUserAppSettings } from './patchUserAppSettings.js'
+
+const THEME_ICON_BY_NAME = {
+  light: 'sun',
+  dark: 'moon',
+  'cloud-light': 'sun',
+  'cloud-dark': 'moon',
+}
+
+function themeLabel (name) {
+  if (typeof name !== 'string' || !name) {
+    return 'Theme'
+  }
+  return name
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ')
+}
+
+function themeIcon (name) {
+  return THEME_ICON_BY_NAME[name] || 'dark-mode'
+}
+
+/**
+ * Theme switcher for app shell header — cycle when two themes, dropdown when more.
+ */
+export function ThemeSelect ({ compact = false }) {
+  const { themes, activeTheme, setTheme } = useTheme()
+  const { t } = useLocale()
+
+  const saveTheme = useCallback((themeName) => {
+    setTheme(themeName)
+    patchUserAppSettings({ theme: themeName }).catch(() => {})
+  }, [setTheme])
+
+  if (!themes?.length || themes.length <= 1) {
+    return null
+  }
+
+  const activeLabel = themeLabel(activeTheme)
+  const ariaLabel =
+    t('app.shell.header.themeSwitch', { theme: activeLabel })
+    || `${activeLabel} theme. Switch theme.`
+
+  if (themes.length === 2) {
+    const cycleTheme = () => {
+      const index = Math.max(0, themes.indexOf(activeTheme))
+      saveTheme(themes[(index + 1) % themes.length])
+    }
+
+    return (
+      <Button
+        variant="link"
+        prefix={themeIcon(activeTheme)}
+        onClick={cycleTheme}
+        aria-label={ariaLabel}
+        style={{ flexShrink: 0 }}
+      >
+        {compact ? null : activeLabel}
+      </Button>
+    )
+  }
+
+  return (
+    <Dropdown
+      trigger={(
+        <Button
+          prefix={compact ? themeIcon(activeTheme) : 'select'}
+          variant="link"
+          aria-label={ariaLabel}
+          style={{ flexShrink: 0 }}
+        >
+          {compact ? null : activeLabel}
+        </Button>
+      )}
+    >
+      <View inset="xs" surface="primary" roundness="s">
+        <ContextMenu roundness="s" surface="primary">
+          {themes.map((name) => (
+            <ContextMenu.Item
+              key={name}
+              onClick={() => saveTheme(name)}
+              aria-current={name === activeTheme ? 'true' : undefined}
+            >
+              {themeLabel(name)}
+            </ContextMenu.Item>
+          ))}
+        </ContextMenu>
+      </View>
+    </Dropdown>
+  )
+}

package/src/shell/buildSidebarNav.js

@@ -0,0 +1,113 @@
+import { slugToDisplayName } from '@ossy/package-catalog'
+import { isServiceEntitled } from '@ossy/workspaces/entitlements'
+import { resolveWorkspaceServices } from './resolveWorkspaceServices.js'
+
+/**
+ * @typedef {object} SidebarShellItem
+ * @property {string} id
+ * @property {string} label
+ * @property {string} prefix
+ */
+
+/**
+ * @typedef {object} SidebarPackageItem
+ * @property {string} slug
+ * @property {string} label
+ * @property {string} icon
+ * @property {string} pageId
+ * @property {number} order
+ */
+
+/**
+ * Pick the package "home" page from manifest pages.
+ * Convention: slug plus "/home", then any page id ending in "/home", then shortest route path.
+ *
+ * @param {Array<{ id?: string, path?: string | Record<string, string> }>} pages
+ * @param {string} slug
+ * @returns {string | null}
+ */
+export function resolvePackageHomePageId (pages, slug) {
+  const list = (pages || []).filter((page) => page?.id)
+  if (!list.length) return null
+
+  const conventional = list.find((page) => page.id === `${slug}/home`)
+  if (conventional) return conventional.id
+
+  const anyHome = list.find((page) => page.id === 'home' || page.id.endsWith('/home'))
+  if (anyHome) return anyHome.id
+
+  const pathLength = (page) => {
+    const path = page.path
+    if (typeof path === 'string') return path.length
+    if (path && typeof path === 'object') {
+      return Math.min(...Object.values(path).map((p) => (typeof p === 'string' ? p.length : 999)))
+    }
+    return 999
+  }
+
+  const byPath = [...list].sort((a, b) => pathLength(a) - pathLength(b) || a.id.localeCompare(b.id))
+  return byPath[0].id
+}
+
+/**
+ * Build entitlement-filtered sidebar navigation — one link per entitled package home.
+ *
+ * @param {{
+ *   manifestSummary?: { packages?: Array<{ slug?: string, package?: string, pages?: Array<{ id: string, title?: string, path?: string | Record<string, string> }> }> }
+ *   workspaceServices?: Record<string, { enabled?: boolean }>
+ *   definitions?: Record<string, object>
+ *   isAuthenticated?: boolean
+ *   workspaceId?: string
+ *   devMode?: boolean
+ *   devEntitlements?: Record<string, { enabled?: boolean }>
+ *   shellItems?: SidebarShellItem[]
+ *   excludeSlugs?: string[] | Set<string>
+ * }} options
+ * @returns {{ shellItems: SidebarShellItem[], packageItems: SidebarPackageItem[], services: Record<string, { enabled?: boolean }> }}
+ */
+export function buildSidebarNav ({
+  manifestSummary,
+  workspaceServices,
+  definitions = {},
+  isAuthenticated = false,
+  workspaceId,
+  devMode = false,
+  devEntitlements,
+  shellItems = [],
+  excludeSlugs = [],
+}) {
+  const services = resolveWorkspaceServices({ devMode, devEntitlements, workspaceServices })
+  const excluded = excludeSlugs instanceof Set ? excludeSlugs : new Set(excludeSlugs)
+
+  const canShowProductGroups =
+    (isAuthenticated && workspaceId) ||
+    (devMode && devEntitlements && Object.keys(devEntitlements).length > 0)
+
+  const packageItems = !canShowProductGroups
+    ? []
+    : (manifestSummary?.packages || [])
+      .filter((pkg) => pkg.slug && !excluded.has(pkg.slug))
+      .filter((pkg) => !definitions[pkg.slug]?.status?.includes('hidden'))
+      .filter((pkg) => {
+        const def = definitions[pkg.slug]
+        const entitlementRequired = def?.entitlementRequired !== false
+        return !entitlementRequired || isServiceEntitled(services, pkg.package)
+      })
+      .map((pkg) => {
+        const slug = pkg.slug
+        const def = definitions[slug]
+        const pageId = resolvePackageHomePageId(pkg.pages, slug)
+        if (!pageId) return null
+        return {
+          slug,
+          label: def?.title || slugToDisplayName(slug),
+          icon: def?.icon || 'package',
+          order: def?.navOrder ?? 100,
+          pageId,
+        }
+      })
+      .filter(Boolean)
+      .sort((a, b) => a.order - b.order || a.label.localeCompare(b.label))
+
+  return { shellItems, packageItems, services }
+}