modern-cms 1.0.0

package/template/apps/web/components/renderer/sections/Testimonial.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Star } from "lucide-react";
+import { CmsImage } from "../CmsImage";
+import type { SectionProps } from "./types";
+
+type TestimonialItem = { avatar?: string; name: string; role?: string; quote: string; rating?: number };
+
+function Card({ item }: { item: TestimonialItem }) {
+  return (
+    <div className="flex flex-col gap-4 rounded-lg border bg-white p-6">
+      {item.rating ? (
+        <div className="flex gap-0.5 text-amber-400">
+          {Array.from({ length: 5 }, (_, i) => (
+            <Star key={i} size={16} fill={i < item.rating! ? "currentColor" : "none"} className={i < item.rating! ? "" : "opacity-30"} />
+          ))}
+        </div>
+      ) : null}
+      <p className="text-sm opacity-80 flex-1">&ldquo;{item.quote}&rdquo;</p>
+      <div className="flex items-center gap-3">
+        {item.avatar && (
+          <div className="relative w-10 h-10 rounded-full overflow-hidden shrink-0">
+            <CmsImage src={item.avatar} alt={item.name} fill className="object-cover" />
+          </div>
+        )}
+        <div>
+          <div className="text-sm font-semibold">{item.name}</div>
+          {item.role && <div className="text-xs opacity-60">{item.role}</div>}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function Testimonial({ node }: SectionProps) {
+  const heading = node.props.heading as string;
+  const items = (node.props.items as TestimonialItem[]) ?? [];
+  const layout = (node.props.layout as string) || "grid";
+  const columns = Math.max(1, Math.min(4, Number(node.props.columns) || 3));
+  const [index, setIndex] = useState(0);
+
+  useEffect(() => {
+    if (layout !== "carousel" || items.length < 2) return;
+    const id = setInterval(() => setIndex((i) => (i + 1) % items.length), 6000);
+    return () => clearInterval(id);
+  }, [layout, items.length]);
+
+  if (items.length === 0) return null;
+
+  return (
+    <div>
+      {heading && <h2 className="text-2xl md:text-3xl font-bold mb-8 text-center">{heading}</h2>}
+      {layout === "carousel" ? (
+        <div className="max-w-xl mx-auto">
+          <Card item={items[Math.min(index, items.length - 1)]} />
+          {items.length > 1 && (
+            <div className="flex justify-center gap-2 mt-4">
+              {items.map((_, i) => (
+                <button
+                  key={i}
+                  onClick={() => setIndex(i)}
+                  className={`h-2 w-2 rounded-full ${i === index ? "bg-theme-primary" : "bg-slate-300"}`}
+                  aria-label={`Show testimonial ${i + 1}`}
+                />
+              ))}
+            </div>
+          )}
+        </div>
+      ) : (
+        <div className="grid gap-6" style={{ gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` }}>
+          {items.map((item, i) => (
+            <Card key={i} item={item} />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/template/apps/web/components/renderer/sections/ThreeBackground.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+import { useRef } from "react";
+import { useThreeBackgroundScene, type ThreeBackgroundPreset } from "@/lib/threeBackgroundScene";
+import { Button } from "./Button";
+import type { SectionProps } from "./types";
+
+export function ThreeBackground({ node, children }: SectionProps) {
+  const { heading, subheading, buttonText, buttonHref } = node.props as Record<string, string>;
+  // Default true: pages built before the toggle existed have no `enabled` prop and
+  // should keep animating exactly as they did.
+  const enabled = node.props.enabled !== false;
+  const preset = ((node.props.preset as ThreeBackgroundPreset) || "particles") as ThreeBackgroundPreset;
+  const color = (node.props.color as string) || "#2563eb";
+  const secondColor = (node.props.secondColor as string) || "";
+  const density = Number(node.props.density) || 80;
+  const speed = Number(node.props.speed) || 1;
+  const mouseFollow = node.props.mouseFollow === true;
+  const bgOpacity = node.props.bgOpacity !== undefined ? Number(node.props.bgOpacity) : 1;
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  useThreeBackgroundScene(canvasRef, containerRef, enabled, {
+    preset,
+    color,
+    secondColor: secondColor || undefined,
+    density,
+    speed,
+    mouseFollow,
+  });
+
+  return (
+    <div ref={containerRef} className="relative flex flex-col items-center justify-center h-full min-h-[inherit] text-center gap-4 overflow-hidden">
+      {enabled && <canvas ref={canvasRef} className="absolute inset-0 w-full h-full" style={{ opacity: bgOpacity }} />}
+      <div className="relative z-10 flex flex-col items-center gap-4 max-w-2xl mx-auto">
+        {heading && <h2 className="text-3xl md:text-4xl font-bold">{heading}</h2>}
+        {subheading && <p className="text-lg opacity-90">{subheading}</p>}
+        {buttonText && <Button text={buttonText} href={buttonHref || "#"} variant="primary" />}
+        {children && <div className="w-full">{children}</div>}
+      </div>
+    </div>
+  );
+}

package/template/apps/web/components/renderer/sections/Timeline.tsx

@@ -0,0 +1,29 @@
+import type { SectionProps } from "./types";
+
+type TimelineItem = { date?: string; title: string; description?: string };
+
+export function Timeline({ node }: SectionProps) {
+  const heading = node.props.heading as string;
+  const items = (node.props.items as TimelineItem[]) ?? [];
+
+  if (items.length === 0) return null;
+
+  return (
+    <div>
+      {heading && <h2 className="text-2xl md:text-3xl font-bold mb-8 text-center">{heading}</h2>}
+      <div className="relative max-w-2xl mx-auto pl-8">
+        <div className="absolute left-[7px] top-1 bottom-1 w-px bg-slate-200" aria-hidden="true" />
+        <div className="flex flex-col gap-8">
+          {items.map((item, i) => (
+            <div key={i} className="relative">
+              <span className="absolute -left-8 top-1 w-3.5 h-3.5 rounded-full bg-theme-primary border-2 border-white shadow" />
+              {item.date && <div className="text-xs font-semibold uppercase tracking-wide text-theme-primary mb-1">{item.date}</div>}
+              <h3 className="font-semibold">{item.title}</h3>
+              {item.description && <p className="text-sm opacity-75 mt-1">{item.description}</p>}
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}

package/template/apps/web/components/renderer/sections/VideoBackgroundSection.tsx

@@ -0,0 +1,20 @@
+import { Button } from "./Button";
+import type { SectionProps } from "./types";
+
+/** The video + overlay layers themselves now render universally for every node type
+ * (see NodeBackgroundLayers) — this component only lays out the built-in content and
+ * any child components dropped into the section. */
+export function VideoBackgroundSection({ node, children }: SectionProps) {
+  const { heading, subheading, buttonText, buttonHref } = node.props as Record<string, string>;
+
+  return (
+    <div className="flex flex-col items-center justify-center h-full min-h-[inherit] text-center gap-4">
+      <div className="flex flex-col items-center gap-4 max-w-2xl mx-auto">
+        {heading && <h2 className="text-3xl md:text-4xl font-bold">{heading}</h2>}
+        {subheading && <p className="text-lg opacity-90">{subheading}</p>}
+        {buttonText && <Button text={buttonText} href={buttonHref || "#"} variant="primary" />}
+      </div>
+      {children && <div className="w-full">{children}</div>}
+    </div>
+  );
+}

package/template/apps/web/components/renderer/sections/VideoEmbed.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import { useState } from "react";
+import { Play } from "lucide-react";
+import { CmsImage } from "../CmsImage";
+import type { SectionProps } from "./types";
+
+type ParsedVideo = { provider: "youtube" | "vimeo" | "mp4" | null; embedUrl?: string; id?: string };
+
+function parseVideoUrl(url: string): ParsedVideo {
+  if (!url) return { provider: null };
+  const yt = url.match(/(?:youtube\.com\/watch\?v=|youtu\.be\/|youtube\.com\/embed\/)([\w-]+)/);
+  if (yt) return { provider: "youtube", id: yt[1], embedUrl: `https://www.youtube-nocookie.com/embed/${yt[1]}?autoplay=1` };
+  const vim = url.match(/vimeo\.com\/(\d+)/);
+  if (vim) return { provider: "vimeo", id: vim[1], embedUrl: `https://player.vimeo.com/video/${vim[1]}?autoplay=1` };
+  if (/\.(mp4|webm|ogg)(\?|$)/i.test(url)) return { provider: "mp4" };
+  return { provider: null };
+}
+
+// Renders a static thumbnail + play button instead of an always-live iframe, so a page
+// with several videos doesn't pay YouTube/Vimeo's heavy embed script cost until a
+// visitor actually presses play.
+export function VideoEmbed({ node }: SectionProps) {
+  const url = (node.props.url as string) || "";
+  const customThumbnail = (node.props.thumbnail as string) || "";
+  const aspectRatio = (node.props.aspectRatio as string) || "16/9";
+  const [playing, setPlaying] = useState(false);
+  const parsed = parseVideoUrl(url);
+
+  if (!url || !parsed.provider) {
+    return (
+      <div className="h-48 flex items-center justify-center bg-slate-100 text-slate-400 text-sm rounded-lg">
+        Add a YouTube, Vimeo, or direct MP4 URL
+      </div>
+    );
+  }
+
+  if (parsed.provider === "mp4") {
+    return (
+      <div className="rounded-lg overflow-hidden" style={{ aspectRatio }}>
+        {/* eslint-disable-next-line jsx-a11y/media-has-caption */}
+        <video src={url} controls className="w-full h-full object-cover" />
+      </div>
+    );
+  }
+
+  const thumbnail =
+    customThumbnail || (parsed.provider === "youtube" ? `https://img.youtube.com/vi/${parsed.id}/hqdefault.jpg` : "");
+
+  return (
+    <div className="relative rounded-lg overflow-hidden bg-slate-900" style={{ aspectRatio }}>
+      {playing ? (
+        <iframe
+          src={parsed.embedUrl}
+          title="Video player"
+          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+          allowFullScreen
+          className="absolute inset-0 w-full h-full border-0"
+        />
+      ) : (
+        <button onClick={() => setPlaying(true)} className="absolute inset-0 flex items-center justify-center group" aria-label="Play video">
+          {thumbnail && <CmsImage src={thumbnail} alt="" fill className="object-cover opacity-90" />}
+          <span className="relative z-10 flex items-center justify-center w-16 h-16 rounded-full bg-white/90 group-hover:bg-white transition-colors">
+            <Play size={28} className="text-slate-900 ml-1" fill="currentColor" />
+          </span>
+        </button>
+      )}
+    </div>
+  );
+}

package/template/apps/web/components/renderer/sections/types.ts

@@ -0,0 +1,7 @@
+import type { PageNode } from "@pgcms/shared";
+import type { ReactNode } from "react";
+
+export type SectionProps = {
+  node: PageNode;
+  children?: ReactNode;
+};

package/template/apps/web/components/seo/JsonLd.tsx

@@ -0,0 +1,111 @@
+import type { Page, PageNode, SiteTheme } from "@pgcms/shared";
+
+const SITE_URL = process.env.SITE_URL ?? "http://localhost:3000";
+
+type FaqItem = { question: string; answer: string };
+
+/** Collects every accordion's question/answer pairs across the whole tree — an
+ * accordion is the CMS's FAQ block (see components.ts), so any page using one for
+ * real Q&A content earns FAQPage rich-result eligibility for free. */
+function collectFaqItems(node: PageNode): FaqItem[] {
+  const items: FaqItem[] = [];
+  function walk(n: PageNode) {
+    if (n.type === "accordion") {
+      const raw = (n.props.items as { question?: string; answer?: string }[]) ?? [];
+      for (const it of raw) {
+        if (it.question && it.answer) items.push({ question: it.question, answer: it.answer });
+      }
+    }
+    n.children.forEach(walk);
+  }
+  walk(node);
+  return items;
+}
+
+/** JSON-LD structured data for public pages — helps search engines understand content.
+ * Emits one primary entity (WebPage for ordinary pages, Article for collection items
+ * like blog posts) plus a BreadcrumbList derived from the URL, plus an FAQPage entity
+ * whenever the content actually contains FAQ-shaped content (see collectFaqItems). */
+export function JsonLd({
+  page,
+  theme,
+  url,
+  contentType = "page",
+  datePublished,
+}: {
+  page: Pick<Page, "title" | "seoTitle" | "seoDescription" | "ogImage" | "content">;
+  theme: Pick<SiteTheme, "siteName">;
+  url: string;
+  /** "collectionItem" (a blog post, a news item...) renders as Article instead of
+   * WebPage — Article is what search engines expect for dated, authored content. */
+  contentType?: "page" | "collectionItem";
+  datePublished?: string | null;
+}) {
+  const name = page.seoTitle || page.title;
+  const description = page.seoDescription ?? undefined;
+
+  const primary =
+    contentType === "collectionItem"
+      ? {
+          "@type": "Article",
+          headline: name,
+          description,
+          url,
+          ...(page.ogImage ? { image: page.ogImage } : {}),
+          ...(datePublished ? { datePublished } : {}),
+          publisher: { "@type": "Organization", name: theme.siteName },
+        }
+      : {
+          "@type": "WebPage",
+          name,
+          description,
+          url,
+          isPartOf: { "@type": "WebSite", name: theme.siteName, url: SITE_URL },
+          ...(page.ogImage ? { image: page.ogImage } : {}),
+        };
+
+  const segments = new URL(url).pathname.split("/").filter(Boolean);
+  const breadcrumb =
+    segments.length > 0
+      ? {
+          "@type": "BreadcrumbList",
+          itemListElement: [
+            { "@type": "ListItem", position: 1, name: theme.siteName, item: SITE_URL },
+            ...segments.map((seg, i) => ({
+              "@type": "ListItem",
+              position: i + 2,
+              name: decodeURIComponent(seg).replace(/-/g, " "),
+              item: `${SITE_URL}/${segments.slice(0, i + 1).join("/")}`,
+            })),
+          ],
+        }
+      : null;
+
+  const faqItems = collectFaqItems(page.content);
+  const faq =
+    faqItems.length > 0
+      ? {
+          "@type": "FAQPage",
+          mainEntity: faqItems.map((item) => ({
+            "@type": "Question",
+            name: item.question,
+            acceptedAnswer: { "@type": "Answer", text: item.answer },
+          })),
+        }
+      : null;
+
+  const schemas = [
+    { "@context": "https://schema.org", ...primary },
+    ...(breadcrumb ? [{ "@context": "https://schema.org", ...breadcrumb }] : []),
+    ...(faq ? [{ "@context": "https://schema.org", ...faq }] : []),
+  ];
+
+  return (
+    <>
+      {schemas.map((schema, i) => (
+        // eslint-disable-next-line react/no-array-index-key
+        <script key={i} type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }} />
+      ))}
+    </>
+  );
+}

package/template/apps/web/components/theme/AnalyticsScripts.tsx

@@ -0,0 +1,68 @@
+"use client";
+
+import { useEffect } from "react";
+import Script from "next/script";
+import type { SiteTheme } from "@pgcms/shared";
+
+/** Browsers never execute <script> tags inserted via innerHTML — parses the admin's
+ * pasted snippet and recreates each script node with document.createElement, which
+ * DOES execute, so a pasted "<script src=...></script><script>...</script>" snippet
+ * (the common shape third-party analytics vendors hand out) actually runs. */
+function CustomScript({ html }: { html: string }) {
+  useEffect(() => {
+    const container = document.createElement("div");
+    container.innerHTML = html;
+    const nodes = Array.from(container.childNodes);
+    const inserted: HTMLElement[] = [];
+    for (const node of nodes) {
+      if (node.nodeName === "SCRIPT") {
+        const source = node as HTMLScriptElement;
+        const script = document.createElement("script");
+        for (const attr of Array.from(source.attributes)) script.setAttribute(attr.name, attr.value);
+        script.text = source.text;
+        document.body.appendChild(script);
+        inserted.push(script);
+      } else {
+        document.body.appendChild(node.cloneNode(true) as HTMLElement);
+      }
+    }
+    return () => inserted.forEach((el) => el.remove());
+  }, [html]);
+
+  return null;
+}
+
+/** Renders whichever analytics snippet the site owner picked in Theme Settings.
+ * Lives alongside ThemeStyleTag/JsonLd (per-request, where theme data is already
+ * loaded) rather than the static root layout. */
+export function AnalyticsScripts({
+  theme,
+}: {
+  theme: Pick<SiteTheme, "analyticsProvider" | "analyticsId" | "analyticsCustomScript">;
+}) {
+  if (theme.analyticsProvider === "ga4" && theme.analyticsId) {
+    return (
+      <>
+        <Script src={`https://www.googletagmanager.com/gtag/js?id=${theme.analyticsId}`} strategy="afterInteractive" />
+        <Script id="ga4-init" strategy="afterInteractive">
+          {`window.dataLayer = window.dataLayer || [];
+function gtag(){dataLayer.push(arguments);}
+gtag('js', new Date());
+gtag('config', '${theme.analyticsId}');`}
+        </Script>
+      </>
+    );
+  }
+
+  if (theme.analyticsProvider === "plausible" && theme.analyticsId) {
+    return <Script defer data-domain={theme.analyticsId} src="https://plausible.io/js/script.js" strategy="afterInteractive" />;
+  }
+
+  if (theme.analyticsProvider === "custom" && theme.analyticsCustomScript) {
+    // Trusted-admin escape hatch, same trust boundary as the existing customCss field —
+    // whoever can edit Theme Settings can already inject arbitrary CSS/attributes.
+    return <CustomScript html={theme.analyticsCustomScript} />;
+  }
+
+  return null;
+}

package/template/apps/web/components/theme/DarkModeToggle.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Moon, Sun } from "lucide-react";
+
+const STORAGE_KEY = "pgcms-theme";
+
+// Rendered only when the site theme has dark mode enabled (see [[...slug]]/page.tsx).
+// Flips the `data-theme` attribute the layout's beforeInteractive script already sets
+// from localStorage/system preference, and persists the explicit choice going forward.
+export function DarkModeToggle() {
+  const [theme, setThemeState] = useState<"light" | "dark">("light");
+
+  useEffect(() => {
+    setThemeState((document.documentElement.getAttribute("data-theme") as "light" | "dark") || "light");
+  }, []);
+
+  function toggle() {
+    const next = theme === "dark" ? "light" : "dark";
+    setThemeState(next);
+    document.documentElement.setAttribute("data-theme", next);
+    try {
+      localStorage.setItem(STORAGE_KEY, next);
+    } catch {
+      // Storage disabled (private browsing) — the toggle still works for this page view.
+    }
+  }
+
+  return (
+    <button
+      onClick={toggle}
+      aria-label={theme === "dark" ? "Switch to light mode" : "Switch to dark mode"}
+      className="fixed top-6 right-6 z-50 flex items-center justify-center w-11 h-11 rounded-full shadow-lg transition-transform hover:scale-110"
+      style={{ backgroundColor: "var(--theme-primary)", color: "#ffffff" }}
+    >
+      {theme === "dark" ? <Sun size={20} /> : <Moon size={20} />}
+    </button>
+  );
+}

package/template/apps/web/components/theme/SiteDataContext.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import type { NavItem, PageTranslationInfo, SiteTheme } from "@pgcms/shared";
+
+export type SiteDataValue = {
+  theme: SiteTheme;
+  navItems: NavItem[];
+  /** The current page's locale + its translation group — feeds the Language Switcher
+   * component. Absent in contexts without a current page (builder canvas). */
+  pageLocale?: string;
+  translations?: PageTranslationInfo[];
+};
+
+const defaultTheme: SiteTheme = {
+  primaryColor: "#2563eb",
+  secondaryColor: "#0f172a",
+  backgroundColor: "#ffffff",
+  textColor: "#111827",
+  headingFont: "Poppins",
+  bodyFont: "Inter",
+  siteName: "My Site",
+  logoUrl: null,
+  faviconUrl: null,
+  customCss: null,
+  darkModeEnabled: false,
+  primaryColorDark: null,
+  backgroundColorDark: null,
+  textColorDark: null,
+  analyticsProvider: "none",
+  analyticsId: null,
+  analyticsCustomScript: null,
+};
+
+export const SiteDataContext = createContext<SiteDataValue>({ theme: defaultTheme, navItems: [] });
+
+export function useSiteData() {
+  return useContext(SiteDataContext);
+}

package/template/apps/web/components/theme/ThemeProvider.tsx

@@ -0,0 +1,58 @@
+import type { SiteTheme } from "@pgcms/shared";
+
+export function themeToCssVars(theme: Partial<SiteTheme>): React.CSSProperties {
+  return {
+    ["--theme-primary" as any]: theme.primaryColor,
+    ["--theme-secondary" as any]: theme.secondaryColor,
+    ["--theme-bg" as any]: theme.backgroundColor,
+    ["--theme-text" as any]: theme.textColor,
+    ["--theme-heading-font" as any]: theme.headingFont ? `"${theme.headingFont}", sans-serif` : undefined,
+    ["--theme-body-font" as any]: theme.bodyFont ? `"${theme.bodyFont}", sans-serif` : undefined,
+  };
+}
+
+/** Dark-token overrides, applied under `:root[data-theme="dark"]` (see the
+ * beforeInteractive script in layout.tsx that sets the attribute). Blank fields fall
+ * back to sensible computed defaults rather than the light colors, so turning dark
+ * mode on without picking custom dark colors still looks like a real dark theme. */
+function darkThemeToCssVars(theme: Partial<SiteTheme>): React.CSSProperties {
+  return {
+    ["--theme-primary" as any]: theme.primaryColorDark || theme.primaryColor,
+    ["--theme-bg" as any]: theme.backgroundColorDark || "#0f172a",
+    ["--theme-text" as any]: theme.textColorDark || "#f1f5f9",
+  };
+}
+
+export function ThemeStyleTag({ theme }: { theme: Partial<SiteTheme> }) {
+  const vars = themeToCssVars(theme);
+  const cssVarString = Object.entries(vars)
+    .filter(([, v]) => v !== undefined)
+    .map(([k, v]) => `${k}: ${v};`)
+    .join(" ");
+
+  const darkVars = darkThemeToCssVars(theme);
+  const darkCssVarString = Object.entries(darkVars)
+    .filter(([, v]) => v !== undefined)
+    .map(([k, v]) => `${k}: ${v};`)
+    .join(" ");
+
+  const fontFamilies = [theme.headingFont, theme.bodyFont].filter(Boolean) as string[];
+  const fontsHref = fontFamilies.length
+    ? `https://fonts.googleapis.com/css2?${fontFamilies
+        .map((f) => `family=${encodeURIComponent(f)}:wght@400;500;600;700`)
+        .join("&")}&display=swap`
+    : null;
+
+  return (
+    <>
+      {fontsHref && <link rel="stylesheet" href={fontsHref} />}
+      <style
+        dangerouslySetInnerHTML={{
+          __html: `:root { ${cssVarString} } ${
+            theme.darkModeEnabled ? `:root[data-theme="dark"] { ${darkCssVarString} }` : ""
+          } ${theme.customCss ?? ""}`,
+        }}
+      />
+    </>
+  );
+}

package/template/apps/web/eslint.config.mjs

@@ -0,0 +1,16 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTypescript from "eslint-config-next/typescript";
+
+export default defineConfig([
+  ...nextVitals,
+  ...nextTypescript,
+  {
+    settings: {
+      next: {
+        rootDir: ".",
+      },
+    },
+  },
+  globalIgnores([".next/**", "out/**", "build/**", "next-env.d.ts"]),
+]);

package/template/apps/web/lib/api.ts

@@ -0,0 +1,45 @@
+export class ApiError extends Error {
+  status: number;
+  constructor(status: number, message: string) {
+    super(message);
+    this.status = status;
+  }
+}
+
+// Browser client: always relative — requests go through the Next.js dev/prod server,
+// which rewrites /api/* to the Express API (see next.config.mjs). This keeps the auth
+// cookie first-party even though Express runs on a different port.
+async function request<T>(path: string, options: RequestInit = {}): Promise<T> {
+  const res = await fetch(path, {
+    ...options,
+    credentials: "include",
+    headers: {
+      ...(options.body && !(options.body instanceof FormData) ? { "Content-Type": "application/json" } : {}),
+      ...options.headers,
+    },
+    cache: "no-store",
+  });
+
+  if (!res.ok) {
+    let message = res.statusText;
+    try {
+      const body = await res.json();
+      message = body.error ? (typeof body.error === "string" ? body.error : JSON.stringify(body.error)) : message;
+    } catch {
+      // ignore
+    }
+    throw new ApiError(res.status, message);
+  }
+
+  if (res.status === 204) return undefined as T;
+  return res.json() as Promise<T>;
+}
+
+export const api = {
+  get: <T>(path: string) => request<T>(path),
+  post: <T>(path: string, body?: unknown) =>
+    request<T>(path, { method: "POST", body: body instanceof FormData ? body : JSON.stringify(body) }),
+  put: <T>(path: string, body?: unknown) =>
+    request<T>(path, { method: "PUT", body: body instanceof FormData ? body : JSON.stringify(body) }),
+  delete: <T>(path: string) => request<T>(path, { method: "DELETE" }),
+};