@woodsportal/hubspot-kit 1.0.4 → 1.0.26

package/templates/module-hybrid-cdn/src/routes/index.tsx

@@ -0,0 +1,7 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+import { StarterHomePage } from '@/features/starter'
+
+export const Route = createFileRoute('/')({
+  component: StarterHomePage,
+})

package/templates/module-hybrid-cdn/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "jsx": "react-jsx",
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"],
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx", "wphs.adapter.ts"]
+}

package/templates/module-hybrid-cdn/vite.config.monolith.mjs

@@ -0,0 +1,8 @@
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+if (!process.env.WP_HS_PROJECT_ROOT?.trim()) {
+  process.env.WP_HS_PROJECT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)))
+}
+
+export { default } from '@woodsportal/hubspot-kit/vite/vite.config.monolith.mjs'

package/templates/module-monolith/README.md

@@ -0,0 +1,59 @@
+# Getting started
+
+This project was scaffolded with **WoodsCLI** (`@woodsportal/hubspot-kit`).
+
+## Daily dev
+
+```bash
+yarn install
+wp doctor
+wp dev
+```
+
+Open the local URL, then **Ctrl+Shift+Z** (Mac **⌃⇧Z**) to edit module fields. Click **Apply changes** to refresh the starter preview.
+
+## Routing (`wp init`)
+
+Default is **hash history** — same as `woodsportal-client-frontend` (`#/guide` URLs work in HubSpot CMS).
+
+| `wp init --router` | Behavior |
+|--------------------|----------|
+| `hash` (default) | `createHashHistory()` — production-safe in HubSpot embeds |
+| `browser` | Clean `/guide` URLs for local dev only |
+| `none` | Single-page starter, no TanStack Router |
+
+Recorded in `woodscli.json` → `scaffold.router`.
+
+## `src/` layout
+
+| Path | Purpose |
+|------|---------|
+| `main.tsx` | Dev entry — loads styles and `mountDevPreview()` |
+| `app.tsx` | `RouterProvider` shell (client-frontend pattern) |
+| `config/router.ts` | Hash vs browser history |
+| `portal/` | Dev vs production mount (`mount-dev-preview`, `mount-portal`) |
+| `routes/` | TanStack file routes — keep thin; import from `features/` |
+| `features/starter/` | Demo home + developer guide (replace with your app) |
+| `components/` | Shared layout and UI |
+| `integrations/` | Router and third-party wiring |
+| `hubspot/` | HubSpot types and dev fixtures |
+| `config/` | Route constants and app config |
+| `assets/css/` | Tailwind entry for local dev |
+
+Kit runtime expects `src/defaultData.ts` (re-exports `hubspot/default-data.ts`).
+
+## Docs (in the kit package)
+
+After `npm install`, see:
+
+- `node_modules/@woodsportal/hubspot-kit/docs/CLI-REFERENCE.md`
+- `node_modules/@woodsportal/hubspot-kit/docs/MODULES.md`
+- `node_modules/@woodsportal/hubspot-kit/docs/HUBSPOT-CLI-SETUP.md`
+
+## HubSpot upload
+
+```bash
+cp hubspot.config.yml.example hubspot.config.yml
+# add portal + personal access key
+wp upload
+```

package/templates/module-monolith/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>WoodsCLI dev preview</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/module-monolith/package.json

@@ -5,15 +5,22 @@
   "scripts": {
     "local": "wp dev",
     "doctor": "wp doctor",
+    "build:dev": "wp build --tier dev",
     "build:prod": "wp build --tier prod",
-    "deploy:prod": "wp deploy --tier prod"
+    "deploy:dev": "wp deploy --tier dev --yes",
+    "deploy:prod": "wp deploy --tier prod --yes",
+    "watch": "wp watch --rebuild"
   },
   "devDependencies": {
-    "@woodsportal/hubspot-kit": "^1.0.4",
+    "@woodsportal/hubspot-kit": "^1.0.11",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@tailwindcss/vite": "^4.0.6",
+    "@tanstack/react-router": "^1.121.2",
     "@tanstack/router-plugin": "^1.121.2",
     "@vitejs/plugin-react": "^4.3.4",
-    "babel-plugin-react-compiler": "^1.0.0",
+    "babel-plugin-react-compiler": "^1.0.11",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tailwindcss": "^4.0.6",

package/templates/module-monolith/public/fields.json

@@ -1 +1,44 @@
-[{"name":"title","label":"Title","type":"text","default":"WoodsCLI module"}]
+[
+  {
+    "name": "title",
+    "label": "Portal title",
+    "type": "text",
+    "tab": "CONTENT",
+    "default": "My HubSpot Portal"
+  },
+  {
+    "name": "tagline",
+    "label": "Tagline",
+    "type": "text",
+    "tab": "CONTENT",
+    "help_text": "Subtitle shown under the hero title in the local dev preview.",
+    "default": "Customize this preview with Ctrl+Shift+Z, then replace StarterPage with your portal app."
+  },
+  {
+    "name": "show_feature_cards",
+    "label": "Show feature cards",
+    "type": "boolean",
+    "display": "toggle",
+    "tab": "CONTENT",
+    "default": true
+  },
+  {
+    "name": "accent_color",
+    "label": "Accent color",
+    "type": "color",
+    "tab": "STYLE",
+    "default": { "color": "#0091ae", "opacity": 100 }
+  },
+  {
+    "name": "hero_style",
+    "label": "Hero style",
+    "type": "choice",
+    "tab": "STYLE",
+    "choices": [
+      ["gradient", "Gradient"],
+      ["minimal", "Minimal"],
+      ["bold", "Bold"]
+    ],
+    "default": "gradient"
+  }
+]

package/templates/module-monolith/public/module.html

@@ -0,0 +1 @@
+<div id="app"></div>

package/templates/module-monolith/src/app.tsx

@@ -0,0 +1,8 @@
+import { RouterProvider } from '@tanstack/react-router'
+
+import { router } from '@/integrations/tanstack-router/router'
+
+/** Root app shell — same pattern as woodsportal-client-frontend `App`. */
+export function App() {
+  return <RouterProvider router={router} />
+}

package/templates/module-monolith/src/assets/css/main.dev.css

@@ -1,3 +1,8 @@
 @import 'tailwindcss';
 
-@source '../../.wphs/**/*.{js,jsx,ts,tsx}';
+/* Kit dev-module-config — paths relative to this file (src/assets/css/) */
+@source '../../../.wphs/.kit-module-config/**/*.{ts,tsx}';
+@source '../../../.wphs/.kit-bootstrap.tsx';
+@source '../../../.wphs/.kit-bootstrap-greenfield.tsx';
+@source '../../../src/**/*.{ts,tsx}';
+@source '../../../node_modules/@woodsportal/hubspot-kit/src/dev-module-config/**/*.{ts,tsx}';

package/templates/module-monolith/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/templates/module-monolith/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/templates/module-monolith/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/templates/module-monolith/src/config/router.ts

@@ -0,0 +1,4 @@
+/** Router history — set by `wp init`. Hash matches woodsportal-client-frontend (HubSpot CMS embeds). */
+export type RouterHistoryMode = 'hash' | 'browser'
+
+export const ROUTER_HISTORY: RouterHistoryMode = 'hash'

package/templates/module-monolith/src/config/routes.ts

@@ -0,0 +1,5 @@
+/** Route paths — keep in sync with `src/routes/` file routes. */
+export const ROUTES = {
+  home: '/',
+  guide: '/guide',
+} as const

package/templates/module-monolith/src/defaultData.ts

@@ -1,7 +1,2 @@
-/** Local dev fixtures for module-config runtime (greenfield wp init). */
-export const defaultData = {
-  dataSourceSet: [],
-  hubId: 'dev',
-  userData: {},
-  objectList: [] as unknown[],
-}
+/** Kit runtime imports `@/defaultData` — re-export from the hubspot slice. */
+export { devDefaultData as defaultData } from './hubspot/default-data'

package/templates/module-monolith/src/features/starter/components/starter-guide-page.tsx

@@ -0,0 +1,93 @@
+import { SectionCard } from '@/components/layout/section-card'
+
+import {
+  DEV_WORKFLOW,
+  PROJECT_LAYOUT,
+  WOODSCLI_ABOUT,
+  WOODSCLI_COMMANDS,
+} from '../content/woodscli-guide-content'
+
+export function StarterGuidePage() {
+  return (
+    <main className="mx-auto max-w-4xl space-y-8 px-6 py-10 sm:px-10">
+      <div>
+        <h1 className="text-2xl font-semibold tracking-tight">Developer guide</h1>
+        <p className="mt-2 text-sm leading-relaxed text-[#516f90]">
+          Commands, project layout, and workflow for this WoodsCLI module. Routes live in{' '}
+          <code className="font-mono text-xs">src/routes/</code> and delegate to{' '}
+          <code className="font-mono text-xs">src/features/</code>.
+        </p>
+      </div>
+
+      <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="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">
+          {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">
+        <p className="text-sm leading-relaxed text-[#516f90]">
+          This starter uses the same TanStack Router setup as{' '}
+          <code className="font-mono text-xs">woodsportal-client-frontend</code>: file routes under{' '}
+          <code className="font-mono text-xs">src/routes/</code>,{' '}
+          <code className="font-mono text-xs">src/app.tsx</code> with{' '}
+          <code className="font-mono text-xs">RouterProvider</code>, and{' '}
+          <strong>hash history</strong> by default (
+          <code className="font-mono text-xs">src/config/router.ts</code>) so routes work inside
+          HubSpot CMS embeds. Run <code className="font-mono text-xs">wp init</code> again on a new
+          folder to choose browser history or no router. Add{' '}
+          <code className="font-mono text-xs">src/routes/about.tsx</code> and restart{' '}
+          <code className="font-mono text-xs">wp dev</code> to regenerate{' '}
+          <code className="font-mono text-xs">routeTree.gen.ts</code>.
+        </p>
+      </SectionCard>
+
+      <SectionCard title="Customize this preview">
+        <p className="text-sm leading-relaxed text-[#516f90]">
+          Edit <code className="font-mono text-xs">public/fields.json</code> to add module fields,
+          then adjust <code className="font-mono text-xs">src/features/starter/</code> to bind them.
+          Replace the starter feature with your own under{' '}
+          <code className="font-mono text-xs">src/features/</code> when you outgrow the demo.
+        </p>
+      </SectionCard>
+    </main>
+  )
+}

package/templates/module-monolith/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/templates/module-monolith/src/features/starter/components/starter-home.tsx

@@ -0,0 +1,52 @@
+import { useStarterPreview } from '../hooks/use-starter-preview'
+import { STARTER_FEATURES, WOODSCLI_ABOUT } from '../content/woodscli-guide-content'
+
+function heroClass(style: ReturnType<typeof useStarterPreview>['heroStyle']): string {
+  if (style === 'minimal') {
+    return 'bg-[var(--mc-bg-shell,#f5f8fa)] text-[var(--mc-text,#33475b)] border-b border-[var(--mc-border,#cbd6e2)]'
+  }
+  if (style === 'bold') {
+    return 'bg-[#1c1c1f] text-white'
+  }
+  return 'bg-gradient-to-br from-[var(--starter-accent,#0091ae)] to-[#ff7a59] text-white'
+}
+
+export function StarterHome() {
+  const { title, tagline, showFeatureCards, accentColor, heroStyle } = useStarterPreview()
+
+  return (
+    <>
+      <div style={{ ['--starter-accent' as string]: accentColor }}>
+        <section className={`px-6 py-14 sm:px-10 sm:py-16 ${heroClass(heroStyle)}`}>
+          <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>
+      </div>
+
+      {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-[#0091ae]">{feature.title}</h2>
+              <p className="mt-2 text-sm leading-relaxed text-[#516f90]">{feature.body}</p>
+            </article>
+          ))}
+        </div>
+      ) : null}
+    </>
+  )
+}

package/templates/module-monolith/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/templates/module-monolith/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 adopt',
+    desc: 'Add woodscli.json + .wphs/ to an existing module or theme repo.',
+  },
+  {
+    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. Advanced apps: wp adopt on woodsportal-client-frontend.',
+  },
+] 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, or wp adopt to merge into the full WoodsPortal client app.',
+  },
+] as const

package/templates/module-monolith/src/features/starter/hooks/starter-preview-values.ts

@@ -0,0 +1,42 @@
+export type StarterPreviewValues = {
+  title: string
+  tagline: string
+  showFeatureCards: boolean
+  accentColor: string
+  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'
+}
+
+export function mapStarterPreviewValues(module: Record<string, unknown>): StarterPreviewValues {
+  const accent = module.accent_color as { color?: string } | undefined
+
+  return {
+    title: String(module.title ?? 'My HubSpot Portal'),
+    tagline: String(
+      module.tagline ??
+        'Customize this preview with Ctrl+Shift+Z, then replace this page with your portal app.',
+    ),
+    showFeatureCards: module.show_feature_cards !== false,
+    accentColor: accent?.color ?? '#0091ae',
+    heroStyle: normalizeHeroStyle(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/templates/module-monolith/src/features/starter/hooks/use-starter-preview.dev.ts

@@ -0,0 +1,17 @@
+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()))
+
+  window.addEventListener(MODULE_CONFIG_CHANGED, refresh)
+  return () => window.removeEventListener(MODULE_CONFIG_CHANGED, refresh)
+}