@byline/host-tanstack-start 3.21.0 → 4.1.0

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'),
               },
             ]}
           />

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

@@ -19,6 +19,7 @@ import { BreadcrumbsClient } from '../admin-shell/chrome/breadcrumbs/breadcrumbs
 import { useNavigate } from '../admin-shell/chrome/loose-router.js'
 import { EditView } from '../admin-shell/collections/edit.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({
@@ -116,11 +117,14 @@ export function createCollectionEditRoute(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),
               },
             ]}
           />

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

@@ -24,6 +24,7 @@ import {
   getCollectionDocumentAuditLog,
   getCollectionDocumentHistory,
 } 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({
@@ -119,15 +120,18 @@ export function createCollectionHistoryRoute(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}/${Route.useParams().id}`,
+                href: getAdminRoutePath('collections', collection, Route.useParams().id),
               },
               {
                 label: t('collections.breadcrumbs.history'),
-                href: `/admin/collections/${collection}/${Route.useParams().id}/history`,
+                href: getAdminRoutePath('collections', collection, Route.useParams().id, 'history'),
               },
             ]}
           />

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

@@ -30,6 +30,7 @@ import {
   placeTreeNode,
   reorderCollectionDocument,
 } from '../server-fns/collections/index.js'
+import { getAdminRoutePath } from './admin-path.js'
 import type { CollectionTreeRow } from '../server-fns/collections/tree.js'
 
 const searchSchema = z.object({
@@ -167,10 +168,10 @@ export function createCollectionListRoute(path: string) {
         <>
           <BreadcrumbsClient
             breadcrumbs={[
-              { label: t('chrome.menu.dashboard'), href: `/admin` },
+              { label: t('chrome.menu.dashboard'), href: getAdminRoutePath() },
               {
                 label: data.included.collection.labels.plural,
-                href: `/admin/collections/${collection}`,
+                href: getAdminRoutePath('collections', collection),
               },
             ]}
           />

package/src/routes/create-sign-in-route.tsx

@@ -9,7 +9,7 @@
 /**
  * Sign-in page route factory.
  *
- * Lives outside the `/admin` subtree so the authenticated-admin layout
+ * Lives outside the configured admin subtree so the authenticated-admin layout
  * (and its `beforeLoad` guard) does not apply. Preserves a `callbackUrl`
  * query param so sign-ins triggered by the admin guard redirect back to
  * the originally-requested path.
@@ -21,6 +21,7 @@ import type { LocaleCode } from '@byline/i18n'
 
 import { SignInPage } from '../admin-shell/chrome/sign-in-page.js'
 import { getActiveLocaleFn } from '../server-fns/i18n/index.js'
+import { resolveAdminCallbackPath, resolveAdminSignInRedirect } from './admin-path.js'
 
 interface SignInSearch {
   callbackUrl?: string
@@ -30,7 +31,7 @@ export function createSignInRoute(path: string) {
   // biome-ignore lint/suspicious/noExplicitAny: dynamic path bypasses route-tree typing
   const Route: any = createFileRoute(path as never)({
     validateSearch: (search: Record<string, unknown>): SignInSearch => {
-      const callbackUrl = typeof search.callbackUrl === 'string' ? search.callbackUrl : undefined
+      const callbackUrl = resolveAdminCallbackPath(search.callbackUrl)
       return { callbackUrl }
     },
     beforeLoad: async () => {
@@ -45,7 +46,12 @@ export function createSignInRoute(path: string) {
     component: function SignInRouteComponent() {
       const { callbackUrl } = Route.useSearch() as SignInSearch
       const { activeLocale } = Route.useRouteContext() as { activeLocale: LocaleCode }
-      return <SignInPage callbackUrl={callbackUrl} activeLocale={activeLocale} />
+      return (
+        <SignInPage
+          redirectTo={resolveAdminSignInRedirect(callbackUrl)}
+          activeLocale={activeLocale}
+        />
+      )
     },
   })
   return Route

package/src/routes/index.ts

@@ -6,6 +6,16 @@
  * Copyright (c) Infonomic Company Limited
  */
 
+export {
+  getAdminRouteId,
+  getAdminRoutePath,
+  isAdminRoutePathActive,
+  isRoutePathWithin,
+  resolveAdminCallbackPath,
+  resolveAdminSignInRedirect,
+} from './admin-path.js'
+export { configureSignInRoutePath, getSignInRoutePath } from './sign-in-path.js'
+
 /**
  * Route factories for the Byline admin UI on TanStack Start.
  *
@@ -14,6 +24,7 @@
  * `createFileRoute(path)({...})`. The host's route file collapses to:
  *
  *   import { createCollectionListRoute } from '@byline/host-tanstack-start/routes'
+ *   // Default admin mount example:
  *   export const Route = createCollectionListRoute('/_byline/admin/collections/$collection/')
  *
  * Routes that need host-specific data (i18n bridge component, content