From ab10d93f9d769eaea41baf503a14b60d6d18c298 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 7 Aug 2026 14:50:02 +0000
Subject: [PATCH 1/2] =?UTF-8?q?fix(app-shell):=20=E7=A9=BA=E6=80=81?=
 =?UTF-8?q?=E3=80=8CCreate=20Your=20First=20App=E3=80=8DCTA=20=E6=8C=87?=
 =?UTF-8?q?=E5=90=91=E5=B7=B2=E5=A3=B0=E6=98=8E=E7=9A=84=20app=20=E5=86=85?=
 =?UTF-8?q?=20create-app=20=E8=B7=AF=E7=94=B1=20(#3573)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

零应用部署的第一屏上,唯一指向「建应用」的 CTA 调用 navigate('/create-app') ——
带前导斜杠的绝对路径,从宿主的根路由树解析。根路由树没有声明 /create-app,于是落到
末尾的 <Route path="*"> 兜底,被 replace 回落地页 `/`:按钮看起来毫无反应。

真正声明 create-app 的是 AppContent 自己,位于 /apps/:appName/* 子树内(无 activeApp
分支与有 app 的路由表各一处)。改为构造 app 作用域的 /apps/<segment>/create-app ——
ADR-0048 的规范应用 URL,也正是 AppSidebar 的 add-app 入口已经在用的同一目标。

实测记录(新增路由测试逐条钉住):

- 空态的真实 URL 家族是 /apps/setup 及其子路径。空态前置条件要求 !activeApp 且
  非 create-app/system/metadata 三条伪路由;要绕过 requestedAppMissing 又必须
  isSpecialRoute,相减后只剩 isSetupRoute。零应用用户从 `/` 会被
  RootLandingRedirect 送到 /home,AppContent 根本不挂载 —— 空态只在子树内出现。
- 因此「改成相对跳转 navigate('create-app')」不成立:装机的 react-router 7 里
  getResolveToMatches 用 LEAF match 的完整 pathname(含 splat)作为相对解析基
  (v6 的 v7_relativeSplatPath 开关,v7 已固化)。它只在最浅的 /apps/setup 正确,
  从 /apps/setup/<segment> 会拼出 /apps/setup/<segment>/create-app —— 匹配不到
  任何路由,渲染成白屏,比原来的弹回更难诊断。

反向验证:两条 CTA 测试在未改的源码上先跑红(dump 里 pathname 为 `/`、
root-landing 已渲染),改后 6/6 全绿。旁边的 go-to-settings-btn 未触及,
其绝对 /apps/setup 目标另有一条测试守住。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
---
 .../no-apps-create-first-app-cta-3573.md      |  26 ++
 packages/app-shell/src/console/AppContent.tsx |  19 +-
 .../__tests__/AppContent.noAppsCta.test.tsx   | 222 ++++++++++++++++++
 3 files changed, 266 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/no-apps-create-first-app-cta-3573.md
 create mode 100644 packages/app-shell/src/console/__tests__/AppContent.noAppsCta.test.tsx

diff --git a/.changeset/no-apps-create-first-app-cta-3573.md b/.changeset/no-apps-create-first-app-cta-3573.md
new file mode 100644
index 0000000000..6ae29a41cf
--- /dev/null
+++ b/.changeset/no-apps-create-first-app-cta-3573.md
@@ -0,0 +1,26 @@
+---
+'@object-ui/app-shell': patch
+---
+
+The no-apps empty state's "Create Your First App" CTA now opens the app-creation
+flow instead of silently bouncing the user back to the landing page. It called
+`navigate('/create-app')` — an ABSOLUTE path, so it resolved against the HOST's
+root route tree, which declares no `/create-app`; the reference host's trailing
+`<Route path="*">` therefore replaced it with `/`. The `create-app` route is
+declared by `AppContent` itself, inside the `/apps/:appName/*` subtree (both the
+no-active-app branch and the with-app router), so the CTA now builds the
+app-scoped `/apps/<segment>/create-app` — the platform's canonical app URL
+(ADR-0048) and the same target the sidebar's add-app entry already links to. On
+a fresh zero-app deployment this was the first screen's only route into app
+creation, and it read as a button that does nothing (#3573).
+
+A plain relative `navigate('create-app')` is deliberately NOT the fix, and the
+new routing test pins why: under the installed react-router 7,
+`getResolveToMatches` resolves a relative target against the LEAF match's full
+`pathname` with the splat INCLUDED (in v6 this was the `v7_relativeSplatPath`
+future flag; v7 hardcodes it). The empty state renders across a whole URL family
+— `/apps/setup` and any deeper `/apps/setup/<segment>` — so the relative form is
+right only at the shallowest of them and builds
+`/apps/setup/<segment>/create-app` elsewhere, which matches no route and renders
+a blank screen instead of the bounce. The sibling "System Settings" CTA is
+unchanged.
diff --git a/packages/app-shell/src/console/AppContent.tsx b/packages/app-shell/src/console/AppContent.tsx
index 9b4973690a..92333202ed 100644
--- a/packages/app-shell/src/console/AppContent.tsx
+++ b/packages/app-shell/src/console/AppContent.tsx
@@ -573,7 +573,24 @@ export function AppContent({ extraRoutes, extraRoutesNoApp }: AppContentProps =
           {t('empty.noAppsConfiguredDescription')}
         </EmptyDescription>
         <div className="mt-4 flex flex-col sm:flex-row items-center gap-3">
-          <Button onClick={() => navigate('/create-app')} data-testid="create-first-app-btn">
+          {/* #3573 — target the APP-SCOPED route, not the host root. `create-app`
+              is declared by THIS component (the no-active-app branch just below,
+              and the with-app router further down), i.e. inside the
+              `/apps/:appName/*` subtree — never at the root. The former absolute
+              `/create-app` resolved against the HOST's root route tree, which
+              declares no such path, so the host's trailing catch-all silently
+              bounced the user back to the landing page: a dead first-screen CTA.
+              A plain relative `navigate('create-app')` does NOT fix it either —
+              react-router 7 resolves a relative `to` against the LEAF match's
+              FULL pathname, splat INCLUDED (`getResolveToMatches`), so from
+              `/apps/setup/<anything>` it builds `/apps/setup/<anything>/create-app`,
+              which matches no route and renders a blank screen. `/apps/<segment>`
+              is the platform's canonical app URL (ADR-0048) and is what every
+              other navigation in this file — and AppSidebar's own add-app entry —
+              builds, so build it here too. (This branch is only reachable under
+              `/apps/setup…`: it requires `isSetupRoute`, the one pseudo-route the
+              guard above does not exclude — so `appName` is always present here.) */}
+          <Button onClick={() => navigate(`/apps/${appName}/create-app`)} data-testid="create-first-app-btn">
             {t('empty.createFirstApp')}
           </Button>
           <Button variant="outline" onClick={() => navigate('/apps/setup')} data-testid="go-to-settings-btn">
diff --git a/packages/app-shell/src/console/__tests__/AppContent.noAppsCta.test.tsx b/packages/app-shell/src/console/__tests__/AppContent.noAppsCta.test.tsx
new file mode 100644
index 0000000000..33334be67f
--- /dev/null
+++ b/packages/app-shell/src/console/__tests__/AppContent.noAppsCta.test.tsx
@@ -0,0 +1,222 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * No-apps empty state — "Create Your First App" must reach the DECLARED
+ * create-app route (objectui#3573).
+ *
+ * ## Measured URL shapes (why the entries below are the real-world ones)
+ *
+ * `AppContent` is mounted by the reference host at ONE place only —
+ * `apps/console/src/App.tsx`: `<Route path="/apps/:appName/*" />`. The empty
+ * state's precondition (`AppContent.tsx`, the `!activeApp && !isCreateAppRoute
+ * && !isSystemRoute && !isMetadataRoute` guard) can therefore only be reached
+ * when the `:appName` segment did NOT resolve to an app AND the URL is one of
+ * the built-in pseudo-routes (otherwise `requestedAppMissing` short-circuits to
+ * the "App not available" screen instead). Subtracting the three pseudo-routes
+ * the guard itself excludes leaves exactly one family:
+ *
+ *     /apps/setup                 and   /apps/setup/<anything not
+ *                                       system|metadata|create-app>
+ *
+ * which is precisely where the sidebar's no-active-app system navigation and
+ * the empty state's own `go-to-settings-btn` send a zero-app user
+ * (`layout/AppSidebar.tsx` systemFallbackNavigation → `/apps/setup`).
+ *
+ * `/` is NOT such a URL: with zero apps `RootLandingRedirect` resolves to
+ * `/home` and `AppContent` never mounts. So the empty state always renders
+ * INSIDE the `/apps/:appName/*` subtree — which is what makes a relative
+ * navigation well-founded, and is pinned by the last test here.
+ *
+ * ## What the fix is (and why the obvious relative form is NOT it)
+ *
+ * The CTA used to call `navigate('/create-app')` — absolute, so it resolved
+ * against the ROOT route tree, which declares no such path; the host's trailing
+ * `<Route path="*">` bounced the user to `/`. The `create-app` route is
+ * declared by `AppContent` itself (both the no-active-app branch and the
+ * with-app branch), i.e. INSIDE the `/apps/:appName/*` subtree.
+ *
+ * MEASURED, against the installed react-router 7.18: a plain relative
+ * `navigate('create-app')` does NOT fix this. `getResolveToMatches` gives the
+ * LEAF match's FULL `pathname` — splat INCLUDED — as the resolution base (in
+ * v6 this was the `v7_relativeSplatPath` future flag; v7 hardcodes it). So the
+ * relative form is depth-dependent: right at `/apps/setup`, but from
+ * `/apps/setup/sys_inbox_message` it builds
+ * `/apps/setup/sys_inbox_message/create-app`, which matches no route inside the
+ * no-active-app `<Routes>` and renders a BLANK screen. The two CTA tests below
+ * cover both depths precisely so that trap stays pinned.
+ *
+ * The fix therefore builds the app-scoped URL `/apps/<segment>/create-app` —
+ * the platform's canonical app URL contract (ADR-0048, `utils/appRoute.ts`),
+ * the same target `layout/AppSidebar.tsx`'s add-app entry already builds, and
+ * the same base every other navigation in `AppContent.tsx` uses.
+ *
+ * NOTE ON SCOPE: `@object-ui/plugin-designer` is stubbed below — this file
+ * measures ROUTING (which route matches, which URL results), not the app
+ * designer's internals.
+ */
+
+import '@testing-library/jest-dom/vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import React from 'react';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { MemoryRouter, Routes, Route, Navigate, useLocation } from 'react-router-dom';
+
+// ---------------------------------------------------------------------------
+// Mocks — providers and the lazily-imported designer pages. Everything that
+// takes part in the ROUTING decision (AppContent's own guards, its nested
+// <Routes>, react-router's relative resolution) stays real.
+// ---------------------------------------------------------------------------
+
+// The CTA's target sits behind `React.lazy(() => import('@object-ui/plugin-designer'))`.
+// Stubbing it keeps the assertion off the transform pipeline entirely (AGENTS.md
+// §测试纪律: never let an unbounded module load race a bounded `findBy` window).
+vi.mock('@object-ui/plugin-designer', () => ({
+  CreateAppPage: () => <div data-testid="create-app-page">create app</div>,
+  EditAppPage: () => <div data-testid="edit-app-page" />,
+  DashboardDesignPage: () => <div data-testid="dashboard-design-page" />,
+}));
+
+vi.mock('@object-ui/i18n', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useObjectTranslation: () => ({
+    t: (key: string, options?: Record<string, unknown>) => String(options?.defaultValue ?? key),
+  }),
+  useObjectLabel: () => ({
+    objectLabel: ({ label }: { label?: string }) => label,
+  }),
+}));
+
+vi.mock('@object-ui/auth', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useAuth: () => ({
+    user: null,
+    getAuthConfig: async () => ({ features: {} }),
+    activeOrganization: null,
+  }),
+  useIsWorkspaceAdmin: () => false,
+}));
+
+const dataSourceStub = {
+  onConnectionStateChange: () => () => {},
+  getConnectionState: () => 'connected',
+};
+vi.mock('../../providers/AdapterProvider', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useAdapter: () => dataSourceStub,
+}));
+
+/** The zero-app deployment this whole screen exists for. */
+const NO_APPS: unknown[] = [];
+const refreshMetadata = vi.fn(async () => {});
+vi.mock('../../providers/MetadataProvider', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useMetadata: () => ({
+    apps: NO_APPS,
+    objects: [],
+    loading: false,
+    // `undefined` — no bucket preloading to await, so the shell is ready on
+    // first render (mirrors a host that ships metadata eagerly).
+    ensureType: undefined,
+    error: null,
+    refresh: refreshMetadata,
+  }),
+}));
+
+const actionRunnerStub = { registerHandler: vi.fn(), getContext: () => ({}) };
+vi.mock('@object-ui/react', async (importOriginal) => ({
+  ...(await importOriginal<Record<string, unknown>>()),
+  useActionRunner: () => ({ execute: vi.fn(), runner: actionRunnerStub }),
+  useGlobalUndo: () => {},
+  useMutationInvalidationBridge: () => {},
+}));
+
+import { AppContent } from '../AppContent';
+
+/** Reports the live URL so a bounce is visible as a URL, not just a screen. */
+function LocationProbe() {
+  const location = useLocation();
+  return <div data-testid="pathname">{location.pathname}</div>;
+}
+
+/**
+ * The reference host's route tree, reduced to the parts that decide this
+ * question: the `/apps/:appName/*` subtree, the landing route, and the
+ * trailing catch-all that used to swallow `/create-app`.
+ * Mirrors `apps/console/src/App.tsx`.
+ */
+function renderConsoleAt(initialUrl: string) {
+  return render(
+    <MemoryRouter initialEntries={[initialUrl]}>
+      <LocationProbe />
+      <Routes>
+        <Route path="/apps/:appName/*" element={<AppContent />} />
+        <Route path="/" element={<div data-testid="root-landing">landing</div>} />
+        <Route path="/home" element={<div data-testid="home-launcher">home</div>} />
+        <Route path="*" element={<Navigate to="/" replace />} />
+      </Routes>
+    </MemoryRouter>,
+  );
+}
+
+const pathname = () => screen.getByTestId('pathname').textContent;
+
+describe('AppContent — no-apps empty state CTA (objectui#3573)', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('renders the empty state at /apps/setup — the measured entry URL', async () => {
+    renderConsoleAt('/apps/setup');
+    expect(await screen.findByTestId('create-first-app-btn')).toBeInTheDocument();
+  });
+
+  it('renders it deeper in the same pseudo-route subtree too', async () => {
+    renderConsoleAt('/apps/setup/sys_inbox_message');
+    expect(await screen.findByTestId('create-first-app-btn')).toBeInTheDocument();
+  });
+
+  it('CTA opens the declared create-app route instead of bouncing to the landing page', async () => {
+    renderConsoleAt('/apps/setup');
+    fireEvent.click(await screen.findByTestId('create-first-app-btn'));
+
+    expect(await screen.findByTestId('create-app-page')).toBeInTheDocument();
+    expect(pathname()).toBe('/apps/setup/create-app');
+    // The regression this pins: the absolute `/create-app` matched no root
+    // route, so the host's `<Route path="*">` replaced it with `/`.
+    expect(screen.queryByTestId('root-landing')).not.toBeInTheDocument();
+  });
+
+  it('resolves from a deeper splat URL to the SAME create-app route', async () => {
+    // The depth trap: react-router 7 resolves a relative `to` against the leaf
+    // match's full pathname (splat included), so a relative `create-app` would
+    // build `/apps/setup/sys_inbox_message/create-app` here — matching nothing,
+    // rendering blank. The splat segment must NOT reach the target URL.
+    renderConsoleAt('/apps/setup/sys_inbox_message');
+    fireEvent.click(await screen.findByTestId('create-first-app-btn'));
+
+    expect(await screen.findByTestId('create-app-page')).toBeInTheDocument();
+    expect(pathname()).toBe('/apps/setup/create-app');
+    expect(screen.queryByTestId('root-landing')).not.toBeInTheDocument();
+  });
+
+  it('leaves the sibling go-to-settings CTA on its absolute /apps/setup target', async () => {
+    renderConsoleAt('/apps/setup/sys_inbox_message');
+    fireEvent.click(await screen.findByTestId('go-to-settings-btn'));
+
+    expect(pathname()).toBe('/apps/setup');
+    // Still the zero-app deployment, so the same empty state renders there.
+    expect(await screen.findByTestId('create-first-app-btn')).toBeInTheDocument();
+    expect(screen.queryByTestId('root-landing')).not.toBeInTheDocument();
+  });
+
+  it('MEASUREMENT: a non-pseudo /apps/:appName URL never reaches this empty state', async () => {
+    // Evidence for the URL-family claim in the file header: an unresolved app
+    // segment that is not a pseudo-route takes the "App not available" branch,
+    // so `/apps/setup*` really is the only family the CTA has to work from.
+    renderConsoleAt('/apps/crm');
+    expect(await screen.findByTestId('app-not-available-retry')).toBeInTheDocument();
+    await waitFor(() => {
+      expect(screen.queryByTestId('create-first-app-btn')).not.toBeInTheDocument();
+    });
+  });
+});

From 3a6b95e556a91d1331ce2cf1800561a5835f37f0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 7 Aug 2026 14:54:25 +0000
Subject: [PATCH 2/2] =?UTF-8?q?test(app-shell):=20=E7=BB=99=20go-to-settin?=
 =?UTF-8?q?gs=20=E9=82=A3=E6=9D=A1=E6=96=AD=E8=A8=80=E6=A0=87=E6=B3=A8?=
 =?UTF-8?q?=E5=AE=83=E9=92=89=E7=9A=84=E6=98=AF=E7=8E=B0=E7=8A=B6=E8=80=8C?=
 =?UTF-8?q?=E9=9D=9E=E6=AD=A3=E7=A1=AE=E6=80=A7=20(#3590)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

该断言原本的注释读起来像在背书 `/apps/setup` 这个目标。实测下来裸
`/apps/setup` 正是空态自己的 URL(isSystemRoute 需要 `/system` 段),
零应用部署下这颗按钮同样是死键 —— 已另立 #3590。此处只用于证明
#3573 的改动没碰它,修 #3590 时应一并更新。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
---
 .../src/console/__tests__/AppContent.noAppsCta.test.tsx   | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/app-shell/src/console/__tests__/AppContent.noAppsCta.test.tsx b/packages/app-shell/src/console/__tests__/AppContent.noAppsCta.test.tsx
index 33334be67f..a6cf722100 100644
--- a/packages/app-shell/src/console/__tests__/AppContent.noAppsCta.test.tsx
+++ b/packages/app-shell/src/console/__tests__/AppContent.noAppsCta.test.tsx
@@ -204,9 +204,13 @@ describe('AppContent — no-apps empty state CTA (objectui#3573)', () => {
     fireEvent.click(await screen.findByTestId('go-to-settings-btn'));
 
     expect(pathname()).toBe('/apps/setup');
-    // Still the zero-app deployment, so the same empty state renders there.
-    expect(await screen.findByTestId('create-first-app-btn')).toBeInTheDocument();
     expect(screen.queryByTestId('root-landing')).not.toBeInTheDocument();
+    // NB: this asserts CURRENT behaviour, it does not bless it. `/apps/setup`
+    // bare IS this empty state's own URL (`isSystemRoute` needs a `/system`
+    // segment), so on a zero-app deployment this sibling CTA is a no-op loop —
+    // filed separately as #3590. Kept here only to prove the #3573 fix did not
+    // touch it; update this expectation together with #3590.
+    expect(await screen.findByTestId('create-first-app-btn')).toBeInTheDocument();
   });
 
   it('MEASUREMENT: a non-pseudo /apps/:appName URL never reaches this empty state', async () => {