create-vexcms 0.1.0-alpha.20 → 0.1.0-alpha.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-vexcms",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.22",
   "description": "Scaffold a new VexCMS project",
   "keywords": [
     "cms",
@@ -51,7 +51,7 @@
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts",
-    "dev": "tsup src/index.ts --format esm --watch",
+    "dev": "tsup src/index.ts --format esm --watch src",
     "test": "vitest run"
   }
 }

package/templates/base-nextjs/package.json

@@ -24,11 +24,11 @@
     "@t3-oss/env-nextjs": "0.13.11",
     "@tanstack/react-form": "1.33.1",
     "@tanstack/react-query": "5.101.2",
-    "@vexcms/better-auth": "~0.1.0-alpha.20",
-    "@vexcms/core": "~0.1.0-alpha.20",
-    "@vexcms/file-storage-convex": "~0.1.0-alpha.20",
-    "@vexcms/next": "~0.1.0-alpha.20",
-    "@vexcms/react": "~0.1.0-alpha.20",
+    "@vexcms/better-auth": "~0.1.0-alpha.22",
+    "@vexcms/core": "~0.1.0-alpha.22",
+    "@vexcms/file-storage-convex": "~0.1.0-alpha.22",
+    "@vexcms/next": "~0.1.0-alpha.22",
+    "@vexcms/react": "~0.1.0-alpha.22",
     "better-auth": "1.6.23",
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
@@ -52,7 +52,7 @@
     "@types/node": "20.19.43",
     "@types/react": "19.2.17",
     "@types/react-dom": "19.2.3",
-    "@vexcms/cli": "~0.1.0-alpha.20",
+    "@vexcms/cli": "~0.1.0-alpha.22",
     "babel-plugin-react-compiler": "1.0.0",
     "eslint": "9.39.5",
     "eslint-config-next": "15.5.9",

package/templates/marketing-site/src/app/(frontend)/(site)/PageContent.tsx

@@ -2,15 +2,22 @@
 
 import { convexQuery } from "@convex-dev/react-query"
 import { api } from "@convex/_generated/api"
-import { useQuery } from "@tanstack/react-query"
-import { RenderBlocks } from "@vexcms/react"
+import { RenderBlocks, useLivePreviewQuery } from "@vexcms/react"
 
+import type { CodeHighlightMap } from "~/lib/highlight"
 import type { PagesDocument } from "~/vex.types"
 
+import { CodeHighlightProvider } from "~/components/CodeHighlightContext"
 import { WelcomePage } from "~/components/WelcomePage"
 import { blockComponents } from "~/vexcms/blocks"
 
 export interface PageContentProps {
+  /**
+   * Server-highlighted code panes for `initialData`, keyed by
+   * `codeHighlightKey`. Built by `highlightPageBlocks`, because nothing below
+   * this client boundary can await shiki.
+   */
+  codeHighlights?: CodeHighlightMap
   /** Server-fetched `pages.getBySlug` result, hydrated as the query's initial data. */
   initialData?: PagesDocument[]
   /** URL slug to render. Omit (or empty) for the home page. */
@@ -23,17 +30,20 @@ export interface PageContentProps {
  * exists yet — a fresh scaffold before `pnpm seed` has run (Contract 3).
  *
  * `pages.getBySlug` always returns an array (empty when no match — the same
- * shape every collection query returns), so this always reads `pages?.[0]`.
+ * shape every collection query returns); `useLivePreviewQuery` performs that
+ * narrowing itself and overlays any unsaved editor values for this document
+ * when the page is being rendered inside a live preview.
  */
-export function PageContent({ slug, initialData }: PageContentProps) {
+export function PageContent({ codeHighlights, slug, initialData }: PageContentProps) {
   const normalizedSlug = slug && slug.length > 0 ? slug : "home"
 
-  const { data: pages, isPending } = useQuery({
-    ...convexQuery(api.pages.getBySlug, { slug: normalizedSlug }),
-    initialData,
-  })
-
-  const page = pages?.[0]
+  const { data: page, isPending } = useLivePreviewQuery(
+    {
+      ...convexQuery(api.pages.getBySlug, { slug: normalizedSlug }),
+      initialData,
+    },
+    "pages",
+  )
 
   if (isPending && initialData === undefined) {
     return null
@@ -44,9 +54,11 @@ export function PageContent({ slug, initialData }: PageContentProps) {
   }
 
   return (
-    <RenderBlocks
-      blocks={page.blocks}
-      components={blockComponents}
-    />
+    <CodeHighlightProvider highlights={codeHighlights ?? {}}>
+      <RenderBlocks
+        blocks={page.blocks}
+        components={blockComponents}
+      />
+    </CodeHighlightProvider>
   )
 }

package/templates/marketing-site/src/app/(frontend)/(site)/SiteLivePreviewProvider.tsx

@@ -0,0 +1,31 @@
+"use client"
+
+import type { ReactNode } from "react"
+
+import { LivePreviewProvider } from "@vexcms/react"
+
+import config from "~/vex.config"
+
+/**
+ * Mounts the live-preview listener for the public site's client tree.
+ *
+ * A `"use client"` component so `vex.config` is imported and owned on the
+ * client — it never crosses the RSC boundary as a prop (ADR-013; the config's
+ * `admin.livePreview.url` resolvers and field validators are functions, which
+ * React refuses to serialize). Mirrors `admin/clientProviders.tsx`.
+ *
+ * `LivePreviewProvider` gates itself on `?vexLivePreview=1` plus the
+ * session-verified `vex-live-preview` cookie `proxy.ts` sets, so wrapping the
+ * layout unconditionally costs a disabled provider and nothing else — and
+ * keeps every public route statically prerenderable.
+ */
+export function SiteLivePreviewProvider({ children }: { children: ReactNode }) {
+  return (
+    <LivePreviewProvider
+      allowedOrigins={config.livePreview.allowedOrigins}
+      collections={config.collections}
+    >
+      {children}
+    </LivePreviewProvider>
+  )
+}

package/templates/marketing-site/src/app/(frontend)/(site)/[slug]/page.tsx

@@ -5,6 +5,7 @@ import { notFound } from "next/navigation"
 import type { PagesDocument } from "~/vex.types"
 
 import { generatePageMetadata } from "~/lib/metadata"
+import { highlightPageBlocks } from "~/lib/highlight"
 import { vex } from "~/lib/vex"
 
 import { PageContent } from "../PageContent"
@@ -54,5 +55,9 @@ export default async function PublicPage({ params }: { params: Promise<{ slug: s
     notFound()
   }
 
-  return <PageContent initialData={initialData} slug={normalized} />
+  const codeHighlights = await highlightPageBlocks(initialData?.[0]?.blocks)
+
+  return (
+    <PageContent codeHighlights={codeHighlights} initialData={initialData} slug={normalized} />
+  )
 }

package/templates/marketing-site/src/app/(frontend)/(site)/layout.tsx

@@ -8,6 +8,7 @@ import { SiteFooter } from "~/components/SiteFooter"
 import { SiteHeader } from "~/components/SiteHeader"
 import { ThemeStyle } from "~/components/ThemeStyle"
 import { vex } from "~/lib/vex"
+import { SiteLivePreviewProvider } from "./SiteLivePreviewProvider"
 
 /**
  * Marketing chrome: header + footer around every site page. Auth routes live
@@ -31,7 +32,7 @@ export default async function SiteLayout({
   }
 
   return (
-    <>
+    <SiteLivePreviewProvider>
       <ThemeStyle />
       {/* Sits above the sticky header so it is the first tab stop on every
           page. Visually hidden until focused. */}
@@ -44,6 +45,6 @@ export default async function SiteLayout({
       <SiteHeader initialData={headerData} />
       <main id="main">{children}</main>
       <SiteFooter initialData={footerData} />
-    </>
+    </SiteLivePreviewProvider>
   )
 }

package/templates/marketing-site/src/app/(frontend)/(site)/page.tsx

@@ -3,6 +3,7 @@ import { api } from "@convex/_generated/api"
 import type { PagesDocument } from "~/vex.types"
 
 import { generatePageMetadata } from "~/lib/metadata"
+import { highlightPageBlocks } from "~/lib/highlight"
 import { vex } from "~/lib/vex"
 
 import { PageContent } from "./PageContent"
@@ -24,5 +25,9 @@ export default async function HomePage() {
     // Fall back to client-only fetch
   }
 
-  return <PageContent initialData={initialData} />
+  const codeHighlights = await highlightPageBlocks(initialData?.[0]?.blocks)
+
+  return (
+    <PageContent codeHighlights={codeHighlights} initialData={initialData} />
+  )
 }

package/templates/marketing-site/src/app/globals.css

@@ -372,3 +372,42 @@
   border-top: 2px dashed var(--border) !important;
 }
 
+/* ── Scrollbar ────────────────────────────────────────────────────────────
+   Matches the admin panel's `.vex-scroll-area` treatment (@vexcms/react's
+   styles.css): transparent track so the scrollbar reads as part of the
+   surface, and a permanently visible semi-transparent thumb rather than an
+   overlay bar that hides how much content is left. Applied to the document
+   scroller here, since the marketing site scrolls the window.
+   ────────────────────────────────────────────────────────────────────────── */
+html {
+  scrollbar-width: thin;
+  scrollbar-color: color-mix(in oklch, var(--foreground) 25%, transparent) transparent;
+}
+
+html::-webkit-scrollbar,
+body ::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+
+html::-webkit-scrollbar-track,
+html::-webkit-scrollbar-corner,
+body ::-webkit-scrollbar-track,
+body ::-webkit-scrollbar-corner {
+  background: transparent;
+}
+
+html::-webkit-scrollbar-thumb,
+body ::-webkit-scrollbar-thumb {
+  /* Transparent border + `background-clip: content-box` is the only way to
+     inset a webkit thumb without painting the track. */
+  background-color: color-mix(in oklch, var(--foreground) 25%, transparent);
+  background-clip: content-box;
+  border: 2px solid transparent;
+  border-radius: 9999px;
+}
+
+html::-webkit-scrollbar-thumb:hover,
+body ::-webkit-scrollbar-thumb:hover {
+  background-color: color-mix(in oklch, var(--foreground) 45%, transparent);
+}

package/templates/marketing-site/src/components/CodeHighlightContext.tsx

@@ -0,0 +1,76 @@
+"use client"
+
+import type { ReactNode } from "react"
+
+import { createContext, useContext, useEffect, useState } from "react"
+
+import type { CodeHighlightMap, CodeLanguage } from "~/lib/highlight"
+
+import { codeHighlightKey } from "~/lib/codeHighlightKey"
+
+const CodeHighlightContext = createContext<CodeHighlightMap>({})
+
+/**
+ * Supplies the server-built highlight map to the client tree.
+ *
+ * @param props.highlights - Map produced by `highlightPageBlocks` on the server.
+ * @param props.children - The page subtree containing code panes.
+ * @returns The provider.
+ */
+export function CodeHighlightProvider(props: {
+  children: ReactNode
+  highlights: CodeHighlightMap
+}) {
+  return (
+    <CodeHighlightContext.Provider value={props.highlights}>
+      {props.children}
+    </CodeHighlightContext.Provider>
+  )
+}
+
+/**
+ * Resolves one pane's highlighted HTML.
+ *
+ * Server-rendered code hits the precomputed map and never touches a
+ * highlighter. Code that only exists in the browser — what an editor is
+ * typing right now in live preview — misses, so this lazily imports shiki and
+ * highlights client-side. The import is dynamic and inside the miss branch, so
+ * an ordinary visitor downloads no highlighter at all.
+ *
+ * @param props.code - Source text.
+ * @param props.language - Resolved grammar name.
+ * @returns The highlighted inner HTML, or `undefined` until it is available
+ *   (render the raw source meanwhile).
+ */
+export function useCodeHighlight(props: {
+  code: string
+  language: CodeLanguage
+}): string | undefined {
+  const highlights = useContext(CodeHighlightContext)
+  const key = codeHighlightKey(props)
+  const precomputed = highlights[key]
+  const [clientHighlighted, setClientHighlighted] = useState<Record<string, string>>({})
+
+  useEffect(() => {
+    if (precomputed !== undefined || clientHighlighted[key] !== undefined) return
+
+    let cancelled = false
+    void (async () => {
+      // Dynamic on purpose, and the one case the static-import rule exempts:
+      // a static import would pull shiki's grammars and wasm into the page's
+      // main client chunk for every visitor, when only an editor previewing
+      // freshly-typed code ever reaches this branch.
+      const { highlightCodeInBrowser } = await import("~/lib/highlightClient")
+      const html = await highlightCodeInBrowser(props)
+      if (cancelled) return
+      setClientHighlighted((previous) => ({ ...previous, [key]: html }))
+    })()
+
+    return () => {
+      cancelled = true
+    }
+    // `props.code`/`props.language` are what `key` is derived from.
+  }, [key, precomputed, clientHighlighted, props])
+
+  return precomputed ?? clientHighlighted[key]
+}

package/templates/marketing-site/src/components/CodePane.tsx

@@ -1,7 +1,10 @@
+"use client"
+
 import { cn } from "@vexcms/react"
 
+import { useCodeHighlight } from "~/components/CodeHighlightContext"
 import { CopyButton } from "~/components/CopyButton"
-import { highlightCode, toCodeLanguage } from "~/lib/highlight"
+import { toCodeLanguage } from "~/lib/highlight"
 
 export type CodePaneProps = {
   /** Extra classes for the scroll body. */
@@ -22,10 +25,16 @@ export type CodePaneProps = {
 /**
  * One code pane: a chrome bar and a scrolling body on the fixed dark surface.
  *
- * Shared by CodeShowcase and Split so the two never drift. A server
- * component — shiki runs here and the client receives only markup.
+ * Shared by CodeShowcase and Split so the two never drift.
+ *
+ * Synchronous, and a client component, because it renders inside
+ * `PageContent` — which is client-side so live preview can overlay its query
+ * result. Highlighting therefore happens outside it: the server pre-highlights
+ * the fetched document's panes (`highlightPageBlocks`) and this reads the
+ * result through `useCodeHighlight`. An async component here is the error
+ * "<CodePane> is an async Client Component".
  */
-export async function CodePane({
+export function CodePane({
   bodyClassName,
   code,
   filename,
@@ -34,7 +43,7 @@ export async function CodePane({
   tone = "generated",
 }: CodePaneProps) {
   const resolvedLanguage = toCodeLanguage(language)
-  const html = await highlightCode({ code, language: resolvedLanguage })
+  const html = useCodeHighlight({ code, language: resolvedLanguage })
 
   return (
     // `min-w-0` is not optional. In a `1fr` grid track the longest line would
@@ -77,8 +86,11 @@ export async function CodePane({
         )}
       >
         <pre className="font-mono text-xs leading-[1.7] whitespace-pre text-[--color-code-fg] xl:text-[12.5px]">
-          {/* Highlighted server-side; the client ships no highlighter. */}
-          <code dangerouslySetInnerHTML={{ __html: html }} />
+          {/* Pre-highlighted on the server for anything the page fetched. A
+              pane the server never saw (code being typed in live preview)
+              renders as plain source until the lazy browser highlighter
+              resolves — never blank, never a spinner over a code block. */}
+          {html === undefined ? <code>{code}</code> : <code dangerouslySetInnerHTML={{ __html: html }} />}
         </pre>
       </div>
     </div>

package/templates/marketing-site/src/components/SiteFooter.tsx

@@ -2,8 +2,7 @@
 
 import { convexQuery } from "@convex-dev/react-query"
 import { api } from "@convex/_generated/api"
-import { useQuery } from "@tanstack/react-query"
-import { type RenderableBlock, RenderBlocks } from "@vexcms/react"
+import { type RenderableBlock, RenderBlocks, useLivePreviewDocumentQuery } from "@vexcms/react"
 
 import type { FootersDocument } from "~/vex.types"
 
@@ -16,10 +15,15 @@ export function SiteFooter({
 }: {
   initialData?: FootersDocument | null
 }) {
-  const { data: footer } = useQuery({
-    ...convexQuery(api.footers.getFirst, {}),
-    initialData: initialData ?? undefined,
-  })
+  // See `SiteHeader`: the overlay only reaches documents a consumer hands it,
+  // so editing the footer while previewing a page needs this wrapper.
+  const { data: footer } = useLivePreviewDocumentQuery(
+    {
+      ...convexQuery(api.footers.getFirst, {}),
+      initialData: initialData ?? undefined,
+    },
+    "footers",
+  )
 
   const content = footer?.content as null | PageBlockLike[] | undefined
   if (!content) {return null}

package/templates/marketing-site/src/components/SiteHeader.tsx

@@ -2,8 +2,7 @@
 
 import { convexQuery } from "@convex-dev/react-query"
 import { api } from "@convex/_generated/api"
-import { useQuery } from "@tanstack/react-query"
-import { type RenderableBlock, RenderBlocks } from "@vexcms/react"
+import { type RenderableBlock, RenderBlocks, useLivePreviewDocumentQuery } from "@vexcms/react"
 
 import type { HeadersDocument } from "~/vex.types"
 
@@ -16,10 +15,16 @@ export function SiteHeader({
 }: {
   initialData?: HeadersDocument | null
 }) {
-  const { data: header } = useQuery({
-    ...convexQuery(api.headers.getFirst, {}),
-    initialData: initialData ?? undefined,
-  })
+  // `useLivePreviewDocumentQuery`, not a bare `useQuery`: the live-preview
+  // overlay only reaches documents a consumer hands it, so a plain query here
+  // means editing the header while previewing a page changes nothing.
+  const { data: header } = useLivePreviewDocumentQuery(
+    {
+      ...convexQuery(api.headers.getFirst, {}),
+      initialData: initialData ?? undefined,
+    },
+    "headers",
+  )
 
   const content = header?.content as null | PageBlockLike[] | undefined
   if (!content) {return null}

package/templates/marketing-site/src/lib/codeHighlightKey.ts

@@ -0,0 +1,27 @@
+/**
+ * Stable key identifying one highlighted code pane.
+ *
+ * Client-safe by construction — this module imports nothing (shiki in
+ * particular), because both sides compute the key: the server when it builds
+ * the highlight map, and `CodePane` in the browser when it looks an entry up.
+ *
+ * A hash rather than the source text itself: the map is serialised into the
+ * RSC payload, and keying by the full code would ship every pane's source a
+ * second time.
+ *
+ * @param props.code - Source text exactly as authored.
+ * @param props.language - Resolved grammar name.
+ * @returns A short key, stable across server and client for identical input.
+ */
+export function codeHighlightKey(props: { code: string; language: string }): string {
+  const input = `${props.language}\u0000${props.code}`
+  // FNV-1a, 32-bit. Collisions only ever mean "render the wrong highlighted
+  // HTML for a pane", not a correctness or security problem, and the input
+  // space here is a handful of panes per page.
+  let hash = 0x811c9dc5
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i)
+    hash = Math.imul(hash, 0x01000193)
+  }
+  return `${props.language}-${(hash >>> 0).toString(36)}-${props.code.length}`
+}

package/templates/marketing-site/src/lib/highlight.ts

@@ -1,12 +1,22 @@
-import { createHighlighter, type Highlighter, type ThemeRegistrationRaw } from "shiki"
+import { createHighlighter, type Highlighter } from "shiki"
 
-import starkEmber from "./shikiStarkEmber.json"
+import { codeHighlightKey } from "./codeHighlightKey"
 
 /** Languages the `language` select on CodeShowcase and Split can produce. */
 export const CODE_LANGUAGES = ["bash", "json", "ts", "tsx"] as const
 
 export type CodeLanguage = (typeof CODE_LANGUAGES)[number]
 
+/**
+ * Shiki theme for every code pane, server and browser alike.
+ *
+ * Tokyo Night supplies the token colours only: `highlightCode` discards
+ * shiki's `<pre>` wrapper, which is where a theme's own background and
+ * default foreground live, so the pane keeps the Stark Ember surface from
+ * `--color-code-bg`/`--color-code-fg` and only the syntax colours change.
+ */
+export const CODE_THEME = "tokyo-night"
+
 /**
  * Narrows an authored `language` value to one shiki is loaded for.
  *
@@ -44,7 +54,7 @@ export async function highlightCode(props: {
   const highlighter = await getHighlighter()
   const html = highlighter.codeToHtml(props.code, {
     lang: props.language,
-    theme: "stark-ember",
+    theme: CODE_THEME,
   })
   // `codeToHtml` returns `<pre …><code>…</code></pre>`; keep the inner code
   // element's contents and let the pane own the scroll container.
@@ -65,7 +75,60 @@ export async function highlightCode(props: {
 function getHighlighter(): Promise<Highlighter> {
   highlighterPromise ??= createHighlighter({
     langs: [...CODE_LANGUAGES],
-    themes: [starkEmber as unknown as ThemeRegistrationRaw],
+    themes: [CODE_THEME],
   })
   return highlighterPromise
 }
+
+/**
+ * Map of {@link codeHighlightKey} to highlighted inner HTML, built on the
+ * server and handed to the client tree.
+ */
+export type CodeHighlightMap = Record<string, string>
+
+/**
+ * Pre-highlights every code pane a page's blocks contain.
+ *
+ * Exists because `PageContent` is a client component (live preview overlays
+ * its query result), so nothing below it can `await` shiki. The server walks
+ * the fetched document, highlights each pane, and passes plain strings across
+ * the boundary; `CodePane` then renders synchronously.
+ *
+ * The walk is structural rather than block-type-aware: any object carrying a
+ * string `code` is a pane, wherever a future block puts it, and its language
+ * comes from a sibling `language`/`codeLanguage` field.
+ *
+ * @param blocks - The document's `blocks` array, as fetched.
+ * @returns Highlighted HTML keyed by {@link codeHighlightKey}.
+ */
+export async function highlightPageBlocks(blocks: unknown): Promise<CodeHighlightMap> {
+  const panes: { code: string; language: CodeLanguage }[] = []
+
+  const collect = (node: unknown): void => {
+    if (Array.isArray(node)) {
+      node.forEach(collect)
+      return
+    }
+    if (node === null || typeof node !== "object") return
+
+    const record = node as Record<string, unknown>
+    if (typeof record.code === "string" && record.code.length > 0) {
+      panes.push({
+        code: record.code,
+        language: toCodeLanguage(
+          (record.language ?? record.codeLanguage) as string | string[] | undefined
+        ),
+      })
+    }
+    Object.values(record).forEach(collect)
+  }
+  collect(blocks)
+
+  const highlighted: CodeHighlightMap = {}
+  for (const pane of panes) {
+    const key = codeHighlightKey(pane)
+    if (highlighted[key] !== undefined) continue
+    highlighted[key] = await highlightCode(pane)
+  }
+  return highlighted
+}

package/templates/marketing-site/src/lib/highlightClient.ts

@@ -0,0 +1,37 @@
+import type { Highlighter } from "shiki"
+
+import { createHighlighter } from "shiki"
+
+import type { CodeLanguage } from "./highlight"
+
+import { CODE_LANGUAGES, CODE_THEME } from "./highlight"
+
+let browserHighlighterPromise: null | Promise<Highlighter> = null
+
+/**
+ * Highlights code in the browser, for panes the server never saw.
+ *
+ * The only caller is `useCodeHighlight`'s miss branch — live preview, where
+ * the editor's unsaved source exists nowhere but this tab. Loaded through a
+ * dynamic import so shiki stays out of the page's main client chunk.
+ *
+ * @param props.code - Source text.
+ * @param props.language - Grammar to highlight with.
+ * @returns Highlighted inner HTML, matching `highlightCode`'s server output.
+ */
+export async function highlightCodeInBrowser(props: {
+  code: string
+  language: CodeLanguage
+}): Promise<string> {
+  browserHighlighterPromise ??= createHighlighter({
+    langs: [...CODE_LANGUAGES],
+    themes: [CODE_THEME],
+  })
+  const highlighter = await browserHighlighterPromise
+  const html = highlighter.codeToHtml(props.code, {
+    lang: props.language,
+    theme: CODE_THEME,
+  })
+  const match = /<code[^>]*>([\s\S]*)<\/code>/.exec(html)
+  return match?.[1] ?? html
+}

package/templates/marketing-site/src/lib/resolvePagePath.ts

@@ -0,0 +1,8 @@
+/**
+ * Maps a `pages` document's slug to its public path. Shared by `vex.config.ts`'s
+ * `routes.map` and `pages.ts`'s `admin.livePreview.url`.
+ */
+export function resolvePagePath(slug: string | undefined): string | undefined {
+  if (!slug) return undefined
+  return slug === "home" ? "/" : `/${slug}`
+}

package/templates/marketing-site/src/proxy.ts

@@ -1,4 +1,9 @@
 import { api } from "@convex/_generated/api";
+import {
+  LIVE_PREVIEW_COOKIE,
+  LIVE_PREVIEW_COOKIE_MAX_AGE_SECONDS,
+  LIVE_PREVIEW_QUERY_PARAM,
+} from "@vexcms/core";
 import { fetchQuery } from "convex/nextjs";
 import { cookies } from "next/headers";
 import { type NextRequest, NextResponse } from "next/server";
@@ -51,27 +56,78 @@ export async function proxy(request: NextRequest) {
     return NextResponse.next();
   }
 
+  if (request.nextUrl.pathname.startsWith("/admin")) {
+    return guardAdminRequest(request);
+  }
+
+  return grantPreviewIfRequested(request);
+}
+
+/** Session gate for the admin panel — fails closed, per the docstring above. */
+async function guardAdminRequest(request: NextRequest) {
+  const sessionStatus = await resolveSessionStatus();
+
+  if (sessionStatus === "verification-failed") {
+    return redirectToUnauthorized(request);
+  }
+  if (sessionStatus === "unauthenticated") {
+    return redirectToSignIn(request);
+  }
+  return NextResponse.next();
+}
+
+/**
+ * Grants live-preview mode to a public-route request carrying `?vexLivePreview=1`
+ * and a verified admin session, by setting the `vex-live-preview` marker
+ * cookie that `LivePreviewProvider` gates on client-side. Fails **open** — an
+ * unauthenticated or unverifiable session here renders the page normally
+ * rather than redirecting.
+ *
+ * A cookie rather than a forwarded request header: a header would have to be
+ * read with `next/headers` in the site layout, which opts every public route
+ * out of static prerendering.
+ */
+async function grantPreviewIfRequested(request: NextRequest) {
+  if (request.nextUrl.searchParams.get(LIVE_PREVIEW_QUERY_PARAM) !== "1") {
+    return NextResponse.next();
+  }
+
+  const sessionStatus = await resolveSessionStatus();
+  if (sessionStatus !== "authenticated") {
+    return NextResponse.next();
+  }
+
+  const response = NextResponse.next();
+  response.cookies.set(LIVE_PREVIEW_COOKIE, "1", {
+    path: "/",
+    maxAge: LIVE_PREVIEW_COOKIE_MAX_AGE_SECONDS,
+    sameSite: "lax",
+    // Read by `LivePreviewProvider` in the browser — the whole point of the
+    // cookie. It carries no secret, only the fact that a session verified.
+    httpOnly: false,
+  });
+  return response;
+}
+
+/** Reads and verifies the Better Auth session cookie — shared by both branches above. */
+async function resolveSessionStatus(): Promise<
+  "authenticated" | "unauthenticated" | "verification-failed"
+> {
   const cookieStore = await cookies();
   const sessionToken =
     cookieStore.get(SESSION_COOKIES.https)?.value ?? cookieStore.get(SESSION_COOKIES.http)?.value;
-  if (!sessionToken) {
-    return redirectToSignIn(request);
-  }
+  if (!sessionToken) return "unauthenticated";
 
   try {
     const session = await fetchQuery(api.auth.sessions.getSessionWithUser, {
       sessionToken: extractToken(sessionToken),
     });
-    if (!session?.user) {
-      return redirectToSignIn(request);
-    }
+    return session?.user ? "authenticated" : "unauthenticated";
   } catch {
-    // Fail closed. Previously this returned `NextResponse.next()`, which served
-    // every guarded route unauthenticated whenever this lookup threw.
-    return redirectToUnauthorized(request);
+    // Fail closed for the admin branch; grantPreviewIfRequested treats this as
+    // "no preview" rather than an error.
+    return "verification-failed";
   }
-
-  return NextResponse.next();
 }
 
 /** Extract the raw token — better-auth stores "<raw_token>.<hmac_signature>" */
@@ -119,5 +175,5 @@ export const config = {
   // Allowlist, not denylist. The base template denies everything except a few
   // paths; here the public site IS the product, so the gate names the private
   // surfaces explicitly. Anything added under `(vexcms)` must be added here.
-  matcher: ["/admin/:path*"],
+  matcher: ["/admin/:path*", "/((?!_next/static|_next/image|favicon.ico).*)"],
 };

package/templates/marketing-site/src/vex.config.ts

@@ -5,6 +5,7 @@ import { uploadFile } from "@vexcms/file-storage-convex/client"
 import { authSchema } from "@convex/auth/schema"
 
 import { access } from "~/auth/access"
+import { resolvePagePath } from "~/lib/resolvePagePath"
 import { footers, headers, images, pages, themes, users } from "~/vexcms/collections"
 import { siteSettings } from "~/vexcms/globals"
 
@@ -37,9 +38,16 @@ const vexConfig = defineConfig({
       if (collection !== pages.slug) return []
       const { slug } = doc
       if (typeof slug !== "string") return []
-      return [slug === "home" ? "/" : `/${slug}`]
+      const path = resolvePagePath(slug)
+      return path === undefined ? [] : [path]
     },
   },
+  livePreview: {
+    allowedOrigins: [
+      "http://localhost:3000",
+      ...(process.env.NEXT_PUBLIC_SITE_URL ? [process.env.NEXT_PUBLIC_SITE_URL] : []),
+    ],
+  },
 })
 
 export default vexConfig

package/templates/marketing-site/src/vexcms/collections/headers.ts

@@ -8,6 +8,9 @@ export const headers = defineCollection({
   admin: {
     useAsTitle: "name",
     icon: "PanelTop",
+    livePreview: {
+      url: "/",
+    },
   },
   fields: {
     name: text({

package/templates/marketing-site/src/vexcms/collections/pages.ts

@@ -2,6 +2,7 @@ import type { DataModel } from "@convex/_generated/dataModel"
 
 import { blocks, defineCollection, text, textValidator, upload } from "@vexcms/core"
 
+import { resolvePagePath } from "~/lib/resolvePagePath"
 import { TABLE_SLUG_IMAGES, TABLE_SLUG_PAGES } from "~/db/constants"
 import { pageBlocks } from "~/vexcms/blocks/config"
 
@@ -11,6 +12,9 @@ export const pages = defineCollection({
     table: { defaultColumns: ["title", "slug", "_id"] },
     useAsTitle: "title",
     icon: "FileText",
+    livePreview: {
+      url: (doc) => resolvePagePath(doc.slug),
+    },
   },
   fields: {
     title: text({

package/templates/marketing-site/src/lib/shikiStarkEmber.json

@@ -1,57 +0,0 @@
-{
-  "name": "stark-ember",
-  "type": "dark",
-  "colors": {
-    "editor.background": "#0F0F0F",
-    "editor.foreground": "#D4D4D4"
-  },
-  "tokenColors": [
-    {
-      "scope": ["comment", "punctuation.definition.comment", "string.comment"],
-      "settings": { "foreground": "#7A7A7A" }
-    },
-    {
-      "scope": [
-        "keyword",
-        "keyword.control",
-        "keyword.operator.new",
-        "storage",
-        "storage.type",
-        "storage.modifier",
-        "constant.language",
-        "support.type.primitive",
-        "variable.language"
-      ],
-      "settings": { "foreground": "#F2864F" }
-    },
-    {
-      "scope": [
-        "entity.name.function",
-        "entity.name.type",
-        "entity.name.class",
-        "support.class",
-        "support.function",
-        "meta.definition.variable entity.name.function"
-      ],
-      "settings": { "foreground": "#F4F4F4" }
-    },
-    {
-      "scope": ["string", "string.quoted", "constant.numeric", "constant.character"],
-      "settings": { "foreground": "#ABABAB" }
-    },
-    {
-      "scope": [
-        "punctuation",
-        "meta.brace",
-        "punctuation.separator",
-        "punctuation.terminator",
-        "keyword.operator"
-      ],
-      "settings": { "foreground": "#6B6B6B" }
-    },
-    {
-      "scope": ["variable", "variable.other", "meta.object-literal.key", "support.variable"],
-      "settings": { "foreground": "#D4D4D4" }
-    }
-  ]
-}