jamdesk 1.1.216 → 1.1.217

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jamdesk",
-  "version": "1.1.216",
+  "version": "1.1.217",
   "description": "CLI for Jamdesk — build, preview, and deploy documentation sites from MDX. Dev server with hot reload, 50+ components, OpenAPI support, AI search, and Mintlify migration",
   "keywords": [
     "jamdesk",

package/vendored/app/api/og/route.tsx

@@ -1,16 +1,11 @@
 import { ImageResponse } from '@vercel/og';
 import { NextRequest } from 'next/server';
 import { sanitizeLogoUrl } from '@/lib/sanitize-url';
+import { parseCardOptions } from '@/lib/og-card';
 
 export const runtime = 'edge';
 
-// Warm cream/red-orange palette — matches marketing site OG images
-const ACCENT_COLOR = '#ff3621';
-const ACCENT_GRADIENT = `linear-gradient(90deg, ${ACCENT_COLOR} 0%, #e02e1a 50%, #c4200f 100%)`;
-const BG_GRADIENT = 'linear-gradient(135deg, #faf8f5 0%, #f3f0eb 100%)';
-const TEXT_COLOR = '#1b3139';
-const MUTED_COLOR = '#5a6b73';
-const BADGE_BG = `rgba(255, 54, 33, 0.08)`; // ACCENT_COLOR at 8% opacity
+// Colors live in lib/og-card.ts; with no theme/accent params it reproduces the original warm cream/red-orange card.
 const MAX_DESCRIPTION_LENGTH = 120;
 const LONG_TITLE_THRESHOLD = 40;
 const FONT_STACK =
@@ -54,7 +49,10 @@ async function fetchDataUri(url: string): Promise<string> {
  * - siteName: Site name (optional, defaults to "Documentation")
  * - logo: URL to the project's logo (optional)
  * - bg: URL to a custom background image rendered behind the text (optional)
- * - theme: accepted but ignored (always uses cream/warm style)
+ * - theme: 'light' (default, warm cream) or 'dark'
+ * - accent: hex color (3 or 6 digits, '#' optional) for the badge and bottom bar; low-contrast values fall back to a readable color
+ * - hideBar: '1' hides the bottom accent bar
+ * - hideName: '1' hides the site name (the logo, if any, still renders)
  *
  * Example:
  * /api/og?title=Introduction&section=Get%20Started&siteName=Acme%20Docs&logo=https://...
@@ -66,6 +64,7 @@ export async function GET(request: NextRequest) {
   const description = searchParams.get('description') || '';
   const section = searchParams.get('section') || '';
   const siteName = searchParams.get('siteName') || 'Documentation';
+  const card = parseCardOptions(searchParams);
   // SSRF guard: HTTPS-only, blocks private/loopback/metadata IPs (incl. encoded forms).
   const logoUrl = sanitizeLogoUrl(searchParams.get('logo') || '');
   const bgUrl = sanitizeLogoUrl(searchParams.get('bg') || '');
@@ -85,7 +84,7 @@ export async function GET(request: NextRequest) {
           height: '100%',
           width: '100%',
           display: 'flex',
-          background: BG_GRADIENT,
+          background: card.palette.background,
           fontFamily: FONT_STACK,
         }}
       >
@@ -116,42 +115,46 @@ export async function GET(request: NextRequest) {
             padding: '60px',
           }}
         >
-          {/* Logo and site name */}
-          <div
-            style={{
-              display: 'flex',
-              flexDirection: 'column',
-              alignItems: 'flex-start',
-              marginBottom: '40px',
-            }}
-          >
-            {logo && (
-              <img
-                src={logo}
-                alt=""
-                width={360}
-                height={48}
-                style={{
-                  height: '48px',
-                  maxWidth: '360px',
-                  objectFit: 'contain',
-                  marginBottom: '16px',
-                  borderRadius: '8px',
-                }}
-              />
-            )}
-            <span
+          {/* Logo and site name. Skipped when both are hidden so its 40px margin doesn't push the title down. */}
+          {(logo || card.showSiteName) && (
+            <div
               style={{
-                fontSize: '24px',
-                fontWeight: 600,
-                color: MUTED_COLOR,
-                textTransform: 'uppercase',
-                letterSpacing: '0.05em',
+                display: 'flex',
+                flexDirection: 'column',
+                alignItems: 'flex-start',
+                marginBottom: '40px',
               }}
             >
-              {siteName}
-            </span>
-          </div>
+              {logo && (
+                <img
+                  src={logo}
+                  alt=""
+                  width={360}
+                  height={48}
+                  style={{
+                    height: '48px',
+                    maxWidth: '360px',
+                    objectFit: 'contain',
+                    marginBottom: card.showSiteName ? '16px' : 0,
+                    borderRadius: '8px',
+                  }}
+                />
+              )}
+              {card.showSiteName && (
+                <span
+                  style={{
+                    fontSize: '24px',
+                    fontWeight: 600,
+                    color: card.palette.muted,
+                    textTransform: 'uppercase',
+                    letterSpacing: '0.05em',
+                  }}
+                >
+                  {siteName}
+                </span>
+              )}
+            </div>
+          )}
 
           {/* Section badge */}
           {section && (
@@ -165,9 +168,9 @@ export async function GET(request: NextRequest) {
                 style={{
                   fontSize: '18px',
                   fontWeight: 500,
-                  color: ACCENT_COLOR,
+                  color: card.palette.badgeText,
                   padding: '8px 16px',
-                  background: BADGE_BG,
+                  background: card.palette.badgeBg,
                   borderRadius: '20px',
                 }}
               >
@@ -189,7 +192,7 @@ export async function GET(request: NextRequest) {
               style={{
                 fontSize: titleFontSize,
                 fontWeight: 700,
-                color: TEXT_COLOR,
+                color: card.palette.title,
                 lineHeight: 1.2,
                 margin: 0,
                 maxWidth: '900px',
@@ -202,7 +205,7 @@ export async function GET(request: NextRequest) {
               <p
                 style={{
                   fontSize: '28px',
-                  color: MUTED_COLOR,
+                  color: card.palette.muted,
                   marginTop: '24px',
                   lineHeight: 1.4,
                   maxWidth: '800px',
@@ -214,15 +217,17 @@ export async function GET(request: NextRequest) {
           </div>
 
           {/* Bottom accent bar */}
-          <div
-            style={{
-              display: 'flex',
-              height: '6px',
-              background: ACCENT_GRADIENT,
-              borderRadius: '3px',
-              marginTop: '40px',
-            }}
-          />
+          {card.showAccentBar && (
+            <div
+              style={{
+                display: 'flex',
+                height: '6px',
+                background: card.palette.bar,
+                borderRadius: '3px',
+                marginTop: '40px',
+              }}
+            />
+          )}
         </div>
       </div>
     ),

package/vendored/lib/docs-types.ts

@@ -723,6 +723,22 @@ export interface ChatConfig {
   starterQuestions?: string[];
 }
 
+/**
+ * Options for the generated social sharing card (og:image).
+ */
+export interface SocialCardConfig {
+  /** Card text/background style (default: 'light') */
+  theme?: 'light' | 'dark';
+  /** Use colors.primary for the accent bar and section badge (default: false) */
+  brandColor?: boolean;
+  /** Show the colored bar along the bottom (default: true) */
+  accentBar?: boolean;
+  /** Show the site name under the logo (default: true) */
+  siteName?: boolean;
+  /** 'background' draws the title over a custom og:image; 'replace' uses it as-is (default: 'background') */
+  customImage?: 'background' | 'replace';
+}
+
 /**
  * SEO configuration
  */
@@ -732,6 +748,7 @@ export interface SeoConfig {
   /** Include hidden pages in sitemap (default: false) */
   indexHiddenPages?: boolean;
   ai?: { llmsTxt?: boolean }; // default true; false suppresses llms.txt + llms-full.txt
+  socialCard?: SocialCardConfig;
 }
 
 /**

package/vendored/lib/og-card.ts

@@ -0,0 +1,119 @@
+/**
+ * Pure helpers for the social card (app/api/og). No imports: the route runs on
+ * the edge runtime and this must stay dependency-free.
+ */
+
+export type CardTheme = 'light' | 'dark';
+
+export const DEFAULT_ACCENT = '#ff3621';
+
+/** Today's bar, kept verbatim so a card with no new params renders exactly as before. */
+export const LEGACY_ACCENT_GRADIENT = 'linear-gradient(90deg, #ff3621 0%, #e02e1a 50%, #c4200f 100%)';
+
+export interface CardPalette {
+  background: string;   // CSS background (gradient) used when there is no bg image
+  surface: string;      // solid hex the gradient starts from; used for contrast checks
+  title: string;
+  muted: string;
+  accent: string;       // resolved accent hex
+  bar: string;          // CSS background for the bar
+  badgeText: string;
+  badgeBg: string;
+}
+
+export interface CardOptions {
+  theme: CardTheme;
+  palette: CardPalette;
+  showAccentBar: boolean;
+  showSiteName: boolean;
+}
+
+const THEMES = {
+  light: {
+    surface: '#faf8f5',
+    background: 'linear-gradient(135deg, #faf8f5 0%, #f3f0eb 100%)',
+    title: '#1b3139',
+    muted: '#5a6b73',
+    badgeAlpha: 0.08,
+  },
+  dark: {
+    surface: '#12161a',
+    background: 'linear-gradient(135deg, #12161a 0%, #1c2228 100%)',
+    title: '#f5f3ef',
+    muted: '#a3b1b8',
+    badgeAlpha: 0.16,
+  },
+} as const;
+
+// Accent text under 3:1 is hard to read at badge size; a bar under 1.5:1 all but vanishes.
+const MIN_TEXT_CONTRAST = 3;
+const MIN_BAR_CONTRAST = 1.5;
+
+/** Accepts 3- or 6-digit hex with or without '#'. Anything else is null, so the value is safe to inline in CSS. */
+export function normalizeHex(input: string | null | undefined): string | null {
+  if (!input) return null;
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(input);
+  if (!m) return null;
+  const h = m[1].toLowerCase();
+  const full = h.length === 3 ? h.split('').map((c) => c + c).join('') : h;
+  return `#${full}`;
+}
+
+function channels(hex: string): [number, number, number] {
+  const n = parseInt(hex.slice(1), 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+export function hexToRgba(hex: string, alpha: number): string {
+  const [r, g, b] = channels(hex);
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+
+function luminance(hex: string): number {
+  const [r, g, b] = channels(hex).map((v) => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+export function contrastRatio(a: string, b: string): number {
+  const la = luminance(a);
+  const lb = luminance(b);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+export function resolveCardPalette(theme: CardTheme, accent: string | null): CardPalette {
+  const t = THEMES[theme];
+  const base = { background: t.background, surface: t.surface, title: t.title, muted: t.muted };
+
+  // No accent means every pre-existing card URL: reproduce today's colors with no contrast logic.
+  if (accent === null) {
+    return {
+      ...base,
+      accent: DEFAULT_ACCENT,
+      bar: LEGACY_ACCENT_GRADIENT,
+      badgeText: DEFAULT_ACCENT,
+      badgeBg: hexToRgba(DEFAULT_ACCENT, t.badgeAlpha),
+    };
+  }
+
+  const contrast = contrastRatio(accent, t.surface);
+  return {
+    ...base,
+    accent,
+    bar: contrast >= MIN_BAR_CONTRAST ? accent : t.muted,
+    badgeText: contrast >= MIN_TEXT_CONTRAST ? accent : t.title,
+    badgeBg: hexToRgba(accent, t.badgeAlpha),
+  };
+}
+
+export function parseCardOptions(params: URLSearchParams): CardOptions {
+  const theme: CardTheme = params.get('theme') === 'dark' ? 'dark' : 'light';
+  return {
+    theme,
+    palette: resolveCardPalette(theme, normalizeHex(params.get('accent'))),
+    showAccentBar: params.get('hideBar') !== '1',
+    showSiteName: params.get('hideName') !== '1',
+  };
+}

package/vendored/lib/seo.ts

@@ -10,8 +10,10 @@
 
 import type { Metadata } from 'next';
 import { stripMarkdownForMeta } from './openapi/operation-description';
-import type { DocsConfig, Logo, LogoConfig, Favicon, LanguageConfig, LanguageCode } from './docs-types';
-import { normalizeLogo } from './docs-types';
+import type { DocsConfig, Logo, LogoConfig, Favicon, LanguageConfig, LanguageCode, SocialCardConfig, ColorsConfig } from './docs-types';
+import { normalizeLogo, transformConfigImagePath } from './docs-types';
+import { normalizeHex } from './og-card';
+import { getTheme } from '../themes';
 import { findHreflangAliasCollisions, transformLanguagePath, toHreflang, resolveLocaleFromPath } from './language-utils';
 import { fallbackSeo } from './locale-fallback';
 import { logger } from '../shared/logger';
@@ -59,11 +61,39 @@ export const FALLBACK_METADATA: Metadata = {
   description: 'Documentation',
 };
 
-/** Resolve a Logo or Favicon config to a path string, preferring light variant. */
-function resolveImagePath(image?: Logo | Favicon): string {
+/**
+ * Resolve a Logo or Favicon config to a path string. Light prefers the light
+ * variant, dark prefers the dark one; each falls back to the other so a
+ * single-variant config still yields an image.
+ */
+function resolveImagePath(image?: Logo | Favicon, variant: 'light' | 'dark' = 'light'): string {
   if (!image) return '';
   if (typeof image === 'string') return image;
-  return (image as LogoConfig).light || (image as LogoConfig).dark || '';
+  const { light, dark } = image as LogoConfig;
+  return (variant === 'dark' ? dark || light : light || dark) || '';
+}
+
+/**
+ * Make a config-supplied image reference fetchable by the OG route, which loads
+ * it server-side. Local paths go through the /_jd asset prefix (where the
+ * pipeline serves them); an existing /_jd path is not doubled. Returns '' for
+ * data: URIs: the route drops them and base64 would bloat the og:image URL.
+ */
+export function toAbsoluteAssetUrl(pathOrUrl: string, rootUrl: string): string {
+  if (pathOrUrl.startsWith('data:')) return '';
+  if (pathOrUrl.startsWith('http://') || pathOrUrl.startsWith('https://')) return pathOrUrl;
+  // transformConfigImagePath passes '//host' through untouched, which would
+  // then be glued onto rootUrl as a path.
+  if (pathOrUrl.startsWith('//')) return `https:${pathOrUrl}`;
+  return `${rootUrl}${transformConfigImagePath(pathOrUrl) ?? ''}`;
+}
+
+/**
+ * True for a WebP or AVIF image path/URL. Satori in the OG route cannot decode
+ * either and answers with an empty PNG instead of an error.
+ */
+function isUndecodableImage(pathOrUrl: string): boolean {
+  return /\.(?:webp|avif)$/i.test(pathOrUrl.split(/[?#]/)[0]);
 }
 
 /**
@@ -102,6 +132,9 @@ function buildOgImageUrl(
     logo?: Logo;
     favicon?: Favicon;
     bg?: string;
+    card?: SocialCardConfig;
+    colors?: ColorsConfig;
+    theme?: string;
   }
 ): string {
   const params = new URLSearchParams();
@@ -122,32 +155,73 @@ function buildOgImageUrl(
   const { prefix: resolvedPrefix, rootUrl } = resolveRootUrl(baseUrl, docsPrefix);
   const isHostAtDocs = resolvedPrefix !== '';
 
-  // Handle logo - prefer light variant for OG images (cream background)
-  // Satori (@vercel/og) can't render webp, so fall back to favicon if logo is webp
-  if (options?.logo || options?.favicon) {
-    let logoPath = resolveImagePath(options?.logo);
-    // Fall back to favicon when logo is webp (Satori can't decode webp)
-    if ((!logoPath || logoPath.endsWith('.webp')) && options?.favicon) {
-      logoPath = resolveImagePath(options.favicon);
+  const card = options?.card;
+  if (!card) {
+    // Tenants without seo.socialCard keep today's URLs byte for byte, including
+    // the non-prefixed asset paths: cached cards and shared links must not change.
+    // Handle logo - prefer light variant for OG images (cream background)
+    // Satori (@vercel/og) can't render webp, so fall back to favicon if logo is webp
+    if (options?.logo || options?.favicon) {
+      let logoPath = resolveImagePath(options?.logo);
+      // Fall back to favicon when logo is webp (Satori can't decode webp)
+      if ((!logoPath || logoPath.endsWith('.webp')) && options?.favicon) {
+        logoPath = resolveImagePath(options.favicon);
+      }
+      // Make logo URL absolute (use root URL since assets are at domain root)
+      if (logoPath && !logoPath.startsWith('http')) {
+        logoPath = `${rootUrl}${logoPath.startsWith('/') ? '' : '/'}${logoPath}`;
+      }
+      if (logoPath) {
+        params.set('logo', logoPath);
+      }
     }
-    // Make logo URL absolute (use root URL since assets are at domain root)
-    if (logoPath && !logoPath.startsWith('http')) {
-      logoPath = `${rootUrl}${logoPath.startsWith('/') ? '' : '/'}${logoPath}`;
+
+    // Custom background image: composite the card text over it instead of using it
+    // as a bare static image. The OG route fetches it server-side, so it must be
+    // absolute — assets live at the domain root, so resolve against rootUrl.
+    if (options?.bg) {
+      let bgPath = options.bg;
+      if (!bgPath.startsWith('http')) {
+        bgPath = `${rootUrl}${bgPath.startsWith('/') ? '' : '/'}${bgPath}`;
+      }
+      params.set('bg', bgPath);
     }
-    if (logoPath) {
-      params.set('logo', logoPath);
+  } else {
+    const variant = card.theme === 'dark' ? 'dark' : 'light';
+
+    // Resolved before any param is set so the param order stays as it was.
+    let logoUrl = '';
+    let logoIsFavicon = false;
+    if (options?.logo || options?.favicon) {
+      let logoPath = resolveImagePath(options?.logo, variant);
+      if ((!logoPath || isUndecodableImage(logoPath)) && options?.favicon) {
+        logoPath = resolveImagePath(options.favicon, variant);
+        logoIsFavicon = true;
+      }
+      // A webp/avif logo makes the route return a 0-byte PNG that the CDN then
+      // caches, so a card with no logo is the better outcome.
+      if (logoPath && !isUndecodableImage(logoPath)) logoUrl = toAbsoluteAssetUrl(logoPath, rootUrl);
     }
-  }
 
-  // Custom background image: composite the card text over it instead of using it
-  // as a bare static image. The OG route fetches it server-side, so it must be
-  // absolute — assets live at the domain root, so resolve against rootUrl.
-  if (options?.bg) {
-    let bgPath = options.bg;
-    if (!bgPath.startsWith('http')) {
-      bgPath = `${rootUrl}${bgPath.startsWith('/') ? '' : '/'}${bgPath}`;
+    if (variant === 'dark') params.set('theme', 'dark');
+    if (card.accentBar === false) params.set('hideBar', '1');
+    // Hiding the name is only safe when the tenant's own logo is drawn: with the
+    // favicon (or nothing) in its place the card would carry no brand at all.
+    if (card.siteName === false && logoUrl && !logoIsFavicon) params.set('hideName', '1');
+
+    if (card.brandColor === true) {
+      const colors = options?.colors;
+      const configured = variant === 'dark' ? colors?.light ?? colors?.primary : colors?.primary;
+      const accent = normalizeHex(configured ?? getTheme(options?.theme).defaultAccent);
+      if (accent) params.set('accent', accent.slice(1));
+    }
+
+    if (logoUrl) params.set('logo', logoUrl);
+
+    if (options?.bg && !isUndecodableImage(options.bg)) {
+      const bgUrl = toAbsoluteAssetUrl(options.bg, rootUrl);
+      if (bgUrl) params.set('bg', bgUrl);
     }
-    params.set('bg', bgPath);
   }
 
   // hostAtDocs: use /_jd/og (proxied to ISR app's /api/og) for same-domain OG images
@@ -157,37 +231,79 @@ function buildOgImageUrl(
 }
 
 /**
- * Public OG-card URL builder. Mirrors the global+page metatag merge that
- * buildSeoMetadata performs, so callers outside the metadata path (the JSON-LD
- * layer) can set an article image to the exact same card the og:image points at.
+ * Resolve the social image a page advertises, plus whether it is the generated
+ * card. Mirrors the global+page metatag merge that buildSeoMetadata performs, so
+ * callers outside the metadata path (the JSON-LD layer) get the exact image the
+ * og:image points at.
+ *
+ * Default: always the generated /api/og card, with a custom og:image composited
+ * in as its background. With `seo.socialCard.customImage: 'replace'` and an
+ * og:image set, that image is served untouched instead (`generated: false`).
+ *
+ * Declared dimensions come from the SAME layer that supplied the winning
+ * og:image: a page image must not inherit the site default's width/height, which
+ * describe a different file.
  *
  * @param docsPrefix - This tenant's external docs URL prefix ('' | '/docs' |
  *   a custom subpath like '/help'). Falls back to the legacy baseUrl-suffix
  *   sniff when omitted — see buildOgImageUrl.
  */
-export function buildPageOgImageUrl(
+export function resolvePageSocialImage(
   config: DocsConfig,
   frontmatter: PageFrontmatter,
   baseUrl: string,
   docsPrefix?: string,
-): string {
+): { url: string; generated: boolean; width?: number; height?: number } {
   const globalMeta = config.seo?.metatags || {};
   const pageMeta = normalizePageMetatags(frontmatter as Record<string, unknown>);
   const metatags: Record<string, string> = { ...globalMeta, ...pageMeta };
   const customImage = metatags['og:image']?.trim();
-  return buildOgImageUrl(
-    baseUrl,
-    metatags['og:title'] || frontmatter.title || 'Documentation',
-    config.name,
-    docsPrefix,
-    {
-      description: metaDescriptionText(metatags['og:description'] || frontmatter.description),
-      section: frontmatter.section,
-      logo: config.logo,
-      favicon: config.favicon,
-      bg: customImage || undefined,
-    },
-  );
+
+  if (config.seo?.socialCard?.customImage === 'replace' && customImage) {
+    const { rootUrl } = resolveRootUrl(baseUrl, docsPrefix);
+    const url = toAbsoluteAssetUrl(customImage, rootUrl);
+    // A data: URI resolves to '' (it would bloat the tag and crawlers drop it),
+    // so fall through to the generated card rather than emit an empty og:image.
+    if (url) {
+      const dims = pageMeta['og:image']?.trim() ? pageMeta : globalMeta;
+      return {
+        url,
+        generated: false,
+        width: positiveIntMeta(dims, 'og:image:width'),
+        height: positiveIntMeta(dims, 'og:image:height'),
+      };
+    }
+  }
+
+  return {
+    generated: true,
+    url: buildOgImageUrl(
+      baseUrl,
+      metatags['og:title'] || frontmatter.title || 'Documentation',
+      config.name,
+      docsPrefix,
+      {
+        description: metaDescriptionText(metatags['og:description'] || frontmatter.description),
+        section: frontmatter.section,
+        logo: config.logo,
+        favicon: config.favicon,
+        bg: customImage || undefined,
+        card: config.seo?.socialCard,
+        colors: config.colors,
+        theme: config.theme,
+      },
+    ),
+  };
+}
+
+/** The social image URL only; see resolvePageSocialImage. */
+export function buildPageOgImageUrl(
+  config: DocsConfig,
+  frontmatter: PageFrontmatter,
+  baseUrl: string,
+  docsPrefix?: string,
+): string {
+  return resolvePageSocialImage(config, frontmatter, baseUrl, docsPrefix).url;
 }
 
 /**
@@ -297,9 +413,21 @@ function numericMeta(metatags: Record<string, string>, key: string): number | un
   return Number.isNaN(n) ? undefined : n;
 }
 
+// numericMeta lets 0, negatives, fractions and whitespace-only strings
+// (Number(' ') === 0) through; a crawler can't use any of those as a pixel size.
+function positiveIntMeta(metatags: Record<string, string>, key: string): number | undefined {
+  const n = numericMeta(metatags, key);
+  return n !== undefined && Number.isInteger(n) && n > 0 ? n : undefined;
+}
+
 type FallbackOg = {
   title?: string; description?: string; url: string; siteName: string; ogImageUrl: string;
   locale?: string;
+  /** False when ogImageUrl is the author's own image (customImage: 'replace'). */
+  ogImageGenerated?: boolean;
+  /** Declared size of an author-supplied image; ignored for the generated card. */
+  ogImageWidth?: number;
+  ogImageHeight?: number;
 };
 
 /**
@@ -344,16 +472,21 @@ export function buildOpenGraphMetadata(
   const ttl = numericMeta(metatags, 'og:ttl');
   if (ttl !== undefined) og.ttl = ttl;
 
-  // Image: always the generated card (1200x630 PNG). A custom og:image is composited
-  // as the card BACKGROUND upstream (buildSeoMetadata routes it through /api/og's
-  // `bg` param), so the emitted image is always the generated card — never the raw
-  // user image. og:image:alt still describes it.
-  const image: Record<string, unknown> = {
-    url: fb.ogImageUrl,
-    width: 1200,
-    height: 630,
-    type: 'image/png',
-  };
+  // Image: the generated card (1200x630 PNG) unless the caller resolved the
+  // author's own image (customImage: 'replace'). In the default mode a custom
+  // og:image is composited as the card BACKGROUND upstream (via /api/og's `bg`
+  // param), so the emitted image is never the raw user file. For a raw image we
+  // can't know the format or size, so emit only the dimensions the author
+  // declared and no `type`. og:image:alt describes either.
+  const image: Record<string, unknown> = { url: fb.ogImageUrl };
+  if (fb.ogImageGenerated === false) {
+    if (fb.ogImageWidth !== undefined) image.width = fb.ogImageWidth;
+    if (fb.ogImageHeight !== undefined) image.height = fb.ogImageHeight;
+  } else {
+    image.width = 1200;
+    image.height = 630;
+    image.type = 'image/png';
+  }
   if (metatags['og:image:alt']) image.alt = metatags['og:image:alt'];
   og.images = [image];
 
@@ -827,17 +960,21 @@ export function buildSeoMetadata(
     (k) => k.startsWith('og:') || k.startsWith('article:') || k.startsWith('book:') || k.startsWith('profile:'),
   );
   if (hasOgFamily || frontmatter.title) {
-    // A custom og:image becomes the card BACKGROUND (text renders on top) rather
-    // than a bare static image, so the emitted OG image is always the generated card.
-    // The card text follows og:title/og:description overrides so the image matches
-    // the link-card text built in buildOpenGraphMetadata.
-    const ogImageUrl = buildPageOgImageUrl(config, frontmatter, baseUrl, docsPrefix);
+    // By default a custom og:image becomes the card BACKGROUND (text renders on
+    // top) and the emitted image is the generated card. With
+    // seo.socialCard.customImage: 'replace' the author's image is emitted as-is.
+    // The generated card's text follows og:title/og:description overrides so the
+    // image matches the link-card text built in buildOpenGraphMetadata.
+    const socialImage = resolvePageSocialImage(config, frontmatter, baseUrl, docsPrefix);
     metadata.openGraph = buildOpenGraphMetadata(metatags, {
       title: frontmatter.title,
       description: metaDescriptionText(frontmatter.description),
       url: pageUrl,
       siteName: config.name,
-      ogImageUrl,
+      ogImageUrl: socialImage.url,
+      ogImageGenerated: socialImage.generated,
+      ogImageWidth: socialImage.width,
+      ogImageHeight: socialImage.height,
       // og:locale describes the language of the CONTENT, so on the fallback it
       // must follow the English body, not the locale URL. (og:url deliberately
       // still points at the locale URL — that is the page's real address, and

package/vendored/schema/docs-schema.json

@@ -609,6 +609,46 @@
                                     "description": "Generate llms.txt and llms-full.txt for AI crawlers. Default true. Set false to stop publishing AI-context files (independent of search noindex)."
                                 }
                             }
+                        },
+                        "socialCard": {
+                            "type": "object",
+                            "additionalProperties": false,
+                            "properties": {
+                                "theme": {
+                                    "type": "string",
+                                    "enum": [
+                                        "light",
+                                        "dark"
+                                    ],
+                                    "default": "light",
+                                    "description": "Text and background style of the card. `dark` uses light text on a dark background and your `logo.dark` image. Defaults to `light`."
+                                },
+                                "brandColor": {
+                                    "type": "boolean",
+                                    "default": false,
+                                    "description": "Use your `colors.primary` for the card's accent bar and section badge (`colors.light` on a dark card). Defaults to `false`, which keeps the default red."
+                                },
+                                "accentBar": {
+                                    "type": "boolean",
+                                    "default": true,
+                                    "description": "Show the colored bar along the bottom of the card. Defaults to `true`."
+                                },
+                                "siteName": {
+                                    "type": "boolean",
+                                    "default": true,
+                                    "description": "Show the site name under the logo. Set `false` when your logo already contains the name. Defaults to `true`."
+                                },
+                                "customImage": {
+                                    "type": "string",
+                                    "enum": [
+                                        "background",
+                                        "replace"
+                                    ],
+                                    "default": "background",
+                                    "description": "How a custom `og:image` is used. `background` draws the page title on top of it. `replace` uses the image as-is, with no text. Defaults to `background`."
+                                }
+                            },
+                            "description": "Customize the generated social sharing card (og:image) for every page."
                         }
                     },
                     "additionalProperties": false,

package/vendored/themes/index.ts

@@ -31,6 +31,7 @@ const jamTheme: ThemeConfig = {
     },
   },
   cssPath: 'jam/variables.css',
+  defaultAccent: '#3b82f6',
 };
 
 const nebulaTheme: ThemeConfig = {
@@ -52,6 +53,7 @@ const nebulaTheme: ThemeConfig = {
     },
   },
   cssPath: 'nebula/variables.css',
+  defaultAccent: '#f97316',
 };
 
 const pulsarTheme: ThemeConfig = {
@@ -73,6 +75,7 @@ const pulsarTheme: ThemeConfig = {
     },
   },
   cssPath: 'pulsar/variables.css',
+  defaultAccent: '#3b82f6',
 };
 
 const haloTheme: ThemeConfig = {
@@ -98,6 +101,7 @@ const haloTheme: ThemeConfig = {
     },
   },
   cssPath: 'halo/variables.css',
+  defaultAccent: '#C0873F',
 };
 
 const duskTheme: ThemeConfig = {
@@ -125,6 +129,7 @@ const duskTheme: ThemeConfig = {
     },
   },
   cssPath: 'dusk/variables.css',
+  defaultAccent: '#2158A1',
 };
 
 // Theme registry

package/vendored/themes/types.ts

@@ -78,6 +78,13 @@ export interface ThemeConfig {
   
   /** CSS file path relative to themes directory */
   cssPath: string;
+
+  /**
+   * The theme's light-mode `--color-accent`. The OG social card uses it as the
+   * accent when a tenant opts into brandColor but sets no colors.primary.
+   * Pinned to variables.css by __tests__/theme-default-accent.test.ts.
+   */
+  defaultAccent: string;
 }
 
 /** 

package/vendored/workspace-package-lock.json

@@ -380,42 +380,40 @@
       "license": "MIT"
     },
     "node_modules/@chevrotain/cst-dts-gen": {
-      "version": "11.1.2",
-      "resolved": "https://registry.npmjs.org/@chevrotain/cst-dts-gen/-/cst-dts-gen-11.1.2.tgz",
-      "integrity": "sha512-XTsjvDVB5nDZBQB8o0o/0ozNelQtn2KrUVteIHSlPd2VAV2utEb6JzyCJaJ8tGxACR4RiBNWy5uYUHX2eji88Q==",
+      "version": "13.2.0",
+      "resolved": "https://registry.npmjs.org/@chevrotain/cst-dts-gen/-/cst-dts-gen-13.2.0.tgz",
+      "integrity": "sha512-bA9dvWlhAUcHkNwU+8w9yiUxJPlj/Lm3VqS7MD+NbIR/7LmpNLuK/AWNFdCo/T3SK5ND0/UHf3IJvl/Jn/i6yg==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@chevrotain/gast": "11.1.2",
-        "@chevrotain/types": "11.1.2",
-        "lodash-es": "4.17.23"
+        "@chevrotain/gast": "13.2.0",
+        "@chevrotain/types": "13.2.0"
       }
     },
     "node_modules/@chevrotain/gast": {
-      "version": "11.1.2",
-      "resolved": "https://registry.npmjs.org/@chevrotain/gast/-/gast-11.1.2.tgz",
-      "integrity": "sha512-Z9zfXR5jNZb1Hlsd/p+4XWeUFugrHirq36bKzPWDSIacV+GPSVXdk+ahVWZTwjhNwofAWg/sZg58fyucKSQx5g==",
+      "version": "13.2.0",
+      "resolved": "https://registry.npmjs.org/@chevrotain/gast/-/gast-13.2.0.tgz",
+      "integrity": "sha512-bCARdAsG+eEbOveSXcOAC7pVxA04I1ionzeMOwIYf5NX7SaS7zgn4Dgug2BSqoL+iyKeMNSorQjsFSHJHsCNwg==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@chevrotain/types": "11.1.2",
-        "lodash-es": "4.17.23"
+        "@chevrotain/types": "13.2.0"
       }
     },
     "node_modules/@chevrotain/regexp-to-ast": {
-      "version": "11.1.2",
-      "resolved": "https://registry.npmjs.org/@chevrotain/regexp-to-ast/-/regexp-to-ast-11.1.2.tgz",
-      "integrity": "sha512-nMU3Uj8naWer7xpZTYJdxbAs6RIv/dxYzkYU8GSwgUtcAAlzjcPfX1w+RKRcYG8POlzMeayOQ/znfwxEGo5ulw==",
+      "version": "13.2.0",
+      "resolved": "https://registry.npmjs.org/@chevrotain/regexp-to-ast/-/regexp-to-ast-13.2.0.tgz",
+      "integrity": "sha512-kxpUkLtiaK09ph+dib+Yvm+3sWSnuwlo25gqfKRgTPNmF6H7uW4gVkMjaRdtnN783S9sM6vUNWh9CsxYX4QwKw==",
       "license": "Apache-2.0"
     },
     "node_modules/@chevrotain/types": {
-      "version": "11.1.2",
-      "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-11.1.2.tgz",
-      "integrity": "sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==",
+      "version": "13.2.0",
+      "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-13.2.0.tgz",
+      "integrity": "sha512-7qrYHRlKfWf2AvBfJi5eVOrKAkbxvMFsy/iIHTGIiApNcEecCaVIdR+mIQhyCBsTDJxBz4JWXHMo6krbhR9hVg==",
       "license": "Apache-2.0"
     },
     "node_modules/@chevrotain/utils": {
-      "version": "11.1.2",
-      "resolved": "https://registry.npmjs.org/@chevrotain/utils/-/utils-11.1.2.tgz",
-      "integrity": "sha512-4mudFAQ6H+MqBTfqLmU7G1ZwRzCLfJEooL/fsF6rCX5eePMbGhoy5n4g+G4vlh2muDcsCTJtL+uKbOzWxs5LHA==",
+      "version": "13.2.0",
+      "resolved": "https://registry.npmjs.org/@chevrotain/utils/-/utils-13.2.0.tgz",
+      "integrity": "sha512-SzKYY68rseOrb9KILVzPsl6SjkQtdWw01SRGB5aCVI5kFcHltQsOYV3JB0Ffst72DgkvHCyDQ0NLwxtmCCf97Q==",
       "license": "Apache-2.0"
     },
     "node_modules/@emnapi/runtime": {
@@ -1126,12 +1124,12 @@
       }
     },
     "node_modules/@mermaid-js/parser": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-2.0.0.tgz",
-      "integrity": "sha512-K8BeapFUfrfxbRAUQAG5oBOCwo1+bNWzaVnPxTCutkfrTBn6T/j91FIhqxWJ32SUeQ9T3iy1zcmPZ5ROZEvDrg==",
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-2.0.1.tgz",
+      "integrity": "sha512-j37dj/h6p6pots1L7pLPPNuABEEu9WP4OYg9pW1g+nYG331j0+3canE9OagtYdytYvdSAMG+2fKU5cxep6LgjA==",
       "license": "MIT",
       "dependencies": {
-        "@chevrotain/types": "~11.1.2"
+        "@chevrotain/types": "~13.2.0"
       },
       "engines": {
         "node": ">=22.12.0"
@@ -2155,9 +2153,9 @@
       }
     },
     "node_modules/@types/node": {
-      "version": "26.6.3",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.3.tgz",
-      "integrity": "sha512-dsqMQQoeTLqu9wynDD00q573mNzso3IdQOAfHRJqLCcmCFPoGo9A1bDpUcv/9tnKpErQWv9uKeGfl37EIS02Yg==",
+      "version": "26.6.4",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.4.tgz",
+      "integrity": "sha512-ldVPDCzj7fsaGZrLB0NuHuTvJcsNasysBAqMolr/cgxrLd1xbqxIr3XJiPnHHJUCxj5sNF1vnRj9aWnrVh5Jcg==",
       "license": "MIT",
       "dependencies": {
         "undici-types": "~8.9.0"
@@ -2234,9 +2232,9 @@
       }
     },
     "node_modules/@vercel/cli-config": {
-      "version": "0.3.0",
-      "resolved": "https://registry.npmjs.org/@vercel/cli-config/-/cli-config-0.3.0.tgz",
-      "integrity": "sha512-kQLt5Pm8wKd7/imzDY9/9u0tf8OuRkAuXI+s7j057FSUrXapAmumJSKwDqnR4ZZqdWoUcNLlFAgVIAdiwcGTcw==",
+      "version": "0.3.1",
+      "resolved": "https://registry.npmjs.org/@vercel/cli-config/-/cli-config-0.3.1.tgz",
+      "integrity": "sha512-sISbygqlFXYb8qfPu/+2Cf/A8IjrlAuZePdag3EDQr2PRA455s7UZtl9Ro674CWsB/saBRmz3jEkw0YsQs8OoQ==",
       "license": "Apache-2.0",
       "dependencies": {
         "xdg-app-paths": "5",
@@ -2256,12 +2254,12 @@
       }
     },
     "node_modules/@vercel/functions": {
-      "version": "3.9.9",
-      "resolved": "https://registry.npmjs.org/@vercel/functions/-/functions-3.9.9.tgz",
-      "integrity": "sha512-ocN/BNsIswReoyqfU1huilNyBM9tvY9kFXgYj0LlyPRATC1dt35gj2jN5hs9+Nag/CRyVQOX58L2FEhvL+0sSA==",
+      "version": "3.9.10",
+      "resolved": "https://registry.npmjs.org/@vercel/functions/-/functions-3.9.10.tgz",
+      "integrity": "sha512-s/Hbm2e/9YDGqAgjsAuhdnSc07psq0AVuELkImVfzoT52CbHLT3DTVoN6N4wtVeel9Tv1G4xB7S2cEkPH4j0og==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@vercel/oidc": "3.8.9"
+        "@vercel/oidc": "3.8.10"
       },
       "engines": {
         "node": ">= 20"
@@ -2280,12 +2278,12 @@
       }
     },
     "node_modules/@vercel/oidc": {
-      "version": "3.8.9",
-      "resolved": "https://registry.npmjs.org/@vercel/oidc/-/oidc-3.8.9.tgz",
-      "integrity": "sha512-TcbdH3YtGS2KU98T99dN4sbf+E4vbJZsJTRN97wKQ7QWQ0BR7U02QX3KN4+5GHxBtKTj1c5CnvTTitc2ZRad0A==",
+      "version": "3.8.10",
+      "resolved": "https://registry.npmjs.org/@vercel/oidc/-/oidc-3.8.10.tgz",
+      "integrity": "sha512-sPw1kIfQEA6/2dB+zlAJHnhhNBRJ8t/t4HfFvKO+g0EPBA7NbCKyGovuhgAV6Mnl865ka7HqCEguIy596czdAw==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@vercel/cli-config": "0.3.0",
+        "@vercel/cli-config": "0.3.1",
         "@vercel/cli-exec": "1.0.1",
         "jose": "^5.9.6"
       },
@@ -2451,9 +2449,9 @@
       }
     },
     "node_modules/baseline-browser-mapping": {
-      "version": "2.11.26",
-      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.11.26.tgz",
-      "integrity": "sha512-GLQdD3y6UF8iVuMJl5fHgE4jdn/ua7n+toKfLgNlg3BqQtOZjpy68T8Tup8/wGWZCDlm7KMg7tPb4MPn7oN0TQ==",
+      "version": "2.11.27",
+      "resolved": "https://registry.npmjs.org/baseline-browser-mapping/-/baseline-browser-mapping-2.11.27.tgz",
+      "integrity": "sha512-ElY12DaROGuan+lMmZ8Cvo/ZUbXPe7Enc/9VU/b1T3Kp4dwytRcNdR8DoSJN5SNJT/CuvcCA0DHDVmMOCePdRQ==",
       "license": "Apache-2.0",
       "bin": {
         "baseline-browser-mapping": "dist/cli.cjs"
@@ -2584,17 +2582,19 @@
       }
     },
     "node_modules/chevrotain": {
-      "version": "11.1.2",
-      "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-11.1.2.tgz",
-      "integrity": "sha512-opLQzEVriiH1uUQ4Kctsd49bRoFDXGGSC4GUqj7pGyxM3RehRhvTlZJc1FL/Flew2p5uwxa1tUDWKzI4wNM8pg==",
+      "version": "13.2.0",
+      "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-13.2.0.tgz",
+      "integrity": "sha512-GTouk5YzgBxlTPCaDn5q0q2EJKkrYmnPF+HmF8v0Qo4r3iyPG7HJivkN1wthCXZcm3sIcZFpGTRovLPNdJNRCA==",
       "license": "Apache-2.0",
       "dependencies": {
-        "@chevrotain/cst-dts-gen": "11.1.2",
-        "@chevrotain/gast": "11.1.2",
-        "@chevrotain/regexp-to-ast": "11.1.2",
-        "@chevrotain/types": "11.1.2",
-        "@chevrotain/utils": "11.1.2",
-        "lodash-es": "4.17.23"
+        "@chevrotain/cst-dts-gen": "13.2.0",
+        "@chevrotain/gast": "13.2.0",
+        "@chevrotain/regexp-to-ast": "13.2.0",
+        "@chevrotain/types": "13.2.0",
+        "@chevrotain/utils": "13.2.0"
+      },
+      "engines": {
+        "node": ">=22.0.0"
       }
     },
     "node_modules/client-only": {
@@ -3279,9 +3279,9 @@
       "license": "MIT"
     },
     "node_modules/electron-to-chromium": {
-      "version": "1.5.443",
-      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.443.tgz",
-      "integrity": "sha512-TDJG36L9A3CWWwZ97HKaE+Iz1sW80pNp6sAU0owzCIV3Zc9eVyRqZK8Vz6NKuMIU8WjP0pIkoqCa0VRf/yFD0Q==",
+      "version": "1.5.444",
+      "resolved": "https://registry.npmjs.org/electron-to-chromium/-/electron-to-chromium-1.5.444.tgz",
+      "integrity": "sha512-5ss/uJfoDYDHT0lfJzT6FbcskIzROIOPf0BbbFkGcvDzoJU7i//9GDrwwIHQVmIsrAGiF3ihpADBRIsrEFt1rQ==",
       "license": "ISC"
     },
     "node_modules/elkjs": {
@@ -4509,9 +4509,9 @@
       }
     },
     "node_modules/lodash-es": {
-      "version": "4.17.23",
-      "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.23.tgz",
-      "integrity": "sha512-kVI48u3PZr38HdYz98UmfPnXl2DXrpdctLrFLCd3kOx1xUkOmpFPx7gCWWM5MPkL/fD8zb+Ph0QzjGFs4+hHWg==",
+      "version": "4.18.1",
+      "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.18.1.tgz",
+      "integrity": "sha512-J8xewKD/Gk22OZbhpOVSwcs60zhd95ESDwezOFuA3/099925PdHJ7OFHNTGtajL3AlZkykD32HykiMo+BIBI8A==",
       "license": "MIT"
     },
     "node_modules/longest-streak": {
@@ -4915,17 +4915,17 @@
       "license": "MIT"
     },
     "node_modules/mermaid": {
-      "version": "12.0.0",
-      "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-12.0.0.tgz",
-      "integrity": "sha512-/wQXC9iBxoGV8p3erbvaXs9h77VyLDBH6GdayVjj3hEcSQhFU4N1WUhUppotCEqlIxI2pRMwjwBSwTB1MfZBgQ==",
+      "version": "12.1.0",
+      "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-12.1.0.tgz",
+      "integrity": "sha512-wlVCp+8eTupfCeeFvoZNNiTuHrvag0P2jz/ILgb/f/6jkVokUefOcujefi8qUe/j2asHiSePncVsz/xzzA80LQ==",
       "license": "MIT",
       "dependencies": {
         "@braintree/sanitize-url": "^7.1.2",
         "@iconify/utils": "^3.0.2",
-        "@mermaid-js/parser": "^2.0.0",
+        "@mermaid-js/parser": "^2.0.1",
         "@types/d3": "^7.4.3",
         "@upsetjs/venn.js": "^2.0.0",
-        "chevrotain": "~11.1.2",
+        "chevrotain": "~13.2.0",
         "cytoscape": "^3.34.0",
         "cytoscape-cose-bilkent": "^4.1.0",
         "cytoscape-fcose": "^2.2.0",