@djangocfg/nextjs 2.1.470 → 2.1.471

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

@@ -80,7 +80,11 @@ interface PageMeta {
     keywords?: string[];
     /** Current locale, used for canonical + openGraph.locale + alternates. */
     locale?: string;
-    /** Path without locale prefix, e.g. "/skills". '' for home. */
+    /**
+     * Path without locale prefix, e.g. "/skills" or "/skills/foo". Home is ''
+     * (or '/'). Leading/trailing slashes are normalized, so both canonical and
+     * og:url come out well-formed whichever you pass.
+     */
     path?: string;
     /**
      * What the OG image should be. Defaults to `'static'` (the brand image).

package/dist/og-image/index.mjs

@@ -70,24 +70,29 @@ function withOgImage(metadata, params = {}) {
 }
 
 // src/og-image/metadata-factory.ts
+function buildUrl(siteUrl, locale, path) {
+  const origin = siteUrl.replace(/\/+$/, "");
+  const segments = [locale, path].map((segment) => segment?.replace(/^\/+|\/+$/g, "") ?? "").filter(Boolean);
+  return segments.length ? `${origin}/${segments.join("/")}` : origin;
+}
 function buildAlternates(config, path, locale) {
   if (!config.locales?.length) {
-    return { canonical: `${config.siteUrl}/${path}`.replace(/\/+$/, "") || config.siteUrl };
+    return { canonical: buildUrl(config.siteUrl, void 0, path) };
   }
   const languages = {};
   for (const loc of config.locales) {
-    languages[loc] = `${config.siteUrl}/${loc}${path}`;
+    languages[loc] = buildUrl(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 };
+  languages["x-default"] = buildUrl(config.siteUrl, xDefault, path);
+  return { canonical: buildUrl(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 ogUrl = buildUrl(config.siteUrl, config.locales?.length ? locale : void 0, path);
   const ogImage = resolveOgImage(page.og ?? "static", config.ogImage, title, config.ogBackend);
   const metadata = {
     title,

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 *\n * @param base Optional explicit backend origin (e.g. \"https://api.example.com\").\n *   When omitted, it's resolved from env (MEDIA_URL → API_URL → SITE_URL → '').\n *   Pass the `ogBackend` from your site config to avoid relying on env.\n */\nexport function buildOgUrl(params: OGImageParams, base?: string): string {\n  const b64 = encodeBase64(JSON.stringify(cleanParams(params)))\n  const origin = (base ?? resolveOgPublicBase()).replace(/\\/$/, '')\n  return `${origin}/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 *\n * `backend` is the Django origin that serves the dynamic renderer. The dynamic\n * cases (`'dynamic'`, `{ render }`) require it: when it's `undefined`/empty —\n * e.g. a frontend with no Django backend — they **fall back to the static brand\n * image** instead of emitting a broken `/cfg/og/` URL. (`undefined` still lets\n * `buildOgUrl` fall back to env vars; pass `''` to force the static fallback.)\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  backend?: string\n): Pick<Metadata, 'openGraph' | 'twitter'> {\n  const canRenderDynamic = backend === undefined || backend !== ''\n\n  if (spec === 'static') {\n    return ogImageFragment(staticUrl, fallbackTitle)\n  }\n  if (spec === 'dynamic') {\n    return canRenderDynamic\n      ? ogImageFragment(buildOgUrl({ title: fallbackTitle }, backend), fallbackTitle)\n      : ogImageFragment(staticUrl, 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 canRenderDynamic\n    ? ogImageFragment(buildOgUrl({ ...spec.render, title }, backend), title)\n    : ogImageFragment(staticUrl, 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  /**\n   * Django origin that serves the dynamic OG renderer (`/cfg/og/`), e.g.\n   * \"https://api.example.com\". Required for `og: 'dynamic'` / `{ render }`.\n   *\n   * - set    → dynamic OG images render against this origin\n   * - `''`   → no backend: dynamic specs fall back to the static brand image\n   *            (use this for a frontend with no Django, so no broken URLs)\n   * - omit   → fall back to env vars (MEDIA_URL → API_URL → SITE_URL)\n   */\n  ogBackend?: 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, config.ogBackend)\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":[]}
+{"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 *\n * @param base Optional explicit backend origin (e.g. \"https://api.example.com\").\n *   When omitted, it's resolved from env (MEDIA_URL → API_URL → SITE_URL → '').\n *   Pass the `ogBackend` from your site config to avoid relying on env.\n */\nexport function buildOgUrl(params: OGImageParams, base?: string): string {\n  const b64 = encodeBase64(JSON.stringify(cleanParams(params)))\n  const origin = (base ?? resolveOgPublicBase()).replace(/\\/$/, '')\n  return `${origin}/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 *\n * `backend` is the Django origin that serves the dynamic renderer. The dynamic\n * cases (`'dynamic'`, `{ render }`) require it: when it's `undefined`/empty —\n * e.g. a frontend with no Django backend — they **fall back to the static brand\n * image** instead of emitting a broken `/cfg/og/` URL. (`undefined` still lets\n * `buildOgUrl` fall back to env vars; pass `''` to force the static fallback.)\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  backend?: string\n): Pick<Metadata, 'openGraph' | 'twitter'> {\n  const canRenderDynamic = backend === undefined || backend !== ''\n\n  if (spec === 'static') {\n    return ogImageFragment(staticUrl, fallbackTitle)\n  }\n  if (spec === 'dynamic') {\n    return canRenderDynamic\n      ? ogImageFragment(buildOgUrl({ title: fallbackTitle }, backend), fallbackTitle)\n      : ogImageFragment(staticUrl, 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 canRenderDynamic\n    ? ogImageFragment(buildOgUrl({ ...spec.render, title }, backend), title)\n    : ogImageFragment(staticUrl, 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  /**\n   * Django origin that serves the dynamic OG renderer (`/cfg/og/`), e.g.\n   * \"https://api.example.com\". Required for `og: 'dynamic'` / `{ render }`.\n   *\n   * - set    → dynamic OG images render against this origin\n   * - `''`   → no backend: dynamic specs fall back to the static brand image\n   *            (use this for a frontend with no Django, so no broken URLs)\n   * - omit   → fall back to env vars (MEDIA_URL → API_URL → SITE_URL)\n   */\n  ogBackend?: 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  /**\n   * Path without locale prefix, e.g. \"/skills\" or \"/skills/foo\". Home is ''\n   * (or '/'). Leading/trailing slashes are normalized, so both canonical and\n   * og:url come out well-formed whichever you pass.\n   */\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\n/**\n * Joins the site origin, an optional locale segment, and a page path into one\n * absolute URL.\n *\n * This is the SINGLE place the URL shape is decided. `canonical` and\n * `openGraph.url` describe the same page, so they must be built by the same\n * function — when they were two hand-rolled template literals they drifted\n * apart (one inserted a slash the other didn't), and a page shipped a canonical\n * and an og:url pointing at two different URLs.\n *\n * Contract (see `PageMeta.path`): `path` carries its own leading slash —\n * \"/skills\", \"/skills/foo\" — and home is '' (we also tolerate '/'). Segments\n * are normalized rather than trusted, so a stray or missing slash at a call\n * site cannot produce \"site.com//skills\" or \"site.comskills\".\n */\nfunction buildUrl(siteUrl: string, locale: string | undefined, path: string): string {\n  const origin = siteUrl.replace(/\\/+$/, '')\n  const segments = [locale, path]\n    .map((segment) => segment?.replace(/^\\/+|\\/+$/g, '') ?? '')\n    .filter(Boolean)\n  return segments.length ? `${origin}/${segments.join('/')}` : origin\n}\n\nfunction buildAlternates(\n  config: SiteMetaConfig,\n  path: string,\n  locale: string\n): Metadata['alternates'] {\n  if (!config.locales?.length) {\n    return { canonical: buildUrl(config.siteUrl, undefined, path) }\n  }\n  const languages: Record<string, string> = {}\n  for (const loc of config.locales) {\n    languages[loc] = buildUrl(config.siteUrl, loc, path)\n  }\n  const xDefault =\n    config.defaultLocale ?? (config.locales.includes('en') ? 'en' : config.locales[0])\n  languages['x-default'] = buildUrl(config.siteUrl, xDefault, path)\n  return { canonical: buildUrl(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  // Same builder as the canonical below — og:url and canonical name the same\n  // page, so they are never allowed to be assembled by two different rules.\n  const ogUrl = buildUrl(config.siteUrl, config.locales?.length ? locale : undefined, path)\n\n  const ogImage = resolveOgImage(page.og ?? 'static', config.ogImage, title, config.ogBackend)\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.470",
+  "version": "2.1.471",
   "description": "Next.js server utilities: sitemap, health, OG images, contact forms, navigation, config",
   "keywords": [
     "nextjs",
@@ -140,12 +140,13 @@
     "clean": "rm -rf dist",
     "lint": "eslint .",
     "check": "tsc --noEmit",
+    "test": "tsx --test src/**/*.test.ts",
     "ai-docs": "tsx src/ai/cli.ts"
   },
   "peerDependencies": {
-    "@djangocfg/devtools": "^2.1.470",
-    "@djangocfg/i18n": "^2.1.470",
-    "@djangocfg/ui-core": "^2.1.470",
+    "@djangocfg/devtools": "^2.1.471",
+    "@djangocfg/i18n": "^2.1.471",
+    "@djangocfg/ui-core": "^2.1.471",
     "next": "^16.2.2"
   },
   "peerDependenciesMeta": {
@@ -167,11 +168,11 @@
     "serwist": "^9.5.11"
   },
   "devDependencies": {
-    "@djangocfg/devtools": "^2.1.470",
-    "@djangocfg/i18n": "^2.1.470",
-    "@djangocfg/layouts": "^2.1.470",
-    "@djangocfg/typescript-config": "^2.1.470",
-    "@djangocfg/ui-core": "^2.1.470",
+    "@djangocfg/devtools": "^2.1.471",
+    "@djangocfg/i18n": "^2.1.471",
+    "@djangocfg/layouts": "^2.1.471",
+    "@djangocfg/typescript-config": "^2.1.471",
+    "@djangocfg/ui-core": "^2.1.471",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",
     "@types/react-dom": "19.2.3",

package/src/og-image/metadata-factory.test.ts

@@ -0,0 +1,136 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+
+import { createMetadata, type SiteMetaConfig } from './metadata-factory'
+
+/**
+ * `canonical` and `og:url` name the SAME page. The bug this suite locks down is
+ * that they were built by two different template literals with opposite slash
+ * conventions, so they silently disagreed:
+ *
+ *   canonical: `${siteUrl}/${path}`   // path "/skills" -> "site.com//skills"
+ *   og:url:    `${siteUrl}${path}`    // path "skills"  -> "site.comskills"
+ *
+ * A consumer that "fixed" one by reshaping `path` at the call site necessarily
+ * broke the other. So every case below asserts BOTH tags together — that
+ * pairing is the actual invariant, not either URL on its own.
+ */
+
+const BASE: SiteMetaConfig = {
+  name: 'Marketplace',
+  description: 'Capability catalogue',
+  siteUrl: 'https://marketplace.cmdop.com',
+  ogImage: '/opengraph-image',
+  ogBackend: '',
+}
+
+const LOCALIZED: SiteMetaConfig = {
+  ...BASE,
+  siteUrl: 'https://cmdop.com',
+  locales: ['en', 'de'],
+  defaultLocale: 'en',
+}
+
+/** Reads back the two URLs the factory is supposed to keep in lock-step. */
+function urlsFor(config: SiteMetaConfig, page: Parameters<typeof createMetadata>[1]) {
+  const meta = createMetadata(config, page)
+  const alternates = meta.alternates as { canonical?: string; languages?: Record<string, string> }
+  const openGraph = meta.openGraph as { url?: string } | undefined
+  return { canonical: alternates?.canonical, ogUrl: openGraph?.url, languages: alternates?.languages }
+}
+
+/** The single invariant: both tags point at the one expected URL. */
+function assertBoth(
+  config: SiteMetaConfig,
+  page: Parameters<typeof createMetadata>[1],
+  expected: string
+) {
+  const { canonical, ogUrl } = urlsFor(config, page)
+  assert.equal(canonical, expected, 'canonical')
+  assert.equal(ogUrl, expected, 'og:url')
+  assert.equal(canonical, ogUrl, 'canonical and og:url must agree')
+}
+
+// ── no locales (marketplace, llm, mark) ──────────────────────────────────────
+
+test('no-locale + home (path: "") → bare site URL', () => {
+  assertBoth(BASE, { title: 'Home', path: '' }, 'https://marketplace.cmdop.com')
+})
+
+test('no-locale + home (path omitted) → bare site URL', () => {
+  assertBoth(BASE, { title: 'Home' }, 'https://marketplace.cmdop.com')
+})
+
+test('no-locale + home (path: "/") → bare site URL, not a trailing slash', () => {
+  // `routes.home` is literally '/' in apps/marketplace, so this is a real input.
+  assertBoth(BASE, { title: 'Home', path: '/' }, 'https://marketplace.cmdop.com')
+})
+
+test('no-locale + "/skills" → one slash, not two, not zero', () => {
+  assertBoth(BASE, { title: 'Skills', path: '/skills' }, 'https://marketplace.cmdop.com/skills')
+})
+
+test('no-locale + nested "/skills/foo" → the live bug: og:url glued the domain to the path', () => {
+  assertBoth(
+    BASE,
+    { title: 'Foo', path: '/skills/foo' },
+    'https://marketplace.cmdop.com/skills/foo'
+  )
+})
+
+// ── locales (web) ────────────────────────────────────────────────────────────
+
+test('locale + home → origin + locale only', () => {
+  assertBoth(LOCALIZED, { title: 'Home', path: '', locale: 'en' }, 'https://cmdop.com/en')
+})
+
+test('locale + "/pricing" → origin + locale + path', () => {
+  assertBoth(
+    LOCALIZED,
+    { title: 'Pricing', path: '/pricing', locale: 'de' },
+    'https://cmdop.com/de/pricing'
+  )
+})
+
+test('locale + nested path', () => {
+  assertBoth(
+    LOCALIZED,
+    { title: 'Terms', path: '/legal/terms', locale: 'en' },
+    'https://cmdop.com/en/legal/terms'
+  )
+})
+
+test('locale hreflang alternates are built by the same rule', () => {
+  const { languages } = urlsFor(LOCALIZED, { title: 'Pricing', path: '/pricing', locale: 'en' })
+  assert.deepEqual(languages, {
+    en: 'https://cmdop.com/en/pricing',
+    de: 'https://cmdop.com/de/pricing',
+    'x-default': 'https://cmdop.com/en/pricing',
+  })
+})
+
+test('locale hreflang alternates at home carry no trailing slash', () => {
+  const { languages } = urlsFor(LOCALIZED, { title: 'Home', path: '', locale: 'en' })
+  assert.deepEqual(languages, {
+    en: 'https://cmdop.com/en',
+    de: 'https://cmdop.com/de',
+    'x-default': 'https://cmdop.com/en',
+  })
+})
+
+// ── normalization guards ─────────────────────────────────────────────────────
+
+test('a trailing slash on the site URL does not double up', () => {
+  assertBoth(
+    { ...BASE, siteUrl: 'https://marketplace.cmdop.com/' },
+    { title: 'Skills', path: '/skills' },
+    'https://marketplace.cmdop.com/skills'
+  )
+})
+
+test('an off-contract slash-less path still yields a well-formed URL', () => {
+  // The old consumer wrapper stripped the leading slash before calling the
+  // factory. That workaround is gone, but a call site that passes 'skills'
+  // must still not produce "site.comskills".
+  assertBoth(BASE, { title: 'Skills', path: 'skills' }, 'https://marketplace.cmdop.com/skills')
+})

package/src/og-image/metadata-factory.ts

@@ -46,7 +46,11 @@ export interface PageMeta {
   keywords?: string[]
   /** Current locale, used for canonical + openGraph.locale + alternates. */
   locale?: string
-  /** Path without locale prefix, e.g. "/skills". '' for home. */
+  /**
+   * Path without locale prefix, e.g. "/skills" or "/skills/foo". Home is ''
+   * (or '/'). Leading/trailing slashes are normalized, so both canonical and
+   * og:url come out well-formed whichever you pass.
+   */
   path?: string
   /**
    * What the OG image should be. Defaults to `'static'` (the brand image).
@@ -60,22 +64,45 @@ export interface PageMeta {
   extra?: Metadata
 }
 
+/**
+ * Joins the site origin, an optional locale segment, and a page path into one
+ * absolute URL.
+ *
+ * This is the SINGLE place the URL shape is decided. `canonical` and
+ * `openGraph.url` describe the same page, so they must be built by the same
+ * function — when they were two hand-rolled template literals they drifted
+ * apart (one inserted a slash the other didn't), and a page shipped a canonical
+ * and an og:url pointing at two different URLs.
+ *
+ * Contract (see `PageMeta.path`): `path` carries its own leading slash —
+ * "/skills", "/skills/foo" — and home is '' (we also tolerate '/'). Segments
+ * are normalized rather than trusted, so a stray or missing slash at a call
+ * site cannot produce "site.com//skills" or "site.comskills".
+ */
+function buildUrl(siteUrl: string, locale: string | undefined, path: string): string {
+  const origin = siteUrl.replace(/\/+$/, '')
+  const segments = [locale, path]
+    .map((segment) => segment?.replace(/^\/+|\/+$/g, '') ?? '')
+    .filter(Boolean)
+  return segments.length ? `${origin}/${segments.join('/')}` : origin
+}
+
 function buildAlternates(
   config: SiteMetaConfig,
   path: string,
   locale: string
 ): Metadata['alternates'] {
   if (!config.locales?.length) {
-    return { canonical: `${config.siteUrl}/${path}`.replace(/\/+$/, '') || config.siteUrl }
+    return { canonical: buildUrl(config.siteUrl, undefined, path) }
   }
   const languages: Record<string, string> = {}
   for (const loc of config.locales) {
-    languages[loc] = `${config.siteUrl}/${loc}${path}`
+    languages[loc] = buildUrl(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 }
+  languages['x-default'] = buildUrl(config.siteUrl, xDefault, path)
+  return { canonical: buildUrl(config.siteUrl, locale, path), languages }
 }
 
 /**
@@ -108,9 +135,9 @@ export function createMetadata(config: SiteMetaConfig, page: PageMeta = {}): Met
   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}`
+  // Same builder as the canonical below — og:url and canonical name the same
+  // page, so they are never allowed to be assembled by two different rules.
+  const ogUrl = buildUrl(config.siteUrl, config.locales?.length ? locale : undefined, path)
 
   const ogImage = resolveOgImage(page.og ?? 'static', config.ogImage, title, config.ogBackend)