doccupine 0.0.88 → 0.0.89

package/README.md

@@ -129,7 +129,7 @@ Place these JSON files in your project root (where you run `doccupine`). They ar
 | File              | Purpose                                                                                                   |
 | ----------------- | --------------------------------------------------------------------------------------------------------- |
 | `doccupine.json`  | CLI config (watchDir, outputDir, port). Auto-generated on first run.                                      |
-| `config.json`     | Site metadata: `name`, `description`, `icon`, `image` URL                                                 |
+| `config.json`     | Site metadata: `name`, `description`, `icon`, `image`, `url` (public site URL for sitemap/robots)         |
 | `theme.json`      | Theme overrides for [cherry-styled-components](https://github.com/cherry-design-system/styled-components) |
 | `navigation.json` | Manual navigation structure (overrides auto-generated)                                                    |
 | `links.json`      | Static header/footer links                                                                                |
@@ -139,7 +139,20 @@ Place these JSON files in your project root (where you run `doccupine`). They ar
 
 ## Public Directory
 
-Place static assets (images, favicons, `robots.txt`, etc.) in a `public/` directory at your project root. Doccupine copies it to the generated Next.js app on startup and watches for changes, so added, modified, or deleted files are synced automatically.
+Place static assets (images, favicons, etc.) in a `public/` directory at your project root. Doccupine copies it to the generated Next.js app on startup and watches for changes, so added, modified, or deleted files are synced automatically.
+
+## Sitemap and robots.txt
+
+Doccupine generates `robots.ts` automatically for every site. When you set a `url` in `config.json`, it also generates `sitemap.ts` covering every page (across all sections) and links the sitemap from `robots.txt`.
+
+```json
+{
+  "name": "My Docs",
+  "url": "https://docs.example.com"
+}
+```
+
+You can override the URL at deploy time by setting the `NEXT_PUBLIC_SITE_URL` environment variable. When no URL is configured (neither in `config.json` nor via env), the sitemap is skipped and `robots.txt` is emitted without a sitemap reference.
 
 ## AI Chat Setup
 

package/dist/index.js

@@ -10,7 +10,7 @@ import { appStructure, startingDocsStructure } from "./lib/structures.js";
 import { layoutTemplate } from "./lib/layout.js";
 import { ConfigManager } from "./lib/config-manager.js";
 import { findAvailablePort, generateSlug, getFullSlug, escapeTemplateContent, } from "./lib/utils.js";
-import { generateMetadataBlock, generateRuntimeOnlyMetadataBlock, } from "./lib/metadata.js";
+import { generateMetadataBlock, generateRuntimeOnlyMetadataBlock, generateJsonLdScript, } from "./lib/metadata.js";
 import { nextConfigTemplate } from "./templates/next.config.js";
 import { proxyTemplate } from "./templates/proxy.js";
 import { robotsTemplate } from "./templates/app/robots.js";
@@ -786,6 +786,20 @@ export default function SectionIndex() {
             description: fm.description,
             icon: fm.icon,
             image: fm.image,
+            canonicalPath: mdxFile.slug,
+        });
+        const jsonLd = generateJsonLdScript({
+            kind: "article",
+            canonicalPath: mdxFile.slug,
+            title: fm.title,
+            description: fm.description,
+            date: typeof fm.date === "string" ? fm.date : undefined,
+            updated: typeof fm.updated === "string"
+                ? fm.updated
+                : typeof fm.date === "string"
+                    ? fm.date
+                    : undefined,
+            image: fm.image,
         });
         const pageContent = `import { Metadata } from "next";
 import { Docs } from "@/components/Docs";
@@ -795,8 +809,21 @@ const content = \`${escapeTemplateContent(mdxFile.content)}\`;
 
 ${metadataBlock}
 
+// Doc pages have no per-request data: theme resolves client-side via the
+// "dark" class on <html> (set before paint by the theme-init blocking
+// script). Static rendering lets every response come from the edge cache.
+export const dynamic = "force-static";
+export const revalidate = false;
+
 export default function Page() {
-  return <Docs content={content} />;
+  ${jsonLd.declarations}
+
+  return (
+    <>
+      ${jsonLd.element}
+      <Docs content={content} />
+    </>
+  );
 }
 `;
         const pagePath = path.join(this.outputDir, "app", mdxFile.slug, "page.tsx");
@@ -818,6 +845,10 @@ export default function Page() {
                     icon: frontmatter.icon,
                     image: frontmatter.image,
                     name: frontmatter.name,
+                    date: typeof frontmatter.date === "string" ? frontmatter.date : undefined,
+                    updated: typeof frontmatter.updated === "string"
+                        ? frontmatter.updated
+                        : undefined,
                 };
                 break;
             }
@@ -831,8 +862,18 @@ export default function Page() {
                 description: indexMDX.description || undefined,
                 icon: indexMDX.icon,
                 image: indexMDX.image,
+                canonicalPath: "",
             })
             : generateRuntimeOnlyMetadataBlock();
+        const homeJsonLd = generateJsonLdScript({
+            kind: "homepage",
+            canonicalPath: "",
+            title: indexMDX?.title,
+            description: indexMDX?.description || undefined,
+            date: indexMDX?.date,
+            updated: indexMDX?.updated ?? indexMDX?.date,
+            image: indexMDX?.image,
+        });
         const indexContent = `import { Metadata } from "next";
 import { Docs } from "@/components/Docs";
 import { config } from "@/utils/config";
@@ -841,8 +882,18 @@ ${indexMDX ? `const content = \`${escapeTemplateContent(indexMDX.content)}\`;` :
 
 ${metadataBlock}
 
+export const dynamic = "force-static";
+export const revalidate = false;
+
 export default function Home() {
-  return <Docs content={content} />;
+  ${homeJsonLd.declarations}
+
+  return (
+    <>
+      ${homeJsonLd.element}
+      <Docs content={content} />
+    </>
+  );
 }
 `;
         await fs.writeFile(path.join(this.outputDir, "app", "page.tsx"), indexContent, "utf8");
@@ -856,6 +907,20 @@ export default function Home() {
             description: frontmatter.description || undefined,
             icon: frontmatter.icon,
             image: frontmatter.image,
+            canonicalPath: sectionSlug,
+        });
+        const sectionJsonLd = generateJsonLdScript({
+            kind: "article",
+            canonicalPath: sectionSlug,
+            title: frontmatter.title,
+            description: frontmatter.description,
+            date: typeof frontmatter.date === "string" ? frontmatter.date : undefined,
+            updated: typeof frontmatter.updated === "string"
+                ? frontmatter.updated
+                : typeof frontmatter.date === "string"
+                    ? frontmatter.date
+                    : undefined,
+            image: frontmatter.image,
         });
         const indexContent = `import { Metadata } from "next";
 import { Docs } from "@/components/Docs";
@@ -865,8 +930,18 @@ const content = \`${escapeTemplateContent(mdxContent)}\`;
 
 ${metadataBlock}
 
+export const dynamic = "force-static";
+export const revalidate = false;
+
 export default function Page() {
-  return <Docs content={content} />;
+  ${sectionJsonLd.declarations}
+
+  return (
+    <>
+      ${sectionJsonLd.element}
+      <Docs content={content} />
+    </>
+  );
 }
 `;
         const pagePath = path.join(this.outputDir, "app", sectionSlug, "page.tsx");

package/dist/lib/layout.js

@@ -48,9 +48,8 @@ ${a}            >`
     return `import type { Metadata } from "next";
 ${isGoogleFont(fontConfig) ? `import { ${fontConfig.googleFont.fontName} } from "next/font/google";` : isLocalFont(fontConfig) ? 'import localFont from "next/font/local";' : 'import { Inter } from "next/font/google";'}
 import dynamic from "next/dynamic";
-import Script from "next/script";
 import { StyledComponentsRegistry } from "cherry-styled-components";
-import { theme, themeDark } from "@/app/theme";
+import { theme } from "@/app/theme";
 import { CherryThemeProvider } from "@/components/layout/CherryThemeProvider";
 import { ChtProvider } from "@/components/Chat";
 import { SearchProvider } from "@/components/SearchDocs";
@@ -90,7 +89,18 @@ ${isGoogleFont(fontConfig)
 });`
             : 'const font = Inter({ subsets: ["latin"] });'}
 
+function resolveSiteUrl(): URL | undefined {
+  const raw = process.env.NEXT_PUBLIC_SITE_URL ?? config.url;
+  if (!raw || typeof raw !== "string") return undefined;
+  try {
+    return new URL(raw);
+  } catch {
+    return undefined;
+  }
+}
+
 export const metadata: Metadata = {
+  metadataBase: resolveSiteUrl(),
   title: config.name || "${DEFAULT_SITE_NAME}",
   description:
     config.description ||
@@ -118,24 +128,26 @@ ${hasSections
   const pages: PagesProps[] = doccupinePages;
 
   return (
-    <html lang="en">
+    <html lang="en" suppressHydrationWarning>
       <head>
-        {/* Prevents dark-mode FOUC on Safari/Firefox. These browsers don't support
-            Sec-CH-Prefers-Color-Scheme (handled by middleware for Chrome), so on
-            a first visit this blocking script detects prefers-color-scheme, sets
-            the theme cookie, and hides the body until router.refresh() re-renders
-            with the correct theme (see ClientThemeProvider). */}
-        <Script
-          id="theme-init"
-          strategy="beforeInteractive"
+        {/* Resolves dark mode before first paint by adding the "dark" class
+            to <html> when needed. CSS variables in GlobalStyles flip values
+            on :root vs :root.dark, so the right palette renders without a
+            React roundtrip. Inlined as a plain <script> (not next/script) so
+            it ships in the SSR HTML and runs synchronously before paint —
+            next/script with beforeInteractive is async in App Router and
+            would still show a flash. suppressHydrationWarning on <html>
+            tells React the class/colorScheme attributes are intentionally
+            different between server (no class) and client (after script). */}
+        <script
           dangerouslySetInnerHTML={{
-            __html: \`(function(){try{var c=document.cookie.split(";").find(function(s){return s.trim().startsWith("theme=")});if(!c){var d=window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches;document.cookie="theme="+(d?"dark":"light")+";path=/;max-age=31536000;SameSite=Lax";if(d){var s=document.createElement("style");s.id="__theme-init";s.textContent="html{background:#000!important;color-scheme:dark}body{visibility:hidden}";document.head.appendChild(s)}}}catch(e){}})();\`,
+            __html: \`(function(){try{var c=document.cookie.split(";").map(function(s){return s.trim();}).find(function(s){return s.indexOf("theme=")===0;});var v=c?c.split("=")[1]:null;var d=v?v==="dark":(window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches);if(!v){document.cookie="theme="+(d?"dark":"light")+";path=/;max-age=31536000;SameSite=Lax";}if(d){document.documentElement.classList.add("dark");document.documentElement.style.colorScheme="dark";}else{document.documentElement.style.colorScheme="light";}}catch(e){}})();\`,
           }}
         />
       </head>
       <body className={font.className}>
         <StyledComponentsRegistry>
-${analyticsEnabled ? "          <PostHogProvider>\n" : ""}${a}          <CherryThemeProvider theme={theme} themeDark={themeDark}>
+${analyticsEnabled ? "          <PostHogProvider>\n" : ""}${a}          <CherryThemeProvider theme={theme}>
 ${a}            ${chtOpen}
 ${a}              <SearchProvider pages={pages} sections={doccupineSections}>
 ${a}                <Header>
@@ -181,24 +193,26 @@ ${analyticsEnabled ? "          </PostHogProvider>\n" : ""}        </StyledCompo
   const defaultResults = transformPagesToGroupedStructure(defaultPages);
 
   return (
-    <html lang="en">
+    <html lang="en" suppressHydrationWarning>
       <head>
-        {/* Prevents dark-mode FOUC on Safari/Firefox. These browsers don't support
-            Sec-CH-Prefers-Color-Scheme (handled by middleware for Chrome), so on
-            a first visit this blocking script detects prefers-color-scheme, sets
-            the theme cookie, and hides the body until router.refresh() re-renders
-            with the correct theme (see ClientThemeProvider). */}
-        <Script
-          id="theme-init"
-          strategy="beforeInteractive"
+        {/* Resolves dark mode before first paint by adding the "dark" class
+            to <html> when needed. CSS variables in GlobalStyles flip values
+            on :root vs :root.dark, so the right palette renders without a
+            React roundtrip. Inlined as a plain <script> (not next/script) so
+            it ships in the SSR HTML and runs synchronously before paint —
+            next/script with beforeInteractive is async in App Router and
+            would still show a flash. suppressHydrationWarning on <html>
+            tells React the class/colorScheme attributes are intentionally
+            different between server (no class) and client (after script). */}
+        <script
           dangerouslySetInnerHTML={{
-            __html: \`(function(){try{var c=document.cookie.split(";").find(function(s){return s.trim().startsWith("theme=")});if(!c){var d=window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches;document.cookie="theme="+(d?"dark":"light")+";path=/;max-age=31536000;SameSite=Lax";if(d){var s=document.createElement("style");s.id="__theme-init";s.textContent="html{background:#000!important;color-scheme:dark}body{visibility:hidden}";document.head.appendChild(s)}}}catch(e){}})();\`,
+            __html: \`(function(){try{var c=document.cookie.split(";").map(function(s){return s.trim();}).find(function(s){return s.indexOf("theme=")===0;});var v=c?c.split("=")[1]:null;var d=v?v==="dark":(window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches);if(!v){document.cookie="theme="+(d?"dark":"light")+";path=/;max-age=31536000;SameSite=Lax";}if(d){document.documentElement.classList.add("dark");document.documentElement.style.colorScheme="dark";}else{document.documentElement.style.colorScheme="light";}}catch(e){}})();\`,
           }}
         />
       </head>
       <body className={font.className}>
         <StyledComponentsRegistry>
-${analyticsEnabled ? "          <PostHogProvider>\n" : ""}${a}          <CherryThemeProvider theme={theme} themeDark={themeDark}>
+${analyticsEnabled ? "          <PostHogProvider>\n" : ""}${a}          <CherryThemeProvider theme={theme}>
 ${a}            ${chtOpen}
 ${a}              <SearchProvider pages={pages}>
 ${a}                <Header />

package/dist/lib/metadata.d.ts

@@ -1,3 +1,28 @@
+export type JsonLdKind = "article" | "homepage";
+export interface JsonLdOptions {
+    kind: JsonLdKind;
+    /** Page slug ("" for homepage). Used to build the absolute URL with config.url. */
+    canonicalPath: string;
+    title?: string;
+    description?: string;
+    date?: string;
+    /** Optional last-modified date; defaults to date when present. */
+    updated?: string;
+    image?: string;
+}
+/**
+ * Returns a code snippet that:
+ *  - declares a `jsonLd` object at runtime using the site's config,
+ *  - and renders a single `<script type="application/ld+json">` element.
+ *
+ * The snippet is meant to be inlined inside a generated page component.
+ * It emits a TechArticle on every doc page; the homepage additionally
+ * emits a graph that includes an Organization entity for entity recognition.
+ */
+export declare function generateJsonLdScript(opts: JsonLdOptions): {
+    declarations: string;
+    element: string;
+};
 export interface MetadataOptions {
     title?: string;
     titleFallback: string;
@@ -6,6 +31,11 @@ export interface MetadataOptions {
     description?: string;
     icon?: string;
     image?: string;
+    /**
+     * Canonical path for this page, e.g. "" for the homepage or "components".
+     * Resolves against `metadataBase` defined in the root layout.
+     */
+    canonicalPath?: string;
 }
 export declare function generateMetadataBlock(opts: MetadataOptions): string;
 export declare function generateRuntimeOnlyMetadataBlock(): string;

package/dist/lib/metadata.js

@@ -1,4 +1,91 @@
 import { DEFAULT_FAVICON, DEFAULT_META_DESCRIPTION, DEFAULT_OG_IMAGE, DEFAULT_SITE_NAME, } from "./constants.js";
+/**
+ * Returns a code snippet that:
+ *  - declares a `jsonLd` object at runtime using the site's config,
+ *  - and renders a single `<script type="application/ld+json">` element.
+ *
+ * The snippet is meant to be inlined inside a generated page component.
+ * It emits a TechArticle on every doc page; the homepage additionally
+ * emits a graph that includes an Organization entity for entity recognition.
+ */
+export function generateJsonLdScript(opts) {
+    const safePath = opts.canonicalPath.replace(/^\/+/, "");
+    const titleLiteral = JSON.stringify(opts.title ?? DEFAULT_SITE_NAME);
+    const descLiteral = JSON.stringify(opts.description ?? DEFAULT_META_DESCRIPTION);
+    const dateLiteral = opts.date ? JSON.stringify(opts.date) : "undefined";
+    const updatedLiteral = opts.updated
+        ? JSON.stringify(opts.updated)
+        : opts.date
+            ? JSON.stringify(opts.date)
+            : "undefined";
+    const defaultFaviconLiteral = JSON.stringify(DEFAULT_FAVICON);
+    const faviconLine = opts.image
+        ? `const faviconUrl =
+      ${JSON.stringify(opts.image)} ||
+      config.icon ||
+      ${defaultFaviconLiteral};`
+        : `const faviconUrl = config.icon || ${defaultFaviconLiteral};`;
+    // Indent 10 + "description: ".length(13) + ",".length(1) = 24. Prettier
+    // wraps the value to the next line (indent 12) once total exceeds 80.
+    const descriptionLine = descLiteral.length > 56
+        ? `description:
+            ${descLiteral},`
+        : `description: ${descLiteral},`;
+    const pathLiteral = JSON.stringify(safePath);
+    const homepageGraph = opts.kind === "homepage"
+        ? `,
+        {
+          "@type": "Organization",
+          name: siteName,
+          url: baseUrl ?? undefined,
+          logo: faviconUrl,
+        }`
+        : "";
+    const declarations = `const __jsonLdBaseUrl = (() => {
+    const raw =
+      typeof process !== "undefined"
+        ? process.env.NEXT_PUBLIC_SITE_URL
+        : undefined;
+    const fromEnv = typeof raw === "string" && raw.trim() !== "" ? raw : null;
+    const fromConfig =
+      typeof config.url === "string" && config.url.trim() !== ""
+        ? config.url
+        : null;
+    return (fromEnv ?? fromConfig)?.replace(/\\/$/, "") ?? null;
+  })();
+  const __jsonLd = (() => {
+    const baseUrl = __jsonLdBaseUrl;
+    const path = ${pathLiteral};
+    const url = baseUrl ? (path ? \`\${baseUrl}/\${path}\` : baseUrl) : undefined;
+    const siteName = config.name || ${JSON.stringify(DEFAULT_SITE_NAME)};
+    ${faviconLine}
+    return {
+      "@context": "https://schema.org",
+      "@graph": [
+        {
+          "@type": "TechArticle",
+          headline: ${titleLiteral},
+          ${descriptionLine}
+          url,
+          mainEntityOfPage: url,
+          datePublished: ${dateLiteral},
+          dateModified: ${updatedLiteral},
+          author: { "@type": "Organization", name: siteName },
+          publisher: {
+            "@type": "Organization",
+            name: siteName,
+            logo: { "@type": "ImageObject", url: faviconUrl },
+          },
+        }${homepageGraph},
+      ],
+    };
+  })();`;
+    const element = `<script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(__jsonLd) }}
+      />`;
+    return { declarations, element };
+}
 function buildFieldExpression(staticValue, configKey, defaultValue) {
     if (staticValue)
         return staticValue;
@@ -18,15 +105,24 @@ function buildTitleExpression(opts) {
         : `\${config.name ? config.name + " -" : "${DEFAULT_SITE_NAME} -"}`;
     return `${prefix} ${title}`;
 }
+function buildCanonicalLine(canonicalPath) {
+    if (canonicalPath === undefined)
+        return "";
+    const safePath = canonicalPath.replace(/^\/+/, "");
+    // Relative path resolves against `metadataBase` set in the root layout.
+    // Empty string means the homepage canonical equals the base URL itself.
+    return `\n  alternates: { canonical: ${JSON.stringify("/" + safePath)} },`;
+}
 export function generateMetadataBlock(opts) {
     const title = buildTitleExpression(opts);
     const desc = buildFieldExpression(opts.description, "description", DEFAULT_META_DESCRIPTION);
     const icon = buildFieldExpression(opts.icon, "icon", DEFAULT_FAVICON);
     const image = buildFieldExpression(opts.image, "image", DEFAULT_OG_IMAGE);
+    const canonical = buildCanonicalLine(opts.canonicalPath);
     return `export const metadata: Metadata = {
   title: \`${title}\`,
   description: \`${desc}\`,
-  icons: \`${icon}\`,
+  icons: \`${icon}\`,${canonical}
   openGraph: {
     title: \`${title}\`,
     description: \`${desc}\`,
@@ -43,6 +139,7 @@ export function generateRuntimeOnlyMetadataBlock() {
   title: \`${title}\`,
   description: \`${desc}\`,
   icons: \`${icon}\`,
+  alternates: { canonical: "/" },
   openGraph: {
     title: \`${title}\`,
     description: \`${desc}\`,

package/dist/templates/app/theme.d.ts

@@ -1,3 +1,3 @@
 export declare const SIDEBAR_WIDTH = 280;
 export declare const CHAT_WIDTH = 420;
-export declare const themeTemplate = "\"use client\";\nimport customThemeJson from \"@/theme.json\";\n\ninterface CustomTheme {\n  default?: Partial<Colors>;\n  dark?: Partial<Colors>;\n}\n\nconst customTheme = customThemeJson as CustomTheme;\n\nconst breakpoints: Breakpoints = {\n  xs: 0,\n  sm: 576,\n  md: 768,\n  lg: 992,\n  xl: 1200,\n  xxl: 1440,\n  xxxl: 1920,\n};\n\nexport function mq(minWidth: keyof Breakpoints) {\n  return `@media screen and (min-width: ${breakpoints[minWidth]}px)`;\n}\n\nconst spacing: Spacing = {\n  maxWidth: { xs: \"1280px\", xxxl: \"1440px\" },\n  padding: { xs: \"20px\", lg: \"40px\" },\n  radius: { xs: \"6px\", lg: \"12px\", xl: \"30px\" },\n  gridGap: { xs: \"20px\", lg: \"40px\" },\n};\n\nconst colors: Colors = {\n  primaryLight: \"#d1d5db\",\n  primary: \"#556272\",\n  primaryDark: \"#374151\",\n  secondaryLight: \"#c4b5fd\",\n  secondary: \"#8b5cf6\",\n  secondaryDark: \"#5b21b6\",\n  tertiaryLight: \"#86efac\",\n  tertiary: \"#22c55e\",\n  tertiaryDark: \"#15803d\",\n  grayLight: \"#e5e7eb\",\n  gray: \"#9ca3af\",\n  grayDark: \"#4b5563\",\n  success: \"#84cc16\",\n  error: \"#ef4444\",\n  warning: \"#eab308\",\n  info: \"#06b6d4\",\n  dark: \"#000000\",\n  light: \"#ffffff\",\n  ...(customTheme.default ? (customTheme.default as Partial<Colors>) : {}),\n};\n\nconst colorsDark: Colors = {\n  primaryLight: \"#9ca3af\",\n  primary: \"#6b7280\",\n  primaryDark: \"#374151\",\n  secondaryLight: \"#ddd6fe\",\n  secondary: \"#a78bfa\",\n  secondaryDark: \"#7c3aed\",\n  tertiaryLight: \"#6ee7b7\",\n  tertiary: \"#10b981\",\n  tertiaryDark: \"#065f46\",\n  grayLight: \"#1a1a1a\",\n  gray: \"#454444\",\n  grayDark: \"#808080\",\n  success: \"#84cc16\",\n  error: \"#ef4444\",\n  warning: \"#eab308\",\n  info: \"#06b6d4\",\n  dark: \"#ffffff\",\n  light: \"#000000\",\n  ...(customTheme.dark ? (customTheme.dark as Partial<Colors>) : {}),\n};\n\nconst shadows: Shadows = {\n  xs: \"0px 4px 4px 0px rgba(18, 18, 18, 0.04), 0px 1px 3px 0px rgba(39, 41, 45, 0.02)\",\n  sm: \"0px 4px 4px 0px rgba(18, 18, 18, 0.08), 0px 1px 3px 0px rgba(39, 41, 45, 0.04)\",\n  md: \"0px 8px 8px 0px rgba(18, 18, 18, 0.16), 0px 2px 3px 0px rgba(39, 41, 45, 0.06)\",\n  lg: \"0px 16px 24px 0px rgba(18, 18, 18, 0.20), 0px 2px 3px 0px rgba(39, 41, 45, 0.08)\",\n  xl: \"0px 24px 32px 0px rgba(18, 18, 18, 0.24), 0px 2px 3px 0px rgba(39, 41, 45, 0.12)\",\n};\n\nconst shadowsDark: Shadows = {\n  xs: \"0px 4px 4px 0px rgba(255, 255, 255, 0.04), 0px 1px 3px 0px rgba(255, 255, 255, 0.02)\",\n  sm: \"0px 4px 4px 0px rgba(255, 255, 255, 0.08), 0px 1px 3px 0px rgba(255, 255, 255, 0.04)\",\n  md: \"0px 8px 8px 0px rgba(255, 255, 255, 0.16), 0px 2px 3px 0px rgba(255, 255, 255, 0.06)\",\n  lg: \"0px 16px 24px 0px rgba(255, 255, 255, 0.20), 0px 2px 3px 0px rgba(255, 255, 255, 0.08)\",\n  xl: \"0px 24px 32px 0px rgba(255, 255, 255, 0.24), 0px 2px 3px 0px rgba(255, 255, 255, 0.12)\",\n};\n\nconst fonts: Fonts = {\n  text: \"Inter\",\n  head: \"Inter\",\n  mono: \"Roboto Mono, monospace\",\n};\n\nconst fontSizes: FontSizes = {\n  hero1: { xs: \"72px\", lg: \"128px\" },\n  hero2: { xs: \"60px\", lg: \"96px\" },\n  hero3: { xs: \"36px\", lg: \"72px\" },\n\n  h1: { xs: \"40px\", lg: \"60px\" },\n  h2: { xs: \"30px\", lg: \"36px\" },\n  h3: { xs: \"28px\", lg: \"30px\" },\n  h4: { xs: \"24px\", lg: \"26px\" },\n  h5: { xs: \"18px\", lg: \"20px\" },\n  h6: { xs: \"16px\", lg: \"18px\" },\n\n  text: { xs: \"14px\", lg: \"16px\" },\n  strong: { xs: \"14px\", lg: \"16px\" },\n  small: { xs: \"12px\", lg: \"14px\" },\n\n  blockquote: { xs: \"16px\", lg: \"18px\" },\n  code: { xs: \"14px\", lg: \"16px\" },\n\n  button: { xs: \"16px\", lg: \"16px\" },\n  buttonBig: { xs: \"18px\", lg: \"18px\" },\n  buttonSmall: { xs: \"14px\", lg: \"14px\" },\n\n  input: { xs: \"16px\", lg: \"16px\" },\n  inputBig: { xs: \"18px\", lg: \"18px\" },\n  inputSmall: { xs: \"14px\", lg: \"14px\" },\n};\n\nconst lineHeights: LineHeights = {\n  hero1: { xs: \"1.1\", lg: \"1.1\" },\n  hero2: { xs: \"1.1\", lg: \"1.1\" },\n  hero3: { xs: \"1.17\", lg: \"1.1\" },\n\n  h1: { xs: \"1\", lg: \"1.07\" },\n  h2: { xs: \"1.2\", lg: \"1.2\" },\n  h3: { xs: \"1.3\", lg: \"1.5\" },\n  h4: { xs: \"1.3\", lg: \"1.5\" },\n  h5: { xs: \"1.6\", lg: \"1.5\" },\n  h6: { xs: \"1.6\", lg: \"1.6\" },\n\n  text: { xs: \"1.7\", lg: \"1.7\" },\n  strong: { xs: \"1.7\", lg: \"1.7\" },\n  small: { xs: \"1.7\", lg: \"1.7\" },\n\n  blockquote: { xs: \"1.7\", lg: \"1.7\" },\n  code: { xs: \"1.7\", lg: \"1.7\" },\n\n  button: { xs: \"1\", lg: \"1\" },\n  buttonBig: { xs: \"1\", lg: \"1\" },\n  buttonSmall: { xs: \"1\", lg: \"1\" },\n\n  input: { xs: \"1\", lg: \"1\" },\n  inputBig: { xs: \"1\", lg: \"1\" },\n  inputSmall: { xs: \"1\", lg: \"1\" },\n};\n\nexport const theme: Theme = {\n  breakpoints,\n  spacing,\n  colors,\n  shadows,\n  fonts,\n  fontSizes,\n  lineHeights,\n  isDark: false,\n};\n\nexport const themeDark: Theme = {\n  breakpoints,\n  spacing,\n  colors: colorsDark,\n  shadows: shadowsDark,\n  fonts,\n  fontSizes,\n  lineHeights,\n  isDark: true,\n};\n\ninterface Breakpoints<TNumber = number> {\n  xs: TNumber;\n  sm: TNumber;\n  md: TNumber;\n  lg: TNumber;\n  xl: TNumber;\n  xxl: TNumber;\n  xxxl: TNumber;\n}\n\ninterface Spacing<TString = string> {\n  maxWidth: { xs: TString; xxxl: TString };\n  padding: { xs: TString; lg: TString };\n  radius: { xs: TString; lg: TString; xl: TString };\n  gridGap: { xs: TString; lg: TString };\n}\n\ninterface Colors<TString = string> {\n  primaryLight: TString;\n  primary: TString;\n  primaryDark: TString;\n\n  secondaryLight: TString;\n  secondary: TString;\n  secondaryDark: TString;\n\n  tertiaryLight: TString;\n  tertiary: TString;\n  tertiaryDark: TString;\n\n  grayLight: TString;\n  gray: TString;\n  grayDark: TString;\n\n  success: TString;\n  error: TString;\n  warning: TString;\n  info: TString;\n\n  dark: TString;\n  light: TString;\n}\n\ninterface Shadows<TString = string> {\n  xs: TString;\n  sm: TString;\n  md: TString;\n  lg: TString;\n  xl: TString;\n}\n\ninterface Fonts<TString = string> {\n  head: TString;\n  text: TString;\n  mono: TString;\n}\n\ninterface FontSizes<TString = string> {\n  hero1: { xs: TString; lg: TString };\n  hero2: { xs: TString; lg: TString };\n  hero3: { xs: TString; lg: TString };\n\n  h1: { xs: TString; lg: TString };\n  h2: { xs: TString; lg: TString };\n  h3: { xs: TString; lg: TString };\n  h4: { xs: TString; lg: TString };\n  h5: { xs: TString; lg: TString };\n  h6: { xs: TString; lg: TString };\n\n  text: { xs: TString; lg: TString };\n  strong: { xs: TString; lg: TString };\n  small: { xs: TString; lg: TString };\n\n  blockquote: { xs: TString; lg: TString };\n  code: { xs: TString; lg: TString };\n\n  button: { xs: TString; lg: TString };\n  buttonBig: { xs: TString; lg: TString };\n  buttonSmall: { xs: TString; lg: TString };\n\n  input: { xs: TString; lg: TString };\n  inputBig: { xs: TString; lg: TString };\n  inputSmall: { xs: TString; lg: TString };\n}\n\ninterface LineHeights<TString = string> {\n  hero1: { xs: TString; lg: TString };\n  hero2: { xs: TString; lg: TString };\n  hero3: { xs: TString; lg: TString };\n\n  h1: { xs: TString; lg: TString };\n  h2: { xs: TString; lg: TString };\n  h3: { xs: TString; lg: TString };\n  h4: { xs: TString; lg: TString };\n  h5: { xs: TString; lg: TString };\n  h6: { xs: TString; lg: TString };\n\n  text: { xs: TString; lg: TString };\n  strong: { xs: TString; lg: TString };\n  small: { xs: TString; lg: TString };\n\n  blockquote: { xs: TString; lg: TString };\n  code: { xs: TString; lg: TString };\n\n  button: { xs: TString; lg: TString };\n  buttonBig: { xs: TString; lg: TString };\n  buttonSmall: { xs: TString; lg: TString };\n\n  input: { xs: TString; lg: TString };\n  inputBig: { xs: TString; lg: TString };\n  inputSmall: { xs: TString; lg: TString };\n}\n\nexport interface Theme {\n  breakpoints: Breakpoints;\n  spacing: Spacing;\n  colors: Colors;\n  shadows: Shadows;\n  fonts: Fonts;\n  fontSizes: FontSizes;\n  lineHeights: LineHeights;\n  isDark: boolean;\n}\n";
+export declare const themeTemplate = "\"use client\";\nimport customThemeJson from \"@/theme.json\";\n\n// Users can only override the brand palette via theme.json \u2014 semantic tokens\n// (accent, surface, etc.) are derived in GlobalStyles from the brand colors\n// and are not directly overridable.\ntype CustomColors = Omit<\n  Colors,\n  \"accent\" | \"accentStrong\" | \"accentMuted\" | \"surface\"\n>;\n\ninterface CustomTheme {\n  default?: Partial<CustomColors>;\n  dark?: Partial<CustomColors>;\n}\n\nconst customTheme = customThemeJson as CustomTheme;\n\nconst breakpoints: Breakpoints = {\n  xs: 0,\n  sm: 576,\n  md: 768,\n  lg: 992,\n  xl: 1200,\n  xxl: 1440,\n  xxxl: 1920,\n};\n\nexport function mq(minWidth: keyof Breakpoints) {\n  return `@media screen and (min-width: ${breakpoints[minWidth]}px)`;\n}\n\nconst spacing: Spacing = {\n  maxWidth: { xs: \"1280px\", xxxl: \"1440px\" },\n  padding: { xs: \"20px\", lg: \"40px\" },\n  radius: { xs: \"6px\", lg: \"12px\", xl: \"30px\" },\n  gridGap: { xs: \"20px\", lg: \"40px\" },\n};\n\n// Resolved hex palettes for each mode. GlobalStyles emits these as CSS\n// custom properties on :root and :root.dark. Components never read these\n// directly \u2014 they read `theme.colors.*` which resolves to var(--color-\u2026)\n// and lets the browser pick the right value based on the active class.\nexport const colorsLight: CustomColors = {\n  primaryLight: \"#d1d5db\",\n  primary: \"#556272\",\n  primaryDark: \"#374151\",\n  secondaryLight: \"#c4b5fd\",\n  secondary: \"#8b5cf6\",\n  secondaryDark: \"#5b21b6\",\n  tertiaryLight: \"#86efac\",\n  tertiary: \"#22c55e\",\n  tertiaryDark: \"#15803d\",\n  grayLight: \"#e5e7eb\",\n  gray: \"#9ca3af\",\n  grayDark: \"#4b5563\",\n  success: \"#84cc16\",\n  error: \"#ef4444\",\n  warning: \"#eab308\",\n  info: \"#06b6d4\",\n  dark: \"#000000\",\n  light: \"#ffffff\",\n  ...(customTheme.default\n    ? (customTheme.default as Partial<CustomColors>)\n    : {}),\n};\n\nexport const colorsDark: CustomColors = {\n  primaryLight: \"#9ca3af\",\n  primary: \"#6b7280\",\n  primaryDark: \"#374151\",\n  secondaryLight: \"#ddd6fe\",\n  secondary: \"#a78bfa\",\n  secondaryDark: \"#7c3aed\",\n  tertiaryLight: \"#6ee7b7\",\n  tertiary: \"#10b981\",\n  tertiaryDark: \"#065f46\",\n  grayLight: \"#1a1a1a\",\n  gray: \"#454444\",\n  grayDark: \"#808080\",\n  success: \"#84cc16\",\n  error: \"#ef4444\",\n  warning: \"#eab308\",\n  info: \"#06b6d4\",\n  dark: \"#ffffff\",\n  light: \"#000000\",\n  ...(customTheme.dark ? (customTheme.dark as Partial<CustomColors>) : {}),\n};\n\nexport const shadowsLight: Shadows = {\n  xs: \"0px 4px 4px 0px rgba(18, 18, 18, 0.04), 0px 1px 3px 0px rgba(39, 41, 45, 0.02)\",\n  sm: \"0px 4px 4px 0px rgba(18, 18, 18, 0.08), 0px 1px 3px 0px rgba(39, 41, 45, 0.04)\",\n  md: \"0px 8px 8px 0px rgba(18, 18, 18, 0.16), 0px 2px 3px 0px rgba(39, 41, 45, 0.06)\",\n  lg: \"0px 16px 24px 0px rgba(18, 18, 18, 0.20), 0px 2px 3px 0px rgba(39, 41, 45, 0.08)\",\n  xl: \"0px 24px 32px 0px rgba(18, 18, 18, 0.24), 0px 2px 3px 0px rgba(39, 41, 45, 0.12)\",\n};\n\nexport const shadowsDark: Shadows = {\n  xs: \"0px 4px 4px 0px rgba(255, 255, 255, 0.04), 0px 1px 3px 0px rgba(255, 255, 255, 0.02)\",\n  sm: \"0px 4px 4px 0px rgba(255, 255, 255, 0.08), 0px 1px 3px 0px rgba(255, 255, 255, 0.04)\",\n  md: \"0px 8px 8px 0px rgba(255, 255, 255, 0.16), 0px 2px 3px 0px rgba(255, 255, 255, 0.06)\",\n  lg: \"0px 16px 24px 0px rgba(255, 255, 255, 0.20), 0px 2px 3px 0px rgba(255, 255, 255, 0.08)\",\n  xl: \"0px 24px 32px 0px rgba(255, 255, 255, 0.24), 0px 2px 3px 0px rgba(255, 255, 255, 0.12)\",\n};\n\nconst fonts: Fonts = {\n  text: \"Inter\",\n  head: \"Inter\",\n  mono: \"Roboto Mono, monospace\",\n};\n\nconst fontSizes: FontSizes = {\n  hero1: { xs: \"72px\", lg: \"128px\" },\n  hero2: { xs: \"60px\", lg: \"96px\" },\n  hero3: { xs: \"36px\", lg: \"72px\" },\n\n  h1: { xs: \"40px\", lg: \"60px\" },\n  h2: { xs: \"30px\", lg: \"36px\" },\n  h3: { xs: \"28px\", lg: \"30px\" },\n  h4: { xs: \"24px\", lg: \"26px\" },\n  h5: { xs: \"18px\", lg: \"20px\" },\n  h6: { xs: \"16px\", lg: \"18px\" },\n\n  text: { xs: \"14px\", lg: \"16px\" },\n  strong: { xs: \"14px\", lg: \"16px\" },\n  small: { xs: \"12px\", lg: \"14px\" },\n\n  blockquote: { xs: \"16px\", lg: \"18px\" },\n  code: { xs: \"14px\", lg: \"16px\" },\n\n  button: { xs: \"16px\", lg: \"16px\" },\n  buttonBig: { xs: \"18px\", lg: \"18px\" },\n  buttonSmall: { xs: \"14px\", lg: \"14px\" },\n\n  input: { xs: \"16px\", lg: \"16px\" },\n  inputBig: { xs: \"18px\", lg: \"18px\" },\n  inputSmall: { xs: \"14px\", lg: \"14px\" },\n};\n\nconst lineHeights: LineHeights = {\n  hero1: { xs: \"1.1\", lg: \"1.1\" },\n  hero2: { xs: \"1.1\", lg: \"1.1\" },\n  hero3: { xs: \"1.17\", lg: \"1.1\" },\n\n  h1: { xs: \"1\", lg: \"1.07\" },\n  h2: { xs: \"1.2\", lg: \"1.2\" },\n  h3: { xs: \"1.3\", lg: \"1.5\" },\n  h4: { xs: \"1.3\", lg: \"1.5\" },\n  h5: { xs: \"1.6\", lg: \"1.5\" },\n  h6: { xs: \"1.6\", lg: \"1.6\" },\n\n  text: { xs: \"1.7\", lg: \"1.7\" },\n  strong: { xs: \"1.7\", lg: \"1.7\" },\n  small: { xs: \"1.7\", lg: \"1.7\" },\n\n  blockquote: { xs: \"1.7\", lg: \"1.7\" },\n  code: { xs: \"1.7\", lg: \"1.7\" },\n\n  button: { xs: \"1\", lg: \"1\" },\n  buttonBig: { xs: \"1\", lg: \"1\" },\n  buttonSmall: { xs: \"1\", lg: \"1\" },\n\n  input: { xs: \"1\", lg: \"1\" },\n  inputBig: { xs: \"1\", lg: \"1\" },\n  inputSmall: { xs: \"1\", lg: \"1\" },\n};\n\n// Single theme object exported to consumers. Every color/shadow value is a\n// CSS custom-property reference; the browser resolves it against :root or\n// :root.dark depending on the active class. Components access these exactly\n// like before \u2014 `theme.colors.primary`, `theme.shadows.sm` \u2014 but the values\n// flip without React re-rendering.\nconst colors: Colors = {\n  // Brand palette \u2014 directly customizable via theme.json's \"default\" / \"dark\".\n  primaryLight: \"var(--color-primaryLight)\",\n  primary: \"var(--color-primary)\",\n  primaryDark: \"var(--color-primaryDark)\",\n  secondaryLight: \"var(--color-secondaryLight)\",\n  secondary: \"var(--color-secondary)\",\n  secondaryDark: \"var(--color-secondaryDark)\",\n  tertiaryLight: \"var(--color-tertiaryLight)\",\n  tertiary: \"var(--color-tertiary)\",\n  tertiaryDark: \"var(--color-tertiaryDark)\",\n  grayLight: \"var(--color-grayLight)\",\n  gray: \"var(--color-gray)\",\n  grayDark: \"var(--color-grayDark)\",\n  success: \"var(--color-success)\",\n  error: \"var(--color-error)\",\n  warning: \"var(--color-warning)\",\n  info: \"var(--color-info)\",\n  dark: \"var(--color-dark)\",\n  light: \"var(--color-light)\",\n\n  // Semantic tokens \u2014 derived in GlobalStyles to capture the most common\n  // mode-aware swaps that components used to express via `theme.isDark ? A : B`.\n  // They follow the same single-noun convention as the brand palette.\n  accent: \"var(--color-accent)\",\n  accentStrong: \"var(--color-accentStrong)\",\n  accentMuted: \"var(--color-accentMuted)\",\n  surface: \"var(--color-surface)\",\n};\n\nconst shadows: Shadows = {\n  xs: \"var(--shadow-xs)\",\n  sm: \"var(--shadow-sm)\",\n  md: \"var(--shadow-md)\",\n  lg: \"var(--shadow-lg)\",\n  xl: \"var(--shadow-xl)\",\n};\n\nexport const theme: Theme = {\n  breakpoints,\n  spacing,\n  colors,\n  shadows,\n  fonts,\n  fontSizes,\n  lineHeights,\n  // Stub for type compatibility with cherry-styled-components' Theme. Mode\n  // switching lives entirely in CSS vars flipped by :root.dark, so our own\n  // code never branches on this. Cherry's internal `isDark ? \u2026 : \u2026` branches\n  // (e.g. buttonStyles' filled-button text) are handled where they surface\n  // by re-pinning to a mode-agnostic semantic token \u2014 see components/layout/Button.tsx.\n  isDark: false,\n};\n\ninterface Breakpoints<TNumber = number> {\n  xs: TNumber;\n  sm: TNumber;\n  md: TNumber;\n  lg: TNumber;\n  xl: TNumber;\n  xxl: TNumber;\n  xxxl: TNumber;\n}\n\ninterface Spacing<TString = string> {\n  maxWidth: { xs: TString; xxxl: TString };\n  padding: { xs: TString; lg: TString };\n  radius: { xs: TString; lg: TString; xl: TString };\n  gridGap: { xs: TString; lg: TString };\n}\n\n// Matches cherry-styled-components' Colors shape for the brand keys, plus a\n// handful of semantic tokens derived from the brand palette by GlobalStyles.\n// The brand keys (primaryLight\u2026light) are customizable via theme.json; the\n// semantic keys (accent*, surface) are derived and not overridable \u2014 see\n// CustomColors above.\ninterface Colors<TString = string> {\n  primaryLight: TString;\n  primary: TString;\n  primaryDark: TString;\n\n  secondaryLight: TString;\n  secondary: TString;\n  secondaryDark: TString;\n\n  tertiaryLight: TString;\n  tertiary: TString;\n  tertiaryDark: TString;\n\n  grayLight: TString;\n  gray: TString;\n  grayDark: TString;\n\n  success: TString;\n  error: TString;\n  warning: TString;\n  info: TString;\n\n  dark: TString;\n  light: TString;\n\n  /** High-contrast accent text. Was: isDark ? primaryLight : primaryDark. */\n  accent: TString;\n  /** Slightly stronger accent (lightened/darkened by ~10%). */\n  accentStrong: TString;\n  /** Muted body text. Was: isDark ? grayDark : primary. */\n  accentMuted: TString;\n  /** Elevated surface color, white-ish in both modes. Was: isDark ? dark : light. */\n  surface: TString;\n}\n\ninterface Shadows<TString = string> {\n  xs: TString;\n  sm: TString;\n  md: TString;\n  lg: TString;\n  xl: TString;\n}\n\ninterface Fonts<TString = string> {\n  head: TString;\n  text: TString;\n  mono: TString;\n}\n\ninterface FontSizes<TString = string> {\n  hero1: { xs: TString; lg: TString };\n  hero2: { xs: TString; lg: TString };\n  hero3: { xs: TString; lg: TString };\n\n  h1: { xs: TString; lg: TString };\n  h2: { xs: TString; lg: TString };\n  h3: { xs: TString; lg: TString };\n  h4: { xs: TString; lg: TString };\n  h5: { xs: TString; lg: TString };\n  h6: { xs: TString; lg: TString };\n\n  text: { xs: TString; lg: TString };\n  strong: { xs: TString; lg: TString };\n  small: { xs: TString; lg: TString };\n\n  blockquote: { xs: TString; lg: TString };\n  code: { xs: TString; lg: TString };\n\n  button: { xs: TString; lg: TString };\n  buttonBig: { xs: TString; lg: TString };\n  buttonSmall: { xs: TString; lg: TString };\n\n  input: { xs: TString; lg: TString };\n  inputBig: { xs: TString; lg: TString };\n  inputSmall: { xs: TString; lg: TString };\n}\n\ninterface LineHeights<TString = string> {\n  hero1: { xs: TString; lg: TString };\n  hero2: { xs: TString; lg: TString };\n  hero3: { xs: TString; lg: TString };\n\n  h1: { xs: TString; lg: TString };\n  h2: { xs: TString; lg: TString };\n  h3: { xs: TString; lg: TString };\n  h4: { xs: TString; lg: TString };\n  h5: { xs: TString; lg: TString };\n  h6: { xs: TString; lg: TString };\n\n  text: { xs: TString; lg: TString };\n  strong: { xs: TString; lg: TString };\n  small: { xs: TString; lg: TString };\n\n  blockquote: { xs: TString; lg: TString };\n  code: { xs: TString; lg: TString };\n\n  button: { xs: TString; lg: TString };\n  buttonBig: { xs: TString; lg: TString };\n  buttonSmall: { xs: TString; lg: TString };\n\n  input: { xs: TString; lg: TString };\n  inputBig: { xs: TString; lg: TString };\n  inputSmall: { xs: TString; lg: TString };\n}\n\nexport interface Theme {\n  breakpoints: Breakpoints;\n  spacing: Spacing;\n  colors: Colors;\n  shadows: Shadows;\n  fonts: Fonts;\n  fontSizes: FontSizes;\n  lineHeights: LineHeights;\n  isDark: boolean;\n}\n";