@woodsportal/hubspot-kit 1.0.41-dev.4 → 1.0.41-dev.6

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/components/starter-protected-page.tsx

@@ -0,0 +1,54 @@
+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 { StarterPageFrame } from '@/features/starter/components/starter-page-frame'
+import { api } from '@/integrations/woodsportal-sdk'
+
+export function StarterProtectedPage() {
+  const isAuthenticated = usePortalSession()
+  const { email, isLoading } = useSignedInEmail()
+  const router = useRouter()
+
+  const signedInLabel = isLoading ? 'Loading…' : (email ?? 'Signed in')
+
+  const handleLogout = async () => {
+    clearClientAuthSession()
+    try {
+      const { logout } = api.auth.logout({})
+      await logout()
+    } catch {
+      // local state already cleared
+    }
+    router.navigate({ to: Routes.login })
+  }
+
+  return (
+    <StarterPageFrame
+      title="Protected portal"
+      description={
+        <>
+          You reached <code className="rounded bg-gray-100 px-1">/portal</code> — sample authenticated
+          page for the auth scaffold.
+        </>
+      }
+    >
+      <dl className="rounded-lg border border-gray-200 bg-gray-50 p-4 text-sm">
+        <div className="flex justify-between gap-4">
+          <dt className="text-gray-500">Session</dt>
+          <dd className="font-medium text-gray-900">{isAuthenticated ? 'Active' : 'None'}</dd>
+        </div>
+        <div className="mt-2 flex justify-between gap-4">
+          <dt className="text-gray-500">Signed in as</dt>
+          <dd className="font-medium text-gray-900">{signedInLabel}</dd>
+        </div>
+      </dl>
+      <Button variant="outline" onClick={() => void handleLogout()}>
+        Sign out
+      </Button>
+    </StarterPageFrame>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/components/starter-single-page.tsx

@@ -0,0 +1,17 @@
+import { StarterShell } from '@/components/layout/starter-shell'
+
+import { StarterGuidePage } from './starter-guide-page'
+import { StarterHome } from './starter-home'
+
+/** Single-page starter when `wp init --router none` (no TanStack Router). */
+export function StarterSinglePage() {
+  return (
+    <StarterShell showNav={false}>
+      <StarterHome />
+      <div className="mx-auto max-w-4xl px-6 sm:px-10">
+        <hr className="my-10 border-[#cbd6e2]" />
+      </div>
+      <StarterGuidePage />
+    </StarterShell>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/content/auth-guide-content.ts

@@ -0,0 +1,91 @@
+export type AuthTierName = 'starter' | 'sso' | 'full'
+
+export const AUTH_TIER_DESCRIPTION: Record<AuthTierName, string> = {
+  starter: 'Email + password login with a protected /portal sample page.',
+  sso: 'Starter login plus SSO OAuth callback handling at /login/sso.',
+  full: 'SSO plus MFA gate at /two-fa — recommended when the hub enforces 2FA.',
+}
+
+export const AUTH_ENV_VARS = [
+  {
+    name: 'VITE_PUBLIC_REST_API_ENDPOINT',
+    note: 'woodsportal-api base URL (required for login). Example: https://api.dev.woodsportal.com',
+  },
+  {
+    name: 'VITE_DEV_PORTAL_ID',
+    note: 'Optional local dev portal id — sent as X-Dev-Portal-Id when logging in.',
+  },
+  {
+    name: 'VITE_REFRESH_TOKEN',
+    note: 'Cookie name for the refresh token (not the token value). Default: wp.c.auth.refresh',
+  },
+] as const
+
+export const AUTH_BOOT_STEPS = [
+  'mountPortal → syncSdkHubContextFromRuntime',
+  'configureWoodsPortalSdk (woodsportal-client-sdk HTTP client)',
+  'SSO URL normalization (sso / full tiers)',
+  'App bootstrap refresh (existing refresh cookie)',
+  'TanStack Router + PublicRoute / PrivateRoute guards',
+  'MainLayout → api.auth.me() (GET /api/auth/me) when authenticated',
+] as const
+
+export const AUTH_PROJECT_PATHS = [
+  { path: 'src/config/auth-tier.ts', note: 'Scaffold tier patched by wp init (starter | sso | full)' },
+  { path: 'src/config/portal-nav.ts', note: 'Shared nav links for top nav and sidebar layouts' },
+  { path: 'src/config/nav-scaffold.ts', note: 'Nav shell mode patched by wp init (top | sidebar)' },
+  { path: 'src/features/auth/', note: 'Login UI, session bridge, route guards, email storage' },
+  { path: 'src/integrations/configure-woodsportal-sdk.ts', note: 'SDK HTTP init — API URL, cookies, routes' },
+  { path: 'src/integrations/woodsportal-sdk.ts', note: 'Single import surface for api.auth.* and api.crm.*' },
+  { path: 'src/app.tsx', note: 'Session bootstrap before RouterProvider mounts' },
+  { path: 'src/utils/public-route.tsx', note: 'Redirects authenticated users away from /login' },
+  { path: 'src/utils/private-route.tsx', note: 'Protects routes with requiresAuth: true' },
+] as const
+
+export const AUTH_INIT_EXAMPLES: Record<AuthTierName, string> = {
+  starter:
+    'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth starter -y',
+  sso: 'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth sso -y',
+  full: 'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth full -y',
+}
+
+export const AUTH_NAV_EXAMPLES = {
+  top: 'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth starter -y',
+  sidebar:
+    'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth starter --nav sidebar -y',
+} as const
+
+export const PAGE_SCAFFOLD_EXAMPLES = [
+  'wp page add settings --protected --nav',
+  'wp page add about --public',
+  'wp page add billing --protected --title "Billing" --no-nav',
+] as const
+
+export function authRoutesForTier(tier: AuthTierName): Array<{ path: string; access: string }> {
+  const routes = [
+    { path: '/guide', access: 'Public — this page' },
+    { path: '/login', access: 'Public — email + password' },
+    { path: '/portal', access: 'Protected — sample page after login' },
+    { path: '/unauthorized', access: 'Public' },
+  ]
+  if (tier === 'sso' || tier === 'full') {
+    routes.splice(2, 0, { path: '/login/sso', access: 'Public — SSO OAuth callback' })
+  }
+  if (tier === 'full') {
+    routes.splice(3, 0, { path: '/two-fa', access: 'Public — MFA OTP gate' })
+  }
+  return routes
+}
+
+export const PORTAL_AUTH_VS_HUBSPOT = [
+  {
+    label: 'HubSpot CLI auth',
+    cmds: 'wp auth · wp portal use',
+    purpose: 'Upload/watch module files to Design Manager',
+  },
+  {
+    label: 'Portal user auth',
+    cmds: 'wp init --auth starter|sso|full',
+    purpose: 'End users sign in via woodsportal-api + woodsportal-client-sdk',
+  },
+] as const

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/content/woodscli-guide-content.ts

@@ -0,0 +1,86 @@
+/** Static WoodsCLI developer reference — shown on the wp init starter pages. */
+
+export const WOODSCLI_COMMANDS = [
+  {
+    cmd: 'wp dev',
+    desc: 'Local Vite preview + module-config overlay (this page). Alias: wp local.',
+  },
+  {
+    cmd: 'wp doctor',
+    desc: 'Validate Node, deps, .wphs/, index.html, fields.json, and HubSpot CLI setup.',
+  },
+  {
+    cmd: 'wp build --tier prod',
+    desc: 'Production build (CDN bundle and/or HubSpot module, per projectType).',
+  },
+  {
+    cmd: 'wp deploy --tier prod',
+    desc: 'Build, publish CDN artifacts, and upload the module to HubSpot.',
+  },
+  {
+    cmd: 'wp setup',
+    desc: 'Copy hubspot.config.yml, .env.*, and vite shims from kit templates.',
+  },
+  {
+    cmd: 'wp migrate --yes',
+    desc: 'Move legacy .dev/ or woodsportal.hs.json to .wphs/ + woodscli.json.',
+  },
+] as const
+
+export const PROJECT_LAYOUT = [
+  { path: 'woodscli.json', note: 'Project config — module paths, entries, dev.adapter' },
+  { path: 'public/fields.json', note: 'HubSpot module field schema (Content / Styles tabs)' },
+  { path: '.wphs/', note: 'Local workspace — config, fixtures, kit symlinks (gitignore most)' },
+  { path: 'wphs.adapter.ts', note: 'Syncs module field values → window.__WPHS_DATA__ in dev' },
+  { path: 'src/config/router.ts', note: 'Hash vs browser history — set by wp init (hash = client-frontend)' },
+  { path: 'src/routes/', note: 'TanStack Router file routes (thin — delegate to features/)' },
+  { path: 'src/app.tsx', note: 'RouterProvider shell — same role as woodsportal-client-frontend App' },
+  { path: 'src/features/starter/', note: 'Starter demo UI — replace with your portal features' },
+  { path: 'src/portal/', note: 'Dev vs production mount (mount-dev-preview, mount-portal)' },
+  { path: 'src/integrations/', note: 'Third-party wiring (TanStack Router, SDK, etc.)' },
+  { path: 'src/hubspot/', note: 'HubSpot runtime types and dev fixtures' },
+  { path: 'src/main.tsx', note: 'Dev entry — mounts overlay + routed preview' },
+  { path: 'hubspot.config.yml', note: 'HubSpot CLI portal + PAT (copy from .example)' },
+] as const
+
+export const DEV_WORKFLOW = [
+  {
+    title: '1 · Edit module fields',
+    body: 'Press Ctrl+Shift+Z (Mac ⌃⇧Z) to open the HubSpot-style Content / Styles panel. Changes apply to the preview after you click Apply changes.',
+  },
+  {
+    title: '2 · Iterate in src/',
+    body: 'Add features under src/features/, shared UI under src/components/, and wire HubSpot data via wphs.adapter.ts and public/fields.json.',
+  },
+  {
+    title: '3 · Connect HubSpot',
+    body: 'Copy hubspot.config.yml.example → hubspot.config.yml, add a personal access key, then wp upload or wp watch for CMS sync.',
+  },
+  {
+    title: '4 · Ship',
+    body: 'Hybrid CDN: wp deploy. Monolith: wp build --hubspot-only then wp upload.',
+  },
+] as const
+
+export const WOODSCLI_ABOUT = {
+  package: '@woodsportal/hubspot-kit',
+  tagline:
+    'WoodsCLI is WoodsPortal’s dev kit for HubSpot CMS modules and themes — Vite local preview, fields.json editing, CDN + module build pipelines, and HubSpot CLI integration.',
+  docsHint:
+    'Full command list and guides ship in node_modules/@woodsportal/hubspot-kit/docs/ (CLI-REFERENCE.md, MODULES.md, HUBSPOT-CLI-SETUP.md).',
+} as const
+
+export const STARTER_FEATURES = [
+  {
+    title: 'Module fields',
+    body: 'Content and Styles tabs mirror HubSpot’s module editor. Apply changes to refresh this preview.',
+  },
+  {
+    title: 'Local persistence',
+    body: 'Saved values land in .wphs/config/module-config.local.json — safe to gitignore.',
+  },
+  {
+    title: 'Ship when ready',
+    body: 'Run wp build and wp deploy when your module is ready for HubSpot.',
+  },
+] as const

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/hooks/starter-preview-values.ts

@@ -0,0 +1,60 @@
+export type StarterPreviewValues = {
+  title: string
+  tagline: string
+  showFeatureCards: boolean
+  heroStyle: 'gradient' | 'minimal' | 'bold'
+}
+
+function normalizeHeroStyle(raw: unknown): StarterPreviewValues['heroStyle'] {
+  const key = String(raw ?? 'gradient').toLowerCase()
+  if (key === 'minimal' || key === 'bold') return key
+  return 'gradient'
+}
+
+/** CONTENT-tab fields may live under a `content` group (fields.json) or flat legacy keys. */
+function readContentField(module: Record<string, unknown>, key: string): unknown {
+  const content = module.content
+  if (content && typeof content === 'object' && key in (content as Record<string, unknown>)) {
+    return (content as Record<string, unknown>)[key]
+  }
+  return module[key]
+}
+
+/** STYLE-tab fields may live under a `style` group (fields.json) or legacy `styles` / flat keys. */
+function readStyleField(module: Record<string, unknown>, key: string): unknown {
+  const style = module.style
+  if (style && typeof style === 'object' && key in (style as Record<string, unknown>)) {
+    return (style as Record<string, unknown>)[key]
+  }
+  const styles = module.styles
+  if (styles && typeof styles === 'object' && key in (styles as Record<string, unknown>)) {
+    return (styles as Record<string, unknown>)[key]
+  }
+  return module[key]
+}
+
+export function mapStarterPreviewValues(module: Record<string, unknown>): StarterPreviewValues {
+  return {
+    title: String(readContentField(module, 'title') ?? 'My HubSpot Portal'),
+    tagline: String(
+      readContentField(module, 'tagline') ??
+        'Customize this preview with Ctrl+Shift+Z, then replace this page with your portal app.',
+    ),
+    showFeatureCards: readContentField(module, 'show_feature_cards') !== false,
+    heroStyle: normalizeHeroStyle(readStyleField(module, 'hero_style')),
+  }
+}
+
+/** HubSpot module field blob on window (dev adapter + CMS runtime). */
+export function readStarterModuleFields(): Record<string, unknown> {
+  const win = window as Window & {
+    __WPHS_DATA__?: Record<string, unknown>
+    hubSpotData?: Record<string, unknown>
+  }
+  const blob = win.__WPHS_DATA__ ?? win.hubSpotData ?? {}
+  const nested = blob.module
+  if (nested && typeof nested === 'object') {
+    return nested as Record<string, unknown>
+  }
+  return blob
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/hooks/use-starter-preview.dev.ts

@@ -0,0 +1,18 @@
+import { MODULE_CONFIG_CHANGED } from '@/dev/module-config/schema/types'
+import { getModuleFieldValues } from '@/dev/module-config/runtime/module-config-runtime'
+
+import {
+  mapStarterPreviewValues,
+  type StarterPreviewValues,
+} from './starter-preview-values'
+
+/** Dev-only: refresh when module-config overlay applies changes. */
+export function subscribeStarterPreview(
+  onChange: (values: StarterPreviewValues) => void,
+): () => void {
+  const refresh = () => onChange(mapStarterPreviewValues(getModuleFieldValues()))
+
+  refresh()
+  window.addEventListener(MODULE_CONFIG_CHANGED, refresh)
+  return () => window.removeEventListener(MODULE_CONFIG_CHANGED, refresh)
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/hooks/use-starter-preview.ts

@@ -0,0 +1,30 @@
+import { useEffect, useState } from 'react'
+
+import {
+  mapStarterPreviewValues,
+  readStarterModuleFields,
+  type StarterPreviewValues,
+} from './starter-preview-values'
+
+/** Module field values for the starter preview (dev overlay + production window data). */
+export function useStarterPreview(): StarterPreviewValues {
+  const [values, setValues] = useState(() => mapStarterPreviewValues(readStarterModuleFields()))
+
+  useEffect(() => {
+    if (!import.meta.env.DEV) {
+      return
+    }
+
+    let unsubscribe = () => {}
+
+    void import('./use-starter-preview.dev').then(({ subscribeStarterPreview }) => {
+      unsubscribe = subscribeStarterPreview(setValues)
+    })
+
+    return () => unsubscribe()
+  }, [])
+
+  return values
+}
+
+export type { StarterPreviewValues } from './starter-preview-values'

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

@@ -0,0 +1,6 @@
+export { StarterHomePage } from './components/starter-home-page'
+export { StarterGuidePage } from './components/starter-guide-page'
+export { StarterSinglePage } from './components/starter-single-page'
+export { StarterHome } from './components/starter-home'
+export { useStarterPreview } from './hooks/use-starter-preview'
+export type { StarterPreviewValues } from './hooks/starter-preview-values'

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/hubspot/bootstrap.ts

@@ -0,0 +1,16 @@
+/**
+ * Thin HubSpot module.js bootstrap — JS app loads from CDN via require_js in module.html.
+ *
+ * CSS imports are extracted to module.css by the HubSpot Vite build (same pattern as
+ * digitalwoods.io-woodsportal-client-frontend). HubSpot CMS editor does not reliably
+ * load external jsDelivr stylesheets from module.html.
+ */
+import '@/assets/css/main.prod.css'
+
+declare global {
+  interface Window {
+    WoodsPortalHubSpotBootstrap?: { ready: true }
+  }
+}
+
+window.WoodsPortalHubSpotBootstrap = { ready: true }

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/hubspot/default-data.ts

@@ -0,0 +1,7 @@
+/** Local dev fixtures merged by the module-config runtime in `wp dev`. */
+export const devDefaultData = {
+  dataSourceSet: [],
+  hubId: 'dev',
+  userData: {},
+  objectList: [] as unknown[],
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/hubspot/is-cms-editor.ts

@@ -0,0 +1,78 @@
+declare global {
+  interface Window {
+    hsInEditor?: boolean
+    hsVars?: {
+      isEditor?: boolean
+      is_edit_mode?: boolean
+      [key: string]: unknown
+    }
+  }
+}
+
+function isInNestedIframe(): boolean {
+  if (typeof window === 'undefined') {
+    return false
+  }
+  return window.self !== window.top
+}
+
+function readHubSpotEditorFlag(): boolean {
+  if (typeof window === 'undefined') {
+    return false
+  }
+  if (window.hubSpotData?.isInEditor === true) {
+    return true
+  }
+  if (window.hsInEditor === true) {
+    return true
+  }
+  if (window.hsVars?.isEditor === true || window.hsVars?.is_edit_mode === true) {
+    return true
+  }
+  return false
+}
+
+function detectEditorFromUrlOrReferrer(): boolean {
+  if (typeof window === 'undefined') {
+    return false
+  }
+  try {
+    const href = window.location.href
+    if (/inpageeditor|page-editor|hs_editor|content-editor/i.test(href)) {
+      return true
+    }
+    if (isInNestedIframe() && /hs_preview|hsCacheBuster/i.test(href)) {
+      return true
+    }
+    const referrer = document.referrer ?? ''
+    if (
+      referrer &&
+      /hubspot\.(com|net)/i.test(referrer) &&
+      /editor|preview|content\/(page|site)/i.test(referrer)
+    ) {
+      return true
+    }
+  } catch {
+    // ignore
+  }
+  return false
+}
+
+export function isHubSpotCmsEditor(): boolean {
+  if (readHubSpotEditorFlag()) {
+    return true
+  }
+  if (detectEditorFromUrlOrReferrer()) {
+    return true
+  }
+  if (isInNestedIframe() && window.hubSpotData?.isInPreviewer === true) {
+    return true
+  }
+  return false
+}
+
+export function isEditorPreviewMode(): boolean {
+  return isHubSpotCmsEditor() && isInNestedIframe()
+}
+
+export {}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/hubspot/module-entry.tsx

@@ -0,0 +1,9 @@
+/**
+ * Monolith production entry — single IIFE `module.js` (wp build).
+ * Dev overlay uses `src/main.tsx` instead.
+ */
+import '@/assets/css/main.dev.css'
+
+import { mountPortal } from '@/portal/mount-portal'
+
+void mountPortal()

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/hubspot/types.ts

@@ -0,0 +1,17 @@
+/** Runtime contract for window.hubSpotData (greenfield stub). */
+export type HubSpotPortalData = {
+  dataSourceSet?: unknown
+  hubId?: string | number
+  apiBaseUrlOption?: string
+  userData?: unknown
+  objectList?: unknown[]
+  isInEditor?: boolean
+}
+
+declare global {
+  interface Window {
+    hubSpotData?: HubSpotPortalData
+  }
+}
+
+export {}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/integrations/configure-woodsportal-sdk.ts

@@ -0,0 +1,94 @@
+import type { LogLevel } from 'woodsportal-client-sdk'
+import {
+  initializeHttpClient,
+  isServiceUnavailableError,
+  setSessionLifecycleListener,
+} from '@/integrations/woodsportal-sdk'
+import { AUTH_SCAFFOLD_TIER } from '@/config/auth-tier'
+import { Routes } from '@/config/routes'
+import { syncSdkHubContextFromRuntime } from '@/data/sync-sdk-hub-context'
+import { resolveHubId } from '@/data/hubSpotContext'
+import { env } from '@/env'
+import { clearClientAuthSession } from '@/features/auth/clear-client-auth-session'
+import { AUTH_SESSION_CHANGED } from '@/features/auth/auth-session-events'
+import { skipCurrentPublicPath } from '@/utils/ValidationSchema'
+import { resolveWoodsPortalApiBaseUrl } from '@/utils/resolve-api-base-url'
+import { isHubSpotCmsEditor } from '@/hubspot/is-cms-editor'
+
+function resolveSdkLogLevel(): LogLevel {
+  const configured = import.meta.env.VITE_SDK_LOG_LEVEL as LogLevel | undefined
+  if (
+    configured === 'debug' ||
+    configured === 'info' ||
+    configured === 'warn' ||
+    configured === 'error' ||
+    configured === 'silent'
+  ) {
+    return configured
+  }
+  return import.meta.env.DEV ? 'debug' : 'info'
+}
+
+/**
+ * Configure woodsportal-client-sdk HTTP before any api.* call.
+ * Tier: {@link AUTH_SCAFFOLD_TIER} (patched by init-auth-scaffold).
+ */
+export function configureWoodsPortalSdk(): void {
+  syncSdkHubContextFromRuntime()
+  const resolvedHubId = resolveHubId()
+  const devPortalId =
+    import.meta.env.DEV && env.VITE_DEV_PORTAL_ID != null && env.VITE_DEV_PORTAL_ID !== ''
+      ? String(env.VITE_DEV_PORTAL_ID)
+      : undefined
+
+  setSessionLifecycleListener(() => {
+    if (typeof window !== 'undefined') {
+      window.dispatchEvent(new CustomEvent(AUTH_SESSION_CHANGED))
+    }
+  })
+
+  initializeHttpClient({
+    baseURL: resolveWoodsPortalApiBaseUrl(),
+    timeout: 50_000,
+    hubId: resolvedHubId != null ? String(resolvedHubId) : undefined,
+    devPortalId,
+    storageMode: isHubSpotCmsEditor() ? 'iframe' : 'cookie',
+    skipCurrentPublicPath,
+    shouldHandleUnauthorized: () => {
+      if (isHubSpotCmsEditor()) {
+        return false
+      }
+            return true
+    },
+    routes: {
+      unauthorized: Routes.unauthorized,
+      login: Routes.login,
+      twoFa: Routes.twoFa,
+      resendEmail: '/resend-email',
+    },
+    onLogout: () => {
+      clearClientAuthSession()
+    },
+    logger: {
+      level: resolveSdkLogLevel(),
+      httpTracing: true,
+    },
+    storageKeys: {
+      loginDetails: env.VITE_LOGIN_DETAILS,
+      refreshToken: env.VITE_REFRESH_TOKEN,
+      portal: env.VITE_PORTAL,
+      subscriptionType: env.VITE_SUBSCRIPTION_TYPE,
+      authUser: env.VITE_AUTH_USER_KEY,
+      pagination: env.VITE_PAGINATION_DATA,
+      routeMenu: env.VITE_ROUTE_MENU_CONFIG_KEY,
+      associationView: env.VITE_ASSOCIATION_VIEW_URL_KEY,
+    },
+    onServiceUnavailable: (error) => {
+      if (isServiceUnavailableError(error)) {
+        console.warn('[WoodsPortal] API unavailable', error)
+      }
+    },
+  })
+
+  void AUTH_SCAFFOLD_TIER
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/integrations/tanstack-query/root-provider.tsx

@@ -0,0 +1,18 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      refetchOnWindowFocus: false,
+      retry: false,
+    },
+  },
+})
+
+export function getContext() {
+  return { queryClient }
+}
+
+export function Provider({ children }: { children: React.ReactNode }) {
+  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/integrations/tanstack-router/router.tsx

@@ -0,0 +1,39 @@
+import {
+  createBrowserHistory,
+  createHashHistory,
+  createRouter,
+  type AnyRouter,
+} from '@tanstack/react-router'
+
+import { ROUTER_HISTORY } from '@/config/router'
+import * as TanStackQueryProvider from '@/integrations/tanstack-query/root-provider'
+import { routeTree } from '@/routeTree.gen'
+
+let routerInstance: AnyRouter | null = null
+
+export function getRouter(): AnyRouter {
+  if (!routerInstance) {
+    const history = ROUTER_HISTORY === 'hash' ? createHashHistory() : createBrowserHistory()
+    routerInstance = createRouter({
+      routeTree,
+      context: {
+        ...TanStackQueryProvider.getContext(),
+      },
+      history,
+      defaultPreload: 'intent',
+      scrollRestoration: true,
+      defaultStructuralSharing: true,
+      defaultPreloadStaleTime: 0,
+    })
+  }
+  return routerInstance
+}
+
+/** Eager router export for dev tooling. */
+export const router = getRouter()
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: ReturnType<typeof getRouter>
+  }
+}