@woodsportal/hubspot-kit 1.0.41 → 1.0.42-dev.1

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/Layouts/MainLayout.tsx

@@ -0,0 +1,7 @@
+import type { ReactNode } from 'react'
+
+import { PortalSidebar } from '@/components/layout/portal-sidebar'
+
+export default function MainLayout({ children }: { children?: ReactNode }) {
+  return <PortalSidebar>{children}</PortalSidebar>
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/Layouts/UnauthorizedLayout.tsx

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react'
+
+export default function UnauthorizedLayout({ children }: { children?: ReactNode }) {
+  return <div className="min-h-screen bg-gray-50">{children}</div>
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/Layouts/index.ts

@@ -0,0 +1,13 @@
+import MainLayout from '@/components/Layouts/MainLayout'
+import AuthLayout from '@/components/Layouts/AuthLayout'
+import DefaultLayout from '@/components/Layouts/DefaultLayout'
+import UnauthorizedLayout from '@/components/Layouts/UnauthorizedLayout'
+
+export const layoutMap = {
+  MainLayout,
+  AuthLayout,
+  DefaultLayout,
+  UnauthorizedLayout,
+} as const
+
+export type LayoutName = keyof typeof layoutMap

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/layout/portal-sidebar-nav.tsx

@@ -0,0 +1,33 @@
+import { Link } from '@/components/ui/link'
+import { portalNavItems } from '@/config/portal-nav'
+
+type PortalSidebarNavProps = {
+  collapsed?: boolean
+  onNavigate?: () => void
+}
+
+export function PortalSidebarNav({ collapsed = false, onNavigate }: PortalSidebarNavProps) {
+  return (
+    <nav className="flex flex-col gap-1 px-2 py-3">
+      {portalNavItems.map((item) => (
+        <Link
+          key={item.to}
+          to={item.to}
+          onClick={onNavigate}
+          title={collapsed ? item.label : undefined}
+          className={`rounded-md px-3 py-2 text-sm text-gray-700 hover:bg-gray-100 ${
+            collapsed ? 'text-center' : ''
+          }`}
+          activeProps={{
+            className: `rounded-md bg-orange-50 px-3 py-2 text-sm font-medium text-orange-700 ${
+              collapsed ? 'text-center' : ''
+            }`,
+          }}
+          activeOptions={{ exact: true }}
+        >
+          {collapsed ? item.label.charAt(0) : item.label}
+        </Link>
+      ))}
+    </nav>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/layout/portal-sidebar.tsx

@@ -0,0 +1,139 @@
+import { useCallback, useEffect, useState, type ReactNode } from 'react'
+import { useRouter } from '@tanstack/react-router'
+
+import { Button } from '@/components/ui/Button'
+import { Routes } from '@/config/routes'
+import { clearClientAuthSession } from '@/features/auth/clear-client-auth-session'
+import { useSignedInEmail } from '@/features/auth/use-signed-in-email'
+import { usePortalSession } from '@/features/auth/use-portal-session'
+import { api } from '@/integrations/woodsportal-sdk'
+
+import { PortalSidebarNav } from './portal-sidebar-nav'
+
+type PortalSidebarProps = {
+  children: ReactNode
+}
+
+export function PortalSidebar({ children }: PortalSidebarProps) {
+  const [collapsed, setCollapsed] = useState(false)
+  const [mobileOpen, setMobileOpen] = useState(false)
+  const isAuthenticated = usePortalSession()
+  const { email, isLoading } = useSignedInEmail()
+  const router = useRouter()
+
+  const closeMobile = useCallback(() => setMobileOpen(false), [])
+
+  useEffect(() => {
+    if (!mobileOpen) {
+      return
+    }
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        closeMobile()
+      }
+    }
+    window.addEventListener('keydown', onKeyDown)
+    return () => window.removeEventListener('keydown', onKeyDown)
+  }, [mobileOpen, closeMobile])
+
+  useEffect(() => {
+    if (!isAuthenticated) {
+      return
+    }
+    const { me } = api.auth.me({})
+    void me()
+  }, [isAuthenticated])
+
+  const handleLogout = async () => {
+    clearClientAuthSession()
+    try {
+      const { logout } = api.auth.logout({})
+      await logout()
+    } catch {
+      // local state already cleared
+    }
+    router.navigate({ to: Routes.login })
+  }
+
+  const signedInLabel = isLoading ? 'Loading…' : (email ?? 'Signed in')
+
+  const sidebarWidth = collapsed ? 'w-16' : 'w-60'
+  const motionClass = 'motion-reduce:transition-none transition-[width] duration-200 ease-in-out'
+
+  const sidebarPanel = (
+    <aside
+      className={`flex h-full shrink-0 flex-col border-r border-gray-200 bg-white ${sidebarWidth} ${motionClass}`}
+    >
+      <div className="flex items-center justify-between gap-2 border-b border-gray-200 px-3 py-4">
+        {!collapsed ? (
+          <span className="truncate text-sm font-semibold text-gray-900">WoodsPortal</span>
+        ) : (
+          <span className="w-full text-center text-sm font-semibold text-gray-900">W</span>
+        )}
+        <button
+          type="button"
+          className="hidden rounded-md p-1 text-gray-500 hover:bg-gray-100 md:inline-flex"
+          aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+          onClick={() => setCollapsed((value) => !value)}
+        >
+          {collapsed ? '»' : '«'}
+        </button>
+      </div>
+
+      <div className="flex-1 overflow-y-auto">
+        <PortalSidebarNav collapsed={collapsed} onNavigate={closeMobile} />
+      </div>
+
+      {isAuthenticated ? (
+        <div className="border-t border-gray-200 p-3">
+          {!collapsed ? (
+            <p className="mb-2 truncate text-xs text-gray-500" title={signedInLabel}>
+              {signedInLabel}
+            </p>
+          ) : null}
+          <Button
+            type="button"
+            variant="outline"
+            className={`w-full text-xs ${collapsed ? 'px-2' : ''}`}
+            onClick={() => void handleLogout()}
+          >
+            {collapsed ? 'Out' : 'Sign out'}
+          </Button>
+        </div>
+      ) : null}
+    </aside>
+  )
+
+  return (
+    <div className="flex min-h-screen bg-white">
+      <div className="hidden md:flex">{sidebarPanel}</div>
+
+      {mobileOpen ? (
+        <div className="fixed inset-0 z-40 flex md:hidden">
+          <button
+            type="button"
+            className="absolute inset-0 bg-black/40"
+            aria-label="Close navigation"
+            onClick={closeMobile}
+          />
+          <div className="relative z-50 flex h-full w-60 flex-col bg-white shadow-lg">{sidebarPanel}</div>
+        </div>
+      ) : null}
+
+      <div className="flex min-w-0 flex-1 flex-col">
+        <header className="flex items-center gap-3 border-b border-gray-200 px-4 py-3 md:hidden">
+          <button
+            type="button"
+            className="rounded-md border border-gray-200 px-2 py-1 text-sm text-gray-700"
+            aria-label="Open navigation"
+            onClick={() => setMobileOpen(true)}
+          >
+            Menu
+          </button>
+          <span className="text-sm font-semibold text-gray-900">WoodsPortal</span>
+        </header>
+        <main className="flex-1 p-6">{children}</main>
+      </div>
+    </div>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/layout/section-card.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react'
+
+export function SectionCard({
+  title,
+  children,
+  className = '',
+}: {
+  title: string
+  children: ReactNode
+  className?: string
+}) {
+  return (
+    <section
+      className={`rounded-lg border border-[#cbd6e2] bg-white p-6 shadow-sm ${className}`}
+    >
+      <h2 className="text-base font-semibold text-[#33475b]">{title}</h2>
+      <div className="mt-4">{children}</div>
+    </section>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/layout/starter-nav.tsx

@@ -0,0 +1,28 @@
+import { Link } from '@tanstack/react-router'
+
+import { ROUTES } from '@/config/routes'
+
+export function StarterNav() {
+  return (
+    <header className="border-b border-[#cbd6e2] bg-white/90 backdrop-blur">
+      <div className="mx-auto flex max-w-4xl items-center justify-between gap-4 px-6 py-3 sm:px-10">
+        <span className="text-sm font-semibold text-[#0091ae]">WoodsCLI starter</span>
+        <nav className="flex gap-4 text-sm font-medium">
+          <Link
+            to={ROUTES.home}
+            className="text-[#516f90] hover:text-[#0091ae] [&.active]:text-[#0091ae]"
+            activeOptions={{ exact: true }}
+          >
+            Home
+          </Link>
+          <Link
+            to={ROUTES.guide}
+            className="text-[#516f90] hover:text-[#0091ae] [&.active]:text-[#0091ae]"
+          >
+            Developer guide
+          </Link>
+        </nav>
+      </div>
+    </header>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/layout/starter-shell.tsx

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react'
+
+import { StarterNav } from './starter-nav'
+
+export function StarterShell({
+  children,
+  showNav = true,
+}: {
+  children: ReactNode
+  showNav?: boolean
+}) {
+  return (
+    <div className="min-h-screen bg-[#eaf0f6] text-[#33475b]">
+      {showNav ? <StarterNav /> : null}
+      {children}
+    </div>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/ui/Button.tsx

@@ -0,0 +1,22 @@
+import { forwardRef, type ButtonHTMLAttributes } from 'react'
+
+type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+  variant?: 'default' | 'outline'
+}
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className = '', variant = 'default', children, ...props }, ref) => {
+    const base =
+      'inline-flex items-center justify-center rounded-md px-4 py-2 text-sm font-medium transition disabled:opacity-50'
+    const styles =
+      variant === 'outline'
+        ? 'border border-gray-300 bg-white text-gray-900 hover:bg-gray-50'
+        : 'bg-[var(--primary-color,#FF7A59)] text-[var(--button-text-color,#FFFFFF)] hover:opacity-90'
+    return (
+      <button ref={ref} className={`${base} ${styles} ${className}`} {...props}>
+        {children}
+      </button>
+    )
+  },
+)
+Button.displayName = 'Button'

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/ui/Form.tsx

@@ -0,0 +1,22 @@
+import type { FormHTMLAttributes, ReactNode } from 'react'
+
+type FormProps = FormHTMLAttributes<HTMLFormElement> & {
+  children: ReactNode
+}
+
+export function Form({ children, className = '', ...props }: FormProps) {
+  return (
+    <form className={`flex flex-col gap-4 ${className}`} {...props}>
+      {children}
+    </form>
+  )
+}
+
+export function FormField({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <label className="flex flex-col gap-1 text-sm text-gray-700">
+      <span>{label}</span>
+      {children}
+    </label>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/ui/Input.tsx

@@ -0,0 +1,12 @@
+import { forwardRef, type InputHTMLAttributes } from 'react'
+
+export const Input = forwardRef<HTMLInputElement, InputHTMLAttributes<HTMLInputElement>>(
+  ({ className = '', ...props }, ref) => (
+    <input
+      ref={ref}
+      className={`w-full rounded-md border border-gray-300 px-3 py-2 text-sm outline-none focus:ring-2 focus:ring-orange-500 ${className}`}
+      {...props}
+    />
+  ),
+)
+Input.displayName = 'Input'

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/ui/Toaster.tsx

@@ -0,0 +1,5 @@
+import { Toaster as SonnerToaster } from 'sonner'
+
+export function Toaster() {
+  return <SonnerToaster position="top-center" richColors closeButton />
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/ui/link.tsx

@@ -0,0 +1,10 @@
+import { Link as RouterLink, type LinkProps } from '@tanstack/react-router'
+
+export function Link({ className = '', ...props }: LinkProps) {
+  return (
+    <RouterLink
+      className={`text-orange-600 underline-offset-4 hover:underline ${className}`}
+      {...props}
+    />
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/components/ui/loader/loader.tsx

@@ -0,0 +1,18 @@
+interface LoaderProps {
+  className?: string
+  text?: string
+  showText?: boolean
+}
+
+export default function Loader({ className = '', text = 'Loading…', showText = true }: LoaderProps) {
+  return (
+    <div className={`flex min-h-[40vh] flex-col items-center justify-center gap-3 ${className}`}>
+      <div
+        className="h-10 w-10 animate-spin rounded-full border-4 border-orange-200 border-t-orange-600"
+        role="status"
+        aria-label="Loading"
+      />
+      {showText ? <p className="text-sm text-gray-600">{text}</p> : null}
+    </div>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/config/auth-tier.ts

@@ -0,0 +1,4 @@
+/** Set by wp init --auth starter. */
+export const AUTH_SCAFFOLD_TIER = 'starter' as const
+
+export type AuthScaffoldTier = typeof AUTH_SCAFFOLD_TIER

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/config/nav-scaffold.ts

@@ -0,0 +1,4 @@
+/** Set by wp init --nav (top | sidebar). */
+export const NAV_SCAFFOLD_MODE = 'sidebar' as const
+
+export type NavScaffoldMode = typeof NAV_SCAFFOLD_MODE

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/config/portal-nav.ts

@@ -0,0 +1,9 @@
+import { Routes } from '@/config/routes'
+
+/** Portal navigation links — edit once; top nav and sidebar both read this file. */
+export const portalNavItems = [
+  { to: Routes.portal, label: 'Portal', requiresAuth: false },
+  { to: Routes.guide, label: 'Guide', requiresAuth: false },
+] as const
+
+export type PortalNavItem = (typeof portalNavItems)[number]

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/config/router.ts

@@ -0,0 +1 @@
+export const ROUTER_HISTORY = 'hash' as const

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/config/routes.ts

@@ -0,0 +1,10 @@
+/** Route paths — keep in sync with `src/routes/` file routes. */
+export const Routes = {
+  login: '/login',
+  twoFa: '/two-fa',
+  unauthorized: '/unauthorized',
+  ssoLogin: '/login/sso',
+  portal: '/portal',
+  guide: '/guide',
+  app: '/portal',
+} as const

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/data/hubSpotContext.ts

@@ -0,0 +1,57 @@
+import { env, isLocal } from '@/env'
+
+declare global {
+  interface Window {
+    hubSpotData?: {
+      hubId?: number | string
+      isInEditor?: boolean
+      isInPreviewer?: boolean
+      [key: string]: unknown
+    }
+  }
+}
+
+const DEFAULT_LOCAL_HUB_ID = 12345678
+
+export function isHubSpotEmbed(): boolean {
+  if (typeof window === 'undefined') {
+    return false
+  }
+  return window.hubSpotData != null
+}
+
+export function shouldUseLocalFixtures(): boolean {
+  return isLocal && !isHubSpotEmbed()
+}
+
+function cmsHubId(): number | string | undefined {
+  const raw = typeof window !== 'undefined' ? window.hubSpotData?.hubId : undefined
+  if (raw == null || String(raw).trim() === '') {
+    return undefined
+  }
+  return raw
+}
+
+export function resolveLocalHubId(): number {
+  const raw = env.VITE_LOCAL_HUB_ID ?? env.VITE_DEV_HUB_ID
+  if (raw != null && raw !== '') {
+    const parsed = Number(raw)
+    if (Number.isFinite(parsed)) {
+      return parsed
+    }
+  }
+  return DEFAULT_LOCAL_HUB_ID
+}
+
+export function resolveHubId(): number | string | undefined {
+  const fromCms = cmsHubId()
+  if (fromCms != null) {
+    return fromCms
+  }
+  if (shouldUseLocalFixtures()) {
+    return resolveLocalHubId()
+  }
+  return undefined
+}
+
+export const hubId = resolveHubId()

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/data/sync-sdk-hub-context.ts

@@ -0,0 +1,44 @@
+import {
+  clearStaleIframeRefreshForOtherHubs,
+  migrateLegacyStorageKeys,
+  WP_STORAGE_KEYS,
+} from 'woodsportal-client-sdk'
+import { store } from '@/integrations/woodsportal-sdk'
+import { env } from '@/env'
+import { resolveWoodsPortalApiBaseUrl } from '@/utils/resolve-api-base-url'
+import { isHubSpotEmbed, resolveHubId } from './hubSpotContext'
+
+const { storage } = store
+
+export function syncSdkHubContextFromRuntime(): void {
+  migrateLegacyStorageKeys()
+
+  const resolvedHubId = resolveHubId()
+  const hubKey = WP_STORAGE_KEYS.c.hub
+  const prevData =
+    storage.get<Record<string, unknown>>(hubKey) ||
+    storage.get<Record<string, unknown>>('hubSpotData') ||
+    {}
+  const payload: Record<string, unknown> = {
+    ...prevData,
+    devApiUrl: resolveWoodsPortalApiBaseUrl(),
+  }
+
+  if (resolvedHubId != null && String(resolvedHubId).trim() !== '') {
+    payload.hubId = resolvedHubId
+    clearStaleIframeRefreshForOtherHubs(resolvedHubId)
+  } else {
+    delete payload.hubId
+    if (isHubSpotEmbed() && import.meta.env.PROD) {
+      console.warn('[WoodsPortal] Missing hubSpotData.hubId on HubSpot embed — login will fail')
+    }
+  }
+
+  if (import.meta.env.DEV && env.VITE_DEV_PORTAL_ID != null && env.VITE_DEV_PORTAL_ID !== '') {
+    payload.devPortalId = String(env.VITE_DEV_PORTAL_ID)
+  } else {
+    delete payload.devPortalId
+  }
+
+  storage.set(hubKey, payload)
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/defaultData.ts

@@ -0,0 +1,2 @@
+/** Kit runtime imports `@/defaultData` — re-export from the hubspot slice. */
+export { devDefaultData as defaultData } from './hubspot/default-data'

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/env.ts

@@ -0,0 +1,59 @@
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+const defaultHubspotObjectIds =
+  '{"contacts":"0-1","companies":"0-2","deals":"0-3","tickets":"0-5"}'
+
+export function parseHubspotDefaultObjectIds(raw: unknown): Record<string, string> {
+  if (typeof raw === 'object' && raw !== null && !Array.isArray(raw)) {
+    return raw as Record<string, string>
+  }
+  try {
+    return JSON.parse(String(raw ?? defaultHubspotObjectIds))
+  } catch {
+    return JSON.parse(defaultHubspotObjectIds)
+  }
+}
+
+export const env = createEnv({
+  server: {
+    SERVER_URL: z.string().url().optional(),
+  },
+  clientPrefix: 'VITE_',
+  client: {
+    VITE_NODE_ENV: z.enum(['local', 'dev', 'prod', 'stg', 'development', 'production', 'staging']).default('local'),
+    VITE_PUBLIC_REST_API_ENDPOINT: z
+      .string()
+      .url()
+      .default('https://api.dev.woodsportal.com'),
+    VITE_DEV_PORTAL_ID: z.union([z.string(), z.number()]).optional(),
+    VITE_LOCAL_HUB_ID: z.union([z.string(), z.number()]).optional(),
+    VITE_DEV_HUB_ID: z.union([z.string(), z.number()]).optional(),
+    VITE_LOGIN_DETAILS: z.string().default('wp.c.auth.login'),
+    VITE_SUBSCRIPTION_TYPE: z.string().default('wp.c.auth.sub'),
+    VITE_PAGINATION_DATA: z.string().default('wp.c.ui.pag'),
+    VITE_PORTAL: z.string().default('wp.c.auth.portal'),
+    VITE_AUTH_TOKEN_KEY: z.string().default('woodsportal_access_token'),
+    VITE_REFRESH_TOKEN: z.string().default('wp.c.auth.refresh'),
+    VITE_AUTH_USER_KEY: z.string().default('wp.c.auth.login'),
+    VITE_ROUTE_MENU_CONFIG_KEY: z.string().default('wp.c.ui.menu'),
+    VITE_ASSOCIATION_VIEW_URL_KEY: z.string().default('wp.c.ui.assoc'),
+    VITE_COOKIE_EXPIRE: z.string().default('7'),
+    VITE_TABLE_PAGE_LIMIT: z.string().default('25'),
+    VITE_HUBSPOT_DEFAULT_OBJECT_IDS: z.any().default(defaultHubspotObjectIds),
+  },
+  runtimeEnv: import.meta.env,
+  emptyStringAsUndefined: true,
+})
+
+export const TABLE_PAGE_LIMIT = Math.max(
+  1,
+  Number.parseInt(env.VITE_TABLE_PAGE_LIMIT, 10) || 25,
+)
+
+export const HUBSPOT_DEFAULT_OBJECT_IDS = parseHubspotDefaultObjectIds(
+  env.VITE_HUBSPOT_DEFAULT_OBJECT_IDS,
+)
+
+export const isLocal =
+  env.VITE_NODE_ENV === 'local' || env.VITE_NODE_ENV === 'development'

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/features/auth/app-bootstrap-guards.ts

@@ -0,0 +1,14 @@
+export type BootstrapRefreshDecisionInput = {
+  isMfaPendingSession: boolean
+  hasRefresh: boolean
+  isPublicAuthRoute: boolean
+}
+
+export function shouldBootstrapRefreshSession(
+  input: BootstrapRefreshDecisionInput,
+): boolean {
+  if (input.isMfaPendingSession || input.isPublicAuthRoute) {
+    return false
+  }
+  return input.hasRefresh
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter-sidebar/src/features/auth/auth-navigation.ts

@@ -0,0 +1,81 @@
+import { Routes } from '@/config/routes'
+import { normalizeRouterPath } from '@/utils/normalize-router-path'
+import {
+  hardReplaceToHashPath,
+  historyReplaceFirstNavigate,
+  readHashPathname,
+  readRouterPathname,
+  type SafeAuthRouter,
+} from '@/utils/safe-router-navigation'
+import { resolvePostLoginPath, type PostLoginRouter } from '@/features/auth/resolve-post-login-path'
+
+export type AuthNavigationRouter = PostLoginRouter
+
+let navigationState = {
+  inFlight: false,
+  lastTarget: '',
+  lastAt: 0,
+}
+
+function normalizeTarget(path: string): string {
+  return normalizeRouterPath(path)
+}
+
+export function isRouterAtPath(router: SafeAuthRouter, path: string): boolean {
+  const target = normalizeTarget(path)
+  const pathname = normalizeTarget(readRouterPathname(router))
+  const hashPath = normalizeTarget(readHashPathname())
+  return pathname === target && hashPath === target
+}
+
+function shouldSkipNavigation(target: string): boolean {
+  const now = Date.now()
+  return (
+    navigationState.inFlight ||
+    (navigationState.lastTarget === target && now - navigationState.lastAt < 2000)
+  )
+}
+
+async function runCoordinatedNavigation(router: SafeAuthRouter, rawTarget: string): Promise<void> {
+  const target = normalizeTarget(rawTarget)
+  if (!target || isRouterAtPath(router, target) || shouldSkipNavigation(target)) {
+    return
+  }
+  navigationState = { inFlight: true, lastTarget: target, lastAt: Date.now() }
+  try {
+    await historyReplaceFirstNavigate(router, target)
+    await new Promise<void>((resolve) => window.setTimeout(resolve, 100))
+    if (!isRouterAtPath(router, target)) {
+      hardReplaceToHashPath(target)
+    }
+  } finally {
+    navigationState = { inFlight: false, lastTarget: target, lastAt: Date.now() }
+  }
+}
+
+export function navigateAfterFullAuth(router: AuthNavigationRouter, target?: string): void {
+  const resolved = target ?? resolvePostLoginPath(router)
+  if (isRouterAtPath(router, resolved)) {
+    return
+  }
+  void runCoordinatedNavigation(router, resolved)
+}
+
+export function navigateToMfaGate(router: SafeAuthRouter): void {
+  if (isRouterAtPath(router, Routes.twoFa)) {
+    return
+  }
+  void runCoordinatedNavigation(router, Routes.twoFa)
+}
+
+export function navigateToLogin(router: SafeAuthRouter, path: string = Routes.login): Promise<void> {
+  const target = normalizeTarget(path)
+  if (isRouterAtPath(router, target)) {
+    return Promise.resolve()
+  }
+  return runCoordinatedNavigation(router, target)
+}
+
+export function resetAuthNavigationState(): void {
+  navigationState = { inFlight: false, lastTarget: '', lastAt: 0 }
+}