From 3ef1d8935fe783f503818777a995d10622821b8c Mon Sep 17 00:00:00 2001
From: Sadiq Ansari <sadiqxansari@gmail.com>
Date: Thu, 13 Aug 2026 16:33:47 +0530
Subject: [PATCH 1/5] refactor(shell): each page owns its header, the way the
 shells expect
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

AppShell hand-rolled one global header for every page, plus an ad-hoc
`#header-actions` teleport target that three pages reached into. Both
MobileShell and DesktopShell already render a PageHeaderTarget above their
scroll region for exactly this: a page declares its own header and it teleports
there. We used neither.

That bypass is what cost every mobile page its last 48px. Our header sat inside
MobileShell's scroll area rather than above it, so the bottom of every page hid
behind the nav bar, and the workaround was a hand-managed flex column. Owning
the header per page removes the class of bug and turns on what the components
already do: a back button, a centred two-line title, tap-the-header to scroll
top, tap-the-active-tab to scroll top.

The pattern is taken from frappe/gameplan, which is where frappe-ui's shell
components were extracted from. Slot names drift between versions — beta.24
takes #left/#right where later releases take #prefix/#suffix — and Vue drops an
unknown named slot silently, so these are written against the installed source
rather than copied from gameplan's templates.

Two things follow from the shell owning the scroll region:

Pages hand it their own scroll boxes behind `sm:` prefixes, which is what makes
tapping the already-active bottom-nav tab scroll to top.

And scroll position is now reset by the router, not by pages remounting. The
shell's scroll div outlives the route, so without it a new page opened wherever
the last one was left. Only a real path change resets — a query-only replace is
the same page and keeps its place.

The mobile header's title also doubles as the section switcher: the bottom bar
holds four tabs, so Servers, Services, Team and the billing pages were otherwise
reachable only by going back to Home first. Home keeps a plain title, since that
page already is the list, and takes the mark on the left instead.

useBreadcrumbs loses its last consumer here and goes with them. ServerFilters comes
along because the servers page now hands it region options grouped by provider,
and a prop type has to move with the thing that passes it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../components/navigation/NavDrawerTitle.vue  | 43 ++++++++
 .../src/components/navigation/Sidebar.vue     | 42 ++++++--
 dashboard/src/components/navigation/list.ts   | 10 +-
 .../src/components/servers/ServerFilters.vue  | 22 +++--
 .../components/settings/forms/TeamForm.vue    | 10 +-
 dashboard/src/components/team/TeamList.vue    | 30 +++++-
 dashboard/src/composables/useBreadcrumbs.ts   | 18 ----
 dashboard/src/composables/useSettings.ts      | 73 ++++++++++----
 dashboard/src/layouts/AppShell.vue            | 66 ++++---------
 dashboard/src/pages/addons/AIInference.vue    | 29 +++++-
 dashboard/src/pages/addons/Page.vue           | 17 +++-
 .../src/pages/billing/BillingOverviewPage.vue | 26 +++--
 .../src/pages/billing/BillingReportsPage.vue  | 33 ++++++-
 dashboard/src/pages/home/HomePage.vue         | 17 ++++
 .../pages/notifications/NotificationsPage.vue | 54 +++++++++--
 dashboard/src/pages/servers/NewServerPage.vue | 43 ++++++--
 dashboard/src/pages/servers/ServersPage.vue   | 88 +++++++++++++----
 .../src/pages/settings/SettingsDetailPage.vue | 67 ++++++++-----
 .../pages/settings/SettingsDialogRoute.vue    | 97 +++++++++++++++++++
 dashboard/src/pages/settings/SettingsPage.vue | 45 +++++++--
 dashboard/src/pages/team/AccessPage.vue       | 32 +++++-
 dashboard/src/pages/team/InvitationsPage.vue  | 16 ++-
 dashboard/src/router/index.ts                 | 38 ++++++--
 23 files changed, 720 insertions(+), 196 deletions(-)
 create mode 100644 dashboard/src/components/navigation/NavDrawerTitle.vue
 delete mode 100644 dashboard/src/composables/useBreadcrumbs.ts
 create mode 100644 dashboard/src/pages/settings/SettingsDialogRoute.vue

diff --git a/dashboard/src/components/navigation/NavDrawerTitle.vue b/dashboard/src/components/navigation/NavDrawerTitle.vue
new file mode 100644
index 00000000..aaaf7b73
--- /dev/null
+++ b/dashboard/src/components/navigation/NavDrawerTitle.vue
@@ -0,0 +1,43 @@
+<script setup lang="ts">
+import { BottomSheet, PageHeaderMobileTitle } from 'frappe-ui'
+import { ref } from 'vue'
+import Sidebar from '@/components/navigation/Sidebar.vue'
+
+// On mobile the header's title doubles as the section switcher. The bottom bar
+// only holds four tabs, so everything else the drawer lists — Servers, Services,
+// Team, the billing pages — would otherwise cost a trip back to Home. Home
+// itself doesn't use this: that page already *is* the list.
+//
+// The sheet lives here rather than in the shell so it unmounts with the page,
+// which is also what dismisses it once you've picked somewhere to go.
+defineProps<{ title: string }>()
+
+const open = ref(false)
+</script>
+
+<template>
+	<!-- PageHeaderMobileTitle, not a bare button: the header's <h1> clamps with
+	     -webkit-line-clamp, which counts line boxes — an inline-flex child is one
+	     atomic box, so a long title would never clamp and would instead grow past
+	     the 52px header and get hard-clipped. This carries the min-w-0/truncate
+	     that makes it ellipsise instead. -->
+	<PageHeaderMobileTitle>
+		<button
+			class="inline-flex min-w-0 items-center gap-1"
+			aria-haspopup="dialog"
+			:aria-expanded="open"
+			@click="open = true"
+		>
+			<span class="truncate">{{ title }}</span>
+			<span
+				class="lucide-chevron-down size-4 shrink-0 text-ink-gray-5"
+				aria-hidden="true"
+			/>
+		</button>
+	</PageHeaderMobileTitle>
+
+	<!-- Named so it doesn't announce as the generic "Bottom sheet". -->
+	<BottomSheet v-model:open="open" title="Go to">
+		<Sidebar is-mobile class="p-4" />
+	</BottomSheet>
+</template>
diff --git a/dashboard/src/components/navigation/Sidebar.vue b/dashboard/src/components/navigation/Sidebar.vue
index 2e7959e4..6be73bc8 100644
--- a/dashboard/src/components/navigation/Sidebar.vue
+++ b/dashboard/src/components/navigation/Sidebar.vue
@@ -7,7 +7,7 @@ import {
 	SidebarItem,
 	SidebarLabel,
 } from 'frappe-ui'
-import { onScopeDispose, ref, watch } from 'vue'
+import { computed, onScopeDispose, ref, watch } from 'vue'
 import { useRoute } from 'vue-router'
 import frappeCloudLogo from '@/assets/fc-logo.svg'
 import { useAppMenu } from '@/composables/useAppMenu'
@@ -17,6 +17,21 @@ import { sidebarSections } from './list'
 
 const props = defineProps<{ isMobile?: boolean }>()
 
+// Search and Notifications are their own tabs in the mobile bottom bar, so the
+// drawer drops them and shows only what the bar can't reach. A section left
+// empty by that drops out with them.
+const sections = computed(() =>
+	sidebarSections.value
+		.map((section) => ({
+			...section,
+			items: section.items.filter(
+				(item) =>
+					item.condition !== false && !(props.isMobile && item.hideOnMobile),
+			),
+		}))
+		.filter((section) => section.items.length > 0),
+)
+
 const { activeTeamLabel } = useSession()
 const { currentUser, headerMenuItems, footerMenuItems } = useAppMenu()
 const { profile } = useMyProfile()
@@ -80,10 +95,7 @@ onScopeDispose(() => cancelAnimationFrame(edgeRaf))
 		/>
 
 		<nav class="flex-1 overflow-y-auto px-2 pt-2">
-			<template
-				v-for="section in sidebarSections"
-				:key="section.label || 'main'"
-			>
+			<template v-for="section in sections" :key="section.label || 'main'">
 				<SidebarLabel
 					v-if="section.label"
 					class="mt-2"
@@ -101,17 +113,31 @@ onScopeDispose(() => cancelAnimationFrame(edgeRaf))
 				<template
 					v-if="!section.collapsible || !collapsedSections[section.label]"
 				>
+					<!-- In the mobile drawer these rows are the primary nav and get
+					     touched, not clicked: 16px labels, a proportionally larger
+					     icon, and a row tall enough to hit. The desktop rail keeps
+					     its denser sizing. -->
 					<SidebarItem
-						v-for="item in section.items.filter((i) => i.condition !== false)"
+						v-for="item in section.items"
 						:key="item.label"
 						:icon="item.icon"
 						:to="item.to"
 						:onclick="item.onClick"
 						class="mb-0.5"
-						:class="item.class"
+						:class="[item.class, isMobile ? '!h-10' : '']"
 						:active="!!item.to && item.to === route.path"
 					>
-						<span class="truncate text-sm">{{ item.label }}</span>
+						<template v-if="isMobile" #prefix>
+							<span
+								class="size-5 shrink-0 text-ink-gray-6"
+								:class="item.icon"
+								aria-hidden="true"
+							/>
+						</template>
+						<!-- text-lg is 16px in this preset; text-base is 14px. -->
+						<span class="truncate" :class="isMobile ? 'text-lg' : 'text-sm'">
+							{{ item.label }}
+						</span>
 					</SidebarItem>
 				</template>
 			</template>
diff --git a/dashboard/src/components/navigation/list.ts b/dashboard/src/components/navigation/list.ts
index c8835ec4..fd7ceae5 100644
--- a/dashboard/src/components/navigation/list.ts
+++ b/dashboard/src/components/navigation/list.ts
@@ -10,6 +10,8 @@ type SidebarItem = {
 	condition?: boolean
 	class?: string
 	onClick?: () => void
+	/** Already a tab in the mobile bottom bar — repeating it in the drawer is noise. */
+	hideOnMobile?: boolean
 }
 
 type SidebarSection = {
@@ -26,13 +28,19 @@ export const sidebarSections = computed<SidebarSection[]>(() => {
 		{
 			label: '',
 			items: [
-				{ label: 'Search', icon: 'lucide-search', onClick: openSearch },
+				{
+					label: 'Search',
+					icon: 'lucide-search',
+					onClick: openSearch,
+					hideOnMobile: true,
+				},
 				{
 					label: 'Notifications',
 					icon: 'lucide-bell',
 					to: '/notifications',
 					condition: isMember.value,
 					class: 'mb-3',
+					hideOnMobile: true,
 				},
 			],
 		},
diff --git a/dashboard/src/components/servers/ServerFilters.vue b/dashboard/src/components/servers/ServerFilters.vue
index 2a9da9fb..ff09c203 100644
--- a/dashboard/src/components/servers/ServerFilters.vue
+++ b/dashboard/src/components/servers/ServerFilters.vue
@@ -1,12 +1,17 @@
 <script setup lang="ts">
-import { Combobox } from 'frappe-ui'
+import { Combobox, type ComboboxOption } from 'frappe-ui'
 import type { ServerVisual } from '@/lib/serverMap'
 
 // The top-right status + region filters over the map. Both scope the map pins
 // and the panel rows; the page owns the option lists and the resolved filters.
+//
+// Combobox in its default `input` trigger: typing happens in the trigger
+// itself, so the popover below is nothing but the option list — no search row
+// stacked inside it, and the list opens under the input rather than over it.
 defineProps<{
 	statusOptions: { label: string; value: string; dot?: string }[]
-	regionOptions: { label: string; value: string }[]
+	/** Grouped by provider, so this is Combobox's option union, not a flat list. */
+	regionOptions: ComboboxOption[]
 }>()
 
 const statusFilter = defineModel<ServerVisual['key'] | ''>('statusFilter', {
@@ -18,15 +23,19 @@ const regionSelection = defineModel<string>('regionSelection', {
 </script>
 
 <template>
-	<div class="absolute right-4 top-4 flex items-center gap-2">
+	<!-- Side by side these two run past the right edge of a phone, and into the
+	     list pill on the left. Stack them under each other until there's room. -->
+	<div
+		class="absolute right-4 top-4 flex flex-col items-end gap-2 sm:flex-row sm:items-center"
+	>
 		<Combobox
 			v-model="statusFilter"
-			trigger="button"
 			variant="outline"
 			size="md"
+			align="end"
+			class="w-40"
 			:options="statusOptions"
 		>
-			<!-- Button mode reuses #item-prefix on the trigger when a value is selected. -->
 			<template #item-prefix="{ item }">
 				<span
 					class="size-2 shrink-0 rounded-full transition-colors"
@@ -36,9 +45,10 @@ const regionSelection = defineModel<string>('regionSelection', {
 		</Combobox>
 		<Combobox
 			v-model="regionSelection"
-			trigger="button"
 			variant="outline"
 			size="md"
+			align="end"
+			class="w-40"
 			:options="regionOptions"
 		/>
 	</div>
diff --git a/dashboard/src/components/settings/forms/TeamForm.vue b/dashboard/src/components/settings/forms/TeamForm.vue
index d814aeeb..8f9d3985 100644
--- a/dashboard/src/components/settings/forms/TeamForm.vue
+++ b/dashboard/src/components/settings/forms/TeamForm.vue
@@ -1,16 +1,14 @@
 <script setup lang="ts">
 import { Avatar, Button, Dialog, FormControl } from 'frappe-ui'
 import { computed, ref, watch } from 'vue'
-import { useRouter } from 'vue-router'
 import { useCapabilities } from '@/composables/useCapabilities'
 import { useSession } from '@/composables/useSession'
-import { settingsOpen } from '@/composables/useSettings'
+import { closeSettingsTo } from '@/composables/useSettings'
 import { useTeamSettings } from '@/composables/useTeamSettings'
 
 // The active team's own settings — rename (team:edit) and the delete row
 // (team:delete). Ownership transfer is NOT here: it lives on the member's ⋯
 // menu in the roster, where the new owner is picked in context.
-const router = useRouter()
 const { activeTeamLabel, activeTeamLogo } = useSession()
 const { saving, rename, deleteTeam } = useTeamSettings()
 const { canEditTeam, canDeleteTeam } = useCapabilities()
@@ -52,8 +50,10 @@ const deleteOptions = computed(() => ({
 async function onDelete(): Promise<void> {
 	if (await deleteTeam()) {
 		confirmDelete.value = false
-		settingsOpen.value = false
-		router.push('/servers')
+		// Not "close, then navigate": closing is what sends you back to wherever
+		// settings were opened from, and that replace would supersede a push
+		// issued beside it — landing you on the deleted team's page.
+		closeSettingsTo('/servers')
 	}
 }
 </script>
diff --git a/dashboard/src/components/team/TeamList.vue b/dashboard/src/components/team/TeamList.vue
index 8c5c8d49..9bab928c 100644
--- a/dashboard/src/components/team/TeamList.vue
+++ b/dashboard/src/components/team/TeamList.vue
@@ -1,8 +1,14 @@
 <script setup lang="ts">
-import { Avatar, Button, TextInput } from 'frappe-ui'
+import {
+	Avatar,
+	Button,
+	vOnOutsideClick,
+	TextInput,
+} from 'frappe-ui'
 import { computed, ref, watch } from 'vue'
 import { useAuth } from '@/composables/useAuth'
 import { useSession } from '@/composables/useSession'
+import { forgetSettingsOrigin } from '@/composables/useSettings'
 import type { Team } from '@/types/api'
 
 // Every team you belong to, one row each: name, then your standing in it, so
@@ -44,6 +50,10 @@ function selectTeam(team: Team): void {
 
 function switchTo(team: Team): void {
 	setActiveTeam(team.name)
+	// This list lives inside settings, so closing them would otherwise land on
+	// whatever page the old team was on — a server, an invoice — which the new
+	// team may not be able to read at all.
+	forgetSettingsOrigin()
 	selected.value = null
 	emit('switched', team)
 }
@@ -63,8 +73,16 @@ function switchTo(team: Team): void {
 		</TextInput>
 
 		<!-- Negative margin + matching padding so the scrollbar rides the outer
-		     edge instead of floating inside the content column. -->
-		<div class="-mr-4 max-h-80 space-y-1 overflow-y-auto pr-4 sm:-mr-6 sm:pr-6">
+		     edge instead of floating inside the content column.
+
+		     A selection is an offer, not a mode: clicking away withdraws it the
+		     same way clicking the row again does. Without this the "Switch team"
+		     button sat there indefinitely, since nothing outside the list cleared
+		     it. -->
+		<div
+			v-on-outside-click="() => (selected = null)"
+			class="-mr-4 max-h-80 space-y-1 overflow-y-auto pr-4 sm:-mr-6 sm:pr-6"
+		>
 			<!-- The row is a div holding a button, not a button holding a button:
 			     the name area selects, the action beside it switches. -->
 			<div
@@ -103,14 +121,18 @@ function switchTo(team: Team): void {
 					class="lucide-check size-4 shrink-0 text-ink-gray-7"
 					aria-hidden="true"
 				/>
+				<!-- `label` stays the full "Switch to <team>" for screen readers —
+				     the row it belongs to isn't announced with it. The visible text
+				     is just the verb; the row already names the team. -->
 				<Button
 					v-else-if="team.name === selected"
 					variant="solid"
+					icon-left="lucide-repeat"
 					:label="`Switch to ${team.label}`"
 					class="shrink-0"
 					@click="switchTo(team)"
 				>
-					Switch team
+					Switch
 				</Button>
 			</div>
 
diff --git a/dashboard/src/composables/useBreadcrumbs.ts b/dashboard/src/composables/useBreadcrumbs.ts
deleted file mode 100644
index ccbf67c4..00000000
--- a/dashboard/src/composables/useBreadcrumbs.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import type { BreadcrumbsProps } from 'frappe-ui'
-import { ref } from 'vue'
-
-type BreadcrumbItem = BreadcrumbsProps['items'][number]
-
-const items = ref<BreadcrumbItem[] | null>(null)
-
-export function useBreadcrumbs() {
-	return {
-		items,
-		setBreadcrumbs: (value: BreadcrumbItem[]) => {
-			items.value = value
-		},
-		resetBreadcrumbs: () => {
-			items.value = null
-		},
-	}
-}
diff --git a/dashboard/src/composables/useSettings.ts b/dashboard/src/composables/useSettings.ts
index a52bad10..e3174e1b 100644
--- a/dashboard/src/composables/useSettings.ts
+++ b/dashboard/src/composables/useSettings.ts
@@ -26,12 +26,14 @@ const TeamForm = defineAsyncComponent(
 // team's settings. Callers name the tab they want and this decides how to show
 // it — a dialog on desktop, a real page on mobile, where a modal over a 375px
 // screen is just a page with the edges shaved off.
+// These double as URL slugs, so they read as addresses rather than internals:
+// 'team-settings', not 'team', which would sit confusingly beside 'teams'.
 export type SettingsTab =
 	| 'profile'
 	| 'notifications'
 	| 'appearance'
 	| 'teams'
-	| 'team'
+	| 'team-settings'
 
 export interface SettingsTabDef {
 	value: SettingsTab
@@ -93,7 +95,7 @@ export const SETTINGS_TABS: SettingsTabDef[] = [
 		component: TeamsForm,
 	},
 	{
-		value: 'team',
+		value: 'team-settings',
 		group: 'Team',
 		label: 'Team settings',
 		icon: 'lucide-building-2',
@@ -107,31 +109,66 @@ export const SETTINGS_TABS: SettingsTabDef[] = [
 export const settingsOpen = ref(false)
 export const settingsTab = ref<SettingsTab>('profile')
 
+// Each presentation owns its own URL space, so a settings address is never
+// ambiguous about which one it means: /settings/:tab is the desktop dialog,
+// /mobile-settings/:tab is the page stack. Both name the tab, so a reload or a
+// shared link reopens exactly where it left off.
+export const SETTINGS_BASE = '/settings'
+export const MOBILE_SETTINGS_BASE = '/mobile-settings'
+
 // A one-shot read rather than useIsMobile(): openSettings runs from click
 // handlers outside any component scope, where a media-query listener would have
 // no scope to be torn down with. Same breakpoint, so both agree on what mobile
-// means — the dialog only mounts when useIsMobile says desktop, and routing
-// here on a different threshold would strand the caller on a page with no
-// dialog behind it.
+// means.
 const onMobile = (): boolean =>
 	window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`).matches
 
+export const settingsPath = (tab: SettingsTab): string =>
+	`${onMobile() ? MOBILE_SETTINGS_BASE : SETTINGS_BASE}/${tab}`
+
+// The dialog covers the page it opened over, and the URL no longer records
+// that page — so remember it here and land back on it when settings close.
+let returnTo: string | null = null
+
+const inSettings = (path: string): boolean =>
+	path.startsWith(SETTINGS_BASE) || path.startsWith(MOBILE_SETTINGS_BASE)
+
 export const openSettings = (tab: SettingsTab = 'profile'): void => {
-	if (onMobile()) {
-		router.push(`/settings/${tab}`)
-		return
-	}
-	settingsTab.value = tab
-	settingsOpen.value = true
+	const path = router.currentRoute.value.path
+	if (!inSettings(path)) returnTo = path
+	router.push(settingsPath(tab))
+}
+
+/** Leave the desktop dialog for wherever it was opened from. */
+export const returnFromSettings = (): void => {
+	router.replace(returnTo ?? '/servers')
 }
 
-// Leave settings, whichever presentation you're in: the dialog closes, and a
-// mobile tab page falls back to the list. Callers that navigate somewhere else
-// themselves (deleting a team lands on Servers) should set `settingsOpen`
-// directly instead, or the two pushes race in the same tick.
+// Leave settings, whichever presentation you're in: a mobile tab page falls
+// back to the hub, and the dialog closes — which the route watches, so the
+// navigation back out happens there rather than racing with this.
 export const closeSettings = (): void => {
-	settingsOpen.value = false
-	if (router.currentRoute.value.path.startsWith('/settings/')) {
-		router.replace('/settings')
+	if (router.currentRoute.value.path.startsWith(`${MOBILE_SETTINGS_BASE}/`)) {
+		router.replace(MOBILE_SETTINGS_BASE)
+		return
 	}
+	settingsOpen.value = false
+}
+
+// Leave settings for somewhere specific instead of back where you came from —
+// deleting a team lands on Servers, not on the team page the pencil opened
+// settings from. Callers must go through this rather than closing and pushing
+// themselves: closing is what triggers the trip back to `returnTo`, and that
+// replace supersedes a push issued alongside it, so the caller's destination
+// silently loses.
+export const closeSettingsTo = (path: string): void => {
+	returnTo = path
+	closeSettings()
+}
+
+// A team switch invalidates wherever settings were opened from: that page
+// belongs to the old team and may not even be readable under the new one.
+// Home is always safe.
+export const forgetSettingsOrigin = (): void => {
+	returnTo = null
 }
diff --git a/dashboard/src/layouts/AppShell.vue b/dashboard/src/layouts/AppShell.vue
index 5f78adad..ece3fe72 100644
--- a/dashboard/src/layouts/AppShell.vue
+++ b/dashboard/src/layouts/AppShell.vue
@@ -1,18 +1,15 @@
 <script setup lang="ts">
 import {
-	BottomSheet,
-	Breadcrumbs,
 	DesktopShell,
 	MobileNav,
 	MobileNavItem,
 	MobileShell,
 	ToastProvider,
 } from 'frappe-ui'
-import { computed, defineAsyncComponent, ref, watch } from 'vue'
+import { defineAsyncComponent, ref, watch } from 'vue'
 import { useRoute } from 'vue-router'
 import Sidebar from '@/components/navigation/Sidebar.vue'
 import SettingsModal from '@/components/settings/SettingsModal.vue'
-import { useBreadcrumbs } from '@/composables/useBreadcrumbs'
 import { useIsMobile } from '@/composables/useIsMobile'
 import { useNotificationsRealtime } from '@/composables/useNotifications'
 import {
@@ -38,38 +35,16 @@ watch(searchOpen, (isOpen) => {
 })
 
 const route = useRoute()
-const { items, resetBreadcrumbs } = useBreadcrumbs()
 const isMobile = useIsMobile()
-
-const mobileNavDrawer = ref(false)
-watch(
-	() => route.name,
-	() => {
-		resetBreadcrumbs()
-		mobileNavDrawer.value = false
-	},
-)
-
-const breadcrumbs = computed(
-	() => items.value ?? [{ label: (route.meta.title as string) ?? '' }],
-)
 </script>
 
 <template>
+	<!-- Neither shell renders a header of its own: both expose a PageHeaderTarget
+	     above their scroll region, and each page teleports its own header there.
+	     Owning one here instead put it *inside* MobileShell's scroll area, which
+	     is what cost every mobile page the bottom 48px behind the nav bar. -->
 	<MobileShell v-if="isMobile">
-		<header
-			class="sticky top-0 z-10 flex h-12 shrink-0 items-center justify-between gap-3 border-b border-outline-gray-1 bg-surface-base px-4"
-		>
-			<button class="flex items-center gap-1" @click="mobileNavDrawer = true">
-				<Breadcrumbs :items="breadcrumbs" />
-				<span class="lucide-chevron-down size-4 text-ink-gray-5" />
-			</button>
-			<div id="header-actions" class="flex shrink-0 items-center gap-2" />
-		</header>
-
-		<main class="h-full overflow-hidden">
-			<router-view />
-		</main>
+		<router-view />
 
 		<template #nav>
 			<MobileNav>
@@ -88,37 +63,36 @@ const breadcrumbs = computed(
 					label="Notifications"
 					icon="lucide-bell"
 					to="/notifications"
-					:active="route.name =='Notifications' "
+					:active="route.name === 'Notifications'"
+				/>
+				<!-- This bar only exists on mobile, so it goes straight to the hub.
+				     Pointing at /settings would bounce through the dialog route and
+				     land on a tab page instead of the list. -->
+				<MobileNavItem
+					label="Settings"
+					icon="lucide-settings"
+					to="/mobile-settings"
+					:active="String(route.name ?? '').startsWith('MobileSettings')"
 				/>
-				<MobileNavItem label="Settings" icon="lucide-settings" to="/settings" />
 			</MobileNav>
 		</template>
-
-		<BottomSheet v-model:open="mobileNavDrawer">
-			<Sidebar is-mobile class="p-4" />
-		</BottomSheet>
 	</MobileShell>
 
+	<!-- scroll=false: the servers map and the split panes own their own overflow,
+	     which is exactly the case frappe-ui documents this prop for. -->
 	<DesktopShell v-else :scroll="false" class="h-screen">
 		<template #sidebar>
 			<Sidebar />
 		</template>
 
-		<header
-			class="flex h-12 shrink-0 items-center justify-between gap-3 border-b border-outline-gray-1 px-4 sm:px-6"
-		>
-			<Breadcrumbs :items="breadcrumbs" />
-			<div id="header-actions" class="flex shrink-0 items-center gap-2" />
-		</header>
-
 		<div class="min-h-0 flex-1 overflow-hidden">
 			<router-view />
 		</div>
 	</DesktopShell>
 
 	<ToastProvider />
-	<!-- Desktop only: on mobile the same tabs are pages (/settings/:tab), so the
-	     dialog never mounts there. -->
+	<!-- Desktop only: on mobile the same tabs are pages (/mobile-settings/:tab),
+	     so the dialog never mounts there. -->
 	<SettingsModal v-if="!isMobile" />
 	<SearchDialog v-if="searchMounted" v-model:open="searchOpen" />
 </template>
diff --git a/dashboard/src/pages/addons/AIInference.vue b/dashboard/src/pages/addons/AIInference.vue
index b17f3645..53cd035f 100644
--- a/dashboard/src/pages/addons/AIInference.vue
+++ b/dashboard/src/pages/addons/AIInference.vue
@@ -1,11 +1,18 @@
 <script setup lang="ts">
-import { Button, Spinner, TabButtons } from 'frappe-ui'
+import {
+	Breadcrumbs,
+	Button,
+	PageHeader,
+	PageHeaderBackButton,
+	PageHeaderMobile,
+	Spinner,
+	TabButtons,
+} from 'frappe-ui'
 import { computed, ref, watch } from 'vue'
 import { useRouter } from 'vue-router'
 import AIApiKeys from '@/components/addons/AIApiKeys.vue'
 import AIOverview from '@/components/addons/AIOverview.vue'
 import EmptyState from '@/components/common/EmptyState.vue'
-import { useBreadcrumbs } from '@/composables/useBreadcrumbs'
 import { useCapabilities } from '@/composables/useCapabilities'
 import { useServices } from '@/composables/useServices'
 import { errorToast, errorToastWithAction } from '@/lib/toast'
@@ -16,7 +23,6 @@ const serviceKey = 'ai'
 const { canManageServices, canManageBilling } = useCapabilities()
 const { offers, offersLoading, instance, loadInstance, activate } =
 	useServices()
-const { setBreadcrumbs } = useBreadcrumbs()
 
 const offer = computed(
 	() => offers.value.find((o) => o.name === serviceKey) ?? null,
@@ -25,7 +31,6 @@ const managedService = computed(() => offer.value?.managed_service ?? null)
 const title = computed(() => offer.value?.title ?? 'Service')
 const description =
 	'Open models on Frappe hardware, through an OpenAI-compatible API.'
-watch(title, (value) => setBreadcrumbs([{ label: value }]), { immediate: true })
 const models = computed(() => instance.value?.models ?? [])
 
 watch(
@@ -63,7 +68,21 @@ const activateService = async (): Promise<void> => {
 </script>
 
 <template>
-	<div class="flex h-full flex-col">
+	<!-- The trail is the service's own title, as it was before: this page is only
+	     ever reached from the Services catalog, so that's where Back goes. -->
+	<PageHeaderMobile class="sm:hidden" :title="title">
+		<template #prefix>
+			<PageHeaderBackButton to="/addons" />
+		</template>
+	</PageHeaderMobile>
+
+	<PageHeader class="hidden sm:flex">
+		<Breadcrumbs :items="[{ label: title }]" />
+	</PageHeader>
+
+	<!-- Desktop-only column: the tab panels own their overflow there, while on a
+	     phone the page falls through to the shell's scroll. -->
+	<div class="sm:flex sm:h-full sm:flex-col">
 		<div
 			v-if="offersLoading && !offer"
 			class="flex flex-1 justify-center py-16"
diff --git a/dashboard/src/pages/addons/Page.vue b/dashboard/src/pages/addons/Page.vue
index 3425899e..79b01d73 100644
--- a/dashboard/src/pages/addons/Page.vue
+++ b/dashboard/src/pages/addons/Page.vue
@@ -1,8 +1,15 @@
 <script setup lang="ts">
-import { Badge, useCall } from 'frappe-ui'
+import {
+	Badge,
+	Breadcrumbs,
+	PageHeader,
+	PageHeaderMobile,
+	useCall,
+} from 'frappe-ui'
 import { computed } from 'vue'
 import { useRouter } from 'vue-router'
 import { API, method } from '@/api/methods'
+import NavDrawerTitle from '@/components/navigation/NavDrawerTitle.vue'
 import { useSession } from '@/composables/useSession'
 import { whenTeamReady } from '@/composables/useTeamScope'
 import { features } from '@/lib/features'
@@ -139,6 +146,14 @@ const cards = computed(() =>
 </script>
 
 <template>
+	<PageHeaderMobile class="sm:hidden">
+		<NavDrawerTitle title="Services" />
+	</PageHeaderMobile>
+
+	<PageHeader class="hidden sm:flex">
+		<Breadcrumbs :items="[{ label: 'Services', route: { name: 'Addons' } }]" />
+	</PageHeader>
+
 	<div class="mx-auto mt-10 max-w-3xl px-5">
 		<section class="grid gap-3 md:grid-cols-2">
 			<!-- A card is a link only once its page exists, so nothing invites a
diff --git a/dashboard/src/pages/billing/BillingOverviewPage.vue b/dashboard/src/pages/billing/BillingOverviewPage.vue
index f231c490..4888e9c0 100644
--- a/dashboard/src/pages/billing/BillingOverviewPage.vue
+++ b/dashboard/src/pages/billing/BillingOverviewPage.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { Alert } from 'frappe-ui'
+import { Alert, Breadcrumbs, PageHeader, PageHeaderMobile } from 'frappe-ui'
 import { ref } from 'vue'
 import BillingContactTaxCard from '@/components/billing/BillingContactTaxCard.vue'
 import CollectionActionBanner from '@/components/billing/CollectionActionBanner.vue'
@@ -14,6 +14,7 @@ import PaymentSchedulePanel from '@/components/billing/PaymentSchedulePanel.vue'
 import StopBillingCard from '@/components/billing/StopBillingCard.vue'
 import WalletCard from '@/components/billing/WalletCard.vue'
 import WalletHistoryPanel from '@/components/billing/WalletHistoryPanel.vue'
+import NavDrawerTitle from '@/components/navigation/NavDrawerTitle.vue'
 import { useBillingSetup } from '@/composables/useBillingSetup'
 import { computed } from 'vue'
 
@@ -52,11 +53,24 @@ const advancedOpen = ref(false)
 </script>
 
 <template>
-	<div class="flex h-full flex-col">
-		<!-- Content + docked wallet-history panel (like the invoice tray): the panel
-         shares the row, the content stays bright beside it — no modal overlay. -->
-		<div class="flex min-h-0 flex-1">
-			<div class="cards-host min-w-0 flex-1 overflow-y-auto">
+	<PageHeaderMobile class="sm:hidden">
+		<NavDrawerTitle title="Billing" />
+	</PageHeaderMobile>
+
+	<PageHeader class="hidden sm:flex">
+		<Breadcrumbs :items="[{ label: 'Billing', route: { name: 'Billing' } }]" />
+	</PageHeader>
+
+	<!-- The split is desktop-only scaffolding: DesktopShell doesn't scroll, so the
+	     panes own their overflow there. On mobile MobileShell is the scroller and
+	     the page has to fall through to it, or the bottom nav eats the last rows. -->
+	<div class="sm:flex sm:h-full sm:flex-col">
+		<!-- Content + wallet-history panel (like the invoice tray): on desktop the
+         panel shares this row and the content stays bright beside it — no modal
+         overlay. Below `sm` SidePanel takes itself out of flow and covers the
+         screen, so there is nothing left for this row to place. -->
+		<div class="sm:flex sm:min-h-0 sm:flex-1">
+			<div class="cards-host sm:min-w-0 sm:flex-1 sm:overflow-y-auto">
 				<div class="mx-auto w-full max-w-3xl space-y-5 px-6 py-8">
 					<!-- Until the billing profile is filled, ask the team to complete it
                first — money-moving actions stay gated on it. -->
diff --git a/dashboard/src/pages/billing/BillingReportsPage.vue b/dashboard/src/pages/billing/BillingReportsPage.vue
index 0e298201..04c81be6 100644
--- a/dashboard/src/pages/billing/BillingReportsPage.vue
+++ b/dashboard/src/pages/billing/BillingReportsPage.vue
@@ -1,5 +1,12 @@
 <script setup lang="ts">
-import { Button, LoadingText, useCall } from 'frappe-ui'
+import {
+	Breadcrumbs,
+	Button,
+	LoadingText,
+	PageHeader,
+	PageHeaderMobile,
+	useCall,
+} from 'frappe-ui'
 import { computed, ref } from 'vue'
 import { useRouter } from 'vue-router'
 import { API, method } from '@/api/methods'
@@ -13,6 +20,7 @@ import StatementCard from '@/components/billing/StatementCard.vue'
 import StatementPanel from '@/components/billing/StatementPanel.vue'
 import TaxSummaryCard from '@/components/billing/TaxSummaryCard.vue'
 import EmptyState from '@/components/common/EmptyState.vue'
+import NavDrawerTitle from '@/components/navigation/NavDrawerTitle.vue'
 import { useSession } from '@/composables/useSession'
 import { whenTeamReady } from '@/composables/useTeamScope'
 import type { SpendHistory } from '@/types/billing'
@@ -81,8 +89,27 @@ function exportUrl(report: string): string {
 </script>
 
 <template>
-	<div class="flex h-full min-h-0">
-		<div class="min-w-0 flex-1 overflow-y-auto">
+	<PageHeaderMobile class="sm:hidden">
+		<NavDrawerTitle title="Reports" />
+	</PageHeaderMobile>
+
+	<!-- 'Billing' is the sidebar group Reports sits in, not a page above it —
+	     Overview is its sibling. So it labels the trail without linking. -->
+	<PageHeader class="hidden sm:flex">
+		<Breadcrumbs
+			:items="[
+				{ label: 'Billing' },
+				{ label: 'Reports', route: { name: 'BillingReports' } },
+			]"
+		/>
+	</PageHeader>
+
+	<!-- The content/tray row is desktop-only scaffolding: DesktopShell doesn't
+	     scroll, so the panes own their overflow there. On mobile MobileShell is
+	     the scroller and the page has to fall through to it, or the bottom nav
+	     eats the last rows. -->
+	<div class="sm:flex sm:h-full sm:min-h-0">
+		<div class="sm:min-w-0 sm:flex-1 sm:overflow-y-auto">
 			<div class="mx-auto w-full max-w-3xl space-y-5 px-6 py-8">
 			<header class="flex flex-wrap items-end justify-between gap-3">
 				<div>
diff --git a/dashboard/src/pages/home/HomePage.vue b/dashboard/src/pages/home/HomePage.vue
index df9adeb3..5b3ffde7 100644
--- a/dashboard/src/pages/home/HomePage.vue
+++ b/dashboard/src/pages/home/HomePage.vue
@@ -1,7 +1,24 @@
 <script setup lang="ts">
+import { Breadcrumbs, PageHeader, PageHeaderMobile } from 'frappe-ui'
+import frappeCloudLogo from '@/assets/fc-logo.svg'
 import Sidebar from '@/components/navigation/Sidebar.vue'
+
+// Home is the nav list itself. Every other section page hangs the same list off
+// its title as a drawer (NavDrawerTitle); here that would just be the page
+// showing itself twice, so the title stays a plain title. Nothing navigates out
+// of the top of the stack, which leaves the left slot free for the mark.
 </script>
 
 <template>
+	<PageHeaderMobile class="sm:hidden" title="Home">
+		<template #prefix>
+			<img :src="frappeCloudLogo" alt="Frappe Cloud" class="size-6" />
+		</template>
+	</PageHeaderMobile>
+
+	<PageHeader class="hidden sm:flex">
+		<Breadcrumbs :items="[{ label: 'Home', route: { name: 'Home' } }]" />
+	</PageHeader>
+
 	<Sidebar is-mobile />
 </template>
diff --git a/dashboard/src/pages/notifications/NotificationsPage.vue b/dashboard/src/pages/notifications/NotificationsPage.vue
index 70eea6de..ec9958b9 100644
--- a/dashboard/src/pages/notifications/NotificationsPage.vue
+++ b/dashboard/src/pages/notifications/NotificationsPage.vue
@@ -1,5 +1,12 @@
 <script setup lang="ts">
-import { Button, LoadingText, TabButtons } from 'frappe-ui'
+import {
+	Breadcrumbs,
+	Button,
+	LoadingText,
+	PageHeader,
+	PageHeaderMobile,
+	TabButtons,
+} from 'frappe-ui'
 import { computed, ref } from 'vue'
 import { useRouter } from 'vue-router'
 import EmptyState from '@/components/common/EmptyState.vue'
@@ -37,8 +44,23 @@ async function onAct(n: TeamNotification): Promise<void> {
 </script>
 
 <template>
-	<div class="flex h-full flex-col">
-		<Teleport defer to="#header-actions">
+	<PageHeaderMobile class="sm:hidden" title="Notifications">
+		<template #suffix>
+			<Button
+				variant="ghost"
+				size="md"
+				icon="lucide-settings-2"
+				label="Notification preferences"
+				@click="openSettings('notifications')"
+			/>
+		</template>
+	</PageHeaderMobile>
+
+	<PageHeader class="hidden sm:flex">
+		<Breadcrumbs
+			:items="[{ label: 'Notifications', route: { name: 'Notifications' } }]"
+		/>
+		<div class="flex items-center gap-2">
 			<Button
 				v-if="unread > 0"
 				variant="subtle"
@@ -51,11 +73,31 @@ async function onAct(n: TeamNotification): Promise<void> {
 				label="Notification preferences"
 				@click="openSettings('notifications')"
 			/>
-		</Teleport>
+		</div>
+	</PageHeader>
 
-		<div class="min-h-0 flex-1 overflow-y-auto">
+	<!-- Desktop-only scroll scaffolding: DesktopShell doesn't scroll, so the page
+	     owns its overflow there. On mobile MobileShell is the scroller and this
+	     falls through to it. -->
+	<div class="sm:flex sm:h-full sm:flex-col">
+		<div class="sm:min-h-0 sm:flex-1 sm:overflow-y-auto">
 			<div class="mx-auto max-w-2xl px-4 py-5 sm:px-6">
-				<TabButtons v-model="filter" :options="FILTERS" class="mb-4" />
+				<!-- Mark all read can't ride along in the mobile header: the title is
+				     centered and each side slot caps at 35% of the width, which the
+				     preferences icon already takes. It shares the filter row instead —
+				     the tabs don't fill the width, so both fit on one line and the
+				     button costs no vertical space. -->
+				<div class="mb-4 flex items-center justify-between gap-2">
+					<TabButtons v-model="filter" :options="FILTERS" />
+					<Button
+						v-if="unread > 0"
+						class="sm:hidden"
+						variant="subtle"
+						size="md"
+						label="Mark all read"
+						@click="markAllAsRead"
+					/>
+				</div>
 
 				<div v-if="loading && !items.length" class="p-4">
 					<LoadingText :lines="6" />
diff --git a/dashboard/src/pages/servers/NewServerPage.vue b/dashboard/src/pages/servers/NewServerPage.vue
index 5eb3f4e6..55b5a0ab 100644
--- a/dashboard/src/pages/servers/NewServerPage.vue
+++ b/dashboard/src/pages/servers/NewServerPage.vue
@@ -1,5 +1,16 @@
 <script setup lang="ts">
-import { Alert, Badge, Button, FormControl, Tabs, useCall } from 'frappe-ui'
+import {
+	Alert,
+	Badge,
+	Breadcrumbs,
+	Button,
+	FormControl,
+	PageHeader,
+	PageHeaderBackButton,
+	PageHeaderMobile,
+	Tabs,
+	useCall,
+} from 'frappe-ui'
 import { computed, ref, watch } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { API, method } from '@/api/methods'
@@ -394,14 +405,30 @@ async function submit() {
 </script>
 
 <template>
-	<div class="flex h-full flex-col">
-		<Teleport defer to="#header-actions">
-			<Button label="Cancel" @click="router.push('/servers')" />
-		</Teleport>
-
-		<div class="flex min-h-0 flex-1 flex-col-reverse lg:flex-row">
+	<!-- Back is the mobile Cancel: same destination, and it doubles as the way out
+	     of a page that has no room for a trail. -->
+	<PageHeaderMobile class="sm:hidden" title="New server">
+		<template #prefix>
+			<PageHeaderBackButton to="/servers" />
+		</template>
+	</PageHeaderMobile>
+
+	<PageHeader class="hidden sm:flex">
+		<Breadcrumbs
+			:items="[
+				{ label: 'Servers', route: { name: 'Servers' } },
+				{ label: 'New server' },
+			]"
+		/>
+		<Button label="Cancel" @click="router.push('/servers')" />
+	</PageHeader>
+
+	<!-- The pane scaffolding is desktop-only: on mobile the page has no height cap
+	     and no inner scroller, so it falls through to the shell's scroll. -->
+	<div class="sm:flex sm:h-full sm:flex-col">
+		<div class="flex flex-col-reverse sm:min-h-0 sm:flex-1 lg:flex-row">
 			<!-- Stepped form (left) -->
-			<div class="w-full overflow-y-auto p-4 lg:w-[40rem] lg:shrink-0">
+			<div class="w-full p-4 sm:overflow-y-auto lg:w-[40rem] lg:shrink-0">
 				<p v-if="loading" class="text-p-sm text-ink-gray-5">Loading regions…</p>
 				<p v-else-if="!regions.length" class="text-p-sm text-ink-gray-5">
 					No active regions are available right now.
diff --git a/dashboard/src/pages/servers/ServersPage.vue b/dashboard/src/pages/servers/ServersPage.vue
index 3b5a04ed..89906184 100644
--- a/dashboard/src/pages/servers/ServersPage.vue
+++ b/dashboard/src/pages/servers/ServersPage.vue
@@ -1,10 +1,18 @@
 <script setup lang="ts">
-import { Button, Spinner, useCall } from 'frappe-ui'
+import {
+	Breadcrumbs,
+	Button,
+	PageHeader,
+	PageHeaderMobile,
+	Spinner,
+	useCall,
+} from 'frappe-ui'
 import { computed, ref, watch } from 'vue'
 import { useRouter } from 'vue-router'
 import { API, method } from '@/api/methods'
 import ConfirmDialog from '@/components/common/ConfirmDialog.vue'
 import EmptyState from '@/components/common/EmptyState.vue'
+import NavDrawerTitle from '@/components/navigation/NavDrawerTitle.vue'
 import MapHealthStrips from '@/components/servers/MapHealthStrips.vue'
 import MapMessageCard from '@/components/servers/MapMessageCard.vue'
 import ResizeServerDialog from '@/components/servers/ResizeServerDialog.vue'
@@ -96,6 +104,12 @@ function dismissOnboarding(): void {
 	onboardingDismissed.value = true
 	localStorage.setItem(ONBOARDING_KEY, '1')
 }
+// Hidden while the onboarding card is up — that card carries the single primary
+// action then, so there's never two New-server buttons at once. Both headers ask,
+// so it's a computed rather than the same condition spelled twice.
+const showNewServerAction = computed(
+	() => !!activeTeam.value && canCreateServer.value && !showOnboarding.value,
+)
 
 const q = ref('')
 const statusFilter = ref<ServerVisual['key'] | ''>('')
@@ -123,21 +137,37 @@ const providerGroups = computed(() => {
 		if (!groups.has(provider)) groups.set(provider, [])
 		groups.get(provider)!.push(region)
 	}
-	return [...groups.entries()].map(([provider, list]) => ({
-		provider,
-		regions: list,
-	}))
+	return (
+		[...groups.entries()]
+			.map(([provider, list]) => ({ provider, regions: list }))
+			// 'Other' is the catch-all for regions with no provider set — a footnote
+			// to the named providers, so it sorts after them rather than landing
+			// first just because an unattributed region happened to come back first.
+			// Sort is stable, so the named providers keep their existing order.
+			.sort(
+				(a, b) =>
+					Number(a.provider === 'Other') - Number(b.provider === 'Other'),
+			)
+	)
 })
 
+// Grouped by provider, so a provider's own regions sit under its heading
+// instead of running together in one flat list where the "All X regions" rows
+// were the only thing marking a boundary. "All regions" stays ungrouped at the
+// top — it spans every provider, so it belongs under none of them.
 const regionOptions = computed(() => [
 	{ label: 'All regions', value: '' },
-	...providerGroups.value.flatMap((group) => [
-		{ label: `All ${group.provider} regions`, value: `p:${group.provider}` },
-		...group.regions.map((r) => ({
-			label: `${flagEmoji(r.country_code)} ${regionLabel(r)}`.trim(),
-			value: `r:${group.provider}|${r.region}`,
-		})),
-	]),
+	...providerGroups.value.map((group) => ({
+		key: group.provider,
+		group: group.provider,
+		options: [
+			{ label: `All ${group.provider} regions`, value: `p:${group.provider}` },
+			...group.regions.map((r) => ({
+				label: `${flagEmoji(r.country_code)} ${regionLabel(r)}`.trim(),
+				value: `r:${group.provider}|${r.region}`,
+			})),
+		],
+	})),
 ])
 const regionSelection = computed({
 	get(): string {
@@ -371,8 +401,30 @@ async function confirmSiteTerminate(): Promise<void> {
 </script>
 
 <template>
-	<div class="flex h-full flex-col">
-		<Teleport defer to="#header-actions">
+	<PageHeaderMobile class="sm:hidden">
+		<NavDrawerTitle title="Servers" />
+		<template #suffix>
+			<Button
+				v-if="activeTeam"
+				variant="ghost"
+				icon="lucide-refresh-cw"
+				label="Refresh"
+				:loading="refreshing"
+				@click="doRefresh"
+			/>
+			<Button
+				v-if="showNewServerAction"
+				variant="ghost"
+				icon="lucide-plus"
+				label="New server"
+				@click="$router.push('/servers/new')"
+			/>
+		</template>
+	</PageHeaderMobile>
+
+	<PageHeader class="hidden sm:flex">
+		<Breadcrumbs :items="[{ label: 'Servers', route: { name: 'Servers' } }]" />
+		<div class="flex items-center gap-2">
 			<Button
 				v-if="activeTeam"
 				label="Refresh"
@@ -380,17 +432,17 @@ async function confirmSiteTerminate(): Promise<void> {
 				:loading="refreshing"
 				@click="doRefresh"
 			/>
-			<!-- Hidden while the onboarding card is up — that card carries the single
-             primary action then, so there's never two New-server buttons at once. -->
 			<Button
-				v-if="activeTeam && canCreateServer && !showOnboarding"
+				v-if="showNewServerAction"
 				variant="solid"
 				label="New server"
 				icon-left="lucide-plus"
 				@click="$router.push('/servers/new')"
 			/>
-		</Teleport>
+		</div>
+	</PageHeader>
 
+	<div class="flex h-full flex-col">
 		<!-- No team at all: create one before anything else can be provisioned. -->
 		<div v-if="hasNoTeam" class="flex flex-1 items-center justify-center p-8">
 			<EmptyState
diff --git a/dashboard/src/pages/settings/SettingsDetailPage.vue b/dashboard/src/pages/settings/SettingsDetailPage.vue
index d4f2a511..67e09cc4 100644
--- a/dashboard/src/pages/settings/SettingsDetailPage.vue
+++ b/dashboard/src/pages/settings/SettingsDetailPage.vue
@@ -1,17 +1,23 @@
 <script setup lang="ts">
+import { PageHeaderBackButton, PageHeaderMobile } from 'frappe-ui'
 import { computed, watch } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
-import { useBreadcrumbs } from '@/composables/useBreadcrumbs'
 import { useCapabilities } from '@/composables/useCapabilities'
-import { SETTINGS_TABS, type SettingsTab } from '@/composables/useSettings'
+import { useIsMobile } from '@/composables/useIsMobile'
+import {
+	MOBILE_SETTINGS_BASE,
+	SETTINGS_BASE,
+	SETTINGS_TABS,
+	type SettingsTab,
+} from '@/composables/useSettings'
 
 // One settings tab as a full page. Mobile has no room for a dialog with a
-// sidebar, so the tabs become routes: /settings lists them, /settings/:tab is
-// the tab itself, and Back goes where you'd expect.
+// sidebar, so the tabs become routes: /mobile-settings lists them,
+// /mobile-settings/:tab is the tab itself, and Back goes where you'd expect.
 const route = useRoute()
 const router = useRouter()
-const { setBreadcrumbs } = useBreadcrumbs()
 const { loading, isMember, canEditTeam, canDeleteTeam } = useCapabilities()
+const isMobile = useIsMobile()
 
 const tab = computed(() =>
 	SETTINGS_TABS.find((t) => t.value === (route.params.tab as SettingsTab)),
@@ -28,35 +34,52 @@ const allowed = computed(() => {
 })
 
 watch(
-	[tab, allowed, loading],
+	[tab, allowed, loading, isMobile],
 	() => {
+		// Widened past the breakpoint (a resize, a rotate): the same tab has a
+		// dialog to live in now, so follow it across to the desktop URL.
+		if (!isMobile.value) {
+			router.replace(`${SETTINGS_BASE}/${tab.value?.value ?? 'profile'}`)
+			return
+		}
 		// An unknown tab is wrong now; a forbidden one is only wrong once
 		// capabilities have actually landed, or a refresh would bounce every
 		// gated tab before the answer arrives.
 		if (!tab.value || (!loading.value && !allowed.value)) {
-			router.replace('/settings')
-			return
+			router.replace(MOBILE_SETTINGS_BASE)
 		}
-		setBreadcrumbs([
-			{ label: 'Settings', route: { path: '/settings' } },
-			{ label: tab.value.label },
-		])
 	},
 	{ immediate: true },
 )
 </script>
 
 <template>
-	<div v-if="tab && allowed" class="h-full overflow-y-auto">
-		<div class="mx-auto max-w-2xl px-4 py-5 sm:px-6">
-			<header class="mb-6">
-				<h1 class="text-lg font-semibold text-ink-gray-8">{{ tab.title }}</h1>
-				<p v-if="tab.description" class="mt-1 text-base text-ink-gray-6">
-					{{ tab.description }}
-				</p>
-			</header>
+	<!-- No desktop PageHeader and no `sm:hidden`: the watcher above hands this
+	     route over to the dialog the moment it isn't mobile, so the page never
+	     renders at desktop width. The back button carries the trail up to the
+	     hub, which is what the breadcrumbs used to say. -->
+	<template v-if="tab && allowed">
+		<PageHeaderMobile :title="tab.title">
+			<template #prefix>
+				<PageHeaderBackButton :to="MOBILE_SETTINGS_BASE" />
+			</template>
+		</PageHeaderMobile>
+
+		<div class="sm:h-full sm:overflow-y-auto">
+			<div class="mx-auto max-w-2xl px-4 py-5 sm:px-6">
+				<header class="mb-6">
+					<!-- The header already carries the title on mobile; the description
+					     is content it can't carry, so that stays. -->
+					<h1 class="hidden text-lg font-semibold text-ink-gray-8 sm:block">
+						{{ tab.title }}
+					</h1>
+					<p v-if="tab.description" class="mt-1 text-base text-ink-gray-6">
+						{{ tab.description }}
+					</p>
+				</header>
 
-			<component :is="tab.component" />
+				<component :is="tab.component" />
+			</div>
 		</div>
-	</div>
+	</template>
 </template>
diff --git a/dashboard/src/pages/settings/SettingsDialogRoute.vue b/dashboard/src/pages/settings/SettingsDialogRoute.vue
new file mode 100644
index 00000000..b569a2cf
--- /dev/null
+++ b/dashboard/src/pages/settings/SettingsDialogRoute.vue
@@ -0,0 +1,97 @@
+<script setup lang="ts">
+import { Breadcrumbs, PageHeader } from 'frappe-ui'
+import { onUnmounted, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { useCapabilities } from '@/composables/useCapabilities'
+import { useIsMobile } from '@/composables/useIsMobile'
+import {
+	MOBILE_SETTINGS_BASE,
+	SETTINGS_BASE,
+	SETTINGS_TABS,
+	type SettingsTab,
+	returnFromSettings,
+	settingsOpen,
+	settingsTab,
+} from '@/composables/useSettings'
+
+// Desktop settings are a dialog, but they still get an address. This route
+// renders nothing: it exists to keep /settings/:tab and the dialog in step in
+// both directions, so Back, Forward and a reload all land on the tab the URL
+// names, and picking a tab inside the dialog updates the URL to match.
+const route = useRoute()
+const router = useRouter()
+const isMobile = useIsMobile()
+
+const { loading, isMember, canEditTeam, canDeleteTeam } = useCapabilities()
+
+const known = (value: unknown): value is SettingsTab =>
+	SETTINGS_TABS.some((tab) => tab.value === value)
+
+// A tab this member can't reach is as wrong as one that doesn't exist: the
+// dialog only renders panels for the tabs it lists, so an ungated slug selects
+// nothing and leaves a blank content pane with nothing lit in the sidebar. The
+// mobile page has always gated this; when the two presentations split, the
+// desktop half lost the check.
+const reachable = (value: SettingsTab): boolean => {
+	const tab = SETTINGS_TABS.find((t) => t.value === value)
+	if (tab?.requires === 'member') return isMember.value
+	if (tab?.requires === 'teamAdmin')
+		return canEditTeam.value || canDeleteTeam.value
+	return true
+}
+
+watch(
+	[() => route.params.tab, isMobile, loading, isMember, canEditTeam, canDeleteTeam],
+	() => {
+		const param = route.params.tab
+		const tab = known(param) ? param : 'profile'
+		// The dialog never mounts on a phone, so this URL would render an empty
+		// page there. Hand the same tab to the page stack that does exist.
+		if (isMobile.value) {
+			router.replace(`${MOBILE_SETTINGS_BASE}/${tab}`)
+			return
+		}
+		// An unknown tab is a typo in the address bar, not a state to render.
+		if (!known(param)) {
+			router.replace(`${SETTINGS_BASE}/${tab}`)
+			return
+		}
+		// A gated tab is only wrong once capabilities have actually landed, or a
+		// reload would bounce every gated tab before the answer arrives.
+		if (!loading.value && !reachable(tab)) {
+			router.replace(`${SETTINGS_BASE}/profile`)
+			return
+		}
+		settingsTab.value = tab
+		settingsOpen.value = true
+	},
+	{ immediate: true },
+)
+
+// A tab picked in the dialog's sidebar is a navigation like any other.
+watch(settingsTab, (tab) => {
+	if (settingsOpen.value && route.params.tab !== tab) {
+		router.replace(`${SETTINGS_BASE}/${tab}`)
+	}
+})
+
+// Dismissing the dialog (its close button, Esc, the backdrop) leaves this route
+// showing nothing, so treat it as leaving settings.
+watch(settingsOpen, (open) => {
+	if (!open) returnFromSettings()
+})
+
+onUnmounted(() => {
+	settingsOpen.value = false
+})
+</script>
+
+<template>
+	<!-- The page itself is empty — the dialog is the content. The header strip
+	     still gets a crumb so the chrome behind the scrim matches every other
+	     desktop page, including when this URL is opened cold and there's no
+	     page underneath to return to. Mobile never reaches here. -->
+	<PageHeader class="hidden sm:flex">
+		<Breadcrumbs :items="[{ label: 'Settings' }]" />
+	</PageHeader>
+</template>
diff --git a/dashboard/src/pages/settings/SettingsPage.vue b/dashboard/src/pages/settings/SettingsPage.vue
index c6b04ce2..7d4f1465 100644
--- a/dashboard/src/pages/settings/SettingsPage.vue
+++ b/dashboard/src/pages/settings/SettingsPage.vue
@@ -1,11 +1,14 @@
 <script setup lang="ts">
-import { Button } from 'frappe-ui'
-import { computed } from 'vue'
+import { Button, PageHeaderMobile } from 'frappe-ui'
+import { computed, watch } from 'vue'
+import { useRouter } from 'vue-router'
 import { useAppMenu } from '@/composables/useAppMenu'
 import { useCapabilities } from '@/composables/useCapabilities'
+import { useIsMobile } from '@/composables/useIsMobile'
 import { useSession } from '@/composables/useSession'
 import {
 	openSettings,
+	SETTINGS_BASE,
 	SETTINGS_TABS,
 	type SettingsTabDef,
 } from '@/composables/useSettings'
@@ -17,6 +20,20 @@ const { activeTeamLabel } = useSession()
 const { isMember, canEditTeam, canDeleteTeam } = useCapabilities()
 const { currentUser, logoutAndRedirect } = useAppMenu()
 
+// This hub only makes sense at phone width. Arriving here on a wide screen
+// (Back into it, a stale link) or widening past the breakpoint while it's open
+// both hand over to the dialog's URL — immediate, or arriving would render a
+// stack of rows on a desktop and only correct itself on the next resize.
+const router = useRouter()
+const isMobile = useIsMobile()
+watch(
+	isMobile,
+	(mobile) => {
+		if (!mobile) router.replace(`${SETTINGS_BASE}/profile`)
+	},
+	{ immediate: true },
+)
+
 const groups = computed(() => {
 	const available = SETTINGS_TABS.filter((tab) => {
 		if (tab.requires === 'member') return isMember.value
@@ -46,22 +63,31 @@ const groups = computed(() => {
 </script>
 
 <template>
-	<div class="m-2 space-y-4">
+	<!-- No desktop PageHeader and no `sm:hidden`: the watcher above hands this
+	     route over to the dialog the moment it isn't mobile, so the page never
+	     renders at desktop width. -->
+	<PageHeaderMobile title="Settings" />
+
+	<!-- Extra top margin so the first group label clears the header rather than
+	     sitting right under its border. -->
+	<div class="m-2 mt-4 space-y-4">
 		<section v-for="group in groups" :key="group.label">
-			<p class="px-1 pb-1.5 text-xs text-ink-gray-5">{{ group.label }}</p>
-			<div class="divide-y divide-outline-gray-1 rounded-4 border">
+			<p class="px-1 pb-1.5 text-base text-ink-gray-5">{{ group.label }}</p>
+			<div
+				class="divide-y divide-outline-gray-1 overflow-hidden rounded-4 border"
+			>
 				<Button
 					v-for="row in group.rows"
 					:key="row.tab.value"
 					variant="ghost"
-					class="w-full !justify-between text-base"
+					class="w-full !justify-between !rounded-none !font-normal"
 					size="lg"
 					@click="openSettings(row.tab.value)"
 				>
 					{{ row.tab.label }}
 					<template #suffix>
 						<span
-							class="flex min-w-0 items-center gap-1 text-p-sm text-ink-gray-5"
+							class="flex min-w-0 items-center gap-1 text-p-base text-ink-gray-5"
 						>
 							<span class="truncate">{{ row.current }}</span>
 							<span class="lucide-chevron-right size-4 shrink-0" />
@@ -71,11 +97,12 @@ const groups = computed(() => {
 			</div>
 		</section>
 
-		<div class="rounded-4 border">
+		<div class="overflow-hidden rounded-4 border">
 			<Button
 				theme="red"
 				variant="ghost"
-				class="!h-auto w-full !justify-start !rounded-none !px-4 !py-3"
+				size="lg"
+				class="w-full !justify-start !rounded-none !font-normal"
 				@click="logoutAndRedirect"
 			>
 				Sign out
diff --git a/dashboard/src/pages/team/AccessPage.vue b/dashboard/src/pages/team/AccessPage.vue
index d8044370..8b3b0f3c 100644
--- a/dashboard/src/pages/team/AccessPage.vue
+++ b/dashboard/src/pages/team/AccessPage.vue
@@ -1,6 +1,14 @@
 <script setup lang="ts">
-import { Avatar, Button, TabButtons } from 'frappe-ui'
+import {
+	Avatar,
+	Breadcrumbs,
+	Button,
+	PageHeader,
+	PageHeaderMobile,
+	TabButtons,
+} from 'frappe-ui'
 import { computed, ref } from 'vue'
+import NavDrawerTitle from '@/components/navigation/NavDrawerTitle.vue'
 import MembersPanel from '@/components/team/MembersPanel.vue'
 import RolesPanel from '@/components/team/RolesPanel.vue'
 import { useCapabilities } from '@/composables/useCapabilities'
@@ -31,8 +39,19 @@ const memberCountText = computed(() => {
 </script>
 
 <template>
-	<div class="flex h-full min-h-0">
-		<div class="min-w-0 flex-1 overflow-y-auto">
+	<PageHeaderMobile class="sm:hidden">
+		<NavDrawerTitle title="Team" />
+	</PageHeaderMobile>
+
+	<PageHeader class="hidden sm:flex">
+		<Breadcrumbs :items="[{ label: 'Team', route: { name: 'Members' } }]" />
+	</PageHeader>
+
+	<!-- The pane and its overflow are desktop-only: on a phone the shell owns the
+	     scroll, and a second scroll box inside it would swallow the tap-the-tab-
+	     to-scroll-top gesture and hide the last rows behind the nav bar. -->
+	<div class="sm:flex sm:h-full sm:min-h-0">
+		<div class="sm:min-w-0 sm:flex-1 sm:overflow-y-auto">
 			<main class="mx-auto flex flex-col max-w-3xl gap-3 mt-10 px-3 xl:p-0">
 				<div class="mb-5 flex items-center gap-3">
 					<!-- Square: this is the organisation, not a person. Circles stay
@@ -58,7 +77,7 @@ const memberCountText = computed(() => {
 						variant="subtle"
 						icon="lucide-pencil"
 						label="Edit team"
-						@click="openSettings('team')"
+						@click="openSettings('team-settings')"
 					/>
 				</div>
 
@@ -74,5 +93,10 @@ const memberCountText = computed(() => {
 				</RolesPanel>
 			</main>
 		</div>
+
+		<!-- RoleCapabilitiesPanel teleports here: the panel is opened from a row
+		     deep inside `main`, but it has to dock beside that scroll box rather
+		     than inside it. `contents` keeps the panel itself the flex item, so its
+		     24rem and the slide's negative margin measure against this row. -->
 	</div>
 </template>
diff --git a/dashboard/src/pages/team/InvitationsPage.vue b/dashboard/src/pages/team/InvitationsPage.vue
index a4870a66..7e995d27 100644
--- a/dashboard/src/pages/team/InvitationsPage.vue
+++ b/dashboard/src/pages/team/InvitationsPage.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { Tabs } from 'frappe-ui'
+import { Breadcrumbs, PageHeader, PageHeaderMobile, Tabs } from 'frappe-ui'
 import { computed, ref } from 'vue'
 import { useRoute } from 'vue-router'
 import ReceivedInvitationsPanel from '@/components/team/ReceivedInvitationsPanel.vue'
@@ -35,7 +35,19 @@ const activeTab = ref(wantReceived ? 'received' : 'sent')
 </script>
 
 <template>
-	<div class="flex h-full flex-col">
+	<!-- No back button, and no route on the crumb: nothing in the app links here
+	     (the sidebar has no Invitations entry and Team doesn't link out to one),
+	     so the page is reached cold from the invite email or a typed URL — and
+	     three routes share it, so a self-link would have to pick one. -->
+	<PageHeaderMobile class="sm:hidden" title="Invitations" />
+
+	<PageHeader class="hidden sm:flex">
+		<Breadcrumbs :items="[{ label: 'Invitations' }]" />
+	</PageHeader>
+
+	<!-- Desktop-only column: on a phone the tabs fall through to the shell's
+	     scroll rather than nesting one of their own. -->
+	<div class="sm:flex sm:h-full sm:flex-col">
 		<Tabs v-model="activeTab" :tabs="tabs">
 			<template #tab-panel="{ tab }">
 				<SentInvitationsPanel v-if="tab.value === 'sent'" />
diff --git a/dashboard/src/router/index.ts b/dashboard/src/router/index.ts
index e110eec8..b8e3002a 100644
--- a/dashboard/src/router/index.ts
+++ b/dashboard/src/router/index.ts
@@ -1,3 +1,5 @@
+import { shellScrollContainer } from 'frappe-ui'
+import { nextTick } from 'vue'
 import { createRouter, createWebHistory } from 'vue-router'
 import { useAuth } from '@/composables/useAuth'
 import { useSession } from '@/composables/useSession'
@@ -99,18 +101,26 @@ const routes = [
 				component: () => import('@/pages/notifications/NotificationsPage.vue'),
 				meta: { title: 'Notifications' },
 			},
+			// Two presentations, two URL spaces, each naming its tab. /settings is
+			// the desktop dialog — that route renders nothing and drives the dialog,
+			// so the open tab always shows in the address bar. /mobile-settings is
+			// the page stack a phone gets instead: a hub, then a page per tab.
+			{ path: 'settings', redirect: '/settings/profile' },
 			{
-				path: 'settings',
+				path: 'settings/:tab',
 				name: 'Settings',
+				component: () => import('@/pages/settings/SettingsDialogRoute.vue'),
+				meta: { title: 'Settings' },
+			},
+			{
+				path: 'mobile-settings',
+				name: 'MobileSettings',
 				component: () => import('@/pages/settings/SettingsPage.vue'),
 				meta: { title: 'Settings' },
 			},
-			// Mobile opens each settings tab as its own page — no dialog on a
-			// phone. Desktop reaches the same tabs through the settings dialog,
-			// but these routes stay valid there (deep links, browser Back).
 			{
-				path: 'settings/:tab',
-				name: 'SettingsTab',
+				path: 'mobile-settings/:tab',
+				name: 'MobileSettingsTab',
 				component: () => import('@/pages/settings/SettingsDetailPage.vue'),
 				meta: { title: 'Settings' },
 			},
@@ -161,6 +171,22 @@ const routes = [
 export const router = createRouter({
 	history: createWebHistory('/dashboard/'),
 	routes,
+	// The shells own the scroll region, not the window, so a returned position
+	// would be applied to a document that never scrolls. Drive the registered
+	// container instead — frappe-ui exposes this ref for exactly this spot.
+	//
+	// Without it a new page opens wherever the last one was left: the shell's
+	// scroll div outlives the route, where each page used to own a box that
+	// remounted at zero. Only a real path change resets — a query-only replace
+	// (settings tabs, ?invoice=) is the same page and keeps its place.
+	scrollBehavior(to, from) {
+		if (to.path === from.path) return
+		// The container is the shell's, so it survives the swap; waiting a tick
+		// only lets the incoming page lay out first.
+		return nextTick().then(() => {
+			shellScrollContainer.value?.scrollTo({ top: 0 })
+		})
+	},
 })
 
 // Session state is seeded synchronously from boot data (window.user), so the

From 505a0232f0089f0808dfc031865d3adde4fcf7b6 Mon Sep 17 00:00:00 2001
From: Sadiq Ansari <sadiqxansari@gmail.com>
Date: Thu, 13 Aug 2026 16:33:59 +0530
Subject: [PATCH 2/5] fix(billing): the tiers ladder reflows instead of
 shrinking on a phone
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The ladder was a four-column table — rail, tier, requirements, price — and the
requirements column is the one that carries sentences. At 375px it got whatever
the other three left, so "≥ $300.00 paid to date" wrapped to four lines on every
rung and the check mark floated away from the text it belonged to.

Columns are the wrong primitive when one of them can't be narrowed. Each rung is
a wrapping flex row now: name and price share the first line, requirements span
the full width beneath, and at `sm` the three fall back into the same columns the
table drew. The `<style>` block goes with the table — padding and vertical
alignment are utilities once there are no cells.

DOM order is the desktop reading order, so the accessibility tree and the tab
order match what a sighted desktop user sees; only mobile reorders, and there
the sequence read aloud is the same one on screen, wrapped onto two lines.

The rail's dot sat 4px below the tier name because its offset assumed a 24px
line box. These tokens are 1.15 line-height, not Tailwind's 1.5, so a 14px name
centres at ~24px and a 16px one at ~25px.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../src/pages/billing/SpendingLimitsPage.vue  | 236 ++++++++++--------
 1 file changed, 131 insertions(+), 105 deletions(-)

diff --git a/dashboard/src/pages/billing/SpendingLimitsPage.vue b/dashboard/src/pages/billing/SpendingLimitsPage.vue
index c3ccb81f..8cf9cd02 100644
--- a/dashboard/src/pages/billing/SpendingLimitsPage.vue
+++ b/dashboard/src/pages/billing/SpendingLimitsPage.vue
@@ -1,9 +1,17 @@
 <script setup lang="ts">
-import { Button, LoadingText, useCall } from 'frappe-ui'
+import {
+	Breadcrumbs,
+	Button,
+	LoadingText,
+	PageHeader,
+	PageHeaderMobile,
+	useCall,
+} from 'frappe-ui'
 import { computed, ref } from 'vue'
 import { API, method } from '@/api/methods'
 import AddMethodDialog from '@/components/AddMethodDialog.vue'
 import EditBillingProfileDialog from '@/components/billing/EditBillingProfileDialog.vue'
+import NavDrawerTitle from '@/components/navigation/NavDrawerTitle.vue'
 import { useBillingOverview } from '@/composables/useBillingOverview'
 import { useBillingSetup } from '@/composables/useBillingSetup'
 import { useSession } from '@/composables/useSession'
@@ -222,8 +230,28 @@ const levels = computed(() => {
 </script>
 
 <template>
-	<div class="h-full overflow-y-auto">
-		<div class="mx-auto flex w-full max-w-3xl flex-col gap-8 px-6 py-8">
+	<PageHeaderMobile class="sm:hidden">
+		<NavDrawerTitle title="Limit tiers" />
+	</PageHeaderMobile>
+
+	<!-- 'Billing' is the sidebar group these three pages sit in, not a page above
+	     them — Overview is their sibling. So it labels the trail without linking. -->
+	<PageHeader class="hidden sm:flex">
+		<Breadcrumbs
+			:items="[
+				{ label: 'Billing' },
+				{ label: 'Limit tiers', route: { name: 'SpendingLimits' } },
+			]"
+		/>
+	</PageHeader>
+
+	<!-- Desktop-only scroll box: DesktopShell doesn't scroll, so the page owns its
+	     overflow there. On mobile MobileShell is the scroller and this has to get
+	     out of the way, or the bottom nav eats the last rows. -->
+	<div class="sm:h-full sm:overflow-y-auto">
+		<div
+			class="mx-auto flex w-full max-w-3xl flex-col gap-6 px-4 py-6 sm:gap-8 sm:px-6 sm:py-8"
+		>
 			<LoadingText v-if="tier.loading && !tier.data" :lines="6" />
 
 			<template v-else-if="levels.length">
@@ -231,7 +259,7 @@ const levels = computed(() => {
 				     the boxes. Current is reference, so its values sit one size below
 				     the gate values: the page's real news is the unmet gate. -->
 				<section v-if="cur">
-					<p class="text-p-base text-ink-gray-7">
+					<p class="text-p-md text-ink-gray-7 sm:text-p-base">
 						Current:
 						<span class="font-medium text-ink-gray-9">
 							{{ tierLabel(cur) }} tier
@@ -358,94 +386,102 @@ const levels = computed(() => {
 					</div>
 				</section>
 
-				<!-- Tiers table. The rail in the leading column is doing a semantic
-				     job, not a wayfinding one: it says "path you're on", where a bare
-				     table of prices reads as "menu you pick from". -->
-				<!-- No header row: every cell is self-labeling, and the ascending
-				     price edge explains itself. Column widths live in the colgroup
-				     since there are no header cells to carry them. -->
-				<table class="w-full text-left text-base">
-					<colgroup>
-						<col class="w-7" />
-						<col class="w-28" />
-						<col />
-						<col />
-					</colgroup>
-
-					<tbody>
-						<!-- No row dividers: the rail and the row rhythm do the separating,
-						     and a hairline would cut across the timeline. -->
-						<tr v-for="(l, rung) in levels" :key="l.tier">
-							<!-- The travelled track is solid and the road ahead is faint;
-							     both stop at the first and last dots so the ladder reads
-							     bounded rather than running off the table. -->
-							<td class="relative">
-								<!-- bg-surface-*, not bg-outline-*: outline tokens carry no
-								     background value, so a faint line needs a surface tone. -->
-								<span
-									v-if="rung !== 0"
-									class="absolute left-1/2 top-0 h-6 w-px -translate-x-1/2"
-									:class="
-										l.state === 'locked'
-											? 'bg-surface-gray-3'
-											: 'bg-surface-gray-5'
-									"
-									aria-hidden="true"
-								/>
-								<span
-									v-if="rung !== levels.length - 1"
-									class="absolute bottom-0 left-1/2 top-6 w-px -translate-x-1/2"
-									:class="
-										l.state === 'reached'
-											? 'bg-surface-gray-5'
-											: 'bg-surface-gray-3'
-									"
-									aria-hidden="true"
-								/>
-								<span
-									class="absolute left-1/2 top-6 -translate-x-1/2 -translate-y-1/2 rounded-full"
-									:class="DOT_CLASSES[l.state]"
-									aria-hidden="true"
-								/>
-							</td>
+				<!-- The tiers ladder. The rail in the leading column is doing a
+				     semantic job, not a wayfinding one: it says "path you're on",
+				     where a bare list of prices reads as "menu you pick from".
+				     No headings: every value is self-labeling, and the ascending
+				     price edge explains itself.
+
+				     Not a table, because the columns can't all survive 375px. Each
+				     rung is a wrapping flex row instead, so the three fields reflow:
+				     desktop keeps name | requirements | price on one line, and mobile
+				     puts name and price on the first line with the requirements —
+				     the longest field by far — spanning the full width beneath.
+				     Squeezed into a column, "≥ $300.00 paid to date" wrapped to four
+				     lines per rung. -->
+				<ul class="text-lg sm:text-base">
+					<!-- No row dividers: the rail and the row rhythm do the separating,
+					     and a hairline would cut across the timeline. -->
+					<li v-for="(l, rung) in levels" :key="l.tier" class="flex gap-3">
+						<!-- The travelled track is solid and the road ahead is faint;
+						     both stop at the first and last dots so the ladder reads
+						     bounded rather than running off the end. -->
+						<div class="relative w-3 shrink-0" aria-hidden="true">
+							<!-- bg-surface-*, not bg-outline-*: outline tokens carry no
+							     background value, so a faint line needs a surface tone. -->
+							<span
+								v-if="rung !== 0"
+								class="absolute left-1/2 top-0 h-6 w-px -translate-x-1/2"
+								:class="
+									l.state === 'locked'
+										? 'bg-surface-gray-3'
+										: 'bg-surface-gray-5'
+								"
+							/>
+							<span
+								v-if="rung !== levels.length - 1"
+								class="absolute bottom-0 left-1/2 top-6 w-px -translate-x-1/2"
+								:class="
+									l.state === 'reached'
+										? 'bg-surface-gray-5'
+										: 'bg-surface-gray-3'
+								"
+							/>
+							<!-- top-6 = the row's pt-4 (16px) plus half a line box. These
+							     tokens are 1.15 line-height, not Tailwind's 1.5, so a 14px
+							     name centres at ~24px and a 16px one at ~25px — 24 splits
+							     them; 28 sat visibly below the text. -->
+							<span
+								class="absolute left-1/2 top-6 -translate-x-1/2 -translate-y-1/2 rounded-full"
+								:class="DOT_CLASSES[l.state]"
+							/>
+						</div>
 
-							<!-- Rungs behind you dim as whole rows (the rail stays full
-							     strength) so the eye lands on current and next. -->
-							<td :class="l.state === 'reached' ? 'opacity-40' : ''">
-								<span class="font-semibold text-ink-gray-9">
-									{{ tierLabel(l) }}
-								</span>
-							</td>
-
-							<td :class="l.state === 'reached' ? 'opacity-40' : ''">
-								<ul class="flex flex-col gap-1.5">
-									<li
-										v-for="(req, i) in requirementsFor(l)"
-										:key="i"
-										class="flex items-center gap-2"
-									>
-										<span
-											class="size-3.5 shrink-0"
-											:class="
-                          req.met
-                            ? 'lucide-check text-ink-green-5'
-                            : 'lucide-minus text-ink-gray-4'
-                        "
-											aria-hidden="true"
-										/>
-										<span
-											:class="req.met ? 'text-ink-gray-9' : 'text-ink-gray-6'"
-										>
-											{{ req.text }}
-										</span>
-									</li>
-								</ul>
-							</td>
-
-							<td
-								class="text-right"
-								:class="l.state === 'reached' ? 'opacity-40' : ''"
+						<!-- Rungs behind you dim as whole rows (the rail stays full
+						     strength) so the eye lands on current and next. -->
+						<div
+							class="flex min-w-0 flex-1 flex-wrap items-start gap-x-4 gap-y-2 py-4"
+							:class="l.state === 'reached' ? 'opacity-40' : ''"
+						>
+							<!-- DOM order is the desktop reading order — name, requirements,
+							     price — so the accessibility tree and the tab order match what
+							     a sighted desktop user sees (order-* moves neither). Only
+							     mobile reorders, and there the visual order it produces is the
+							     same sequence read aloud, just wrapped onto two lines. -->
+							<span class="order-1 font-semibold text-ink-gray-9 sm:order-none sm:w-28">
+								{{ tierLabel(l) }}
+							</span>
+
+							<!-- w-full is what forces the wrap on mobile; on desktop it
+							     becomes the flexible middle column. -->
+							<ul
+								class="order-3 flex w-full flex-col gap-1.5 sm:order-none sm:w-auto sm:flex-1"
 							>
+								<!-- items-start, not items-center: a requirement that wraps to
+								     two lines would otherwise float its mark between them. -->
+								<li
+									v-for="(req, i) in requirementsFor(l)"
+									:key="i"
+									class="flex items-start gap-2"
+								>
+									<span
+										class="mt-1 size-3.5 shrink-0"
+										:class="
+											req.met
+												? 'lucide-check text-ink-green-5'
+												: 'lucide-minus text-ink-gray-4'
+										"
+										aria-hidden="true"
+									/>
+									<span :class="req.met ? 'text-ink-gray-9' : 'text-ink-gray-6'">
+										{{ req.text }}
+									</span>
+								</li>
+							</ul>
+
+							<!-- order-2 pulls this onto the name's line on mobile; on desktop
+							     it falls back to DOM order, which is already last. -->
+							<div class="order-2 ml-auto text-right sm:order-none">
 								<span
 									class="whitespace-nowrap font-semibold tabular-nums text-ink-gray-9"
 								>
@@ -453,16 +489,16 @@ const levels = computed(() => {
 								</span>
 								<p
 									v-if="l.max_resource_count != null"
-									class="whitespace-nowrap text-p-sm text-ink-gray-5"
+									class="whitespace-nowrap text-p-md text-ink-gray-5 sm:text-p-sm"
 								>
 									up to
 									{{ l.max_resource_count }}
 									resource{{ l.max_resource_count === 1 ? '' : 's' }}
 								</p>
-							</td>
-						</tr>
-					</tbody>
-				</table>
+							</div>
+						</div>
+					</li>
+				</ul>
 
 				<!-- Same fold as billing's Advanced section. -->
 				<section>
@@ -524,13 +560,3 @@ const levels = computed(() => {
 		<AddMethodDialog v-model="showAddMethod" @done="onMethodAdded" />
 	</div>
 </template>
-
-<style scoped>
-/* With no dividers or header, rhythm alone separates the rungs — hence a
-   little more air than the old ruled table had. */
-td {
-	padding-top: 1rem;
-	padding-bottom: 1rem;
-	vertical-align: top;
-}
-</style>

From 329c20a966d4d1851b6c1d68a5617bf89b8a013f Mon Sep 17 00:00:00 2001
From: Sadiq Ansari <sadiqxansari@gmail.com>
Date: Thu, 13 Aug 2026 16:33:59 +0530
Subject: [PATCH 3/5] feat(billing): an invoice receipt is a page on a phone
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Invoices page is a list with a 24rem receipt docked beside it. Nothing docks
beside anything at 375px, so the panel stacked under the list at a fixed 384px —
and since the page auto-opens the newest invoice, a phone landed on a list with
a receipt dangling off the bottom of it.

A row pushes /billing/invoices/:name instead, and Back returns to the list. The
receipt reads the same on both, so its body moves into InvoiceReceipt and the
fetch, the payability rules and the pay wiring move into useInvoiceDetail; the
panel and the page supply only their own chrome. Desktop keeps the docked panel,
its auto-select and its URLs exactly as they were.

Auto-select is desktop-only now: opening a receipt on a phone is a navigation,
and landing on the list only to be carried off it is not what tapping Invoices
asked for. A `?invoice=` deep link did ask for one by name, so that still goes
through — straight to its page. It latches either way, so a later refetch can't
act on a query still sitting in the URL and yank you off a list you were reading.

Widening past `sm` hands the route back to the list with the same invoice open,
the way the settings pages hand back to the dialog.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../src/components/billing/InvoiceReceipt.vue | 201 ++++++++++
 dashboard/src/composables/useInvoiceDetail.ts | 110 ++++++
 .../src/pages/billing/BillingInvoicesPage.vue | 355 ++++--------------
 .../src/pages/billing/InvoiceDetailPage.vue   | 140 +++++++
 dashboard/src/router/index.ts                 |   9 +
 5 files changed, 536 insertions(+), 279 deletions(-)
 create mode 100644 dashboard/src/components/billing/InvoiceReceipt.vue
 create mode 100644 dashboard/src/composables/useInvoiceDetail.ts
 create mode 100644 dashboard/src/pages/billing/InvoiceDetailPage.vue

diff --git a/dashboard/src/components/billing/InvoiceReceipt.vue b/dashboard/src/components/billing/InvoiceReceipt.vue
new file mode 100644
index 00000000..0ff4ae25
--- /dev/null
+++ b/dashboard/src/components/billing/InvoiceReceipt.vue
@@ -0,0 +1,201 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import ChargeBreakdown from '@/components/billing/ChargeBreakdown.vue'
+import { shortDate } from '@/lib/date'
+import { money } from '@/lib/format'
+import type { InvoiceDetail } from '@/types/billing'
+
+// The receipt itself and nothing around it: what the invoice is made of, what it
+// comes to, and what has happened to it. Both hosts supply their own chrome —
+// the docked panel puts identity in its header and Pay in its footer, the mobile
+// page puts them above and below this — so neither lives here.
+const props = defineProps<{
+	invoice: InvoiceDetail
+	/** Owned by useInvoiceDetail, which holds the status rules. */
+	overdue?: boolean
+}>()
+
+// Activity is folded away by default — for a settled invoice the log is
+// reference, not news. Fold it again when switching invoices.
+const activityExpanded = ref(false)
+watch(
+	() => props.invoice.name,
+	() => (activityExpanded.value = false),
+)
+
+// Timeline dot colour per event theme; gray for informational events, so color
+// stays reserved for outcomes.
+const DOTS: Record<string, string> = {
+	green: 'bg-[var(--ink-green-6)]',
+	red: 'bg-[var(--ink-red-6)]',
+}
+const dotClass = (theme: string): string =>
+	DOTS[theme] || 'bg-[var(--ink-gray-4)]'
+
+const paidWithIcon = computed(() =>
+	/upi/i.test(props.invoice.paid_with?.method_type ?? '')
+		? 'lucide-smartphone'
+		: 'lucide-credit-card',
+)
+
+// "31 May 2026, 09:00" → "31 May 2026": the date carries the story; the
+// clock time is noise at timeline granularity.
+const eventDate = (at: string | null): string => String(at ?? '').split(',')[0]
+
+// One gray sentence under the label: amount first, then the backend's detail.
+const eventDetail = (ev: {
+	detail: string | null
+	amount: number
+	currency?: string
+}): string => {
+	const parts: string[] = []
+	if (ev.amount) parts.push(money(ev.amount, ev.currency || props.invoice.currency))
+	if (ev.detail) parts.push(ev.detail)
+	return parts.join(' · ')
+}
+</script>
+
+<template>
+	<div class="flex min-h-0 flex-1 flex-col">
+		<p
+			v-if="overdue"
+			class="flex items-center gap-1.5 px-4 pt-4 text-p-sm text-ink-red-7"
+		>
+			<span class="lucide-triangle-alert size-3.5 shrink-0" />
+			Due {{ shortDate(invoice.due_date) }} — overdue
+		</p>
+
+		<!-- Receipt: plan charges per server, then metered add-ons — each
+         section a plain eyebrow with its subtotal, like the V2 receipt. -->
+		<!-- No inner scroll: the panel already scrolls, and a second scroller
+		     here clipped the receipt mid-row once a team had more than one
+		     machine on the invoice. -->
+		<div class="shrink-0 px-4 pt-4">
+			<ChargeBreakdown :lines="invoice.items" :currency="invoice.currency" />
+		</div>
+
+		<!-- Cost breakdown + Activity -->
+		<div class="mt-4 border-t border-outline-gray-2 px-4">
+			<dl class="space-y-2 py-3 text-sm">
+				<div class="flex justify-between gap-3">
+					<dt class="text-ink-gray-5">Subtotal</dt>
+					<dd class="tabular-nums text-ink-gray-8">
+						{{ money(invoice.subtotal, invoice.currency) }}
+					</dd>
+				</div>
+				<div v-if="invoice.output_tax_amount" class="flex justify-between gap-3">
+					<dt class="text-ink-gray-5">
+						{{ invoice.output_tax_type || 'Tax' }}
+						<template v-if="invoice.output_tax_rate">
+							({{ invoice.output_tax_rate }}%)</template
+						>
+					</dt>
+					<dd class="tabular-nums text-ink-gray-8">
+						{{ money(invoice.output_tax_amount, invoice.currency) }}
+					</dd>
+				</div>
+				<p v-if="invoice.zero_rating_reason" class="text-p-sm text-ink-gray-5">
+					{{ invoice.zero_rating_reason }}
+				</p>
+				<div v-if="invoice.credit_applied" class="flex justify-between gap-3">
+					<dt class="text-ink-green-5">Credits applied</dt>
+					<dd class="tabular-nums text-ink-green-5">
+						−{{ money(invoice.credit_applied, invoice.currency) }}
+					</dd>
+				</div>
+				<div
+					class="mt-1 flex justify-between gap-3 border-t border-outline-gray-1 pt-2.5 font-semibold"
+				>
+					<dt class="text-ink-gray-8">Total</dt>
+					<dd class="tabular-nums text-ink-gray-9">
+						{{ money(invoice.total, invoice.currency) }}
+					</dd>
+				</div>
+				<!-- Which method settled it — a quiet receipt line, not a form
+             row. Falls back to the paid amount when the method is gone. -->
+				<div
+					v-if="invoice.paid_with"
+					class="flex justify-between gap-3 text-p-sm text-ink-gray-5"
+				>
+					<dt>Paid with</dt>
+					<dd class="flex min-w-0 items-center gap-1.5">
+						<span
+							class="size-3.5 shrink-0 text-ink-gray-4"
+							:class="paidWithIcon"
+							aria-hidden="true"
+						/>
+						<span class="truncate">{{ invoice.paid_with.label }}</span>
+					</dd>
+				</div>
+				<div
+					v-else-if="invoice.amount_paid"
+					class="flex justify-between gap-3 text-p-sm text-ink-gray-5"
+				>
+					<dt>Paid</dt>
+					<dd class="tabular-nums">
+						{{ money(invoice.amount_paid, invoice.currency) }}
+					</dd>
+				</div>
+			</dl>
+
+			<!-- Activity — this invoice's own history. Folded away entirely:
+           for a settled invoice the log is reference, not news. -->
+			<section
+				v-if="invoice.activity?.length"
+				class="border-t border-outline-gray-1 py-3"
+			>
+				<button
+					class="flex w-full items-center gap-1.5 text-left"
+					:aria-expanded="activityExpanded"
+					@click="activityExpanded = !activityExpanded"
+				>
+					<span
+						class="lucide-chevron-right size-3.5 shrink-0 text-ink-gray-5 transition-transform duration-150 ease-out"
+						:class="activityExpanded ? 'rotate-90' : ''"
+					/>
+					<h3 class="text-sm-medium text-ink-gray-8">Activity</h3>
+					<span class="text-p-sm text-ink-gray-5">
+						{{ invoice.activity.length }}
+					</span>
+				</button>
+				<ol v-if="activityExpanded" class="relative mt-3">
+					<li
+						v-for="(ev, idx) in invoice.activity"
+						:key="idx"
+						class="relative flex gap-3 pb-4 last:pb-0"
+					>
+						<!-- Rail: one continuous line running through the column, with
+                 the solid dot sitting on top of it. The line is dropped on
+                 the last row so it doesn't dangle. -->
+						<div class="relative flex w-2.5 shrink-0 justify-center">
+							<span
+								v-if="idx < invoice.activity.length - 1"
+								class="absolute left-1/2 top-2 h-[calc(100%+1rem)] w-px -translate-x-1/2 bg-[var(--outline-gray-2)]"
+							/>
+							<span
+								class="relative z-10 mt-1 size-2 shrink-0 rounded-full"
+								:class="dotClass(ev.theme)"
+							/>
+						</div>
+						<div class="min-w-0 flex-1">
+							<div class="flex items-baseline justify-between gap-2">
+								<span class="text-sm-medium text-ink-gray-8">
+									{{ ev.title }}
+								</span>
+								<span class="shrink-0 tabular-nums text-p-sm text-ink-gray-5">
+									{{ eventDate(ev.at) }}
+								</span>
+							</div>
+							<p
+								v-if="eventDetail(ev)"
+								class="mt-0.5 break-words text-p-sm text-ink-gray-5"
+							>
+								{{ eventDetail(ev) }}
+							</p>
+						</div>
+					</li>
+				</ol>
+			</section>
+		</div>
+	</div>
+</template>
diff --git a/dashboard/src/composables/useInvoiceDetail.ts b/dashboard/src/composables/useInvoiceDetail.ts
new file mode 100644
index 00000000..473f6573
--- /dev/null
+++ b/dashboard/src/composables/useInvoiceDetail.ts
@@ -0,0 +1,110 @@
+import { useCall } from 'frappe-ui'
+import { computed, type MaybeRefOrGetter, toValue, watch } from 'vue'
+import { API, method } from '@/api/methods'
+import { useCapabilities } from '@/composables/useCapabilities'
+import { usePayInvoice } from '@/composables/usePayInvoice'
+import { usePayInvoiceCheckout } from '@/composables/usePayInvoiceCheckout'
+import { teamParams, whenTeamReady } from '@/composables/useTeamScope'
+import type { CollectionStatus, InvoiceDetail } from '@/types/billing'
+
+// One invoice receipt has two hosts: the docked panel on the Invoices page and,
+// on a phone where there's no room to dock anything, the /billing/invoices/:name
+// page. They frame it differently but read the same invoice under the same
+// rules, so the fetch, the payability tests and the pay wiring live here instead
+// of in either of them. The caller names the invoice — the selected row on
+// desktop, the route param on mobile — and `onPaid` refreshes whatever else that
+// host has on screen (the list) once money moves.
+
+// Each presentation owns its own URL space, like settings does: /billing/invoices
+// is the list (which opens a receipt beside it on desktop) and the child path is
+// the mobile receipt page.
+export const INVOICES_PATH = '/billing/invoices'
+export const invoicePath = (name: string): string =>
+	`${INVOICES_PATH}/${encodeURIComponent(name)}`
+
+export function useInvoiceDetail(
+	name: MaybeRefOrGetter<string | null>,
+	{ onPaid }: { onPaid?: () => void } = {},
+) {
+	const { canManageBilling } = useCapabilities()
+
+	const collection = useCall<CollectionStatus, { team: string }>({
+		url: method(API.collectionStatus),
+		params: teamParams,
+		immediate: false,
+		refetch: true,
+	})
+	whenTeamReady(() => collection.reload())
+
+	const detail = useCall<InvoiceDetail, { name: string }>({
+		url: method(API.invoice),
+		immediate: false,
+	})
+
+	// Follow whatever the host points at. A cleared name is not a fetch: the panel
+	// keeps rendering the last receipt while it slides out, and blanking the body
+	// mid-animation is the thing its `shown` ref exists to prevent.
+	watch(
+		() => toValue(name),
+		(invoice) => {
+			if (invoice) detail.submit({ name: invoice })
+		},
+		{ immediate: true },
+	)
+
+	// Open OR Overdue is still collectable — an overdue invoice is the one the customer
+	// most needs to settle (dunning failed on the card), so it must offer Pay too.
+	const isPayable = computed(() =>
+		['open', 'overdue'].includes(String(detail.data?.status).toLowerCase()),
+	)
+	// The receipt's one pre-items line, and only in the problem state — its single
+	// use of color above the fold.
+	const isOverdue = computed(
+		() =>
+			String(detail.data?.status).toLowerCase() === 'overdue' &&
+			!!detail.data?.due_date,
+	)
+	// A charge already in flight (or captured, awaiting the settlement webhook) means
+	// the money is moving — show a "settling" status, never a second Pay button.
+	const settling = computed(
+		() => isPayable.value && !!detail.data?.payment_in_progress,
+	)
+	// Only offer Pay when something is actually collectable — a zero-due invoice
+	// (e.g. a trial Cost Report) must never render a "Pay 0.00" button.
+	const hasDue = computed(() => Number(detail.data?.expected_collection) > 0)
+	const canPay = computed(
+		() =>
+			canManageBilling.value &&
+			isPayable.value &&
+			!settling.value &&
+			hasDue.value,
+	)
+
+	// Re-read this invoice after a charge, and let the host re-read whatever it
+	// shows alongside (the list's status column moves with the receipt).
+	function refresh(): void {
+		const invoice = toValue(name)
+		if (invoice) detail.submit({ name: invoice })
+		onPaid?.()
+	}
+	const { run: payInvoice, loading: paying } = usePayInvoice({
+		onDone: refresh,
+	})
+	const { run: payCheckout, loading: payingCheckout } = usePayInvoiceCheckout({
+		onDone: refresh,
+	})
+
+	// manual_checkout teams settle on-session (any amount, no ₹15k limit); everyone
+	// else uses the off-session charge against their saved method.
+	const manualMode = computed(
+		() => collection.data?.collection_mode === 'Manual Checkout',
+	)
+	const payBusy = computed(() => paying.value || payingCheckout.value)
+	async function pay(): Promise<void> {
+		const invoice = detail.data?.name
+		if (!invoice) return
+		await (manualMode.value ? payCheckout(invoice) : payInvoice(invoice))
+	}
+
+	return { detail, isOverdue, settling, canPay, payBusy, pay }
+}
diff --git a/dashboard/src/pages/billing/BillingInvoicesPage.vue b/dashboard/src/pages/billing/BillingInvoicesPage.vue
index 7deed1e5..96f976ac 100644
--- a/dashboard/src/pages/billing/BillingInvoicesPage.vue
+++ b/dashboard/src/pages/billing/BillingInvoicesPage.vue
@@ -1,55 +1,45 @@
 <script setup lang="ts">
-import { Badge, Button, LoadingText, Spinner, useCall } from 'frappe-ui'
-import { computed, ref, watch } from 'vue'
-import { useRoute } from 'vue-router'
-import { API, method } from '@/api/methods'
+import {
+	Badge,
+	Breadcrumbs,
+	Button,
+	LoadingText,
+	PageHeader,
+	PageHeaderMobile,
+	Spinner,
+} from 'frappe-ui'
+import { ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
 import InvoiceListView from '@/components/billing/InvoiceListView.vue'
+import InvoiceReceipt from '@/components/billing/InvoiceReceipt.vue'
 import SidePanel from '@/components/common/SidePanel.vue'
-import { useCapabilities } from '@/composables/useCapabilities'
+import NavDrawerTitle from '@/components/navigation/NavDrawerTitle.vue'
+import { invoicePath, useInvoiceDetail } from '@/composables/useInvoiceDetail'
 import { useInvoices } from '@/composables/useInvoices'
-import { usePayInvoice } from '@/composables/usePayInvoice'
-import { usePayInvoiceCheckout } from '@/composables/usePayInvoiceCheckout'
+import { useIsMobile } from '@/composables/useIsMobile'
 import { useSession } from '@/composables/useSession'
-import { teamParams, whenTeamReady } from '@/composables/useTeamScope'
 import { billingPeriod, shortDate } from '@/lib/date'
 import { money } from '@/lib/format'
 import { invoiceTheme } from '@/lib/status'
-import type {
-	CollectionStatus,
-	InvoiceDetail,
-	InvoiceSummary,
-} from '@/types/billing'
+import type { InvoiceSummary } from '@/types/billing'
 
 // Billing › Invoices (#70) — list (left) + docked 24rem receipt panel (right)
 // that slides in, mirroring the FC V2 prototype's invoice anatomy. Invoices come
 // from the team-scoped list_invoices/get_invoice endpoints (curated fields, not
 // raw reportview), so we filter client-side over that list.
+// A phone gets the list alone: there's no room to dock 24rem beside it, so a row
+// pushes /billing/invoices/:name instead and the receipt is a page of its own.
 const route = useRoute()
-const { canManageBilling } = useCapabilities()
+const router = useRouter()
+const isMobile = useIsMobile()
 const {
 	invoices,
 	loading: invoicesLoading,
 	reload: reloadInvoices,
 } = useInvoices()
 
-const collection = useCall<CollectionStatus, { team: string }>({
-	url: method(API.collectionStatus),
-	params: teamParams,
-	immediate: false,
-	refetch: true,
-})
-whenTeamReady(() => collection.reload())
-
 // ── Detail panel ──
 const selected = ref<InvoiceSummary | null>(null)
-const detail = useCall<InvoiceDetail, { name: string }>({
-	url: method(API.invoice),
-	immediate: false,
-})
-
-// Activity is folded away by default — for a settled invoice the log is
-// reference, not news. Fold it again when switching invoices.
-const activityExpanded = ref(false)
 
 // Holds the invoice while the panel slides out, so the receipt doesn't blank
 // mid-animation. `detail` keeps its data, so the body follows suit.
@@ -58,10 +48,16 @@ watch(selected, (invoice) => {
 	if (invoice) shown.value = invoice
 })
 
-async function selectRow(inv: InvoiceSummary): Promise<void> {
-	selected.value = inv
-	activityExpanded.value = false
-	await detail.submit({ name: inv.name })
+const { detail, isOverdue, settling, canPay, payBusy, pay } = useInvoiceDetail(
+	() => selected.value?.name ?? null,
+	{ onPaid: reloadInvoices },
+)
+
+// A row means "show me this invoice" — which is the panel here and a page on a
+// phone, where the panel doesn't render at all.
+function selectRow(inv: InvoiceSummary): void {
+	if (isMobile.value) router.push(invoicePath(inv.name))
+	else selected.value = inv
 }
 
 // Open the latest invoice expanded on first load — list_invoices is ordered newest
@@ -73,10 +69,23 @@ watch(
 	() => invoices.value,
 	(rows) => {
 		if (autoSelected || selected.value || !rows.length) return
+		const wanted = String(route.query.invoice ?? '')
+		const asked = wanted ? rows.find((r) => r.name === wanted) : undefined
+		// Nothing auto-opens on mobile: opening a receipt there is a navigation, and
+		// landing on the list only to be carried off it is not what tapping Invoices
+		// asked for. A deep link did ask for one invoice by name, so that still goes
+		// through — straight to its page, replacing so Back returns to the list.
+		if (isMobile.value) {
+			// Latch either way. Only the first list this page sees may carry you
+			// off it: leaving it unlatched means a later refetch — a payment, a
+			// team switch — can act on a `?invoice=` still sitting in the URL and
+			// yank you off a list you've been reading for minutes.
+			autoSelected = true
+			if (asked) router.replace(invoicePath(asked.name))
+			return
+		}
 		autoSelected = true
-		const wanted = route.query.invoice
-		const row = (wanted && rows.find((r) => r.name === wanted)) || rows[0]
-		selectRow(row)
+		selectRow(asked ?? rows[0])
 	},
 	{ immediate: true },
 )
@@ -91,93 +100,32 @@ watch(activeTeam, (team, previous) => {
 	shown.value = null
 	autoSelected = false
 })
-
-// Open OR Overdue is still collectable — an overdue invoice is the one the customer
-// most needs to settle (dunning failed on the card), so it must offer Pay too.
-const isPayable = computed(() =>
-	['open', 'overdue'].includes(String(detail.data?.status).toLowerCase()),
-)
-// The panel's one pre-items line, and only in the problem state — its single
-// use of color above the fold.
-const isOverdue = computed(
-	() =>
-		String(detail.data?.status).toLowerCase() === 'overdue' &&
-		!!detail.data?.due_date,
-)
-// A charge already in flight (or captured, awaiting the settlement webhook) means
-// the money is moving — show a "settling" status, never a second Pay button.
-const settling = computed(
-	() => isPayable.value && !!detail.data?.payment_in_progress,
-)
-// Only offer Pay when something is actually collectable — a zero-due invoice
-// (e.g. a trial Cost Report) must never render a "Pay 0.00" button.
-const hasDue = computed(() => Number(detail.data?.expected_collection) > 0)
-const canPay = computed(
-	() =>
-		canManageBilling.value &&
-		isPayable.value &&
-		!settling.value &&
-		hasDue.value,
-)
-
-function refresh(): void {
-	reloadInvoices()
-	if (selected.value) detail.submit({ name: selected.value.name })
-}
-const { run: payInvoice, loading: paying } = usePayInvoice({ onDone: refresh })
-const { run: payCheckout, loading: payingCheckout } = usePayInvoiceCheckout({
-	onDone: refresh,
-})
-
-// manual_checkout teams settle on-session (any amount, no ₹15k limit); everyone
-// else uses the off-session charge against their saved method.
-const manualMode = computed(
-	() => collection.data?.collection_mode === 'Manual Checkout',
-)
-const payBusy = computed(() => paying.value || payingCheckout.value)
-function pay(name: string): Promise<unknown> {
-	return manualMode.value ? payCheckout(name) : payInvoice(name)
-}
-
-// Timeline dot colour per event theme; gray for informational events, so color
-// stays reserved for outcomes.
-const DOTS: Record<string, string> = {
-	green: 'bg-[var(--ink-green-6)]',
-	red: 'bg-[var(--ink-red-6)]',
-}
-const dotClass = (theme: string): string =>
-	DOTS[theme] || 'bg-[var(--ink-gray-4)]'
-
-
-const paidWithIcon = computed(() =>
-	/upi/i.test(detail.data?.paid_with?.method_type ?? '')
-		? 'lucide-smartphone'
-		: 'lucide-credit-card',
-)
-
-// "31 May 2026, 09:00" → "31 May 2026": the date carries the story; the
-// clock time is noise at timeline granularity.
-const eventDate = (at: string | null): string => String(at ?? '').split(',')[0]
-
-// One gray sentence under the label: amount first, then the backend's detail.
-const eventDetail = (ev: {
-	detail: string | null
-	amount: number
-	currency?: string
-}): string => {
-	const parts: string[] = []
-	if (ev.amount)
-		parts.push(money(ev.amount, ev.currency || detail.data?.currency))
-	if (ev.detail) parts.push(ev.detail)
-	return parts.join(' · ')
-}
 </script>
 
 <template>
-	<div class="flex h-full min-h-0">
+	<PageHeaderMobile class="sm:hidden">
+		<NavDrawerTitle title="Invoices" />
+	</PageHeaderMobile>
+
+	<!-- 'Billing' is the sidebar group Invoices sits in, not a page above it —
+	     Overview is its sibling. So it labels the trail without linking. -->
+	<PageHeader class="hidden sm:flex">
+		<Breadcrumbs
+			:items="[
+				{ label: 'Billing' },
+				{ label: 'Invoices', route: { name: 'BillingInvoices' } },
+			]"
+		/>
+	</PageHeader>
+
+	<!-- The list/receipt row is desktop-only scaffolding: DesktopShell doesn't
+	     scroll, so the panes own their overflow there. On mobile MobileShell is
+	     the scroller and the page has to fall through to it, or the bottom nav
+	     eats the last rows. -->
+	<div class="sm:flex sm:h-full sm:min-h-0">
 		<!-- LIST — capped and centered so rows stay scannable when the panel is
          closed; the cap matches the Limit tiers page. -->
-		<div class="min-w-0 flex-1 overflow-y-auto">
+		<div class="sm:min-w-0 sm:flex-1 sm:overflow-y-auto">
 			<div class="mx-auto w-full max-w-3xl px-4 py-5 sm:px-6">
 				<InvoiceListView
 					:invoices="invoices"
@@ -191,9 +139,12 @@ const eventDetail = (ev: {
 		<!-- Docked receipt panel — the shared SidePanel, slides in beside the
          list, never over it. Header carries all invoice identity: number +
          status together, so the body never needs a labelled "Status" row.
+         Desktop only: at 24rem it can't sit beside anything on a phone, and
+         stacked under the list it's just an overflowing second screen.
          GROUNDING GAP (#70): no email-invoice / download-PDF endpoints yet,
          so both header actions stay disabled until the backend lands them. -->
 		<SidePanel
+			v-if="!isMobile"
 			:open="!!selected"
 			@update:open="(v: boolean) => !v && (selected = null)"
 		>
@@ -240,165 +191,11 @@ const eventDetail = (ev: {
 				<LoadingText :lines="6" />
 			</div>
 
-			<!-- Body: the receipt list scrolls on its own; the cost breakdown and
-           Activity sit below it, so the totals never shift as the list
-           scrolls. Activity opens below and is revealed by scrolling. -->
-			<div v-else-if="detail.data" class="flex min-h-0 flex-1 flex-col">
-					<p
-						v-if="isOverdue"
-						class="flex items-center gap-1.5 px-4 pt-4 text-p-sm text-ink-red-7"
-					>
-						<span class="lucide-triangle-alert size-3.5 shrink-0" />
-						Due {{ shortDate(detail.data.due_date) }} — overdue
-					</p>
-
-					<!-- Receipt: plan charges per server, then metered add-ons — each
-               section a plain eyebrow with its subtotal, like the V2 receipt. -->
-					<!-- No inner scroll: the panel already scrolls, and a second scroller
-					     here clipped the receipt mid-row once a team had more than one
-					     machine on the invoice. -->
-					<div class="shrink-0 px-4 pt-4">
-						<ChargeBreakdown
-							:lines="detail.data.items"
-							:currency="detail.data.currency"
-						/>
-					</div>
-
-					<!-- Cost breakdown + Activity -->
-					<div class="mt-4 border-t border-outline-gray-2 px-4">
-						<dl class="space-y-2 py-3 text-sm">
-							<div class="flex justify-between gap-3">
-								<dt class="text-ink-gray-5">Subtotal</dt>
-								<dd class="tabular-nums text-ink-gray-8">
-									{{ money(detail.data.subtotal, detail.data.currency) }}
-								</dd>
-							</div>
-							<div
-								v-if="detail.data.output_tax_amount"
-								class="flex justify-between gap-3"
-							>
-								<dt class="text-ink-gray-5">
-									{{ detail.data.output_tax_type || 'Tax' }}
-									<template v-if="detail.data.output_tax_rate">
-										({{ detail.data.output_tax_rate }}%)</template
-									>
-								</dt>
-								<dd class="tabular-nums text-ink-gray-8">
-									{{ money(detail.data.output_tax_amount, detail.data.currency) }}
-								</dd>
-							</div>
-							<p
-								v-if="detail.data.zero_rating_reason"
-								class="text-p-sm text-ink-gray-5"
-							>
-								{{ detail.data.zero_rating_reason }}
-							</p>
-							<div
-								v-if="detail.data.credit_applied"
-								class="flex justify-between gap-3"
-							>
-								<dt class="text-ink-green-5">Credits applied</dt>
-								<dd class="tabular-nums text-ink-green-5">
-									−{{ money(detail.data.credit_applied, detail.data.currency) }}
-								</dd>
-							</div>
-							<div
-								class="mt-1 flex justify-between gap-3 border-t border-outline-gray-1 pt-2.5 font-semibold"
-							>
-								<dt class="text-ink-gray-8">Total</dt>
-								<dd class="tabular-nums text-ink-gray-9">
-									{{ money(detail.data.total, detail.data.currency) }}
-								</dd>
-							</div>
-							<!-- Which method settled it — a quiet receipt line, not a form
-                   row. Falls back to the paid amount when the method is gone. -->
-							<div
-								v-if="detail.data.paid_with"
-								class="flex justify-between gap-3 text-p-sm text-ink-gray-5"
-							>
-								<dt>Paid with</dt>
-								<dd class="flex min-w-0 items-center gap-1.5">
-									<span
-										class="size-3.5 shrink-0 text-ink-gray-4"
-										:class="paidWithIcon"
-										aria-hidden="true"
-									/>
-									<span class="truncate">{{ detail.data.paid_with.label }}</span>
-								</dd>
-							</div>
-							<div
-								v-else-if="detail.data.amount_paid"
-								class="flex justify-between gap-3 text-p-sm text-ink-gray-5"
-							>
-								<dt>Paid</dt>
-								<dd class="tabular-nums">
-									{{ money(detail.data.amount_paid, detail.data.currency) }}
-								</dd>
-							</div>
-						</dl>
-
-						<!-- Activity — this invoice's own history. Folded away entirely:
-                 for a settled invoice the log is reference, not news. -->
-						<section
-							v-if="detail.data.activity?.length"
-							class="border-t border-outline-gray-1 py-3"
-						>
-							<button
-								class="flex w-full items-center gap-1.5 text-left"
-								:aria-expanded="activityExpanded"
-								@click="activityExpanded = !activityExpanded"
-							>
-								<span
-									class="lucide-chevron-right size-3.5 shrink-0 text-ink-gray-5 transition-transform duration-150 ease-out"
-									:class="activityExpanded ? 'rotate-90' : ''"
-								/>
-								<h3 class="text-sm-medium text-ink-gray-8">Activity</h3>
-								<span class="text-p-sm text-ink-gray-5">
-									{{ detail.data.activity.length }}
-								</span>
-							</button>
-							<ol v-if="activityExpanded" class="relative mt-3">
-								<li
-									v-for="(ev, idx) in detail.data.activity"
-									:key="idx"
-									class="relative flex gap-3 pb-4 last:pb-0"
-								>
-									<!-- Rail: one continuous line running through the column, with
-                       the solid dot sitting on top of it. The line is dropped on
-                       the last row so it doesn't dangle. -->
-									<div class="relative flex w-2.5 shrink-0 justify-center">
-										<span
-											v-if="idx < detail.data.activity.length - 1"
-											class="absolute left-1/2 top-2 h-[calc(100%+1rem)] w-px -translate-x-1/2 bg-[var(--outline-gray-2)]"
-										/>
-										<span
-											class="relative z-10 mt-1 size-2 shrink-0 rounded-full"
-											:class="dotClass(ev.theme)"
-										/>
-									</div>
-									<div class="min-w-0 flex-1">
-										<div class="flex items-baseline justify-between gap-2">
-											<span class="text-sm-medium text-ink-gray-8">
-												{{ ev.title }}
-											</span>
-											<span
-												class="shrink-0 tabular-nums text-p-sm text-ink-gray-5"
-											>
-												{{ eventDate(ev.at) }}
-											</span>
-										</div>
-										<p
-											v-if="eventDetail(ev)"
-											class="mt-0.5 break-words text-p-sm text-ink-gray-5"
-										>
-											{{ eventDetail(ev) }}
-										</p>
-									</div>
-								</li>
-							</ol>
-						</section>
-					</div>
-				</div>
+			<InvoiceReceipt
+				v-else-if="detail.data"
+				:invoice="detail.data"
+				:overdue="isOverdue"
+			/>
 
 			<!-- The footer carries only the one state-dependent action. Settling an
            invoice is the helpful way out of an overdue state, not a
@@ -411,7 +208,7 @@ const eventDetail = (ev: {
 					icon-left="lucide-credit-card"
 					:label="`Pay ${money(detail.data.expected_collection, detail.data.currency)} now`"
 					:loading="payBusy"
-					@click="pay(detail.data.name)"
+					@click="pay()"
 				/>
 				<div
 					v-else
diff --git a/dashboard/src/pages/billing/InvoiceDetailPage.vue b/dashboard/src/pages/billing/InvoiceDetailPage.vue
new file mode 100644
index 00000000..9f13e085
--- /dev/null
+++ b/dashboard/src/pages/billing/InvoiceDetailPage.vue
@@ -0,0 +1,140 @@
+<script setup lang="ts">
+import {
+	Badge,
+	Button,
+	LoadingText,
+	PageHeaderBackButton,
+	PageHeaderMobile,
+	Spinner,
+} from 'frappe-ui'
+import { computed, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import InvoiceReceipt from '@/components/billing/InvoiceReceipt.vue'
+import { INVOICES_PATH, useInvoiceDetail } from '@/composables/useInvoiceDetail'
+import { useInvoices } from '@/composables/useInvoices'
+import { useIsMobile } from '@/composables/useIsMobile'
+import { billingPeriod, shortDate } from '@/lib/date'
+import { money } from '@/lib/format'
+import { invoiceTheme } from '@/lib/status'
+import { isAbortError } from '@/lib/toast'
+
+// One invoice receipt as a full page. A phone has no room for the 24rem panel
+// the Invoices page docks beside its list, so a row pushes this instead and Back
+// goes where you'd expect. Same body, different chrome.
+const route = useRoute()
+const router = useRouter()
+const isMobile = useIsMobile()
+const { reload: reloadInvoices } = useInvoices()
+
+const name = computed(() => String(route.params.name ?? ''))
+const { detail, isOverdue, settling, canPay, payBusy, pay } = useInvoiceDetail(
+	name,
+	{ onPaid: reloadInvoices },
+)
+
+// The number is the one piece of identity the header can hold. The route already
+// names it, so it's there before the fetch lands and the header never opens empty.
+const title = computed(() => detail.data?.name || name.value)
+
+watch(
+	isMobile,
+	(mobile) => {
+		// Widened past the breakpoint (a resize, a rotate): this invoice has a panel
+		// to live in now, so follow it across. `?invoice=` is how the list is asked
+		// to open a receipt it wasn't clicked into — the same door global search uses.
+		if (!mobile)
+			router.replace({ path: INVOICES_PATH, query: { invoice: name.value } })
+	},
+	{ immediate: true },
+)
+
+// A name nothing comes back for (a stale link, an invoice from another team)
+// belongs back at the list rather than on a blank page. An aborted read isn't a
+// failure — a team switch supersedes the one in flight.
+watch(
+	() => detail.error,
+	(error) => {
+		if (error && !isAbortError(error)) router.replace(INVOICES_PATH)
+	},
+)
+</script>
+
+<template>
+	<!-- No desktop PageHeader and no `sm:hidden`: the watcher above hands this
+	     route over to the list's docked panel the moment it isn't mobile, so the
+	     page never renders at desktop width. -->
+	<PageHeaderMobile :title="title">
+		<template #prefix>
+			<PageHeaderBackButton :to="INVOICES_PATH" />
+		</template>
+		<!-- The panel's header actions, in the header a page has. GROUNDING GAP
+		     (#70): no email-invoice / download-PDF endpoints yet, so both stay
+		     disabled until the backend lands them. -->
+		<template #suffix>
+			<Button
+				variant="ghost"
+				icon="lucide-mail"
+				:disabled="true"
+				title="Email invoice — coming soon"
+				label="Email invoice"
+			/>
+			<Button
+				variant="ghost"
+				icon="lucide-download"
+				:disabled="true"
+				title="Download PDF — coming soon"
+				label="Download PDF"
+			/>
+		</template>
+	</PageHeaderMobile>
+
+	<div v-if="detail.loading && !detail.data" class="space-y-3 p-4">
+		<LoadingText :lines="6" />
+	</div>
+
+	<div v-else-if="detail.data" class="mx-auto w-full max-w-3xl pb-5">
+		<!-- The rest of the identity the panel carries in its header. The mobile
+		     header centers its title between two 35%-wide slots, so only the number
+		     fits up there; status and period read as the receipt's first line. -->
+		<header class="flex flex-wrap items-center gap-x-2 gap-y-1 px-4 pt-4">
+			<Badge
+				:theme="invoiceTheme(detail.data.status)"
+				variant="subtle"
+				:label="detail.data.status"
+			/>
+			<span class="text-p-sm text-ink-gray-5">
+				{{ detail.data.invoice_type }}
+				·
+				{{ billingPeriod(detail.data.period_start, detail.data.period_end) }}
+				<span v-if="detail.data.due_date">
+					· Due {{ shortDate(detail.data.due_date) }}</span
+				>
+			</span>
+		</header>
+
+		<InvoiceReceipt :invoice="detail.data" :overdue="isOverdue" />
+
+		<!-- The panel pins this in a footer; a page has no footer to pin to, so the
+		     one state-dependent action closes the receipt out. Settling an invoice
+		     is the helpful way out of an overdue state, not a destructive act —
+		     the default solid, not red. -->
+		<div v-if="canPay || settling" class="px-4 pt-4">
+			<Button
+				v-if="canPay"
+				variant="solid"
+				class="w-full"
+				icon-left="lucide-credit-card"
+				:label="`Pay ${money(detail.data.expected_collection, detail.data.currency)} now`"
+				:loading="payBusy"
+				@click="pay()"
+			/>
+			<div
+				v-else
+				class="flex items-center justify-center gap-2 py-1 text-p-sm text-ink-gray-6"
+			>
+				<Spinner size="md" />
+				<span>Waiting for your bank to confirm the payment…</span>
+			</div>
+		</div>
+	</div>
+</template>
diff --git a/dashboard/src/router/index.ts b/dashboard/src/router/index.ts
index b8e3002a..2b909f6c 100644
--- a/dashboard/src/router/index.ts
+++ b/dashboard/src/router/index.ts
@@ -83,6 +83,15 @@ const routes = [
 				component: () => import('@/pages/billing/BillingInvoicesPage.vue'),
 				meta: { title: 'Invoices' },
 			},
+			// The receipt only needs an address of its own on mobile, where it's a
+			// page instead of the panel docked beside the list. Arriving at desktop
+			// width hands straight back to /billing/invoices?invoice=.
+			{
+				path: 'billing/invoices/:name',
+				name: 'BillingInvoice',
+				component: () => import('@/pages/billing/InvoiceDetailPage.vue'),
+				meta: { title: 'Invoice' },
+			},
 			{
 				path: 'billing/reports',
 				name: 'BillingReports',

From 48219ebf2c3487aef39df5cb531622764d5903b4 Mon Sep 17 00:00:00 2001
From: Sadiq Ansari <sadiqxansari@gmail.com>
Date: Thu, 13 Aug 2026 16:33:59 +0530
Subject: [PATCH 4/5] fix(ui): the docked side panel is a sheet on a phone
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SidePanel is a 24rem column that slides in beside the content, hosted as the
last child of a `flex h-full` row. Once pages hand their scroll to the shell
there is no such row on mobile, so the panel stacked below the content at a
fixed 384px on a 375px viewport.

Invoices got a route because a receipt is a destination. The rest — wallet
history, role capabilities, and the four billing trays — are peeks opened from a
card, so they don't want URLs; they want the panel to stop pretending it can
dock. Below `sm` it presents as a full-screen sheet, and every consumer gets
that from one place.

A sheet is modal in a way the docked panel never was: it covers the page rather
than sitting beside it. So on mobile it announces as a dialog, takes focus when
it opens and gives it back when it closes — otherwise Close leaves focus on a
row that is no longer rendered. The Escape guard skips the panel's own root,
or the role it just gained would match the "a stacked dialog owns Escape first"
test and Escape would stop working entirely.

The wallet ledger had its own scroller nested inside the panel's — harmless
while the panel was a short column, a trap once it is the whole screen. Same
nesting #281 removed from the invoice receipt.

RoleCapabilitiesPanel teleported to #team-page-aside, which existed nowhere in
the repo: it had never rendered, on any viewport, since the commit that
introduced it. Adding the target switches it on — on desktop as well as mobile.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../components/billing/WalletHistoryPanel.vue |  7 +-
 dashboard/src/components/common/SidePanel.vue | 67 ++++++++++++++++---
 dashboard/src/pages/team/AccessPage.vue       |  1 +
 3 files changed, 65 insertions(+), 10 deletions(-)

diff --git a/dashboard/src/components/billing/WalletHistoryPanel.vue b/dashboard/src/components/billing/WalletHistoryPanel.vue
index 10db1774..62752399 100644
--- a/dashboard/src/components/billing/WalletHistoryPanel.vue
+++ b/dashboard/src/components/billing/WalletHistoryPanel.vue
@@ -57,8 +57,11 @@ function isCredit(entry: CreditLedgerEntry): boolean {
 			/>
 		</div>
 
-			<!-- Ledger -->
-			<div class="min-h-0 flex-1 overflow-y-auto">
+			<!-- Ledger. No inner scroll: SidePanel's body already scrolls, and a
+			     second scroller here traps the ledger in a short box — worst on the
+			     mobile sheet, where the panel is the full screen and the ledger got
+			     a sliver of it. Same fix the invoice receipt took. -->
+			<div>
 				<div v-if="ledger.loading && !ledger.data" class="space-y-3 p-4">
 					<LoadingText :lines="5" />
 				</div>
diff --git a/dashboard/src/components/common/SidePanel.vue b/dashboard/src/components/common/SidePanel.vue
index dd026901..1e5c0616 100644
--- a/dashboard/src/components/common/SidePanel.vue
+++ b/dashboard/src/components/common/SidePanel.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { Button } from 'frappe-ui'
-import { onBeforeUnmount, watch } from 'vue'
+import { nextTick, onBeforeUnmount, useTemplateRef, watch } from 'vue'
+import { useIsMobile } from '@/composables/useIsMobile'
 
 // The docked detail panel every page shares — a 24rem column that slides in
 // beside the content (never over it), the billing invoice panel's anatomy made
@@ -10,23 +11,52 @@ import { onBeforeUnmount, watch } from 'vue'
 //
 // Hosting: render as the last child of a `flex h-full` row, after the page's
 // own `min-w-0 flex-1 overflow-y-auto` content column.
+//
+// Below `sm` there is no row to dock into — MobileShell owns the scroll, so
+// pages make that row `sm:`-only and a docked panel would stack a 384px column
+// under content on a 375px viewport. Same anatomy, presented as a sheet
+// instead: full-screen over the page header and the bottom nav, with the close
+// button (or Esc, on a keyboard) the only way out.
 defineProps<{ title?: string; subtitle?: string }>()
 const open = defineModel<boolean>('open', { default: false })
 
+// Docked, the panel sits beside content that stays usable, so it is a
+// complementary region. As a sheet it covers everything, so it has to say so —
+// otherwise a screen reader walks straight into the page behind it.
+const isMobile = useIsMobile()
+const panel = useTemplateRef<HTMLElement>('panel')
+
 // The panel is docked, not modal, so it never holds focus — Esc has to be
 // caught on the document. A stacked dialog owns Esc first: closing both at once
-// would take the panel away for what read as one dismissal.
+// would take the panel away for what read as one dismissal. `:not()` on our own
+// root because the sheet now carries role="dialog" itself and would otherwise
+// match, killing Esc entirely.
 function onEscape(event: KeyboardEvent): void {
 	if (event.key !== 'Escape') return
-	if (document.querySelector('[role="dialog"]')) return
+	if (document.querySelector('[role="dialog"]:not([data-slot="side-panel"])'))
+		return
 	open.value = false
 }
 
+// A sheet is the only thing on screen, so it takes focus and gives it back —
+// without this, Close leaves focus on a row that is no longer rendered and the
+// next Tab restarts from the top of the document.
+let restoreFocusTo: HTMLElement | null = null
+
 watch(
 	open,
 	(isOpen) => {
-		if (isOpen) document.addEventListener('keydown', onEscape)
-		else document.removeEventListener('keydown', onEscape)
+		if (isOpen) {
+			document.addEventListener('keydown', onEscape)
+			if (isMobile.value) {
+				restoreFocusTo = document.activeElement as HTMLElement | null
+				void nextTick(() => panel.value?.focus())
+			}
+			return
+		}
+		document.removeEventListener('keydown', onEscape)
+		restoreFocusTo?.focus?.()
+		restoreFocusTo = null
 	},
 	{ immediate: true },
 )
@@ -34,10 +64,25 @@ onBeforeUnmount(() => document.removeEventListener('keydown', onEscape))
 </script>
 
 <template>
+	<!-- Once the sheet is fixed it stops sharing the page's scroll, so it has to
+	     stop handing gestures back to it: `max-sm:overscroll-contain` for reaching
+	     the end of the body, and touch-action for the rest.
+	     `touch-pan-y`, not MobileShell's `touch-none`: the body is the tall thing
+	     here (a year of payments, a full receipt), and whether an ancestor's
+	     `touch-none` reaches down into a descendant scroller is exactly the kind of
+	     thing that behaves one way in a desktop emulator and another on a phone.
+	     Allowing the one gesture the sheet needs costs nothing — pinch-zoom and
+	     horizontal pan stay blocked either way. -->
 	<Transition name="slide" appear>
 		<aside
 			v-if="open"
-			class="flex w-[24rem] shrink-0 flex-col border-l border-outline-gray-2 bg-surface-base"
+			ref="panel"
+			data-slot="side-panel"
+			:role="isMobile ? 'dialog' : undefined"
+			:aria-modal="isMobile ? 'true' : undefined"
+			:aria-label="isMobile ? title : undefined"
+			:tabindex="isMobile ? -1 : undefined"
+			class="flex w-[24rem] shrink-0 flex-col border-l border-outline-gray-2 bg-surface-base focus:outline-none max-sm:fixed max-sm:inset-0 max-sm:z-20 max-sm:w-full max-sm:touch-pan-y max-sm:border-l-0"
 		>
 			<div
 				class="flex items-start justify-between gap-3 border-b border-outline-gray-2 p-4"
@@ -67,7 +112,9 @@ onBeforeUnmount(() => document.removeEventListener('keydown', onEscape))
 				</div>
 			</div>
 
-			<div class="flex min-h-0 flex-1 flex-col overflow-y-auto">
+			<div
+				class="flex min-h-0 flex-1 flex-col overflow-y-auto max-sm:overscroll-contain"
+			>
 				<slot />
 			</div>
 
@@ -81,7 +128,11 @@ onBeforeUnmount(() => document.removeEventListener('keydown', onEscape))
 <style scoped>
 /* The margin animates alongside the slide: without it the panel's 24rem of
    layout width appears/disappears in a single frame. Margin animation costs
-   layout per frame — the accepted tradeoff for a docked (not overlaid) panel. */
+   layout per frame — the accepted tradeoff for a docked (not overlaid) panel.
+   Below `sm` there is no layout width to collapse: left/right/width are all set
+   (inset-0 + w-full), which over-constrains the box, so `right` is dropped and
+   the end margin never enters the equation. The translate alone carries the
+   sheet in, which is the whole animation a full-screen sheet wants. */
 
 /* iOS drawer curve — decelerates hard at the end, so the panel settles rather
    than stops. */
diff --git a/dashboard/src/pages/team/AccessPage.vue b/dashboard/src/pages/team/AccessPage.vue
index 8b3b0f3c..ae07af36 100644
--- a/dashboard/src/pages/team/AccessPage.vue
+++ b/dashboard/src/pages/team/AccessPage.vue
@@ -98,5 +98,6 @@ const memberCountText = computed(() => {
 		     deep inside `main`, but it has to dock beside that scroll box rather
 		     than inside it. `contents` keeps the panel itself the flex item, so its
 		     24rem and the slide's negative margin measure against this row. -->
+		<div id="team-page-aside" class="contents" />
 	</div>
 </template>

From 59bb8c30a05d701d128eec23e032b5a6a58ebf41 Mon Sep 17 00:00:00 2001
From: Sadiq Ansari <sadiqxansari@gmail.com>
Date: Thu, 13 Aug 2026 16:33:59 +0530
Subject: [PATCH 5/5] fix(ui): mobile sizing for list filters, rows and forms

The list toolbar put each filter at a fixed width, so a 160px status filter and
a 176px date picker came to 344px against 343px of room and stacked one per row.
They grow from a 9rem floor below `sm` instead, which packs two to a row and
still lets a third wrap rather than squeezing all three thin.

The rest is what a phone reads at arm's length rather than a desk: notification
rows and their message text step up a size, the servers list panel stops hanging
off the right edge, the region and status filters stack, and the search palette
drops its keyboard hints, which are advice a phone can't take.

Also: a disabled email field that had gone invisible in dark mode, and the
appearance form's row, which was a settings-dialog layout being asked to be a
page.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .../src/components/billing/InvoiceListView.vue  |  4 +++-
 .../components/common/list-view/ListView.vue    |  6 +++++-
 .../notifications/NotificationItem.vue          | 11 +++++++----
 .../src/components/search/SearchDialog.vue      |  5 +++++
 .../src/components/servers/ServerListPanel.vue  |  4 +++-
 .../settings/forms/AppearanceForm.vue           | 17 +++++++++++++----
 .../components/settings/forms/ProfileForm.vue   | 12 ++++++++++--
 7 files changed, 46 insertions(+), 13 deletions(-)

diff --git a/dashboard/src/components/billing/InvoiceListView.vue b/dashboard/src/components/billing/InvoiceListView.vue
index a55902de..d07ea3fc 100644
--- a/dashboard/src/components/billing/InvoiceListView.vue
+++ b/dashboard/src/components/billing/InvoiceListView.vue
@@ -171,9 +171,11 @@ const filters: ListViewFilter[] = [
 		@row-click="emit('rowClick', $event)"
 	>
 		<template #filters>
+			<!-- Shares the filter row's mobile sizing: grow from a floor below `sm`,
+			     fixed 11rem from `sm` up. -->
 			<DateRangePicker
 				v-model="range"
-				class="w-44 shrink-0"
+				class="min-w-[9rem] flex-1 sm:w-44 sm:flex-none"
 				size="sm"
 				format="D MMM"
 				placeholder="Any date"
diff --git a/dashboard/src/components/common/list-view/ListView.vue b/dashboard/src/components/common/list-view/ListView.vue
index 3fbf24f3..824627b8 100644
--- a/dashboard/src/components/common/list-view/ListView.vue
+++ b/dashboard/src/components/common/list-view/ListView.vue
@@ -446,11 +446,15 @@ const showListControls = computed(
 				</TextInput>
 				<!-- A plain Select, not a Combobox: filter option sets are short, so a
              search field inside the popover is noise. -->
+				<!-- Fixed widths only from `sm` up. On a phone two 160px filters miss a
+				     343px row by a pixel and stack one per line; growing from a 9rem
+				     floor packs them two to a row instead, and a third still wraps
+				     rather than squeezing all three thin. -->
 				<Select
 					v-for="filter in filters"
 					:key="filter.key"
 					:model-value="query.filters[filter.key] || ''"
-					class="w-40"
+					class="min-w-[9rem] flex-1 sm:w-40 sm:flex-none"
 					variant="subtle"
 					:placeholder="filter.allLabel || `All ${filter.label.toLowerCase()}`"
 					:options="[
diff --git a/dashboard/src/components/notifications/NotificationItem.vue b/dashboard/src/components/notifications/NotificationItem.vue
index 9db86bd6..8127e511 100644
--- a/dashboard/src/components/notifications/NotificationItem.vue
+++ b/dashboard/src/components/notifications/NotificationItem.vue
@@ -5,6 +5,9 @@ import type { NotificationSeverity, TeamNotification } from '@/types/billing'
 // One feed row, shared by the bell dropdown (compact) and the /notifications page.
 // Plain list row: no background, no border — unread is the blue dot by the time.
 // Category is not shown here; it only drives the page's filter tabs.
+// Text sizes step up below `sm` (16/15 rather than 14/13): on a phone these are
+// the primary rows of a full-screen list. The timestamp stays at 13 — it's
+// metadata, and it shares the title's line.
 const props = defineProps<{
 	notification: TeamNotification
 	compact?: boolean
@@ -52,7 +55,7 @@ function timeAgo(ts: string): string {
 		<div class="min-w-0 flex-1">
 			<div class="flex items-center gap-2">
 				<p
-					class="min-w-0 flex-1 text-base-medium text-ink-gray-9"
+					class="min-w-0 flex-1 text-lg-medium text-ink-gray-9 sm:text-base-medium"
 					:class="compact ? 'truncate' : ''"
 				>
 					{{ notification.title }}
@@ -69,7 +72,7 @@ function timeAgo(ts: string): string {
 
 			<p
 				v-if="notification.message"
-				class="mt-0.5 text-p-sm text-ink-gray-6"
+				class="mt-0.5 text-p-md text-ink-gray-6 sm:text-p-sm"
 				:class="compact ? 'line-clamp-2' : ''"
 			>
 				{{ notification.message }}
@@ -81,7 +84,7 @@ function timeAgo(ts: string): string {
 			>
 				<button
 					v-if="notification.action_label"
-					class="text-p-sm font-medium text-ink-gray-8 hover:text-ink-gray-9"
+					class="text-p-md font-medium text-ink-gray-8 hover:text-ink-gray-9 sm:text-p-sm"
 					@click="emit('act')"
 				>
 					{{ notification.action_label }}
@@ -89,7 +92,7 @@ function timeAgo(ts: string): string {
 				</button>
 				<button
 					v-if="!notification.is_read"
-					class="text-p-sm text-ink-gray-5 hover:text-ink-gray-8"
+					class="text-p-md text-ink-gray-5 hover:text-ink-gray-8 sm:text-p-sm"
 					@click="emit('read')"
 				>
 					Mark as read
diff --git a/dashboard/src/components/search/SearchDialog.vue b/dashboard/src/components/search/SearchDialog.vue
index 40d39876..8dcf9f49 100644
--- a/dashboard/src/components/search/SearchDialog.vue
+++ b/dashboard/src/components/search/SearchDialog.vue
@@ -10,6 +10,7 @@ import {
 } from 'reka-ui'
 import { computed, ref, watch } from 'vue'
 import { useRouter } from 'vue-router'
+import { useIsMobile } from '@/composables/useIsMobile'
 import type { SearchItem } from './index'
 import { useSearchIndex } from './index'
 import { filterIndex, highlightMatch } from './utils'
@@ -17,6 +18,9 @@ import { filterIndex, highlightMatch } from './utils'
 const open = defineModel<boolean>('open', { default: false })
 
 const router = useRouter()
+// The footer is nothing but keyboard hints, and a touch device has no keyboard
+// to offer them to — arrows, enter, esc and ⌘K are all unreachable there.
+const isMobile = useIsMobile()
 const query = ref('')
 const searchIndex = useSearchIndex()
 
@@ -103,6 +107,7 @@ function select(item: SearchItem): void {
 				</ListboxContent>
 
 				<div
+					v-if="!isMobile"
 					class="mt-2 flex items-center justify-between border-t border-outline-gray-1 px-2.5 py-2 text-xs text-ink-gray-6"
 				>
 					<div class="flex items-center gap-4">
diff --git a/dashboard/src/components/servers/ServerListPanel.vue b/dashboard/src/components/servers/ServerListPanel.vue
index b83ff244..90574977 100644
--- a/dashboard/src/components/servers/ServerListPanel.vue
+++ b/dashboard/src/components/servers/ServerListPanel.vue
@@ -46,9 +46,11 @@ const hoverId = defineModel<string | null>('hoverId', { required: true })
 </script>
 
 <template>
+	<!-- The open width (24rem) is wider than a phone, so the panel hung off the
+	     right edge — fill the map instead, keeping the 1rem gutter `left-4` sets. -->
 	<section
 		class="sp-float absolute left-4 top-4 z-30 overflow-hidden rounded-6 border border-outline-gray-2 bg-surface-elevation-1"
-		:class="open && 'sp-float-open'"
+		:class="open && 'sp-float-open max-sm:!w-[calc(100%-2rem)]'"
 		role="region"
 		aria-label="Your servers"
 		@keydown.esc="open = false"
diff --git a/dashboard/src/components/settings/forms/AppearanceForm.vue b/dashboard/src/components/settings/forms/AppearanceForm.vue
index 74697760..c6d3965b 100644
--- a/dashboard/src/components/settings/forms/AppearanceForm.vue
+++ b/dashboard/src/components/settings/forms/AppearanceForm.vue
@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { Button, SettingsRow, useColorScheme } from 'frappe-ui'
+import { Button, useColorScheme } from 'frappe-ui'
 import { useAppMenu } from '@/composables/useAppMenu'
 
 // Theme also lives in the sidebar's header menu, where it's a shortcut. This is
@@ -10,8 +10,17 @@ const { colorScheme, setColorScheme } = useColorScheme()
 </script>
 
 <template>
-	<SettingsRow title="Theme" description="Applies to this browser only.">
-		<div class="flex items-center gap-1">
+	<!-- SettingsRow's own layout is a fixed two-column row, and three labelled
+	     buttons leave the title column too narrow to read on a phone. Same
+	     styling, stacked until there's width for the row. -->
+	<div class="flex flex-col gap-3 py-3.5 sm:flex-row sm:items-center sm:gap-8">
+		<div class="min-w-0 flex-1">
+			<div class="text-base-medium block text-ink-gray-8">Theme</div>
+			<div class="mt-1 text-base leading-5 text-ink-gray-6">
+				Applies to this browser only.
+			</div>
+		</div>
+		<div class="flex shrink-0 items-center gap-1 sm:justify-end">
 			<Button
 				v-for="theme in themeOptions"
 				:key="theme.value"
@@ -21,5 +30,5 @@ const { colorScheme, setColorScheme } = useColorScheme()
 				@click="setColorScheme(theme.value)"
 			/>
 		</div>
-	</SettingsRow>
+	</div>
 </template>
diff --git a/dashboard/src/components/settings/forms/ProfileForm.vue b/dashboard/src/components/settings/forms/ProfileForm.vue
index 38f88574..19d4b938 100644
--- a/dashboard/src/components/settings/forms/ProfileForm.vue
+++ b/dashboard/src/components/settings/forms/ProfileForm.vue
@@ -140,8 +140,16 @@ function resetPassword(): void {
 		</div>
 
 		<!-- Identity, not a setting — disabled (not readonly) so it can't be
-		     focused or clicked into at all. -->
-		<FormControl :model-value="profile?.user ?? ''" label="Email" disabled />
+		     focused or clicked into at all. The disabled surface-gray-1 fill leaves
+		     the value all but invisible in dark mode; gray-2 lifts the field off
+		     the background there and still reads as a filled, inert input in light
+		     mode (elevation-2 goes white in light, which looks editable). -->
+		<FormControl
+			:model-value="profile?.user ?? ''"
+			label="Email"
+			disabled
+			class="[&_input]:!bg-surface-gray-2"
+		/>
 
 		<!-- One button until you mean it; the fields appear in place. The button
 		     and field labels name themselves — no section label. -->