feat(app-shell): ADR-0048 (A) package-id routing — foundation (resolver)

First, non-breaking slice of the unified package-id routing refactor.

- New `appRoute` helpers: `appRouteSegment(app)` (canonical link segment =
  package id, name fallback) and `matchAppBySegment(apps, seg)` (resolve a
  route segment to its app, preferring `_packageId`, falling back to `name`).
- AppContent's active-app selection now uses `matchAppBySegment`, so
  `/apps/<packageId>` resolves — while `/apps/<appName>` keeps working (the
  name fallback doubles as a per-tenant alias / legacy URL). No emitted URL
  changes yet, so live behaviour is unchanged.

Remaining (browser-verified follow-up): switch href emission from app objects
to package id at the ~13 nav sites (AppSidebar/UnifiedSidebar/AppSwitcher/
AppHeader/CommandPalette/SearchResultsPage/UnpublishedAppBar/useNavigationSync/
ConsoleFloatingChatbot), and move docs to /apps/:packageId/docs/:name
(DocPage prefer-local + DocsIndex package-scoped links).

Test: utils/__tests__/appRoute.test.ts (7). Typecheck clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: os-zhuang

packages/app-shell/src/console/AppContent.tsx

@@ -25,6 +25,7 @@ import { PreviewDraftEmptyState } from '../preview/PreviewDraftEmptyState';
 import { ExpressionProvider, evaluateVisibility } from '../providers/ExpressionProvider';
 import { useTrackRouteAsRecent } from '../hooks/useTrackRouteAsRecent';
 import { resolveRecordFormTarget, resolveNavigateCreateUrl, resolveNavigateEditUrl } from '../utils/recordFormNavigation';
+import { matchAppBySegment } from '../utils/appRoute';
 import { resolveHref, type NavTemplateContext } from '@object-ui/layout';
 import { ExpressionEvaluator } from '@object-ui/core';
 
@@ -172,7 +173,9 @@ export function AppContent({ extraRoutes, extraRoutesNoApp }: AppContentProps =
   const activeApps = apps.filter((a: any) => a.active !== false);
   const launcherApps = activeApps.filter((a: any) => a.hidden !== true);
   const activeApp =
-    apps.find((a: any) => a.name === appName) ||
+    // ADR-0048 (A) — the route segment is the package id; resolve by it,
+    // falling back to the app name (legacy/alias URL).
+    matchAppBySegment(apps, appName) ||
     launcherApps.find((a: any) => a.isDefault === true) ||
     launcherApps[0];
 

packages/app-shell/src/utils/__tests__/appRoute.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { appRouteSegment, matchAppBySegment } from '../appRoute';
+
+/**
+ * ADR-0048 (option A) — package-id route segment.
+ */
+describe('appRouteSegment', () => {
+  it('returns the package id when present', () => {
+    expect(appRouteSegment({ name: 'crm', _packageId: 'com.acme.crm' })).toBe('com.acme.crm');
+  });
+  it('falls back to the app name when no package id', () => {
+    expect(appRouteSegment({ name: 'crm' })).toBe('crm');
+  });
+  it('returns undefined for nullish input', () => {
+    expect(appRouteSegment(undefined)).toBeUndefined();
+    expect(appRouteSegment(null)).toBeUndefined();
+  });
+});
+
+describe('matchAppBySegment', () => {
+  const crm = { name: 'crm', _packageId: 'com.acme.crm' };
+  const hr = { name: 'crm', _packageId: 'com.beta.crm' }; // same display name, different vendor
+  const apps = [crm, hr];
+
+  it('matches by package id (disambiguates same-named apps)', () => {
+    expect(matchAppBySegment(apps, 'com.acme.crm')).toBe(crm);
+    expect(matchAppBySegment(apps, 'com.beta.crm')).toBe(hr);
+  });
+  it('falls back to matching by name (legacy/alias URL)', () => {
+    expect(matchAppBySegment([{ name: 'sales' }], 'sales')).toEqual({ name: 'sales' });
+  });
+  it('prefers a package-id match over a name match', () => {
+    const byName = { name: 'com.acme.crm' }; // pathological: an app literally named like a pkg id
+    expect(matchAppBySegment([byName, crm], 'com.acme.crm')).toBe(crm);
+  });
+  it('returns undefined for missing inputs', () => {
+    expect(matchAppBySegment(apps, undefined)).toBeUndefined();
+    expect(matchAppBySegment(null, 'com.acme.crm')).toBeUndefined();
+  });
+});

packages/app-shell/src/utils/appRoute.ts

@@ -0,0 +1,30 @@
+/**
+ * ADR-0048 (option A) — the `/apps/<segment>` route is keyed on the **package
+ * id** (reverse-domain, globally unique), not the app's display name. This makes
+ * two vendors' same-named apps unambiguous and self-describing in the URL.
+ *
+ * - `appRouteSegment(app)` — the canonical route segment for linking TO an app
+ *   (its package id; falls back to `name` for runtime/DB apps with no
+ *   `_packageId`).
+ * - `matchAppBySegment(apps, seg)` — resolve a route segment back to its app,
+ *   preferring the package id and falling back to the app name. The name
+ *   fallback doubles as a per-tenant friendly alias and keeps legacy
+ *   name-based URLs/bookmarks working. Callers keep their own
+ *   default/first-app fallback around this match.
+ */
+
+type AppLike = { name?: unknown; _packageId?: unknown } & Record<string, unknown>;
+
+export function appRouteSegment(app: AppLike | null | undefined): string | undefined {
+  if (!app) return undefined;
+  const seg = (app._packageId as string | undefined) ?? (app.name as string | undefined);
+  return seg ?? undefined;
+}
+
+export function matchAppBySegment<T extends AppLike>(
+  apps: readonly T[] | null | undefined,
+  seg: string | null | undefined,
+): T | undefined {
+  if (!apps || seg == null) return undefined;
+  return apps.find((a) => a?._packageId === seg) ?? apps.find((a) => a?.name === seg);
+}

packages/app-shell/src/utils/index.ts

@@ -14,6 +14,7 @@ export { deriveRelatedLists } from './deriveRelatedLists';
 export type { DerivedRelatedList } from './deriveRelatedLists';
 
 export { preferLocal } from './preferLocal';
+export { appRouteSegment, matchAppBySegment } from './appRoute';
 
 /**
  * Resolves an I18nLabel to a plain string.