feat(web): consolidated single-component header for Unraid 7.3+ (fixes mobile overlap)

.gitignore

@@ -130,3 +130,4 @@ web/public/test-pages/*.html
 # local scripts for testing and development
 .dev-scripts/
 
+.gstack/

.limetech/ai-review-markers/feat-consolidated-header-f1ad9c831fe8.json

@@ -0,0 +1,22 @@
+{
+  "agent": "claude",
+  "base_oid": "f3205d978fada931da54df4255d41c07489066d9",
+  "base_ref": "origin/main",
+  "branch": "feat/consolidated-header",
+  "linear_data_shares": [],
+  "linear_skip_reason": "No durable cross-branch knowledge emerged; delta findings are branch-local non-blocking test-coverage nits and a comment fix.",
+  "linear_state": "skipped",
+  "review_notes": "Requested preset auto; resolved to thorough with the shared mount-engine.ts delta reviewed deep (blast-radius trigger). Full branch was exhaustively reviewed at prior SHA ead8641; this pass verifies the applied fixes + 7.4 gate comment sync. Lenses: correctness, architecture, tests, type/modeling - all delegated, one read-only subagent each, strong model/high reasoning. Data-safety/security/documentation lenses not re-run (no changed surface in the delta; covered at ead8641). Source remediation: report-only (one comment fix applied that a lens explicitly requested). Marker: commit-on-green. Refreshes the stale marker from prior SHA ead8641 after 4 follow-up commits.",
+  "review_status": "reviewed",
+  "reviewed_at": "2026-07-23T12:44:57Z",
+  "reviewed_sha": "ba0d98a82ad7e566eb721d2e085c96e7e2796510",
+  "schema": "limetech.ai-review-marker.v1",
+  "scope": "branch-diff",
+  "summary": "No blocking findings. Delegated re-review of the delta since the prior exhaustive pass (mount-engine placeholder-gating + timer/observer/buffer teardown, headerLogoStyle typing, 7.3->7.4 gate comment sync). Correctness/architecture/type lenses clean; blast radius confirmed bounded to the header; 4 non-blocking test-coverage nits; one stale 7.3 comment fixed (main.css). Lint/type-check clean; 656 tests pass.",
+  "unreviewed_head_reason": "The latest PR SHA is the marker-only commit that records this review.",
+  "validation": {
+    "lint": "pass (eslint + prettier)",
+    "tests": "656 passed / 6 skipped / 67 files",
+    "type_check": "pass (vue-tsc)"
+  }
+}

web/__test__/components/Header.test.ts

@@ -0,0 +1,235 @@
+import { ref } from 'vue';
+import { setActivePinia } from 'pinia';
+import { provideApolloClient } from '@vue/apollo-composable';
+import { mount } from '@vue/test-utils';
+
+import { ApolloClient, InMemoryCache } from '@apollo/client/core';
+import { createTestingPinia } from '@pinia/testing';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { VueWrapper } from '@vue/test-utils';
+import type { Server, ServerconnectPluginInstalled, ServerState } from '~/types/server';
+import type { Pinia } from 'pinia';
+
+import Header from '~/components/Header.standalone.vue';
+import { useServerStore } from '~/store/server';
+import { useThemeStore } from '~/store/theme';
+
+const mockCopy = vi.fn();
+const mockCopied = ref(false);
+const mockIsSupported = ref(true);
+
+vi.mock('@vueuse/core', () => ({
+  useClipboard: () => {
+    const actualCopy = (text: string) => {
+      if (mockIsSupported.value) {
+        mockCopy(text);
+        mockCopied.value = true;
+      } else {
+        mockCopied.value = false;
+      }
+    };
+    return {
+      copy: actualCopy,
+      copied: mockCopied,
+      isSupported: mockIsSupported,
+    };
+  },
+  useLocalStorage: <T>(key: string, initialValue: T) => {
+    const storage = new Map<string, T>();
+    if (!storage.has(key)) {
+      storage.set(key, initialValue);
+    }
+    return ref(storage.get(key) ?? initialValue);
+  },
+}));
+
+vi.mock('@unraid/ui', () => ({
+  DropdownMenu: {
+    template: '<div data-testid="dropdown-menu"><slot name="trigger" /><slot name="content" /></div>',
+  },
+  Button: {
+    template: '<button><slot /></button>',
+    props: ['variant', 'size'],
+  },
+  cn: (...classes: string[]) => classes.filter(Boolean).join(' '),
+  isDarkModeActive: vi.fn(() => false),
+}));
+
+const mockWatcher = vi.fn();
+
+vi.mock('~/store/callbackActions', () => ({
+  useCallbackActionsStore: vi.fn(() => ({
+    watcher: mockWatcher,
+    callbackData: ref(null),
+  })),
+}));
+
+const t = (key: string, args?: unknown[]) => (args ? `${key} ${JSON.stringify(args)}` : key);
+vi.mock('vue-i18n', () => ({
+  useI18n: () => ({ t }),
+}));
+
+const initialServerData: Server = {
+  name: 'DEVGEN',
+  description: 'Dev Server',
+  guid: 'TEST-GUID',
+  keyfile: 'keyfile.key',
+  lanIp: '192.168.1.100',
+  connectPluginInstalled: 'dynamix.unraid.net.plg' as ServerconnectPluginInstalled,
+  state: 'PRO' as ServerState,
+  dateTimeFormat: { date: 'YYYY-MM-DD', time: 'HH:mm' },
+  deviceCount: 5,
+  flashProduct: 'TestFlash',
+  flashVendor: 'TestVendor',
+  regGuid: 'REG-GUID',
+  regTm: 1678886400,
+  regTo: 'Test User',
+  regTy: 'Pro',
+  regExp: undefined,
+  regUpdatesExpired: false,
+  registered: true,
+  wanIp: '8.8.8.8',
+};
+
+// Stub the heavier child components; the consolidated header is responsible for
+// layout composition, which is what these tests exercise.
+const stubs = {
+  HeaderVersion: { template: '<div data-testid="header-version"></div>' },
+  ArrayUsage: { template: '<div data-testid="array-usage"></div>' },
+  UpcServerStatus: {
+    template: '<div data-testid="server-status"></div>',
+    props: ['class'],
+  },
+  NotificationsSidebar: { template: '<div data-testid="notifications-sidebar"></div>' },
+  DropdownMenu: {
+    template: '<div data-testid="dropdown-menu"><slot name="trigger" /><slot name="content" /></div>',
+  },
+  UpcDropdownContent: { template: '<div data-testid="dropdown-content"></div>' },
+  UpcDropdownTrigger: { template: '<button data-testid="dropdown-trigger"></button>' },
+};
+
+describe('Header.standalone.vue', () => {
+  let wrapper: VueWrapper<InstanceType<typeof Header>>;
+  let pinia: Pinia;
+  let serverStore: ReturnType<typeof useServerStore>;
+  let themeStore: ReturnType<typeof useThemeStore>;
+  let consoleSpies: Array<ReturnType<typeof vi.spyOn>> = [];
+
+  beforeEach(() => {
+    Object.defineProperty(window, 'location', {
+      value: {
+        hostname: 'localhost',
+        port: '3000',
+        pathname: '/',
+        protocol: 'http:',
+        href: 'http://localhost:3000/',
+      },
+      writable: true,
+      configurable: true,
+    });
+
+    provideApolloClient(new ApolloClient({ cache: new InMemoryCache() }));
+
+    consoleSpies = [
+      vi.spyOn(console, 'log').mockImplementation(() => {}),
+      vi.spyOn(console, 'warn').mockImplementation(() => {}),
+      vi.spyOn(console, 'debug').mockImplementation(() => {}),
+      vi.spyOn(console, 'error').mockImplementation(() => {}),
+    ];
+
+    mockCopied.value = false;
+    mockIsSupported.value = true;
+
+    pinia = createTestingPinia({
+      createSpy: vi.fn,
+      initialState: { server: { ...initialServerData } },
+      stubActions: false,
+    });
+    setActivePinia(pinia);
+
+    serverStore = useServerStore();
+    themeStore = useThemeStore();
+    themeStore.setTheme({
+      name: 'white',
+      banner: true,
+      bannerGradient: true,
+      descriptionShow: true,
+      textColor: '',
+      metaColor: '',
+      bgColor: '',
+    });
+
+    vi.spyOn(serverStore, 'setServer').mockImplementation((server) => {
+      Object.assign(serverStore, server);
+      return server;
+    });
+
+    vi.clearAllMocks();
+
+    wrapper = mount(Header, {
+      props: { server: JSON.stringify(initialServerData) },
+      global: { plugins: [pinia], stubs },
+    });
+  });
+
+  afterEach(() => {
+    wrapper?.unmount();
+    consoleSpies.forEach((spy) => spy.mockRestore());
+    vi.restoreAllMocks();
+  });
+
+  it('renders every header region in a single component', () => {
+    expect(wrapper.find('[data-testid="header-version"]').exists()).toBe(true);
+    expect(wrapper.find('[data-testid="server-status"]').exists()).toBe(true);
+    expect(wrapper.find('[data-testid="notifications-sidebar"]').exists()).toBe(true);
+    expect(wrapper.find('[data-testid="dropdown-menu"]').exists()).toBe(true);
+    expect(wrapper.find('[data-testid="dropdown-trigger"]').exists()).toBe(true);
+    expect(wrapper.find('button').text()).toContain('DEVGEN');
+  });
+
+  it('hydrates the server store from the prop and starts the callback watcher', () => {
+    expect(serverStore.setServer).toHaveBeenCalledTimes(1);
+    expect(serverStore.setServer).toHaveBeenCalledWith(JSON.parse(JSON.stringify(initialServerData)));
+    expect(mockWatcher).toHaveBeenCalledTimes(1);
+  });
+
+  it('throws when the server prop is missing', () => {
+    expect(() => mount(Header, { props: {}, global: { plugins: [pinia], stubs } })).toThrow(
+      'Server data not present'
+    );
+  });
+
+  it('lays out on a responsive grid with each region in its own area (no overlap)', () => {
+    const root = wrapper.get('#UnraidHeader');
+    // A single grid owns the responsive layout (breakpoints live in scoped CSS).
+    expect(root.classes()).toContain('unraid-header-shell');
+    // Every header region is placed in its own grid area, so nothing is absolutely
+    // positioned on top of anything else (the root cause of the old mobile overlap).
+    expect(root.find('.uh-logo-block').exists()).toBe(true);
+    expect(root.find('.uh-meta-right').exists()).toBe(true);
+    expect(root.find('.uh-nav-right').exists()).toBe(true);
+    expect(root.find('.uh-name').exists()).toBe(true);
+    // The only absolutely-positioned element allowed is the banner gradient layer.
+    expect(root.classes()).not.toContain('absolute');
+    expect(root.find('.absolute:not(.unraid-banner-gradient-layer)').exists()).toBe(false);
+  });
+
+  it('hides the array-usage bar by default and shows it when enabled', async () => {
+    expect(wrapper.find('[data-testid="array-usage"]').exists()).toBe(false);
+
+    const withUsage = mount(Header, {
+      props: { server: JSON.stringify(initialServerData), showArrayUsage: 'true' },
+      global: { plugins: [pinia], stubs },
+    });
+    expect(withUsage.find('[data-testid="array-usage"]').exists()).toBe(true);
+    withUsage.unmount();
+  });
+
+  it('copies the LAN IP when the server name is clicked', async () => {
+    mockIsSupported.value = true;
+    await wrapper.find('button').trigger('click');
+    await wrapper.vm.$nextTick();
+    expect(mockCopy).toHaveBeenCalledWith(initialServerData.lanIp);
+  });
+});

web/__test__/components/UserProfile.test.ts

@@ -376,36 +376,4 @@ describe('UserProfile.standalone.vue', () => {
 
     expect(wrapper.find('[data-testid="notifications-sidebar"]').exists()).toBe(true);
   });
-
-  it('conditionally renders banner based on theme store', async () => {
-    const bannerSelector = '.unraid-banner-gradient-layer';
-
-    themeStore.setTheme({
-      ...themeStore.theme,
-      banner: true,
-      bannerGradient: true,
-    });
-    await wrapper.vm.$nextTick();
-
-    expect(themeStore.bannerGradient).toBe(true);
-    expect(wrapper.find(bannerSelector).exists()).toBe(true);
-
-    themeStore.setTheme({
-      ...themeStore.theme,
-      bannerGradient: false,
-    });
-    await wrapper.vm.$nextTick();
-
-    expect(themeStore.bannerGradient).toBe(false);
-    expect(wrapper.find(bannerSelector).exists()).toBe(false);
-
-    themeStore.setTheme({
-      ...themeStore.theme,
-      bannerGradient: true,
-    });
-    await wrapper.vm.$nextTick();
-
-    expect(themeStore.bannerGradient).toBe(true);
-    expect(wrapper.find(bannerSelector).exists()).toBe(true);
-  });
 });

web/__test__/components/Wrapper/component-registry.test.ts

@@ -74,9 +74,11 @@ describe('component-registry', () => {
   it('should have priority components listed first', async () => {
     const { componentMappings } = await import('~/components/Wrapper/component-registry');
 
-    // Priority components should be first
-    expect(componentMappings[0].appId).toBe('header-os-version');
-    expect(componentMappings[1].appId).toBe('user-profile');
+    // Priority components should be first: the consolidated header (7.4+) leads,
+    // followed by the legacy multi-component header used as the < 7.4 fallback.
+    expect(componentMappings[0].appId).toBe('header');
+    expect(componentMappings[1].appId).toBe('header-os-version');
+    expect(componentMappings[2].appId).toBe('user-profile');
   });
 
   it('should support multiple selectors for modals', async () => {

web/__test__/components/Wrapper/mount-engine.test.ts

@@ -494,6 +494,56 @@ describe('mount-engine', () => {
     });
   });
 
+  describe('placeholder preservation', () => {
+    it('preserves a meaningful boot placeholder, then removes it once content lands', async () => {
+      const element = document.createElement('div');
+      element.id = 'placeholder-app';
+      const placeholder = document.createElement('span');
+      placeholder.className = 'boot-placeholder';
+      element.appendChild(placeholder);
+      document.body.appendChild(element);
+
+      mockComponentMappings.push({
+        selector: '#placeholder-app',
+        appId: 'placeholder-app',
+        component: TestComponent,
+      });
+
+      await mountUnifiedApp();
+
+      // Once the client render lands, the observer swaps out the placeholder.
+      await vi.waitFor(() => {
+        expect(element.querySelector('.test-component')).toBeTruthy();
+        expect(element.querySelector('.boot-placeholder')).toBeFalsy();
+      });
+    });
+
+    it('takes the clear-then-render path for whitespace-only children (no buffer wrapper)', async () => {
+      const element = document.createElement('div');
+      element.id = 'whitespace-app';
+      // Multi-line custom-element markup leaves a whitespace text node — this is
+      // not a placeholder and must not trigger the display:contents buffer.
+      element.appendChild(document.createTextNode('\n  '));
+      document.body.appendChild(element);
+
+      mockComponentMappings.push({
+        selector: '#whitespace-app',
+        appId: 'whitespace-app',
+        component: TestComponent,
+      });
+
+      await mountUnifiedApp();
+
+      await vi.waitFor(() => {
+        expect(element.querySelector('.test-component')).toBeTruthy();
+      });
+
+      // Rendered directly into the host, with no intervening display:contents div.
+      expect(element.querySelector('div[style*="display: contents"]')).toBeFalsy();
+      expect(element.firstElementChild?.classList.contains('u-app')).toBe(true);
+    });
+  });
+
   describe('autoMountAllComponents', () => {
     it('should call mountUnifiedApp', async () => {
       const element = document.createElement('div');

web/components.d.ts

@@ -18,6 +18,7 @@ declare module 'vue' {
     'ApiKeyPage.standalone': typeof import('./src/components/ApiKeyPage.standalone.vue')['default']
     ApiStatus: typeof import('./src/components/ApiStatus/ApiStatus.vue')['default']
     'ApiStatus.standalone': typeof import('./src/components/ApiStatus/ApiStatus.standalone.vue')['default']
+    ArrayUsage: typeof import('./src/components/Header/ArrayUsage.vue')['default']
     'Auth.standalone': typeof import('./src/components/Auth.standalone.vue')['default']
     Avatar: typeof import('./src/components/Brand/Avatar.vue')['default']
     BaseLogViewer: typeof import('./src/components/Logs/BaseLogViewer.vue')['default']
@@ -77,8 +78,11 @@ declare module 'vue' {
     EffectivePermissions: typeof import('./src/components/ApiKey/EffectivePermissions.vue')['default']
     FileViewer: typeof import('./src/components/FileViewer.vue')['default']
     FilteredLogModal: typeof import('./src/components/Logs/FilteredLogModal.vue')['default']
+    'Header.standalone': typeof import('./src/components/Header.standalone.vue')['default']
     HeaderContent: typeof import('./src/components/Docker/HeaderContent.vue')['default']
+    HeaderLogo: typeof import('./src/components/Header/HeaderLogo.vue')['default']
     'HeaderOsVersion.standalone': typeof import('./src/components/HeaderOsVersion.standalone.vue')['default']
+    HeaderVersion: typeof import('./src/components/Header/HeaderVersion.vue')['default']
     IgnoredRelease: typeof import('./src/components/UpdateOs/IgnoredRelease.vue')['default']
     Indicator: typeof import('./src/components/Notifications/Indicator.vue')['default']
     InternalBootConfirmDialog: typeof import('./src/components/Onboarding/components/InternalBootConfirmDialog.vue')['default']