npm - @moku-labs/web - Versions diffs - 1.4.1 → 1.5.1 - Mend

@moku-labs/web 1.4.1 → 1.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/dist/browser.d.mts CHANGED Viewed

@@ -1138,6 +1138,25 @@ type Api$1 = {
    * ```
    */
   render(route: ResolvedRoute, data: unknown): string;
+  /**
+   * Compose the SITE-LEVEL `<head>` Open Graph / Twitter block for a bare-path redirect or
+   * landing page that has no route identity (e.g. the apex-domain `/` redirect a
+   * `localeRedirects` build emits). Returns `""` UNLESS `defaultOgImage` is configured, so
+   * apps that opt out keep a bare redirect. Pulled synchronously by `build`.
+   *
+   * @param input - The landing URL (resolved to an absolute canonical) plus an optional locale.
+   * @param input.url - The page's URL or path (absolutized via `site.canonical`) → `og:url`.
+   * @param input.locale - Optional locale whose `og:locale` is emitted (e.g. the default locale).
+   * @returns The serialized inner HTML of the site-level head block, or `""` when disabled.
+   * @example
+   * ```ts
+   * api.siteHead({ url: "/en/", locale: "en" });
+   * ```
+   */
+  siteHead(input: {
+    url: string;
+    locale?: string;
+  }): string;
 };
 declare namespace types_d_exports$6 {
   export { COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentHooks, ComponentInstance, ExtractApi, PageData, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };

package/dist/browser.mjs CHANGED Viewed

@@ -2514,6 +2514,42 @@ function composeHead(input) {
 	}), ...head.elements ?? []]);
 }
 /**
+* Compose the SITE-LEVEL Open Graph / Twitter block for a bare-path redirect or landing
+* page that has no per-route head of its own. Returns `[]` UNLESS a `defaultOgImage` is
+* configured — so apps that opt out keep a bare redirect (no behavior change). The site
+* name + description become the card's title/description (`og:type=website`); `url` is the
+* canonical the page points at. A bare article/tag alias gets this site card as a fallback;
+* crawlers that honor the page's `rel=canonical` still resolve the per-route card.
+*
+* @param input - The site slice, head defaults, landing URL, and optional `og:locale`.
+* @returns The ordered site-level head element set, or `[]` when no default image is set.
+* @example composeSiteHead({ site, defaults, url: "https://blog.dev/en/", ogLocale: "en_US" })
+*/
+function composeSiteHead(input) {
+	const { site, defaults, url, ogLocale } = input;
+	const image = defaults.defaultOgImage;
+	if (image === void 0) return [];
+	const absoluteImage = resolveImage(image, site);
+	const name = site.name();
+	const description = site.description();
+	const elements = [
+		meta("description", description),
+		og("og:type", "website"),
+		og("og:site_name", name),
+		og("og:title", name),
+		og("og:description", description),
+		og("og:url", url),
+		og("og:image", absoluteImage),
+		twitter("twitter:card", defaults.twitterCard),
+		twitter("twitter:title", name),
+		twitter("twitter:description", description),
+		twitter("twitter:image", absoluteImage)
+	];
+	if (defaults.twitterHandle) elements.push(twitter("twitter:site", defaults.twitterHandle));
+	if (ogLocale) elements.push(og("og:locale", ogLocale));
+	return elements;
+}
+/**
 * HTML-escape a value for safe insertion into an attribute or text node. `&` is
 * escaped first so already-escaped entities are not double-escaped.
 *
@@ -2602,28 +2638,53 @@ function readDefaults(state) {
 * ```
 */
 function createApi$1(ctx) {
-	return {
-	/**
-	* Compose the final `<head>` inner HTML for a route (pulled by `build`).
-	*
-	* @param route - The resolved route descriptor (incl. its `.head()` HeadConfig).
-	* @param data - The page data object passed to the route's loader/render.
-	* @returns The serialized inner HTML of `<head>`.
-	* @example
-	* ```ts
-	* api.render(route, { title: "Post" });
-	* ```
-	*/
-render(route, data) {
-		return serializeHead(composeHead({
-			route,
-			data,
-			defaults: readDefaults(ctx.state),
-			site: ctx.require(sitePlugin),
-			i18n: ctx.require(i18nPlugin),
-			router: ctx.require(routerPlugin)
-		}));
-	} };
+	return {
+		/**
+		* Compose the final `<head>` inner HTML for a route (pulled by `build`).
+		*
+		* @param route - The resolved route descriptor (incl. its `.head()` HeadConfig).
+		* @param data - The page data object passed to the route's loader/render.
+		* @returns The serialized inner HTML of `<head>`.
+		* @example
+		* ```ts
+		* api.render(route, { title: "Post" });
+		* ```
+		*/
+		render(route, data) {
+			return serializeHead(composeHead({
+				route,
+				data,
+				defaults: readDefaults(ctx.state),
+				site: ctx.require(sitePlugin),
+				i18n: ctx.require(i18nPlugin),
+				router: ctx.require(routerPlugin)
+			}));
+		},
+		/**
+		* Compose the site-level OG/Twitter block for a bare-path redirect/landing page. Resolves
+		* `site`/`i18n` via `ctx.require`, absolutizes `url` against the site base, and emits an
+		* `og:locale` for `locale` when supplied. Returns `""` when no `defaultOgImage` is configured.
+		*
+		* @param input - The landing URL/path plus an optional locale (for `og:locale`).
+		* @param input.url - The page's URL or path (absolutized via `site.canonical`) → `og:url`.
+		* @param input.locale - Optional locale whose `og:locale` is emitted.
+		* @returns The serialized inner HTML of the site-level head block, or `""` when disabled.
+		* @example
+		* ```ts
+		* api.siteHead({ url: "/en/", locale: "en" });
+		* ```
+		*/
+		siteHead(input) {
+			const site = ctx.require(sitePlugin);
+			const ogLocale = input.locale === void 0 ? void 0 : ctx.require(i18nPlugin).ogLocale(input.locale);
+			return serializeHead(composeSiteHead({
+				site,
+				defaults: readDefaults(ctx.state),
+				url: site.canonical(input.url),
+				...ogLocale === void 0 ? {} : { ogLocale }
+			}));
+		}
+	};
 }
 //#endregion
 //#region src/plugins/head/config.ts

package/dist/index.cjs CHANGED Viewed

@@ -3072,6 +3072,42 @@ function composeHead(input) {
 	}), ...head.elements ?? []]);
 }
 /**
+* Compose the SITE-LEVEL Open Graph / Twitter block for a bare-path redirect or landing
+* page that has no per-route head of its own. Returns `[]` UNLESS a `defaultOgImage` is
+* configured — so apps that opt out keep a bare redirect (no behavior change). The site
+* name + description become the card's title/description (`og:type=website`); `url` is the
+* canonical the page points at. A bare article/tag alias gets this site card as a fallback;
+* crawlers that honor the page's `rel=canonical` still resolve the per-route card.
+*
+* @param input - The site slice, head defaults, landing URL, and optional `og:locale`.
+* @returns The ordered site-level head element set, or `[]` when no default image is set.
+* @example composeSiteHead({ site, defaults, url: "https://blog.dev/en/", ogLocale: "en_US" })
+*/
+function composeSiteHead(input) {
+	const { site, defaults, url, ogLocale } = input;
+	const image = defaults.defaultOgImage;
+	if (image === void 0) return [];
+	const absoluteImage = resolveImage(image, site);
+	const name = site.name();
+	const description = site.description();
+	const elements = [
+		meta("description", description),
+		og("og:type", "website"),
+		og("og:site_name", name),
+		og("og:title", name),
+		og("og:description", description),
+		og("og:url", url),
+		og("og:image", absoluteImage),
+		twitter("twitter:card", defaults.twitterCard),
+		twitter("twitter:title", name),
+		twitter("twitter:description", description),
+		twitter("twitter:image", absoluteImage)
+	];
+	if (defaults.twitterHandle) elements.push(twitter("twitter:site", defaults.twitterHandle));
+	if (ogLocale) elements.push(og("og:locale", ogLocale));
+	return elements;
+}
+/**
 * HTML-escape a value for safe insertion into an attribute or text node. `&` is
 * escaped first so already-escaped entities are not double-escaped.
 *
@@ -3160,28 +3196,53 @@ function readDefaults(state) {
 * ```
 */
 function createApi$4(ctx) {
-	return {
-	/**
-	* Compose the final `<head>` inner HTML for a route (pulled by `build`).
-	*
-	* @param route - The resolved route descriptor (incl. its `.head()` HeadConfig).
-	* @param data - The page data object passed to the route's loader/render.
-	* @returns The serialized inner HTML of `<head>`.
-	* @example
-	* ```ts
-	* api.render(route, { title: "Post" });
-	* ```
-	*/
-render(route, data) {
-		return serializeHead(composeHead({
-			route,
-			data,
-			defaults: readDefaults(ctx.state),
-			site: ctx.require(sitePlugin),
-			i18n: ctx.require(i18nPlugin),
-			router: ctx.require(routerPlugin)
-		}));
-	} };
+	return {
+		/**
+		* Compose the final `<head>` inner HTML for a route (pulled by `build`).
+		*
+		* @param route - The resolved route descriptor (incl. its `.head()` HeadConfig).
+		* @param data - The page data object passed to the route's loader/render.
+		* @returns The serialized inner HTML of `<head>`.
+		* @example
+		* ```ts
+		* api.render(route, { title: "Post" });
+		* ```
+		*/
+		render(route, data) {
+			return serializeHead(composeHead({
+				route,
+				data,
+				defaults: readDefaults(ctx.state),
+				site: ctx.require(sitePlugin),
+				i18n: ctx.require(i18nPlugin),
+				router: ctx.require(routerPlugin)
+			}));
+		},
+		/**
+		* Compose the site-level OG/Twitter block for a bare-path redirect/landing page. Resolves
+		* `site`/`i18n` via `ctx.require`, absolutizes `url` against the site base, and emits an
+		* `og:locale` for `locale` when supplied. Returns `""` when no `defaultOgImage` is configured.
+		*
+		* @param input - The landing URL/path plus an optional locale (for `og:locale`).
+		* @param input.url - The page's URL or path (absolutized via `site.canonical`) → `og:url`.
+		* @param input.locale - Optional locale whose `og:locale` is emitted.
+		* @returns The serialized inner HTML of the site-level head block, or `""` when disabled.
+		* @example
+		* ```ts
+		* api.siteHead({ url: "/en/", locale: "en" });
+		* ```
+		*/
+		siteHead(input) {
+			const site = ctx.require(sitePlugin);
+			const ogLocale = input.locale === void 0 ? void 0 : ctx.require(i18nPlugin).ogLocale(input.locale);
+			return serializeHead(composeSiteHead({
+				site,
+				defaults: readDefaults(ctx.state),
+				url: site.canonical(input.url),
+				...ogLocale === void 0 ? {} : { ogLocale }
+			}));
+		}
+	};
 }
 //#endregion
 //#region src/plugins/head/config.ts
@@ -3754,19 +3815,26 @@ async function processImages(ctx, options = {}) {
 * bare path that points at the default-locale-prefixed URL. Deliberately does NOT
 * emit a Cloudflare `_redirects` catch-all (an SSG infinite-loop trap). Gated by
 * `config.localeRedirects` (false/unset disables).
+*
+* When `head.defaultOgImage` is configured, each redirect page ALSO carries the
+* site-level Open Graph / Twitter block (`head.siteHead`) so a social crawler that
+* fetches the apex domain (or any locale-less alias) — and does not follow the
+* meta-refresh — still gets a branded preview card. No image configured ⇒ bare redirect.
 */
 /**
-* Render a redirect HTML page: a `0;url` refresh meta + a canonical link to `target`.
+* Render a redirect HTML page: a `0;url` refresh meta + a canonical link to `target`,
+* with an optional site-level OG/Twitter block injected at the end of `<head>`.
 *
 * @param target - The default-locale-prefixed URL to redirect to.
+* @param headExtra - Extra `<head>` inner HTML (the site-level OG block), or `""` for none.
 * @returns The complete redirect HTML document string.
 * @example
 * ```ts
-* redirectHtml("/en/about/");
+* redirectHtml("/en/about/", '<meta property="og:image" content="…">');
 * ```
 */
-function redirectHtml(target) {
-	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${target}"><link rel="canonical" href="${target}"></head><body><a href="${target}">Redirecting…</a></body></html>`;
+function redirectHtml(target, headExtra = "") {
+	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${target}"><link rel="canonical" href="${target}">${headExtra}</head><body><a href="${target}">Redirecting…</a></body></html>`;
 }
 /**
 * Correlate manifest definitions to compiled `TypedRoute` entries by pattern (the
@@ -3858,16 +3926,17 @@ async function expandRedirects(definition, entry, defaultLocale, ctx) {
 * @param job.file - The redirect page's output path, relative to `outDir`.
 * @param job.target - The absolute default-locale URL the page redirects to.
 * @param outDir - The build output directory the file is resolved against.
+* @param headExtra - The site-level OG block to inject into `<head>`, or `""` for none.
 * @returns Resolves once the redirect HTML page is written.
 * @example
 * ```ts
-* await writeRedirectFile({ file: "about/index.html", target: "/en/about/" }, "dist");
+* await writeRedirectFile({ file: "about/index.html", target: "/en/about/" }, "dist", "");
 * ```
 */
-async function writeRedirectFile(job, outDir) {
+async function writeRedirectFile(job, outDir, headExtra = "") {
 	const filePath = node_path$1.default.join(outDir, job.file);
 	await (0, node_fs_promises.mkdir)(node_path$1.default.dirname(filePath), { recursive: true });
-	await (0, node_fs_promises.writeFile)(filePath, redirectHtml(job.target), "utf8");
+	await (0, node_fs_promises.writeFile)(filePath, redirectHtml(job.target, headExtra), "utf8");
 }
 /**
 * Emits one bare-path redirect HTML page per locale-prefixed route path, each a
@@ -3890,7 +3959,14 @@ async function generateLocaleRedirects(ctx) {
 	const router = ctx.require(routerPlugin);
 	const defaultLocale = ctx.require(i18nPlugin).defaultLocale();
 	const jobs = (await Promise.all(pairRoutes(router).map(([definition, entry]) => expandRedirects(definition, entry, defaultLocale, ctx)))).flat();
-	await Promise.all(jobs.map((job) => writeRedirectFile(job, ctx.config.outDir)));
+	const head = ctx.has("head") ? ctx.require(headPlugin) : void 0;
+	await Promise.all(jobs.map((job) => {
+		const headExtra = head ? head.siteHead({
+			url: job.target,
+			locale: defaultLocale
+		}) : "";
+		return writeRedirectFile(job, ctx.config.outDir, headExtra);
+	}));
 	ctx.log.debug("build:locale-redirects", { written: jobs.length });
 	return { written: jobs.length };
 }
@@ -4098,6 +4174,45 @@ function defaultCard(input) {
 	} }, input.title);
 }
 /**
+* The built-in SITE-LEVEL default card — the site name over its description on a dark
+* background, centered. Rendered once (when `ogImage.defaultCard` is true) to `og-default.png`
+* and used as the `head.defaultOgImage` fallback. Reads `siteName` + `description` from the
+* {@link RichOgInput}; the per-article `render` hook is deliberately NOT applied here.
+*
+* @param input - The rich OG input (only `siteName` + `description` are used).
+* @returns The Preact `VNode` for the site default card.
+* @example
+* ```ts
+* defaultSiteCard({ ...input, siteName: "My Blog", description: "A dev blog" });
+* ```
+*/
+function defaultSiteCard(input) {
+	const children = [(0, preact.h)("div", { style: {
+		display: "flex",
+		fontSize: 72,
+		fontWeight: 700,
+		color: "#ffffff"
+	} }, input.siteName)];
+	if (input.description) children.push((0, preact.h)("div", { style: {
+		display: "flex",
+		marginTop: 28,
+		maxWidth: 900,
+		fontSize: 32,
+		color: "#a1a1aa",
+		textAlign: "center"
+	} }, input.description));
+	return (0, preact.h)("div", { style: {
+		display: "flex",
+		flexDirection: "column",
+		width: "100%",
+		height: "100%",
+		alignItems: "center",
+		justifyContent: "center",
+		padding: 80,
+		background: "#0b0b0c"
+	} }, ...children);
+}
+/**
 * The default PNG renderer: a Preact `VNode` (custom `render` hook or the built-in
 * card) is rendered to SVG by Satori, then rasterized to PNG by resvg. Both native
 * deps are imported LAZILY (browser-safe goal); the VNode→Satori-input cast happens
@@ -4187,6 +4302,24 @@ function resolveSiteName(ctx) {
 	}
 }
 /**
+* Resolve the site description via `ctx.require(sitePlugin)`, falling back to `""` when the
+* site API is unavailable (e.g. unit mocks that omit it). Used by the site default card.
+*
+* @param ctx - Plugin context (provides `require`).
+* @returns The site description, or `""` when the site plugin is not wired.
+* @example
+* ```ts
+* resolveSiteDescription(ctx);
+* ```
+*/
+function resolveSiteDescription(ctx) {
+	try {
+		return ctx.require(sitePlugin).description();
+	} catch {
+		return "";
+	}
+}
+/**
 * Render (or cache-skip) one article's OG image, mutating {@link RenderTally} in
 * place. A matching cached hash bumps `skipped` and returns early; otherwise the
 * PNG is rasterized to `<outDir>/og/<slug>.png`, the cache entry is updated, and
@@ -4257,6 +4390,10 @@ async function generateOgImages(ctx, options = {}) {
 		fonts,
 		...renderHook
 	});
+	const renderSitePng = options.renderPng ?? makeDefaultRenderer({
+		fonts,
+		render: defaultSiteCard
+	});
 	const siteName = resolveSiteName(ctx);
 	const defaultLocale = ctx.require(i18nPlugin).defaultLocale();
 	const articles = selectArticles(readCachedContent(ctx), defaultLocale);
@@ -4281,15 +4418,31 @@ async function generateOgImages(ctx, options = {}) {
 			outDir
 		}, tally);
 	})));
+	const defaultCard = config.defaultCard === true;
+	if (defaultCard) {
+		const png = await renderSitePng({
+			title: siteName,
+			description: resolveSiteDescription(ctx),
+			date: "",
+			tags: [],
+			locale: defaultLocale,
+			siteName,
+			size
+		});
+		await (0, node_fs_promises.mkdir)(ctx.config.outDir, { recursive: true });
+		await (0, node_fs_promises.writeFile)(node_path.default.join(ctx.config.outDir, "og-default.png"), png);
+	}
 	await persistDiskCache(ctx.config.outDir, cache);
 	ctx.log.debug("build:og-images", {
 		rendered: tally.rendered,
-		skipped: tally.skipped
+		skipped: tally.skipped,
+		defaultCard
 	});
 	return {
 		rendered: tally.rendered,
 		skipped: tally.skipped,
-		peakConcurrency: tally.peakConcurrency
+		peakConcurrency: tally.peakConcurrency,
+		defaultCard
 	};
 }
 /**

package/dist/index.d.cts CHANGED Viewed

@@ -1138,6 +1138,25 @@ type Api$4 = {
    * ```
    */
   render(route: ResolvedRoute, data: unknown): string;
+  /**
+   * Compose the SITE-LEVEL `<head>` Open Graph / Twitter block for a bare-path redirect or
+   * landing page that has no route identity (e.g. the apex-domain `/` redirect a
+   * `localeRedirects` build emits). Returns `""` UNLESS `defaultOgImage` is configured, so
+   * apps that opt out keep a bare redirect. Pulled synchronously by `build`.
+   *
+   * @param input - The landing URL (resolved to an absolute canonical) plus an optional locale.
+   * @param input.url - The page's URL or path (absolutized via `site.canonical`) → `og:url`.
+   * @param input.locale - Optional locale whose `og:locale` is emitted (e.g. the default locale).
+   * @returns The serialized inner HTML of the site-level head block, or `""` when disabled.
+   * @example
+   * ```ts
+   * api.siteHead({ url: "/en/", locale: "en" });
+   * ```
+   */
+  siteHead(input: {
+    url: string;
+    locale?: string;
+  }): string;
 };
 declare namespace types_d_exports$9 {
   export { COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentHooks, ComponentInstance, ExtractApi$1 as ExtractApi, PageData, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
@@ -1613,6 +1632,13 @@ interface OgImageConfig {
   render?(input: RichOgInput): import("preact").VNode;
   /** Explicit named fonts loaded once per build (overrides the first-file scan). */
   fonts?: OgFont[];
+  /**
+   * When `true`, also render a single SITE-LEVEL default card to `<outDir>/og-default.png`
+   * — a generic site name + description on a dark background, using the same loaded fonts (the
+   * per-article `render` hook is NOT applied). Point `head.defaultOgImage` at `"/og-default.png"`
+   * to use it as the og:image fallback for non-article pages. Default `false`.
+   */
+  defaultCard?: boolean;
 }
 /**
  * Public configuration for the `build` plugin. Flags give opt-in granularity over

package/dist/index.d.mts CHANGED Viewed

@@ -1138,6 +1138,25 @@ type Api$4 = {
    * ```
    */
   render(route: ResolvedRoute, data: unknown): string;
+  /**
+   * Compose the SITE-LEVEL `<head>` Open Graph / Twitter block for a bare-path redirect or
+   * landing page that has no route identity (e.g. the apex-domain `/` redirect a
+   * `localeRedirects` build emits). Returns `""` UNLESS `defaultOgImage` is configured, so
+   * apps that opt out keep a bare redirect. Pulled synchronously by `build`.
+   *
+   * @param input - The landing URL (resolved to an absolute canonical) plus an optional locale.
+   * @param input.url - The page's URL or path (absolutized via `site.canonical`) → `og:url`.
+   * @param input.locale - Optional locale whose `og:locale` is emitted (e.g. the default locale).
+   * @returns The serialized inner HTML of the site-level head block, or `""` when disabled.
+   * @example
+   * ```ts
+   * api.siteHead({ url: "/en/", locale: "en" });
+   * ```
+   */
+  siteHead(input: {
+    url: string;
+    locale?: string;
+  }): string;
 };
 declare namespace types_d_exports$9 {
   export { COMPONENT_HOOK_NAMES, ComponentContext, ComponentDef, ComponentHooks, ComponentInstance, ExtractApi$1 as ExtractApi, PageData, ResolvedSpaConfig, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState };
@@ -1613,6 +1632,13 @@ interface OgImageConfig {
   render?(input: RichOgInput): import("preact").VNode;
   /** Explicit named fonts loaded once per build (overrides the first-file scan). */
   fonts?: OgFont[];
+  /**
+   * When `true`, also render a single SITE-LEVEL default card to `<outDir>/og-default.png`
+   * — a generic site name + description on a dark background, using the same loaded fonts (the
+   * per-article `render` hook is NOT applied). Point `head.defaultOgImage` at `"/og-default.png"`
+   * to use it as the og:image fallback for non-article pages. Default `false`.
+   */
+  defaultCard?: boolean;
 }
 /**
  * Public configuration for the `build` plugin. Flags give opt-in granularity over

package/dist/index.mjs CHANGED Viewed

@@ -3059,6 +3059,42 @@ function composeHead(input) {
 	}), ...head.elements ?? []]);
 }
 /**
+* Compose the SITE-LEVEL Open Graph / Twitter block for a bare-path redirect or landing
+* page that has no per-route head of its own. Returns `[]` UNLESS a `defaultOgImage` is
+* configured — so apps that opt out keep a bare redirect (no behavior change). The site
+* name + description become the card's title/description (`og:type=website`); `url` is the
+* canonical the page points at. A bare article/tag alias gets this site card as a fallback;
+* crawlers that honor the page's `rel=canonical` still resolve the per-route card.
+*
+* @param input - The site slice, head defaults, landing URL, and optional `og:locale`.
+* @returns The ordered site-level head element set, or `[]` when no default image is set.
+* @example composeSiteHead({ site, defaults, url: "https://blog.dev/en/", ogLocale: "en_US" })
+*/
+function composeSiteHead(input) {
+	const { site, defaults, url, ogLocale } = input;
+	const image = defaults.defaultOgImage;
+	if (image === void 0) return [];
+	const absoluteImage = resolveImage(image, site);
+	const name = site.name();
+	const description = site.description();
+	const elements = [
+		meta("description", description),
+		og("og:type", "website"),
+		og("og:site_name", name),
+		og("og:title", name),
+		og("og:description", description),
+		og("og:url", url),
+		og("og:image", absoluteImage),
+		twitter("twitter:card", defaults.twitterCard),
+		twitter("twitter:title", name),
+		twitter("twitter:description", description),
+		twitter("twitter:image", absoluteImage)
+	];
+	if (defaults.twitterHandle) elements.push(twitter("twitter:site", defaults.twitterHandle));
+	if (ogLocale) elements.push(og("og:locale", ogLocale));
+	return elements;
+}
+/**
 * HTML-escape a value for safe insertion into an attribute or text node. `&` is
 * escaped first so already-escaped entities are not double-escaped.
 *
@@ -3147,28 +3183,53 @@ function readDefaults(state) {
 * ```
 */
 function createApi$4(ctx) {
-	return {
-	/**
-	* Compose the final `<head>` inner HTML for a route (pulled by `build`).
-	*
-	* @param route - The resolved route descriptor (incl. its `.head()` HeadConfig).
-	* @param data - The page data object passed to the route's loader/render.
-	* @returns The serialized inner HTML of `<head>`.
-	* @example
-	* ```ts
-	* api.render(route, { title: "Post" });
-	* ```
-	*/
-render(route, data) {
-		return serializeHead(composeHead({
-			route,
-			data,
-			defaults: readDefaults(ctx.state),
-			site: ctx.require(sitePlugin),
-			i18n: ctx.require(i18nPlugin),
-			router: ctx.require(routerPlugin)
-		}));
-	} };
+	return {
+		/**
+		* Compose the final `<head>` inner HTML for a route (pulled by `build`).
+		*
+		* @param route - The resolved route descriptor (incl. its `.head()` HeadConfig).
+		* @param data - The page data object passed to the route's loader/render.
+		* @returns The serialized inner HTML of `<head>`.
+		* @example
+		* ```ts
+		* api.render(route, { title: "Post" });
+		* ```
+		*/
+		render(route, data) {
+			return serializeHead(composeHead({
+				route,
+				data,
+				defaults: readDefaults(ctx.state),
+				site: ctx.require(sitePlugin),
+				i18n: ctx.require(i18nPlugin),
+				router: ctx.require(routerPlugin)
+			}));
+		},
+		/**
+		* Compose the site-level OG/Twitter block for a bare-path redirect/landing page. Resolves
+		* `site`/`i18n` via `ctx.require`, absolutizes `url` against the site base, and emits an
+		* `og:locale` for `locale` when supplied. Returns `""` when no `defaultOgImage` is configured.
+		*
+		* @param input - The landing URL/path plus an optional locale (for `og:locale`).
+		* @param input.url - The page's URL or path (absolutized via `site.canonical`) → `og:url`.
+		* @param input.locale - Optional locale whose `og:locale` is emitted.
+		* @returns The serialized inner HTML of the site-level head block, or `""` when disabled.
+		* @example
+		* ```ts
+		* api.siteHead({ url: "/en/", locale: "en" });
+		* ```
+		*/
+		siteHead(input) {
+			const site = ctx.require(sitePlugin);
+			const ogLocale = input.locale === void 0 ? void 0 : ctx.require(i18nPlugin).ogLocale(input.locale);
+			return serializeHead(composeSiteHead({
+				site,
+				defaults: readDefaults(ctx.state),
+				url: site.canonical(input.url),
+				...ogLocale === void 0 ? {} : { ogLocale }
+			}));
+		}
+	};
 }
 //#endregion
 //#region src/plugins/head/config.ts
@@ -3741,19 +3802,26 @@ async function processImages(ctx, options = {}) {
 * bare path that points at the default-locale-prefixed URL. Deliberately does NOT
 * emit a Cloudflare `_redirects` catch-all (an SSG infinite-loop trap). Gated by
 * `config.localeRedirects` (false/unset disables).
+*
+* When `head.defaultOgImage` is configured, each redirect page ALSO carries the
+* site-level Open Graph / Twitter block (`head.siteHead`) so a social crawler that
+* fetches the apex domain (or any locale-less alias) — and does not follow the
+* meta-refresh — still gets a branded preview card. No image configured ⇒ bare redirect.
 */
 /**
-* Render a redirect HTML page: a `0;url` refresh meta + a canonical link to `target`.
+* Render a redirect HTML page: a `0;url` refresh meta + a canonical link to `target`,
+* with an optional site-level OG/Twitter block injected at the end of `<head>`.
 *
 * @param target - The default-locale-prefixed URL to redirect to.
+* @param headExtra - Extra `<head>` inner HTML (the site-level OG block), or `""` for none.
 * @returns The complete redirect HTML document string.
 * @example
 * ```ts
-* redirectHtml("/en/about/");
+* redirectHtml("/en/about/", '<meta property="og:image" content="…">');
 * ```
 */
-function redirectHtml(target) {
-	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${target}"><link rel="canonical" href="${target}"></head><body><a href="${target}">Redirecting…</a></body></html>`;
+function redirectHtml(target, headExtra = "") {
+	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${target}"><link rel="canonical" href="${target}">${headExtra}</head><body><a href="${target}">Redirecting…</a></body></html>`;
 }
 /**
 * Correlate manifest definitions to compiled `TypedRoute` entries by pattern (the
@@ -3845,16 +3913,17 @@ async function expandRedirects(definition, entry, defaultLocale, ctx) {
 * @param job.file - The redirect page's output path, relative to `outDir`.
 * @param job.target - The absolute default-locale URL the page redirects to.
 * @param outDir - The build output directory the file is resolved against.
+* @param headExtra - The site-level OG block to inject into `<head>`, or `""` for none.
 * @returns Resolves once the redirect HTML page is written.
 * @example
 * ```ts
-* await writeRedirectFile({ file: "about/index.html", target: "/en/about/" }, "dist");
+* await writeRedirectFile({ file: "about/index.html", target: "/en/about/" }, "dist", "");
 * ```
 */
-async function writeRedirectFile(job, outDir) {
+async function writeRedirectFile(job, outDir, headExtra = "") {
 	const filePath = path.join(outDir, job.file);
 	await mkdir(path.dirname(filePath), { recursive: true });
-	await writeFile(filePath, redirectHtml(job.target), "utf8");
+	await writeFile(filePath, redirectHtml(job.target, headExtra), "utf8");
 }
 /**
 * Emits one bare-path redirect HTML page per locale-prefixed route path, each a
@@ -3877,7 +3946,14 @@ async function generateLocaleRedirects(ctx) {
 	const router = ctx.require(routerPlugin);
 	const defaultLocale = ctx.require(i18nPlugin).defaultLocale();
 	const jobs = (await Promise.all(pairRoutes(router).map(([definition, entry]) => expandRedirects(definition, entry, defaultLocale, ctx)))).flat();
-	await Promise.all(jobs.map((job) => writeRedirectFile(job, ctx.config.outDir)));
+	const head = ctx.has("head") ? ctx.require(headPlugin) : void 0;
+	await Promise.all(jobs.map((job) => {
+		const headExtra = head ? head.siteHead({
+			url: job.target,
+			locale: defaultLocale
+		}) : "";
+		return writeRedirectFile(job, ctx.config.outDir, headExtra);
+	}));
 	ctx.log.debug("build:locale-redirects", { written: jobs.length });
 	return { written: jobs.length };
 }
@@ -4085,6 +4161,45 @@ function defaultCard(input) {
 	} }, input.title);
 }
 /**
+* The built-in SITE-LEVEL default card — the site name over its description on a dark
+* background, centered. Rendered once (when `ogImage.defaultCard` is true) to `og-default.png`
+* and used as the `head.defaultOgImage` fallback. Reads `siteName` + `description` from the
+* {@link RichOgInput}; the per-article `render` hook is deliberately NOT applied here.
+*
+* @param input - The rich OG input (only `siteName` + `description` are used).
+* @returns The Preact `VNode` for the site default card.
+* @example
+* ```ts
+* defaultSiteCard({ ...input, siteName: "My Blog", description: "A dev blog" });
+* ```
+*/
+function defaultSiteCard(input) {
+	const children = [h("div", { style: {
+		display: "flex",
+		fontSize: 72,
+		fontWeight: 700,
+		color: "#ffffff"
+	} }, input.siteName)];
+	if (input.description) children.push(h("div", { style: {
+		display: "flex",
+		marginTop: 28,
+		maxWidth: 900,
+		fontSize: 32,
+		color: "#a1a1aa",
+		textAlign: "center"
+	} }, input.description));
+	return h("div", { style: {
+		display: "flex",
+		flexDirection: "column",
+		width: "100%",
+		height: "100%",
+		alignItems: "center",
+		justifyContent: "center",
+		padding: 80,
+		background: "#0b0b0c"
+	} }, ...children);
+}
+/**
 * The default PNG renderer: a Preact `VNode` (custom `render` hook or the built-in
 * card) is rendered to SVG by Satori, then rasterized to PNG by resvg. Both native
 * deps are imported LAZILY (browser-safe goal); the VNode→Satori-input cast happens
@@ -4174,6 +4289,24 @@ function resolveSiteName(ctx) {
 	}
 }
 /**
+* Resolve the site description via `ctx.require(sitePlugin)`, falling back to `""` when the
+* site API is unavailable (e.g. unit mocks that omit it). Used by the site default card.
+*
+* @param ctx - Plugin context (provides `require`).
+* @returns The site description, or `""` when the site plugin is not wired.
+* @example
+* ```ts
+* resolveSiteDescription(ctx);
+* ```
+*/
+function resolveSiteDescription(ctx) {
+	try {
+		return ctx.require(sitePlugin).description();
+	} catch {
+		return "";
+	}
+}
+/**
 * Render (or cache-skip) one article's OG image, mutating {@link RenderTally} in
 * place. A matching cached hash bumps `skipped` and returns early; otherwise the
 * PNG is rasterized to `<outDir>/og/<slug>.png`, the cache entry is updated, and
@@ -4244,6 +4377,10 @@ async function generateOgImages(ctx, options = {}) {
 		fonts,
 		...renderHook
 	});
+	const renderSitePng = options.renderPng ?? makeDefaultRenderer({
+		fonts,
+		render: defaultSiteCard
+	});
 	const siteName = resolveSiteName(ctx);
 	const defaultLocale = ctx.require(i18nPlugin).defaultLocale();
 	const articles = selectArticles(readCachedContent(ctx), defaultLocale);
@@ -4268,15 +4405,31 @@ async function generateOgImages(ctx, options = {}) {
 			outDir
 		}, tally);
 	})));
+	const defaultCard = config.defaultCard === true;
+	if (defaultCard) {
+		const png = await renderSitePng({
+			title: siteName,
+			description: resolveSiteDescription(ctx),
+			date: "",
+			tags: [],
+			locale: defaultLocale,
+			siteName,
+			size
+		});
+		await mkdir(ctx.config.outDir, { recursive: true });
+		await writeFile(path.join(ctx.config.outDir, "og-default.png"), png);
+	}
 	await persistDiskCache(ctx.config.outDir, cache);
 	ctx.log.debug("build:og-images", {
 		rendered: tally.rendered,
-		skipped: tally.skipped
+		skipped: tally.skipped,
+		defaultCard
 	});
 	return {
 		rendered: tally.rendered,
 		skipped: tally.skipped,
-		peakConcurrency: tally.peakConcurrency
+		peakConcurrency: tally.peakConcurrency,
+		defaultCard
 	};
 }
 /**

package/package.json CHANGED Viewed

@@ -113,5 +113,5 @@
     "test:cli-e2e": "bun test src/plugins/cli/__tests__/e2e/",
     "test:coverage": "vitest run --project unit --project integration --coverage"
   },
-  "version": "1.4.1"
+  "version": "1.5.1"
 }