create-vexcms 0.1.0-alpha.2 → 0.1.0-alpha.21

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

@@ -0,0 +1,413 @@
+/* ============================================================================
+   VexCMS · globals.css — Stark × Ember (shadcn-faithful translation)
+   ----------------------------------------------------------------------------
+   Source of design intent: .agent/docs/design/claude-design/admin.css (Claude Design
+   export). That file uses bespoke tokens (--page, --fg-muted, --line-bold,
+   --accent / --accent-tint / --accent-ink, …); this file translates them
+   into shadcn-named tokens so every React component in @vexcms/react keeps
+   working with no per-component overrides.
+
+   Read .agent/docs/design/claude-design/README.md before editing.
+
+   Key semantic decisions (different from naive shadcn):
+   - Brand CTA  → --primary       (admin.css `--accent`)        ember solid
+   - Highlight  → --accent        (admin.css `--accent-tint`)   ember tint
+   - Ink/active → --accent-fg     (admin.css `--accent-ink`)    deep ember
+   - Default surfaces (--card, --popover) = SAME tone (admin.css `--surface`)
+   - --muted / --raised = third elevation level (admin.css `--raised`)
+     used for table headers, modal foots, hover bgs, badge.muted.
+
+   All values are oklch.
+   ============================================================================ */
+
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "@vexcms/next/styles";
+
+/* Scan the installed @vexcms packages for class candidates (their dist output
+   ships alongside this app in node_modules; @vexcms/next/styles above pulls
+   the stylesheet, these make sure every utility used by the admin UI exists).
+   Globbed to `*.js` only — the same `dist` directories also carry `.map`
+   sourcemaps and `.d.ts` declaration files, and Tailwind's scanner extracts
+   garbage "class candidates" from their base64/binary-ish content and emits
+   unparseable CSS, exactly like the raw `public/` binary assets below. */
+@source "../../node_modules/@vexcms/react/dist/**/*.js";
+@source "../../node_modules/@vexcms/next/dist/**/*.js";
+@source not "../../public";
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  /* ── Surfaces ─────────────────────────────────────────────────────────── */
+  --color-background:                 var(--background);
+  --color-foreground:                 var(--foreground);
+  --color-card:                       var(--card);
+  --color-card-foreground:            var(--card-foreground);
+  --color-popover:                    var(--popover);
+  --color-popover-foreground:         var(--popover-foreground);
+
+  /* ── Brand / accents ──────────────────────────────────────────────────── */
+  --color-primary:                    var(--primary);            /* ember solid */
+  --color-primary-foreground:         var(--primary-foreground);
+  --color-secondary:                  var(--secondary);
+  --color-secondary-foreground:       var(--secondary-foreground);
+  --color-accent:                     var(--accent);             /* ember tint */
+  --color-accent-foreground:          var(--accent-foreground);  /* ember ink */
+
+  /* ── Neutral hover & muted ────────────────────────────────────────────── */
+  --color-muted:                      var(--muted);              /* = --raised */
+  --color-muted-foreground:           var(--muted-foreground);
+
+  /* ── Borders & inputs ─────────────────────────────────────────────────── */
+  --color-border:                     var(--border);             /* default separators */
+  --color-input:                      var(--input);              /* input borders */
+  --color-ring:                       var(--ring);               /* solid ember focus */
+
+  /* ── Status ───────────────────────────────────────────────────────────── */
+  --color-destructive:                var(--destructive);
+  --color-destructive-foreground:     var(--destructive-foreground);
+
+  /* ── Sidebar ──────────────────────────────────────────────────────────── */
+  --color-sidebar:                    var(--sidebar);
+  --color-sidebar-foreground:         var(--sidebar-foreground);
+  --color-sidebar-primary:            var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent:             var(--sidebar-accent);
+  --color-sidebar-accent-foreground:  var(--sidebar-accent-foreground);
+  --color-sidebar-border:             var(--sidebar-border);
+  --color-sidebar-ring:               var(--sidebar-ring);
+
+  /* ── Charts ───────────────────────────────────────────────────────────── */
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+
+  /* ── Fonts ────────────────────────────────────────────────────────────── */
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-geist-mono);
+
+  /* ── Radii — Vex is sharp ─────────────────────────────────────────────── */
+  --radius-sm:  2px;   /* controls: buttons, inputs, menu items, type chips */
+  --radius-md:  4px;   /* cards, popovers, table wraps */
+  --radius-lg:  8px;   /* modals, dialogs */
+  --radius-xl:  12px;
+  --radius-2xl: 16px;
+  --radius-3xl: 20px;
+  --radius-4xl: 9999px; /* pill badges & avatars */
+
+  /* ── Shadows ──────────────────────────────────────────────────────────── */
+  --shadow-xs:  var(--shadow-xs-val);
+  --shadow-sm:  var(--shadow-sm-val);
+  --shadow-md:  var(--shadow-md-val);
+  --shadow-lg:  var(--shadow-lg-val);
+  --shadow-pop: var(--shadow-pop-val);
+
+  /* ── Motion ───────────────────────────────────────────────────────────── */
+  --ease-emphasized: cubic-bezier(.2, .8, .2, 1);
+  --duration-fast: 120ms;
+  --duration-base: 180ms;
+  --duration-slow: 260ms;
+
+  /* ── Section rhythm — every block's vertical padding derives from these ── */
+  --spacing-section:    3.5rem;  /*  56px  mobile  */
+  --spacing-section-md: 5rem;    /*  80px  tablet  */
+  --spacing-section-xl: 7rem;    /* 112px  desktop */
+
+  /* ── Code pane — FIXED IN BOTH THEMES ─────────────────────────────────────
+     The one deliberate exception to "the theme decides colour": code panes
+     stay dark under a light theme. That is what lets shiki run a single
+     server pass with one theme and ship no highlighter to the client.
+     These are @theme tokens, never part of the themes collection record. */
+  --color-code-bg:     oklch(11%   0     0);
+  --color-code-chrome: oklch(15.5% 0     0);
+  --color-code-border: oklch(24%   0     0);
+  --color-code-fg:     oklch(84%   0     0);
+  --color-code-dim:    oklch(52%   0     0);  /* comments, shell prompts        */
+  --color-code-key:    oklch(72%   0.16 42);  /* keywords, primitives, booleans */
+  --color-code-ident:  oklch(96%   0     0);  /* functions, type names          */
+  --color-code-string: oklch(70%   0     0);  /* strings, slugs                 */
+  --color-code-punct:  oklch(45%   0     0);
+}
+
+/* ────────────────────────────────────────────────────────────────────────────
+   LIGHT — Stark × Ember
+   page #F5F5F5 · surface #FFFFFF · raised #FAFAFA · fg #0A0A0A
+   ──────────────────────────────────────────────────────────────────────────── */
+:root {
+  /* Surfaces — three elevation levels */
+  --background:                  oklch(96.1% 0    0);            /* #F5F5F5 */
+  --foreground:                  oklch(13.7% 0    0);            /* #0A0A0A */
+  --card:                        oklch(100%  0    0);            /* #FFFFFF */
+  --card-foreground:             oklch(13.7% 0    0);
+  --popover:                     oklch(100%  0    0);            /* same as card */
+  --popover-foreground:          oklch(13.7% 0    0);
+
+  /* Brand — ember on --primary */
+  --primary:                     oklch(60.5% 0.175 42);          /* #E8622A */
+  --primary-foreground:          oklch(100%  0    0);
+
+  /* Neutral secondary */
+  --secondary:                   oklch(98%   0    0);            /* #FAFAFA */
+  --secondary-foreground:        oklch(13.7% 0    0);
+
+  /* Highlight = ember TINT (matches admin.css --accent-tint) */
+  --accent:                      oklch(96%   0.025 42);          /* #FEF0E8 */
+  --accent-foreground:           oklch(52%   0.180 40);          /* ember ink */
+
+  /* Neutral hover & muted (= admin.css --hover / --raised) */
+  --muted:                       oklch(98%   0    0);            /* #FAFAFA = raised */
+  --muted-foreground:            oklch(50.5% 0    0);            /* #717171 */
+
+  /* Borders */
+  --border:                      oklch(85%   0    0);            /* #D4D4D4 — default */
+  --input:                       oklch(54.6% 0    0);            /* #6B6B6B — inputs */
+  --ring:                        oklch(60.5% 0.175 42);          /* solid ember */
+
+  /* Status */
+  --destructive:                 oklch(57.7% 0.198 27);          /* #DC2626 */
+  --destructive-foreground:      oklch(98%   0    0);
+
+  /* Base radius — used by anything reading var(--radius) directly */
+  --radius: 4px;
+
+  /* Sidebar */
+  --sidebar:                     oklch(98%   0     0);           /* #FAFAFA */
+  --sidebar-foreground:          oklch(13.7% 0     0);
+  --sidebar-primary:             oklch(60.5% 0.175 42);          /* ember */
+  --sidebar-primary-foreground:  oklch(100%  0     0);
+  --sidebar-accent:              oklch(96.1% 0     0);
+  --sidebar-accent-foreground:   oklch(13.7% 0     0);
+  --sidebar-border:              oklch(85%   0     0);
+  --sidebar-ring:                oklch(60.5% 0.175 42);
+
+  /* Charts */
+  --chart-1: oklch(60.5% 0.175 42);
+  --chart-2: oklch(45%   0     0);
+  --chart-3: oklch(72%   0.100 60);
+  --chart-4: oklch(60%   0.040 30);
+  --chart-5: oklch(78%   0     0);
+
+  /* Shadows — soft elevation in light */
+  --shadow-xs-val:  0 1px 2px  rgba(10, 10, 10, 0.04);
+  --shadow-sm-val:  0 1px 3px  rgba(10, 10, 10, 0.08);
+  --shadow-md-val:  0 4px 12px rgba(10, 10, 10, 0.08);
+  --shadow-lg-val:  0 12px 32px rgba(10, 10, 10, 0.12);
+  --shadow-pop-val: 0 12px 28px rgba(10, 10, 10, 0.14),
+                    0 1px 3px   rgba(10, 10, 10, 0.06);
+}
+
+/* ────────────────────────────────────────────────────────────────────────────
+   DARK — Stark × Ember dark
+   page #0A0A0A · surface #141414 · raised #1E1E1E · fg #F4F4F4
+   Hotter ember (#F07040) for contrast. No flat shadows.
+   ──────────────────────────────────────────────────────────────────────────── */
+.dark {
+  /* Surfaces */
+  --background:                  oklch(13.7% 0     0);           /* #0A0A0A */
+  --foreground:                  oklch(95%   0     0);           /* #F4F4F4 */
+  --card:                        oklch(17.4% 0     0);           /* #141414 */
+  --card-foreground:             oklch(95%   0     0);
+  --popover:                     oklch(17.4% 0     0);           /* same as card */
+  --popover-foreground:          oklch(95%   0     0);
+
+  /* Brand */
+  --primary:                     oklch(72%   0.175 50);          /* #F07040 */
+  --primary-foreground:          oklch(13.7% 0     0);
+
+  /* Secondary */
+  --secondary:                   oklch(20%   0     0);           /* #1E1E1E */
+  --secondary-foreground:        oklch(95%   0     0);
+
+  /* Highlight — translucent ember tint */
+  --accent:                      oklch(72%   0.175 50 / 0.12);
+  --accent-foreground:           oklch(72%   0.175 50);          /* ember itself in dark */
+
+  /* Neutral hover & muted */
+  --muted:                       oklch(20%   0     0);           /* = raised in dark */
+  --muted-foreground:            oklch(70%   0     0);           /* #A0A0A0 */
+
+  /* Borders */
+  --border:                      oklch(25%   0     0);           /* #2A2A2A */
+  --input:                       oklch(40%   0     0);           /* #5A5A5A */
+  --ring:                        oklch(72%   0.175 50);
+
+  /* Status */
+  --destructive:                 oklch(63%   0.210 27);          /* #EF4444 */
+  --destructive-foreground:      oklch(95%   0     0);
+
+  /* Sidebar */
+  --sidebar:                     oklch(7%    0     0);           /* #050505 */
+  --sidebar-foreground:          oklch(95%   0     0);
+  --sidebar-primary:             oklch(72%   0.175 50);
+  --sidebar-primary-foreground:  oklch(13.7% 0     0);
+  --sidebar-accent:              oklch(20%   0     0);
+  --sidebar-accent-foreground:   oklch(95%   0     0);
+  --sidebar-border:              oklch(25%   0     0);
+  --sidebar-ring:                oklch(72%   0.175 50);
+
+  /* Charts */
+  --chart-1: oklch(72%   0.175 50);
+  --chart-2: oklch(78%   0     0);
+  --chart-3: oklch(78%   0.120 65);
+  --chart-4: oklch(60%   0.060 30);
+  --chart-5: oklch(45%   0     0);
+
+  /* Shadows — flat in dark; only overlays use --shadow-pop */
+  --shadow-xs-val:  none;
+  --shadow-sm-val:  none;
+  --shadow-md-val:  none;
+  --shadow-lg-val:  none;
+  --shadow-pop-val: 0 18px 40px rgba(0, 0, 0, 0.55),
+                    0 1px 0 var(--border) inset;
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+    font-feature-settings:
+      "ss01" 1,
+      "cv11" 1;
+    -webkit-font-smoothing: antialiased;
+  }
+
+  /* Focus-visible is global and is never removed or restyled per block. It
+     must stay legible against bg-background AND the fixed dark code pane. */
+  :focus-visible {
+    outline: 2px solid var(--color-ring);
+    outline-offset: 2px;
+  }
+
+  ::selection {
+    background-color: color-mix(in oklch, var(--color-primary) 22%, transparent);
+  }
+
+  /* Links inside `text` field output. There is no richtext field, so this is
+     the only styling prose from the CMS ever receives. */
+  .prose-field a {
+    color: var(--color-primary);
+    text-decoration-line: underline;
+    text-underline-offset: 4px;
+    text-decoration-color: color-mix(in oklch, currentColor 40%, transparent);
+  }
+  .prose-field a:hover {
+    text-decoration-color: currentColor;
+  }
+
+  code,
+  pre {
+    font-feature-settings:
+      "ss01" 1,
+      "calt" 1;
+    tab-size: 2;
+  }
+
+  /* Smooth scrolling is scoped to explicit in-page anchor navigation, never
+     applied to `html` globally.
+
+     A global `scroll-behavior: smooth` animates *every* programmatic scroll,
+     including the position restoration that popovers, dialogs and scroll
+     locks perform. A 20px correction then reads as the page gliding away
+     under the cursor, and a restore-to-saved-offset reads as a scroll to the
+     top. `:target` limits it to the one case the design actually asked for. */
+  html:has(:target) {
+    scroll-behavior: smooth;
+  }
+}
+
+/* ────────────────────────────────────────────────────────────────────────────
+   MOTION KIT
+   The `reveal` keyframe and `.item` live in
+   src/components/motion-primitives/reveal.module.css — do not duplicate them.
+   Only the two rules that must be global are declared here.
+   ──────────────────────────────────────────────────────────────────────────── */
+
+/* Stagger contract — the group sets the step, each item reads its index. */
+.reveal-group > * {
+  --reveal-delay: calc(var(--reveal-stagger, 60ms) * var(--i, 0));
+}
+
+/* The one decorative loop on the entire site: the Roadmap "In progress" dot. */
+@keyframes livepulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.35;
+  }
+}
+
+.live-dot {
+  animation: livepulse 2s var(--ease-emphasized) infinite;
+}
+
+/* Reduced motion is a full stop, not a shortened duration: the final state is
+   painted immediately — opacity 1, no blur, no translate. */
+@media (prefers-reduced-motion: reduce) {
+  .item,
+  .live-dot,
+  .reveal-group > * {
+    animation: none !important;
+  }
+
+  html {
+    scroll-behavior: auto;
+  }
+}
+
+/* Pangea dnd placeholder — thin dashed line instead of full-height gap */
+[data-rfd-placeholder] {
+  height: 3px !important;
+  min-height: 3px !important;
+  margin: 0 !important;
+  padding: 0 !important;
+  background: transparent !important;
+  border-radius: 0 !important;
+  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/app/layout.tsx

@@ -0,0 +1,85 @@
+import type { Metadata } from "next"
+
+import "./globals.css"
+
+import { ThemeScript } from "@vexcms/react"
+import { Geist, Geist_Mono } from "next/font/google"
+
+import ClientProviders from "~/components/providers/client"
+import ServerProviders from "~/components/providers/server"
+import { ThemeLive } from "~/components/ThemeLive"
+
+/**
+ * Geist carries the whole type system — display through body — so weight is
+ * the only axis the design varies. 800 is the hero display weight; without it
+ * next/font would synthesise it and the -0.04em tracking would fall apart.
+ *
+ * `--font-sans` is also written by the active theme record's `fontFamily`
+ * (THEME_SHARED_TOKENS). Both land at specificity (0,1,0), so the theme's
+ * stack acts as the fallback and an editor can change the family without a
+ * redeploy.
+ */
+const geistSans = Geist({
+  display: "swap",
+  subsets: ["latin"],
+  variable: "--font-sans",
+  weight: ["400", "500", "600", "700", "800"],
+})
+
+const geistMono = Geist_Mono({
+  display: "swap",
+  subsets: ["latin"],
+  variable: "--font-geist-mono",
+  weight: ["400", "500"],
+})
+
+/**
+ * `icons.icon` lists the SVG first: browsers pick the last format they
+ * understand, and every current engine understands `image/svg+xml`, so the
+ * `.ico` only serves older ones. All three assets are the ember chevron from
+ * `BrandMark` — placeholder branding, exactly like `BrandMark` itself and the
+ * "VexCMS" site name in `convex/seed.ts`. Replace `public/favicon.svg`,
+ * `public/favicons/favicon.ico` and `public/favicons/apple-touch-icon.png`
+ * with your own mark; `.ico` and `apple-touch-icon` must stay raster, since
+ * older browsers and iOS home-screen icons do not accept SVG.
+ */
+export const metadata: Metadata = {
+  description: "Built with VexCMS",
+  icons: {
+    apple: "/favicons/apple-touch-icon.png",
+    icon: [
+      { url: "/favicon.svg", type: "image/svg+xml" },
+      { url: "/favicons/favicon.ico", sizes: "16x16 32x32 48x48" },
+    ],
+  },
+  title: "VexCMS",
+}
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode
+}>) {
+  return (
+    <html
+      className={`${geistSans.variable} ${geistMono.variable} antialiased`}
+      lang="en"
+      suppressHydrationWarning
+    >
+      <head>
+        {/* Applies the persisted light/dark class before first paint (no
+            flash). Site theming now renders in `(frontend)/(site)/layout.tsx`
+            — the admin layout re-emits its own scope for `/admin`. */}
+        <ThemeScript />
+      </head>
+      <body>
+        <ServerProviders>
+          <ClientProviders>
+            <ThemeLive />
+            {children}
+          </ClientProviders>
+        </ServerProviders>
+      </body>
+    </html>
+  )
+}

package/templates/marketing-site/src/app/robots.ts

@@ -0,0 +1,13 @@
+import { createVexRobots } from "@vexcms/next/seo"
+
+import { env } from "~/env.mjs"
+
+/**
+ * Generates `/robots.txt`. Allows all crawlers on the public site and points
+ * them at the generated sitemap; disallows the authenticated `/admin` tree
+ * and its `/api` routes.
+ */
+export default createVexRobots({
+  siteUrl: env.NEXT_PUBLIC_SITE_URL,
+  disallow: ["/admin", "/api"],
+})

package/templates/marketing-site/src/app/sitemap.ts

@@ -0,0 +1,18 @@
+import { api } from "@convex/_generated/api"
+import { createVexSitemap } from "@vexcms/next/seo"
+
+import { env } from "~/env.mjs"
+import { vex } from "~/lib/vex"
+
+/**
+ * Generates `/sitemap.xml` from every published `pages` document plus the
+ * site root. Degrades to `[]` (no page entries) when Convex is unreachable —
+ * the packed-tarball scaffold this template ships into has no live
+ * deployment and builds against placeholder env (P-020).
+ */
+export default createVexSitemap({
+  client: vex,
+  query: api.pages.publishedSlugs,
+  toUrl: (slug) => (slug === "home" ? env.NEXT_PUBLIC_SITE_URL : `${env.NEXT_PUBLIC_SITE_URL}/${slug}`),
+  getSlug: (item) => item.slug,
+})

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

@@ -0,0 +1,27 @@
+/**
+ * The VexCMS chevron, inline in the layout rather than in the media library.
+ *
+ * A freshly scaffolded project has an empty media library, so the mark cannot
+ * be an upload — the header and footer would render a wordmark with a hole
+ * next to it on first run. `logoImage` overrides this when an editor sets one.
+ */
+export function BrandMark({ className }: { className?: string }) {
+  return (
+    <svg
+      aria-hidden
+      className={className}
+      fill="none"
+      height="16"
+      viewBox="0 0 16 16"
+      width="16"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path
+        d="M2.5 3.25 7.25 12.75a0.85 0.85 0 0 0 1.5 0L13.5 3.25"
+        stroke="currentColor"
+        strokeLinecap="square"
+        strokeWidth="2.25"
+      />
+    </svg>
+  )
+}

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]
+}