From 047055391563165e2546a6552fdf5822973686e6 Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Thu, 21 May 2026 15:26:59 +0200
Subject: [PATCH 1/7] refactor(ui): tabs align with default sidenav offset +
 tighten gap below tabs

- CoreSurfaceTabBar: add `mx-4` to `<v-tabs>` so the tab strip aligns
  horizontally with PageHeader's title icon (both now use the same 16px
  inset inside `v-container fluid`).
- user.view.vue + admin.layout.vue: add `pb-0` on the parent
  `<v-container fluid>` to collapse ~16px of dead space between the tab
  underline and the routed child's top edge. Child views own their own
  top padding via their own `<v-container fluid>` + `pa-2` row.

Visual impact (Account, Org detail, Admin surfaces):
- Tabs now align with the section title icon instead of being 16px to the left
- Vertical gap below tabs drops from ~40px to ~24px
---
 src/modules/admin/views/admin.layout.vue                     | 2 +-
 src/modules/core/components/core.surfaceTabBar.component.vue | 2 +-
 src/modules/users/views/user.view.vue                        | 5 +++--
 3 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/modules/admin/views/admin.layout.vue b/src/modules/admin/views/admin.layout.vue
index da6d77343..4c450eb56 100644
--- a/src/modules/admin/views/admin.layout.vue
+++ b/src/modules/admin/views/admin.layout.vue
@@ -1,5 +1,5 @@
 <template>
-  <v-container fluid>
+  <v-container fluid class="pb-0">
     <v-alert
       v-if="error"
       type="error"
diff --git a/src/modules/core/components/core.surfaceTabBar.component.vue b/src/modules/core/components/core.surfaceTabBar.component.vue
index 98b89bea3..7c86a8f4f 100644
--- a/src/modules/core/components/core.surfaceTabBar.component.vue
+++ b/src/modules/core/components/core.surfaceTabBar.component.vue
@@ -54,7 +54,7 @@ function tabTo(route) {
 </script>
 
 <template>
-  <v-tabs>
+  <v-tabs class="mx-4">
     <v-tab
       v-for="t in visibleTabs"
       :key="t.value"
diff --git a/src/modules/users/views/user.view.vue b/src/modules/users/views/user.view.vue
index a437a219c..5b78cb376 100644
--- a/src/modules/users/views/user.view.vue
+++ b/src/modules/users/views/user.view.vue
@@ -1,7 +1,8 @@
 <template>
   <div>
-    <!-- Layout chrome: header + tab bar, guttered with their own container -->
-    <v-container fluid>
+    <!-- Layout chrome: header + tab bar, guttered with their own container.
+         pb-0 collapses the gap below tabs — child router-view supplies its own top padding. -->
+    <v-container fluid class="pb-0">
       <PageHeader icon="fa-solid fa-user" title="Account">
         <template #actions>
           <organizationsSwitcherComponent />

From ef11b5421d95494395d1c292e452f47d119a4a7e Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Thu, 21 May 2026 15:45:42 +0200
Subject: [PATCH 2/7] refactor(ui): apply pb-0 to organization detail container

Extends the tabs-spacing-alignment fix to organization.detail.component.vue
which had the same `<v-container fluid>` parent pattern as user.view.vue
and admin.layout.vue. Brings /users/organizations/:id/* into visual
parity with /users/profile and /admin/* surfaces.
---
 .../components/organization.detail.component.vue             | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/modules/organizations/components/organization.detail.component.vue b/src/modules/organizations/components/organization.detail.component.vue
index ae6401e75..235e2fac3 100644
--- a/src/modules/organizations/components/organization.detail.component.vue
+++ b/src/modules/organizations/components/organization.detail.component.vue
@@ -1,7 +1,8 @@
 <template>
   <div>
-    <!-- Layout chrome: header + tab bar, guttered with their own container -->
-    <v-container fluid>
+    <!-- Layout chrome: header + tab bar, guttered with their own container.
+         pb-0 collapses the gap below tabs — child router-view supplies its own top padding. -->
+    <v-container fluid class="pb-0">
       <!-- Header -->
       <PageHeader
         :title="viewedOrganization ? viewedOrganization.name : 'Organization'"

From a9d6deab38cb13b3d7714f0cab26d96575e836ed Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Thu, 21 May 2026 16:11:39 +0200
Subject: [PATCH 3/7] refactor(core): split PageHeader + CorePageHeaderTabs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Splits the chrome primitive into two specialised components so each page
gets the spacing it actually needs:

- `PageHeader` (existing, simplified): content-sized header for list views
  and simple pages (Tasks, Scraps, etc.). Drops the 56px min/max-height
  enforcement and removes the dead `#tabs` slot path (unused since the
  CoreSurfaceTabBar sibling refactor in #4187/#4188).
- `CorePageHeaderTabs` (new): bundles a PageHeader + CoreSurfaceTabBar and
  enforces the 56px height externally via a scoped `:deep()` rule. Used on
  tabbed surfaces (Account, Organization detail, Admin) where the title↔
  breadcrumb rhythm matters across route transitions.

The new primitive accepts `tabs`, `can`, `basePath`, and `hideTabs` for the
tab bar, plus passthrough of icon/title/subtitle/avatar/actions/breadcrumb
slots and props to the inner PageHeader.

Migrates 3 callsites:
- user.view.vue (Account)
- admin.layout.vue (with hideTabs in breadcrumb mode)
- organization.detail.component.vue

Visual impact: pages without tabs (e.g. /tasks) no longer pay the 56px
chrome tax; tabbed surfaces preserve the route-transition rhythm.
---
 .../admin/tests/admin.layout.unit.tests.js    | 92 ++++++++----------
 src/modules/admin/views/admin.layout.vue      | 19 ++--
 .../components/core.pageHeader.component.vue  | 87 ++++++++---------
 .../core.pageHeaderTabs.component.vue         | 63 +++++++++++++
 ...ore.pageHeaderTabs.component.unit.tests.js | 94 +++++++++++++++++++
 .../core.pageHeader.component.unit.tests.js   | 21 +----
 .../organization.detail.component.vue         | 21 ++---
 .../organizations.detail.layout.unit.tests.js | 70 ++++++--------
 .../users/tests/user.view.unit.tests.js       | 38 ++++----
 src/modules/users/views/user.view.vue         | 21 ++---
 10 files changed, 306 insertions(+), 220 deletions(-)
 create mode 100644 src/modules/core/components/core.pageHeaderTabs.component.vue
 create mode 100644 src/modules/core/components/tests/core.pageHeaderTabs.component.unit.tests.js

diff --git a/src/modules/admin/tests/admin.layout.unit.tests.js b/src/modules/admin/tests/admin.layout.unit.tests.js
index 94f65a716..03eb53a3d 100644
--- a/src/modules/admin/tests/admin.layout.unit.tests.js
+++ b/src/modules/admin/tests/admin.layout.unit.tests.js
@@ -44,27 +44,21 @@ const mountLayout = (configOverrides = {}, routePath = '/admin/users') =>
       stubs: {
         RouterLink: true,
         RouterView: { template: '<div class="router-view-stub" />' },
-        PageHeader: {
-          name: 'PageHeader',
-          props: ['title', 'icon'],
+        // Single stub for the new bundled header-with-tabs primitive — exposes
+        // all the props admin.layout passes through, plus the breadcrumb slot.
+        CorePageHeaderTabs: {
+          name: 'CorePageHeaderTabs',
+          props: ['title', 'icon', 'tabs', 'can', 'basePath', 'hideTabs'],
           template: `
-            <div class="page-header-stub" :data-title="title" :data-icon="icon">
+            <div class="page-header-tabs-stub" :data-title="title" :data-icon="icon" :data-hide-tabs="hideTabs">
               <slot name="avatar" />
               <slot name="breadcrumb" />
-              <slot name="tabs" />
               <slot name="title" />
               <slot name="subtitle" />
               <slot name="actions" />
             </div>
           `,
         },
-        // Stub SurfaceTabBar so we can read the props it receives without rendering full v-tabs.
-        // name: 'CoreSurfaceTabBar' is required for findComponent({ name: ... }) to work.
-        CoreSurfaceTabBar: {
-          name: 'CoreSurfaceTabBar',
-          props: ['tabs', 'can', 'basePath'],
-          template: '<div class="surface-tab-bar-stub" :data-tabs-count="tabs?.length || 0" />',
-        },
       },
     },
   });
@@ -79,7 +73,7 @@ describe('admin.layout', () => {
 
   it('renders the page header', () => {
     const wrapper = mountLayout();
-    expect(wrapper.find('.page-header-stub').exists()).toBe(true);
+    expect(wrapper.find('.page-header-tabs-stub').exists()).toBe(true);
   });
 
   it('renders a <router-view> for nested admin content', () => {
@@ -87,16 +81,16 @@ describe('admin.layout', () => {
     expect(wrapper.find('.router-view-stub').exists()).toBe(true);
   });
 
-  it('passes the four built-in tabs to CoreSurfaceTabBar when no extras are configured', () => {
+  it('passes the four built-in tabs to CorePageHeaderTabs when no extras are configured', () => {
     const wrapper = mountLayout();
-    const bar = wrapper.findComponent({ name: 'CoreSurfaceTabBar' });
-    expect(bar.exists()).toBe(true);
-    const tabs = bar.props('tabs');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(headerTabs.exists()).toBe(true);
+    const tabs = headerTabs.props('tabs');
     expect(tabs).toHaveLength(4);
     expect(tabs.map((t) => t.value)).toEqual(['users', 'organizations', 'readiness', 'activity']);
   });
 
-  it('passes built-in + extra tabs from config.admin.tabs to CoreSurfaceTabBar', () => {
+  it('passes built-in + extra tabs from config.admin.tabs to CorePageHeaderTabs', () => {
     const wrapper = mountLayout({
       admin: {
         tabs: [
@@ -105,29 +99,29 @@ describe('admin.layout', () => {
         ],
       },
     });
-    const bar = wrapper.findComponent({ name: 'CoreSurfaceTabBar' });
-    const tabs = bar.props('tabs');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    const tabs = headerTabs.props('tabs');
     expect(tabs).toHaveLength(6);
     expect(tabs[4].value).toBe('knowledge');
     expect(tabs[5].value).toBe('costs');
   });
 
-  it('passes basePath="/admin" to CoreSurfaceTabBar', () => {
+  it('passes basePath="/admin" to CorePageHeaderTabs', () => {
     const wrapper = mountLayout();
-    const bar = wrapper.findComponent({ name: 'CoreSurfaceTabBar' });
-    expect(bar.props('basePath')).toBe('/admin');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(headerTabs.props('basePath')).toBe('/admin');
   });
 
-  it('passes a function `can` predicate to CoreSurfaceTabBar', () => {
+  it('passes a function `can` predicate to CorePageHeaderTabs', () => {
     const wrapper = mountLayout();
-    const bar = wrapper.findComponent({ name: 'CoreSurfaceTabBar' });
-    expect(typeof bar.props('can')).toBe('function');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(typeof headerTabs.props('can')).toBe('function');
   });
 
-  it('gracefully handles non-array admin.tabs (CoreSurfaceTabBar receives only the built-in 4)', () => {
+  it('gracefully handles non-array admin.tabs (CorePageHeaderTabs receives only the built-in 4)', () => {
     const wrapper = mountLayout({ admin: { tabs: 'invalid' } });
-    const bar = wrapper.findComponent({ name: 'CoreSurfaceTabBar' });
-    expect(bar.props('tabs')).toHaveLength(4);
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(headerTabs.props('tabs')).toHaveLength(4);
   });
 
   it('renders the error banner at the TOP of the layout, before the header', async () => {
@@ -135,7 +129,7 @@ describe('admin.layout', () => {
     const wrapper = mountLayout();
     await wrapper.vm.$nextTick();
     const html = wrapper.html();
-    expect(html.indexOf('Boom')).toBeLessThan(html.indexOf('page-header-stub'));
+    expect(html.indexOf('Boom')).toBeLessThan(html.indexOf('page-header-tabs-stub'));
   });
 
   it('renders the mailer warning at the TOP when serverConfig.mail.configured is false', async () => {
@@ -143,7 +137,7 @@ describe('admin.layout', () => {
     const wrapper = mountLayout();
     await wrapper.vm.$nextTick();
     const html = wrapper.html();
-    expect(html.indexOf('No mailer configured')).toBeLessThan(html.indexOf('page-header-stub'));
+    expect(html.indexOf('No mailer configured')).toBeLessThan(html.indexOf('page-header-tabs-stub'));
   });
 
   it('does NOT render the mailer warning when mail is configured', () => {
@@ -152,16 +146,6 @@ describe('admin.layout', () => {
     expect(wrapper.html()).not.toContain('No mailer configured');
   });
 
-  it('renders <CoreSurfaceTabBar> as a SIBLING of <PageHeader> (not inside its #tabs slot)', () => {
-    const wrapper = mountLayout();
-    const pageHeaderEl = wrapper.find('.page-header-stub');
-    const surfaceTabBarEl = wrapper.find('.surface-tab-bar-stub');
-    expect(pageHeaderEl.exists()).toBe(true);
-    expect(surfaceTabBarEl.exists()).toBe(true);
-    // Sibling layout: the tab-bar element is NOT inside the page-header-stub element.
-    expect(pageHeaderEl.element.contains(surfaceTabBarEl.element)).toBe(false);
-  });
-
   it('renders <router-view> OUTSIDE the layout <v-container>', () => {
     const wrapper = mountLayout();
     const layoutContainer = wrapper.find('.v-container');
@@ -171,32 +155,34 @@ describe('admin.layout', () => {
     expect(layoutContainer.element.contains(routerViewEl.element)).toBe(false);
   });
 
-  it('PageHeader receives title="Admin" + icon="fa-solid fa-user-tie" in list mode', () => {
+  it('CorePageHeaderTabs receives title="Admin" + icon="fa-solid fa-user-tie" in list mode', () => {
     const wrapper = mountLayout();
-    const ph = wrapper.findComponent({ name: 'PageHeader' });
-    expect(ph.props('title')).toBe('Admin');
-    expect(ph.props('icon')).toBe('fa-solid fa-user-tie');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(headerTabs.props('title')).toBe('Admin');
+    expect(headerTabs.props('icon')).toBe('fa-solid fa-user-tie');
   });
 
-  it('PageHeader receives title="" + icon stays in breadcrumb mode', async () => {
+  it('CorePageHeaderTabs receives title="" + icon stays in breadcrumb mode', async () => {
     adminStoreState.currentBreadcrumb = { title: 'Jane Doe' };
     const wrapper = mountLayout({}, '/admin/users/u1');
     await wrapper.vm.$nextTick();
-    const ph = wrapper.findComponent({ name: 'PageHeader' });
-    expect(ph.props('title')).toBe('');
-    expect(ph.props('icon')).toBe('fa-solid fa-user-tie');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(headerTabs.props('title')).toBe('');
+    expect(headerTabs.props('icon')).toBe('fa-solid fa-user-tie');
   });
 
-  it('does NOT render <CoreSurfaceTabBar> when currentBreadcrumb is set (detail mode)', async () => {
+  it('passes hideTabs=true when currentBreadcrumb is set (detail mode)', async () => {
     adminStoreState.currentBreadcrumb = { title: 'Jane Doe' };
     const wrapper = mountLayout({}, '/admin/users/u1');
     await wrapper.vm.$nextTick();
-    expect(wrapper.findComponent({ name: 'CoreSurfaceTabBar' }).exists()).toBe(false);
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(headerTabs.props('hideTabs')).toBe(true);
   });
 
-  it('renders <CoreSurfaceTabBar> when currentBreadcrumb is null (list mode)', () => {
+  it('passes hideTabs=false when currentBreadcrumb is null (list mode)', () => {
     const wrapper = mountLayout();
-    expect(wrapper.findComponent({ name: 'CoreSurfaceTabBar' }).exists()).toBe(true);
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(headerTabs.props('hideTabs')).toBe(false);
   });
 
   it('renders the breadcrumb when useAdminStore().currentBreadcrumb is set', async () => {
diff --git a/src/modules/admin/views/admin.layout.vue b/src/modules/admin/views/admin.layout.vue
index 4c450eb56..a4c6897d5 100644
--- a/src/modules/admin/views/admin.layout.vue
+++ b/src/modules/admin/views/admin.layout.vue
@@ -27,22 +27,20 @@
       </span>
     </v-alert>
 
-    <PageHeader
+    <CorePageHeaderTabs
       icon="fa-solid fa-user-tie"
       :title="currentBreadcrumb ? '' : 'Admin'"
+      :tabs="allTabs"
+      :can="adminCan"
+      :base-path="basePath"
+      :hide-tabs="!!currentBreadcrumb"
     >
       <template v-if="currentBreadcrumb" #breadcrumb>
         <router-link to="/admin" class="text-medium-emphasis text-decoration-none">Admin</router-link>
         <v-icon icon="fa-solid fa-chevron-right" size="x-small" class="mx-2 text-medium-emphasis"></v-icon>
         <span :class="currentBreadcrumb.titleClass || ''">{{ currentBreadcrumb.title }}</span>
       </template>
-    </PageHeader>
-    <CoreSurfaceTabBar
-      v-if="!currentBreadcrumb"
-      :tabs="allTabs"
-      :can="adminCan"
-      :base-path="basePath"
-    />
+    </CorePageHeaderTabs>
   </v-container>
 
   <router-view />
@@ -51,8 +49,7 @@
 /**
  * Module dependencies.
  */
-import PageHeader from '../../core/components/core.pageHeader.component.vue';
-import CoreSurfaceTabBar from '../../core/components/core.surfaceTabBar.component.vue';
+import CorePageHeaderTabs from '../../core/components/core.pageHeaderTabs.component.vue';
 import { ability } from '../../../lib/helpers/ability';
 import { useAdminStore } from '../stores/admin.store';
 import { useAuthStore } from '../../auth/stores/auth.store';
@@ -85,7 +82,7 @@ const BUILT_IN_TABS = Object.freeze([
  */
 export default {
   name: 'AdminLayout',
-  components: { PageHeader, CoreSurfaceTabBar },
+  components: { CorePageHeaderTabs },
   computed: {
     /**
      * @desc Base path for admin tabs (where CoreSurfaceTabBar resolves relative routes).
diff --git a/src/modules/core/components/core.pageHeader.component.vue b/src/modules/core/components/core.pageHeader.component.vue
index b2f337368..c9bfa21e3 100644
--- a/src/modules/core/components/core.pageHeader.component.vue
+++ b/src/modules/core/components/core.pageHeader.component.vue
@@ -1,50 +1,44 @@
 <template>
   <v-row class="core-page-header mx-4 my-1 flex-nowrap" align="center">
-    <template v-if="$slots.tabs">
-      <!-- Tabs mode: tabs replace icon + title -->
-      <slot name="tabs"></slot>
-    </template>
-    <template v-else>
-      <!-- Standard mode: icon + (breadcrumb OR title) -->
-      <slot v-if="!$vuetify.display.mobile" name="avatar">
-        <v-avatar v-if="icon" :color="avatarColor" size="40">
-          <v-icon :icon="icon" size="small" color="white"></v-icon>
-        </v-avatar>
-      </slot>
+    <!-- Standard mode: icon + (breadcrumb OR title) -->
+    <slot v-if="!$vuetify.display.mobile" name="avatar">
+      <v-avatar v-if="icon" :color="avatarColor" size="40">
+        <v-icon :icon="icon" size="small" color="white"></v-icon>
+      </v-avatar>
+    </slot>
+    <div
+      class="core-page-header__content"
+      :class="[
+        $vuetify.display.mobile ? 'ml-6' : '',
+        !$vuetify.display.mobile && ($slots.avatar || icon) ? 'ml-2' : '',
+      ]"
+    >
+      <!-- Breadcrumb takes precedence over title when provided -->
       <div
-        class="core-page-header__content"
-        :class="[
-          $vuetify.display.mobile ? 'ml-6' : '',
-          !$vuetify.display.mobile && ($slots.avatar || icon) ? 'ml-2' : '',
-        ]"
+        v-if="$slots.breadcrumb"
+        class="core-page-header__breadcrumb text-title-large font-weight-medium text-truncate"
+        :class="titleClass"
+        style="line-height: 1;"
       >
-        <!-- Breadcrumb takes precedence over title when provided -->
-        <div
-          v-if="$slots.breadcrumb"
-          class="core-page-header__breadcrumb text-title-large font-weight-medium text-truncate"
+        <slot name="breadcrumb"></slot>
+      </div>
+      <template v-else>
+        <h2
+          class="core-page-header__title text-title-large font-weight-medium text-truncate"
           :class="titleClass"
           style="line-height: 1;"
         >
-          <slot name="breadcrumb"></slot>
-        </div>
-        <template v-else>
-          <h2
-            class="core-page-header__title text-title-large font-weight-medium text-truncate"
-            :class="titleClass"
-            style="line-height: 1;"
-          >
-            <slot name="title">{{ title }}</slot>
-          </h2>
-          <p
-            v-if="subtitle || $slots.subtitle"
-            class="core-page-header__subtitle text-body-medium text-medium-emphasis text-truncate"
-            style="margin: 0; line-height: 1;"
-          >
-            <slot name="subtitle">{{ subtitle }}</slot>
-          </p>
-        </template>
-      </div>
-    </template>
+          <slot name="title">{{ title }}</slot>
+        </h2>
+        <p
+          v-if="subtitle || $slots.subtitle"
+          class="core-page-header__subtitle text-body-medium text-medium-emphasis text-truncate"
+          style="margin: 0; line-height: 1;"
+        >
+          <slot name="subtitle">{{ subtitle }}</slot>
+        </p>
+      </template>
+    </div>
     <v-spacer></v-spacer>
     <!-- Actions slot — wrapped in a flex cluster (flex-wrap = safety net for extreme viewports) -->
     <div v-if="$slots.actions" class="core-page-header__actions d-flex align-center flex-wrap">
@@ -82,19 +76,14 @@ export default {
 </script>
 
 <style scoped>
-/*
- * Canonical 56px height — keeps list view (title) and detail view (breadcrumb)
- * visually aligned so route transitions don't jump.
- */
-.core-page-header {
-  min-height: 56px;
-  max-height: 56px;
-}
-
 /*
  * flex: 1 + min-width: 0 lets the title/breadcrumb container shrink past its
  * intrinsic width when content is long, so the truncate kicks in instead of
  * pushing the actions cluster off-screen.
+ *
+ * NOTE: PageHeader is content-sized by default. Tabbed surfaces that need
+ * a 56px rhythm for title↔breadcrumb route transitions use CorePageHeaderTabs,
+ * which enforces the height externally.
  */
 .core-page-header__content {
   flex: 1 1 0;
diff --git a/src/modules/core/components/core.pageHeaderTabs.component.vue b/src/modules/core/components/core.pageHeaderTabs.component.vue
new file mode 100644
index 000000000..f50ba53d8
--- /dev/null
+++ b/src/modules/core/components/core.pageHeaderTabs.component.vue
@@ -0,0 +1,63 @@
+<template>
+  <div>
+    <PageHeader
+      :icon="icon"
+      :title="title"
+      :subtitle="subtitle"
+      :title-class="titleClass"
+      :avatar-color="avatarColor"
+    >
+      <template v-if="$slots.avatar" #avatar><slot name="avatar"></slot></template>
+      <template v-if="$slots.title" #title><slot name="title"></slot></template>
+      <template v-if="$slots.subtitle" #subtitle><slot name="subtitle"></slot></template>
+      <template v-if="$slots.breadcrumb" #breadcrumb><slot name="breadcrumb"></slot></template>
+      <template v-if="$slots.actions" #actions><slot name="actions"></slot></template>
+    </PageHeader>
+    <CoreSurfaceTabBar
+      v-if="!hideTabs && tabs && tabs.length > 0"
+      :tabs="tabs"
+      :can="can"
+      :base-path="basePath"
+    />
+  </div>
+</template>
+
+<script>
+import PageHeader from './core.pageHeader.component.vue';
+import CoreSurfaceTabBar from './core.surfaceTabBar.component.vue';
+
+/**
+ * CorePageHeaderTabs — bundles a fixed-height PageHeader (title↔breadcrumb
+ * rhythm preserved across route transitions) with a CoreSurfaceTabBar
+ * sibling. Use on surfaces where a tab bar is part of the page chrome
+ * (Account, Organization detail, Admin). Pages without tabs (Tasks, list
+ * views) should use `PageHeader` directly, which is content-sized.
+ */
+export default {
+  name: 'CorePageHeaderTabs',
+  components: { PageHeader, CoreSurfaceTabBar },
+  props: {
+    title: { type: String, default: '' },
+    subtitle: { type: String, default: '' },
+    icon: { type: String, default: '' },
+    titleClass: { type: String, default: '' },
+    avatarColor: { type: String, default: 'primary' },
+    tabs: { type: Array, default: () => [] },
+    can: { type: Function, required: true },
+    basePath: { type: String, required: true },
+    hideTabs: { type: Boolean, default: false },
+  },
+};
+</script>
+
+<style scoped>
+/*
+ * Canonical 56px height — enforced only on tabbed surfaces so list view
+ * (title) and detail view (breadcrumb) stay aligned across route changes
+ * without jumping. Pages without tabs let the header be content-sized.
+ */
+:deep(.core-page-header) {
+  min-height: 56px;
+  max-height: 56px;
+}
+</style>
diff --git a/src/modules/core/components/tests/core.pageHeaderTabs.component.unit.tests.js b/src/modules/core/components/tests/core.pageHeaderTabs.component.unit.tests.js
new file mode 100644
index 000000000..7c6123651
--- /dev/null
+++ b/src/modules/core/components/tests/core.pageHeaderTabs.component.unit.tests.js
@@ -0,0 +1,94 @@
+import { describe, it, expect } from 'vitest';
+import { mount } from '@vue/test-utils';
+import { createVuetify } from 'vuetify';
+import * as components from 'vuetify/components';
+import * as directives from 'vuetify/directives';
+import CorePageHeaderTabs from '../core.pageHeaderTabs.component.vue';
+
+/**
+ * Vuetify instance with all components registered for component mount.
+ * @returns {import('vuetify').Vuetify}
+ */
+// biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Qwik rule does not apply in a Vue/Vitest context
+const makeVuetify = () => createVuetify({ components, directives });
+
+const VTabStub = {
+  template: '<a class="v-tab-stub" :href="to"><slot /></a>',
+  props: ['to'],
+};
+
+/**
+ * Mount the component with sensible defaults; callers override via opts.
+ * @param {object} [opts]
+ * @returns {import('@vue/test-utils').VueWrapper}
+ */
+// biome-ignore lint/correctness/useQwikValidLexicalScope: false positive — Qwik rule does not apply in a Vue/Vitest context
+const mountIt = (opts = {}) =>
+  mount(CorePageHeaderTabs, {
+    props: {
+      title: 'Account',
+      icon: 'fa-solid fa-user',
+      tabs: [{ value: 'profile', label: 'Profile', route: 'profile' }],
+      can: () => true,
+      basePath: '/users',
+      ...(opts.props || {}),
+    },
+    slots: opts.slots,
+    global: {
+      plugins: [makeVuetify()],
+      stubs: { VTab: VTabStub },
+    },
+  });
+
+describe('CorePageHeaderTabs — composition', () => {
+  it('renders an inner PageHeader with the title prop forwarded', () => {
+    const wrapper = mountIt({ props: { title: 'Account' } });
+    expect(wrapper.find('h2.core-page-header__title').text()).toContain('Account');
+  });
+
+  it('renders an inner CoreSurfaceTabBar when tabs are provided', () => {
+    const wrapper = mountIt();
+    expect(wrapper.text()).toContain('Profile');
+  });
+
+  it('hides the tab bar when hideTabs is true (breadcrumb mode)', () => {
+    const wrapper = mountIt({ props: { hideTabs: true } });
+    expect(wrapper.text()).not.toContain('Profile');
+  });
+
+  it('hides the tab bar when the tabs array is empty', () => {
+    const wrapper = mountIt({ props: { tabs: [] } });
+    expect(wrapper.text()).not.toContain('Profile');
+  });
+
+  it('forwards the actions slot through to PageHeader', () => {
+    const wrapper = mountIt({
+      slots: { actions: '<button class="qa-action">Switch</button>' },
+    });
+    expect(wrapper.find('.qa-action').exists()).toBe(true);
+  });
+
+  it('forwards the breadcrumb slot through to PageHeader (precedence over title)', () => {
+    const wrapper = mountIt({
+      props: { title: 'Account' },
+      slots: { breadcrumb: '<span class="qa-bc">Account &rsaquo; Detail</span>' },
+    });
+    expect(wrapper.find('.qa-bc').exists()).toBe(true);
+    expect(wrapper.find('h2.core-page-header__title').exists()).toBe(false);
+  });
+
+});
+
+describe('CorePageHeaderTabs — CASL gating on tabs', () => {
+  it('respects the can predicate when rendering tabs', () => {
+    const tabs = [
+      { value: 'profile', label: 'Profile', route: 'profile' },
+      { value: 'billing', label: 'Billing', route: 'billing', action: 'manage', subject: 'Billing' },
+    ];
+    const wrapper = mountIt({
+      props: { tabs, can: () => false, basePath: '/users' },
+    });
+    expect(wrapper.text()).toContain('Profile');
+    expect(wrapper.text()).not.toContain('Billing');
+  });
+});
diff --git a/src/modules/core/tests/core.pageHeader.component.unit.tests.js b/src/modules/core/tests/core.pageHeader.component.unit.tests.js
index d6a3beb34..7ec8ea611 100644
--- a/src/modules/core/tests/core.pageHeader.component.unit.tests.js
+++ b/src/modules/core/tests/core.pageHeader.component.unit.tests.js
@@ -107,7 +107,7 @@ describe('core.pageHeader.component — breadcrumb slot', () => {
   });
 });
 
-describe('core.pageHeader.component — canonical 56px height invariant', () => {
+describe('core.pageHeader.component — root layout class', () => {
   it('applies the .core-page-header class on the root row in title mode', () => {
     const wrapper = mountHeader({ props: { title: 'Tasks' } });
     expect(wrapper.find('.core-page-header').exists()).toBe(true);
@@ -129,7 +129,6 @@ describe('core.pageHeader.component — canonical 56px height invariant', () =>
     });
     const titleRoot = wrapperTitle.find('.core-page-header');
     const bcRoot = wrapperBc.find('.core-page-header');
-    // Layout-bearing classes (height invariant + nowrap) must match across modes
     expect(titleRoot.classes()).toEqual(expect.arrayContaining(['core-page-header', 'flex-nowrap']));
     expect(bcRoot.classes()).toEqual(expect.arrayContaining(['core-page-header', 'flex-nowrap']));
   });
@@ -196,21 +195,3 @@ describe('core.pageHeader.component — actions cluster', () => {
   });
 });
 
-describe('core.pageHeader.component — tabs mode (unchanged)', () => {
-  it('renders the tabs slot and skips the icon/title block', () => {
-    const wrapper = mountHeader({
-      props: { title: 'Tasks', icon: 'fa-solid fa-list-check' },
-      slots: { tabs: '<div class="qa-tabs">Tabs here</div>' },
-    });
-    expect(wrapper.find('.qa-tabs').exists()).toBe(true);
-    expect(wrapper.find('h2.core-page-header__title').exists()).toBe(false);
-    expect(wrapper.find('.core-page-header__breadcrumb').exists()).toBe(false);
-  });
-
-  it('still applies the canonical 56px height class in tabs mode', () => {
-    const wrapper = mountHeader({
-      slots: { tabs: '<div class="qa-tabs">Tabs here</div>' },
-    });
-    expect(wrapper.find('.core-page-header').exists()).toBe(true);
-  });
-});
diff --git a/src/modules/organizations/components/organization.detail.component.vue b/src/modules/organizations/components/organization.detail.component.vue
index 235e2fac3..b119ef05d 100644
--- a/src/modules/organizations/components/organization.detail.component.vue
+++ b/src/modules/organizations/components/organization.detail.component.vue
@@ -3,9 +3,11 @@
     <!-- Layout chrome: header + tab bar, guttered with their own container.
          pb-0 collapses the gap below tabs — child router-view supplies its own top padding. -->
     <v-container fluid class="pb-0">
-      <!-- Header -->
-      <PageHeader
+      <CorePageHeaderTabs
         :title="viewedOrganization ? viewedOrganization.name : 'Organization'"
+        :tabs="config.organizations.tabs"
+        :can="abilityCan"
+        :base-path="basePath"
       >
         <template #avatar>
           <orgAvatarComponent v-if="viewedOrganization" :org="viewedOrganization" :size="40" class="mr-3" />
@@ -23,14 +25,7 @@
             Delete
           </v-btn>
         </template>
-      </PageHeader>
-
-      <!-- Tab bar (config-driven, CASL-gated) -->
-      <CoreSurfaceTabBar
-        :tabs="config.organizations.tabs"
-        :can="abilityCan"
-        :base-path="basePath"
-      />
+      </CorePageHeaderTabs>
     </v-container>
 
     <!-- Active child route renders outside the layout container so each child's
@@ -61,17 +56,15 @@ import { subject } from '@casl/ability';
 import { useRoute } from 'vue-router';
 import { ability } from '../../../lib/helpers/ability';
 import { useOrganizationsStore } from '../stores/organizations.store';
-import PageHeader from '../../core/components/core.pageHeader.component.vue';
+import CorePageHeaderTabs from '../../core/components/core.pageHeaderTabs.component.vue';
 import orgAvatarComponent from '../../core/components/org.avatar.component.vue';
-import CoreSurfaceTabBar from '../../core/components/core.surfaceTabBar.component.vue';
 import coreConfirmDialog from '../../core/components/core.confirmDialog.component.vue';
 
 export default {
   name: 'OrganizationDetailComponent',
   components: {
-    PageHeader,
+    CorePageHeaderTabs,
     orgAvatarComponent,
-    CoreSurfaceTabBar,
     coreConfirmDialog,
   },
   props: {
diff --git a/src/modules/organizations/tests/organizations.detail.layout.unit.tests.js b/src/modules/organizations/tests/organizations.detail.layout.unit.tests.js
index 1b5634e98..cb4fe4fce 100644
--- a/src/modules/organizations/tests/organizations.detail.layout.unit.tests.js
+++ b/src/modules/organizations/tests/organizations.detail.layout.unit.tests.js
@@ -73,13 +73,12 @@ import OrganizationGeneralTab from '../components/organization.general.tab.vue';
  * Minimal stubs for Vuetify / child components so mount stays lightweight.
  */
 const baseStubs = {
-  PageHeader: { template: '<div class="page-header-stub" />' },
-  orgAvatarComponent: { template: '<div />' },
-  CoreSurfaceTabBar: {
-    name: 'CoreSurfaceTabBar',
-    props: ['tabs', 'can', 'basePath'],
-    template: '<div class="surface-tab-bar-stub" :data-base-path="basePath" />',
+  CorePageHeaderTabs: {
+    name: 'CorePageHeaderTabs',
+    props: ['title', 'tabs', 'can', 'basePath', 'hideTabs'],
+    template: '<div class="page-header-tabs-stub" :data-base-path="basePath"><slot name="avatar" /><slot name="actions" /></div>',
   },
+  orgAvatarComponent: { template: '<div />' },
   coreConfirmDialog: { template: '<div class="core-confirm-dialog-stub"><slot /></div>' },
   RouterView: { template: '<div class="router-view-stub" />' },
   'router-view': { template: '<div class="router-view-stub" />' },
@@ -140,9 +139,9 @@ describe('organization.detail.component.vue — tabbed parent layout (C3)', () =
     setActivePinia(createPinia());
   });
 
-  it('renders CoreSurfaceTabBar', () => {
+  it('renders CorePageHeaderTabs', () => {
     const wrapper = mountLayout();
-    expect(wrapper.findComponent({ name: 'CoreSurfaceTabBar' }).exists()).toBe(true);
+    expect(wrapper.findComponent({ name: 'CorePageHeaderTabs' }).exists()).toBe(true);
   });
 
   it('renders router-view for child tabs', () => {
@@ -152,27 +151,16 @@ describe('organization.detail.component.vue — tabbed parent layout (C3)', () =
   });
 
   it('router-view is NOT nested inside a v-container (no double-gutter regression)', () => {
-    // The layout wraps only its chrome (PageHeader + CoreSurfaceTabBar) in a
-    // v-container; router-view sits outside so each child provides its own
-    // single container gutter.  The stub renders as <div><slot /></div>, so
-    // we verify the rendered HTML does NOT show router-view-stub as a
-    // descendant of a v-container stub (i.e. router-view-stub is not inside
-    // the container div that also contains page-header-stub and surface-tab-bar-stub).
+    // The layout wraps only its chrome (CorePageHeaderTabs) in a v-container;
+    // router-view sits outside so each child provides its own single container
+    // gutter.
     const wrapper = mountLayout();
     const html = wrapper.html();
-    // The router-view-stub should appear AFTER the closing tag of the inner container
-    // that holds the tab bar. A simple structural check: router-view-stub must not
-    // appear between page-header-stub and surface-tab-bar-stub's enclosing div.
-    const tabBarPos = html.indexOf('surface-tab-bar-stub');
+    const headerPos = html.indexOf('page-header-tabs-stub');
     const routerViewPos = html.indexOf('router-view-stub');
-    // router-view-stub must appear after the tab bar (chrome is above content)
-    expect(routerViewPos).toBeGreaterThan(tabBarPos);
+    // router-view-stub must appear after the header chrome
+    expect(routerViewPos).toBeGreaterThan(headerPos);
     // The layout root must NOT be a v-container stub itself — it is a plain <div>
-    // (the v-container stub renders as <div><slot/></div>, but the root wrapper
-    // element should be a plain div wrapping a v-container then router-view).
-    // Verify the component root element is not the v-container by checking
-    // that the layout exposes no v-container as the outermost wrapper.
-    // (shallowMount root = component's root template element)
     expect(wrapper.element.tagName.toLowerCase()).toBe('div');
   });
 
@@ -192,32 +180,32 @@ describe('organization.detail.component.vue — tabbed parent layout (C3)', () =
     expect(wrapper.vm.basePath).not.toContain(':organizationId');
   });
 
-  it('passes the resolved basePath to CoreSurfaceTabBar', () => {
+  it('passes the resolved basePath to CorePageHeaderTabs', () => {
     const wrapper = mountLayout('org-xyz');
-    const tabBar = wrapper.findComponent({ name: 'CoreSurfaceTabBar' });
-    expect(tabBar.props('basePath')).toBe('/users/organizations/org-xyz');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(headerTabs.props('basePath')).toBe('/users/organizations/org-xyz');
   });
 
-  it('passes config.organizations.tabs to CoreSurfaceTabBar', () => {
+  it('passes config.organizations.tabs to CorePageHeaderTabs', () => {
     const wrapper = mountLayout();
-    const tabBar = wrapper.findComponent({ name: 'CoreSurfaceTabBar' });
-    const tabs = tabBar.props('tabs');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    const tabs = headerTabs.props('tabs');
     expect(Array.isArray(tabs)).toBe(true);
     expect(tabs.find((t) => t.value === 'billing')).toBeDefined();
   });
 
-  it('passes both Organization + Billing tabs to CoreSurfaceTabBar', () => {
+  it('passes both Organization + Billing tabs to CorePageHeaderTabs', () => {
     const wrapper = mountLayout();
-    const tabBar = wrapper.findComponent({ name: 'CoreSurfaceTabBar' });
-    expect(tabBar.exists()).toBe(true);
-    const tabs = tabBar.props('tabs');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(headerTabs.exists()).toBe(true);
+    const tabs = headerTabs.props('tabs');
     expect(tabs.map((t) => t.value)).toEqual(['organization', 'billing']);
   });
 
-  it('passes a function as the `can` prop to CoreSurfaceTabBar', () => {
+  it('passes a function as the `can` prop to CorePageHeaderTabs', () => {
     const wrapper = mountLayout();
-    const tabBar = wrapper.findComponent({ name: 'CoreSurfaceTabBar' });
-    expect(typeof tabBar.props('can')).toBe('function');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(typeof headerTabs.props('can')).toBe('function');
   });
 
   it('basePath resolves differently for different org IDs (reactive)', () => {
@@ -245,10 +233,10 @@ describe('organization.detail.component.vue — tabbed parent layout (C3)', () =
     expect(wrapper.vm.basePath).not.toContain(':organizationId');
   });
 
-  it('passes admin basePath to CoreSurfaceTabBar in admin context', () => {
+  it('passes admin basePath to CorePageHeaderTabs in admin context', () => {
     const wrapper = mountLayout('org-xyz', '/admin/organizations/org-xyz');
-    const tabBar = wrapper.findComponent({ name: 'CoreSurfaceTabBar' });
-    expect(tabBar.props('basePath')).toBe('/admin/organizations/org-xyz');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(headerTabs.props('basePath')).toBe('/admin/organizations/org-xyz');
   });
 
   // ── FIX 1: no inert beforeRouteLeave on the layout ───────────────────────
diff --git a/src/modules/users/tests/user.view.unit.tests.js b/src/modules/users/tests/user.view.unit.tests.js
index 24793a57e..812069c73 100644
--- a/src/modules/users/tests/user.view.unit.tests.js
+++ b/src/modules/users/tests/user.view.unit.tests.js
@@ -15,8 +15,11 @@ vi.mock('../../../lib/services/config', () => ({
 vi.mock('../../../lib/helpers/ability', () => ({ ability: null, updateAbilities: vi.fn() }));
 
 const sharedStubs = {
-  PageHeader: { template: '<div data-test="page-header"><slot /><slot name="actions" /></div>', name: 'PageHeader' },
-  CoreSurfaceTabBar: { template: '<div data-test="core-surface-tab-bar" />', name: 'CoreSurfaceTabBar', props: ['tabs', 'can', 'basePath'] },
+  CorePageHeaderTabs: {
+    template: '<div data-test="page-header-tabs"><slot /><slot name="actions" /></div>',
+    name: 'CorePageHeaderTabs',
+    props: ['icon', 'title', 'tabs', 'can', 'basePath', 'hideTabs'],
+  },
   organizationsSwitcherComponent: { template: '<div />' },
   RouterView: { template: '<div data-test="router-view" />' },
   'router-view': { template: '<div data-test="router-view" />' },
@@ -38,23 +41,16 @@ const sharedMocks = () => ({
 
 // ── UserView – layout shape (Gamma refactor) ──────────────────────────────────
 
-describe('UserView – layout shape (PageHeader + SurfaceTabBar + router-view)', () => {
+describe('UserView – layout shape (CorePageHeaderTabs + router-view)', () => {
   beforeEach(() => {
     setActivePinia(createPinia());
   });
 
-  it('renders PageHeader', () => {
-    const wrapper = shallowMount(UserView, {
-      global: { mocks: sharedMocks(), stubs: sharedStubs },
-    });
-    expect(wrapper.find('[data-test="page-header"]').exists()).toBe(true);
-  });
-
-  it('renders CoreSurfaceTabBar', () => {
+  it('renders CorePageHeaderTabs', () => {
     const wrapper = shallowMount(UserView, {
       global: { mocks: sharedMocks(), stubs: sharedStubs },
     });
-    expect(wrapper.find('[data-test="core-surface-tab-bar"]').exists()).toBe(true);
+    expect(wrapper.find('[data-test="page-header-tabs"]').exists()).toBe(true);
   });
 
   it('renders a router-view for child route content', () => {
@@ -64,31 +60,31 @@ describe('UserView – layout shape (PageHeader + SurfaceTabBar + router-view)',
     expect(wrapper.find('[data-test="router-view"]').exists()).toBe(true);
   });
 
-  it('passes config.users.tabs to CoreSurfaceTabBar', () => {
+  it('passes config.users.tabs to CorePageHeaderTabs', () => {
     const wrapper = shallowMount(UserView, {
       global: { mocks: sharedMocks(), stubs: sharedStubs },
     });
-    const tabBar = wrapper.findComponent({ name: 'CoreSurfaceTabBar' });
-    const tabs = tabBar.props('tabs');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    const tabs = headerTabs.props('tabs');
     expect(Array.isArray(tabs)).toBe(true);
     expect(tabs.map((t) => t.value)).toContain('profile');
     expect(tabs.map((t) => t.value)).toContain('organizations');
   });
 
-  it('passes /users as basePath to CoreSurfaceTabBar', () => {
+  it('passes /users as basePath to CorePageHeaderTabs', () => {
     const wrapper = shallowMount(UserView, {
       global: { mocks: sharedMocks(), stubs: sharedStubs },
     });
-    const tabBar = wrapper.findComponent({ name: 'CoreSurfaceTabBar' });
-    expect(tabBar.props('basePath')).toBe('/users');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(headerTabs.props('basePath')).toBe('/users');
   });
 
-  it('passes a function as can prop to CoreSurfaceTabBar', () => {
+  it('passes a function as can prop to CorePageHeaderTabs', () => {
     const wrapper = shallowMount(UserView, {
       global: { mocks: sharedMocks(), stubs: sharedStubs },
     });
-    const tabBar = wrapper.findComponent({ name: 'CoreSurfaceTabBar' });
-    expect(typeof tabBar.props('can')).toBe('function');
+    const headerTabs = wrapper.findComponent({ name: 'CorePageHeaderTabs' });
+    expect(typeof headerTabs.props('can')).toBe('function');
   });
 });
 
diff --git a/src/modules/users/views/user.view.vue b/src/modules/users/views/user.view.vue
index 5b78cb376..7ab337f67 100644
--- a/src/modules/users/views/user.view.vue
+++ b/src/modules/users/views/user.view.vue
@@ -3,17 +3,17 @@
     <!-- Layout chrome: header + tab bar, guttered with their own container.
          pb-0 collapses the gap below tabs — child router-view supplies its own top padding. -->
     <v-container fluid class="pb-0">
-      <PageHeader icon="fa-solid fa-user" title="Account">
-        <template #actions>
-          <organizationsSwitcherComponent />
-        </template>
-      </PageHeader>
-      <!-- Tab bar (config-driven, CASL-gated) -->
-      <CoreSurfaceTabBar
+      <CorePageHeaderTabs
+        icon="fa-solid fa-user"
+        title="Account"
         :tabs="config.users.tabs"
         :can="userCan"
         :base-path="basePath"
-      />
+      >
+        <template #actions>
+          <organizationsSwitcherComponent />
+        </template>
+      </CorePageHeaderTabs>
     </v-container>
 
     <!-- Active child route renders outside the layout container so each child's
@@ -26,13 +26,12 @@
 import { ability } from '../../../lib/helpers/ability';
 import { useAuthStore } from '../../auth/stores/auth.store';
 import { useOrganizationsStore } from '../../organizations/stores/organizations.store';
-import PageHeader from '../../core/components/core.pageHeader.component.vue';
-import CoreSurfaceTabBar from '../../core/components/core.surfaceTabBar.component.vue';
+import CorePageHeaderTabs from '../../core/components/core.pageHeaderTabs.component.vue';
 import organizationsSwitcherComponent from '../../organizations/components/organizations.switcher.component.vue';
 
 export default {
   name: 'UserView',
-  components: { PageHeader, CoreSurfaceTabBar, organizationsSwitcherComponent },
+  components: { CorePageHeaderTabs, organizationsSwitcherComponent },
   /**
    * @desc Wires auth + organizations stores for the layout-level isLoggedIn
    *       watcher. The watcher mirrors the pre-Gamma fetch behavior: it pre-

From 12ba82c0748e223fb9032c79bbeac6f0766564de Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Thu, 21 May 2026 16:16:58 +0200
Subject: [PATCH 4/7] fix(tasks): align empty state row spacing with populated
 state
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The empty-state v-row was missing `pa-2 mt-0` (so Vuetify's default v-row
margin applied) and the card carried `ma-6` (24px all-sides margin),
which together added ~36px of dead space above the "No tasks yet" card
compared to the populated state. Drop `ma-6` and apply the same
`pa-2 mt-0` row classes as the populated branch — empty state now sits
flush with where task cards would render.
---
 src/modules/tasks/views/tasks.view.vue | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/modules/tasks/views/tasks.view.vue b/src/modules/tasks/views/tasks.view.vue
index 55c26b9fb..833d13b95 100644
--- a/src/modules/tasks/views/tasks.view.vue
+++ b/src/modules/tasks/views/tasks.view.vue
@@ -18,9 +18,9 @@
     <v-row class="pa-2 mt-0">
       <taskComponent v-for="(item, index) in tasks" :key="item.id" :item="item" :index="index"></taskComponent>
     </v-row>
-    <v-row v-if="!tasks || !tasks.length" align="start" justify="center">
+    <v-row v-if="!tasks || !tasks.length" class="pa-2 mt-0" align="start" justify="center">
       <v-col cols="12">
-        <v-card class="ma-6 pa-8 text-center" color="surface" :flat="config.vuetify.theme.flat" :class="config.vuetify.theme.rounded">
+        <v-card class="pa-8 text-center" color="surface" :flat="config.vuetify.theme.flat" :class="config.vuetify.theme.rounded">
           <v-icon icon="fa-solid fa-list-check" size="x-large" color="primary" class="mb-4 text-medium-emphasis"></v-icon>
           <h2 class="text-title-large font-weight-medium mb-2">No tasks yet</h2>
           <p class="text-body-medium text-medium-emphasis mb-4">Create your first task to get started.</p>

From dd8324565968f8ee0e29b2e139992ab9b6abb0ab Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Thu, 21 May 2026 16:22:52 +0200
Subject: [PATCH 5/7] fix(tasks): harmonize empty state card with /task layout
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drop `align="start" justify="center"` on the v-row and align card padding
(pa-8 → pa-6) so the empty-state card sits at the exact same top/left as
the form card on /task. Keeps `text-center` for icon + label centering
inside the card.
---
 src/modules/tasks/views/tasks.view.vue | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/modules/tasks/views/tasks.view.vue b/src/modules/tasks/views/tasks.view.vue
index 833d13b95..bb9d07f54 100644
--- a/src/modules/tasks/views/tasks.view.vue
+++ b/src/modules/tasks/views/tasks.view.vue
@@ -18,9 +18,9 @@
     <v-row class="pa-2 mt-0">
       <taskComponent v-for="(item, index) in tasks" :key="item.id" :item="item" :index="index"></taskComponent>
     </v-row>
-    <v-row v-if="!tasks || !tasks.length" class="pa-2 mt-0" align="start" justify="center">
+    <v-row v-if="!tasks || !tasks.length" class="pa-2 mt-0">
       <v-col cols="12">
-        <v-card class="pa-8 text-center" color="surface" :flat="config.vuetify.theme.flat" :class="config.vuetify.theme.rounded">
+        <v-card class="pa-6 text-center" color="surface" :flat="config.vuetify.theme.flat" :class="config.vuetify.theme.rounded">
           <v-icon icon="fa-solid fa-list-check" size="x-large" color="primary" class="mb-4 text-medium-emphasis"></v-icon>
           <h2 class="text-title-large font-weight-medium mb-2">No tasks yet</h2>
           <p class="text-body-medium text-medium-emphasis mb-4">Create your first task to get started.</p>

From 14c02b5f0a9220b7d122f516fd2220c7d14ae117 Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Thu, 21 May 2026 16:25:55 +0200
Subject: [PATCH 6/7] fix(tasks): hide populated v-row when task list is empty
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The populated state's v-row had no v-if guard, so when the task list was
empty it still rendered (just without children) — taking ~16-24px of
vertical space (pa-2 + default v-row margins) on top of the empty-state
row below. Empty-state card now sits at the same top position as the
populated cards (and /task form card).
---
 src/modules/tasks/views/tasks.view.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/modules/tasks/views/tasks.view.vue b/src/modules/tasks/views/tasks.view.vue
index bb9d07f54..1ab48a947 100644
--- a/src/modules/tasks/views/tasks.view.vue
+++ b/src/modules/tasks/views/tasks.view.vue
@@ -15,7 +15,7 @@
         </v-btn>
       </template>
     </PageHeader>
-    <v-row class="pa-2 mt-0">
+    <v-row v-if="tasks && tasks.length" class="pa-2 mt-0">
       <taskComponent v-for="(item, index) in tasks" :key="item.id" :item="item" :index="index"></taskComponent>
     </v-row>
     <v-row v-if="!tasks || !tasks.length" class="pa-2 mt-0">

From 1a9d48600c9e07ed4ae7a1ab70a07be4578bf1a8 Mon Sep 17 00:00:00 2001
From: Pierre Brisorgueil <pierrebrisorgueil@me.com>
Date: Thu, 21 May 2026 16:30:49 +0200
Subject: [PATCH 7/7] docs(migrations): document PageHeader split + tabs
 spacing/alignment refactor
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds a new migration entry above the previous chrome convergence entry
covering the changes in this batch:
- PageHeader is content-sized (56px enforcement removed)
- #tabs slot on PageHeader dropped (dead since #4187)
- mx-4 on v-tabs inside CoreSurfaceTabBar (horizontal alignment with title)
- New CorePageHeaderTabs primitive that bundles PageHeader + SurfaceTabBar
  and re-enforces the 56px rhythm for tabbed surfaces
- pb-0 on the tabbed-layout container to collapse the gap below tabs
- Empty-state v-row regression pattern (guard the populated row with v-if)

Downstream impact: minimal — only projects with custom tabbed layouts need
to migrate to CorePageHeaderTabs; default consumers get the new convention
via /update-stack automatically.
---
 MIGRATIONS.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)

diff --git a/MIGRATIONS.md b/MIGRATIONS.md
index 3b591e199..4de5354b4 100644
--- a/MIGRATIONS.md
+++ b/MIGRATIONS.md
@@ -4,6 +4,116 @@ Breaking changes and upgrade notes for downstream projects.
 
 ---
 
+## PageHeader split + tabs spacing/alignment refactor (2026-05-21, v2)
+
+**Non-breaking for default consumers** — affects 3 stack layouts (Account, Organization detail, Admin) which were already refactored upstream. Downstream projects only need to act if they wrote a custom layout using `PageHeader` + `CoreSurfaceTabBar` directly, or relied on the (now removed) `#tabs` slot on `PageHeader`.
+
+This entry supersedes the spacing/structure parts of the previous "Account / Organization / Admin chrome convergence" entry below; the four conventions still apply for child views, dialogs, etc.
+
+### What changed
+
+1. **`PageHeader` is now content-sized** — the canonical `min-height: 56px / max-height: 56px` is gone from `core.pageHeader.component.vue`. Pages without tabs (list views like Tasks, Scraps) no longer pay the chrome tax.
+2. **`PageHeader`'s `#tabs` slot is removed** — it was dead code since #4187 (tabs are siblings of the header, not inside it).
+3. **`CoreSurfaceTabBar` aligns tabs horizontally with the title** — `<v-tabs class="mx-4">` is now applied internally, so the tab strip sits at the same x-offset as `PageHeader`'s icon+title.
+4. **New primitive `CorePageHeaderTabs`** (`src/modules/core/components/core.pageHeaderTabs.component.vue`) bundles `PageHeader` + `CoreSurfaceTabBar` and enforces the 56px title↔breadcrumb rhythm via a scoped `:deep()` rule — used wherever a section needs both a header and a tab bar.
+5. **Tabbed layouts use `<v-container fluid class="pb-0">`** to collapse the dead gap between the tab underline and the routed child's top edge.
+
+### The new convention
+
+Pages **with tabs** (Account, Org detail, Admin) — single primitive:
+
+```vue
+<template>
+  <v-container fluid class="pb-0">
+    <CorePageHeaderTabs
+      icon="fa-solid fa-X"
+      title="Section"
+      :tabs="config.section.tabs"
+      :can="sectionCan"
+      :base-path="basePath"
+      :hide-tabs="false"
+    >
+      <template #actions>...</template>
+      <template #breadcrumb v-if="...">...</template>
+    </CorePageHeaderTabs>
+  </v-container>
+  <router-view />
+</template>
+```
+
+Pages **without tabs** (Tasks, Scraps, simple list views) — content-sized `PageHeader`, unchanged shape:
+
+```vue
+<template>
+  <v-container fluid>
+    <PageHeader icon="fa-solid fa-X" title="Section">
+      <template #actions>...</template>
+    </PageHeader>
+    <v-row class="pa-2 mt-0">
+      <!-- content -->
+    </v-row>
+  </v-container>
+</template>
+```
+
+### Breadcrumb mode
+
+The pattern from the previous migration entry still holds. Now expressed via `CorePageHeaderTabs`:
+
+```vue
+<CorePageHeaderTabs
+  icon="fa-solid fa-user-tie"
+  :title="currentBreadcrumb ? '' : 'Section'"
+  :tabs="tabs"
+  :can="can"
+  :base-path="basePath"
+  :hide-tabs="!!currentBreadcrumb"
+>
+  <template v-if="currentBreadcrumb" #breadcrumb>
+    <router-link to="/section">Section</router-link>
+    <v-icon icon="fa-solid fa-chevron-right" size="x-small" class="mx-2 text-medium-emphasis" />
+    <span>{{ currentBreadcrumb.title }}</span>
+  </template>
+</CorePageHeaderTabs>
+```
+
+Set `:hide-tabs="true"` when in breadcrumb mode (user has drilled into a sub-record) so the tab bar disappears; the 56px height stays consistent across the title↔breadcrumb route transition.
+
+### Empty-state regression to watch for
+
+If a list view renders both a populated row AND an empty-state row in the same template, **guard the populated row with `v-if`** so it doesn't take vertical space when the list is empty. Example fixed in this batch (`tasks.view.vue`):
+
+```vue
+<v-row v-if="tasks && tasks.length" class="pa-2 mt-0">
+  <taskComponent v-for="..." />
+</v-row>
+<v-row v-if="!tasks || !tasks.length" class="pa-2 mt-0">
+  <!-- empty state -->
+</v-row>
+```
+
+Without the guard, the empty populated row still consumes ~16-24px (pa-2 + default v-row margins) and pushes the empty-state card down.
+
+### Migration for downstream projects
+
+Most downstream projects don't write custom layouts using `PageHeader` + `CoreSurfaceTabBar` — they consume the layouts via the stack. `/update-stack` will pick up the new convention automatically.
+
+**If your project has a custom tabbed layout** (rare):
+
+1. Replace `<PageHeader>` + `<CoreSurfaceTabBar>` siblings with a single `<CorePageHeaderTabs>` (import from `src/modules/core/components/core.pageHeaderTabs.component.vue`).
+2. Add `class="pb-0"` to the wrapping `<v-container fluid>` so the gap below tabs collapses.
+3. Drop any local CSS that compensated for the 56px PageHeader height — the new primitive handles it.
+
+**If your project uses `PageHeader` with the `#tabs` slot** (very rare):
+
+- Remove the slot usage. Render tabs as a sibling of `PageHeader` (or use `CorePageHeaderTabs`).
+
+### Tests touched
+
+Stack tests updated to find `CorePageHeaderTabs` by name instead of looking for `PageHeader` + `CoreSurfaceTabBar` separately. Downstream test files that follow the same pattern will need the same update; if a downstream stub-tests `PageHeader` directly, no change needed.
+
+---
+
 ## Account / Organization / Admin chrome convergence (2026-05-21)
 
 **Non-breaking for default consumers.** Builds on #4183 (`corePageTabs`), #4184 (org tabs), #4185 (Account chrome), and #4187 (Admin chrome + `coreConfirmDialog` + `coreAvatarUploader`). Locks in one chrome convention across all "section + tab bar + routed children" layouts.