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

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/auth/login-email-storage.ts

@@ -0,0 +1,64 @@
+import { WP_STORAGE_KEYS } from 'woodsportal-client-sdk'
+
+const LOGIN_EMAIL_KEY = WP_STORAGE_KEYS.c.login.email
+
+function isValidEmail(value: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim())
+}
+
+export function extractLoginEmailFromPayload(
+  payload: Record<string, unknown> | null | undefined,
+): string | null {
+  if (!payload || typeof payload !== 'object') {
+    return null
+  }
+  const loggedInDetails = payload.loggedInDetails
+  if (loggedInDetails && typeof loggedInDetails === 'object') {
+    const email = (loggedInDetails as Record<string, unknown>).email
+    if (typeof email === 'string' && isValidEmail(email)) {
+      return email.trim().toLowerCase()
+    }
+  }
+  for (const key of ['email', 'username'] as const) {
+    const value = payload[key]
+    if (typeof value === 'string' && isValidEmail(value)) {
+      return value.trim().toLowerCase()
+    }
+  }
+  return null
+}
+
+export function captureLoginEmailBeforeSessionClear(
+  resolveLoggedInEmail?: () => string | null | undefined,
+): void {
+  if (getStoredLoginEmail()) {
+    return
+  }
+  const email = resolveLoggedInEmail?.()
+  if (email) {
+    setStoredLoginEmail(email)
+  }
+}
+
+export function getStoredLoginEmail(): string | null {
+  if (typeof window === 'undefined') {
+    return null
+  }
+  const stored = sessionStorage.getItem(LOGIN_EMAIL_KEY)?.trim().toLowerCase() ?? ''
+  return stored && isValidEmail(stored) ? stored : null
+}
+
+export function setStoredLoginEmail(email: string): void {
+  if (typeof window === 'undefined') {
+    return
+  }
+  const normalized = email.trim().toLowerCase()
+  if (!isValidEmail(normalized)) {
+    return
+  }
+  sessionStorage.setItem(LOGIN_EMAIL_KEY, normalized)
+}
+
+export function clearLoginPreAuthSession(): void {
+  // starter scaffold: no pre-login passkey state
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/auth/login-session-bridge.ts

@@ -0,0 +1,72 @@
+import { api } from '@/integrations/woodsportal-sdk'
+import {
+  navigateAfterFullAuth,
+  type AuthNavigationRouter,
+} from '@/features/auth/auth-navigation'
+import { resolvePostLoginPath } from '@/features/auth/resolve-post-login-path'
+import { AUTH_SESSION_CHANGED } from '@/features/auth/auth-session-events'
+import { signalSessionChanged } from 'woodsportal-client-sdk'
+import {
+  extractLoginEmailFromPayload,
+  setStoredLoginEmail,
+} from '@/features/auth/login-email-storage'
+
+function notifyAuthSessionChanged(): void {
+  if (typeof window === 'undefined') return
+  signalSessionChanged('login')
+  window.dispatchEvent(new CustomEvent(AUTH_SESSION_CHANGED))
+}
+
+type AuthRouter = AuthNavigationRouter
+
+function unwrapLoginPayload(
+  response: { data?: Record<string, unknown>; statusMsg?: string } | Record<string, unknown>,
+): Record<string, unknown> {
+  return (response?.data ?? response ?? {}) as Record<string, unknown>
+}
+
+export type HandleAuthLoginResponseOptions = {
+  clearPreHashQuery?: () => void
+  onSubscriptionType?: (subscriptionType: string) => void
+}
+
+export type HandleAuthLoginResponseResult =
+  | { success: false; reason: 'no_token' | 'mfa_required' }
+  | { success: true; mfaRequired: true }
+  | { success: true; mfaRequired: false }
+
+/** Shown when the hub requires MFA but the project used `--auth starter` or `sso`. */
+export const MFA_REQUIRED_SCAFFOLD_MESSAGE =
+  'This hub requires MFA. Re-init with wp init --auth full (see docs/AUTH-SCAFFOLD.md).'
+
+export async function handleAuthLoginResponse(
+  response: { data?: Record<string, unknown>; statusMsg?: string } | Record<string, unknown>,
+  router: AuthRouter,
+  options: HandleAuthLoginResponseOptions = {},
+): Promise<HandleAuthLoginResponseResult> {
+  const data = unwrapLoginPayload(response)
+  const tokenData = (data.tokenData ?? {}) as { token?: string }
+  const sessionToken = api.auth.session.getAccessToken()
+  const token = tokenData.token ?? sessionToken ?? undefined
+
+  if (!token) {
+    return { success: false, reason: 'no_token' }
+  }
+
+  const loginEmail = extractLoginEmailFromPayload(data)
+  if (loginEmail) {
+    setStoredLoginEmail(loginEmail)
+  }
+
+  if (data.twoFactorRequired === true) {
+    return { success: false, reason: 'mfa_required' }
+  }
+
+  const loggedInDetails = (data.loggedInDetails ?? {}) as { subscriptionType?: string }
+  options.onSubscriptionType?.(loggedInDetails.subscriptionType ?? 'BASIC')
+
+  options.clearPreHashQuery?.()
+  notifyAuthSessionChanged()
+  navigateAfterFullAuth(router, resolvePostLoginPath(router))
+  return { success: true, mfaRequired: false }
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/auth/post-login-path.ts

@@ -0,0 +1,17 @@
+import { Routes } from '@/config/routes'
+import { normalizeRouterPath } from '@/utils/normalize-router-path'
+
+const AUTH_RETURN_PATHS = new Set<string>([
+  Routes.login,
+  Routes.twoFa,
+  Routes.unauthorized,
+  Routes.ssoLogin,
+])
+
+export function isBlockedPostLoginPath(path: string): boolean {
+  const normalized = normalizeRouterPath(path)
+  if (AUTH_RETURN_PATHS.has(normalized)) {
+    return true
+  }
+  return normalized.startsWith('/login')
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/auth/resolve-auth-login-error-message.ts

@@ -0,0 +1,52 @@
+const GENERIC_AUTH_FAILED_MESSAGES = new Set([
+  'Authentication Failed',
+  'Invalid credentials provided.',
+])
+
+type LoginErrorPayload = {
+  errorCode?: unknown
+  errorMessage?: unknown
+  validationErrors?: unknown
+}
+
+function extractFirstValidationMessage(validationErrors: unknown): string | null {
+  if (validationErrors == null || typeof validationErrors !== 'object') {
+    return null
+  }
+  const first = Object.values(validationErrors as Record<string, unknown>)[0]
+  if (typeof first === 'string') {
+    return first
+  }
+  if (Array.isArray(first) && typeof first[0] === 'string') {
+    return first[0]
+  }
+  return null
+}
+
+export function resolveAuthLoginErrorMessage(error: unknown): string {
+  const fallback = 'Wrong email or password'
+  if (error == null || typeof error !== 'object') {
+    return fallback
+  }
+  const data = (error as { response?: { data?: LoginErrorPayload } }).response?.data
+  if (!data) {
+    return fallback
+  }
+  const validationMessage = extractFirstValidationMessage(data.validationErrors)
+  if (validationMessage) {
+    return validationMessage
+  }
+  const errorCode = typeof data.errorCode === 'string' ? data.errorCode : undefined
+  const errorMessage =
+    typeof data.errorMessage === 'string' ? data.errorMessage.trim() : ''
+  if (!errorMessage) {
+    return fallback
+  }
+  if (
+    errorCode === 'AUTHENTICATION_FAILED' &&
+    GENERIC_AUTH_FAILED_MESSAGES.has(errorMessage)
+  ) {
+    return fallback
+  }
+  return errorMessage
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/auth/resolve-post-login-path.ts

@@ -0,0 +1,21 @@
+import { Routes } from '@/config/routes'
+import { isBlockedPostLoginPath } from '@/features/auth/post-login-path'
+import { normalizeRouterPath } from '@/utils/normalize-router-path'
+import type { SafeAuthRouter } from '@/utils/safe-router-navigation'
+
+export type PostLoginRouter = SafeAuthRouter & {
+  state: {
+    location?: {
+      search?: { r?: string; [key: string]: string | undefined }
+      pathname?: string
+    }
+  }
+}
+
+export function resolvePostLoginPath(router: PostLoginRouter): string {
+  const redirect = router.state.location?.search?.r
+  if (redirect && !isBlockedPostLoginPath(String(redirect))) {
+    return normalizeRouterPath(String(redirect))
+  }
+  return Routes.portal
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/auth/use-portal-session.ts

@@ -0,0 +1,25 @@
+import { useEffect, useMemo, useState } from 'react'
+import { AUTH_SESSION_CHANGED } from '@/features/auth/auth-session-events'
+import { isFullyAuthenticatedSession, isMfaPendingSession } from '@/features/auth/auth-session'
+
+function useAuthSessionRevision(): number {
+  const [revision, setRevision] = useState(0)
+  useEffect(() => {
+    const bump = () => setRevision((value) => value + 1)
+    window.addEventListener(AUTH_SESSION_CHANGED, bump)
+    return () => window.removeEventListener(AUTH_SESSION_CHANGED, bump)
+  }, [])
+  return revision
+}
+
+export { useAuthSessionRevision }
+
+export function usePortalSession(): boolean {
+  const revision = useAuthSessionRevision()
+  return useMemo(() => isFullyAuthenticatedSession(), [revision])
+}
+
+export function useIsMfaPendingSession(): boolean {
+  const revision = useAuthSessionRevision()
+  return useMemo(() => isMfaPendingSession(), [revision])
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/auth/use-signed-in-email.ts

@@ -0,0 +1,55 @@
+import { useEffect, useState } from 'react'
+
+import { api } from '@/integrations/woodsportal-sdk'
+import { getStoredLoginEmail } from '@/features/auth/login-email-storage'
+import { usePortalSession } from '@/features/auth/use-portal-session'
+
+function readEmailFromProfile(data: unknown): string | null {
+  if (data == null || typeof data !== 'object') {
+    return null
+  }
+  const root = data as Record<string, unknown>
+  const profile = (root.data ?? root) as Record<string, unknown>
+  const email = profile.email
+  return typeof email === 'string' && email.trim() !== '' ? email.trim() : null
+}
+
+export function useSignedInEmail(): { email: string | null; isLoading: boolean } {
+  const isAuthenticated = usePortalSession()
+  const [email, setEmail] = useState<string | null>(() => getStoredLoginEmail())
+  const [isLoading, setIsLoading] = useState(false)
+
+  useEffect(() => {
+    if (!isAuthenticated) {
+      setEmail(null)
+      setIsLoading(false)
+      return
+    }
+
+    const stored = getStoredLoginEmail()
+    if (stored) {
+      setEmail(stored)
+      return
+    }
+
+    setIsLoading(true)
+    const { me } = api.auth.me({
+      onSuccess: (data) => {
+        setEmail(readEmailFromProfile(data) ?? getStoredLoginEmail())
+        setIsLoading(false)
+      },
+      onError: () => {
+        setEmail(getStoredLoginEmail())
+        setIsLoading(false)
+      },
+      onLoadingChange: (loading) => {
+        if (!loading) {
+          setIsLoading(false)
+        }
+      },
+    })
+    void me()
+  }, [isAuthenticated])
+
+  return { email, isLoading }
+}

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

@@ -0,0 +1,218 @@
+import { SectionCard } from '@/components/layout/section-card'
+import { Link } from '@/components/ui/link'
+import { AUTH_SCAFFOLD_TIER } from '@/config/auth-tier'
+import { NAV_SCAFFOLD_MODE } from '@/config/nav-scaffold'
+import { Routes } from '@/config/routes'
+import {
+  AUTH_BOOT_STEPS,
+  AUTH_ENV_VARS,
+  AUTH_INIT_EXAMPLES,
+  AUTH_NAV_EXAMPLES,
+  PAGE_SCAFFOLD_EXAMPLES,
+  AUTH_PROJECT_PATHS,
+  AUTH_TIER_DESCRIPTION,
+  PORTAL_AUTH_VS_HUBSPOT,
+  authRoutesForTier,
+} from '@/features/starter/content/auth-guide-content'
+import {
+  DEV_WORKFLOW,
+  PROJECT_LAYOUT,
+  WOODSCLI_ABOUT,
+  WOODSCLI_COMMANDS,
+} from '@/features/starter/content/woodscli-guide-content'
+import { StarterPageFrame } from '@/features/starter/components/starter-page-frame'
+
+export function StarterGuidePage() {
+  const tier = AUTH_SCAFFOLD_TIER
+  const routes = authRoutesForTier(tier)
+
+  return (
+    <StarterPageFrame
+      className="max-w-4xl"
+      title="Developer guide"
+      description={
+        <>
+          WoodsCLI module with portal auth (<strong>{tier}</strong> tier). Use this page for
+          commands, project layout, and auth wiring — then replace the starter features with your CRM
+          UI under <code className="rounded bg-gray-100 px-1 text-xs">src/features/</code>.
+        </>
+      }
+    >
+      <div className="space-y-6">
+        <SectionCard title={`Portal auth — ${tier} tier`}>
+          <p className="text-sm leading-relaxed text-[#516f90]">{AUTH_TIER_DESCRIPTION[tier]}</p>
+          <ul className="mt-4 list-disc space-y-2 pl-5 text-sm text-[#516f90]">
+            <li>
+              <Link to={Routes.login}>Sign in</Link> at <code className="font-mono text-xs">/#/login</code>{' '}
+              (posts <code className="font-mono text-xs">username</code> + password to{' '}
+              <code className="font-mono text-xs">/api/auth/login</code>).
+            </li>
+            <li>
+              After login, visit the protected sample at{' '}
+              <Link to={Routes.portal}>/portal</Link> — session + profile via{' '}
+              <code className="font-mono text-xs">GET /api/auth/me</code>.
+            </li>
+            <li>
+              Set <code className="font-mono text-xs">VITE_PUBLIC_REST_API_ENDPOINT</code> in{' '}
+              <code className="font-mono text-xs">.env.local</code> after{' '}
+              <code className="font-mono text-xs">wp setup</code>.
+            </li>
+          </ul>
+          <p className="mt-4 text-xs text-[#516f90]">
+            Re-scaffold:{' '}
+            <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono">{AUTH_INIT_EXAMPLES[tier]}</code>
+          </p>
+        </SectionCard>
+
+        <SectionCard title={`Navigation — ${NAV_SCAFFOLD_MODE} shell`}>
+          <p className="text-sm leading-relaxed text-[#516f90]">
+            Menu links come from{' '}
+            <code className="rounded bg-gray-100 px-1 text-xs">src/config/portal-nav.ts</code> — edit
+            once for both top nav and sidebar layouts.
+          </p>
+          <p className="mt-4 text-xs text-[#516f90]">
+            Sidebar init:{' '}
+            <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono">
+              {AUTH_NAV_EXAMPLES.sidebar}
+            </code>
+          </p>
+          <ul className="mt-4 space-y-2 text-xs text-[#516f90]">
+            {PAGE_SCAFFOLD_EXAMPLES.map((cmd) => (
+              <li key={cmd}>
+                <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono">{cmd}</code>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Auth routes (this tier)">
+          <ul className="divide-y divide-[#eaf0f6]">
+            {routes.map(({ path, access }) => (
+              <li key={path} className="flex flex-col gap-1 py-3 first:pt-0 last:pb-0 sm:flex-row sm:gap-4">
+                <code className="shrink-0 rounded bg-[#eaf0f6] px-2 py-1 font-mono text-xs text-[#0091ae]">
+                  {path}
+                </code>
+                <span className="text-sm leading-relaxed text-[#516f90]">{access}</span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Two auth concepts">
+          <ul className="space-y-4">
+            {PORTAL_AUTH_VS_HUBSPOT.map(({ label, cmds, purpose }) => (
+              <li key={label}>
+                <h3 className="text-sm font-medium text-[#33475b]">{label}</h3>
+                <p className="mt-1 font-mono text-xs text-[#0091ae]">{cmds}</p>
+                <p className="mt-1 text-sm leading-relaxed text-[#516f90]">{purpose}</p>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Environment (.env.local)">
+          <ul className="space-y-3">
+            {AUTH_ENV_VARS.map(({ name, note }) => (
+              <li key={name} className="text-sm leading-relaxed">
+                <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono text-xs text-[#33475b]">
+                  {name}
+                </code>
+                <span className="mt-1 block text-[#516f90] sm:mt-0 sm:inline sm:before:content-['—_']">
+                  {note}
+                </span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Session boot order">
+          <ol className="list-decimal space-y-2 pl-5 text-sm leading-relaxed text-[#516f90]">
+            {AUTH_BOOT_STEPS.map((step) => (
+              <li key={step}>{step}</li>
+            ))}
+          </ol>
+        </SectionCard>
+
+        <SectionCard title="About WoodsCLI">
+          <p className="text-sm leading-relaxed text-[#516f90]">{WOODSCLI_ABOUT.tagline}</p>
+          <p className="mt-3 text-sm leading-relaxed text-[#516f90]">{WOODSCLI_ABOUT.docsHint}</p>
+        </SectionCard>
+
+        <SectionCard title="Essential commands">
+          <ul className="divide-y divide-[#eaf0f6]">
+            {WOODSCLI_COMMANDS.map(({ cmd, desc }) => (
+              <li key={cmd} className="flex flex-col gap-1 py-3 first:pt-0 last:pb-0 sm:flex-row sm:gap-4">
+                <code className="shrink-0 rounded bg-[#eaf0f6] px-2 py-1 font-mono text-xs text-[#0091ae]">
+                  {cmd}
+                </code>
+                <span className="text-sm leading-relaxed text-[#516f90]">{desc}</span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Auth-related paths">
+          <ul className="space-y-3">
+            {AUTH_PROJECT_PATHS.map(({ path, note }) => (
+              <li key={path} className="text-sm leading-relaxed">
+                <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono text-xs text-[#33475b]">
+                  {path}
+                </code>
+                <span className="mt-1 block text-[#516f90] sm:mt-0 sm:inline sm:before:content-['—_']">
+                  {note}
+                </span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Project layout">
+          <ul className="space-y-3">
+            {PROJECT_LAYOUT.map(({ path, note }) => (
+              <li key={path} className="text-sm leading-relaxed">
+                <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono text-xs text-[#33475b]">
+                  {path}
+                </code>
+                <span className="mt-1 block text-[#516f90] sm:mt-0 sm:inline sm:before:content-['—_']">
+                  {note}
+                </span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Developer workflow">
+          <ol className="space-y-4">
+            <li>
+              <h3 className="text-sm font-medium text-[#33475b]">0 · Verify portal login</h3>
+              <p className="mt-1 text-sm leading-relaxed text-[#516f90]">
+                Run <code className="font-mono text-xs">wp dev</code>, open{' '}
+                <Link to={Routes.login}>/#/login</Link>, and confirm you reach{' '}
+                <Link to={Routes.portal}>/portal</Link> with an active session before building CRM
+                features.
+              </p>
+            </li>
+            {DEV_WORKFLOW.map(({ title: stepTitle, body }) => (
+              <li key={stepTitle}>
+                <h3 className="text-sm font-medium text-[#33475b]">{stepTitle}</h3>
+                <p className="mt-1 text-sm leading-relaxed text-[#516f90]">{body}</p>
+              </li>
+            ))}
+          </ol>
+        </SectionCard>
+
+        <SectionCard title="Routing & customization">
+          <p className="text-sm leading-relaxed text-[#516f90]">
+            File routes live under <code className="font-mono text-xs">src/routes/</code> and delegate
+            to <code className="font-mono text-xs">src/features/</code>. Hash history is the default
+            for HubSpot CMS embeds. Add protected routes with{' '}
+            <code className="font-mono text-xs">beforeLoad: {'() => ({ requiresAuth: true })'}</code>.
+            Replace <code className="font-mono text-xs">src/features/starter/</code> when you outgrow
+            the demo. Kit docs:{' '}
+            <code className="font-mono text-xs">node_modules/@woodsportal/hubspot-kit/docs/AUTH-SCAFFOLD.md</code>.
+          </p>
+        </SectionCard>
+      </div>
+    </StarterPageFrame>
+  )
+}

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

@@ -0,0 +1,21 @@
+import { Link } from '@tanstack/react-router'
+
+import { ROUTES } from '@/config/routes'
+
+import { StarterHome } from './starter-home'
+
+export function StarterHomePage() {
+  return (
+    <>
+      <StarterHome />
+      <div className="mx-auto max-w-4xl px-6 pb-10 sm:px-10">
+        <Link
+          to={ROUTES.guide}
+          className="inline-flex items-center rounded-md bg-[#0091ae] px-4 py-2 text-sm font-semibold text-white shadow-sm hover:bg-[#007a8c]"
+        >
+          Open developer guide →
+        </Link>
+      </div>
+    </>
+  )
+}

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

@@ -0,0 +1,48 @@
+import { useStarterPreview } from '../hooks/use-starter-preview'
+import { STARTER_FEATURES, WOODSCLI_ABOUT } from '../content/woodscli-guide-content'
+
+export function StarterHome() {
+  const { title, tagline, showFeatureCards, heroStyle } = useStarterPreview()
+
+  return (
+    <>
+      <section
+        className={
+          heroStyle === 'minimal'
+            ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[var(--mc-bg-shell,#f5f8fa)] text-[var(--mc-text,#33475b)] border-b border-[var(--mc-border,#cbd6e2)]'
+            : heroStyle === 'bold'
+              ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[#1c1c1f] text-white'
+              : 'px-6 py-14 sm:px-10 sm:py-16 bg-gradient-to-br from-[var(--primary-color,#FF7A59)] to-[var(--secondary-color,#2797AF)] text-white'
+        }
+      >
+        <div className="mx-auto max-w-4xl">
+          <p className="mb-2 text-xs font-semibold uppercase tracking-widest opacity-80">
+            {WOODSCLI_ABOUT.package} · local dev
+          </p>
+          <h1 className="text-3xl font-semibold tracking-tight sm:text-4xl">{title}</h1>
+          <p className="mt-4 max-w-2xl text-base leading-relaxed opacity-90 sm:text-lg">{tagline}</p>
+          <p className="mt-6 text-sm opacity-75">
+            Module config overlay:{' '}
+            <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">Ctrl+Shift+Z</kbd>
+            {' · '}
+            Mac: <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">⌃⇧Z</kbd>
+          </p>
+        </div>
+      </section>
+
+      {showFeatureCards ? (
+        <div className="mx-auto grid max-w-4xl gap-4 px-6 py-10 sm:grid-cols-3 sm:px-10">
+          {STARTER_FEATURES.map((feature) => (
+            <article
+              key={feature.title}
+              className="rounded-lg border border-[#cbd6e2] bg-white p-5 shadow-sm"
+            >
+              <h2 className="text-sm font-semibold text-[var(--primary-color,#FF7A59)]">{feature.title}</h2>
+              <p className="mt-2 text-sm leading-relaxed text-[#516f90]">{feature.body}</p>
+            </article>
+          ))}
+        </div>
+      ) : null}
+    </>
+  )
+}

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

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react'
+
+type StarterPageFrameProps = {
+  title: string
+  description?: ReactNode
+  children?: ReactNode
+  className?: string
+}
+
+export function StarterPageFrame({
+  title,
+  description,
+  children,
+  className = 'max-w-2xl',
+}: StarterPageFrameProps) {
+  return (
+    <div className={`mx-auto space-y-4 ${className}`}>
+      <div>
+        <h1 className="text-2xl font-semibold text-gray-900">{title}</h1>
+        {description ? <p className="mt-2 text-gray-600">{description}</p> : null}
+      </div>
+      {children}
+    </div>
+  )
+}