@sonordev/site-kit 5.6.0 → 5.8.0

package/dist/og/index.js

@@ -1,25 +1,43 @@
 'use strict';
 
-var chunk6CJP7BFM_js = require('../chunk-6CJP7BFM.js');
+var chunkOEW2LFOV_js = require('../chunk-OEW2LFOV.js');
+var chunkCUNZAD46_js = require('../chunk-CUNZAD46.js');
+require('../chunk-R7GHP3FY.js');
 require('../chunk-SNAQBZPT.js');
 
 
 
-Object.defineProperty(exports, "OG_HEIGHT", {
+Object.defineProperty(exports, "PARAM_CARD_DIR", {
   enumerable: true,
-  get: function () { return chunk6CJP7BFM_js.OG_HEIGHT; }
+  get: function () { return chunkOEW2LFOV_js.PARAM_CARD_DIR; }
 });
-Object.defineProperty(exports, "OG_WIDTH", {
+Object.defineProperty(exports, "buildOgHtml", {
   enumerable: true,
-  get: function () { return chunk6CJP7BFM_js.OG_WIDTH; }
+  get: function () { return chunkOEW2LFOV_js.buildOgHtml; }
 });
-Object.defineProperty(exports, "buildOgHtml", {
+Object.defineProperty(exports, "codeCardImage", {
+  enumerable: true,
+  get: function () { return chunkOEW2LFOV_js.codeCardImage; }
+});
+Object.defineProperty(exports, "paramCardImage", {
+  enumerable: true,
+  get: function () { return chunkOEW2LFOV_js.paramCardImage; }
+});
+Object.defineProperty(exports, "paramCardUrl", {
+  enumerable: true,
+  get: function () { return chunkOEW2LFOV_js.paramCardUrl; }
+});
+Object.defineProperty(exports, "OG_HEIGHT", {
+  enumerable: true,
+  get: function () { return chunkCUNZAD46_js.OG_HEIGHT; }
+});
+Object.defineProperty(exports, "OG_WIDTH", {
   enumerable: true,
-  get: function () { return chunk6CJP7BFM_js.buildOgHtml; }
+  get: function () { return chunkCUNZAD46_js.OG_WIDTH; }
 });
 Object.defineProperty(exports, "defineOgCard", {
   enumerable: true,
-  get: function () { return chunk6CJP7BFM_js.defineOgCard; }
+  get: function () { return chunkCUNZAD46_js.defineOgCard; }
 });
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/og/index.mjs

@@ -1,4 +1,6 @@
-export { OG_HEIGHT, OG_WIDTH, buildOgHtml, defineOgCard } from '../chunk-UJ6CHZAI.mjs';
+export { PARAM_CARD_DIR, buildOgHtml, codeCardImage, paramCardImage, paramCardUrl } from '../chunk-XZO5I4RS.mjs';
+export { OG_HEIGHT, OG_WIDTH, defineOgCard } from '../chunk-YU7QZ3PP.mjs';
+import '../chunk-4LYW6PMU.mjs';
 import '../chunk-BEXTDHO4.mjs';
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/og/pages.d.ts

@@ -37,6 +37,18 @@ export interface OgPageRoute {
  * src/og/README.md.)
  */
 export declare const DYNAMIC = "*";
+/**
+ * Trailing brand suffix on a managed title (` | Acme`, ` - Acme`, ` — Acme`).
+ * Managed titles carry the brand because a SERP entry needs it; a card does
+ * not — the logo, the photo and the bar are already saying whose it is, and
+ * every character spent on the brand is one not spent on the page.
+ *
+ * Also drops the two broken suffixes managed titles turn up with, both found
+ * on 2026-09-15 and each worked around by hand in a site's `cards`: a
+ * dangling separator with no brand after it (reinhart's "About Us |", Green
+ * Bay's), and the domain after a comma ("Privacy Policy, abbeyglenapts.com").
+ */
+export declare function stripBrandSuffix(title: string, brand?: string): string;
 /**
  * `/services/walk-in-closets` -> `Walk In Closets`. The no-managed-data path.
  *
@@ -84,6 +96,95 @@ export declare function slugForPath(path: string): string;
  * hand-written card with nothing said about it. The caller reports these.
  */
 export declare function unmatchedCardKeys(cards: Record<string, unknown> | undefined, paths: string[]): string[];
+/**
+ * Does a concrete URL fall under a dynamic route pattern? One `*` matches
+ * exactly one segment: `/properties/tall-pines/about` is under
+ * `/properties/*` + `/about`, and `/floor-plans/1-bedroom` under
+ * `/floor-plans/*`. A key that is itself a pattern matches nothing.
+ */
+export declare function matchesRoutePattern(path: string, pattern: string): boolean;
+/**
+ * The `cards` keys that name one page under a dynamic route: a card per
+ * floor plan, per community, per sub-page of a community. Keyed by the URL
+ * itself (`/floor-plans/1-bedroom`), which any site can build from the same
+ * data its `generateStaticParams` reads.
+ *
+ * A static file in a dynamic segment covers every param of the route, so
+ * these can't be `opengraph-image` files. `sonor-setup og` renders each one to
+ * `public/_og/` (see paramCardUrl), and the page declares it with
+ * `paramCardImage`. The MDG property sites needed a card per floor plan and
+ * per community and rendered them with their own script until this existed.
+ *
+ * Returns each key with the pattern it falls under. Keys that are a real
+ * static route or a pattern are left to the route cards.
+ */
+export declare function paramCardKeys(cards: Record<string, unknown> | undefined, paths: string[]): Array<{
+    path: string;
+    pattern: string;
+}>;
+/**
+ * Public directory (under `public/`) that `sonor-setup og` owns for per-URL
+ * cards. Generated; the command clears it on every run, so keep nothing else
+ * in it.
+ */
+export declare const PARAM_CARD_DIR = "_og";
+/**
+ * Where the per-URL card for a page is served: `/floor-plans/1-bedroom` ->
+ * `/_og/floor-plans/1-bedroom.jpg`. Single source of truth for the file the
+ * CLI writes and the URL `paramCardImage` declares.
+ *
+ * It ends in `.jpg` on purpose. Next serves a code-based `opengraph-image`
+ * route without an extension, and `trailingSlash: true` answers that URL with
+ * a 308 before the card, which some preview bots don't follow. A static file
+ * with an extension is never redirected.
+ */
+export declare function paramCardUrl(path: string): string;
+/** An `openGraph.images` entry. */
+export interface OgImageDescriptor {
+    url: string;
+    width: number;
+    height: number;
+    type: string;
+    alt?: string;
+}
+/**
+ * The page's per-URL card, for its metadata:
+ *
+ * ```ts
+ * const card = paramCardImage(`/floor-plans/${slug}`, { config: ogConfig })
+ * return {
+ *   openGraph: { ...(card && { images: [card] }) },
+ *   twitter: { card: 'summary_large_image', ...(card && { images: [card.url] }) },
+ * }
+ * ```
+ *
+ * Pass `config` (the site's og.config) and it answers undefined for a page
+ * with no `cards` entry, so the page keeps its segment's static card. Without
+ * `config` it always answers, so only call it for URLs you gave a card.
+ */
+export declare function paramCardImage(path: string, options?: {
+    config?: Pick<OgCardConfig, 'cards'>;
+    alt?: string;
+}): OgImageDescriptor | undefined;
+/**
+ * A code-based card (`opengraph-image.tsx`) declared at the URL the site
+ * actually serves it from.
+ *
+ * Next wires such a card in as `<path>/opengraph-image`, with no extension.
+ * With `trailingSlash: true` that URL 308-redirects to the slashed one, so
+ * every share preview starts with a redirect, and bots that don't follow one
+ * show no card (the MDG property sites, 2026-09-15). Declaring the slashed URL
+ * gets a 200 first time. Declared images beat the file convention, so this
+ * replaces Next's own entry rather than adding a second.
+ *
+ * `trailingSlash` defaults to the site's next.config. Without it, this is the
+ * URL Next would have used anyway.
+ */
+export declare function codeCardImage(path: string, options?: {
+    trailingSlash?: boolean;
+    alt?: string;
+    contentType?: string;
+}): OgImageDescriptor;
 /**
  * Build a page's card config by layering its copy over the site's card.
  *

package/dist/og/pages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../src/og/pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAE5C,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,MAAM,CAAA;AAsB1B;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOlD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUlF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,SAAM,GAAG,MAAM,GAAG,SAAS,CA2BrF;AAsBD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAShD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,KAAK,EAAE,MAAM,EAAE,GACd,MAAM,EAAE,CAIV;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,WAAW,EAClB,KAAK,CAAC,EAAE,MAAM,GACb,YAAY,CAsCd"}
+{"version":3,"file":"pages.d.ts","sourceRoot":"","sources":["../../src/og/pages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAK5C,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,OAAO,MAAM,CAAA;AAqB1B;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAYtE;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOlD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYlF;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,SAAM,GAAG,MAAM,GAAG,SAAS,CA2BrF;AAsBD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAShD;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,KAAK,EAAE,MAAM,EAAE,GACd,MAAM,EAAE,CAOV;AAQD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAK1E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,KAAK,EAAE,MAAM,EAAE,GACd,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAW1C;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAQ,CAAA;AAEnC;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED,mCAAmC;AACnC,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAO,GACnE,iBAAiB,GAAG,SAAS,CAa/B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5E,iBAAiB,CAUnB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,WAAW,EAClB,KAAK,CAAC,EAAE,MAAM,GACb,YAAY,CAuCd"}

package/dist/og/route-copy.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @sonordev/site-kit/og — what Sonor says about each route, for its card.
+ *
+ * SINGLE SOURCE OF TRUTH for the per-route Sonor lookup, shared by
+ * `sonor-setup og` (card copy, and which pages set managed_og_image) and the
+ * doctor's online `og.card` check (managed_og_image only). One lookup per
+ * route either way; they must not drift on which fields they read.
+ *
+ * Node-only (it's CLI code): never import from browser or client code.
+ */
+import type { OgPageRoute } from './pages';
+/** Concurrent Chrome renders and Sonor lookups. More than this thrashes. */
+export declare const RENDER_CONCURRENCY = 4;
+/** Run tasks with a small concurrency cap. */
+export declare function pooled<T, R>(items: T[], limit: number, fn: (item: T, i: number) => Promise<R>): Promise<R[]>;
+export type RouteCopy = OgPageRoute & {
+    /** seo_pages.managed_og_image, which overrides the route's own card. */
+    managedOgImage?: string;
+};
+/**
+ * Ask Sonor for each route's managed title and description, so a page card
+ * says what the page's own <title> says.
+ *
+ * Best effort by design: one lookup per route, capped concurrency, and any
+ * failure degrades that route to a path-derived title rather than failing the
+ * command. A site with no key still gets a full set of cards.
+ */
+export declare function resolveRouteCopy(paths: string[]): Promise<RouteCopy[]>;
+/**
+ * The site's static routes whose seo_pages row sets managed_og_image, or
+ * undefined when that can't be known (no key, no app directory).
+ */
+export declare function readManagedOgImages(cwd: string): Promise<string[] | undefined>;
+//# sourceMappingURL=route-copy.d.ts.map

package/dist/og/route-copy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-copy.d.ts","sourceRoot":"","sources":["../../src/og/route-copy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAG1C,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,IAAI,CAAA;AAEnC,8CAA8C;AAC9C,wBAAsB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAWlH;AAED,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG;IACpC,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB,CAAA;AAID;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAyB5E;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,CAOpF"}

package/dist/og/route-fit.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @sonordev/site-kit/og — title fitting for the runtime (Satori) card.
+ *
+ * The build-time card is fitted in the page: Chrome measures the rendered
+ * title and steps it down until it fits (template.ts). The runtime card is
+ * Satori, which has no DOM to measure, so its title sat at a fixed 84px,
+ * uppercase, with no fitting. Beside the 430px photo that holds about 11
+ * characters a line, so a real post title ran off the bottom of the card.
+ * watsonhac.com, reinhart and vsf-consulting-nextjs each worked around it by
+ * dropping the photo past a hand-picked length (40 or 50 characters).
+ *
+ * This does what the build-time fitter does, from an estimate instead of a
+ * measurement: the same size range (TITLE_MAX_PX down to TITLE_MIN_PX, in 2px
+ * steps), word-wrapped at an estimated glyph width against the real column
+ * width and the height the kicker, subtitle and bar leave. When the title
+ * can't fit beside the photo even at the floor, the photo goes and the title
+ * gets the full width.
+ *
+ * The estimate is deliberately wide (uppercase, bold-ish) so an unusual
+ * face errs toward a smaller title, never an overflowing one, and the title
+ * box clips at its height as the backstop.
+ *
+ * Pure: no DOM, no Node built-ins. Geometry constants are the card's own
+ * (route.tsx imports them), so the two can't drift.
+ */
+/** The runtime card's layout, in px. route.tsx renders exactly this. */
+export declare const ROUTE_CARD: {
+    readonly padX: 68;
+    readonly gap: 48;
+    readonly photoWidth: 430;
+    readonly photoHeight: 470;
+    readonly barHeight: 74;
+    /** Breathing room above and below the copy column. */
+    readonly padY: 44;
+    readonly kickerPx: 24;
+    readonly kickerGap: 18;
+    readonly subtitlePx: 30;
+    readonly subtitleGap: 20;
+    readonly subtitleLineHeight: 1.3;
+    readonly titleLineHeight: 1.02;
+};
+/** Estimated width of `text` set uppercase at `px`. */
+export declare function uppercaseWidth(text: string, px: number): number;
+/**
+ * Lines `text` wraps to in a column `width` px wide, greedy by word, the way
+ * the browser and Satori wrap. `\n` is a hard break. Returns Infinity when a
+ * single word is wider than the column: it can't wrap, so no line count fits.
+ */
+export declare function wrappedLines(text: string, width: number, measure: (s: string) => number): number;
+export interface RouteFitInput {
+    title: string;
+    kicker?: string;
+    subtitle?: string;
+    /** A photo was offered. */
+    photo: boolean;
+    /** The card has a bottom bar. */
+    bar: boolean;
+}
+export interface RouteFit {
+    /** Title size in px. */
+    titlePx: number;
+    /** Keep the photo. False when the title only fits at full width. */
+    photo: boolean;
+    /** Height the title box may use; route.tsx clips the title to it. */
+    titleMaxHeight: number;
+    /** The title fits at `titlePx` by the estimate (false only at the floor, full width). */
+    fits: boolean;
+}
+/**
+ * Size the title, and decide whether the photo stays.
+ *
+ * Beside the photo first, since the photo is the page's own image and worth
+ * keeping. If even the floor size doesn't fit there, drop the photo and fit
+ * the full width. If that fails too, the title sits at the floor and clips.
+ */
+export declare function fitRouteTitle(input: RouteFitInput): RouteFit;
+//# sourceMappingURL=route-fit.d.ts.map

package/dist/og/route-fit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-fit.d.ts","sourceRoot":"","sources":["../../src/og/route-fit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,wEAAwE;AACxE,eAAO,MAAM,UAAU;aACrB,IAAI,EAAE,EAAE;aACR,GAAG,EAAE,EAAE;aACP,UAAU,EAAE,GAAG;aACf,WAAW,EAAE,GAAG;aAChB,SAAS,EAAE,EAAE;IACb,sDAAsD;aACtD,IAAI,EAAE,EAAE;aACR,QAAQ,EAAE,EAAE;aACZ,SAAS,EAAE,EAAE;aACb,UAAU,EAAE,EAAE;aACd,WAAW,EAAE,EAAE;aACf,kBAAkB,EAAE,GAAG;aACvB,eAAe,EAAE,IAAI;CACb,CAAA;AAiBV,uDAAuD;AACvD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAM/D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAC7B,MAAM,CAsBR;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2BAA2B;IAC3B,KAAK,EAAE,OAAO,CAAA;IACd,iCAAiC;IACjC,GAAG,EAAE,OAAO,CAAA;CACb;AAED,MAAM,WAAW,QAAQ;IACvB,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,oEAAoE;IACpE,KAAK,EAAE,OAAO,CAAA;IACd,qEAAqE;IACrE,cAAc,EAAE,MAAM,CAAA;IACtB,yFAAyF;IACzF,IAAI,EAAE,OAAO,CAAA;CACd;AAiCD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ,CAe5D"}

package/dist/og/route.d.ts

@@ -1,43 +1,81 @@
 /**
  * @sonordev/site-kit/og/route — tier 2: per-entity runtime OG cards.
  *
- * `sonor-setup og` covers the site-wide static card. This factory covers the
- * cards that must vary per URL — one per blog post, per event, per product —
- * rendered on demand with next/og (Satori) in a route handler:
+ * `sonor-setup og` covers the build-time cards: the site card and one per
+ * route. This covers the cards that must vary per URL and can't wait for a
+ * rebuild — one per blog post, per event, per product — rendered on demand
+ * with next/og (Satori).
+ *
+ * TWO SHAPES, ONE CARD:
+ *
+ * `createOgImage` is the metadata file convention, and the one to reach for.
+ * Next calls an `opengraph-image.tsx` default export with `{ params }` and
+ * wires og:image and twitter:image for the page by itself, and `sonor-setup
+ * og` sees the file and leaves the folder alone:
  *
  * ```tsx
- * // app/blog/[slug]/opengraph-image/route.tsx
- * import { createOgImageRoute } from '@sonordev/site-kit/og/route'
+ * // app/blog/[slug]/opengraph-image.tsx
+ * import { createOgImage } from '@sonordev/site-kit/og/route'
  * import { getBlogPost } from '@sonordev/site-kit/blog/server'
  *
- * export const GET = createOgImageRoute(async (_req, { params }) => {
- *   const post = await getBlogPost((await params).slug)
- *   if (!post) return null
+ * export { size, contentType } from '@sonordev/site-kit/og/route'
+ * export const alt = 'From the Acme blog'
+ *
+ * export default createOgImage<{ slug: string }>(async ({ slug }) => {
+ *   const post = await getBlogPost(slug)
+ *   if (!post) return null                  // 404: a bad slug never renders a card
  *   return {
  *     theme: { bg: '#111110', text: '#faf6f0', accent: '#ad1d25' },
  *     kicker: 'From the blog',
  *     title: post.title,
- *     photoUrl: post.featured_image_url,   // the image from the page
+ *     photoUrl: post.featured_image,       // absolute URL (Satori requirement)
  *     bar: 'yourdomain.com',
  *   }
  * })
  * ```
  *
+ * The page then passes `images: false` to generateBlogPostMetadata: declared
+ * images beat the file convention.
+ *
+ * `createOgImageRoute` is a plain route handler, `GET(request, { params })`,
+ * for a card served at a URL of your choosing (`app/og/[slug]/route.tsx`).
+ * Next doesn't wire it into metadata; the page declares it.
+ *
+ * Sites needed an adapter between the two before `createOgImage` existed
+ * (watsonhac.com, reinhart, vsf-consulting-nextjs: a default export that
+ * built a dummy Request to call the GET handler).
+ *
  * SATORI CONSTRAINTS (why this is not the static template): flexbox-only CSS
  * subset, no external stylesheets, images must be absolute URLs or data URIs,
  * and fonts must be provided as ArrayBuffers via `fonts` — Satori cannot load
  * Google Fonts at runtime. Without fonts it falls back to Satori's default
  * face; brand-critical cards should pass font data (fetch the TTF once at
  * module init and reuse the promise).
+ *
+ * TITLE FITTING: Satori can't measure, so the title is sized from an estimate
+ * (og/route-fit.ts) over the same range the build-time card uses, and the
+ * photo is dropped when the title can't fit beside it. Long post titles no
+ * longer run off the card.
  */
 import React from 'react';
+export interface OgRouteTheme {
+    bg: string;
+    text: string;
+    accent: string;
+    muted?: string;
+    /** og.config.ts's surface color. Only used as a bar-text candidate. */
+    surface?: string;
+    /**
+     * Bottom-bar text, set on `accent`. Defaults to the first of `surface`,
+     * `bg`, `text` that reaches WCAG AA for large text (3:1) against the
+     * accent. It used to be `text`, which is unreadable wherever text and
+     * accent are both strong (navy on crimson).
+     */
+    barText?: string;
+}
 export interface OgRouteCard {
-    theme: {
-        bg: string;
-        text: string;
-        accent: string;
-        muted?: string;
-    };
+    /** og.config.ts's `theme` can be passed as is. */
+    theme: OgRouteTheme;
     kicker?: string;
     title: string;
     subtitle?: string;
@@ -52,6 +90,15 @@ export interface OgRouteFont {
     weight?: number;
     style?: 'normal' | 'italic';
 }
+export interface OgImageOptions {
+    fonts?: OgRouteFont[];
+}
+/** For `export { size, contentType } from '@sonordev/site-kit/og/route'` in an opengraph-image file. */
+export declare const size: {
+    width: number;
+    height: number;
+};
+export declare const contentType = "image/png";
 type Resolver<Ctx> = (req: Request, ctx: Ctx) => Promise<OgRouteCard | null> | OgRouteCard | null;
 /**
  * Satori-safe element tree — exported for tests and for sites that want to
@@ -59,13 +106,26 @@ type Resolver<Ctx> = (req: Request, ctx: Ctx) => Promise<OgRouteCard | null> | O
  */
 export declare function ogRouteElement(card: OgRouteCard): React.ReactElement;
 /**
- * Route handler factory. Returns 404 when the resolver returns null, so a
- * bad slug never renders a broken card.
+ * Metadata file-convention factory, for `export default` from an
+ * `opengraph-image.tsx` (or `twitter-image.tsx`). Next calls it with
+ * `{ params }` (a promise on Next 15+) and, with `generateImageMetadata`, an
+ * `id`. The resolver gets both already awaited. Return null for a 404.
+ */
+export declare function createOgImage<Params extends Record<string, string | string[]> = Record<string, string>>(resolve: (params: Params, ctx: {
+    id?: string;
+}) => Promise<OgRouteCard | null> | OgRouteCard | null, options?: OgImageOptions): (props: {
+    params: Params | Promise<Params>;
+    id?: string | Promise<string>;
+}) => Promise<Response>;
+/**
+ * Route handler factory, `export const GET` from a `route.tsx`. Returns 404
+ * when the resolver returns null, so a bad slug never renders a broken card.
+ *
+ * Next doesn't wire a route handler into metadata. For a card Next should
+ * attach to the page by itself, use `createOgImage` in `opengraph-image.tsx`.
  */
 export declare function createOgImageRoute<Ctx = {
     params: Promise<Record<string, string>>;
-}>(resolve: Resolver<Ctx>, options?: {
-    fonts?: OgRouteFont[];
-}): (req: Request, ctx: Ctx) => Promise<Response>;
+}>(resolve: Resolver<Ctx>, options?: OgImageOptions): (req: Request, ctx: Ctx) => Promise<Response>;
 export {};
 //# sourceMappingURL=route.d.ts.map

package/dist/og/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/og/route.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAA;AAEzB,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACnE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,WAAW,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAC5B;AAED,KAAK,QAAQ,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,WAAW,GAAG,IAAI,CAAA;AAEjG;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,KAAK,CAAC,YAAY,CAuDpE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,EAClF,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,EACtB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,WAAW,EAAE,CAAA;CAAO,SAER,OAAO,OAAO,GAAG,KAAG,OAAO,CAAC,QAAQ,CAAC,CAarE"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/og/route.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAA;AAKzB,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,KAAK,EAAE,YAAY,CAAA;IACnB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,WAAW,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAC5B;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,WAAW,EAAE,CAAA;CACtB;AAED,wGAAwG;AACxG,eAAO,MAAM,IAAI;;;CAAyC,CAAA;AAC1D,eAAO,MAAM,WAAW,cAAc,CAAA;AAEtC,KAAK,QAAQ,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,WAAW,GAAG,IAAI,CAAA;AAEjG;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,KAAK,CAAC,YAAY,CA8GpE;AAkBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACrG,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,WAAW,GAAG,IAAI,EACnG,OAAO,GAAE,cAAmB,WAEO;IACjC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAChC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CAC9B,KAAG,OAAO,CAAC,QAAQ,CAAC,CAKtB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAG;IAAE,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,EAClF,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,EACtB,OAAO,GAAE,cAAmB,SAEG,OAAO,OAAO,GAAG,KAAG,OAAO,CAAC,QAAQ,CAAC,CAGrE"}