@byline/host-tanstack-start 3.21.0 → 4.0.0

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} />
         </>

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

@@ -43,18 +43,18 @@ import { BylineAiAdminProvider } from '../integrations/byline-ai.js'
 import { bylineFieldServices } from '../integrations/byline-field-services.js'
 import { getCurrentAdminUser } from '../server-fns/auth/index.js'
 import { getActiveLocaleFn, setInterfaceLocaleFn } from '../server-fns/i18n/index.js'
+import { createSignInRoutePathResolver } from './sign-in-path.js'
 
 interface AdminLayoutOpts {
-  /** Path users are redirected to when unauthenticated. Defaults to `/sign-in`. */
+  /** @deprecated Configure `routes.signIn`; an override must resolve to the same path. */
   signInPath?: string
 }
 
 export function createAdminLayoutRoute(path: string, opts: AdminLayoutOpts = {}) {
-  const signInPath = opts.signInPath ?? '/sign-in'
-
-  // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
+  const resolveSignInPath = createSignInRoutePathResolver(opts.signInPath)
   const Route: any = createFileRoute(path as never)({
     beforeLoad: async ({ location }: { location: { href: string } }) => {
+      const signInPath = resolveSignInPath()
       try {
         const user = await getCurrentAdminUser()
         // Resolve the active interface locale once on the server so SSR

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

@@ -16,6 +16,7 @@ import {
   type ListRegisteredAbilitiesResponse,
   listRegisteredAbilities,
 } from '../server-fns/admin-permissions/index.js'
+import { getAdminRoutePath } from './admin-path.js'
 
 export function createAdminPermissionsRoute(path: string) {
   // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
@@ -31,8 +32,8 @@ export function createAdminPermissionsRoute(path: string) {
         <>
           <BreadcrumbsClient
             breadcrumbs={[
-              { label: t('chrome.menu.dashboard'), href: '/admin' },
-              { label: t('chrome.menu.permissions'), href: '/admin/permissions' },
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
+              { label: t('chrome.menu.permissions'), href: getAdminRoutePath('permissions') },
             ]}
           />
           <AbilitiesInspector data={data} />

package/src/routes/create-admin-role-edit-route.tsx

@@ -19,6 +19,7 @@ import {
   listRegisteredAbilities,
 } from '../server-fns/admin-permissions/index.js'
 import { type AdminRoleResponse, getAdminRole } from '../server-fns/admin-roles/index.js'
+import { getAdminRoutePath } from './admin-path.js'
 
 interface LoaderData {
   role: AdminRoleResponse
@@ -62,9 +63,12 @@ export function createAdminRoleEditRoute(path: string) {
         <>
           <BreadcrumbsClient
             breadcrumbs={[
-              { label: t('chrome.menu.dashboard'), href: '/admin' },
-              { label: t('chrome.menu.adminRoles'), href: '/admin/roles' },
-              { label: t('adminRoles.breadcrumbDetail'), href: `/admin/roles/${role.id}` },
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
+              { label: t('chrome.menu.adminRoles'), href: getAdminRoutePath('roles') },
+              {
+                label: t('adminRoles.breadcrumbDetail'),
+                href: getAdminRoutePath('roles', role.id),
+              },
             ]}
           />
           <Section className="py-5 pb-2">

package/src/routes/create-admin-roles-list-route.tsx

@@ -13,6 +13,7 @@ import { useTranslation } from '@byline/i18n/react'
 import { AdminRolesListView } from '../admin-shell/admin-roles/list.js'
 import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
 import { type AdminRoleListResponse, listAdminRoles } from '../server-fns/admin-roles/index.js'
+import { getAdminRoutePath } from './admin-path.js'
 
 export function createAdminRolesListRoute(path: string) {
   // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
@@ -28,8 +29,8 @@ export function createAdminRolesListRoute(path: string) {
         <>
           <BreadcrumbsClient
             breadcrumbs={[
-              { label: t('chrome.menu.dashboard'), href: '/admin' },
-              { label: t('chrome.menu.adminRoles'), href: '/admin/roles' },
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
+              { label: t('chrome.menu.adminRoles'), href: getAdminRoutePath('roles') },
             ]}
           />
           <AdminRolesListView data={data} />

package/src/routes/create-admin-user-edit-route.tsx

@@ -19,6 +19,7 @@ import {
   getAdminUser,
   getUserRoles,
 } from '../server-fns/admin-users/index.js'
+import { getAdminRoutePath } from './admin-path.js'
 
 interface LoaderData {
   user: AdminUserResponse
@@ -79,9 +80,12 @@ export function createAdminUserEditRoute(path: string) {
         <>
           <BreadcrumbsClient
             breadcrumbs={[
-              { label: t('chrome.menu.dashboard'), href: '/admin' },
-              { label: t('chrome.menu.adminUsers'), href: '/admin/users' },
-              { label: t('adminUsers.breadcrumbDetail'), href: `/admin/users/${user.id}` },
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
+              { label: t('chrome.menu.adminUsers'), href: getAdminRoutePath('users') },
+              {
+                label: t('adminUsers.breadcrumbDetail'),
+                href: getAdminRoutePath('users', user.id),
+              },
             ]}
           />
           <Section className="py-5 pb-2">

package/src/routes/create-admin-users-list-route.tsx

@@ -14,6 +14,7 @@ import { z } from 'zod'
 import { AdminUsersListView } from '../admin-shell/admin-users/list.js'
 import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
 import { type AdminUserListResponse, listAdminUsers } from '../server-fns/admin-users/index.js'
+import { getAdminRoutePath } from './admin-path.js'
 
 const orderSchema = z.enum([
   'given_name',
@@ -72,8 +73,8 @@ export function createAdminUsersListRoute(path: string) {
         <>
           <BreadcrumbsClient
             breadcrumbs={[
-              { label: t('chrome.menu.dashboard'), href: '/admin' },
-              { label: t('chrome.menu.adminUsers'), href: '/admin/users' },
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
+              { label: t('chrome.menu.adminUsers'), href: getAdminRoutePath('users') },
             ]}
           />
           <AdminUsersListView data={data} />

package/src/routes/create-collection-api-route.tsx

@@ -16,6 +16,7 @@ import { z } from 'zod'
 import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
 import { ApiView } from '../admin-shell/collections/api.js'
 import { getCollectionDocument } from '../server-fns/collections/index.js'
+import { getAdminRoutePath } from './admin-path.js'
 import { getContentLocaleRouteConfig } from './get-content-locale-route-config.js'
 
 const searchSchema = z.object({
@@ -81,15 +82,18 @@ export function createCollectionApiRoute(path: string) {
         <>
           <BreadcrumbsClient
             breadcrumbs={[
-              { label: t('chrome.menu.dashboard'), href: `/admin` },
-              { label: collectionDef.labels.plural, href: `/admin/collections/${collection}` },
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
+              {
+                label: collectionDef.labels.plural,
+                href: getAdminRoutePath('collections', collection),
+              },
               {
                 label: t('common.actions.edit'),
-                href: `/admin/collections/${collection}/${id}`,
+                href: getAdminRoutePath('collections', collection, id),
               },
               {
                 label: t('collections.viewMenu.apiButton'),
-                href: `/admin/collections/${collection}/${id}/api`,
+                href: getAdminRoutePath('collections', collection, id, 'api'),
               },
             ]}
           />

package/src/routes/create-collection-create-route.tsx

@@ -18,6 +18,7 @@ import { useTranslation } from '@byline/i18n/react'
 
 import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs-client.js'
 import { CreateView } from '../admin-shell/collections/create.js'
+import { getAdminRoutePath } from './admin-path.js'
 
 export function createCollectionCreateRoute(path: string) {
   // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
@@ -49,11 +50,14 @@ export function createCollectionCreateRoute(path: string) {
         <>
           <BreadcrumbsClient
             breadcrumbs={[
-              { label: t('chrome.menu.dashboard'), href: '/admin' },
-              { label: collectionDef.labels.plural, href: `/admin/collections/${collection}` },
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
+              {
+                label: collectionDef.labels.plural,
+                href: getAdminRoutePath('collections', collection),
+              },
               {
                 label: t('collections.breadcrumbs.create'),
-                href: `/admin/collections/${collection}/create`,
+                href: getAdminRoutePath('collections', collection, 'create'),
               },
             ]}
           />