@nextclaw/ui 0.12.11 → 0.12.13

package/src/features/system-status/managers/system-status.manager.test.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import type { BootstrapStatusView } from '@/api/types';
+import type { BootstrapStatusView } from '@/shared/lib/api';
 import { appQueryClient } from '@/app-query-client';
-import { t } from '@/lib/i18n';
+import { t } from '@/shared/lib/i18n';
 import {
   isTransientRuntimeConnectionErrorMessage,
   systemStatusManager,
@@ -98,6 +98,19 @@ describe('systemStatusManager', () => {
     expect(refetchQueriesSpy).toHaveBeenCalledWith({ type: 'active' });
   });
 
+  it('keeps the last ready bootstrap status while recovering so websocket reopen can restore readiness', () => {
+    systemStatusManager.reportBootstrapStatus(readyBootstrapStatus);
+    systemStatusManager.handleConnectionInterrupted('websocket error');
+
+    expect(useSystemStatusStore.getState().state.bootstrapStatus).toEqual(
+      readyBootstrapStatus
+    );
+
+    systemStatusManager.handleConnectionRestored();
+
+    expect(useSystemStatusStore.getState().state.lifecyclePhase).toBe('ready');
+  });
+
   it('marks recovery as stalled after the timeout window elapses', async () => {
     systemStatusManager.reportBootstrapStatus(readyBootstrapStatus);
     systemStatusManager.handleConnectionInterrupted('websocket error');
@@ -131,6 +144,19 @@ describe('systemStatusManager', () => {
     ).toBeNull();
   });
 
+  it('restores readiness from stalled once the realtime connection reopens', async () => {
+    systemStatusManager.reportBootstrapStatus(readyBootstrapStatus);
+    systemStatusManager.handleConnectionInterrupted('websocket error');
+
+    await vi.advanceTimersByTimeAsync(30_000);
+
+    expect(useSystemStatusStore.getState().state.lifecyclePhase).toBe('stalled');
+
+    systemStatusManager.handleConnectionRestored();
+
+    expect(useSystemStatusStore.getState().state.lifecyclePhase).toBe('ready');
+  });
+
   it('keeps only transport-level failures in the recovery flow', () => {
     expect(isTransientRuntimeConnectionErrorMessage('Failed to fetch')).toBe(
       true

package/src/features/system-status/managers/system-status.manager.ts

@@ -1,18 +1,18 @@
-import type { BootstrapStatusView } from '@/api/types';
+import type { BootstrapStatusView } from '@/shared/lib/api';
 import {
   fetchRuntimeControl,
   restartRuntimeService,
   startRuntimeService,
   stopRuntimeService,
-} from '@/api/runtime-control';
+} from '@/shared/lib/api';
 import type {
   RuntimeControlAction,
   RuntimeControlActionResult,
   RuntimeControlView,
-} from '@/api/runtime-control.types';
+} from '@/shared/lib/api';
 import { appQueryClient } from '@/app-query-client';
 import type { NextClawDesktopBridge } from '@/platforms/desktop';
-import { t } from '@/lib/i18n';
+import { t } from '@/shared/lib/i18n';
 import {
   buildActiveSystemActionState,
   resolveChatRuntimeMessage,
@@ -347,9 +347,7 @@ export class SystemStatusManager {
       lifecyclePhase:
         state.lifecyclePhase === 'stalled' ? 'stalled' : 'recovering',
       recoveryStartedAt: state.recoveryStartedAt ?? Date.now(),
-      bootstrapStatus:
-        bootstrapStatus ??
-        (state.lifecyclePhase === 'ready' ? null : state.bootstrapStatus),
+      bootstrapStatus: bootstrapStatus ?? state.bootstrapStatus,
       lastError: errorMessage?.trim() || state.lastError,
       lastTransportError: errorMessage?.trim() || state.lastTransportError,
     });

package/src/features/system-status/pages/runtime-config-page.test.tsx

@@ -0,0 +1,140 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { RuntimeConfig } from '@/features/system-status/pages/runtime-config-page';
+import { setLanguage } from '@/shared/lib/i18n';
+
+const mocks = vi.hoisted(() => ({
+  mutate: vi.fn(),
+  useConfigResult: null as unknown as {
+    data: Record<string, unknown> | null;
+    isLoading: boolean;
+  },
+  useConfigSchemaResult: null as unknown as {
+    data: Record<string, unknown> | null;
+  }
+}));
+
+vi.mock('@/shared/hooks/use-config', () => ({
+  useConfig: () => mocks.useConfigResult,
+  useConfigSchema: () => mocks.useConfigSchemaResult,
+  useUpdateRuntime: () => ({
+    mutate: mocks.mutate,
+    isPending: false
+  })
+}));
+
+describe('RuntimeConfig', () => {
+  beforeEach(() => {
+    setLanguage('en');
+    mocks.mutate.mockReset();
+    mocks.useConfigResult = {
+      isLoading: false,
+      data: {
+        agents: {
+          defaults: {
+            model: 'gpt-4.1',
+            contextTokens: 120000,
+            engine: 'native'
+          },
+          list: [
+            {
+              id: 'main',
+              default: true,
+              workspace: '/tmp/demo',
+              model: 'gpt-4.1',
+              runtime: 'native'
+            }
+          ],
+          runtimes: {
+            entries: {
+              hermes: {
+                enabled: true,
+                label: 'Hermes',
+                type: 'narp-stdio',
+                config: {
+                  command: 'npx',
+                  args: ['acp']
+                }
+              }
+            }
+          }
+        },
+        bindings: [
+          {
+            agentId: 'main',
+            match: {
+              channel: 'discord'
+            }
+          }
+        ],
+        session: {
+          dmScope: 'per-peer'
+        }
+      }
+    };
+    mocks.useConfigSchemaResult = {
+      data: {
+        uiHints: {}
+      }
+    };
+  });
+
+  it('saves the migrated runtime page through the system-status feature root', async () => {
+    const user = userEvent.setup();
+
+    render(<RuntimeConfig />);
+
+    expect(screen.getByText('Save Runtime Settings')).toBeTruthy();
+    expect(screen.getByPlaceholderText('Default runtime (e.g. native or codex)')).toBeTruthy();
+    expect(screen.getByDisplayValue('Hermes')).toBeTruthy();
+
+    await user.clear(screen.getByPlaceholderText('Default runtime (e.g. native or codex)'));
+    await user.type(screen.getByPlaceholderText('Default runtime (e.g. native or codex)'), '  hermes  ');
+    await user.click(screen.getByRole('button', { name: 'Save Runtime Settings' }));
+
+    expect(mocks.mutate).toHaveBeenCalledWith({
+      data: {
+        agents: {
+          defaults: {
+            contextTokens: 120000,
+            engine: 'hermes'
+          },
+          list: [
+            {
+              id: 'main',
+              default: true,
+              workspace: '/tmp/demo',
+              model: 'gpt-4.1',
+              engine: 'native'
+            }
+          ],
+          runtimes: {
+            entries: {
+              hermes: {
+                enabled: true,
+                label: 'Hermes',
+                type: 'narp-stdio',
+                config: {
+                  command: 'npx',
+                  args: ['acp']
+                }
+              }
+            }
+          }
+        },
+        bindings: [
+          {
+            agentId: 'main',
+            match: {
+              channel: 'discord'
+            }
+          }
+        ],
+        session: {
+          dmScope: 'per-peer'
+        }
+      }
+    });
+  });
+});

package/src/features/system-status/pages/runtime-config-page.tsx

@@ -0,0 +1,15 @@
+import { useConfig, useConfigSchema, useUpdateRuntime } from '@/shared/hooks/use-config';
+import { RuntimeConfigEditor } from '@/features/system-status/components/config/runtime-config-editor';
+import { t } from '@/shared/lib/i18n';
+
+export function RuntimeConfig() {
+  const { data: config, isLoading } = useConfig();
+  const { data: schema } = useConfigSchema();
+  const updateRuntime = useUpdateRuntime();
+
+  if (isLoading || !config) {
+    return <div className="p-8 text-gray-400">{t('runtimeLoading')}</div>;
+  }
+
+  return <RuntimeConfigEditor config={config} uiHints={schema?.uiHints} updateRuntime={updateRuntime} />;
+}

package/src/features/system-status/types/system-status.types.ts

@@ -1,10 +1,10 @@
-import type { BootstrapStatusView } from '@/api/types';
+import type { BootstrapStatusView } from '@/shared/lib/api';
 import type {
   RuntimeControlAction,
   RuntimeControlView,
   RuntimeLifecycleState,
   RuntimeServiceState,
-} from '@/api/runtime-control.types';
+} from '@/shared/lib/api';
 
 export type SystemStatusLifecyclePhase =
   | 'cold-starting'

package/src/features/system-status/utils/runtime-config-agent.utils.ts

@@ -0,0 +1,152 @@
+import type { AgentBindingView, AgentProfileView, ConfigView, RuntimeConfigUpdate, RuntimeEntryView } from '@/shared/lib/api';
+import { t } from '@/shared/lib/i18n';
+
+export type DmScope = 'main' | 'per-peer' | 'per-channel-peer' | 'per-account-channel-peer';
+export type PeerKind = '' | 'direct' | 'group' | 'channel';
+export type RuntimeEntryDraft = RuntimeEntryView & { id: string; configText: string };
+export type RuntimeConfigEditorState = { agents: AgentProfileView[]; bindings: AgentBindingView[]; runtimeEntries: RuntimeEntryDraft[]; dmScope: DmScope; defaultContextTokens: number; defaultEngine: string };
+
+const DEFAULT_NARP_STDIO_ENTRY_CONFIG = {
+  wireDialect: 'acp',
+  processScope: 'per-session',
+  command: '',
+  args: ['acp'],
+  env: {},
+  cwd: '',
+  startupTimeoutMs: 8000,
+  probeTimeoutMs: 3000,
+  requestTimeoutMs: 120000
+};
+
+export function createEmptyRuntimeAgent(): AgentProfileView {
+  return { id: '', default: false, workspace: '', model: '', runtime: '', contextTokens: undefined, maxToolIterations: undefined };
+}
+
+export function createEmptyRuntimeBinding(): AgentBindingView {
+  return { agentId: '', match: { channel: '', accountId: '' } };
+}
+
+export function createEmptyRuntimeEntry(): RuntimeEntryDraft {
+  return { id: '', enabled: true, label: '', type: 'narp-stdio', config: DEFAULT_NARP_STDIO_ENTRY_CONFIG, configText: JSON.stringify(DEFAULT_NARP_STDIO_ENTRY_CONFIG, null, 2) };
+}
+
+export function hydrateRuntimeAgent(agent: AgentProfileView): AgentProfileView {
+  return { id: agent.id ?? '', default: Boolean(agent.default), displayName: agent.displayName ?? '', description: agent.description ?? '', avatar: agent.avatar ?? '', workspace: agent.workspace ?? '', model: agent.model ?? '', runtime: agent.runtime ?? agent.engine ?? '', contextTokens: agent.contextTokens, maxToolIterations: agent.maxToolIterations };
+}
+
+export function hydrateRuntimeBinding(binding: AgentBindingView): AgentBindingView {
+  return {
+    agentId: binding.agentId ?? '',
+    match: {
+      channel: binding.match?.channel ?? '',
+      accountId: binding.match?.accountId ?? '',
+      peer: binding.match?.peer ? { kind: binding.match.peer.kind, id: binding.match.peer.id } : undefined
+    }
+  };
+}
+
+export function parseOptionalInt(value: string): number | undefined {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const parsed = Number.parseInt(trimmed, 10);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+export function createRuntimeConfigEditorState(config: ConfigView): RuntimeConfigEditorState {
+  return {
+    agents: (config.agents.list ?? []).map(hydrateRuntimeAgent),
+    bindings: (config.bindings ?? []).map(hydrateRuntimeBinding),
+    runtimeEntries: Object.entries(config.agents.runtimes?.entries ?? {}).map(([id, entry]) => ({ id, enabled: entry.enabled !== false, label: entry.label ?? '', type: entry.type, config: entry.config ?? {}, configText: JSON.stringify(entry.config ?? {}, null, 2) })),
+    dmScope: (config.session?.dmScope as DmScope) ?? 'per-channel-peer',
+    defaultContextTokens: config.agents.defaults.contextTokens ?? 200000,
+    defaultEngine: config.agents.defaults.engine ?? 'native'
+  };
+}
+
+export function toPersistedRuntimeAgent(agent: AgentProfileView): AgentProfileView {
+  const normalized: AgentProfileView = { id: agent.id.trim() };
+  if (agent.default) normalized.default = true;
+  if (agent.displayName?.trim()) normalized.displayName = agent.displayName.trim();
+  if (agent.description?.trim()) normalized.description = agent.description.trim();
+  if (agent.avatar?.trim()) normalized.avatar = agent.avatar.trim();
+  if (agent.workspace?.trim()) normalized.workspace = agent.workspace.trim();
+  if (agent.model?.trim()) normalized.model = agent.model.trim();
+  const runtime = agent.runtime?.trim() ?? agent.engine?.trim();
+  if (runtime) normalized.engine = runtime;
+  if (typeof agent.contextTokens === 'number') normalized.contextTokens = Math.max(1000, agent.contextTokens);
+  if (typeof agent.maxToolIterations === 'number') normalized.maxToolIterations = agent.maxToolIterations;
+  return normalized;
+}
+
+export function createRuntimeConfigUpdatePayload(input: {
+  agents: AgentProfileView[];
+  bindings: AgentBindingView[];
+  runtimeEntries: RuntimeEntryDraft[];
+  dmScope: DmScope;
+  defaultContextTokens: number;
+  defaultEngine: string;
+  knownAgentIds: Set<string>;
+}): RuntimeConfigUpdate {
+  const normalizedAgents = input.agents.map((agent, index) => {
+    const id = agent.id.trim();
+    if (!id) throw new Error(t('agentIdRequiredError').replace('{index}', String(index)));
+    return toPersistedRuntimeAgent(agent);
+  });
+  const duplicates = normalizedAgents.map((agent) => agent.id).filter((id, index, all) => all.indexOf(id) !== index);
+  if (duplicates.length > 0) {
+    throw new Error(`${t('duplicateAgentId')}: ${duplicates[0]}`);
+  }
+  const normalizedBindings = input.bindings.map((binding, index) => {
+    const agentId = binding.agentId.trim();
+    const channel = binding.match.channel.trim();
+    const accountId = binding.match.accountId?.trim() ?? '';
+    const peerKind = binding.match.peer?.kind;
+    const peerId = binding.match.peer?.id?.trim() ?? '';
+    if (!agentId) throw new Error(t('bindingAgentIdRequired').replace('{index}', String(index)));
+    if (!input.knownAgentIds.has(agentId)) throw new Error(`${t('bindingAgentIdNotFound').replace('{index}', String(index))}: ${agentId}`);
+    if (!channel) throw new Error(t('bindingChannelRequired').replace('{index}', String(index)));
+    const normalized: AgentBindingView = { agentId, match: { channel } };
+    if (accountId) {
+      normalized.match.accountId = accountId;
+    }
+    if (peerKind) {
+      if (!peerId) throw new Error(t('bindingPeerIdRequired').replace('{index}', String(index)));
+      normalized.match.peer = { kind: peerKind, id: peerId };
+    }
+    return normalized;
+  });
+  const normalizedRuntimeEntries = input.runtimeEntries.reduce<Record<string, RuntimeEntryView>>((entries, entry, index) => {
+    const id = entry.id.trim();
+    const type = entry.type.trim();
+    if (!id) throw new Error(`Runtime entry id is required at index ${index}.`);
+    if (!type) throw new Error(`Runtime entry type is required for "${id}".`);
+    if (entries[id]) throw new Error(`Duplicate runtime entry id: ${id}`);
+    const configValue = entry.configText.trim() ? JSON.parse(entry.configText) : {};
+    if (configValue && (typeof configValue !== 'object' || Array.isArray(configValue))) throw new Error(`Runtime entry config for "${id}" must be a JSON object.`);
+    entries[id] = {
+      enabled: entry.enabled !== false,
+      ...(entry.label?.trim() ? { label: entry.label.trim() } : {}),
+      type,
+      config: (configValue as Record<string, unknown>) ?? {}
+    };
+    return entries;
+  }, {});
+  return {
+    agents: {
+      defaults: {
+        contextTokens: Math.max(1000, input.defaultContextTokens),
+        engine: input.defaultEngine.trim() || 'native'
+      },
+      list: normalizedAgents,
+      runtimes: {
+        entries: normalizedRuntimeEntries
+      }
+    },
+    bindings: normalizedBindings,
+    session: {
+      dmScope: input.dmScope
+    }
+  };
+}

package/src/features/system-status/utils/system-status.utils.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { t } from '@/lib/i18n';
+import { t } from '@/shared/lib/i18n';
 import {
   resolveChatRuntimeMessage,
   resolveSystemConnectionStatus,

package/src/features/system-status/utils/system-status.utils.ts

@@ -1,9 +1,9 @@
-import { t } from '@/lib/i18n';
+import { t } from '@/shared/lib/i18n';
 import type {
   RuntimeControlAction,
   RuntimeLifecycleState,
   RuntimeServiceState,
-} from '@/api/runtime-control.types';
+} from '@/shared/lib/api';
 import type {
   RuntimeControlPanelView,
   RuntimeStatusBadgeView,

package/src/index.css

@@ -1,5 +1,5 @@
 /* Import Design System - must be first */
-@import './styles/design-system.css';
+@import './app/styles/design-system.css';
 
 @tailwind base;
 @tailwind components;

package/src/platforms/desktop/components/desktop-app-shell.tsx

@@ -0,0 +1,52 @@
+import { lazy, Suspense } from "react";
+import { isMainWorkspaceRoute } from "@/app/configs/app-navigation.config";
+import { Sidebar } from "@/app/components/layout/sidebar";
+
+const DocBrowser = lazy(async () => ({
+  default: (await import("@/shared/components/doc-browser/doc-browser")).DocBrowser,
+}));
+
+type DesktopAppShellProps = {
+  pathname: string;
+  isDocBrowserOpen: boolean;
+  docBrowserMode: "floating" | "docked";
+  children: React.ReactNode;
+};
+
+export function DesktopAppShell({
+  pathname,
+  isDocBrowserOpen,
+  docBrowserMode,
+  children,
+}: DesktopAppShellProps) {
+  const isMainRoute = isMainWorkspaceRoute(pathname);
+
+  return (
+    <div className="h-screen flex bg-background font-sans text-foreground">
+      {!isMainRoute && <Sidebar mode="settings" />}
+      <div className="flex-1 flex min-w-0 overflow-hidden relative">
+        <div className="flex-1 flex flex-col min-w-0 overflow-hidden">
+          {isMainRoute ? (
+            <div className="flex-1 h-full overflow-hidden">{children}</div>
+          ) : (
+            <main className="flex-1 overflow-auto p-8 pb-16 custom-scrollbar">
+              <div className="mx-auto h-full max-w-6xl animate-fade-in">
+                {children}
+              </div>
+            </main>
+          )}
+        </div>
+        {isDocBrowserOpen && docBrowserMode === "docked" ? (
+          <Suspense fallback={null}>
+            <DocBrowser />
+          </Suspense>
+        ) : null}
+      </div>
+      {isDocBrowserOpen && docBrowserMode === "floating" ? (
+        <Suspense fallback={null}>
+          <DocBrowser />
+        </Suspense>
+      ) : null}
+    </div>
+  );
+}

package/src/platforms/desktop/index.ts

@@ -6,6 +6,7 @@ export {
   desktopUpdateManager,
   DesktopUpdateManager,
 } from './managers/desktop-update.manager';
+export { DesktopAppShell } from './components/desktop-app-shell';
 export { useDesktopPresenceStore } from './stores/desktop-presence.store';
 export { useDesktopUpdateStore } from './stores/desktop-update.store';
 export type {

package/src/platforms/desktop/managers/desktop-presence.manager.ts

@@ -3,7 +3,7 @@ import type {
   NextClawDesktopBridge
 } from '@/platforms/desktop/types/desktop-update.types';
 import { useDesktopPresenceStore } from '@/platforms/desktop/stores/desktop-presence.store';
-import { t } from '@/lib/i18n';
+import { t } from '@/shared/lib/i18n';
 import { toast } from 'sonner';
 
 export class DesktopPresenceManager {

package/src/platforms/desktop/managers/desktop-update.manager.ts

@@ -5,7 +5,7 @@ import type {
   NextClawDesktopBridge
 } from '@/platforms/desktop/types/desktop-update.types';
 import { useDesktopUpdateStore } from '@/platforms/desktop/stores/desktop-update.store';
-import { t } from '@/lib/i18n';
+import { t } from '@/shared/lib/i18n';
 import { toast } from 'sonner';
 
 type DesktopUpdateBusyAction = 'checking' | 'downloading' | 'applying' | 'saving-preferences' | 'switching-channel';

package/src/platforms/desktop/types/desktop-update.types.ts

@@ -44,9 +44,12 @@ export type DesktopPresenceSnapshot = DesktopPresencePreferences & {
   launchAtLoginReason: string | null;
 };
 
+export type DesktopUiLanguagePreference = 'en' | 'zh';
+
 export type NextClawDesktopBridge = {
   platform: string;
   version: string;
+  localePreference?: DesktopUiLanguagePreference | null;
   getUpdateState: () => Promise<DesktopUpdateSnapshot>;
   checkForUpdates: () => Promise<DesktopUpdateSnapshot>;
   downloadUpdate: () => Promise<DesktopUpdateSnapshot>;
@@ -57,5 +60,6 @@ export type NextClawDesktopBridge = {
   restartApp: () => Promise<DesktopRuntimeControlResult>;
   getPresenceState: () => Promise<DesktopPresenceSnapshot>;
   updatePresencePreferences: (preferences: Partial<DesktopPresencePreferences>) => Promise<DesktopPresenceSnapshot>;
+  setLocalePreference?: (language: DesktopUiLanguagePreference | null) => Promise<DesktopUiLanguagePreference | null>;
   onUpdateStateChanged: (listener: (snapshot: DesktopUpdateSnapshot) => void) => () => void;
 };

package/src/platforms/mobile/components/chat-mobile-shell.tsx

@@ -0,0 +1,20 @@
+import { useLocation, useNavigate } from "react-router-dom";
+import { isChatSessionDetailRoute } from "@/app/configs/app-navigation.config";
+import { ChatConversationPanel, ChatSidebar } from "@/features/chat";
+
+export function ChatMobileShell() {
+  const { pathname } = useLocation();
+  const navigate = useNavigate();
+  const isSessionDetailRoute = isChatSessionDetailRoute(pathname);
+
+  if (isSessionDetailRoute) {
+    return (
+      <ChatConversationPanel
+        layoutMode="mobile"
+        onBackToList={() => navigate("/chat")}
+      />
+    );
+  }
+
+  return <ChatSidebar variant="mobile" />;
+}

package/src/platforms/mobile/components/mobile-app-shell.test.tsx

@@ -0,0 +1,42 @@
+import { render, screen } from "@testing-library/react";
+import { MemoryRouter } from "react-router-dom";
+import { describe, expect, it } from "vitest";
+import { I18nProvider } from "@/app/components/i18n-provider";
+import { MobileAppShell } from "@/platforms/mobile/components/mobile-app-shell";
+
+function renderShell(pathname: string) {
+  return render(
+    <I18nProvider>
+      <MemoryRouter initialEntries={[pathname]}>
+        <MobileAppShell pathname={pathname} isDocBrowserOpen={false}>
+          <div>Content</div>
+        </MobileAppShell>
+      </MemoryRouter>
+    </I18nProvider>,
+  );
+}
+
+describe("MobileAppShell", () => {
+  it("shows the bottom navigation on the chat list route", () => {
+    renderShell("/chat");
+
+    expect(screen.getByTestId("mobile-bottom-nav")).toBeTruthy();
+  });
+
+  it("centers primary route titles without reserving back-button spacers", () => {
+    renderShell("/skills");
+
+    const topbar = screen.getByTestId("mobile-topbar");
+    const heading = screen.getByRole("heading", { name: "Skills" });
+
+    expect(heading.className).toContain("text-center");
+    expect(topbar.querySelector('[aria-hidden="true"]')).toBeNull();
+  });
+
+  it("hides the shared mobile chrome on chat session detail routes", () => {
+    renderShell("/chat/demo-session");
+
+    expect(screen.queryByTestId("mobile-bottom-nav")).toBeNull();
+    expect(screen.queryByTestId("mobile-topbar")).toBeNull();
+  });
+});

package/src/platforms/mobile/components/mobile-app-shell.tsx

@@ -0,0 +1,48 @@
+import { lazy, Suspense } from "react";
+import {
+  isChatSessionDetailRoute,
+  isMainWorkspaceRoute,
+} from "@/app/configs/app-navigation.config";
+import { MobileBottomNav } from "@/platforms/mobile/components/mobile-bottom-nav";
+import { MobileTopbar } from "@/platforms/mobile/components/mobile-topbar";
+
+const DocBrowser = lazy(async () => ({
+  default: (await import("@/shared/components/doc-browser/doc-browser")).DocBrowser,
+}));
+
+type MobileAppShellProps = {
+  pathname: string;
+  isDocBrowserOpen: boolean;
+  children: React.ReactNode;
+};
+
+export function MobileAppShell({
+  pathname,
+  isDocBrowserOpen,
+  children,
+}: MobileAppShellProps) {
+  const isMainRoute = isMainWorkspaceRoute(pathname);
+  const showTopbar = !isChatSessionDetailRoute(pathname);
+  const showBottomNav = !isChatSessionDetailRoute(pathname);
+
+  return (
+    <div className="flex h-screen flex-col bg-background font-sans text-foreground">
+      {showTopbar ? <MobileTopbar /> : null}
+      <div className="relative flex-1 min-h-0 overflow-hidden">
+        {isMainRoute ? (
+          <div className="h-full min-h-0 overflow-hidden">{children}</div>
+        ) : (
+          <main className="h-full overflow-auto px-4 py-4 custom-scrollbar">
+            <div className="mx-auto max-w-3xl animate-fade-in">{children}</div>
+          </main>
+        )}
+      </div>
+      {showBottomNav ? <MobileBottomNav /> : null}
+      {isDocBrowserOpen ? (
+        <Suspense fallback={null}>
+          <DocBrowser displayMode="fullscreen" />
+        </Suspense>
+      ) : null}
+    </div>
+  );
+}