From ab331b6b4432c95c2ecbe31b3cc892bb63a855c3 Mon Sep 17 00:00:00 2001
From: Ross Lovas <rosslovas@users.noreply.github.com>
Date: Tue, 11 Aug 2026 11:38:01 +0930
Subject: [PATCH 1/3] Add logged-in state to WIP new top nav

---
 dictionary-octopus.txt             |   5 +
 src/components/Avatar.astro        | 143 ++++++++++++++++++++++++++
 src/components/TopNav.astro        |  24 ++++-
 src/lib/avatar.ts                  |  59 +++++++++++
 src/lib/signedInUser.ts            |  68 +++++++++++++
 src/pages/components.mdx           |  23 +++++
 src/scripts/avatar.ts              |  71 +++++++++++++
 src/scripts/signed-in-user.ts      |  74 ++++++++++++++
 src/styles/button.css              |   4 +
 tests/avatar-fallback-text.spec.ts |  50 +++++++++
 tests/topnav-signedin.spec.ts      | 157 +++++++++++++++++++++++++++++
 11 files changed, 676 insertions(+), 2 deletions(-)
 create mode 100644 src/components/Avatar.astro
 create mode 100644 src/lib/avatar.ts
 create mode 100644 src/lib/signedInUser.ts
 create mode 100644 src/scripts/avatar.ts
 create mode 100644 src/scripts/signed-in-user.ts
 create mode 100644 tests/avatar-fallback-text.spec.ts
 create mode 100644 tests/topnav-signedin.spec.ts

diff --git a/dictionary-octopus.txt b/dictionary-octopus.txt
index 3d54554a5e..45b0d8d11c 100644
--- a/dictionary-octopus.txt
+++ b/dictionary-octopus.txt
@@ -6,6 +6,7 @@ advfirewall
 agentic
 allatclaims
 ALLUSERSPROFILE
+andré
 anglin
 anotherdir
 Antiforgery
@@ -59,6 +60,7 @@ buildevent
 buildinfo
 buildmetadata
 CAIQ
+çelik
 Ceph
 certkeyName
 Certstore
@@ -182,6 +184,7 @@ fontawesome
 frontmatter
 functionapp
 g3662re9njtelsyfhm7t
+García
 gcloud
 gcore
 getenv
@@ -246,6 +249,7 @@ ITSM
 javac
 jdbc
 jjones
+José
 journalctl
 jsondecode
 JSSE
@@ -309,6 +313,7 @@ msiexec
 mssqldb
 MSSQLSERVER
 MTTR
+Müller
 multifactor
 Multipath
 multistep
diff --git a/src/components/Avatar.astro b/src/components/Avatar.astro
new file mode 100644
index 0000000000..81a0ce2f55
--- /dev/null
+++ b/src/components/Avatar.astro
@@ -0,0 +1,143 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import type { AvatarShape, AvatarSize } from '../lib/avatar';
+
+type SharedProps = {
+  size: AvatarSize;
+  shape: AvatarShape;
+  src?: string;
+  srcSet?: string;
+  alt?: string;
+  isMuted?: boolean;
+  title?: string;
+};
+
+type Props =
+  | (HTMLAttributes<'div'> & SharedProps & { href?: never })
+  | (HTMLAttributes<'a'> & SharedProps & { href: string | URL });
+
+const {
+  size,
+  shape,
+  src,
+  srcSet,
+  alt = '',
+  isMuted = false,
+  title,
+  href,
+  class: className,
+  ...rest
+} = Astro.props satisfies Props;
+
+const classes = `avatar avatar--${size} avatar--${shape}${isMuted ? ' avatar--muted' : ''}${className ? ` ${className}` : ''}`;
+
+const Tag = href ? 'a' : 'div';
+---
+
+<Tag
+  class={classes}
+  title={title}
+  {...href ? { href } : {}}
+  {...rest}
+  data-avatar
+  data-avatar-size={size}
+>
+  <span class="avatar__fallback" data-avatar-fallback><slot /></span>
+  <img
+    class="avatar__image"
+    src={src}
+    srcset={srcSet}
+    alt={alt}
+    data-avatar-image
+    hidden
+  />
+</Tag>
+
+<script>
+  import '../scripts/avatar';
+</script>
+
+<style>
+  .avatar {
+    position: relative;
+    display: flex;
+    flex-shrink: 0;
+    align-items: center;
+    justify-content: center;
+    overflow: hidden;
+    container-type: inline-size;
+    background: var(--colorAvatarBackgroundUserDefault);
+    color: var(--colorAvatarText);
+    font-weight: 400;
+    text-decoration: none;
+    text-transform: uppercase;
+    user-select: none;
+    transition: background-color 150ms ease-in-out;
+  }
+
+  .avatar[hidden] {
+    display: none;
+  }
+
+  .avatar--small {
+    width: 20px;
+    height: 20px;
+  }
+
+  .avatar--medium {
+    width: 36px;
+    height: 36px;
+  }
+
+  .avatar--large {
+    width: 48px;
+    height: 48px;
+  }
+
+  .avatar--circle {
+    border-radius: var(--borderRadiusCircle);
+  }
+
+  .avatar--rounded {
+    border-radius: var(--borderRadiusSmall);
+  }
+
+  .avatar--muted {
+    opacity: 0.4;
+  }
+
+  .avatar__fallback {
+    display: block;
+    margin: 0;
+    color: var(--colorAvatarText);
+    font-size: 44cqi;
+  }
+
+  .avatar__fallback[hidden] {
+    display: none;
+  }
+
+  .avatar__image {
+    width: 100%;
+    height: 100%;
+    aspect-ratio: 1 / 1;
+    background: var(--colorAvatarBackgroundImageDefault);
+    object-fit: scale-down;
+    transition: background-color 150ms ease-in-out;
+  }
+
+  a.avatar:hover,
+  a.avatar:focus-visible {
+    background: var(--colorAvatarBackgroundUserHover);
+    color: var(--colorAvatarText);
+  }
+
+  a.avatar:focus-visible {
+    outline: var(--borderWidth2) solid var(--colorBorderSelected);
+    outline-offset: var(--borderWidth2);
+  }
+
+  a.avatar:hover .avatar__image {
+    background: var(--colorAvatarBackgroundImageHover);
+  }
+</style>
diff --git a/src/components/TopNav.astro b/src/components/TopNav.astro
index 7ef723885e..0b32e3f792 100644
--- a/src/components/TopNav.astro
+++ b/src/components/TopNav.astro
@@ -1,5 +1,6 @@
 ---
 import Logo from '../assets/octopus-logo-v2.svg';
+import Avatar from './Avatar.astro';
 import Button from './Button.astro';
 
 type Props = {
@@ -50,7 +51,26 @@ const {
     <Button icon="fa-regular fa-moon" aria-label="Switch to dark theme" />
     <!-- TODO: Make these real links -->
     <Button label="Changelog" href="#" />
-    <Button label="Sign in" href="#" />
-    <Button label="Start for free" href="#" importance="loud" />
+    <Button label="Sign in" href="#" data-signed-out-only />
+    <Button
+      label="Start for free"
+      href="#"
+      importance="loud"
+      data-signed-out-only
+    />
+    <Avatar
+      size="medium"
+      shape="circle"
+      alt=""
+      data-signed-in-only
+      data-user-avatar
+      hidden
+    >
+      <span data-user-initials></span>
+    </Avatar>
   </div>
 </header>
+
+<script>
+  import '../scripts/signed-in-user';
+</script>
diff --git a/src/lib/avatar.ts b/src/lib/avatar.ts
new file mode 100644
index 0000000000..891d02f2f1
--- /dev/null
+++ b/src/lib/avatar.ts
@@ -0,0 +1,59 @@
+export type AvatarSize = 'large' | 'medium' | 'small';
+export type AvatarShape = 'circle' | 'rounded';
+
+export const avatarSizeMap: Record<AvatarSize, number> = {
+  small: 20,
+  medium: 36,
+  large: 48,
+};
+
+export function isAvatarSize(value: unknown): value is AvatarSize {
+  return value === 'small' || value === 'medium' || value === 'large';
+}
+
+export function generateFallbackText(text: string): string {
+  const trimmedText = text.trim();
+  if (!trimmedText) return '';
+
+  const words = trimmedText.split(/\s+/);
+
+  if (words.length > 1) {
+    const firstWord = words[0] ?? '';
+    const lastWord = words[words.length - 1] ?? '';
+
+    return [firstWord, lastWord]
+      .map((word) => Array.from(word.trim())[0])
+      .filter((character): character is string => !!character)
+      .join('')
+      .toUpperCase();
+  }
+
+  return Array.from(trimmedText).slice(0, 2).join('').toUpperCase();
+}
+
+export function getAvatarImageUrls(
+  src: string,
+  size: AvatarSize
+): { avatarImageUrl: string; srcSet: string } {
+  const avatarImageSize = avatarSizeMap[size];
+
+  try {
+    const url = new URL(src);
+
+    url.searchParams.set('d', '404');
+    url.searchParams.set('s', avatarImageSize.toString());
+    const avatarImageUrl = url.toString();
+
+    const srcSet = [1, 2, 3]
+      .map((scale) => {
+        const scaledUrl = new URL(url.toString());
+        scaledUrl.searchParams.set('s', (avatarImageSize * scale).toString());
+        return `${scaledUrl.toString()} ${scale}x`;
+      })
+      .join(', ');
+
+    return { avatarImageUrl, srcSet };
+  } catch {
+    return { avatarImageUrl: src, srcSet: '' };
+  }
+}
diff --git a/src/lib/signedInUser.ts b/src/lib/signedInUser.ts
new file mode 100644
index 0000000000..6e9a4f71c9
--- /dev/null
+++ b/src/lib/signedInUser.ts
@@ -0,0 +1,68 @@
+export const USER_COOKIE = 'OctopusSignedInUser';
+export const USER_CHANGED_EVENT = 'octopus:user-changed';
+
+export type SignedInUser = {
+  email?: string;
+  fullName?: string;
+  profileImageUrl?: string;
+  userHash?: string;
+};
+
+function isSignedInUser(value: unknown): value is SignedInUser {
+  if (!value || typeof value !== 'object') return false;
+  const user = value as SignedInUser;
+  const hasEmail = typeof user.email === 'string' && user.email.length > 0;
+  const hasName = typeof user.fullName === 'string' && user.fullName.length > 0;
+  return hasEmail || hasName;
+}
+
+function readCookie(): string | null {
+  const match = document.cookie.match(
+    new RegExp(`(^|;\\s*)${USER_COOKIE}=([^;]+)`)
+  );
+  return match ? decodeURIComponent(match[2]) : null;
+}
+
+export function getSignedInUser(): SignedInUser | null {
+  const cookie = readCookie();
+  if (!cookie) return null;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(cookie);
+  } catch {
+    return null;
+  }
+
+  return isSignedInUser(parsed) ? parsed : null;
+}
+
+export function safeImageUrl(value: unknown): string {
+  if (typeof value !== 'string' || !value) return '';
+  try {
+    const url = new URL(value, window.location.origin);
+    return url.protocol === 'https:' || url.protocol === 'http:'
+      ? url.href
+      : '';
+  } catch {
+    return '';
+  }
+}
+
+export function addSignedInUserChangedListener(callback: () => void) {
+  const cookieStore = (window as Window & { cookieStore?: EventTarget })
+    .cookieStore;
+
+  if (cookieStore) {
+    cookieStore.addEventListener('change', (event) => {
+      const { changed = [], deleted = [] } = event;
+      if (
+        [...changed, ...deleted].some((cookie) => cookie.name === USER_COOKIE)
+      ) {
+        callback();
+      }
+    });
+  }
+
+  window.addEventListener(USER_CHANGED_EVENT, callback);
+}
diff --git a/src/pages/components.mdx b/src/pages/components.mdx
index 1e54ce5dd2..96f03bd28e 100644
--- a/src/pages/components.mdx
+++ b/src/pages/components.mdx
@@ -13,6 +13,7 @@ robots: noindex, follow
 listable: false # stop the oldest-content report from listing this page
 ---
 
+import Avatar from 'src/components/Avatar.astro';
 import Button from 'src/components/Button.astro';
 import Card from 'src/components/Card.astro';
 import IconTile from 'src/components/IconTile.astro';
@@ -165,6 +166,28 @@ An icon-only button has no visible text, so include an `aria-label` to give it a
   </div>
 </div>
 
+### Avatar
+
+<div class="docs-home simple-grid">
+  <div class="btn-row">
+    <Avatar size="small" shape="circle">JD</Avatar>
+    <Avatar size="medium" shape="circle">JD</Avatar>
+    <Avatar size="large" shape="circle">JD</Avatar>
+    <Avatar size="medium" shape="rounded">JD</Avatar>
+    <Avatar size="medium" shape="circle" isMuted={true}>JD</Avatar>
+    <Avatar size="medium" shape="circle" src="/docs/img/octopus-deploy-logo.png" alt="">JD</Avatar>
+    <Avatar size="medium" shape="circle" src="/docs/img/does-not-exist.png" alt="">JD</Avatar>
+  </div>
+  <div>
+    ```
+    <Avatar size="medium" shape="circle">JD</Avatar>
+    <Avatar size="medium" shape="rounded">JD</Avatar>
+    <Avatar size="medium" shape="circle" isMuted={true}>JD</Avatar>
+    <Avatar size="medium" shape="circle" src="/path/to/image.png" alt="">JD</Avatar>
+    ```
+  </div>
+</div>
+
 ### TopNav
 
 Temporary showcase for the new, work-in-progress TopNav component.
diff --git a/src/scripts/avatar.ts b/src/scripts/avatar.ts
new file mode 100644
index 0000000000..198dbc2868
--- /dev/null
+++ b/src/scripts/avatar.ts
@@ -0,0 +1,71 @@
+const AVATAR_SELECTOR = '[data-avatar]';
+const IMAGE_SELECTOR = '[data-avatar-image]';
+const FALLBACK_SELECTOR = '[data-avatar-fallback]';
+
+function showImage(avatar: HTMLElement, image: HTMLImageElement) {
+  const fallback = avatar.querySelector<HTMLElement>(FALLBACK_SELECTOR);
+  if (fallback) fallback.hidden = true;
+  image.hidden = false;
+}
+
+function showFallback(avatar: HTMLElement, image: HTMLImageElement) {
+  const fallback = avatar.querySelector<HTMLElement>(FALLBACK_SELECTOR);
+  if (fallback) fallback.hidden = false;
+  image.hidden = true;
+}
+
+function watch(avatar: HTMLElement, image: HTMLImageElement) {
+  if (image.complete) {
+    if (image.naturalWidth > 0) showImage(avatar, image);
+    return;
+  }
+
+  image.addEventListener('load', () => showImage(avatar, image), {
+    once: true,
+  });
+}
+
+export function setAvatarImage(
+  avatar: HTMLElement,
+  src: string,
+  srcSet: string = ''
+) {
+  const image = avatar.querySelector<HTMLImageElement>(IMAGE_SELECTOR);
+  if (!image) return;
+
+  if (!src) {
+    image.removeAttribute('srcset');
+    image.removeAttribute('src');
+    showFallback(avatar, image);
+    return;
+  }
+
+  if (
+    image.getAttribute('src') !== src ||
+    (image.getAttribute('srcset') ?? '') !== srcSet
+  ) {
+    showFallback(avatar, image);
+    if (srcSet) {
+      image.srcset = srcSet;
+    } else {
+      image.removeAttribute('srcset');
+    }
+    image.src = src;
+  }
+
+  watch(avatar, image);
+}
+
+function bind(avatar: HTMLElement) {
+  const image = avatar.querySelector<HTMLImageElement>(IMAGE_SELECTOR);
+  if (!image || !image.getAttribute('src')) return;
+  watch(avatar, image);
+}
+
+function bindAll() {
+  document.querySelectorAll<HTMLElement>(AVATAR_SELECTOR).forEach(bind);
+}
+
+bindAll();
+
+document.addEventListener('astro:after-swap', bindAll);
diff --git a/src/scripts/signed-in-user.ts b/src/scripts/signed-in-user.ts
new file mode 100644
index 0000000000..24ee567a82
--- /dev/null
+++ b/src/scripts/signed-in-user.ts
@@ -0,0 +1,74 @@
+import {
+  getSignedInUser,
+  addSignedInUserChangedListener,
+  safeImageUrl,
+  type SignedInUser,
+} from '../lib/signedInUser';
+import {
+  generateFallbackText,
+  getAvatarImageUrls,
+  isAvatarSize,
+} from '../lib/avatar';
+import { setAvatarImage } from './avatar';
+
+const SIGNED_OUT_ONLY_SELECTOR = '[data-signed-out-only]';
+const SIGNED_IN_ONLY_SELECTOR = '[data-signed-in-only]';
+const USER_AVATAR_SELECTOR = '[data-user-avatar]';
+const USER_INITIALS_SELECTOR = '[data-user-initials]';
+
+function displayName(user: SignedInUser): string {
+  return user.fullName?.trim() || user.email?.trim() || '';
+}
+
+function avatarSize(avatar: HTMLElement) {
+  const size = avatar.dataset.avatarSize;
+  return isAvatarSize(size) ? size : 'medium';
+}
+
+function toggle(selector: string, hidden: boolean) {
+  document.querySelectorAll<HTMLElement>(selector).forEach((el) => {
+    el.hidden = hidden;
+  });
+}
+
+function apply() {
+  const user = getSignedInUser();
+
+  toggle(SIGNED_OUT_ONLY_SELECTOR, user !== null);
+  toggle(SIGNED_IN_ONLY_SELECTOR, user === null);
+
+  if (user) {
+    const name = displayName(user);
+    const imageUrl = safeImageUrl(user.profileImageUrl);
+
+    document
+      .querySelectorAll<HTMLElement>(USER_AVATAR_SELECTOR)
+      .forEach((avatar) => {
+        const target = avatar.querySelector<HTMLElement>(
+          USER_INITIALS_SELECTOR
+        );
+        if (target) {
+          target.textContent = generateFallbackText(name);
+          if (name) target.title = name;
+        }
+
+        if (name) avatar.title = name;
+
+        if (!imageUrl) {
+          setAvatarImage(avatar, '');
+          return;
+        }
+
+        const { avatarImageUrl, srcSet } = getAvatarImageUrls(
+          imageUrl,
+          avatarSize(avatar)
+        );
+        setAvatarImage(avatar, avatarImageUrl, srcSet);
+      });
+  }
+}
+
+apply();
+addSignedInUserChangedListener(apply);
+
+document.addEventListener('astro:after-swap', apply);
diff --git a/src/styles/button.css b/src/styles/button.css
index bbefb2c05f..2a97108cf1 100644
--- a/src/styles/button.css
+++ b/src/styles/button.css
@@ -21,6 +21,10 @@
   text-decoration: none;
 }
 
+.btn[hidden] {
+  display: none;
+}
+
 .btn--medium {
   --btn-min-size: 2.25rem;
   --btn-padding-block: var(--space8);
diff --git a/tests/avatar-fallback-text.spec.ts b/tests/avatar-fallback-text.spec.ts
new file mode 100644
index 0000000000..3fa846a465
--- /dev/null
+++ b/tests/avatar-fallback-text.spec.ts
@@ -0,0 +1,50 @@
+import { test, expect } from '@playwright/test';
+import { generateFallbackText } from '../src/lib/avatar';
+
+const cases: [string, string][] = [
+  ['', ''],
+  ['   ', ''],
+  ['\t', ''],
+  ['A', 'A'],
+  ['a', 'A'],
+  ['John', 'JO'],
+  ['alice', 'AL'],
+  ['ADMIN', 'AD'],
+  ['jOhN', 'JO'],
+  ['John Doe', 'JD'],
+  ['john doe', 'JD'],
+  ['John Michael Doe', 'JD'],
+  ['Mary Jane Watson Smith', 'MS'],
+  ['John   Doe', 'JD'],
+  ['  John  \n  Doe  ', 'JD'],
+  ['😀', '😀'],
+  ['😀A', '😀A'],
+  ['😀John', '😀J'],
+  ['John😀', 'JO'],
+  ['😀John 😀Doe', '😀😀'],
+  ['@john', '@J'],
+  ['user123', 'US'],
+  ['user-name', 'US'],
+  ['José', 'JO'],
+  ['Müller', 'MÜ'],
+  ['北京', '北京'],
+  ['José García', 'JG'],
+  ['andré çelik', 'AÇ'],
+  ['王 Wei', '王W'],
+  ['123', '12'],
+  ['123 456', '14'],
+  ['ß', 'SS'],
+  ['ø', 'Ø'],
+  ['Smith, John', 'SJ'],
+  ['Dr. John Smith', 'DS'],
+  ['john.doe@company.com', 'JO'],
+  ['test.user+tag@domain.org', 'TE'],
+];
+
+test('generateFallbackText returns expected fallback string', () => {
+  for (const [input, expected] of cases) {
+    expect(generateFallbackText(input), `input: ${JSON.stringify(input)}`).toBe(
+      expected
+    );
+  }
+});
diff --git a/tests/topnav-signedin.spec.ts b/tests/topnav-signedin.spec.ts
new file mode 100644
index 0000000000..42cbce6919
--- /dev/null
+++ b/tests/topnav-signedin.spec.ts
@@ -0,0 +1,157 @@
+import { test, expect, type Page } from '@playwright/test';
+
+const showcase = '/components';
+
+const nav = '.top-nav';
+const trailing = '.top-nav__trailing';
+const avatar = `${nav} [data-user-avatar]`;
+
+async function signIn(
+  page: Page,
+  baseURL: string | undefined,
+  user: Record<string, string>
+) {
+  await page.context().addCookies([
+    {
+      name: 'OctopusSignedInUser',
+      value: encodeURIComponent(JSON.stringify(user)),
+      url: new URL(showcase, baseURL).toString(),
+    },
+  ]);
+}
+
+test.describe('top nav signed-in state', () => {
+  test('shows the sign in and sign up buttons when signed out', async ({
+    page,
+  }) => {
+    await page.goto(showcase);
+
+    await expect(page.locator(trailing).getByText('Sign in')).toBeVisible();
+    await expect(
+      page.locator(trailing).getByText('Start for free')
+    ).toBeVisible();
+    await expect(page.locator(avatar)).toBeHidden();
+  });
+
+  test('swaps those buttons for an initials avatar when signed in', async ({
+    page,
+    baseURL,
+  }) => {
+    await signIn(page, baseURL, {
+      fullName: 'John Doe',
+      email: 'jd@example.com',
+    });
+    await page.goto(showcase);
+
+    await expect(page.locator(trailing).getByText('Sign in')).toBeHidden();
+    await expect(
+      page.locator(trailing).getByText('Start for free')
+    ).toBeHidden();
+    await expect(page.locator(trailing).getByText('Changelog')).toBeVisible();
+
+    await expect(page.locator(avatar)).toBeVisible();
+    await expect(page.locator(`${avatar} [data-user-initials]`)).toHaveText(
+      'JD'
+    );
+    await expect(page.locator(avatar)).toHaveAttribute(
+      'title',
+      'John Doe'
+    );
+  });
+
+  test('takes the first two characters of a single-word name', async ({
+    page,
+    baseURL,
+  }) => {
+    await signIn(page, baseURL, { fullName: 'John' });
+    await page.goto(showcase);
+
+    await expect(page.locator(`${avatar} [data-user-initials]`)).toHaveText(
+      'JO'
+    );
+  });
+
+  test('falls back to the email when there is no name', async ({
+    page,
+    baseURL,
+  }) => {
+    await signIn(page, baseURL, { email: 'jd@example.com' });
+    await page.goto(showcase);
+
+    await expect(page.locator(`${avatar} [data-user-initials]`)).toHaveText(
+      'JD'
+    );
+  });
+
+  test('requests the image at the avatar size and 404s rather than defaulting', async ({
+    page,
+    baseURL,
+  }) => {
+    await signIn(page, baseURL, {
+      fullName: 'John Doe',
+      profileImageUrl: new URL(
+        '/docs/img/octopus-deploy-logo.png',
+        baseURL
+      ).toString(),
+    });
+    await page.goto(showcase);
+
+    const image = page.locator(`${avatar} [data-avatar-image]`);
+    const src = new URL((await image.getAttribute('src')) ?? '', baseURL);
+    expect(src.searchParams.get('d')).toBe('404');
+    expect(src.searchParams.get('s')).toBe('36');
+
+    const srcSet = (await image.getAttribute('srcset')) ?? '';
+    expect(srcSet).toContain('s=36 1x');
+    expect(srcSet).toContain('s=72 2x');
+    expect(srcSet).toContain('s=108 3x');
+  });
+
+  test('shows the profile image when one loads', async ({ page, baseURL }) => {
+    await signIn(page, baseURL, {
+      fullName: 'John Doe',
+      profileImageUrl: new URL(
+        '/docs/img/octopus-deploy-logo.png',
+        baseURL
+      ).toString(),
+    });
+    await page.goto(showcase);
+
+    await expect(page.locator(`${avatar} [data-avatar-image]`)).toBeVisible();
+    await expect(page.locator(`${avatar} [data-avatar-fallback]`)).toBeHidden();
+  });
+
+  test('keeps the initials when the profile image fails to load', async ({
+    page,
+    baseURL,
+  }) => {
+    await signIn(page, baseURL, {
+      fullName: 'John Doe',
+      profileImageUrl: new URL(
+        '/docs/img/no-such-image.png',
+        baseURL
+      ).toString(),
+    });
+    await page.goto(showcase);
+
+    await expect(
+      page.locator(`${avatar} [data-avatar-fallback]`)
+    ).toBeVisible();
+    await expect(page.locator(`${avatar} [data-avatar-image]`)).toBeHidden();
+  });
+
+  test('rejects a non-http profile image url', async ({ page, baseURL }) => {
+    await signIn(page, baseURL, {
+      fullName: 'John Doe',
+      profileImageUrl: 'javascript:alert(1)',
+    });
+    await page.goto(showcase);
+
+    await expect(
+      page.locator(`${avatar} [data-avatar-fallback]`)
+    ).toBeVisible();
+    await expect(
+      page.locator(`${avatar} [data-avatar-image]`)
+    ).not.toHaveAttribute('src');
+  });
+});

From 656542ad75aa5e44447aa0d6de880daf08c3e37c Mon Sep 17 00:00:00 2001
From: Ross Lovas <rosslovas@users.noreply.github.com>
Date: Tue, 11 Aug 2026 14:37:09 +0930
Subject: [PATCH 2/3] Exclude tests from spellcheck

---
 cspell.json            | 1 +
 dictionary-octopus.txt | 5 -----
 2 files changed, 1 insertion(+), 5 deletions(-)

diff --git a/cspell.json b/cspell.json
index ad7b787683..4777dcd8b2 100644
--- a/cspell.json
+++ b/cspell.json
@@ -64,6 +64,7 @@
     "src/pages/report/**",
     "src/fallback/**",
     "src/scripts/**",
+    "tests/**",
     "node_modules/**",
     "public/docs/css/fa/**",
     "assets/diagrams/**"
diff --git a/dictionary-octopus.txt b/dictionary-octopus.txt
index 45b0d8d11c..3d54554a5e 100644
--- a/dictionary-octopus.txt
+++ b/dictionary-octopus.txt
@@ -6,7 +6,6 @@ advfirewall
 agentic
 allatclaims
 ALLUSERSPROFILE
-andré
 anglin
 anotherdir
 Antiforgery
@@ -60,7 +59,6 @@ buildevent
 buildinfo
 buildmetadata
 CAIQ
-çelik
 Ceph
 certkeyName
 Certstore
@@ -184,7 +182,6 @@ fontawesome
 frontmatter
 functionapp
 g3662re9njtelsyfhm7t
-García
 gcloud
 gcore
 getenv
@@ -249,7 +246,6 @@ ITSM
 javac
 jdbc
 jjones
-José
 journalctl
 jsondecode
 JSSE
@@ -313,7 +309,6 @@ msiexec
 mssqldb
 MSSQLSERVER
 MTTR
-Müller
 multifactor
 Multipath
 multistep

From 36b5b53f4cf3d93d2316ba67e3a479eff00e588e Mon Sep 17 00:00:00 2001
From: Ross Lovas <rosslovas@users.noreply.github.com>
Date: Tue, 11 Aug 2026 14:28:50 +0930
Subject: [PATCH 3/3] Fill out WIP TopNav, make it possible to preview with
 ?newnav

---
 dictionary-octopus.txt                    |   1 +
 src/components/Header.astro               |  36 +++++++
 src/components/TopNav.astro               | 120 +++++++++++++++++++---
 src/pages/docs/octopus-rest-api/index.mdx |   6 +-
 src/scripts/theme-switcher.ts             |  29 ++++++
 src/styles/main.css                       |  90 +++-------------
 src/styles/vars.css                       |   1 +
 tests/topnav-signedin.spec.ts             |   4 +-
 8 files changed, 194 insertions(+), 93 deletions(-)

diff --git a/dictionary-octopus.txt b/dictionary-octopus.txt
index 3d54554a5e..2b564d5573 100644
--- a/dictionary-octopus.txt
+++ b/dictionary-octopus.txt
@@ -333,6 +333,7 @@ netstandard
 newcert
 newguid
 NEWID
+newnav
 Newtonsoft
 nfsadmin
 nlog
diff --git a/src/components/Header.astro b/src/components/Header.astro
index 35d6a484dc..8115af8901 100644
--- a/src/components/Header.astro
+++ b/src/components/Header.astro
@@ -7,6 +7,7 @@ import Search from '../themes/octopus/components/Search.astro';
 import MobileMenu from './MobileMenu.astro';
 import OctopusLogo from './icons/OctopusLogo.astro';
 import ThemeSwitcher from './ThemeSwitcher.astro';
+import TopNav from './TopNav.astro';
 
 const stats = new accelerator.statistics('components/Header.astro');
 stats.start();
@@ -26,6 +27,41 @@ const _ = Lang(lang);
 stats.stop();
 ---
 
+<script is:inline>
+  {
+    const key = 'use-new-nav';
+    const newNavRequested = new URLSearchParams(location.search).get('newnav');
+
+    let useNewNav = false;
+    try {
+      if (newNavRequested == null) {
+        const storedItem = JSON.parse(sessionStorage.getItem(key));
+        if (storedItem) {
+          // Remember the new nav setting for an hour
+          if (Date.now() - storedItem.timestamp < 60 * 60 * 1000) {
+            useNewNav = true;
+          } else {
+            sessionStorage.removeItem(key);
+          }
+        }
+      } else if (newNavRequested !== '0') {
+        useNewNav = true;
+        sessionStorage.setItem(key, JSON.stringify({ timestamp: Date.now() }));
+      } else {
+        sessionStorage.removeItem(key);
+      }
+    } catch {}
+
+    if (useNewNav) {
+      document.documentElement.dataset.nav = 'new';
+    }
+  }
+</script>
+
+<div class="new-top-nav">
+  <TopNav />
+</div>
+
 <header class="octo-header-bkg site-header header-default">
   <div class="octo-header">
     <div class="octo-header__wrapper--left">
diff --git a/src/components/TopNav.astro b/src/components/TopNav.astro
index 0b32e3f792..e8ec54044e 100644
--- a/src/components/TopNav.astro
+++ b/src/components/TopNav.astro
@@ -4,20 +4,22 @@ import Avatar from './Avatar.astro';
 import Button from './Button.astro';
 
 type Props = {
-  active?: string;
   links?: { label: string; href: string }[];
 };
 
-// TODO: Make these real links
 const {
-  active = 'Docs',
   links = [
-    { label: 'Docs', href: '#' },
-    { label: 'Learn', href: '#' },
-    { label: 'API', href: '#' },
-    { label: 'CLI', href: '#' },
+    { label: 'Docs', href: '/docs' },
+    { label: 'Learn', href: '#' }, // TODO: Make this a real link
+    { label: 'API', href: '/docs/octopus-rest-api' },
+    { label: 'CLI', href: '/docs/octopus-rest-api/cli' },
   ],
-} = Astro.props;
+} = Astro.props satisfies Props;
+
+const pathname = Astro.url.pathname.replace(/\/+$/, '') || '/';
+const currentLabel = links
+  .filter(({ href }) => pathname === href || pathname.startsWith(`${href}/`))
+  .sort((a, b) => b.href.length - a.href.length)[0]?.label;
 ---
 
 <header class="top-nav">
@@ -35,10 +37,10 @@ const {
           <a
             class:list={[
               'top-nav__link',
-              label === active && 'top-nav__link--active',
+              label === currentLabel && 'top-nav__link--active',
             ]}
             href={href}
-            aria-current={label === active ? 'page' : undefined}
+            aria-current={label === currentLabel ? 'page' : undefined}
           >
             {label}
           </a>
@@ -47,14 +49,23 @@ const {
     </nav>
   </div>
   <div class="top-nav__trailing">
-    <!-- All of these are just non-functional and for visual/presentation only at this stage -->
-    <Button icon="fa-regular fa-moon" aria-label="Switch to dark theme" />
-    <!-- TODO: Make these real links -->
+    <!-- TODO: Fix the theme switcher icons -->
+    <Button
+      icon="fa-regular fa-moon"
+      aria-label="Dark mode"
+      aria-pressed="false"
+      data-theme-toggle-button
+    />
+    <!-- TODO: Make this a real link -->
     <Button label="Changelog" href="#" />
-    <Button label="Sign in" href="#" data-signed-out-only />
+    <Button
+      label="Sign in"
+      href="https://octopus.com/signin"
+      data-signed-out-only
+    />
     <Button
       label="Start for free"
-      href="#"
+      href="https://octopus.com/free-signup"
       importance="loud"
       data-signed-out-only
     />
@@ -73,4 +84,83 @@ const {
 
 <script>
   import '../scripts/signed-in-user';
+  import '../scripts/theme-switcher';
 </script>
+
+<style>
+  .top-nav {
+    box-sizing: border-box;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--space24);
+    padding: var(--space16) var(--space24)
+      calc(var(--space16) - var(--borderWidth1));
+    border-block-end: var(--borderWidth1) solid var(--colorBorderPrimary);
+    background: var(--colorBackgroundPrimaryDefault);
+  }
+
+  .top-nav__leading,
+  .top-nav__trailing {
+    flex-shrink: 0; /* Disallow shrinking so button labels don't wrap across 2 lines */
+  }
+
+  .top-nav__leading {
+    display: flex;
+    align-items: center;
+    gap: var(--space64);
+  }
+
+  .top-nav__logo {
+    display: flex;
+  }
+
+  .top-nav__logo-mark {
+    display: block;
+    height: 2rem;
+    width: auto;
+    color: var(--colorTextPrimary);
+  }
+
+  .top-nav__links {
+    display: flex;
+    align-items: center;
+    gap: var(--space2);
+  }
+
+  .top-nav__trailing {
+    display: flex;
+    align-items: center;
+    gap: var(--space12);
+  }
+
+  a.top-nav__link {
+    box-sizing: border-box;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: var(--space8) var(--space12);
+    border-radius: var(--borderRadiusSmall);
+    background: var(--colorNavBackgroundRest);
+    color: var(--colorTextPrimary);
+    font: var(--textBodyRegularMedium);
+    text-align: center;
+    text-decoration: none;
+  }
+
+  a.top-nav__link:hover:not(.top-nav__link--active),
+  a.top-nav__link:focus:not(.top-nav__link--active) {
+    background: var(--colorNavBackgroundHover);
+  }
+
+  a.top-nav__link:focus-visible {
+    outline: var(--borderWidth2) solid var(--colorBorderSelected);
+    outline-offset: var(--borderWidth1);
+  }
+
+  a.top-nav__link--active {
+    background: var(--colorNavBackgroundActive);
+    color: var(--colorTextSelected);
+    font: var(--textBodyBoldMedium);
+  }
+</style>
diff --git a/src/pages/docs/octopus-rest-api/index.mdx b/src/pages/docs/octopus-rest-api/index.mdx
index c052db27d7..40b11ed5f2 100644
--- a/src/pages/docs/octopus-rest-api/index.mdx
+++ b/src/pages/docs/octopus-rest-api/index.mdx
@@ -26,12 +26,12 @@ We designed the Octopus REST API to:
 
 ## Octopus Command Line (CLI)
 
-The Octopus CLI is a command line tool that builds on top of the [Octopus Deploy REST API](https://octopus.com/docs/octopus-rest-api). With the Octopus CLI, you can push your application packages for deployment as either zip or NuGet packages, and manage your environments, deployments, projects, and workers.
+The Octopus CLI is a command line tool that builds on top of the [Octopus Deploy REST API](/docs/octopus-rest-api). With the Octopus CLI, you can push your application packages for deployment as either zip or NuGet packages, and manage your environments, deployments, projects, and workers.
 
 The Octopus CLI can be used on Windows, Mac, Linux, and Docker. For installation options and direct downloads, visit the [CLI Readme](https://github.com/OctopusDeploy/cli/blob/main/README.md).
 
-For more information see [Octopus Command Line (CLI)](https://octopus.com/docs/octopus-rest-api/cli).
+For more information see [Octopus Command Line (CLI)](/docs/octopus-rest-api/cli).
 
 ## Next steps
 
-Follow our [getting started with the Octopus REST API](/docs/octopus-rest-api/getting-started) guide or learn [how to create an API key](/docs/octopus-rest-api/how-to-create-an-api-key).
\ No newline at end of file
+Follow our [getting started with the Octopus REST API](/docs/octopus-rest-api/getting-started) guide or learn [how to create an API key](/docs/octopus-rest-api/how-to-create-an-api-key).
diff --git a/src/scripts/theme-switcher.ts b/src/scripts/theme-switcher.ts
index 91ffeff354..87f2fa397b 100644
--- a/src/scripts/theme-switcher.ts
+++ b/src/scripts/theme-switcher.ts
@@ -10,6 +10,12 @@ import {
 } from '../lib/theme';
 
 const CHECKBOX_SELECTOR = '[data-theme-toggle-checkbox]';
+const BUTTON_SELECTOR = '[data-theme-toggle-button]';
+const BUTTON_ICON_SELECTOR = '.btn__icon';
+const BUTTON_ICON_CLASSES: Record<Theme, string> = {
+  light: 'fa-moon',
+  dark: 'fa-sun',
+};
 
 const root = document.documentElement;
 const darkQuery = window.matchMedia(COLOR_SCHEME_QUERY);
@@ -18,6 +24,10 @@ function checkboxes() {
   return document.querySelectorAll<HTMLInputElement>(CHECKBOX_SELECTOR);
 }
 
+function buttons() {
+  return document.querySelectorAll<HTMLButtonElement>(BUTTON_SELECTOR);
+}
+
 // localStorage throws in Safari private mode and in cookie-blocked iframes.
 // A failed read or write only costs persistence, so swallow it.
 function readPreference(): ThemePreference {
@@ -54,6 +64,16 @@ function syncControls(theme: Theme) {
   checkboxes().forEach((box) => {
     box.checked = theme === 'dark';
   });
+
+  buttons().forEach((button) => {
+    button.setAttribute('aria-pressed', String(theme === 'dark'));
+
+    const icon = button.querySelector(BUTTON_ICON_SELECTOR);
+    icon?.classList.remove(
+      BUTTON_ICON_CLASSES[theme === 'dark' ? 'light' : 'dark']
+    );
+    icon?.classList.add(BUTTON_ICON_CLASSES[theme]);
+  });
 }
 
 function apply(preference: ThemePreference) {
@@ -99,6 +119,15 @@ function bind() {
       box.click();
     });
   });
+
+  buttons().forEach((button) => {
+    if (button.dataset.themeBound) return;
+    button.dataset.themeBound = 'true';
+
+    button.addEventListener('click', () =>
+      setTheme(currentTheme() === 'dark' ? 'light' : 'dark')
+    );
+  });
 }
 
 // Follow the OS only while the user has not made an explicit choice.
diff --git a/src/styles/main.css b/src/styles/main.css
index ab43dcb6d3..b1cbb8aa82 100644
--- a/src/styles/main.css
+++ b/src/styles/main.css
@@ -648,7 +648,7 @@ nav.skip-links a:focus {
 .octo-header-bkg {
   box-shadow: 0 5px 30px rgba(0, 0, 0, 0.2);
   background-color: var(--header-bg);
-  min-height: 82px;
+  min-height: var(--header-height);
   position: fixed;
   width: 100%;
   top: 0;
@@ -1229,8 +1229,8 @@ html[data-theme='light'] .theme-switcher__icon--dark svg path {
 .site-nav {
   align-self: start;
   position: sticky;
-  top: 82px;
-  height: calc(100vh - 82px);
+  top: var(--header-height);
+  height: calc(100vh - var(--header-height));
   box-sizing: border-box;
   /* No inline-end padding here — the scrolling list owns that gap, so the
      scrollbar rides against the border. No block-end padding either: the
@@ -1363,10 +1363,10 @@ html[data-theme='light'] .theme-switcher__icon--dark svg path {
   /* The last of the three column start heights below the header — 16px for the
      nav, 56px for the content, 100px here. */
   margin-block-start: 6.25rem;
-  top: calc(82px + 6.25rem);
+  top: calc(var(--header-height) + 6.25rem);
   /* Everything from the sticky top to the bottom of the window, so a long list
      scrolls inside the column instead of running off the end of it. */
-  height: calc(100vh - 82px - 6.25rem);
+  height: calc(100vh - var(--header-height) - 6.25rem);
   /* Keeps the toc off the right edge of the window. The grid column is widened
      to match, so the nav itself keeps its designed width. */
   padding-inline-end: var(--space16);
@@ -1504,7 +1504,7 @@ html[data-theme='light'] .theme-switcher__icon--dark svg path {
   grid-template-areas:
     'menu . content . toc .'
     'menu . footer  . .   .';
-  margin-top: 82px;
+  margin-top: var(--header-height);
 }
 
 /* Article header */
@@ -3119,80 +3119,24 @@ a.button.button--primary:active {
 /* Button component end */
 
 /* TopNav component */
-.top-nav {
-  box-sizing: border-box;
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: var(--space24);
-  padding: var(--space16) var(--space24)
-    calc(var(--space16) - var(--borderWidth1));
-  border-block-end: var(--borderWidth1) solid var(--colorBorderPrimary);
-  background: var(--colorBackgroundPrimaryDefault);
-}
-
-.top-nav__leading,
-.top-nav__trailing {
-  flex-shrink: 0; /* Disallow shrinking so button labels don't wrap across 2 lines */
+.new-top-nav {
+  display: none;
 }
 
-.top-nav__leading {
-  display: flex;
-  align-items: center;
-  gap: var(--space64);
+html[data-nav='new'] {
+  --header-height: 68px;
 }
 
-.top-nav__logo {
-  display: flex;
-}
-
-.top-nav__logo-mark {
+html[data-nav='new'] .new-top-nav {
   display: block;
-  height: 2rem;
-  width: auto;
-  color: var(--colorTextPrimary);
-}
-
-.top-nav__links {
-  display: flex;
-  align-items: center;
-  gap: var(--space2);
-}
-
-.top-nav__trailing {
-  display: flex;
-  align-items: center;
-  gap: var(--space12);
-}
-
-a.top-nav__link {
-  box-sizing: border-box;
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  padding: var(--space8) var(--space12);
-  border-radius: var(--borderRadiusSmall);
-  background: var(--colorNavBackgroundRest);
-  color: var(--colorTextPrimary);
-  font: var(--textBodyRegularMedium);
-  text-align: center;
-  text-decoration: none;
-}
-
-a.top-nav__link:hover:not(.top-nav__link--active),
-a.top-nav__link:focus:not(.top-nav__link--active) {
-  background: var(--colorNavBackgroundHover);
-}
-
-a.top-nav__link:focus-visible {
-  outline: var(--borderWidth2) solid var(--colorBorderSelected);
-  outline-offset: var(--borderWidth1);
+  position: fixed;
+  width: 100%;
+  top: 0;
+  z-index: 11;
 }
 
-a.top-nav__link--active {
-  background: var(--colorNavBackgroundActive);
-  color: var(--colorTextSelected);
-  font: var(--textBodyBoldMedium);
+html[data-nav='new'] .site-header {
+  display: none;
 }
 /* TopNav component end */
 
diff --git a/src/styles/vars.css b/src/styles/vars.css
index bad17d2e35..1991994fd9 100644
--- a/src/styles/vars.css
+++ b/src/styles/vars.css
@@ -208,6 +208,7 @@
   --block-gap: 2rem;
 
   --header-pin: 0;
+  --header-height: 82px;
   --scroll-pad: 140px;
 
   --box-shadow: 4px 0px 8px rgba(0, 0, 0, 0.25);
diff --git a/tests/topnav-signedin.spec.ts b/tests/topnav-signedin.spec.ts
index 42cbce6919..5612f8eb83 100644
--- a/tests/topnav-signedin.spec.ts
+++ b/tests/topnav-signedin.spec.ts
@@ -2,8 +2,8 @@ import { test, expect, type Page } from '@playwright/test';
 
 const showcase = '/components';
 
-const nav = '.top-nav';
-const trailing = '.top-nav__trailing';
+const nav = '.top-nav-showcase .top-nav';
+const trailing = `${nav} .top-nav__trailing`;
 const avatar = `${nav} [data-user-avatar]`;
 
 async function signIn(