@djangocfg/nextjs 2.1.438 → 2.1.439

package/dist/og-image/index.d.mts

@@ -2,6 +2,23 @@ import { Metadata } from 'next';
 
 type OGPreset = 'DARK' | 'DARK_BLUE' | 'DARK_PURPLE' | 'DARK_GREEN' | 'DARK_ROSE' | 'LIGHT' | 'LIGHT_GRAY' | 'LIGHT_WARM' | 'LIGHT_GREEN';
 type OGLayout = 'DEFAULT' | 'HERO' | 'ARTICLE' | 'MINIMAL';
+/**
+ * Per-page OG image intent — the single axis that decides what the OG image is.
+ * A discriminated union so every case is explicit and type-checked:
+ *
+ *   'static'              brand image from site config (the default)
+ *   'dynamic'             render the page title onto the OG card
+ *   { render: {...} }     render with explicit preset/layout/colors
+ *   { image, alt? }       an exact image URL (e.g. a content screenshot)
+ */
+type OgSpec = 'static' | 'dynamic' | {
+    render: Omit<OGImageParams, 'title'> & {
+        title?: string;
+    };
+} | {
+    image: string;
+    alt?: string;
+};
 /** Mirrors Django OGImageParams exactly */
 interface OGImageParams {
     title: string;
@@ -20,51 +37,6 @@ interface OGImageParams {
     page_url?: string;
 }
 
-/**
- * Builds an absolute (or relative) OG image URL pointing to Django's
- * django_ogimage endpoint: /cfg/og/<base64params>/
- *
- * The URL is suitable for use in og:image and twitter:image meta tags.
- */
-declare function buildOgUrl(params: OGImageParams): string;
-
-/**
- * Creates Next.js Metadata fragment with og:image and twitter:image
- * pointing to Django's django_ogimage renderer.
- *
- * Usage in generateMetadata():
- *   return createOgMetadata({ title: 'Page', preset: 'DARK_BLUE' })
- */
-declare function createOgMetadata(params: OGImageParams): Metadata;
-/**
- * Options for `withOgImage`. Extends the dynamic-renderer params with an
- * `image` opt-out so a page can keep its own (static) OG image instead of the
- * dynamically-rendered one.
- */
-type WithOgImageOptions = Omit<OGImageParams, 'title'> & {
-    title?: string;
-    /**
-     * Controls the OG image source:
-     * - omitted / `true` → dynamic render via Django's /cfg/og/ (default)
-     * - `false`          → don't touch images; the page/layout's own og:image
-     *                      is preserved (use for a ready-made static brand image)
-     * - `string`         → use this exact URL as a static og/twitter image
-     */
-    image?: boolean | string;
-};
-/**
- * Merges og:image metadata into an existing Metadata object.
- *
- * Usage:
- *   // dynamic (default)
- *   return withOgImage({ title: 'Page', description: '...' }, { preset: 'DARK_BLUE' })
- *   // keep the page's own static image
- *   return withOgImage(meta, { preset: 'DARK_BLUE', image: false })
- *   // explicit static image
- *   return withOgImage(meta, { image: '/static/ogimage.png' })
- */
-declare function withOgImage(metadata: Metadata, params?: WithOgImageOptions): Metadata;
-
 /**
  * Site-wide identity the metadata factory needs. Config-agnostic on purpose —
  * the package doesn't know about any app's `settings` object, so the consumer
@@ -81,41 +53,43 @@ interface SiteMetaConfig {
     ogImage: string;
     /** Optional favicon / apple-touch icons forwarded to Metadata.icons. */
     icons?: Metadata['icons'];
-    /** Locales for hreflang alternates (first is treated as x-default if no enDefault). */
+    /** Locales for hreflang alternates. Omit for single-locale sites. */
     locales?: readonly string[];
     /** Locale used for x-default hreflang (defaults to "en" or first locale). */
     defaultLocale?: string;
 }
-/** Per-page inputs. Everything is optional except what makes the page unique. */
+/**
+ * Per-page inputs. Only `title` is really worth setting per page; everything
+ * else falls back to the site config.
+ */
 interface PageMeta {
-    /** Page title (without the brand suffix — the template adds it). */
+    /** Page title (without the brand suffix). Falls back to the site name. */
     title?: string;
     /** Page description; falls back to the site description. */
     description?: string;
     keywords?: string[];
     /** Current locale, used for canonical + openGraph.locale + alternates. */
     locale?: string;
-    /** Path without locale prefix, e.g. "/skills". '' for home. Drives alternates. */
+    /** Path without locale prefix, e.g. "/skills". '' for home. */
     path?: string;
     /**
-     * OG image control, forwarded to `withOgImage`:
-     * - omitted        → static brand image (`config.ogImage`) — the safe default
-     * - `true`         → dynamic render from the page title
-     * - OGImageParams  → dynamic render with explicit preset/layout/colors
-     * - `false`        → no image (inherit whatever the layout set)
-     * - string         → explicit image URL
+     * What the OG image should be. Defaults to `'static'` (the brand image).
+     * - `'static'`          brand image from config (default)
+     * - `'dynamic'`         render the page title onto the card
+     * - `{ render: {...} }` render with explicit preset/layout/colors
+     * - `{ image, alt? }`   an exact image URL (e.g. a content screenshot)
      */
-    og?: boolean | string | Omit<OGImageParams, 'title'>;
+    og?: OgSpec;
+    /** Escape hatch: extra Metadata fields merged last (robots, authors, etc.). */
+    extra?: Metadata;
 }
 /**
- * Builds a complete Next.js `Metadata` object from a one-time site config plus
- * per-page inputs — title-template, description, openGraph, twitter, canonical
- * + hreflang alternates, and icons — so pages only declare what's unique.
- *
- * OG image defaults to the static brand image (`config.ogImage`); opt into the
- * dynamic renderer per page with `og: true` / `og: { preset: 'DARK_BLUE' }`.
+ * Builds a complete Next.js `Metadata` from a one-time site config plus per-page
+ * inputs — title-template, description, openGraph, twitter, canonical + hreflang,
+ * icons, and the OG image — so pages only declare what's unique.
  *
- * Bind the config once in your app, then call the bound fn from each page:
+ * The OG image is chosen by the single `og` field (defaults to the static brand
+ * image). There is exactly one way to do each thing.
  *
  *   // app/_core/metadata.ts
  *   export const createMetadata = makeMetadataFactory({
@@ -127,14 +101,53 @@ interface PageMeta {
  *     locales: LOCALES,
  *   })
  *
- *   // any page.tsx
- *   export const metadata = createMetadata({ title: 'Skills', path: '/skills' })
+ *   // landing page — static brand image (default)
+ *   export const metadata = createMetadata({ title: 'Pricing', path: '/pricing' })
+ *   // content page — title rendered onto the card
+ *   export const metadata = createMetadata({ title: post.title, path, og: 'dynamic' })
+ *   // content page with its own image
+ *   export const metadata = createMetadata({ title: p.name, og: { image: p.image } })
  */
 declare function createMetadata(config: SiteMetaConfig, page?: PageMeta): Metadata;
 /**
  * Curries `createMetadata` with a fixed site config so pages call a zero-config
- * factory. See the docstring on `createMetadata` for the usage pattern.
+ * factory. This is the single recommended entry point for app metadata.
  */
 declare function makeMetadataFactory(config: SiteMetaConfig): (page?: PageMeta) => Metadata;
 
-export { type OGImageParams, type OGLayout, type OGPreset, type PageMeta, type SiteMetaConfig, type WithOgImageOptions, buildOgUrl, createMetadata, createOgMetadata, makeMetadataFactory, withOgImage };
+/**
+ * Builds an absolute (or relative) OG image URL pointing to Django's
+ * django_ogimage endpoint: /cfg/og/<base64params>/
+ *
+ * The URL is suitable for use in og:image and twitter:image meta tags.
+ */
+declare function buildOgUrl(params: OGImageParams): string;
+
+/**
+ * Metadata fragment whose OG image is rendered by Django's django_ogimage
+ * endpoint (/cfg/og/). Low-level — most callers use `createMetadata`'s `og`
+ * field instead.
+ */
+declare function createOgMetadata(params: OGImageParams): Metadata;
+/** Extract a plain title string from Next.js's title shapes. */
+declare function extractTitle(metadata: Metadata): string;
+/**
+ * Resolves an `OgSpec` against a base Metadata into a concrete og/twitter image
+ * fragment. `staticUrl` is the site's brand image, used for the `'static'` case.
+ * Returns `null` only if there's genuinely nothing to set.
+ *
+ * This is the single decision point for "what is the OG image" — no other code
+ * branches on the spec.
+ */
+declare function resolveOgImage(spec: OgSpec, staticUrl: string, fallbackTitle: string): Pick<Metadata, 'openGraph' | 'twitter'>;
+/**
+ * Merges OG image metadata (dynamic render) into existing Metadata. Kept for
+ * low-level/manual use; `createMetadata` is the recommended entry point.
+ *
+ *   return withOgImage({ title: 'Page' }, { preset: 'DARK_BLUE' })
+ */
+declare function withOgImage(metadata: Metadata, params?: Omit<OGImageParams, 'title'> & {
+    title?: string;
+}): Metadata;
+
+export { type OGImageParams, type OGLayout, type OGPreset, type OgSpec, type PageMeta, type SiteMetaConfig, buildOgUrl, createMetadata, createOgMetadata, extractTitle, makeMetadataFactory, resolveOgImage, withOgImage };

package/dist/og-image/index.mjs

@@ -23,55 +23,20 @@ function buildOgUrl(params) {
 }
 
 // src/og-image/metadata.ts
-function createOgMetadata(params) {
-  const url = buildOgUrl(params);
-  const image = { url, width: 1200, height: 630, alt: params.title };
-  return {
-    openGraph: {
-      images: [image]
-    },
-    twitter: {
-      card: "summary_large_image",
-      images: [url]
-    }
-  };
+var OG_WIDTH = 1200;
+var OG_HEIGHT = 630;
+function imageEntry(url, alt) {
+  return { url, width: OG_WIDTH, height: OG_HEIGHT, alt };
 }
-function withOgImage(metadata, params = {}) {
-  const { image, ...ogParams } = params;
-  if (image === false) {
-    return metadata;
-  }
-  if (typeof image === "string") {
-    return {
-      ...metadata,
-      openGraph: {
-        ...metadata.openGraph,
-        images: [{ url: image, width: 1200, height: 630, alt: extractTitle(metadata) }]
-      },
-      twitter: {
-        card: "summary_large_image",
-        ...metadata.twitter,
-        images: [image]
-      }
-    };
-  }
-  const resolvedParams = {
-    title: extractTitle(metadata),
-    ...ogParams
-  };
-  const ogMeta = createOgMetadata(resolvedParams);
+function ogImageFragment(url, alt) {
   return {
-    ...metadata,
-    openGraph: {
-      ...metadata.openGraph,
-      ...ogMeta.openGraph
-    },
-    twitter: {
-      ...metadata.twitter,
-      ...ogMeta.twitter
-    }
+    openGraph: { images: [imageEntry(url, alt)] },
+    twitter: { card: "summary_large_image", images: [url] }
   };
 }
+function createOgMetadata(params) {
+  return ogImageFragment(buildOgUrl(params), params.title);
+}
 function extractTitle(metadata) {
   const t = metadata.title;
   if (!t) return "";
@@ -80,11 +45,33 @@ function extractTitle(metadata) {
   if (typeof t === "object" && "default" in t) return t.default;
   return "";
 }
+function resolveOgImage(spec, staticUrl, fallbackTitle) {
+  if (spec === "static") {
+    return ogImageFragment(staticUrl, fallbackTitle);
+  }
+  if (spec === "dynamic") {
+    return ogImageFragment(buildOgUrl({ title: fallbackTitle }), fallbackTitle);
+  }
+  if ("image" in spec) {
+    return ogImageFragment(spec.image, spec.alt ?? fallbackTitle);
+  }
+  const title = spec.render.title ?? fallbackTitle;
+  return ogImageFragment(buildOgUrl({ ...spec.render, title }), title);
+}
+function withOgImage(metadata, params = {}) {
+  const title = params.title ?? extractTitle(metadata);
+  const frag = createOgMetadata({ ...params, title });
+  return {
+    ...metadata,
+    openGraph: { ...metadata.openGraph, ...frag.openGraph },
+    twitter: { ...metadata.twitter, ...frag.twitter }
+  };
+}
 
 // src/og-image/metadata-factory.ts
 function buildAlternates(config, path, locale) {
   if (!config.locales?.length) {
-    return { canonical: `${config.siteUrl}/${locale}${path}` };
+    return { canonical: `${config.siteUrl}/${path}`.replace(/\/+$/, "") || config.siteUrl };
   }
   const languages = {};
   for (const loc of config.locales) {
@@ -99,7 +86,9 @@ function createMetadata(config, page = {}) {
   const description = page.description ?? config.description;
   const locale = page.locale ?? config.defaultLocale ?? "en";
   const path = page.path ?? "";
-  const base = {
+  const ogUrl = config.locales?.length ? `${config.siteUrl}/${locale}${path}` : `${config.siteUrl}${path}`;
+  const ogImage = resolveOgImage(page.og ?? "static", config.ogImage, title);
+  const metadata = {
     title,
     description,
     keywords: page.keywords,
@@ -107,29 +96,26 @@ function createMetadata(config, page = {}) {
     openGraph: {
       type: "website",
       locale,
-      url: `${config.siteUrl}/${locale}${path}`,
+      url: ogUrl,
       siteName: config.name,
       title,
-      description
+      description,
+      ...ogImage.openGraph
     },
     twitter: {
-      card: "summary_large_image",
       title,
-      description
+      description,
+      ...ogImage.twitter
     },
     icons: config.icons
   };
-  let ogOptions;
-  if (page.og === void 0 || page.og === false) {
-    ogOptions = { image: config.ogImage };
-  } else if (page.og === true) {
-    ogOptions = {};
-  } else if (typeof page.og === "string") {
-    ogOptions = { image: page.og };
-  } else {
-    ogOptions = page.og;
-  }
-  return withOgImage(base, ogOptions);
+  if (!page.extra) return metadata;
+  return {
+    ...metadata,
+    ...page.extra,
+    openGraph: { ...metadata.openGraph, ...page.extra.openGraph },
+    twitter: { ...metadata.twitter, ...page.extra.twitter }
+  };
 }
 function makeMetadataFactory(config) {
   return (page = {}) => createMetadata(config, page);
@@ -138,7 +124,9 @@ export {
   buildOgUrl,
   createMetadata,
   createOgMetadata,
+  extractTitle,
   makeMetadataFactory,
+  resolveOgImage,
   withOgImage
 };
 //# sourceMappingURL=index.mjs.map

package/dist/og-image/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/og-image/url.ts","../../src/og-image/metadata.ts","../../src/og-image/metadata-factory.ts"],"sourcesContent":["import type { OGImageParams } from './types'\n\n/**\n * Resolves the base URL for og:image meta tags.\n * Must be publicly accessible by crawlers (Twitter, Facebook, etc).\n *\n * Priority:\n * 1. NEXT_PUBLIC_MEDIA_URL — explicit media domain (nginx proxy or CDN)\n * 2. NEXT_PUBLIC_API_URL   — direct Django API domain\n * 3. NEXT_PUBLIC_SITE_URL  — site domain (same-domain/static build)\n * 4. ''                    — relative URL (last resort)\n *\n * Use cases:\n * - Same domain (static build):   API_URL='' → relative /cfg/og/...\n * - Split domain (standalone):    API_URL=https://api.x.com → absolute\n * - Media via nginx proxy:        MEDIA_URL=https://x.com, API_URL=https://api.x.com\n * - CDN:                          MEDIA_URL=https://cdn.x.com\n */\nfunction resolveOgPublicBase(): string {\n  if (typeof process === 'undefined') return ''\n  return (\n    process.env.NEXT_PUBLIC_MEDIA_URL?.replace(/\\/$/, '') ??\n    process.env.NEXT_PUBLIC_API_URL?.replace(/\\/$/, '') ??\n    process.env.NEXT_PUBLIC_SITE_URL?.replace(/\\/$/, '') ??\n    ''\n  )\n}\n\nfunction encodeBase64(str: string): string {\n  if (typeof Buffer !== 'undefined') {\n    return Buffer.from(str).toString('base64url')\n  }\n  // Browser fallback\n  return btoa(unescape(encodeURIComponent(str)))\n    .replace(/\\+/g, '-')\n    .replace(/\\//g, '_')\n    .replace(/=+$/, '')\n}\n\nfunction cleanParams(params: OGImageParams): Record<string, unknown> {\n  return Object.fromEntries(\n    Object.entries(params).filter(\n      ([, v]) => v !== undefined && v !== null && v !== ''\n    )\n  )\n}\n\n/**\n * Builds an absolute (or relative) OG image URL pointing to Django's\n * django_ogimage endpoint: /cfg/og/<base64params>/\n *\n * The URL is suitable for use in og:image and twitter:image meta tags.\n */\nexport function buildOgUrl(params: OGImageParams): string {\n  const b64 = encodeBase64(JSON.stringify(cleanParams(params)))\n  const base = resolveOgPublicBase()\n  return `${base}/cfg/og/${b64}/`\n}\n","import type { Metadata } from 'next'\nimport type { OGImageParams } from './types'\nimport { buildOgUrl } from './url'\n\n/**\n * Creates Next.js Metadata fragment with og:image and twitter:image\n * pointing to Django's django_ogimage renderer.\n *\n * Usage in generateMetadata():\n *   return createOgMetadata({ title: 'Page', preset: 'DARK_BLUE' })\n */\nexport function createOgMetadata(params: OGImageParams): Metadata {\n  const url = buildOgUrl(params)\n  const image = { url, width: 1200, height: 630, alt: params.title }\n  return {\n    openGraph: {\n      images: [image],\n    },\n    twitter: {\n      card: 'summary_large_image',\n      images: [url],\n    },\n  }\n}\n\n/**\n * Options for `withOgImage`. Extends the dynamic-renderer params with an\n * `image` opt-out so a page can keep its own (static) OG image instead of the\n * dynamically-rendered one.\n */\nexport type WithOgImageOptions = Omit<OGImageParams, 'title'> & {\n  title?: string\n  /**\n   * Controls the OG image source:\n   * - omitted / `true` → dynamic render via Django's /cfg/og/ (default)\n   * - `false`          → don't touch images; the page/layout's own og:image\n   *                      is preserved (use for a ready-made static brand image)\n   * - `string`         → use this exact URL as a static og/twitter image\n   */\n  image?: boolean | string\n}\n\n/**\n * Merges og:image metadata into an existing Metadata object.\n *\n * Usage:\n *   // dynamic (default)\n *   return withOgImage({ title: 'Page', description: '...' }, { preset: 'DARK_BLUE' })\n *   // keep the page's own static image\n *   return withOgImage(meta, { preset: 'DARK_BLUE', image: false })\n *   // explicit static image\n *   return withOgImage(meta, { image: '/static/ogimage.png' })\n */\nexport function withOgImage(\n  metadata: Metadata,\n  params: WithOgImageOptions = {}\n): Metadata {\n  const { image, ...ogParams } = params\n\n  // Opt-out: leave the incoming metadata's images untouched.\n  if (image === false) {\n    return metadata\n  }\n\n  // Explicit static URL: set og/twitter images without hitting the renderer.\n  if (typeof image === 'string') {\n    return {\n      ...metadata,\n      openGraph: {\n        ...metadata.openGraph,\n        images: [{ url: image, width: 1200, height: 630, alt: extractTitle(metadata) }],\n      },\n      twitter: {\n        card: 'summary_large_image',\n        ...metadata.twitter,\n        images: [image],\n      },\n    }\n  }\n\n  // Default: dynamic render. Auto-extract title; params.title overrides.\n  const resolvedParams: OGImageParams = {\n    title: extractTitle(metadata),\n    ...ogParams,\n  }\n\n  const ogMeta = createOgMetadata(resolvedParams)\n\n  return {\n    ...metadata,\n    openGraph: {\n      ...metadata.openGraph,\n      ...ogMeta.openGraph,\n    },\n    twitter: {\n      ...metadata.twitter,\n      ...ogMeta.twitter,\n    },\n  }\n}\n\nfunction extractTitle(metadata: Metadata): string {\n  const t = metadata.title\n  if (!t) return ''\n  if (typeof t === 'string') return t\n  if (typeof t === 'object' && 'absolute' in t) return (t as { absolute: string }).absolute\n  if (typeof t === 'object' && 'default' in t) return (t as { default: string }).default\n  return ''\n}\n","import type { Metadata } from 'next'\nimport type { OGImageParams } from './types'\nimport { withOgImage, type WithOgImageOptions } from './metadata'\n\n/**\n * Site-wide identity the metadata factory needs. Config-agnostic on purpose —\n * the package doesn't know about any app's `settings` object, so the consumer\n * passes these once (typically derived from their own settings module).\n */\nexport interface SiteMetaConfig {\n  /** Brand / app name, e.g. \"CMDOP\". Used in titles, siteName, alt text. */\n  name: string\n  /** Default description used when a page doesn't supply its own. */\n  description: string\n  /** Absolute site origin, e.g. \"https://cmdop.com\". Used for canonical/og url. */\n  siteUrl: string\n  /** Ready-made static brand OG image URL (absolute or root-relative). */\n  ogImage: string\n  /** Optional favicon / apple-touch icons forwarded to Metadata.icons. */\n  icons?: Metadata['icons']\n  /** Locales for hreflang alternates (first is treated as x-default if no enDefault). */\n  locales?: readonly string[]\n  /** Locale used for x-default hreflang (defaults to \"en\" or first locale). */\n  defaultLocale?: string\n}\n\n/** Per-page inputs. Everything is optional except what makes the page unique. */\nexport interface PageMeta {\n  /** Page title (without the brand suffix — the template adds it). */\n  title?: string\n  /** Page description; falls back to the site description. */\n  description?: string\n  keywords?: string[]\n  /** Current locale, used for canonical + openGraph.locale + alternates. */\n  locale?: string\n  /** Path without locale prefix, e.g. \"/skills\". '' for home. Drives alternates. */\n  path?: string\n  /**\n   * OG image control, forwarded to `withOgImage`:\n   * - omitted        → static brand image (`config.ogImage`) — the safe default\n   * - `true`         → dynamic render from the page title\n   * - OGImageParams  → dynamic render with explicit preset/layout/colors\n   * - `false`        → no image (inherit whatever the layout set)\n   * - string         → explicit image URL\n   */\n  og?: boolean | string | Omit<OGImageParams, 'title'>\n}\n\nfunction buildAlternates(\n  config: SiteMetaConfig,\n  path: string,\n  locale: string\n): Metadata['alternates'] {\n  if (!config.locales?.length) {\n    return { canonical: `${config.siteUrl}/${locale}${path}` }\n  }\n  const languages: Record<string, string> = {}\n  for (const loc of config.locales) {\n    languages[loc] = `${config.siteUrl}/${loc}${path}`\n  }\n  const xDefault = config.defaultLocale ?? (config.locales.includes('en') ? 'en' : config.locales[0])\n  languages['x-default'] = `${config.siteUrl}/${xDefault}${path}`\n  return { canonical: `${config.siteUrl}/${locale}${path}`, languages }\n}\n\n/**\n * Builds a complete Next.js `Metadata` object from a one-time site config plus\n * per-page inputs — title-template, description, openGraph, twitter, canonical\n * + hreflang alternates, and icons — so pages only declare what's unique.\n *\n * OG image defaults to the static brand image (`config.ogImage`); opt into the\n * dynamic renderer per page with `og: true` / `og: { preset: 'DARK_BLUE' }`.\n *\n * Bind the config once in your app, then call the bound fn from each page:\n *\n *   // app/_core/metadata.ts\n *   export const createMetadata = makeMetadataFactory({\n *     name: settings.app.name,\n *     description: settings.app.description,\n *     siteUrl: settings.app.siteUrl,\n *     ogImage: settings.app.media.ogimage,\n *     icons: { icon: settings.app.media.favicon },\n *     locales: LOCALES,\n *   })\n *\n *   // any page.tsx\n *   export const metadata = createMetadata({ title: 'Skills', path: '/skills' })\n */\nexport function createMetadata(config: SiteMetaConfig, page: PageMeta = {}): Metadata {\n  const title = page.title ?? config.name\n  const description = page.description ?? config.description\n  const locale = page.locale ?? config.defaultLocale ?? 'en'\n  const path = page.path ?? ''\n\n  const base: Metadata = {\n    title,\n    description,\n    keywords: page.keywords,\n    alternates: buildAlternates(config, path, locale),\n    openGraph: {\n      type: 'website',\n      locale,\n      url: `${config.siteUrl}/${locale}${path}`,\n      siteName: config.name,\n      title,\n      description,\n    },\n    twitter: {\n      card: 'summary_large_image',\n      title,\n      description,\n    },\n    icons: config.icons,\n  }\n\n  // Resolve the `og` shorthand into withOgImage options.\n  let ogOptions: WithOgImageOptions\n  if (page.og === undefined || page.og === false) {\n    // Default & explicit-off both map to the static brand image. (false on the\n    // factory means \"don't render dynamic\" — but we still want a brand image,\n    // so we point at the static one. Use og:false at the page only if you've\n    // set images elsewhere; here static is the friendly default.)\n    ogOptions = { image: config.ogImage }\n  } else if (page.og === true) {\n    ogOptions = {} // dynamic, title auto-extracted\n  } else if (typeof page.og === 'string') {\n    ogOptions = { image: page.og }\n  } else {\n    ogOptions = page.og // OGImageParams → dynamic with overrides\n  }\n\n  return withOgImage(base, ogOptions)\n}\n\n/**\n * Curries `createMetadata` with a fixed site config so pages call a zero-config\n * factory. See the docstring on `createMetadata` for the usage pattern.\n */\nexport function makeMetadataFactory(config: SiteMetaConfig) {\n  return (page: PageMeta = {}): Metadata => createMetadata(config, page)\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/og-image/url.ts","../../src/og-image/metadata.ts","../../src/og-image/metadata-factory.ts"],"sourcesContent":["import type { OGImageParams } from './types'\n\n/**\n * Resolves the base URL for og:image meta tags.\n * Must be publicly accessible by crawlers (Twitter, Facebook, etc).\n *\n * Priority:\n * 1. NEXT_PUBLIC_MEDIA_URL — explicit media domain (nginx proxy or CDN)\n * 2. NEXT_PUBLIC_API_URL   — direct Django API domain\n * 3. NEXT_PUBLIC_SITE_URL  — site domain (same-domain/static build)\n * 4. ''                    — relative URL (last resort)\n *\n * Use cases:\n * - Same domain (static build):   API_URL='' → relative /cfg/og/...\n * - Split domain (standalone):    API_URL=https://api.x.com → absolute\n * - Media via nginx proxy:        MEDIA_URL=https://x.com, API_URL=https://api.x.com\n * - CDN:                          MEDIA_URL=https://cdn.x.com\n */\nfunction resolveOgPublicBase(): string {\n  if (typeof process === 'undefined') return ''\n  return (\n    process.env.NEXT_PUBLIC_MEDIA_URL?.replace(/\\/$/, '') ??\n    process.env.NEXT_PUBLIC_API_URL?.replace(/\\/$/, '') ??\n    process.env.NEXT_PUBLIC_SITE_URL?.replace(/\\/$/, '') ??\n    ''\n  )\n}\n\nfunction encodeBase64(str: string): string {\n  if (typeof Buffer !== 'undefined') {\n    return Buffer.from(str).toString('base64url')\n  }\n  // Browser fallback\n  return btoa(unescape(encodeURIComponent(str)))\n    .replace(/\\+/g, '-')\n    .replace(/\\//g, '_')\n    .replace(/=+$/, '')\n}\n\nfunction cleanParams(params: OGImageParams): Record<string, unknown> {\n  return Object.fromEntries(\n    Object.entries(params).filter(\n      ([, v]) => v !== undefined && v !== null && v !== ''\n    )\n  )\n}\n\n/**\n * Builds an absolute (or relative) OG image URL pointing to Django's\n * django_ogimage endpoint: /cfg/og/<base64params>/\n *\n * The URL is suitable for use in og:image and twitter:image meta tags.\n */\nexport function buildOgUrl(params: OGImageParams): string {\n  const b64 = encodeBase64(JSON.stringify(cleanParams(params)))\n  const base = resolveOgPublicBase()\n  return `${base}/cfg/og/${b64}/`\n}\n","import type { Metadata } from 'next'\nimport type { OGImageParams, OgSpec } from './types'\nimport { buildOgUrl } from './url'\n\nconst OG_WIDTH = 1200\nconst OG_HEIGHT = 630\n\n/** A Next.js OG image entry. */\nfunction imageEntry(url: string, alt: string) {\n  return { url, width: OG_WIDTH, height: OG_HEIGHT, alt }\n}\n\n/**\n * Builds the og/twitter image fragment for a given image URL — the one place\n * that knows the shape Next.js expects. Both static URLs and the dynamic\n * renderer funnel through here, so there's a single source of truth.\n */\nfunction ogImageFragment(url: string, alt: string): Pick<Metadata, 'openGraph' | 'twitter'> {\n  return {\n    openGraph: { images: [imageEntry(url, alt)] },\n    twitter: { card: 'summary_large_image', images: [url] },\n  }\n}\n\n/**\n * Metadata fragment whose OG image is rendered by Django's django_ogimage\n * endpoint (/cfg/og/). Low-level — most callers use `createMetadata`'s `og`\n * field instead.\n */\nexport function createOgMetadata(params: OGImageParams): Metadata {\n  return ogImageFragment(buildOgUrl(params), params.title)\n}\n\n/** Extract a plain title string from Next.js's title shapes. */\nexport function extractTitle(metadata: Metadata): string {\n  const t = metadata.title\n  if (!t) return ''\n  if (typeof t === 'string') return t\n  if (typeof t === 'object' && 'absolute' in t) return (t as { absolute: string }).absolute\n  if (typeof t === 'object' && 'default' in t) return (t as { default: string }).default\n  return ''\n}\n\n/**\n * Resolves an `OgSpec` against a base Metadata into a concrete og/twitter image\n * fragment. `staticUrl` is the site's brand image, used for the `'static'` case.\n * Returns `null` only if there's genuinely nothing to set.\n *\n * This is the single decision point for \"what is the OG image\" — no other code\n * branches on the spec.\n */\nexport function resolveOgImage(\n  spec: OgSpec,\n  staticUrl: string,\n  fallbackTitle: string\n): Pick<Metadata, 'openGraph' | 'twitter'> {\n  if (spec === 'static') {\n    return ogImageFragment(staticUrl, fallbackTitle)\n  }\n  if (spec === 'dynamic') {\n    return ogImageFragment(buildOgUrl({ title: fallbackTitle }), fallbackTitle)\n  }\n  if ('image' in spec) {\n    return ogImageFragment(spec.image, spec.alt ?? fallbackTitle)\n  }\n  // { render: {...} } — dynamic with explicit params; title defaults to page title.\n  const title = spec.render.title ?? fallbackTitle\n  return ogImageFragment(buildOgUrl({ ...spec.render, title }), title)\n}\n\n/**\n * Merges OG image metadata (dynamic render) into existing Metadata. Kept for\n * low-level/manual use; `createMetadata` is the recommended entry point.\n *\n *   return withOgImage({ title: 'Page' }, { preset: 'DARK_BLUE' })\n */\nexport function withOgImage(\n  metadata: Metadata,\n  params: Omit<OGImageParams, 'title'> & { title?: string } = {}\n): Metadata {\n  const title = params.title ?? extractTitle(metadata)\n  const frag = createOgMetadata({ ...params, title })\n  return {\n    ...metadata,\n    openGraph: { ...metadata.openGraph, ...frag.openGraph },\n    twitter: { ...metadata.twitter, ...frag.twitter },\n  }\n}\n","import type { Metadata } from 'next'\nimport type { OgSpec } from './types'\nimport { resolveOgImage } from './metadata'\n\n/**\n * Site-wide identity the metadata factory needs. Config-agnostic on purpose —\n * the package doesn't know about any app's `settings` object, so the consumer\n * passes these once (typically derived from their own settings module).\n */\nexport interface SiteMetaConfig {\n  /** Brand / app name, e.g. \"CMDOP\". Used in titles, siteName, alt text. */\n  name: string\n  /** Default description used when a page doesn't supply its own. */\n  description: string\n  /** Absolute site origin, e.g. \"https://cmdop.com\". Used for canonical/og url. */\n  siteUrl: string\n  /** Ready-made static brand OG image URL (absolute or root-relative). */\n  ogImage: string\n  /** Optional favicon / apple-touch icons forwarded to Metadata.icons. */\n  icons?: Metadata['icons']\n  /** Locales for hreflang alternates. Omit for single-locale sites. */\n  locales?: readonly string[]\n  /** Locale used for x-default hreflang (defaults to \"en\" or first locale). */\n  defaultLocale?: string\n}\n\n/**\n * Per-page inputs. Only `title` is really worth setting per page; everything\n * else falls back to the site config.\n */\nexport interface PageMeta {\n  /** Page title (without the brand suffix). Falls back to the site name. */\n  title?: string\n  /** Page description; falls back to the site description. */\n  description?: string\n  keywords?: string[]\n  /** Current locale, used for canonical + openGraph.locale + alternates. */\n  locale?: string\n  /** Path without locale prefix, e.g. \"/skills\". '' for home. */\n  path?: string\n  /**\n   * What the OG image should be. Defaults to `'static'` (the brand image).\n   * - `'static'`          brand image from config (default)\n   * - `'dynamic'`         render the page title onto the card\n   * - `{ render: {...} }` render with explicit preset/layout/colors\n   * - `{ image, alt? }`   an exact image URL (e.g. a content screenshot)\n   */\n  og?: OgSpec\n  /** Escape hatch: extra Metadata fields merged last (robots, authors, etc.). */\n  extra?: Metadata\n}\n\nfunction buildAlternates(\n  config: SiteMetaConfig,\n  path: string,\n  locale: string\n): Metadata['alternates'] {\n  if (!config.locales?.length) {\n    return { canonical: `${config.siteUrl}/${path}`.replace(/\\/+$/, '') || config.siteUrl }\n  }\n  const languages: Record<string, string> = {}\n  for (const loc of config.locales) {\n    languages[loc] = `${config.siteUrl}/${loc}${path}`\n  }\n  const xDefault =\n    config.defaultLocale ?? (config.locales.includes('en') ? 'en' : config.locales[0])\n  languages['x-default'] = `${config.siteUrl}/${xDefault}${path}`\n  return { canonical: `${config.siteUrl}/${locale}${path}`, languages }\n}\n\n/**\n * Builds a complete Next.js `Metadata` from a one-time site config plus per-page\n * inputs — title-template, description, openGraph, twitter, canonical + hreflang,\n * icons, and the OG image — so pages only declare what's unique.\n *\n * The OG image is chosen by the single `og` field (defaults to the static brand\n * image). There is exactly one way to do each thing.\n *\n *   // app/_core/metadata.ts\n *   export const createMetadata = makeMetadataFactory({\n *     name: settings.app.name,\n *     description: settings.app.description,\n *     siteUrl: settings.app.siteUrl,\n *     ogImage: settings.app.media.ogimage,\n *     icons: { icon: settings.app.media.favicon },\n *     locales: LOCALES,\n *   })\n *\n *   // landing page — static brand image (default)\n *   export const metadata = createMetadata({ title: 'Pricing', path: '/pricing' })\n *   // content page — title rendered onto the card\n *   export const metadata = createMetadata({ title: post.title, path, og: 'dynamic' })\n *   // content page with its own image\n *   export const metadata = createMetadata({ title: p.name, og: { image: p.image } })\n */\nexport function createMetadata(config: SiteMetaConfig, page: PageMeta = {}): Metadata {\n  const title = page.title ?? config.name\n  const description = page.description ?? config.description\n  const locale = page.locale ?? config.defaultLocale ?? 'en'\n  const path = page.path ?? ''\n  const ogUrl = config.locales?.length\n    ? `${config.siteUrl}/${locale}${path}`\n    : `${config.siteUrl}${path}`\n\n  const ogImage = resolveOgImage(page.og ?? 'static', config.ogImage, title)\n\n  const metadata: Metadata = {\n    title,\n    description,\n    keywords: page.keywords,\n    alternates: buildAlternates(config, path, locale),\n    openGraph: {\n      type: 'website',\n      locale,\n      url: ogUrl,\n      siteName: config.name,\n      title,\n      description,\n      ...ogImage.openGraph,\n    },\n    twitter: {\n      title,\n      description,\n      ...ogImage.twitter,\n    },\n    icons: config.icons,\n  }\n\n  if (!page.extra) return metadata\n  // Shallow-merge the escape hatch, but deep-merge the nested og/twitter so the\n  // image we just set isn't clobbered by a partial `extra.openGraph`.\n  return {\n    ...metadata,\n    ...page.extra,\n    openGraph: { ...metadata.openGraph, ...page.extra.openGraph },\n    twitter: { ...metadata.twitter, ...page.extra.twitter },\n  }\n}\n\n/**\n * Curries `createMetadata` with a fixed site config so pages call a zero-config\n * factory. This is the single recommended entry point for app metadata.\n */\nexport function makeMetadataFactory(config: SiteMetaConfig) {\n  return (page: PageMeta = {}): Metadata => createMetadata(config, page)\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/nextjs",
-  "version": "2.1.438",
+  "version": "2.1.439",
   "description": "Next.js server utilities: sitemap, health, OG images, contact forms, navigation, config",
   "keywords": [
     "nextjs",
@@ -143,9 +143,9 @@
     "ai-docs": "tsx src/ai/cli.ts"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.438",
-    "@djangocfg/monitor": "^2.1.438",
-    "@djangocfg/ui-core": "^2.1.438",
+    "@djangocfg/i18n": "^2.1.439",
+    "@djangocfg/monitor": "^2.1.439",
+    "@djangocfg/ui-core": "^2.1.439",
     "next": "^16.2.2"
   },
   "peerDependenciesMeta": {
@@ -167,11 +167,11 @@
     "serwist": "^9.2.3"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.438",
-    "@djangocfg/monitor": "^2.1.438",
-    "@djangocfg/ui-core": "^2.1.438",
-    "@djangocfg/layouts": "^2.1.438",
-    "@djangocfg/typescript-config": "^2.1.438",
+    "@djangocfg/i18n": "^2.1.439",
+    "@djangocfg/monitor": "^2.1.439",
+    "@djangocfg/ui-core": "^2.1.439",
+    "@djangocfg/layouts": "^2.1.439",
+    "@djangocfg/typescript-config": "^2.1.439",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",

package/src/og-image/README.md

@@ -1,30 +1,80 @@
 # @djangocfg/nextjs/og-image
 
-Typed URL builder for Django's `django_ogimage` renderer.
+Page metadata + typed OG image builder for Django's `django_ogimage` renderer.
 
 **No Edge Runtime. No `@vercel/og`. No JSX templates.**
 Django renders and caches the PNG — Next.js only builds the URL and injects it into metadata.
 
 ---
 
+## Quick start
+
+One factory per app; pages declare only what's unique. The OG image is chosen by
+a single `og` field (defaults to your static brand image):
+
+```typescript
+// app/_core/metadata.ts — bind the factory once
+import { makeMetadataFactory } from '@djangocfg/nextjs/og-image'
+import { settings } from './settings'
+import { LOCALES } from '@i18n/locales.config'
+
+export const createMetadata = makeMetadataFactory({
+  name: settings.app.name,
+  description: settings.app.description,
+  siteUrl: settings.app.siteUrl,
+  ogImage: settings.app.media.ogimage,     // static brand card (the default)
+  icons: { icon: settings.app.media.favicon },
+  locales: LOCALES,                        // omit for single-locale sites
+})
+
+// any page.tsx
+export const metadata = createMetadata({ title: 'Pricing', path: '/pricing' })
+//                        ↑ static brand image, canonical, hreflang, og, twitter, icons
+```
+
+```typescript
+// content page — render the title onto the OG card
+export const metadata = createMetadata({ title: post.title, path, og: 'dynamic' })
+
+// content page with its own image (a screenshot, cover, …)
+export const metadata = createMetadata({ title: p.name, path, og: { image: p.image, alt: p.name } })
+```
+
+### The `og` axis (`OgSpec`)
+
+A single discriminated union decides what the OG image is — there is exactly one
+way to express each case:
+
+| `og` value | Result |
+|---|---|
+| omitted / `'static'` | the brand image from `config.ogImage` (default) |
+| `'dynamic'` | Django renders the page **title** onto the card |
+| `{ render: { preset, layout, … } }` | dynamic render with explicit params |
+| `{ image, alt? }` | an exact image URL (content screenshot, cover) |
+
+---
+
 ## How It Works
 
 ```
-generateMetadata() / withOgImage()
+createMetadata({ … , og })   — picks the OG image by the single `og` field
+    ↓  (dynamic cases only)
+buildOgUrl(params)           — base64-encodes OGImageParams
     ↓
-buildOgUrl(params)          — base64-encodes OGImageParams
-    ↓
-resolveOgPublicBase()       — picks the right base URL from env vars
+resolveOgPublicBase()        — picks the right base URL from env vars
     ↓
 <meta og:image> = "{base}/cfg/og/{b64}/"
 
 Crawler/browser hits that URL
     ↓
-Django OGImageRenderView    — decodes params, renders PNG via PicTex
+Django OGImageRenderView     — decodes params, renders PNG via PicTex
     ↓
 FileResponse (cached in MEDIA_ROOT/ogimage/<sharded>/<key>.png)
 ```
 
+Static / `{ image }` cases skip Django entirely — the URL points straight at the
+given image.
+
 ---
 
 ## URL Resolution
@@ -66,45 +116,70 @@ NEXT_PUBLIC_MEDIA_URL=https://cdn.example.com
 
 ## API
 
-### `buildOgUrl(params)`
+### Recommended
 
-Builds the raw OG image URL string. Useful when you need the URL directly.
+#### `makeMetadataFactory(config) → (page) => Metadata`
 
-```typescript
-import { buildOgUrl } from '@djangocfg/nextjs/og-image'
+Binds a `SiteMetaConfig` once and returns a per-page factory. This is the single
+recommended entry point.
 
-const url = buildOgUrl({ title: 'Hello', preset: 'DARK_BLUE' })
-// → "https://api.example.com/cfg/og/eyJ0aXRsZSI6Ikhlb.../"
+```typescript
+const createMetadata = makeMetadataFactory(config)
+export const metadata = createMetadata({ title: 'About', path: '/about' })
 ```
 
-### `createOgMetadata(params)`
+**`SiteMetaConfig`**
 
-Returns a Next.js `Metadata` fragment with `openGraph.images` and `twitter.images`.
+| Field | Type | Notes |
+|---|---|---|
+| `name` | `string` | brand name (titles, siteName, alt) |
+| `description` | `string` | default description |
+| `siteUrl` | `string` | absolute origin, e.g. `https://example.com` |
+| `ogImage` | `string` | static brand OG image URL |
+| `icons?` | `Metadata['icons']` | favicon / apple-touch |
+| `locales?` | `readonly string[]` | for hreflang; omit for single-locale |
+| `defaultLocale?` | `string` | x-default locale (defaults `en` / first) |
 
-```typescript
-import { createOgMetadata } from '@djangocfg/nextjs/og-image'
+**`PageMeta`**
 
-export async function generateMetadata() {
-  return createOgMetadata({ title: 'Page', preset: 'DARK_BLUE' })
-}
-// → { openGraph: { images: [{ url, width: 1200, height: 630 }] }, twitter: { ... } }
-```
+| Field | Type | Notes |
+|---|---|---|
+| `title?` | `string` | falls back to `config.name` |
+| `description?` | `string` | falls back to `config.description` |
+| `keywords?` | `string[]` | |
+| `locale?` | `string` | canonical + `openGraph.locale` |
+| `path?` | `string` | path without locale prefix, `''` for home |
+| `og?` | `OgSpec` | the OG image axis (see table above) |
+| `extra?` | `Metadata` | escape hatch merged last (robots, authors, title-template, …) |
 
-### `withOgImage(metadata, params)`
+#### `createMetadata(config, page)`
 
-Merges OG image into an existing `Metadata` object. Auto-extracts `title` from metadata if not in params.
+The un-curried form `makeMetadataFactory` wraps. Use when you don't want a bound factory.
 
-```typescript
-import { withOgImage } from '@djangocfg/nextjs/og-image'
+### Low-level (escape hatches)
 
-export async function generateMetadata(): Promise<Metadata> {
-  return withOgImage(
-    { title: 'Product Page', description: 'Buy now' },
-    { preset: 'DARK_BLUE', layout: 'HERO' }
-  )
-}
+Most pages never need these — they're the primitives the factory is built on.
+
+#### `buildOgUrl(params)`
+
+Raw OG image URL string for the dynamic renderer.
+
+```typescript
+const url = buildOgUrl({ title: 'Hello', preset: 'DARK_BLUE' })
+// → "https://api.example.com/cfg/og/eyJ0aXRsZSI6Ikhlb.../"
 ```
 
+#### `createOgMetadata(params)` · `withOgImage(metadata, params)`
+
+`createOgMetadata` returns a `{ openGraph, twitter }` image fragment for the
+dynamic renderer; `withOgImage` merges that fragment into an existing `Metadata`
+(auto-extracting `title`). Both are for manual metadata assembly outside the factory.
+
+#### `resolveOgImage(spec, staticUrl, fallbackTitle)`
+
+The single decision point that turns an `OgSpec` into an image fragment — exported
+for advanced custom factories.
+
 ---
 
 ## OGImageParams