jamdesk 1.1.215 → 1.1.217

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/lib/theme-preview.ts

@@ -57,7 +57,6 @@
  *    a `Vary` header.
  */
 import { getAllThemes, type ThemeConfig, type ThemeName } from '@/themes';
-import { DUSK_PUBLIC } from '@/lib/dusk-embargo';
 
 /** Cookie the picker writes; read server-side in app/layout.tsx. */
 export const THEME_PREVIEW_COOKIE = 'jd_theme';
@@ -70,9 +69,9 @@ export const THEME_PREVIEW_SLUG = 'jamdesk-docs';
 // setting, and should not outlive the visit. The clear path still sends
 // `Max-Age=0` — see theme-preview-client.ts's applyThemePreview.
 
-/** Themes the picker offers. Dusk joins on launch day (lib/dusk-embargo.ts). */
+/** Themes the picker offers. */
 export function getPreviewThemes(): ThemeConfig[] {
-  return getAllThemes().filter((theme) => DUSK_PUBLIC || theme.name !== 'dusk');
+  return getAllThemes();
 }
 
 // Built from the themes the picker actually offers, rather than using
@@ -81,8 +80,7 @@ export function getPreviewThemes(): ThemeConfig[] {
 // would reach getTheme(), which falls back to jam silently for unknown names
 // but returns Object's own constructor for 'constructor' — yielding
 // data-theme="constructor" and no theme CSS. A Set of the offered themes' own
-// names is immune, picks up new themes for free, and keeps an embargoed theme
-// out of both the picker and the cookie reader below.
+// names is immune and picks up new themes for free.
 const VALID_THEME_NAMES: ReadonlySet<string> = new Set(
   getPreviewThemes().map((theme) => theme.name),
 );

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;
 }
 
 /**