@byline/host-tanstack-start 5.1.2 → 5.1.4

package/package.json

@@ -3,7 +3,7 @@
   "private": false,
   "type": "module",
   "license": "MPL-2.0",
-  "version": "5.1.2",
+  "version": "5.1.4",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -125,15 +125,15 @@
     "react-json-view-lite": "^2.5.0",
     "react-swipeable": "^7.0.2",
     "zod": "^4.5.4",
-    "@byline/admin": "5.1.2",
-    "@byline/analytics": "5.1.2",
-    "@byline/analytics-agent": "5.1.2",
-    "@byline/auth": "5.1.2",
-    "@byline/client": "5.1.2",
-    "@byline/ai": "5.1.2",
-    "@byline/i18n": "5.1.2",
-    "@byline/core": "5.1.2",
-    "@byline/ui": "5.1.2"
+    "@byline/analytics": "5.1.4",
+    "@byline/admin": "5.1.4",
+    "@byline/auth": "5.1.4",
+    "@byline/ai": "5.1.4",
+    "@byline/client": "5.1.4",
+    "@byline/core": "5.1.4",
+    "@byline/i18n": "5.1.4",
+    "@byline/analytics-agent": "5.1.4",
+    "@byline/ui": "5.1.4"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.167.0",

package/src/admin-shell/chrome/sign-in-page.module.css

@@ -5,6 +5,10 @@
  *   .byline-sign-in-page       — outer <main>
  *   .byline-sign-in-page-bar   — top bar carrying the LanguageMenu
  *   .byline-sign-in-page-inner — vertically-centred card container
+ *   .byline-sign-in-page-checking — activity indicator during session bootstrap
+ *   .byline-sign-in-page-card     — card frame for the bootstrap-error state (matches the form card)
+ *   .byline-sign-in-page-alert    — noscript / bootstrap-error alert spacing
+ *   .byline-sign-in-page-actions  — action row for the bootstrap-error state
  *
  * The Home link itself lives inside `SignInForm`'s action row — see
  * `@byline/ui` `sign-in-form.module.css` for `.byline-sign-in-home-link`.
@@ -42,3 +46,58 @@
     margin-top: 14vh;
   }
 }
+
+.checking,
+:global(.byline-sign-in-page-checking) {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 2rem 0;
+  color: inherit;
+  opacity: 0.6;
+}
+
+.srOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+.card,
+:global(.byline-sign-in-page-card) {
+  width: 100%;
+}
+
+@media (min-width: 40rem) {
+  .card,
+  :global(.byline-sign-in-page-card) {
+    max-width: 380px;
+  }
+}
+
+.alert,
+:global(.byline-sign-in-page-alert) {
+  width: 100%;
+  margin-top: var(--spacing-12);
+}
+
+@media (min-width: 40rem) {
+  :global(noscript) > .alert,
+  :global(noscript) > :global(.byline-sign-in-page-alert) {
+    max-width: 380px;
+  }
+}
+
+.actions,
+:global(.byline-sign-in-page-actions) {
+  display: flex;
+  justify-content: flex-end;
+  padding-top: var(--spacing-8);
+  margin-bottom: var(--spacing-8);
+}

package/src/admin-shell/chrome/sign-in-page.test.tsx

@@ -0,0 +1,99 @@
+/**
+ * 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 { act } from 'react'
+
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({ renew: vi.fn() }))
+vi.mock('../../server-fns/auth/renew.js', () => ({ renewAdminSession: mocks.renew }))
+vi.mock('../../server-fns/i18n/index.js', () => ({ setAdminLocaleFn: vi.fn() }))
+vi.mock('../../integrations/byline-admin-services.js', () => ({ bylineAdminServices: {} }))
+vi.mock('@byline/core', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@byline/core')>()
+  const { adminTranslations } = await import('@byline/i18n/admin')
+  return {
+    ...actual,
+    getAdminConfig: () => ({
+      routes: { admin: '/admin' },
+      i18n: {
+        admin: { locales: ['en'], defaultLocale: 'en' },
+        translations: adminTranslations({ locales: ['en'] }),
+      },
+    }),
+  }
+})
+
+import { SignInPage } from './sign-in-page.js'
+
+let root: Root
+let container: HTMLDivElement
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+  vi.stubGlobal('BroadcastChannel', undefined)
+  window.sessionStorage.clear()
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+})
+afterEach(() => {
+  act(() => root.unmount())
+  container.remove()
+  vi.unstubAllGlobals()
+})
+
+async function render() {
+  await act(async () => {
+    root.render(<SignInPage redirectTo="/admin" activeLocale="en" reauthenticate={false} />)
+  })
+  // The bootstrap promise settles through `.catch`/`.finally` after the first
+  // commit; yield one macrotask inside `act` so that state update is flushed.
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0))
+  })
+}
+
+describe('SignInPage bootstrap states', () => {
+  it('renders the bootstrap error in the kit card with a kit button', async () => {
+    mocks.renew.mockRejectedValue(new Error('network'))
+    await render()
+    const alert = container.querySelector('[role="alert"]')
+    expect(alert).not.toBeNull()
+    expect(alert?.classList.contains('byline-card')).toBe(true)
+    expect(alert?.querySelector('.byline-alert-danger')?.textContent).toContain(
+      'Unable to check your session. Please try again.'
+    )
+    // The alert itself carries no dismiss button; the only button is the retry action.
+    expect(alert?.querySelectorAll('button').length).toBe(1)
+    const button = alert?.querySelector('.byline-sign-in-page-actions button')
+    expect(button?.classList.contains('byline-button')).toBe(true)
+    expect(button?.textContent).toBe('Try again')
+  })
+
+  it('falls through to the sign-in form on an ordinary auth outcome', async () => {
+    mocks.renew.mockRejectedValue(Object.assign(new Error('none'), { code: 'ERR_UNAUTHENTICATED' }))
+    await render()
+    expect(container.querySelector('[role="alert"]')).toBeNull()
+    expect(container.querySelector('form.byline-sign-in-form')).not.toBeNull()
+  })
+
+  // Runs last: `renewSingleFlight` keeps the in-flight promise at module level,
+  // and a never-settling renewal would block every later case in this file.
+  it('shows a wordless activity indicator while the bootstrap renewal is pending', async () => {
+    mocks.renew.mockReturnValue(new Promise(() => {}))
+    await render()
+    const status = container.querySelector('[role="status"]')
+    expect(status).not.toBeNull()
+    expect(status?.querySelector('.byline-loader-ring')).not.toBeNull()
+    // The only text is the visually hidden label; nothing advertises a session check.
+    expect(status?.textContent).toBe('Loading…')
+    expect(container.textContent).not.toContain('session')
+  })
+})

package/src/admin-shell/chrome/sign-in-page.tsx

@@ -12,19 +12,14 @@ import { SignInForm } from '@byline/admin/auth/components/sign-in-form'
 import { BylineAdminServicesProvider } from '@byline/admin/services'
 import { getAdminConfig } from '@byline/core'
 import type { LocaleCode } from '@byline/i18n'
-import { I18nProvider, LanguageMenu } from '@byline/i18n/react'
+import { I18nProvider, LanguageMenu, useTranslation } from '@byline/i18n/react'
+import { Alert, Button, Card, LoaderRing } from '@byline/ui/react'
 import cx from 'clsx'
 
 import { buildLocaleDefinitions } from '../../i18n/locale-definitions.js'
 import { bylineAdminServices } from '../../integrations/byline-admin-services.js'
-import {
-  coordinateAuthAction,
-  expectedSession,
-  flagSessionChanged,
-  observeSession,
-  renewSingleFlight,
-} from '../../integrations/session-coordination.js'
-import { renewAdminSession } from '../../server-fns/auth/renew.js'
+import { flagSessionChanged } from '../../integrations/session-coordination.js'
+import { renewExpectedSession } from '../../integrations/session-renewal.js'
 import { setAdminLocaleFn } from '../../server-fns/i18n/index.js'
 import { SessionChangeBoundary } from './session-change-boundary.js'
 import styles from './sign-in-page.module.css'
@@ -67,14 +62,7 @@ export function SignInPage({
   useEffect(() => {
     if (reauthenticate) return
     let active = true
-    void renewSingleFlight(() =>
-      coordinateAuthAction(async () => {
-        const result = await renewAdminSession({
-          data: { expectedSessionId: expectedSession() ?? undefined },
-        })
-        observeSession(result.sessionId)
-      })
-    )
+    void renewExpectedSession()
       .then(() => {
         if (active) window.location.replace(redirectTo)
       })
@@ -113,20 +101,15 @@ export function SignInPage({
     >
       <BylineAdminServicesProvider services={bylineAdminServices}>
         <main className={cx('byline-sign-in-page', styles.main)}>
-          <noscript>JavaScript is required to sign in or renew your admin session.</noscript>
           <div className={cx('byline-sign-in-page-bar', styles.bar)}>
             <LanguageMenu />
           </div>
           <div className={cx('byline-sign-in-page-inner', styles.inner)}>
+            <NoScriptNotice />
             {bootstrapError ? (
-              <div role="alert">
-                <p>Unable to check your session. Please try again.</p>
-                <button type="button" onClick={() => window.location.reload()}>
-                  Try again
-                </button>
-              </div>
+              <SessionCheckError />
             ) : checking ? (
-              <p role="status">Checking your session…</p>
+              <SessionCheckIndicator />
             ) : (
               <SignInForm redirectTo={redirectTo} homeUrl={homeUrl} />
             )}
@@ -137,3 +120,76 @@ export function SignInPage({
   )
   return reauthenticate ? content : <SessionChangeBoundary>{content}</SessionChangeBoundary>
 }
+
+/**
+ * Activity indicator shown while the bootstrap renewal runs. Deliberately
+ * wordless on screen; the visually hidden label keeps it announced for
+ * assistive technology. The ring inherits `currentColor`, so it follows
+ * the host theme in light and dark mode without a hard-coded colour.
+ */
+function SessionCheckIndicator() {
+  const { t } = useTranslation('byline-admin')
+  return (
+    <div
+      role="status"
+      aria-live="polite"
+      className={cx('byline-sign-in-page-checking', styles.checking)}
+    >
+      <LoaderRing size={32} aria-hidden="true" />
+      <span className={styles.srOnly}>{t('common.loading')}</span>
+    </div>
+  )
+}
+
+/**
+ * Shown only when JavaScript is unavailable. React renders `<noscript>`
+ * children as static markup on the server and skips them on the client,
+ * so the kit `Alert` here is SSR-only chrome that never hydrates.
+ */
+function NoScriptNotice() {
+  const { t } = useTranslation('byline-admin')
+  return (
+    <noscript>
+      <Alert
+        intent="warning"
+        close={false}
+        className={cx('byline-sign-in-page-alert', styles.alert)}
+      >
+        {t('auth.signIn.noscript')}
+      </Alert>
+    </noscript>
+  )
+}
+
+/**
+ * Bootstrap renewal hit a service or network error, not an auth outcome.
+ * Presented in the same card frame as the form so the three page states
+ * share one visual footprint. Retry is a full reload: it re-runs the
+ * bootstrap without resubmitting anything.
+ */
+function SessionCheckError() {
+  const { t } = useTranslation('byline-admin')
+  return (
+    <Card role="alert" className={cx('byline-sign-in-page-card', styles.card)}>
+      <Card.Header>
+        <Card.Title>
+          <h2>{t('auth.signIn.title')}</h2>
+        </Card.Title>
+        <Alert
+          intent="danger"
+          close={false}
+          className={cx('byline-sign-in-page-alert', styles.alert)}
+        >
+          {t('auth.signIn.errors.bootstrap')}
+        </Alert>
+      </Card.Header>
+      <Card.Content>
+        <div className={cx('byline-sign-in-page-actions', styles.actions)}>
+          <Button type="button" onClick={() => window.location.reload()}>
+            {t('common.actions.tryAgain')}
+          </Button>
+        </div>
+      </Card.Content>
+    </Card>
+  )
+}

package/src/integrations/admin-session-recovery.test.tsx

@@ -0,0 +1,120 @@
+/**
+ * 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 { act } from 'react'
+
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => {
+  const invalidate = vi.fn()
+  return { renew: vi.fn(), invalidate, router: { invalidate }, href: '/en/news' }
+})
+vi.mock('./session-renewal.js', () => ({ renewExpectedSession: mocks.renew }))
+vi.mock('@tanstack/react-router', () => ({
+  // A real router instance is stable across renders; location changes on navigation.
+  useRouter: () => mocks.router,
+  useRouterState: ({ select }: { select: (state: unknown) => unknown }) =>
+    select({ location: { href: mocks.href } }),
+}))
+
+import { AdminSessionRecovery } from './admin-session-recovery.js'
+
+let root: Root
+let container: HTMLDivElement
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+  mocks.href = '/en/news'
+  mocks.invalidate.mockResolvedValue(undefined)
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+})
+afterEach(() => {
+  act(() => root.unmount())
+  container.remove()
+  vi.unstubAllGlobals()
+})
+
+async function render(renewable: boolean) {
+  await act(async () => {
+    root.render(<AdminSessionRecovery renewable={renewable} />)
+  })
+  await act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, 0))
+  })
+}
+
+describe('AdminSessionRecovery', () => {
+  it('renders nothing and does not renew when the session is not renewable', async () => {
+    await render(false)
+    expect(container.innerHTML).toBe('')
+    expect(mocks.renew).not.toHaveBeenCalled()
+    expect(mocks.invalidate).not.toHaveBeenCalled()
+  })
+
+  it('renews and re-runs the route loaders when the session is renewable', async () => {
+    mocks.renew.mockResolvedValue(undefined)
+    await render(true)
+    expect(mocks.renew).toHaveBeenCalledTimes(1)
+    expect(mocks.invalidate).toHaveBeenCalledTimes(1)
+    expect(container.innerHTML).toBe('')
+  })
+
+  it('does not re-run loaders when renewal fails for a service reason', async () => {
+    mocks.renew.mockRejectedValue(new Error('network'))
+    await render(true)
+    expect(mocks.renew).toHaveBeenCalledTimes(1)
+    expect(mocks.invalidate).not.toHaveBeenCalled()
+  })
+
+  it('renews only once while mounted even across re-renders', async () => {
+    mocks.renew.mockResolvedValue(undefined)
+    await render(true)
+    await render(true)
+    expect(mocks.renew).toHaveBeenCalledTimes(1)
+  })
+
+  it('recovers again on a later expiry cycle while the layout stays mounted', async () => {
+    mocks.renew.mockResolvedValue(undefined)
+    await render(true)
+    // The loader re-ran after renewal and reported a live session...
+    await render(false)
+    // ...and a later navigation finds the access credential expired again.
+    await render(true)
+    expect(mocks.renew).toHaveBeenCalledTimes(2)
+    expect(mocks.invalidate).toHaveBeenCalledTimes(2)
+  })
+
+  it('retries on a later navigation after a service failure', async () => {
+    mocks.renew.mockRejectedValueOnce(new Error('network')).mockResolvedValueOnce(undefined)
+    await render(true)
+    expect(mocks.renew).toHaveBeenCalledTimes(1)
+    mocks.href = '/en/news/second-story'
+    await render(true)
+    expect(mocks.renew).toHaveBeenCalledTimes(2)
+    expect(mocks.invalidate).toHaveBeenCalledTimes(1)
+  })
+
+  // Runs last: a terminal outcome suppresses further attempts for the life of
+  // the page (module state), so later cases in this file would see no renewal.
+  it('stops retrying after a terminal auth outcome until the page reloads', async () => {
+    mocks.renew.mockRejectedValue(
+      Object.assign(new Error('revoked'), { code: 'ERR_REVOKED_TOKEN' })
+    )
+    await render(true)
+    expect(mocks.renew).toHaveBeenCalledTimes(1)
+    act(() => root.unmount())
+    root = createRoot(container)
+    mocks.href = '/en/news/after-revocation'
+    await render(true)
+    expect(mocks.renew).toHaveBeenCalledTimes(1)
+    expect(mocks.invalidate).not.toHaveBeenCalled()
+  })
+})

package/src/integrations/admin-session-recovery.tsx

@@ -0,0 +1,72 @@
+/**
+ * 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
+ */
+
+/**
+ * Public-page session recovery.
+ *
+ * Public reads are verification-only and never rotate credentials, so a
+ * signed-in editor whose access credential has expired renders a public page
+ * as an anonymous visitor: the admin bar hides and preview mode drops. Mount
+ * this component in the public layout with the `renewable` hint from
+ * `getCurrentAdminSessionSoft`. When the hint is set it runs the coordinated
+ * browser renewal (same expected-login check as admin navigation) and then
+ * re-runs the route loaders, so the admin bar and any draft-aware reads on
+ * the page re-evaluate against the renewed session.
+ *
+ * It renders nothing. Content already on screen stays as rendered until the
+ * loaders re-run; the renewal never retroactively changes a response that was
+ * produced without preview authorisation.
+ *
+ * The public layout stays mounted across navigations, so recovery must work
+ * for every expiry cycle, not just the first: one attempt runs per renewable
+ * hint per location, never overlapping. After a successful renewal the loader
+ * re-runs and clears the hint; the next expiry sets it again and recovery
+ * runs again. After a service or network failure the hint persists, and the
+ * next navigation (a new location) tries again.
+ *
+ * A terminal auth outcome (revoked, disabled, unknown) suppresses further
+ * attempts for the life of the page: the hint would otherwise repeat on every
+ * navigation while the stale refresh cookie remains.
+ */
+
+import { useEffect, useRef } from 'react'
+import { useRouter, useRouterState } from '@tanstack/react-router'
+
+import { renewExpectedSession } from './session-renewal.js'
+
+const TERMINAL_CODES = new Set([
+  'ERR_UNAUTHENTICATED',
+  'ERR_INVALID_TOKEN',
+  'ERR_REVOKED_TOKEN',
+  'ERR_ACCOUNT_DISABLED',
+  'ERR_SESSION_CHANGED',
+])
+
+let suppressed = false
+
+export function AdminSessionRecovery({ renewable }: { renewable: boolean }) {
+  const router = useRouter()
+  const href = useRouterState({ select: (state) => state.location.href })
+  const inFlight = useRef(false)
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `href` is not read inside the effect; it re-arms recovery on navigation so a service failure can be retried later.
+  useEffect(() => {
+    if (!renewable || inFlight.current || suppressed) return
+    inFlight.current = true
+    // `router.invalidate()` is safe after unmount, so no cleanup guard: a
+    // renewal that completes during a layout remount still refreshes data.
+    renewExpectedSession()
+      .then(() => router.invalidate())
+      .catch((error) => {
+        if (TERMINAL_CODES.has((error as { code?: string })?.code ?? '')) suppressed = true
+      })
+      .finally(() => {
+        inFlight.current = false
+      })
+  }, [renewable, href, router])
+  return null
+}

package/src/integrations/session-renewal.test.tsx

@@ -0,0 +1,72 @@
+/**
+ * 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 { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({ renew: vi.fn() }))
+vi.mock('../server-fns/auth/renew.js', () => ({ renewAdminSession: mocks.renew }))
+
+import { acceptSession, expectedSession, sessionIsChanged } from './session-coordination.js'
+import { renewExpectedSession } from './session-renewal.js'
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  vi.stubGlobal('BroadcastChannel', undefined)
+  window.sessionStorage.clear()
+})
+
+describe('renewExpectedSession', () => {
+  // Runs first: the coordinator caches the expected login at module level, so
+  // only the initial case in this file observes a page with no expected login.
+  it('adopts the verified login when the page had no expected login yet', async () => {
+    mocks.renew.mockResolvedValue({ sessionId: 'login-2' })
+    await renewExpectedSession()
+    expect(mocks.renew).toHaveBeenCalledWith({ data: { expectedSessionId: undefined } })
+    expect(expectedSession()).toBe('login-2')
+  })
+
+  it('sends the stored expected login and keeps it when renewal returns the same login', async () => {
+    acceptSession('login-1')
+    mocks.renew.mockResolvedValue({ sessionId: 'login-1' })
+    await renewExpectedSession()
+    expect(mocks.renew).toHaveBeenCalledWith({ data: { expectedSessionId: 'login-1' } })
+    expect(expectedSession()).toBe('login-1')
+    expect(sessionIsChanged()).toBe(false)
+  })
+
+  it('flags a session change and rethrows when renewal reports one', async () => {
+    acceptSession('login-1')
+    mocks.renew.mockRejectedValue(
+      Object.assign(new Error('changed'), { code: 'ERR_SESSION_CHANGED' })
+    )
+    await expect(renewExpectedSession()).rejects.toMatchObject({ code: 'ERR_SESSION_CHANGED' })
+    expect(sessionIsChanged()).toBe(true)
+  })
+
+  it('flags a session change when renewal returns a different login', async () => {
+    acceptSession('login-1')
+    mocks.renew.mockResolvedValue({ sessionId: 'login-9' })
+    await expect(renewExpectedSession()).rejects.toThrow()
+    expect(sessionIsChanged()).toBe(true)
+  })
+
+  it('coalesces concurrent callers into one renewal request', async () => {
+    acceptSession('login-1')
+    let release!: () => void
+    mocks.renew.mockReturnValue(
+      new Promise((resolve) => {
+        release = () => resolve({ sessionId: 'login-1' })
+      })
+    )
+    const first = renewExpectedSession()
+    const second = renewExpectedSession()
+    release()
+    await Promise.all([first, second])
+    expect(mocks.renew).toHaveBeenCalledTimes(1)
+  })
+})

package/src/integrations/session-renewal.ts

@@ -0,0 +1,45 @@
+/**
+ * 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
+ */
+
+/**
+ * Browser-side session renewal shared by every navigation-time caller: the
+ * admin layout guard (client-side navigation after access expiry) and the
+ * sign-in page bootstrap (server-rendered navigation after access expiry).
+ *
+ * Runs the CSRF-protected renewal server fn once per page (same-tab
+ * single-flight), inside the cross-tab auth-action queue, carrying the page's
+ * expected login so renewal can never silently adopt another tab's account.
+ * A reported or observed login change flags the session-change interstitial
+ * and rejects; callers must not treat that as a retryable outcome.
+ *
+ * Business-operation renewal lives in `session-middleware.ts`; it captures a
+ * per-operation snapshot and resends, which this navigation helper does not.
+ */
+
+import { renewAdminSession } from '../server-fns/auth/renew.js'
+import {
+  coordinateAuthAction,
+  expectedSession,
+  flagSessionChanged,
+  observeSession,
+  renewSingleFlight,
+} from './session-coordination.js'
+
+export function renewExpectedSession(): Promise<void> {
+  return renewSingleFlight(() =>
+    coordinateAuthAction(async () => {
+      const result = await renewAdminSession({
+        data: { expectedSessionId: expectedSession() ?? undefined },
+      }).catch((error) => {
+        if (error?.code === 'ERR_SESSION_CHANGED') flagSessionChanged()
+        throw error
+      })
+      observeSession(result.sessionId)
+    })
+  )
+}