@byline/host-tanstack-start 3.20.4 → 4.0.0

package/src/integrations/byline-viewer-client.ts

@@ -49,6 +49,7 @@ import { getServerConfig } from '@byline/core'
 
 import { getAdminRequestContext } from '../auth/auth-context.js'
 import { readPreviewCookie } from '../auth/preview-cookies.js'
+import { oncePerRequest } from '../auth/request-scope.js'
 
 let cachedClient: BylineClient | undefined
 
@@ -56,28 +57,39 @@ export function getViewerBylineClient(): BylineClient {
   if (cachedClient) return cachedClient
   cachedClient = createBylineClient({
     config: getServerConfig(),
-    requestContext: async () => {
-      // No preview cookie → behave exactly like the public client.
-      // Cheap path; no JWT verification, no DB lookup.
-      if (!readPreviewCookie()) {
-        return createRequestContext({ readMode: 'published' })
-      }
-
-      // Preview cookie present → try the admin context. A failure means
-      // the cookie is stale (admin signed out, session expired, refresh
-      // rejected). We swallow the error and fall back to the public
-      // context so the page renders instead of erroring.
-      try {
-        const ctx = await getAdminRequestContext()
-        return { ...ctx, readMode: 'any' }
-      } catch {
-        return createRequestContext({ readMode: 'published' })
-      }
-    },
+    requestContext: resolveViewerRequestContext,
   })
   return cachedClient
 }
 
+/**
+ * Preview-aware viewer context — memoized per request so every read in
+ * one request binds the same context instance (and requestId): reads
+ * sharing a ReadContext must resolve a single request authority.
+ */
+export function resolveViewerRequestContext() {
+  return oncePerRequest('byline:viewer-request-context', resolveViewerContext)
+}
+
+async function resolveViewerContext() {
+  // No preview cookie → behave exactly like the public client.
+  // Cheap path; no JWT verification, no DB lookup.
+  if (!readPreviewCookie()) {
+    return createRequestContext({ readMode: 'published' })
+  }
+
+  // Preview cookie present → try the admin context. A failure means
+  // the cookie is stale (admin signed out, session expired, refresh
+  // rejected). We swallow the error and fall back to the public
+  // context so the page renders instead of erroring.
+  try {
+    const ctx = await getAdminRequestContext()
+    return { ...ctx, readMode: 'any' as const }
+  } catch {
+    return createRequestContext({ readMode: 'published' })
+  }
+}
+
 /**
  * Resolve whether the current request should surface non-published
  * versions. True iff the preview cookie is set **and** a valid admin

package/src/integrations/request-context-contract.test.node.ts

@@ -0,0 +1,131 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Cross-layer contract test: a real `BylineClient` wired to the real
+ * cookie-derived host factory (`getAdminRequestContext`) under a mocked
+ * Start request, running two operations that share one `ReadContext`.
+ *
+ * This is the seam every per-layer suite missed when the admin tree view
+ * broke with 'ReadContext cannot be reused across request authorities':
+ * client tests used stable test contexts, host auth tests called the
+ * factory once, and tree tests mocked the handle. Here the factory's
+ * request-stability contract (see `BylineClientConfig.requestContext`)
+ * is exercised end-to-end through the SDK's authority binding.
+ */
+
+import { AdminAuth } from '@byline/auth'
+import { createBylineClient } from '@byline/client'
+import type { CollectionDefinition, IDbAdapter } from '@byline/core'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  verifyAccessToken: vi.fn(),
+  refreshSession: vi.fn(),
+  getCookie: vi.fn(),
+  setCookie: vi.fn(),
+  getRequestHeader: vi.fn(),
+  getRequest: vi.fn(),
+}))
+
+vi.mock('@byline/core', async () => {
+  const actual = await vi.importActual<typeof import('@byline/core')>('@byline/core')
+  return {
+    ...actual,
+    getServerConfig: () => ({
+      sessionProvider: {
+        verifyAccessToken: mocks.verifyAccessToken,
+        refreshSession: mocks.refreshSession,
+      },
+    }),
+  }
+})
+
+vi.mock('@tanstack/react-start/server', () => ({
+  getCookie: mocks.getCookie,
+  setCookie: mocks.setCookie,
+  getRequestHeader: mocks.getRequestHeader,
+  getRequest: mocks.getRequest,
+}))
+
+import { createReadContext } from '@byline/core'
+
+import { getAdminRequestContext } from '../auth/auth-context.js'
+
+const postsCollection: CollectionDefinition = {
+  path: 'posts',
+  labels: { singular: 'Post', plural: 'Posts' },
+  fields: [{ name: 'title', type: 'text', label: 'Title' }],
+}
+
+function mockDb(): IDbAdapter {
+  return {
+    commands: { collections: {}, documents: {}, counters: {} },
+    queries: {
+      collections: {
+        getCollectionByPath: vi.fn().mockResolvedValue({ id: 'col-1', version: 1 }),
+      },
+      documents: {
+        findDocuments: vi.fn().mockResolvedValue({ documents: [], total: 0 }),
+        getDocumentsByDocumentIds: vi.fn().mockResolvedValue([]),
+      },
+    },
+  } as unknown as IDbAdapter
+}
+
+describe('host factory ↔ client authority contract', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mocks.getCookie.mockImplementation((name: string) =>
+      name === 'byline_access_token' ? 'valid-access' : undefined
+    )
+    mocks.verifyAccessToken.mockResolvedValue({
+      actor: new AdminAuth({ id: 'admin-1', abilities: ['collections.posts.read'] }),
+    })
+  })
+
+  it('two reads sharing a ReadContext bind one authority within a request', async () => {
+    mocks.getRequest.mockReturnValue({ id: 'request-a' })
+    const db = mockDb()
+    const beforeRead = vi.fn(() => ({ title: 'scoped' }))
+    const client = createBylineClient({
+      db,
+      collections: [{ ...postsCollection, hooks: { beforeRead } }],
+      requestContext: getAdminRequestContext,
+    })
+    const readContext = createReadContext()
+
+    // The admin tree view shape: two top-level reads, one shared ReadContext.
+    await client.collection('posts').find({ status: 'any', _readContext: readContext })
+    await client.collection('posts').find({ status: 'any', _readContext: readContext })
+
+    expect(db.queries.documents.findDocuments).toHaveBeenCalledTimes(2)
+    // One session verification and one beforeRead compile for the whole
+    // request — the factory resolved a single request-stable context.
+    expect(mocks.verifyAccessToken).toHaveBeenCalledTimes(1)
+    expect(beforeRead).toHaveBeenCalledTimes(1)
+  })
+
+  it('still rejects a ReadContext carried across two different requests', async () => {
+    const db = mockDb()
+    const client = createBylineClient({
+      db,
+      collections: [{ ...postsCollection, hooks: { beforeRead: () => ({ title: 'scoped' }) } }],
+      requestContext: getAdminRequestContext,
+    })
+    const readContext = createReadContext()
+
+    mocks.getRequest.mockReturnValue({ id: 'request-a' })
+    await client.collection('posts').find({ status: 'any', _readContext: readContext })
+
+    mocks.getRequest.mockReturnValue({ id: 'request-b' })
+    await expect(
+      client.collection('posts').find({ status: 'any', _readContext: readContext })
+    ).rejects.toThrow('cannot be reused across request authorities')
+  })
+})

package/src/integrations/request-context-factories.test.node.ts

@@ -0,0 +1,140 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Direct regression coverage for the public and viewer request-context
+ * factories: both must be request-stable (same instance, same requestId,
+ * for every call within one Start request) so reads sharing a
+ * `ReadContext` bind a single request authority.
+ */
+
+import { AdminAuth } from '@byline/auth'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  verifyAccessToken: vi.fn(),
+  refreshSession: vi.fn(),
+  getCookie: vi.fn(),
+  setCookie: vi.fn(),
+  getRequestHeader: vi.fn(),
+  getRequest: vi.fn(),
+}))
+
+vi.mock('@byline/core', async () => {
+  const actual = await vi.importActual<typeof import('@byline/core')>('@byline/core')
+  return {
+    ...actual,
+    getServerConfig: () => ({
+      sessionProvider: {
+        verifyAccessToken: mocks.verifyAccessToken,
+        refreshSession: mocks.refreshSession,
+      },
+    }),
+  }
+})
+
+vi.mock('@tanstack/react-start/server', () => ({
+  getCookie: mocks.getCookie,
+  setCookie: mocks.setCookie,
+  getRequestHeader: mocks.getRequestHeader,
+  getRequest: mocks.getRequest,
+}))
+
+import { resolvePublicRequestContext } from './byline-public-client.js'
+import { resolveViewerRequestContext } from './byline-viewer-client.js'
+
+function cookiesReturn(values: Record<string, string | undefined>) {
+  mocks.getCookie.mockImplementation((name: string) => values[name])
+}
+
+describe('request-context factories', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mocks.getRequest.mockImplementation(() => {
+      throw new Error('No StartEvent found in AsyncLocalStorage')
+    })
+    cookiesReturn({})
+  })
+
+  describe('resolvePublicRequestContext', () => {
+    it('returns the same anonymous published context for every call in one request', async () => {
+      mocks.getRequest.mockReturnValue({ id: 'request-a' })
+
+      const first = await resolvePublicRequestContext()
+      const second = await resolvePublicRequestContext()
+
+      expect(second).toBe(first)
+      expect(first.actor).toBeNull()
+      expect(first.readMode).toBe('published')
+      expect(second.requestId).toBe(first.requestId)
+    })
+
+    it('resolves independently across requests', async () => {
+      mocks.getRequest.mockReturnValue({ id: 'request-a' })
+      const first = await resolvePublicRequestContext()
+      mocks.getRequest.mockReturnValue({ id: 'request-b' })
+      const second = await resolvePublicRequestContext()
+
+      expect(second).not.toBe(first)
+      expect(second.requestId).not.toBe(first.requestId)
+    })
+  })
+
+  describe('resolveViewerRequestContext', () => {
+    it('returns the same anonymous context per request when no preview cookie is set', async () => {
+      mocks.getRequest.mockReturnValue({ id: 'request-a' })
+
+      const first = await resolveViewerRequestContext()
+      const second = await resolveViewerRequestContext()
+
+      expect(second).toBe(first)
+      expect(first.actor).toBeNull()
+      expect(first.readMode).toBe('published')
+    })
+
+    it('returns the same admin any-mode context per request in preview mode', async () => {
+      mocks.getRequest.mockReturnValue({ id: 'request-a' })
+      cookiesReturn({ byline_preview: '1', byline_access_token: 'valid-access' })
+      const actor = new AdminAuth({ id: 'admin-1', abilities: [] })
+      mocks.verifyAccessToken.mockResolvedValue({ actor })
+
+      const first = await resolveViewerRequestContext()
+      const second = await resolveViewerRequestContext()
+
+      expect(second).toBe(first)
+      expect(first.actor).toBe(actor)
+      expect(first.readMode).toBe('any')
+      // The viewer context and the nested admin resolution are both
+      // memoized — one session verification per request, not per call.
+      expect(mocks.verifyAccessToken).toHaveBeenCalledTimes(1)
+    })
+
+    it('falls back to one stable anonymous context when the preview session is stale', async () => {
+      mocks.getRequest.mockReturnValue({ id: 'request-a' })
+      cookiesReturn({ byline_preview: '1', byline_access_token: 'stale' })
+      mocks.verifyAccessToken.mockRejectedValue(new Error('expired'))
+
+      const first = await resolveViewerRequestContext()
+      const second = await resolveViewerRequestContext()
+
+      expect(second).toBe(first)
+      expect(first.actor).toBeNull()
+      expect(first.readMode).toBe('published')
+    })
+
+    it('resolves independently across requests', async () => {
+      mocks.getRequest.mockReturnValue({ id: 'request-a' })
+      const first = await resolveViewerRequestContext()
+      mocks.getRequest.mockReturnValue({ id: 'request-b' })
+      const second = await resolveViewerRequestContext()
+
+      expect(second).not.toBe(first)
+      expect(second.requestId).not.toBe(first.requestId)
+    })
+  })
+})

package/src/integrations/start-errors.test.node.ts

@@ -0,0 +1,22 @@
+import { ERR_CONFLICT, ERR_TREE_HOOK_COMMITTED } from '@byline/core'
+import { describe, expect, it } from 'vitest'
+
+import { bylineCodedErrorAdapter } from './start-errors.js'
+
+describe('Byline coded error serialization', () => {
+  it.each([
+    ERR_CONFLICT({ message: 'stale tree' }),
+    ERR_TREE_HOOK_COMMITTED({ message: 'tree committed; hook failed' }),
+  ])('preserves core BylineError code $code', (error) => {
+    expect(bylineCodedErrorAdapter.test(error)).toBe(true)
+
+    const payload = bylineCodedErrorAdapter.toSerializable(error)
+    const restored = bylineCodedErrorAdapter.fromSerializable(payload)
+
+    expect(restored).toMatchObject({
+      name: 'BylineError',
+      code: error.code,
+      message: error.message,
+    })
+  })
+})

package/src/integrations/start-errors.ts

@@ -44,6 +44,7 @@ const CODED_ERROR_NAMES = new Set([
   'AdminRolesError',
   'AdminUsersError',
   'AuthError',
+  'BylineError',
 ])
 
 export interface BylineCodedErrorPayload {

package/src/routes/admin-path.test.node.ts

@@ -0,0 +1,129 @@
+import { defineClientConfig } from '@byline/core'
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import {
+  getAdminRouteId,
+  getAdminRoutePath,
+  isAdminRoutePathActive,
+  isRoutePathWithin,
+  resolveAdminCallbackPath,
+  resolveAdminSignInRedirect,
+} from './admin-path.js'
+
+function registerRoutes(admin?: string): void {
+  defineClientConfig({
+    serverURL: 'http://localhost:3000',
+    routes: admin ? { admin } : undefined,
+    collections: [],
+    admin: [],
+    i18n: {
+      interface: { defaultLocale: 'en', locales: [] },
+      content: { defaultLocale: 'en', locales: [] },
+    },
+  })
+}
+
+describe('getAdminRoutePath', () => {
+  beforeEach(() => registerRoutes('/cms/'))
+
+  it.each([
+    [[], '/cms'],
+    [['collections'], '/cms/collections'],
+    [['collections', '$collection'], '/cms/collections/$collection'],
+    [['collections', '$collection', 'create'], '/cms/collections/$collection/create'],
+    [['collections', '$collection', '$id'], '/cms/collections/$collection/$id'],
+    [['collections', '$collection', '$id', 'history'], '/cms/collections/$collection/$id/history'],
+    [['collections', '$collection', '$id', 'api'], '/cms/collections/$collection/$id/api'],
+    [['users'], '/cms/users'],
+    [['users', '$id'], '/cms/users/$id'],
+    [['roles'], '/cms/roles'],
+    [['roles', '$id'], '/cms/roles/$id'],
+    [['permissions'], '/cms/permissions'],
+    [['activity'], '/cms/activity'],
+    [['account'], '/cms/account'],
+  ])('joins %j against the configured admin mount', (segments, expected) => {
+    expect(getAdminRoutePath(...segments)).toBe(expected)
+  })
+
+  it('safely joins slash-delimited segments', () => {
+    expect(getAdminRoutePath('/collections/', '/pages/')).toBe('/cms/collections/pages')
+    registerRoutes('cms')
+    expect(getAdminRoutePath('users')).toBe('/cms/users')
+  })
+
+  it('preserves a configured multi-segment admin mount', () => {
+    registerRoutes('/internal/cms/')
+    expect(getAdminRoutePath('users')).toBe('/internal/cms/users')
+  })
+
+  it('accepts callbacks inside a configured multi-segment admin mount', () => {
+    registerRoutes('/internal/cms/')
+    expect(resolveAdminCallbackPath('/internal/cms/users?status=active#results')).toBe(
+      '/internal/cms/users?status=active#results'
+    )
+    expect(resolveAdminCallbackPath('/internal/cms-old/users')).toBeUndefined()
+  })
+
+  it('matches dashboard, collection, and trailing-slash paths', () => {
+    expect(isAdminRoutePathActive('/cms')).toBe(true)
+    expect(isAdminRoutePathActive('/cms/')).toBe(true)
+    expect(isAdminRoutePathActive('/cms/collections/pages', 'collections')).toBe(true)
+    expect(isAdminRoutePathActive('/cms/users', 'collections')).toBe(false)
+    expect(isAdminRoutePathActive('/cms/collections-old', 'collections')).toBe(false)
+    expect(isRoutePathWithin('/cms/users/123', '/cms/users')).toBe(true)
+    expect(isRoutePathWithin('/cms/users-archive', '/cms/users')).toBe(false)
+  })
+
+  it.each([
+    ['/cms', '/cms'],
+    ['/cms/', '/cms/'],
+    [
+      '/cms/collections/pages?query=hello%20world#results',
+      '/cms/collections/pages?query=hello%20world#results',
+    ],
+  ])('accepts a safe admin callback %j', (callback, expected) => {
+    expect(resolveAdminCallbackPath(callback)).toBe(expected)
+  })
+
+  it.each([
+    undefined,
+    '',
+    ' /cms',
+    'https://evil.test/cms',
+    '//evil.test/cms',
+    '/\\evil.test/cms',
+    '/admin',
+    '/cms-old',
+    '/cms\\users',
+    '%2Fcms',
+    '/%2F%2Fevil.test',
+    '/cms/%2e%2e/account',
+    '/cms/%2e/account',
+    '/cms/%252e%252e/account',
+    '/cms/%5c%5cevil.test',
+    '/cms/../account',
+    '/cms/./account',
+    '/cms\u0085account',
+  ])('rejects an unsafe or non-admin callback %j', (callback) => {
+    expect(resolveAdminCallbackPath(callback)).toBeUndefined()
+  })
+
+  it('sends direct and rejected-callback sign-ins to the configured dashboard', () => {
+    expect(resolveAdminSignInRedirect(undefined)).toBe('/cms')
+    expect(resolveAdminSignInRedirect('https://evil.test')).toBe('/cms')
+    expect(resolveAdminSignInRedirect('/cms/account')).toBe('/cms/account')
+  })
+
+  it('builds route IDs matching the custom filesystem mount', () => {
+    expect(getAdminRouteId()).toBe('/_byline/cms')
+    expect(getAdminRouteId('collections', '$collection', '$id', 'history')).toBe(
+      '/_byline/cms/collections/$collection/$id/history'
+    )
+  })
+
+  it('keeps the default admin mount backward compatible', () => {
+    registerRoutes()
+    expect(getAdminRoutePath()).toBe('/admin')
+    expect(getAdminRoutePath('collections', '$collection')).toBe('/admin/collections/$collection')
+  })
+})

package/src/routes/admin-path.ts

@@ -0,0 +1,66 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { getClientConfig, normalizeRootRelativeRedirect } from '@byline/core'
+
+/** Build an admin URL or parameterized TanStack route from client-safe config. */
+export function getAdminRoutePath(...segments: ReadonlyArray<string | number>): string {
+  const configuredBase = getClientConfig().routes.admin
+  const normalizedBase = configuredBase.replace(/^\/+|\/+$/g, '')
+  const base = normalizedBase ? `/${normalizedBase}` : '/'
+  const suffix = segments
+    .map((segment) => String(segment).replace(/^\/+|\/+$/g, ''))
+    .filter(Boolean)
+    .join('/')
+
+  if (!suffix) return base
+  return base === '/' ? `/${suffix}` : `${base}/${suffix}`
+}
+
+/** Build the matching pathless-group route ID used by generated host route trees. */
+export function getAdminRouteId(...segments: ReadonlyArray<string | number>): string {
+  return `/_byline${getAdminRoutePath(...segments)}`
+}
+
+/** True when a pathname is the target route or one of its segment-delimited descendants. */
+export function isRoutePathWithin(pathname: string, target: string): boolean {
+  const current = pathname.length > 1 ? pathname.replace(/\/+$/, '') : pathname
+  const base = target.length > 1 ? target.replace(/\/+$/, '') : target
+  return (
+    current === base || (base === '/' ? current.startsWith('/') : current.startsWith(`${base}/`))
+  )
+}
+
+/**
+ * Accept an untrusted callback only when it is an unencoded, same-origin path
+ * inside the configured admin mount.
+ */
+export function resolveAdminCallbackPath(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const normalized = normalizeRootRelativeRedirect(value)
+  if (!normalized) return undefined
+  const url = new URL(normalized, 'https://byline.invalid')
+  if (!isRoutePathWithin(url.pathname, getAdminRoutePath())) return undefined
+  return `${url.pathname}${url.search}${url.hash}`
+}
+
+/** Resolve an untrusted callback or fall back to the configured admin dashboard. */
+export function resolveAdminSignInRedirect(value: unknown): string {
+  return resolveAdminCallbackPath(value) ?? getAdminRoutePath()
+}
+
+/** Match the admin root exactly and admin child entries by pathname prefix. */
+export function isAdminRoutePathActive(
+  pathname: string,
+  ...segments: ReadonlyArray<string>
+): boolean {
+  const target = getAdminRoutePath(...segments)
+  const current = pathname.length > 1 ? pathname.replace(/\/+$/, '') : pathname
+  if (segments.length === 0) return current === target
+  return isRoutePathWithin(current, target)
+}

package/src/routes/auth-routes.test.node.ts

@@ -0,0 +1,39 @@
+import { defineClientConfig } from '@byline/core'
+import { beforeEach, describe, expect, it } from 'vitest'
+
+import { resolveAdminCallbackPath, resolveAdminSignInRedirect } from './admin-path.js'
+import { configureSignInRoutePath, getSignInRoutePath } from './sign-in-path.js'
+
+describe('admin authentication routes', () => {
+  beforeEach(() => {
+    defineClientConfig({
+      serverURL: 'http://localhost:3000',
+      routes: { admin: '/cms/', signIn: '/staff/login/' },
+      collections: [],
+      admin: [],
+      i18n: {
+        interface: { defaultLocale: 'en', locales: [] },
+        content: { defaultLocale: 'en', locales: [] },
+      },
+    })
+  })
+
+  it('sanitizes sign-in route search before it reaches the form', () => {
+    expect(resolveAdminCallbackPath('/cms/account')).toBe('/cms/account')
+    expect(resolveAdminCallbackPath('https://evil.test')).toBeUndefined()
+  })
+
+  it('uses the custom mount for direct sign-in and callback navigation', () => {
+    expect(resolveAdminSignInRedirect(undefined)).toBe('/cms')
+    expect(resolveAdminSignInRedirect('/cms/collections/pages/1')).toBe('/cms/collections/pages/1')
+  })
+
+  it('shares routes.signIn between guard and sign-out consumers', () => {
+    expect(getSignInRoutePath()).toBe('/staff/login')
+    expect(configureSignInRoutePath('/staff/login/')).toBe('/staff/login')
+  })
+
+  it('does not allow the deprecated layout override to silently diverge', () => {
+    expect(() => configureSignInRoutePath('/auth/login')).toThrow(/must match routes\.signIn/)
+  })
+})

package/src/routes/create-admin-account-route.tsx

@@ -14,6 +14,7 @@ import { Container, Section } from '@byline/ui/react'
 
 import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
 import { type AccountResponse, getAccount } from '../server-fns/admin-account/index.js'
+import { getAdminRoutePath } from './admin-path.js'
 
 function displayNameFor(account: {
   given_name: string | null
@@ -43,8 +44,8 @@ export function createAdminAccountRoute(path: string) {
         <>
           <BreadcrumbsClient
             breadcrumbs={[
-              { label: t('chrome.menu.dashboard'), href: '/admin' },
-              { label: t('chrome.account'), href: '/admin/account' },
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
+              { label: t('chrome.account'), href: getAdminRoutePath('account') },
             ]}
           />
           <Section className="pb-2">

package/src/routes/create-admin-activity-route.tsx

@@ -14,6 +14,7 @@ import { z } from 'zod'
 import { ActivitySystemView } from '../admin-shell/admin-activity/list.js'
 import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
 import { getSystemActivityLog } from '../server-fns/admin-activity/index.js'
+import { getAdminRoutePath } from './admin-path.js'
 import type { SystemActivityResponse } from '../server-fns/admin-activity/index.js'
 
 const searchSchema = z.object({
@@ -62,8 +63,8 @@ export function createAdminActivityRoute(path: string) {
         <>
           <BreadcrumbsClient
             breadcrumbs={[
-              { label: t('chrome.menu.dashboard'), href: '/admin' },
-              { label: t('activity.title'), href: '/admin/activity' },
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
+              { label: t('activity.title'), href: getAdminRoutePath('activity') },
             ]}
           />
           <ActivitySystemView data={data} />

package/src/routes/create-admin-dashboard-route.tsx

@@ -14,6 +14,7 @@ import { useTranslation } from '@byline/i18n/react'
 import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
 import { AdminDashboard } from '../admin-shell/chrome/dashboard.js'
 import { type CollectionStatusCount, getCollectionStats } from '../server-fns/collections/index.js'
+import { getAdminRoutePath } from './admin-path.js'
 
 export function createAdminDashboardRoute(path: string) {
   // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
@@ -44,7 +45,7 @@ export function createAdminDashboardRoute(path: string) {
       return (
         <>
           <BreadcrumbsClient
-            breadcrumbs={[{ label: t('chrome.menu.dashboard'), href: '/admin' }]}
+            breadcrumbs={[{ label: t('chrome.menu.dashboard'), href: getAdminRoutePath() }]}
           />
           <AdminDashboard statsMap={statsMap} />
         </>