@djangocfg/nextjs 2.1.437 → 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,6 +37,84 @@ interface OGImageParams {
     page_url?: string;
 }
 
+/**
+ * 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
+ * passes these once (typically derived from their own settings module).
+ */
+interface SiteMetaConfig {
+    /** Brand / app name, e.g. "CMDOP". Used in titles, siteName, alt text. */
+    name: string;
+    /** Default description used when a page doesn't supply its own. */
+    description: string;
+    /** Absolute site origin, e.g. "https://cmdop.com". Used for canonical/og url. */
+    siteUrl: string;
+    /** Ready-made static brand OG image URL (absolute or root-relative). */
+    ogImage: string;
+    /** Optional favicon / apple-touch icons forwarded to Metadata.icons. */
+    icons?: Metadata['icons'];
+    /** 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. Only `title` is really worth setting per page; everything
+ * else falls back to the site config.
+ */
+interface PageMeta {
+    /** 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. */
+    path?: string;
+    /**
+     * 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?: OgSpec;
+    /** Escape hatch: extra Metadata fields merged last (robots, authors, etc.). */
+    extra?: Metadata;
+}
+/**
+ * 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.
+ *
+ * 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({
+ *     name: settings.app.name,
+ *     description: settings.app.description,
+ *     siteUrl: settings.app.siteUrl,
+ *     ogImage: settings.app.media.ogimage,
+ *     icons: { icon: settings.app.media.favicon },
+ *     locales: LOCALES,
+ *   })
+ *
+ *   // 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. This is the single recommended entry point for app metadata.
+ */
+declare function makeMetadataFactory(config: SiteMetaConfig): (page?: PageMeta) => Metadata;
+
 /**
  * Builds an absolute (or relative) OG image URL pointing to Django's
  * django_ogimage endpoint: /cfg/og/<base64params>/
@@ -29,24 +124,30 @@ interface OGImageParams {
 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' })
+ * 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 into an existing Metadata object.
+ * Merges OG image metadata (dynamic render) into existing Metadata. Kept for
+ * low-level/manual use; `createMetadata` is the recommended entry point.
  *
- * Usage:
- *   return withOgImage(
- *     { title: 'Page', description: '...' },
- *     { preset: 'DARK_BLUE', layout: 'HERO' }
- *   )
+ *   return withOgImage({ title: 'Page' }, { preset: 'DARK_BLUE' })
  */
-declare function withOgImage(metadata: Metadata, params: Omit<OGImageParams, 'title'> & {
+declare function withOgImage(metadata: Metadata, params?: Omit<OGImageParams, 'title'> & {
     title?: string;
 }): Metadata;
 
-export { type OGImageParams, type OGLayout, type OGPreset, buildOgUrl, createOgMetadata, withOgImage };
+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,37 +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 resolvedParams = {
-    title: extractTitle(metadata),
-    ...params
-  };
-  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 "";
@@ -62,9 +45,88 @@ 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}/${path}`.replace(/\/+$/, "") || config.siteUrl };
+  }
+  const languages = {};
+  for (const loc of config.locales) {
+    languages[loc] = `${config.siteUrl}/${loc}${path}`;
+  }
+  const xDefault = config.defaultLocale ?? (config.locales.includes("en") ? "en" : config.locales[0]);
+  languages["x-default"] = `${config.siteUrl}/${xDefault}${path}`;
+  return { canonical: `${config.siteUrl}/${locale}${path}`, languages };
+}
+function createMetadata(config, page = {}) {
+  const title = page.title ?? config.name;
+  const description = page.description ?? config.description;
+  const locale = page.locale ?? config.defaultLocale ?? "en";
+  const path = page.path ?? "";
+  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,
+    alternates: buildAlternates(config, path, locale),
+    openGraph: {
+      type: "website",
+      locale,
+      url: ogUrl,
+      siteName: config.name,
+      title,
+      description,
+      ...ogImage.openGraph
+    },
+    twitter: {
+      title,
+      description,
+      ...ogImage.twitter
+    },
+    icons: config.icons
+  };
+  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);
+}
 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"],"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 * Merges og:image metadata into an existing Metadata object.\n *\n * Usage:\n *   return withOgImage(\n *     { title: 'Page', description: '...' },\n *     { preset: 'DARK_BLUE', layout: 'HERO' }\n *   )\n */\nexport function withOgImage(\n  metadata: Metadata,\n  params: Omit<OGImageParams, 'title'> & { title?: string }\n): Metadata {\n  // Auto-extract title from metadata; params.title overrides if explicitly provided\n  const resolvedParams: OGImageParams = {\n    title: extractTitle(metadata),\n    ...params,\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"],"mappings":";AAkBA,SAAS,sBAA8B;AACrC,MAAI,OAAO,YAAY,YAAa,QAAO;AAC3C,SACE,QAAQ,IAAI,uBAAuB,QAAQ,OAAO,EAAE,KACpD,QAAQ,IAAI,qBAAqB,QAAQ,OAAO,EAAE,KAClD,QAAQ,IAAI,sBAAsB,QAAQ,OAAO,EAAE,KACnD;AAEJ;AAEA,SAAS,aAAa,KAAqB;AACzC,MAAI,OAAO,WAAW,aAAa;AACjC,WAAO,OAAO,KAAK,GAAG,EAAE,SAAS,WAAW;AAAA,EAC9C;AAEA,SAAO,KAAK,SAAS,mBAAmB,GAAG,CAAC,CAAC,EAC1C,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,EAAE;AACtB;AAEA,SAAS,YAAY,QAAgD;AACnE,SAAO,OAAO;AAAA,IACZ,OAAO,QAAQ,MAAM,EAAE;AAAA,MACrB,CAAC,CAAC,EAAE,CAAC,MAAM,MAAM,UAAa,MAAM,QAAQ,MAAM;AAAA,IACpD;AAAA,EACF;AACF;AAQO,SAAS,WAAW,QAA+B;AACxD,QAAM,MAAM,aAAa,KAAK,UAAU,YAAY,MAAM,CAAC,CAAC;AAC5D,QAAM,OAAO,oBAAoB;AACjC,SAAO,GAAG,IAAI,WAAW,GAAG;AAC9B;;;AC9CO,SAAS,iBAAiB,QAAiC;AAChE,QAAM,MAAM,WAAW,MAAM;AAC7B,QAAM,QAAQ,EAAE,KAAK,OAAO,MAAM,QAAQ,KAAK,KAAK,OAAO,MAAM;AACjE,SAAO;AAAA,IACL,WAAW;AAAA,MACT,QAAQ,CAAC,KAAK;AAAA,IAChB;AAAA,IACA,SAAS;AAAA,MACP,MAAM;AAAA,MACN,QAAQ,CAAC,GAAG;AAAA,IACd;AAAA,EACF;AACF;AAWO,SAAS,YACd,UACA,QACU;AAEV,QAAM,iBAAgC;AAAA,IACpC,OAAO,aAAa,QAAQ;AAAA,IAC5B,GAAG;AAAA,EACL;AAEA,QAAM,SAAS,iBAAiB,cAAc;AAE9C,SAAO;AAAA,IACL,GAAG;AAAA,IACH,WAAW;AAAA,MACT,GAAG,SAAS;AAAA,MACZ,GAAG,OAAO;AAAA,IACZ;AAAA,IACA,SAAS;AAAA,MACP,GAAG,SAAS;AAAA,MACZ,GAAG,OAAO;AAAA,IACZ;AAAA,EACF;AACF;AAEA,SAAS,aAAa,UAA4B;AAChD,QAAM,IAAI,SAAS;AACnB,MAAI,CAAC,EAAG,QAAO;AACf,MAAI,OAAO,MAAM,SAAU,QAAO;AAClC,MAAI,OAAO,MAAM,YAAY,cAAc,EAAG,QAAQ,EAA2B;AACjF,MAAI,OAAO,MAAM,YAAY,aAAa,EAAG,QAAQ,EAA0B;AAC/E,SAAO;AACT;","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.437",
+  "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.437",
-    "@djangocfg/monitor": "^2.1.437",
-    "@djangocfg/ui-core": "^2.1.437",
+    "@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.437",
-    "@djangocfg/monitor": "^2.1.437",
-    "@djangocfg/ui-core": "^2.1.437",
-    "@djangocfg/layouts": "^2.1.437",
-    "@djangocfg/typescript-config": "^2.1.437",
+    "@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

package/src/og-image/index.ts

@@ -1,3 +1,11 @@
-export type { OGImageParams, OGPreset, OGLayout } from './types'
+// ── Recommended API ──────────────────────────────────────────────────────────
+// Bind the factory once per app, then call it from each page.
+export { createMetadata, makeMetadataFactory } from './metadata-factory'
+export type { SiteMetaConfig, PageMeta } from './metadata-factory'
+
+// ── Types ────────────────────────────────────────────────────────────────────
+export type { OGImageParams, OGPreset, OGLayout, OgSpec } from './types'
+
+// ── Low-level primitives (escape hatches) ────────────────────────────────────
 export { buildOgUrl } from './url'
-export { createOgMetadata, withOgImage } from './metadata'
+export { createOgMetadata, withOgImage, resolveOgImage, extractTitle } from './metadata'