@prenta/admin 0.92.0

package/src/__tests__/hooks/useAppearanceBootstrap.test.ts

@@ -0,0 +1,69 @@
+// @vitest-environment happy-dom
+import { renderHook, waitFor } from '@testing-library/react'
+import { describe, expect, it, vi } from 'vitest'
+
+import type { AppearanceSnapshot } from '../../components/ThemeProvider.js'
+
+const applyAppearance = vi.fn<(snapshot: AppearanceSnapshot) => void>()
+vi.mock('../../components/ThemeProvider.js', () => ({
+  useTheme: () => ({ applyAppearance }),
+}))
+
+const cmsApi = vi.fn()
+vi.mock('../../lib/api.js', () => ({ cmsApi }))
+
+const { useAppearanceBootstrap } = await import('../../hooks/useAppearanceBootstrap.js')
+
+describe('useAppearanceBootstrap', () => {
+  it('fetches /appearance and applies the snapshot when a session is present', async () => {
+    applyAppearance.mockClear()
+    cmsApi.mockResolvedValueOnce({
+      data: {
+        appearance: {
+          adminColorModeDefault: 'light',
+          adminAccentColor: 'purple',
+          sidebarDensity: 'default',
+          contentFont: 'DM Sans',
+          reduceMotion: false,
+        },
+        brand: {
+          mode: 'customAdminBrand',
+          adminPrimaryLogoAssetId: 'logo-1',
+        },
+        resolved: { admin: { initials: 'UP' } },
+        assets: [
+          {
+            id: 'logo-1',
+            publicUrl: 'https://cdn.example.com/logo.svg',
+            mimeType: 'image/svg+xml',
+          },
+        ],
+        siteTitle: 'UpChat',
+      },
+    })
+
+    renderHook(() => useAppearanceBootstrap({ userId: 'user-1' }))
+
+    await waitFor(() => expect(cmsApi).toHaveBeenCalledWith('/appearance'))
+    await waitFor(() =>
+      expect(applyAppearance).toHaveBeenCalledWith(
+        expect.objectContaining({
+          adminBrand: expect.objectContaining({
+            primaryUrl: 'https://cdn.example.com/logo.svg',
+          }),
+        }),
+      ),
+    )
+  })
+
+  it('does not fetch when there is no session', async () => {
+    applyAppearance.mockClear()
+    cmsApi.mockClear()
+
+    renderHook(() => useAppearanceBootstrap(null))
+
+    await waitFor(() => {
+      expect(cmsApi).not.toHaveBeenCalled()
+    })
+  })
+})

package/src/__tests__/hooks/useIdleLogout.test.tsx

@@ -0,0 +1,188 @@
+// @vitest-environment happy-dom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { render } from '@testing-library/react'
+
+import { useIdleLogout } from '../../hooks/useIdleLogout.js'
+
+function Harness({
+  enabled,
+  timeoutMs,
+  onIdle,
+  warningMs,
+  onWarn,
+  onWarnCancelled,
+  stayActiveRef,
+}: {
+  enabled: boolean
+  timeoutMs: number
+  onIdle: () => void
+  warningMs?: number
+  onWarn?: () => void
+  onWarnCancelled?: () => void
+  stayActiveRef?: { current: (() => void) | null }
+}) {
+  const { stayActive } = useIdleLogout({
+    enabled,
+    timeoutMs,
+    onIdle,
+    warningMs,
+    onWarn,
+    onWarnCancelled,
+  })
+  if (stayActiveRef) stayActiveRef.current = stayActive
+  return null
+}
+
+const TIMEOUT_MS = 60_000
+
+beforeEach(() => {
+  vi.useFakeTimers()
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+})
+
+describe('useIdleLogout', () => {
+  it('fires onIdle exactly once after the timeout with no activity', () => {
+    const onIdle = vi.fn()
+    render(<Harness enabled timeoutMs={TIMEOUT_MS} onIdle={onIdle} />)
+
+    vi.advanceTimersByTime(TIMEOUT_MS - 1_000)
+    expect(onIdle).not.toHaveBeenCalled()
+
+    vi.advanceTimersByTime(TIMEOUT_MS)
+    expect(onIdle).toHaveBeenCalledTimes(1)
+
+    // The idle callback must not re-fire on subsequent ticks.
+    vi.advanceTimersByTime(TIMEOUT_MS * 3)
+    expect(onIdle).toHaveBeenCalledTimes(1)
+  })
+
+  it('resets the idle deadline on user activity', () => {
+    const onIdle = vi.fn()
+    render(<Harness enabled timeoutMs={TIMEOUT_MS} onIdle={onIdle} />)
+
+    // Just before the deadline the user types — the clock restarts.
+    vi.advanceTimersByTime(TIMEOUT_MS - 5_000)
+    window.dispatchEvent(new Event('keydown'))
+    vi.advanceTimersByTime(TIMEOUT_MS - 5_000)
+    expect(onIdle).not.toHaveBeenCalled()
+
+    // A full quiet timeout after the last activity signs the user out.
+    vi.advanceTimersByTime(TIMEOUT_MS)
+    expect(onIdle).toHaveBeenCalledTimes(1)
+  })
+
+  it('does nothing when disabled', () => {
+    const onIdle = vi.fn()
+    render(<Harness enabled={false} timeoutMs={TIMEOUT_MS} onIdle={onIdle} />)
+    vi.advanceTimersByTime(TIMEOUT_MS * 10)
+    expect(onIdle).not.toHaveBeenCalled()
+  })
+
+  it('tears everything down on unmount', () => {
+    const onIdle = vi.fn()
+    const { unmount } = render(<Harness enabled timeoutMs={TIMEOUT_MS} onIdle={onIdle} />)
+    unmount()
+    vi.advanceTimersByTime(TIMEOUT_MS * 10)
+    expect(onIdle).not.toHaveBeenCalled()
+  })
+
+  it('checks the deadline immediately when a hidden tab becomes visible', () => {
+    const onIdle = vi.fn()
+    render(<Harness enabled timeoutMs={TIMEOUT_MS} onIdle={onIdle} />)
+
+    // Simulate the deadline passing while the tab was hidden (the interval is
+    // shared with visibility, so freeze it by only moving the mocked clock).
+    vi.setSystemTime(Date.now() + TIMEOUT_MS + 1_000)
+    document.dispatchEvent(new Event('visibilitychange'))
+    expect(onIdle).toHaveBeenCalledTimes(1)
+  })
+
+  describe('warning window', () => {
+    const WARNING_MS = 20_000
+
+    it('fires onWarn once inside the warning window, then onIdle at the deadline', () => {
+      const onIdle = vi.fn()
+      const onWarn = vi.fn()
+      render(
+        <Harness
+          enabled
+          timeoutMs={TIMEOUT_MS}
+          warningMs={WARNING_MS}
+          onIdle={onIdle}
+          onWarn={onWarn}
+        />,
+      )
+
+      // Before the warning window: nothing.
+      vi.advanceTimersByTime(TIMEOUT_MS - WARNING_MS - 5_000)
+      expect(onWarn).not.toHaveBeenCalled()
+
+      // Inside the window: warn exactly once, no logout yet.
+      vi.advanceTimersByTime(10_000)
+      expect(onWarn).toHaveBeenCalledTimes(1)
+      expect(onIdle).not.toHaveBeenCalled()
+
+      // Deadline: logout, and the warning doesn't re-fire.
+      vi.advanceTimersByTime(TIMEOUT_MS)
+      expect(onIdle).toHaveBeenCalledTimes(1)
+      expect(onWarn).toHaveBeenCalledTimes(1)
+    })
+
+    it('activity after the warning cancels it and resets the clock', () => {
+      const onIdle = vi.fn()
+      const onWarn = vi.fn()
+      const onWarnCancelled = vi.fn()
+      render(
+        <Harness
+          enabled
+          timeoutMs={TIMEOUT_MS}
+          warningMs={WARNING_MS}
+          onIdle={onIdle}
+          onWarn={onWarn}
+          onWarnCancelled={onWarnCancelled}
+        />,
+      )
+
+      vi.advanceTimersByTime(TIMEOUT_MS - 10_000)
+      expect(onWarn).toHaveBeenCalledTimes(1)
+
+      window.dispatchEvent(new Event('keydown'))
+      expect(onWarnCancelled).toHaveBeenCalledTimes(1)
+
+      // The clock restarted: warn again on the next quiet cycle, no logout yet.
+      vi.advanceTimersByTime(TIMEOUT_MS - 10_000)
+      expect(onWarn).toHaveBeenCalledTimes(2)
+      expect(onIdle).not.toHaveBeenCalled()
+    })
+
+    it('stayActive resets the clock like real activity', () => {
+      const onIdle = vi.fn()
+      const onWarn = vi.fn()
+      const onWarnCancelled = vi.fn()
+      const stayActiveRef: { current: (() => void) | null } = { current: null }
+      render(
+        <Harness
+          enabled
+          timeoutMs={TIMEOUT_MS}
+          warningMs={WARNING_MS}
+          onIdle={onIdle}
+          onWarn={onWarn}
+          onWarnCancelled={onWarnCancelled}
+          stayActiveRef={stayActiveRef}
+        />,
+      )
+
+      vi.advanceTimersByTime(TIMEOUT_MS - 10_000)
+      expect(onWarn).toHaveBeenCalledTimes(1)
+
+      stayActiveRef.current?.()
+      expect(onWarnCancelled).toHaveBeenCalledTimes(1)
+
+      vi.advanceTimersByTime(TIMEOUT_MS - 15_000)
+      expect(onIdle).not.toHaveBeenCalled()
+    })
+  })
+})

package/src/__tests__/layout/build-nav-items.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest'
+
+import { buildNavItems } from '../../layout/Sidebar.js'
+
+/**
+ * Mirrors a standard scaffold that enables formsPlugin + seoPlugin +
+ * redirectsPlugin (like the `ntn` site): plugin-forms registers a `forms`
+ * collection grouped under 'Forms', and every plugin's adminNavItems arrive on
+ * `_pluginNavItems`. Before the fix this produced a duplicate "Forms" (static +
+ * grouped collection) and a second "CONTENT" header for the SEO sub-links.
+ */
+function scaffoldLikeConfig() {
+  return {
+    collections: {
+      pages: { slug: 'pages', type: 'page', labels: { plural: 'Pages' } },
+      forms: { slug: 'forms', labels: { plural: 'Forms' }, admin: { group: 'Forms' } },
+      'form-submissions': {
+        slug: 'form-submissions',
+        labels: { plural: 'Form Submissions' },
+        admin: { group: 'Forms' },
+      },
+    },
+    _pluginNavItems: [
+      { label: 'Forms', icon: 'FileText', path: '/forms' },
+      { label: 'Submissions', icon: 'Inbox', path: '/form-submissions' },
+      { label: 'SEO Overview', icon: 'search', path: '/seo' },
+      { label: 'Sitemap', icon: 'map', path: '/seo/sitemap' },
+      { label: 'Link Health', icon: 'link', path: '/seo/link-health' },
+      { label: 'Redirects', icon: 'arrow-right-left', path: '/redirects' },
+    ],
+  }
+}
+
+describe('buildNavItems — duplicate / grouping regressions', () => {
+  it('never emits the same path twice', () => {
+    const paths = buildNavItems(scaffoldLikeConfig()).map((i) => i.path)
+    expect(new Set(paths).size).toBe(paths.length)
+  })
+
+  it('shows Forms exactly once (grouped `forms` collection deduped against the static entry)', () => {
+    const items = buildNavItems(scaffoldLikeConfig())
+    expect(items.filter((i) => i.path === '/forms')).toHaveLength(1)
+  })
+
+  it('keeps the Content group contiguous — no second CONTENT header', () => {
+    const items = buildNavItems(scaffoldLikeConfig())
+    // Once the nav leaves the Content group it must never return to it, or the
+    // renderer emits a duplicate "CONTENT" section header.
+    let leftContent = false
+    for (const item of items) {
+      if (item.group === 'Content') {
+        expect(leftContent).toBe(false)
+      } else if (item.group) {
+        leftContent = true
+      }
+    }
+  })
+
+  it('surfaces the SEO sub-links inside the Content block', () => {
+    const items = buildNavItems(scaffoldLikeConfig())
+    expect(items.find((i) => i.path === '/seo/sitemap')?.group).toBe('Content')
+    expect(items.find((i) => i.path === '/seo/link-health')?.group).toBe('Content')
+  })
+
+  it('excludes admin.hidden collections and does not resurrect removed nav paths', () => {
+    // Post-fix reality: plugin-forms/plugin-redirects no longer advertise
+    // Submissions/Redirects nav items, and their form-submissions/redirects
+    // collections are admin.hidden. Neither should surface a (404-ing) nav path.
+    const items = buildNavItems({
+      collections: {
+        pages: { slug: 'pages', type: 'page', labels: { plural: 'Pages' } },
+        forms: { slug: 'forms', labels: { plural: 'Forms' }, admin: { group: 'Forms' } },
+        'form-submissions': {
+          slug: 'form-submissions',
+          labels: { plural: 'Form Submissions' },
+          admin: { hidden: true },
+        },
+        redirects: { slug: 'redirects', labels: { plural: 'Redirects' }, admin: { hidden: true } },
+      },
+      _pluginNavItems: [
+        { label: 'Forms', icon: 'FileText', path: '/forms' },
+        { label: 'SEO', icon: 'search', path: '/seo' },
+      ],
+    })
+    const paths = items.map((i) => i.path)
+    expect(paths).not.toContain('/form-submissions')
+    expect(paths).not.toContain('/redirects')
+    expect(items.filter((i) => i.path === '/forms')).toHaveLength(1)
+  })
+})

package/src/__tests__/layout/primitives.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest'
+import { tokens } from '../../layout/primitives/tokens.js'
+import * as primitives from '../../layout/primitives/index.js'
+
+describe('layout primitive tokens', () => {
+  it('exposes the canonical spacing scale', () => {
+    expect(tokens.space['0']).toBe(0)
+    expect(tokens.space['1']).toBe(4)
+    expect(tokens.space['4']).toBe(16)
+    expect(tokens.space['8']).toBe(32)
+  })
+
+  it('exposes the canonical radius scale', () => {
+    expect(tokens.radius.none).toBe(0)
+    expect(tokens.radius.sm).toBe(6)
+    expect(tokens.radius.md).toBe(8)
+    expect(tokens.radius.lg).toBe(10)
+    expect(tokens.radius.full).toBe(99)
+  })
+
+  it('exposes layout dimensions from the design system', () => {
+    expect(tokens.layout.sidebarWidth).toBe(224)
+    expect(tokens.layout.sidebarWidthCollapsed).toBe(60)
+    expect(tokens.layout.topbarHeight).toBe(56)
+  })
+
+  it('exposes the canonical breakpoint scale', () => {
+    expect(tokens.breakpoint.sm).toBe(640)
+    expect(tokens.breakpoint.md).toBe(768)
+    expect(tokens.breakpoint.lg).toBe(1024)
+  })
+})
+
+describe('layout primitives exports', () => {
+  it('re-exports every public primitive', () => {
+    expect(typeof primitives.AdminShell).toBe('function')
+    expect(typeof primitives.PageContainer).toBe('function')
+    expect(typeof primitives.Stack).toBe('function')
+    expect(typeof primitives.Cluster).toBe('function')
+    expect(typeof primitives.Grid).toBe('function')
+    expect(typeof primitives.Split).toBe('function')
+    expect(typeof primitives.Box).toBe('object')
+    expect(typeof primitives.tokens).toBe('object')
+  })
+})

package/src/__tests__/layout/sidebar-brand.render.test.tsx

@@ -0,0 +1,142 @@
+// @vitest-environment happy-dom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { fireEvent, render, screen } from '@testing-library/react'
+
+// The sidebar fetches forms unread counts on mount; stub it so these brand
+// tests stay offline and deterministic.
+vi.mock('../../lib/forms-service.js', () => ({
+  fetchFormsSidebarCounts: vi.fn(async () => []),
+}))
+
+// Drive the brand lockup directly via a mutable theme state. happy-dom's
+// localStorage stub is unreliable here, so we mock the theme hook rather than
+// hydrating it. Tests mutate `themeState` before rendering.
+interface ThemeState {
+  adminBrand: {
+    primaryUrl: string | null
+    markUrl: string | null
+    darkUrl: string | null
+    initials: string
+  }
+  resolvedTheme: string
+  density: string
+}
+const DEFAULT_THEME: ThemeState = {
+  adminBrand: { primaryUrl: null, markUrl: null, darkUrl: null, initials: 'AC' },
+  resolvedTheme: 'light',
+  density: 'default',
+}
+let themeState: ThemeState = { ...DEFAULT_THEME }
+
+vi.mock('../../components/ThemeProvider.js', () => ({
+  useTheme: () => themeState,
+}))
+
+const { Sidebar } = await import('../../layout/Sidebar.js')
+
+function setTheme(brand: Partial<ThemeState['adminBrand']>, resolvedTheme = 'light') {
+  themeState = {
+    ...DEFAULT_THEME,
+    resolvedTheme,
+    adminBrand: { ...DEFAULT_THEME.adminBrand, ...brand },
+  }
+}
+
+function renderSidebar(collapsed: boolean, config?: unknown) {
+  return render(
+    <Sidebar
+      collapsed={collapsed}
+      onToggleCollapse={() => {}}
+      currentPath="/"
+      onNavigate={() => {}}
+      config={config}
+    />,
+  )
+}
+
+afterEach(() => {
+  themeState = { ...DEFAULT_THEME }
+})
+
+/**
+ * Brand lockup fallback behaviour. When an install is branded (a site name is
+ * set, so initials exist) but no logo has been uploaded, the sidebar must show
+ * the neutral logo placeholder — NOT a filled initials badge, which reads as a
+ * user avatar (the real account avatar already lives top-right).
+ */
+describe('Sidebar brand placeholder', () => {
+  it('renders the logo placeholder (not an initials avatar) when branded with no logo — expanded', () => {
+    renderSidebar(false, { admin: { branding: { name: 'Acme Co' } } })
+
+    // Placeholder slot is present and the brand name shows beside it.
+    expect(screen.getByText('Acme Co')).toBeTruthy()
+    // The old avatar-style initials badge must not render.
+    expect(screen.queryByText('AC')).toBeNull()
+  })
+
+  it('renders the logo placeholder slot when branded with no logo — collapsed', () => {
+    renderSidebar(true)
+
+    expect(screen.getByRole('img', { name: 'Logo placeholder' })).toBeTruthy()
+    expect(screen.queryByText('AC')).toBeNull()
+  })
+})
+
+describe('Sidebar brand logo rendering', () => {
+  it('shows the primary logo (scaled to fit) when collapsed — never the favicon', () => {
+    setTheme({ primaryUrl: 'https://cdn.example.com/logo.svg' })
+    renderSidebar(true)
+
+    const img = screen.getByRole('img', { name: 'Admin' }) as HTMLImageElement
+    expect(img.src).toContain('logo.svg')
+    // Wide logos must be width-capped so they scale down instead of overflowing.
+    expect(img.className).toContain('max-w-full')
+  })
+
+  it('caps the expanded logo width so wide logos stay responsive', () => {
+    setTheme({ primaryUrl: 'https://cdn.example.com/logo.svg' })
+    renderSidebar(false)
+
+    const img = screen.getByRole('img', { name: 'Admin' }) as HTMLImageElement
+    expect(img.className).toContain('max-w-full')
+    expect(img.className).toContain('object-contain')
+  })
+
+  it('does not duplicate the site name beside a primary logo', () => {
+    setTheme({ primaryUrl: 'https://cdn.example.com/logo.svg' })
+    renderSidebar(false, { admin: { branding: { name: 'Acme Co' } } })
+
+    expect(screen.getByRole('img', { name: 'Acme Co' })).toBeTruthy()
+    expect(screen.queryByText('Acme Co')).toBeNull()
+  })
+
+  it('prefers the dark logo in dark mode and falls back to primary on error', () => {
+    setTheme(
+      {
+        primaryUrl: 'https://cdn.example.com/logo.svg',
+        darkUrl: 'https://cdn.example.com/dark.svg',
+      },
+      'dark',
+    )
+    renderSidebar(false)
+
+    const img = screen.getByRole('img', { name: 'Admin' }) as HTMLImageElement
+    expect(img.src).toContain('dark.svg')
+  })
+
+  it('falls through to the placeholder when the logo URL is broken (onError)', () => {
+    setTheme({ primaryUrl: 'https://cdn.example.com/broken.svg' })
+    renderSidebar(false, { admin: { branding: { name: 'Acme Co' } } })
+
+    // With a brand name configured, the logo alt is the brand name.
+    const img = screen.getByRole('img', { name: 'Acme Co' }) as HTMLImageElement
+    expect(img.src).toContain('broken.svg')
+    // Simulate the asset URL failing to load.
+    fireEvent.error(img)
+
+    // The broken logo is gone; the neutral placeholder + brand name take over
+    // (no browser broken-image glyph left behind).
+    expect(screen.queryByRole('img', { name: 'Acme Co' })).toBeNull()
+    expect(screen.getByText('Acme Co')).toBeTruthy()
+  })
+})

package/src/__tests__/layout/sidebar-forms-badge.render.test.tsx

@@ -0,0 +1,50 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+
+// The Forms nav item shows a live unread total summed across active forms.
+// Mock the sidebar-counts fetcher so the badge math is deterministic.
+const fetchFormsSidebarCounts = vi.fn(async () => [
+  { formId: 'f1', name: 'Contact Us', slug: 'contact-us', status: 'active', unread: 8 },
+  { formId: 'f2', name: 'Project Inquiry', slug: 'project-inquiry', status: 'active', unread: 3 },
+])
+
+vi.mock('../../lib/forms-service.js', () => ({
+  fetchFormsSidebarCounts: () => fetchFormsSidebarCounts(),
+}))
+
+const { Sidebar } = await import('../../layout/Sidebar.js')
+
+describe('Sidebar forms unread badge', () => {
+  it('sums unread across active forms onto the Forms item', async () => {
+    render(
+      <Sidebar
+        collapsed={false}
+        onToggleCollapse={() => {}}
+        currentPath="/"
+        onNavigate={() => {}}
+      />,
+    )
+
+    // 8 + 3 = 11 unread surfaced as the Forms badge.
+    await waitFor(() => expect(screen.getByLabelText('11 unread')).toBeTruthy())
+  })
+
+  it('renders no badge when there are no unread submissions', async () => {
+    fetchFormsSidebarCounts.mockResolvedValueOnce([
+      { formId: 'f1', name: 'Newsletter', slug: 'newsletter', status: 'active', unread: 0 },
+    ])
+
+    render(
+      <Sidebar
+        collapsed={false}
+        onToggleCollapse={() => {}}
+        currentPath="/"
+        onNavigate={() => {}}
+      />,
+    )
+
+    await screen.findByText('Forms')
+    expect(screen.queryByLabelText(/unread$/)).toBeNull()
+  })
+})

package/src/__tests__/layout/sidebar-forms-submenu.render.test.tsx

@@ -0,0 +1,38 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+
+// The Forms nav item expands into a submenu: an "All Entries" child plus one
+// child per active form carrying its own unread badge. Mock the sidebar-counts
+// fetcher so the children are deterministic.
+// Distinct per-form counts so a child badge can't collide with the parent
+// total badge (8 + 5 = 13).
+const fetchFormsSidebarCounts = vi.fn(async () => [
+  { formId: 'f1', name: 'Contact Us', slug: 'contact-us', status: 'active', unread: 8 },
+  { formId: 'f2', name: 'Project Inquiry', slug: 'project-inquiry', status: 'active', unread: 5 },
+])
+
+vi.mock('../../lib/forms-service.js', () => ({
+  fetchFormsSidebarCounts: () => fetchFormsSidebarCounts(),
+}))
+
+const { Sidebar } = await import('../../layout/Sidebar.js')
+
+describe('Sidebar Forms submenu', () => {
+  it('renders All Entries plus a child per active form', async () => {
+    render(
+      <Sidebar
+        collapsed={false}
+        onToggleCollapse={() => {}}
+        currentPath="/forms"
+        onNavigate={() => {}}
+      />,
+    )
+
+    await waitFor(() => expect(screen.getByText('All Entries')).toBeTruthy())
+    // Per-form children (the Contact Us label also appears; scope to nav links).
+    expect(screen.getByText('Project Inquiry')).toBeTruthy()
+    // The form with unread submissions shows its own badge.
+    expect(screen.getByLabelText('8 unread')).toBeTruthy()
+  })
+})

package/src/__tests__/layout/sidebar-plugin-nav.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+import { buildNavItems } from '../../layout/Sidebar.js'
+
+// Plugin adminNavItems (collected onto `_pluginNavItems` by cms-core's
+// applyPlugins) must surface in the admin sidebar, without doubling a built-in
+// destination or one of the plugin's own collections.
+const baseCollections = {
+  collections: {
+    pages: { slug: 'pages', labels: { singular: 'Page', plural: 'Pages' }, type: 'page' },
+  },
+}
+
+describe('buildNavItems — plugin nav items', () => {
+  it('adds a plugin-contributed custom nav link', () => {
+    const items = buildNavItems({
+      ...baseCollections,
+      _pluginNavItems: [{ label: 'Redirects', icon: 'arrow-right-left', path: '/redirects' }],
+    })
+    const redirects = items.find((i) => i.path === '/redirects')
+    expect(redirects).toBeDefined()
+    expect(redirects?.label).toBe('Redirects')
+    expect(redirects?.group).toBe('Content')
+  })
+
+  it('does not double a built-in destination path', () => {
+    const items = buildNavItems({
+      ...baseCollections,
+      _pluginNavItems: [{ label: 'Media Library', icon: 'image', path: '/media' }],
+    })
+    expect(items.filter((i) => i.path === '/media')).toHaveLength(1)
+  })
+
+  it('falls back to a default icon for an unknown icon string and still renders', () => {
+    const items = buildNavItems({
+      ...baseCollections,
+      _pluginNavItems: [{ label: 'Custom', icon: 'no-such-icon', path: '/custom' }],
+    })
+    const custom = items.find((i) => i.path === '/custom')
+    expect(custom).toBeDefined()
+    expect(custom?.icon).toBeTruthy()
+  })
+
+  it('ignores malformed plugin nav entries', () => {
+    const items = buildNavItems({
+      ...baseCollections,
+      _pluginNavItems: [{ label: 'No path' }, null, { path: '/ok', label: 'Ok', icon: 'menu' }],
+    })
+    expect(items.find((i) => i.path === '/ok')).toBeDefined()
+  })
+})