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

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

@@ -0,0 +1,210 @@
+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,
+  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>
+        </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-sso/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-sso/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-sso/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>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-sso/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-sso/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-sso/src/features/starter/content/auth-guide-content.ts

@@ -0,0 +1,85 @@
+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 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-sso/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-sso/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-sso/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-sso/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'