@ingram-tech/nk-seo 0.6.2 → 0.8.0

package/README.md

@@ -5,8 +5,9 @@ keep re-implementing:
 
 1. **`<JsonLd>`** + **typed schema.org builders** — `faqPage`, `breadcrumbList`,
    `article`, `softwareApplication`, `organization`, `website`, `person`,
-   `localBusiness`, `event`, and a `createSeo` factory that resolves site-relative
-   paths and injects your publisher.
+   `localBusiness`, `event`, `dataset`, `definedTerm`/`definedTermSet`, and a
+   `createSeo` factory that resolves site-relative paths and injects your
+   publisher.
 2. **`createMetadata`** — a Next `Metadata` factory: canonical + OpenGraph +
    Twitter card from one title/description/path.
 3. **`createSitemap` / `createRobots`** — `app/sitemap.ts` and `app/robots.ts`
@@ -75,6 +76,53 @@ or an array (e.g. `[organization(org), website(site)]` on the homepage), and
 escapes `<` on serialization so CMS-sourced strings can't break out of the
 `<script>` tag.
 
+### Properties the builders don't cover
+
+schema.org is much larger than any builder surface, so every builder takes an
+`extra` object shallow-merged over the built payload (it wins on conflict).
+Reach for it rather than dropping the whole node back to a literal:
+
+```ts
+website({
+	name: "Acme",
+	url: "https://example.com",
+	extra: {
+		alternateName: "ACME",
+		inLanguage: ["en", "fr"],
+		potentialAction: {
+			"@type": "SearchAction",
+			target: "https://example.com/search?q={search_term_string}",
+			"query-input": "required name=search_term_string",
+		},
+	},
+});
+```
+
+`extra` works on nested inputs too — `publisher: { name: "Acme", extra: {…} }`.
+Values passed this way aren't reflected in the returned node type.
+
+For a node type no builder covers, `<JsonLd data={…} />` takes **any** object or
+array of objects. Hand-written nodes still get the `<` / U+2028 escaping, which
+is the security-relevant half of the package — worth preferring over
+`dangerouslySetInnerHTML` even with no builder involved.
+
+`article` covers `Article`, `BlogPosting`, `NewsArticle`, `ScholarlyArticle`,
+`TechArticle` (the right type for API/developer docs) and `Report` via `type`.
+`dataset` and `definedTerm`/`definedTermSet` mark up data and controlled
+vocabularies:
+
+```ts
+<JsonLd
+	data={seo.definedTerm({
+		name: "Computer programming",
+		termCode: "62.01",
+		path: "/code/62.01",
+		inDefinedTermSet: { name: "Acme classification", path: "/", version: "2025" },
+		extra: { inLanguage: "en" },
+	})}
+/>
+```
+
 ## Page metadata
 
 ```ts
@@ -103,10 +151,26 @@ export const metadata = pageMetadata({
 
 Produces `title`, `description`, a self-referencing `alternates.canonical`,
 `openGraph`, and a `summary_large_image` Twitter card. Pass `noIndex`, `keywords`,
-`type: "article"`, or per-page `openGraph`/`twitter` overrides as needed. With
+`type: "article"`, or per-page `alternates`/`openGraph`/`twitter` overrides as
+needed — each is merged into the generated object and wins on conflict. With
 `titleTemplate` set, `pageMetadata.root()` emits `title.template`, so plain page
 titles render as "Services | Acme" without every page appending the suffix.
 
+On a localized site the per-page `alternates` and `locale` are what make the
+factory usable — `alternates.languages` is what Next renders as
+`<link rel="alternate" hreflang>`, and `og:locale` has to vary per page:
+
+```ts
+import { hreflangAlternates } from "@ingram-tech/nk-seo";
+
+const { languages } = hreflangAlternates(HREFLANG_CONFIG, `/${locale}/about`);
+return pageMetadata({
+	title, description, path: `/${locale}/about`,
+	alternates: { languages },
+	locale: "fr_BE",   // overrides the site-wide `locale`
+});
+```
+
 ## Sitemap & robots
 
 ```ts
@@ -171,17 +235,50 @@ Pass `logo` (absolute URL or data URI) to replace the accent-square mark with
 your logo, and `fonts` + `fontFamily` to render with the brand typeface —
 `fonts` is forwarded to `ImageResponse`, which takes raw TTF/OTF/WOFF data.
 
+### Two ways the generated card silently doesn't reach your pages
+
+Both fail with a green build and no warning; only fetching each page type shows
+them.
+
+**A page's own `openGraph` drops the inherited image.** Next attaches a
+file-convention image to the segment that declares it, and sibling metadata
+objects are *replaced*, not deep-merged — so any page whose `generateMetadata`
+returns an `openGraph` object (i.e. any page setting `og:title`/`og:url`) emits
+no `og:image` at all. The home page, sitting in the same segment as the image
+file, looks perfectly correct throughout. Build the list once and spread it into
+every page:
+
+```ts
+import { ogImageMetadata } from "@ingram-tech/nk-seo";
+
+const images = ogImageMetadata({ baseUrl, path: "/opengraph-image", alt: "Acme" });
+return { title, openGraph: { title, url, images } };
+```
+
+`createMetadata`'s `defaultImage` / per-page `image` already do this — point
+either at the image route and every page it builds carries the card.
+
+**Locale-negotiating middleware eats the image route.** A site that redirects
+any path lacking a locale prefix also redirects `/opengraph-image`, so the card
+URL never resolves. Put the file at `app/[locale]/opengraph-image.tsx` instead:
+it dodges the redirect and gives per-locale cards from `params`. That is the
+better default for any localized site.
+
 The template encodes the Satori rule that trips everyone up: every node with
 more than one child sets `display: flex`, and text nodes are never mixed with
 sibling elements — so the headline stays a plain string and the accent rides on
 the mark, not a coloured `<span>` inside the title.
 
-No linter or type-check validates Satori-supported CSS (`ImageResponse` accepts
-all of `React.CSSProperties`; Satori silently drops what it doesn't know), so
-the only real validator is rendering. This package renders its template through
-the real satori + resvg pipeline in its own tests; if a site hand-rolls extra
-cards, give it the same guard — a vitest file (node environment) that renders
-each `opengraph-image.tsx` and asserts a valid PNG comes out.
+Type-check won't help here: `ImageResponse` accepts all of
+`React.CSSProperties` and Satori silently drops what it doesn't know. Two guards
+cover that. `@ingram-tech/nk-dev`'s oxlint plugin ships `nextkit/satori-css`,
+which flags unsupported style properties, `calc()`, and the two structural rules
+in files that import `next/og` or are an `opengraph-image`/`twitter-image`
+convention. And rendering remains the final validator: this package renders its
+template through the real satori + resvg pipeline in its own tests, so a site
+hand-rolling extra cards should add the same guard — a vitest file (node
+environment) that renders each `opengraph-image.tsx` and asserts a valid PNG
+comes out.
 
 ## Hreflang & canonical
 
@@ -219,6 +316,22 @@ import { HreflangLinks } from "@ingram-tech/nk-seo/components";
 />
 ```
 
+Sites that prefix **every** locale — where `/about` redirects to `/en/about`
+and no bare path exists — pass `prefixDefaultLocale`, which prefixes the default
+locale too and points `x-default` at that prefixed URL. Without it the bare path
+is emitted for both `en` and `x-default`, annotating URLs that redirect (Google
+wants every hreflang target to answer 200 directly).
+
+```tsx
+<HreflangLinks
+	baseUrl="https://example.com"
+	locales={["en", "fr", "nl"]}
+	strategy="prefix"
+	defaultLocale="en"
+	prefixDefaultLocale
+/>
+```
+
 Pass `pathname` explicitly if you don't use the `x-pathname` header. When
 neither is available the component **throws** instead of guessing — a silent
 fallback would canonicalize every page to the homepage, the kind of site-wide
@@ -228,11 +341,42 @@ Two rules of the road:
 
 - **One canonical per page.** If your pages already set `alternates.canonical`
   (e.g. via `createMetadata`), render `<HreflangLinks canonical={false} />`.
-- **The canonical must self-reference.** A localized variant that
-  canonicalizes to a different URL makes Google discard the whole hreflang
-  cluster. The prefix strategy auto-detects the current locale from the
-  (possibly `/fr/…`-prefixed) pathname; the query strategy can't see the query
-  string server-side, so pass `currentLocale` from your locale negotiation.
+- **The canonical must self-reference, and it follows the ADDRESS, not the
+  rendered language.** A localized variant that canonicalizes to a different URL
+  makes Google discard the whole hreflang cluster. Under `"query"` the bare path
+  is the negotiating `x-default` and belongs to no locale, so `/pricing`
+  canonicalizes to `/pricing` even while negotiation renders it in French — pass
+  `currentLocale` only when the URL itself names a locale. The prefix strategy
+  auto-detects it from the (possibly `/fr/…`-prefixed) pathname; the query
+  strategy can't see the query string server-side, so
+  [`hreflangConfigFor(routing)`](../nk-i18n/README.md) from
+  `@ingram-tech/nk-i18n/next` is the wiring that gets this right for you.
 - Building metadata instead of rendering links? The pure `hreflangAlternates`
-  (package root) returns the same `{ canonical, links }` for use in
-  `generateMetadata`.
+  (package root) returns the same links for use in `generateMetadata`:
+  `{ canonical, links, languages }`, where `languages` is already keyed by
+  hreflang for `Metadata.alternates.languages` (or `createMetadata`'s
+  per-page `alternates`).
+
+## Verifying the cluster (`/verify`)
+
+hreflang is a set of promises about **other** URLs, and nothing local can tell
+you whether they hold. A site can emit a flawless cluster while its middleware
+redirects every URL in it away, or while each variant quietly canonicalizes to
+the default language. Both delete the non-default languages from search, neither
+raises an error, and Search Console reports them as ordinary redirects and
+duplicates months later. Fetch them:
+
+```ts
+import { assertHreflangCluster } from "@ingram-tech/nk-seo/verify";
+import { routing } from "@/lib/i18n/routing";
+
+await assertHreflangCluster(routing, ["/", "/pricing", "/docs/getting-started"]);
+```
+
+It fails on an advertised URL that redirects or isn't 200, a variant that
+canonicalizes elsewhere, a missing or duplicated canonical, a non-reciprocal
+cluster, and an `<html lang>` contradicting the `hreflang` it's advertised under.
+`verifyHreflangCluster` returns the problems instead of throwing.
+
+Run it against a real deployment — it is the only check that sees what a crawler
+sees. A `LocaleRouting` from `@ingram-tech/nk-i18n` is a valid config for it.

package/dist/alternates.d.ts

@@ -12,19 +12,36 @@ export interface HreflangConfig {
      * How locale is encoded in the alternate URLs:
      *  - `"query"` (default): `${baseUrl}${path}?${param}=${locale}` for every locale.
      *  - `"prefix"`: the default locale stays at the bare path; others get
-     *    `/${locale}${path}` (matches a localized-rewrite setup).
+     *    `/${locale}${path}` (matches a localized-rewrite setup). Set
+     *    {@link HreflangConfig.prefixDefaultLocale} for sites that prefix every
+     *    locale instead.
      */
     strategy?: "query" | "prefix";
     /** Query-param name for the `"query"` strategy. Default `"hl"`. */
     param?: string;
-    /** Default (unprefixed) locale for the `"prefix"` strategy. */
+    /** Default locale. Required for `"prefix"`; it is what `x-default` resolves to. */
     defaultLocale?: string;
     /**
-     * Locale of the page being rendered. Determines the self-referencing
-     * canonical: a localized variant that canonicalizes to another URL makes
-     * Google discard the entire hreflang cluster. For the `"prefix"` strategy it
-     * is auto-detected from the pathname; for `"query"` the server can't see the
-     * query string, so pass it (e.g. from your locale negotiation).
+     * `"prefix"` only: prefix the default locale too (`/en/about`, never
+     * `/about`), and point `x-default` at that prefixed URL. For sites whose
+     * locale negotiation redirects every bare path — emitting the bare path as
+     * an alternate would annotate a URL that 3xx-redirects, which is the bug the
+     * mandatory `defaultLocale` exists to prevent.
+     */
+    prefixDefaultLocale?: boolean;
+    /**
+     * The locale **the URL names**, which is not always the locale that rendered.
+     * It determines the self-referencing canonical, and a canonical is a claim
+     * about an address: under `"query"`, `/pricing` canonicalizes to `/pricing`
+     * even while content negotiation renders it in French for a French visitor,
+     * because `/pricing` is the negotiating entry point and belongs to no locale.
+     * Passing the negotiated locale here instead makes the bare path claim to be
+     * the French URL, and the real French URL then looks like a duplicate.
+     *
+     * Leave it unset on a negotiating bare path. Under `"prefix"` it is detected
+     * from the pathname; under `"query"` the server cannot see the query string,
+     * so pass it — `hreflangConfigFor(routing)` from
+     * "@ingram-tech/nk-i18n/next" fills it in correctly.
      */
     currentLocale?: string;
     /** Optional locale → hreflang tag map, e.g. `{ en: "en-BE", fr: "fr-BE" }`. */
@@ -38,8 +55,14 @@ export interface HreflangLink {
 export interface HreflangAlternates {
     /** Self-referencing canonical URL of `pathname`. */
     canonical: string;
-    /** One link per locale, plus the trailing `x-default` (→ canonical). */
+    /** One link per locale, plus the trailing `x-default`. */
     links: HreflangLink[];
+    /**
+     * The same links keyed by `hrefLang` (`x-default` included) — the shape Next
+     * wants for `Metadata.alternates.languages` / `createMetadata`'s
+     * `alternates`.
+     */
+    languages: Record<string, string>;
 }
 /**
  * Computes the self-referencing canonical plus per-locale hreflang alternate

package/dist/alternates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alternates.d.ts","sourceRoot":"","sources":["../src/alternates.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC9B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC5B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,kBAAkB;IAClC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,KAAK,EAAE,YAAY,EAAE,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,GACd,kBAAkB,CA2DpB"}
+{"version":3,"file":"alternates.d.ts","sourceRoot":"","sources":["../src/alternates.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IAC9B,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,YAAY;IAC5B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,kBAAkB;IAClC,oDAAoD;IACpD,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CACjC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,GACd,kBAAkB,CAuFpB"}

package/dist/alternates.js

@@ -4,10 +4,12 @@ import { absoluteUrl } from "./url.js";
  * URLs (and an `x-default`) for `pathname`.
  */
 export function hreflangAlternates(config, pathname) {
-    const { strategy = "query", param = "hl", defaultLocale, hrefLangTags } = config;
+    const { strategy = "query", param = "hl", defaultLocale, prefixDefaultLocale, hrefLangTags, } = config;
     if (strategy === "prefix" && !defaultLocale) {
-        // Without it every locale gets a prefix while canonical/x-default point
-        // at a bare path that is no locale's URL — a silent SEO bug.
+        // Without it canonical/x-default point at a bare path that is no
+        // locale's URL — a silent SEO bug. (With `prefixDefaultLocale` no bare
+        // path is emitted at all, but x-default still has to resolve to *some*
+        // locale, so the requirement stands.)
         throw new Error("hreflangAlternates: `defaultLocale` is required for the prefix strategy.");
     }
     // Prefix strategy: accept both the bare and the locale-prefixed form of the
@@ -26,34 +28,49 @@ export function hreflangAlternates(config, pathname) {
         }
         currentLocale ??= defaultLocale;
     }
-    /** The default-locale URL — the bare path; also serves as x-default. */
-    const defaultUrl = absoluteUrl(basePath, config.baseUrl);
+    /** The bare (locale-free) URL of the path. */
+    const bareUrl = absoluteUrl(basePath, config.baseUrl);
+    const prefixedUrl = (locale) => absoluteUrl(`/${locale}${basePath === "/" ? "" : basePath}`, config.baseUrl);
     const hrefFor = (locale) => {
         if (strategy === "prefix") {
-            if (locale === defaultLocale)
-                return defaultUrl;
-            const clean = basePath === "/" ? "" : basePath;
-            return absoluteUrl(`/${locale}${clean}`, config.baseUrl);
+            if (locale === defaultLocale && !prefixDefaultLocale)
+                return bareUrl;
+            return prefixedUrl(locale);
         }
-        return `${defaultUrl}${defaultUrl.includes("?") ? "&" : "?"}${param}=${locale}`;
+        return `${bareUrl}${bareUrl.includes("?") ? "&" : "?"}${param}=${locale}`;
     };
+    /** x-default: the default locale's own URL, prefixed or not. */
+    const defaultUrl = strategy === "prefix" && prefixDefaultLocale && defaultLocale
+        ? prefixedUrl(defaultLocale)
+        : bareUrl;
     // Self-referencing canonical: the current variant's own URL. Canonicalizing
     // a localized variant to the bare path makes Google treat the variants as
     // duplicates and ignore the hreflang annotations entirely.
+    //
+    // Whether the default locale has a URL of its own is strategy-dependent, and
+    // conflating the two is a silent way to delete the default locale from the
+    // cluster. Under `"prefix"` it shares the bare path (unless every locale is
+    // prefixed), so its canonical IS the bare path. Under `"query"` every locale
+    // gets its own `?param=` address and the bare path belongs to none of them:
+    // it is the negotiating entry point that `x-default` names. So `?hl=en` must
+    // canonicalize to `?hl=en`, never to the bare path.
+    const defaultLocaleOwnsBarePath = strategy === "prefix" && !prefixDefaultLocale;
     const canonical = currentLocale &&
-        currentLocale !== defaultLocale &&
-        config.locales.includes(currentLocale)
+        config.locales.includes(currentLocale) &&
+        !(defaultLocaleOwnsBarePath && currentLocale === defaultLocale)
         ? hrefFor(currentLocale)
         : defaultUrl;
+    const links = [
+        ...config.locales.map((locale) => ({
+            hrefLang: hrefLangTags?.[locale] ?? locale,
+            href: hrefFor(locale),
+        })),
+        { hrefLang: "x-default", href: defaultUrl },
+    ];
     return {
         canonical,
-        links: [
-            ...config.locales.map((locale) => ({
-                hrefLang: hrefLangTags?.[locale] ?? locale,
-                href: hrefFor(locale),
-            })),
-            { hrefLang: "x-default", href: defaultUrl },
-        ],
+        links,
+        languages: Object.fromEntries(links.map((link) => [link.hrefLang, link.href])),
     };
 }
 //# sourceMappingURL=alternates.js.map

package/dist/alternates.js.map

@@ -1 +1 @@
-{"version":3,"file":"alternates.js","sourceRoot":"","sources":["../src/alternates.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAgDvC;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CACjC,MAAsB,EACtB,QAAgB;IAEhB,MAAM,EAAE,QAAQ,GAAG,OAAO,EAAE,KAAK,GAAG,IAAI,EAAE,aAAa,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;IACjF,IAAI,QAAQ,KAAK,QAAQ,IAAI,CAAC,aAAa,EAAE,CAAC;QAC7C,wEAAwE;QACxE,6DAA6D;QAC7D,MAAM,IAAI,KAAK,CACd,0EAA0E,CAC1E,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,yEAAyE;IACzE,qEAAqE;IACrE,0BAA0B;IAC1B,IAAI,QAAQ,GAAG,QAAQ,CAAC;IACxB,IAAI,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;IACzC,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC3B,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACrC,IAAI,QAAQ,KAAK,IAAI,MAAM,EAAE,IAAI,QAAQ,CAAC,UAAU,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrE,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC;gBACpD,aAAa,KAAK,MAAM,CAAC;gBACzB,MAAM;YACP,CAAC;QACF,CAAC;QACD,aAAa,KAAK,aAAa,CAAC;IACjC,CAAC;IAED,wEAAwE;IACxE,MAAM,UAAU,GAAG,WAAW,CAAC,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;IAEzD,MAAM,OAAO,GAAG,CAAC,MAAc,EAAU,EAAE;QAC1C,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC3B,IAAI,MAAM,KAAK,aAAa;gBAAE,OAAO,UAAU,CAAC;YAChD,MAAM,KAAK,GAAG,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;YAC/C,OAAO,WAAW,CAAC,IAAI,MAAM,GAAG,KAAK,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QAC1D,CAAC;QACD,OAAO,GAAG,UAAU,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,GAAG,KAAK,IAAI,MAAM,EAAE,CAAC;IACjF,CAAC,CAAC;IAEF,4EAA4E;IAC5E,0EAA0E;IAC1E,2DAA2D;IAC3D,MAAM,SAAS,GACd,aAAa;QACb,aAAa,KAAK,aAAa;QAC/B,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;QACrC,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC;QACxB,CAAC,CAAC,UAAU,CAAC;IAEf,OAAO;QACN,SAAS;QACT,KAAK,EAAE;YACN,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;gBAClC,QAAQ,EAAE,YAAY,EAAE,CAAC,MAAM,CAAC,IAAI,MAAM;gBAC1C,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC;aACrB,CAAC,CAAC;YACH,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE;SAC3C;KACD,CAAC;AACH,CAAC"}
+{"version":3,"file":"alternates.js","sourceRoot":"","sources":["../src/alternates.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { type AggregateOfferNode, type AggregateRatingInput, type AggregateRatingNode, article, type ArticleAuthor, type ArticleAuthorNode, type ArticleInput, type ArticleNode, breadcrumbList, type BreadcrumbItem, type BreadcrumbListNode, type BreadcrumbPath, createSeo, event, type EventInput, type EventLocationInput, type EventNode, faqPage, type FaqItem, type FaqPageNode, type GeoCoordinatesNode, type GeoInput, type ImageObjectNode, type JsonLdNode, type ListItemNode, localBusiness, type LocalBusinessInput, type LocalBusinessNode, type OfferInput, type OfferNode, organization, type OrganizationInput, type OrganizationNode, person, type PersonInput, type PersonNode, type PlaceNode, type PostalAddressInput, type PostalAddressNode, type QuestionNode, type Seo, type SeoConfig, softwareApplication, type SoftwareApplicationInput, type SoftwareApplicationNode, type VirtualLocationNode, website, type WebsiteInput, type WebsiteNode, type WithContext, } from "./schema.js";
-export { createMetadata, type MetadataSiteConfig, type PageMetadata, type PageMetadataInput, type RootMetadataInput, } from "./metadata.js";
+export { type AggregateOfferNode, type AggregateRatingInput, type AggregateRatingNode, article, type ArticleAuthor, type ArticleAuthorNode, type ArticleInput, type ArticleNode, type ArticleType, breadcrumbList, type BreadcrumbItem, type BreadcrumbListNode, type BreadcrumbPath, createSeo, type DataDownloadInput, type DataDownloadNode, dataset, type DatasetInput, type DatasetNode, definedTerm, type DefinedTermInput, type DefinedTermNode, definedTermSet, type DefinedTermSetInput, type DefinedTermSetNode, event, type EventInput, type EventLocationInput, type EventNode, faqPage, type FaqItem, type FaqPageNode, type GeoCoordinatesNode, type GeoInput, type ImageObjectNode, type JsonLdNode, type ListItemNode, localBusiness, type LocalBusinessInput, type LocalBusinessNode, type OfferInput, type OfferNode, organization, type OrganizationInput, type OrganizationNode, person, type PersonInput, type PersonNode, type PlaceNode, type PostalAddressInput, type PostalAddressNode, type QuestionNode, type Seo, type SeoConfig, softwareApplication, type SoftwareApplicationInput, type SoftwareApplicationNode, type VirtualLocationNode, website, type WebsiteInput, type WebsiteNode, type WithContext, type WithExtra, } from "./schema.js";
+export { createMetadata, type MetadataSiteConfig, ogImageMetadata, type OgImageMetadataInput, type PageMetadata, type PageMetadataInput, type RootMetadataInput, } from "./metadata.js";
 export { createRobots, createSitemap, type RobotsConfig, type SitemapConfig, type SitemapLanguages, type SitemapRoute, } from "./routes.js";
 export { hreflangAlternates, type HreflangAlternates, type HreflangConfig, type HreflangLink, } from "./alternates.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACN,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,OAAO,EACP,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,SAAS,EACT,KAAK,EACL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,OAAO,EACP,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,MAAM,EACN,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,GAAG,EACR,KAAK,SAAS,EACd,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,GAChB,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,YAAY,EACZ,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,GACjB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACN,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,OAAO,EACP,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,SAAS,EACT,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,cAAc,EACd,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,EACL,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,OAAO,EACP,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,MAAM,EACN,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,GAAG,EACR,KAAK,SAAS,EACd,mBAAmB,EACnB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,OAAO,EACP,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,SAAS,GACd,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,cAAc,EACd,KAAK,kBAAkB,EACvB,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,YAAY,EACZ,aAAa,EACb,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,YAAY,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,kBAAkB,EAClB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,YAAY,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -2,8 +2,8 @@
 // route handlers / sitemap.ts can import these without pulling in the renderer.
 // The <JsonLd> and <HreflangLinks> components live at
 // "@ingram-tech/nk-seo/components".
-export { article, breadcrumbList, createSeo, event, faqPage, localBusiness, organization, person, softwareApplication, website, } from "./schema.js";
-export { createMetadata, } from "./metadata.js";
+export { article, breadcrumbList, createSeo, dataset, definedTerm, definedTermSet, event, faqPage, localBusiness, organization, person, softwareApplication, website, } from "./schema.js";
+export { createMetadata, ogImageMetadata, } from "./metadata.js";
 export { createRobots, createSitemap, } from "./routes.js";
 export { hreflangAlternates, } from "./alternates.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gFAAgF;AAChF,sDAAsD;AACtD,oCAAoC;AACpC,OAAO,EAIN,OAAO,EAKP,cAAc,EAId,SAAS,EACT,KAAK,EAIL,OAAO,EAQP,aAAa,EAKb,YAAY,EAGZ,MAAM,EASN,mBAAmB,EAInB,OAAO,GAIP,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,cAAc,GAKd,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,YAAY,EACZ,aAAa,GAKb,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,kBAAkB,GAIlB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,gFAAgF;AAChF,sDAAsD;AACtD,oCAAoC;AACpC,OAAO,EAIN,OAAO,EAMP,cAAc,EAId,SAAS,EAGT,OAAO,EAGP,WAAW,EAGX,cAAc,EAGd,KAAK,EAIL,OAAO,EAQP,aAAa,EAKb,YAAY,EAGZ,MAAM,EASN,mBAAmB,EAInB,OAAO,GAKP,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,cAAc,EAEd,eAAe,GAKf,MAAM,eAAe,CAAC;AACvB,OAAO,EACN,YAAY,EACZ,aAAa,GAKb,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,kBAAkB,GAIlB,MAAM,iBAAiB,CAAC"}

package/dist/metadata.d.ts

@@ -16,7 +16,10 @@ export interface MetadataSiteConfig {
     defaultImage?: string;
     defaultImageWidth?: number;
     defaultImageHeight?: number;
-    /** OpenGraph locale, e.g. "en_US". */
+    /**
+     * Default OpenGraph locale, e.g. "en_US". On a multilingual site set the
+     * per-page `locale` instead (or as well, as the fallback).
+     */
     locale?: string;
     /** Twitter `@handle` for `site`. */
     twitterSite?: string;
@@ -34,6 +37,18 @@ export interface PageMetadataInput {
     type?: "website" | "article";
     keywords?: Metadata["keywords"];
     noIndex?: boolean;
+    /**
+     * OpenGraph locale for this page, e.g. "fr_BE". Overrides `site.locale` —
+     * on a multilingual site `og:locale` has to vary per page.
+     */
+    locale?: string;
+    /**
+     * Merged into the generated `alternates` (wins on conflict). The reason it
+     * exists: `alternates.languages` is per-page on a localized site, and
+     * spreading the result to bolt it on drops the rest of the object.
+     * `hreflangAlternates()` returns a ready-made `languages` map.
+     */
+    alternates?: Partial<NonNullable<Metadata["alternates"]>>;
     /** Merged into the generated `openGraph` (wins on conflict). */
     openGraph?: Partial<NonNullable<Metadata["openGraph"]>>;
     /** Merged into the generated `twitter` (wins on conflict). */
@@ -74,4 +89,43 @@ export declare function createMetadata(site: MetadataSiteConfig): {
     root: (input?: RootMetadataInput) => Metadata;
 };
 export type PageMetadata = ReturnType<typeof createMetadata>;
+/** Inputs for {@link ogImageMetadata}. */
+export interface OgImageMetadataInput {
+    /** Absolute site origin, e.g. "https://acme.example". */
+    baseUrl: string;
+    /**
+     * Path of the image route — the route the `opengraph-image.tsx` file
+     * convention serves, e.g. "/opengraph-image" or "/en/opengraph-image" when
+     * the file sits under `app/[locale]/`.
+     */
+    path: string;
+    alt: string;
+    /** Defaults to the 1200×630 the `/og` template renders. */
+    width?: number;
+    height?: number;
+}
+/**
+ * Builds the `openGraph.images` entry for a card served by Next's
+ * `opengraph-image` file convention.
+ *
+ * Next attaches a file-convention image only to the segment that declares it,
+ * and a page's own `openGraph` object *replaces* the inherited one rather than
+ * merging into it — so any page returning `openGraph` from `generateMetadata`
+ * silently loses the card. Build the list once and spread it into every page.
+ *
+ * `createMetadata`'s `defaultImage` / per-page `image` already do this; reach
+ * for the standalone helper when you assemble `Metadata` by hand.
+ *
+ * @example
+ * const images = ogImageMetadata({
+ *   baseUrl, path: `/${locale}/opengraph-image`, alt: "Acme",
+ * });
+ * return { title, openGraph: { title, url, images } };
+ */
+export declare function ogImageMetadata(input: OgImageMetadataInput): {
+    url: string;
+    width: number;
+    height: number;
+    alt: string;
+}[];
 //# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAGrC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACxD,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CACpD;AAED,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB;YAGzB,iBAAiB,GAAG,QAAQ;mBA+CR,iBAAiB,KAAQ,QAAQ;EAalF;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC"}
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAGrC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC7B,QAAQ,CAAC,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAChC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAC1D,gEAAgE;IAChE,SAAS,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACxD,8DAA8D;IAC9D,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;CACpD;AAED,mEAAmE;AACnE,MAAM,WAAW,iBAAiB;IACjC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,QAAQ,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,kBAAkB;YAGzB,iBAAiB,GAAG,QAAQ;mBAgDR,iBAAiB,KAAQ,QAAQ;EAalF;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,0CAA0C;AAC1C,MAAM,WAAW,oBAAoB;IACpC,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB;;;;;IAS1D"}

package/dist/metadata.js

@@ -27,12 +27,13 @@ export function createMetadata(site) {
         const imagePath = input.image ?? site.defaultImage;
         const imageUrl = imagePath ? absolute(imagePath) : undefined;
         const url = absolute(input.path);
+        const locale = input.locale ?? site.locale;
         return {
             metadataBase: new URL(site.baseUrl),
             title: input.title,
             description: input.description,
             ...(input.keywords ? { keywords: input.keywords } : {}),
-            alternates: { canonical: url },
+            alternates: { canonical: url, ...input.alternates },
             // noindex but follow: keep link equity flowing through the page. Use a
             // full robots override in the page's own metadata for nofollow too.
             ...(input.noIndex ? { robots: { index: false, follow: true } } : {}),
@@ -42,7 +43,7 @@ export function createMetadata(site) {
                 type: input.type ?? "website",
                 url,
                 siteName: site.siteName,
-                ...(site.locale ? { locale: site.locale } : {}),
+                ...(locale ? { locale } : {}),
                 ...(imageUrl
                     ? {
                         images: [
@@ -81,4 +82,32 @@ export function createMetadata(site) {
     };
     return pageMetadata;
 }
+/**
+ * Builds the `openGraph.images` entry for a card served by Next's
+ * `opengraph-image` file convention.
+ *
+ * Next attaches a file-convention image only to the segment that declares it,
+ * and a page's own `openGraph` object *replaces* the inherited one rather than
+ * merging into it — so any page returning `openGraph` from `generateMetadata`
+ * silently loses the card. Build the list once and spread it into every page.
+ *
+ * `createMetadata`'s `defaultImage` / per-page `image` already do this; reach
+ * for the standalone helper when you assemble `Metadata` by hand.
+ *
+ * @example
+ * const images = ogImageMetadata({
+ *   baseUrl, path: `/${locale}/opengraph-image`, alt: "Acme",
+ * });
+ * return { title, openGraph: { title, url, images } };
+ */
+export function ogImageMetadata(input) {
+    return [
+        {
+            url: absoluteUrl(input.path, input.baseUrl),
+            width: input.width ?? 1200,
+            height: input.height ?? 630,
+            alt: input.alt,
+        },
+    ];
+}
 //# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

@@ -1 +1 @@
-{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"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"}