feat(app-shell): ADR-0048 (A) — emit package-id app URLs from nav (emission layer) (#1696)

Nav now generates `/apps/<packageId>` links instead of `/apps/<name>`: app
switching (AppSwitcher/AppSidebar/CommandPalette onAppChange), sidebar base paths
(AppSidebar/UnifiedSidebar), create/edit-app, and the AppHeader hidden-app switch
all build via `appRouteSegment(app)` (= package id, name fallback). Route-param
propagation then carries the package id through every in-app link.

Browser-verified (live split backend): entering Studio via a package-id URL,
all 53 in-app links emit `/apps/com.objectstack.studio/...` (0 name-based);
Studio renders with full sidebar+header; `/apps/studio` (name) still resolves.
Typecheck clean.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

packages/app-shell/src/chrome/CommandPalette.tsx

@@ -32,7 +32,7 @@ import { useRecordSearch } from '@object-ui/react';
 import { useTheme } from './ThemeProvider';
 import { useExpressionContext, evaluateVisibility } from '../providers/ExpressionProvider';
 import { useObjectTranslation } from '@object-ui/i18n';
-import { resolveI18nLabel, getRecordDisplayName } from '../utils';
+import { resolveI18nLabel, getRecordDisplayName, appRouteSegment } from '../utils';
 import { getIcon } from '../utils/getIcon';
 import { useRecentItems } from '../context/RecentItemsProvider';
 import { resolveHref } from '@object-ui/layout';
@@ -76,7 +76,7 @@ export function CommandPalette({ apps, activeApp, objects, onAppChange, dataSour
     if (!open) setInputValue('');
   }, [open]);
 
-  const baseUrl = `/apps/${appName || activeApp?.name}`;
+  const baseUrl = `/apps/${appName || appRouteSegment(activeApp)}`;
   const { user } = useAuth();
   const templateContext = useMemo(() => ({ currentUserId: user?.id ?? null }), [user?.id]);
 
@@ -284,7 +284,7 @@ export function CommandPalette({ apps, activeApp, objects, onAppChange, dataSour
                     <CommandItem
                       key={app.name}
                       value={`app ${resolveI18nLabel(app.label, t)} ${app.name}`}
-                      onSelect={() => runCommand(() => onAppChange(app.name))}
+                      onSelect={() => runCommand(() => onAppChange(appRouteSegment(app) ?? app.name))}
                     >
                       <Icon className="mr-2 h-4 w-4" />
                       <span>{resolveI18nLabel(app.label, t)}</span>

packages/app-shell/src/layout/AppHeader.tsx

@@ -61,7 +61,7 @@ import { useObjectTranslation, useObjectLabel } from '@object-ui/i18n';
 import type { BreadcrumbItem as BreadcrumbItemType } from '@object-ui/types';
 import { useAuth, getUserInitials } from '@object-ui/auth';
 import { useMetadata } from '../providers/MetadataProvider';
-import { resolveI18nLabel, preferLocal, matchAppBySegment } from '../utils';
+import { resolveI18nLabel, preferLocal, matchAppBySegment, appRouteSegment } from '../utils';
 import { getIcon } from '../utils/getIcon';
 import { useMobileViewSwitcher } from './MobileViewSwitcherContext';
 import { useNavigationContext } from '../context/NavigationContext';
@@ -856,7 +856,7 @@ export function AppHeader({
                   return (
                     <DropdownMenuItem
                       key={`hidden_app_${app.name}`}
-                      onClick={() => navigate(`/apps/${app.name}`)}
+                      onClick={() => navigate(`/apps/${appRouteSegment(app) ?? app.name}`)}
                       className="cursor-pointer"
                     >
                       <AppIcon className="mr-2 h-4 w-4" />

packages/app-shell/src/layout/AppSidebar.tsx

@@ -61,7 +61,7 @@ import { usePermissions } from '@object-ui/permissions';
 import { useRecentItems } from '../hooks/useRecentItems';
 import { useFavorites } from '../hooks/useFavorites';
 import { useNavPins } from '../hooks/useNavPins';
-import { resolveI18nLabel, matchAppBySegment } from '../utils';
+import { resolveI18nLabel, matchAppBySegment, appRouteSegment } from '../utils';
 import { useObjectTranslation, useObjectLabel } from '@object-ui/i18n';
 import { useAppContextSelectors } from './ContextSelectors';
 
@@ -271,7 +271,7 @@ export function AppSidebar({ activeAppName, onAppChange }: { activeAppName: stri
     [registeredObjectNames],
   );
 
-  const basePath = activeApp ? `/apps/${activeAppName}` : '';
+  const basePath = activeApp ? `/apps/${appRouteSegment(activeApp) ?? activeAppName}` : '';
 
   // Fallback system navigation when no active app exists — routes into the Setup app.
   // The marketplace entry is hidden from non-admin members (install is gated to
@@ -341,7 +341,7 @@ export function AppSidebar({ activeAppName, onAppChange }: { activeAppName: stri
                 {activeApps.map((app: any) => (
                   <DropdownMenuItem
                     key={app.name}
-                    onClick={() => onAppChange(app.name)}
+                    onClick={() => onAppChange(appRouteSegment(app) ?? app.name)}
                     className="gap-2 p-2"
                   >
                     <div className="flex size-6 items-center justify-center rounded-sm border">
@@ -359,13 +359,13 @@ export function AppSidebar({ activeAppName, onAppChange }: { activeAppName: stri
                   <div className="font-medium text-muted-foreground">{t('layout.appSwitcher.home')}</div>
                 </DropdownMenuItem>
                 <DropdownMenuSeparator />
-                <DropdownMenuItem className="gap-2 p-2" onClick={() => navigate(`/apps/${activeAppName}/create-app`)} data-testid="add-app-btn">
+                <DropdownMenuItem className="gap-2 p-2" onClick={() => navigate(`/apps/${appRouteSegment(activeApp) ?? activeAppName}/create-app`)} data-testid="add-app-btn">
                   <div className="flex size-6 items-center justify-center rounded-md border bg-background">
                     <Plus className="size-4" />
                   </div>
                   <div className="font-medium text-muted-foreground">{t('layout.appSwitcher.addApp')}</div>
                 </DropdownMenuItem>
-                <DropdownMenuItem className="gap-2 p-2" onClick={() => navigate(`/apps/${activeAppName}/edit-app/${activeAppName}`)} data-testid="edit-app-btn">
+                <DropdownMenuItem className="gap-2 p-2" onClick={() => navigate(`/apps/${appRouteSegment(activeApp) ?? activeAppName}/edit-app/${activeAppName}`)} data-testid="edit-app-btn">
                   <div className="flex size-6 items-center justify-center rounded-md border bg-background">
                     <Pencil className="size-4" />
                   </div>
@@ -655,7 +655,7 @@ export function AppSidebar({ activeAppName, onAppChange }: { activeAppName: stri
           }
           return leaves.slice(0, 5).map((item: any) => {
           const NavIcon = getIcon(item.icon);
-          const baseUrl = activeApp ? `/apps/${activeAppName}` : '';
+          const baseUrl = activeApp ? `/apps/${appRouteSegment(activeApp) ?? activeAppName}` : '';
           const { href } = resolveHref(item, baseUrl, { currentUserId: user?.id ?? null });
           return (
             <Link key={item.id} to={href} className="flex flex-col items-center gap-0.5 px-2 py-1.5 text-muted-foreground hover:text-foreground transition-colors min-w-[44px] min-h-[44px] justify-center">

packages/app-shell/src/layout/AppSwitcher.tsx

@@ -17,7 +17,7 @@ import {
 } from '@object-ui/components';
 import { ChevronDown, Check } from 'lucide-react';
 import { useMetadata } from '../providers/MetadataProvider';
-import { resolveI18nLabel, matchAppBySegment } from '../utils';
+import { resolveI18nLabel, matchAppBySegment, appRouteSegment } from '../utils';
 import { useObjectTranslation, useObjectLabel } from '@object-ui/i18n';
 import { getIcon } from '../utils/getIcon';
 
@@ -63,7 +63,7 @@ export function AppSwitcher({ activeAppName, onAppChange }: AppSwitcherProps) {
           return (
             <DropdownMenuItem
               key={app.name}
-              onClick={() => onAppChange(app.name)}
+              onClick={() => onAppChange(appRouteSegment(app) ?? app.name)}
               className="flex items-center gap-2.5 py-2"
             >
               <div className="flex size-5 shrink-0 items-center justify-center rounded border bg-muted text-muted-foreground">

packages/app-shell/src/layout/UnifiedSidebar.tsx

@@ -47,7 +47,7 @@ import { useAuth, useIsWorkspaceAdmin } from '@object-ui/auth';
 import { useRecentItems } from '../hooks/useRecentItems';
 import { useFavorites } from '../hooks/useFavorites';
 import { useNavPins } from '../hooks/useNavPins';
-import { resolveI18nLabel, matchAppBySegment } from '../utils';
+import { resolveI18nLabel, matchAppBySegment, appRouteSegment } from '../utils';
 import { useObjectTranslation, useObjectLabel } from '@object-ui/i18n';
 // useObjectLabel provides appLabel/appDescription for convention-based
 // i18n lookup — `{ns}.apps.{name}.label` resolves to the translated label
@@ -255,7 +255,7 @@ export function UnifiedSidebar({ activeAppName }: UnifiedSidebarProps) {
 
   // Determine which navigation to show based on context
   const navigationItems = context === 'home' ? homeNavigation : appNavigation;
-  const basePath = context === 'app' && activeApp ? `/apps/${activeApp.name}` : '';
+  const basePath = context === 'app' && activeApp ? `/apps/${appRouteSegment(activeApp)}` : '';
   const isStudioApp = context === 'app' && activeApp?.name === 'studio';
   const studioHomeSearch = React.useMemo(() => {
     if (!isStudioApp) return '';