@getquick/content 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { A as Unavailable, B as routeLanguage, C as EntryContent, D as PublishedEntry, E as Missing, F as SiteLanguage, I as WordPressLanguages, L as htmlLang, M as WordPressMenuItem, N as WordPressPost, O as SiteChrome, P as WordPressSettings, R as isLanguageHome, S as DesignPresets, T as HomeContent, V as siteLanguages, _ as SqlDatabase, b as CmsFailureReason, c as EntryDelivery, d as HomeDelivery, f as HomePage, g as ContentBindings, h as NotServed, i as ContentRuntime, j as WordPressImage, k as Translation, l as EntryPage, m as Moved, n as ContentConfig, o as Alternate, p as HomePublication, r as ContentConsentConfig, s as DeliveryFailureReason, t as WordPressClient, u as EntryPublication, v as SqlStatement, w as Found, x as Delivery, y as CmsFailure, z as languageSubject } from "./wordpress-CPL40-vq.js";
+import { $ as Found, A as htmlLang, B as designMenuItems, C as Moved, D as SqlStatement, E as SqlDatabase, F as DesignBlock, G as CmsFailure, H as parseDesignBlocks, I as DesignBlockRenderer, J as CollectionTerm, K as CmsFailureReason, L as DesignPattern, M as languageSubject, N as routeLanguage, O as SiteLanguage, P as siteLanguages, Q as Extended, R as DesignRenderContext, S as HomePublication, T as ContentBindings, U as renderDesignPattern, V as escapeHtml, W as Archives, X as DesignPresets, Y as Delivery, Z as EntryContent, _ as EntryDelivery, a as ContentExtension, at as Unavailable, b as HomeDelivery, ct as WordPressPost, d as CollectionListing, et as HomeContent, f as CollectionPage, g as DeliveryFailureReason, h as CollectionTermListing, i as ContentConsentConfig, it as Translation, j as isLanguageHome, k as WordPressLanguages, l as Alternate, lt as WordPressSettings, m as CollectionTermCount, n as CollectionConfig, nt as PublishedEntry, o as ContentRuntime, ot as WordPressImage, p as CollectionQuery, q as CollectionMembership, r as ContentConfig, rt as SiteChrome, s as ExtensionNode, st as WordPressMenuItem, t as WordPressClient, tt as Missing, u as CollectionItem, v as EntryPage, w as NotServed, x as HomePage, y as EntryPublication, z as DesignRenderOptions } from "./wordpress-D_HG2rEt.js";
 //#region frontend/src/wp-block-styles.d.ts
 export interface Preset {
   slug: string;
@@ -13,8 +13,19 @@ export interface BlockPresetStyles {
   vars: Record<string, string>;
   colorRules: string;
 }
-/** WordPress preset classes need the CMS palette as well as CSS variables. */
-export declare function blockPresetStyles(spacingSizes: SpacingPreset[], colors: ColorPreset[]): BlockPresetStyles;
+/**
+ * WordPress preset classes need the CMS palette as well as CSS variables.
+ * `scope` is the content's container (`.prose-wp` by default; another for
+ * content a Site renders itself).
+ */
+export declare function blockPresetStyles(spacingSizes: SpacingPreset[], colors: ColorPreset[], scope?: string): BlockPresetStyles;
+/**
+ * The design presets as WordPress defines them, on `:root`, for styles that
+ * read the palette and spacing from these variables outside the content's
+ * container. Presets with an invalid slug, or a value that could end the
+ * rule, are left out; "" without any.
+ */
+export declare function presetRootStyle(spacingSizes: SpacingPreset[], colors: ColorPreset[]): string;
 //#endregion
 //#region frontend/src/wp-block-renderer.d.ts
 export interface WordPressBlock {
@@ -58,7 +69,12 @@ export declare function cmsTime(value: string | null | undefined): number | null
 export declare function uriPath(uri: string): string;
 export declare function menuItemHref(url: string, internalOrigins: string[]): string;
 export declare function stripHtml(value: string): string;
+/**
+ * Text with its HTML character references decoded: numeric ones, and the
+ * named ones in NAMED_ENTITIES (any other is left as written).
+ */
+export declare function decodeEntities(value: string): string;
 export declare function formatDate(value: string, lang?: string): string;
 export declare function routeOf(path: string): string;
 //#endregion
-export { Alternate, CmsFailure, CmsFailureReason, ContentBindings, type ContentConfig, type ContentConsentConfig, type ContentRuntime, Delivery, DeliveryFailureReason, DesignPresets, EntryContent, EntryDelivery, EntryPage, EntryPublication, Found, HomeContent, HomeDelivery, HomePage, HomePublication, Missing, Moved, NotServed, PublishedEntry, SiteChrome, SiteLanguage, SqlDatabase, SqlStatement, Translation, Unavailable, type WordPressClient, WordPressImage, WordPressLanguages, WordPressMenuItem, WordPressPost, WordPressSettings, htmlLang, isLanguageHome, languageSubject, routeLanguage, siteLanguages };
+export { Alternate, Archives, CmsFailure, CmsFailureReason, type CollectionConfig, CollectionItem, CollectionListing, CollectionMembership, CollectionPage, CollectionQuery, CollectionTerm, CollectionTermCount, CollectionTermListing, ContentBindings, type ContentConfig, type ContentConsentConfig, type ContentExtension, type ContentRuntime, Delivery, DeliveryFailureReason, DesignBlock, DesignBlockRenderer, DesignPattern, DesignPresets, DesignRenderContext, DesignRenderOptions, EntryContent, EntryDelivery, EntryPage, EntryPublication, Extended, type ExtensionNode, Found, HomeContent, HomeDelivery, HomePage, HomePublication, Missing, Moved, NotServed, PublishedEntry, SiteChrome, SiteLanguage, SqlDatabase, SqlStatement, Translation, Unavailable, type WordPressClient, WordPressImage, WordPressLanguages, WordPressMenuItem, WordPressPost, WordPressSettings, designMenuItems, escapeHtml, htmlLang, isLanguageHome, languageSubject, parseDesignBlocks, renderDesignPattern, routeLanguage, siteLanguages };

package/dist/index.js

@@ -1,20 +1,39 @@
-import { _ as youtubeVideoId, a as routeOf, c as htmlLang, d as routeLanguage, f as siteLanguages, g as renderWordPressBlocks, h as parseWordPressBlocks, i as responseStatus, l as isLanguageHome, m as hasVideoHero, n as formatDate, o as stripHtml, p as VIDEO_HERO_BLOCK, r as menuItemHref, s as uriPath, t as cmsTime, u as languageSubject, v as containerChildLayoutHtml, y as containerLayoutHtml } from "./formatting-wOk2jz6J.js";
+import { C as containerChildLayoutHtml, S as youtubeVideoId, _ as uriPath, a as siteLanguages, b as parseWordPressBlocks, c as parseDesignBlocks, d as decodeEntities, f as formatDate, g as stripHtml, h as routeOf, i as routeLanguage, l as renderDesignPattern, m as responseStatus, n as isLanguageHome, o as designMenuItems, p as menuItemHref, r as languageSubject, s as escapeHtml, t as htmlLang, u as cmsTime, v as VIDEO_HERO_BLOCK, w as containerLayoutHtml, x as renderWordPressBlocks, y as hasVideoHero } from "./site-language-cBP8SFrS.js";
 //#region frontend/src/wp-block-styles.ts
 const validSlug = (slug) => /^[a-z0-9][a-z0-9-]*$/.test(slug);
-/** WordPress preset classes need the CMS palette as well as CSS variables. */
-function blockPresetStyles(spacingSizes, colors) {
+/** A CSS value safe inside a stylesheet: a color or length, nothing that ends a rule. */
+const safeValue = (value) => /^[#(),.%\w\s-]+$/.test(value);
+/** A selector for the content's container: classes, ids, elements and descendants. */
+const validScope = (scope) => /^[.#]?[A-Za-z][\w-]*(?:[ .#>][A-Za-z][\w-]*)*$/.test(scope);
+/**
+* WordPress preset classes need the CMS palette as well as CSS variables.
+* `scope` is the content's container (`.prose-wp` by default; another for
+* content a Site renders itself).
+*/
+function blockPresetStyles(spacingSizes, colors, scope = ".prose-wp") {
+	if (!validScope(scope)) throw new Error(`${JSON.stringify(scope)} isn't a container selector`);
 	const vars = {};
 	const colorRules = [];
 	for (const { slug, size } of spacingSizes) if (validSlug(slug)) vars[`--wp--preset--spacing--${slug}`] = size;
 	for (const { slug, color } of colors) {
 		if (!validSlug(slug)) continue;
 		vars[`--wp--preset--color--${slug}`] = color;
-		colorRules.push(`.prose-wp .has-${slug}-color{color:var(--wp--preset--color--${slug})}`, `.prose-wp .has-${slug}-background-color{background-color:var(--wp--preset--color--${slug})}`, `.prose-wp .has-${slug}-color.has-link-color a{color:var(--wp--preset--color--${slug})}`);
+		colorRules.push(`${scope} .has-${slug}-color{color:var(--wp--preset--color--${slug})}`, `${scope} .has-${slug}-background-color{background-color:var(--wp--preset--color--${slug})}`, `${scope} .has-${slug}-color.has-link-color a{color:var(--wp--preset--color--${slug})}`);
 	}
 	return {
 		vars,
 		colorRules: colorRules.join("\n")
 	};
 }
+/**
+* The design presets as WordPress defines them, on `:root`, for styles that
+* read the palette and spacing from these variables outside the content's
+* container. Presets with an invalid slug, or a value that could end the
+* rule, are left out; "" without any.
+*/
+function presetRootStyle(spacingSizes, colors) {
+	const declarations = [...spacingSizes.filter(({ slug, size }) => validSlug(slug) && safeValue(size)).map(({ slug, size }) => `--wp--preset--spacing--${slug}:${size}`), ...colors.filter(({ slug, color }) => validSlug(slug) && safeValue(color)).map(({ slug, color }) => `--wp--preset--color--${slug}:${color}`)];
+	return declarations.length ? `:root{${declarations.join(";")}}` : "";
+}
 //#endregion
-export { VIDEO_HERO_BLOCK, blockPresetStyles, cmsTime, containerChildLayoutHtml, containerLayoutHtml, formatDate, hasVideoHero, htmlLang, isLanguageHome, languageSubject, menuItemHref, parseWordPressBlocks, renderWordPressBlocks, responseStatus, routeLanguage, routeOf, siteLanguages, stripHtml, uriPath, youtubeVideoId };
+export { VIDEO_HERO_BLOCK, blockPresetStyles, cmsTime, containerChildLayoutHtml, containerLayoutHtml, decodeEntities, designMenuItems, escapeHtml, formatDate, hasVideoHero, htmlLang, isLanguageHome, languageSubject, menuItemHref, parseDesignBlocks, parseWordPressBlocks, presetRootStyle, renderDesignPattern, renderWordPressBlocks, responseStatus, routeLanguage, routeOf, siteLanguages, stripHtml, uriPath, youtubeVideoId };

package/dist/metadata-content.d.ts

@@ -0,0 +1,36 @@
+import { MetadataImage, MetadataInput, MetadataLocale, MetadataSite } from "./metadata.js";
+//#region frontend/src/metadata-content.d.ts
+/** Minimal structural slice of existing HomePublication/EntryPublication; no CMS reads. */
+export interface PublishedContentMetadata {
+  /** WordPress title/excerpt are authored HTML; featuredImage.altText is already plain text. */
+  title: string;
+  excerpt?: string;
+  date?: string;
+  featuredImage?: {
+    sourceUrl: string;
+    altText: string;
+  } | null;
+}
+export interface ContentMetadataOptions {
+  site: MetadataSite;
+  route: string;
+  language?: MetadataLocale;
+  kind?: "website" | "article";
+  /** Existing Alternate records: language-home fallbacks are deliberately excluded. */
+  alternates?: readonly {
+    language: MetadataLocale;
+    route: string;
+    translation: boolean;
+  }[];
+  /** Verified dimensions/MIME unavailable in the existing CMS image contract; supplied by asset evidence. */
+  featuredImageFacts?: {
+    width: number;
+    height: number;
+    type?: MetadataImage["type"];
+  };
+}
+/** Decodes entities and extracts authored text without executing HTML or reading body markup. */
+export declare function contentMetadataText(html: string): string;
+/** Call only for the same published snapshot being served, including a retained snapshot. */
+export declare function mapPublishedContentMetadata(content: PublishedContentMetadata, options: ContentMetadataOptions): MetadataInput;
+//#endregion

package/dist/metadata-content.js

@@ -0,0 +1,51 @@
+import { normalizeMetadataText } from "./metadata.js";
+import { n as parseFragment } from "./dist-D4-CMkrf.js";
+//#region frontend/src/metadata-content.ts
+/** Decodes entities and extracts authored text without executing HTML or reading body markup. */
+function contentMetadataText(html) {
+	const walk = (node) => {
+		if ("tagName" in node && [
+			"script",
+			"style",
+			"template"
+		].includes(node.tagName)) return "";
+		if ("value" in node) return node.value;
+		if (!("childNodes" in node)) return "";
+		const text = node.childNodes.map(walk).join("");
+		return "tagName" in node && /^(?:p|div|br|li|h[1-6]|blockquote|section|article)$/u.test(node.tagName) ? ` ${text} ` : text;
+	};
+	return normalizeMetadataText(walk(parseFragment(html)));
+}
+/** Call only for the same published snapshot being served, including a retained snapshot. */
+function mapPublishedContentMetadata(content, options) {
+	const absolute = (route) => new URL(route, options.site.origin).href;
+	const title = contentMetadataText(content.title);
+	const description = content.excerpt === void 0 ? void 0 : contentMetadataText(content.excerpt);
+	const image = content.featuredImage;
+	const facts = options.featuredImageFacts;
+	return {
+		site: options.site,
+		state: "public",
+		status: 200,
+		canonical: absolute(options.route),
+		language: options.language,
+		kind: options.kind,
+		page: {
+			...title ? { title } : {},
+			...description ? { description } : {},
+			...image && facts ? { images: [{
+				url: image.sourceUrl,
+				alt: normalizeMetadataText(image.altText),
+				...facts
+			}] } : {}
+		},
+		translations: options.alternates?.filter((a) => a.translation).map((a) => ({
+			...a.language,
+			canonical: absolute(a.route),
+			published: true
+		})),
+		...options.kind === "article" && content.date && /(?:Z|[+-]\d\d:\d\d)$/u.test(content.date) ? { article: { publishedTime: content.date } } : {}
+	};
+}
+//#endregion
+export { contentMetadataText, mapPublishedContentMetadata };

package/dist/metadata-testing.d.ts

@@ -0,0 +1,34 @@
+import { MetadataImage } from "./metadata.js";
+//#region frontend/src/metadata-testing.d.ts
+export interface MetadataHtmlExpectation {
+  baseline: "OG-1";
+  applicable: boolean;
+  /** false checks preserved document basics while explicitly asserting OG is pending. */
+  graph?: boolean;
+  lang: string;
+  dir: "ltr" | "rtl";
+  robots: string;
+  /** Required for applicable pages; supplied independently of resolver output. */
+  title?: string;
+  shareTitle?: string;
+  canonical?: string;
+  description?: string;
+  siteName?: string;
+  locale?: string;
+  type?: "website" | "article";
+  images?: readonly MetadataImage[];
+  alternates?: readonly {
+    lang: string;
+    url: string;
+  }[];
+  localeAlternates?: readonly string[];
+  article?: {
+    publishedTime?: string;
+    modifiedTime?: string;
+    authors?: readonly string[];
+  };
+}
+/** Parses delivered bytes with HTML-standard tree construction, never resolver descriptors. */
+export declare function inspectMetadataHtml(html: string, expected: MetadataHtmlExpectation): string[];
+export declare function assertMetadataHtml(html: string, expected: MetadataHtmlExpectation): void;
+//#endregion

package/dist/metadata-testing.js

@@ -0,0 +1,142 @@
+import { t as parse } from "./dist-D4-CMkrf.js";
+//#region frontend/src/metadata-testing.ts
+const attr = (node, name) => node.attrs.find((a) => a.name === name)?.value;
+const hasRel = (node, rel) => node.tagName === "link" && (attr(node, "rel") ?? "").toLowerCase().split(/\s+/u).includes(rel);
+const isElement = (node) => "tagName" in node;
+const content = (node) => "value" in node ? node.value : "childNodes" in node ? node.childNodes.map(content).join("") : "";
+/** Parses delivered bytes with HTML-standard tree construction, never resolver descriptors. */
+function inspectMetadataHtml(html, expected) {
+	const issues = [];
+	const document = parse(html, {
+		sourceCodeLocationInfo: true,
+		onParseError: (error) => {
+			if (error.code !== "missing-doctype") issues.push(`HTML parse error: ${error.code}`);
+		}
+	});
+	const all = [];
+	const walk = (node) => {
+		if (isElement(node)) all.push(node);
+		if ("childNodes" in node) node.childNodes.forEach(walk);
+	};
+	walk(document);
+	const root = all.find((node) => node.tagName === "html");
+	const head = all.find((node) => node.tagName === "head");
+	const equal = (label, actual, wanted) => {
+		if (JSON.stringify(actual) !== JSON.stringify(wanted)) issues.push(`${label}: expected ${JSON.stringify(wanted)}, received ${JSON.stringify(actual)}`);
+	};
+	equal("baseline", expected.baseline, "OG-1");
+	equal("html.lang", root && attr(root, "lang"), expected.lang);
+	equal("html.dir", root && attr(root, "dir"), expected.dir);
+	if (!head?.sourceCodeLocation?.startTag || !head.sourceCodeLocation.endTag) issues.push("Explicit complete head required in delivered HTML");
+	const tags = all.filter((node) => [
+		"title",
+		"meta",
+		"link"
+	].includes(node.tagName));
+	const relevant = tags.filter((node) => node.tagName === "title" || /^(og:|article:)/u.test(attr(node, "property") ?? attr(node, "name") ?? "") || ["description", "robots"].includes(attr(node, "name") ?? "") || hasRel(node, "canonical") || hasRel(node, "alternate"));
+	for (const node of relevant) {
+		const location = node.sourceCodeLocation;
+		if (node.parentNode !== head || !location || !head?.sourceCodeLocation?.endTag || location.startOffset < head.sourceCodeLocation.startOffset || location.endOffset > head.sourceCodeLocation.endTag.startOffset) issues.push(`Metadata outside actual head: ${node.tagName}`);
+	}
+	const metas = tags.filter((node) => node.tagName === "meta");
+	const values = (key, attribute = "property") => metas.filter((node) => attr(node, attribute) === key).map((node) => attr(node, "content"));
+	const one = (key, wanted, attribute = "property") => equal(key, values(key, attribute), wanted === void 0 ? [] : [wanted]);
+	one("robots", expected.robots, "name");
+	const graph = metas.filter((node) => /^(og:|article:)/u.test(attr(node, "property") ?? attr(node, "name") ?? ""));
+	const canonicals = tags.filter((node) => hasRel(node, "canonical"));
+	for (const node of relevant) {
+		const allowedAttrs = node.tagName === "meta" ? [
+			"name",
+			"property",
+			"content"
+		] : node.tagName === "link" ? [
+			"rel",
+			"href",
+			"hreflang"
+		] : [];
+		if (node.attrs.some((a) => !allowedAttrs.includes(a.name))) issues.push(`Unexpected attribute on ${node.tagName}`);
+		if (node.tagName === "title" && node.childNodes.some(isElement)) issues.push("Markup inside title");
+	}
+	if (!expected.applicable) {
+		equal("excluded graph", graph.length, 0);
+		equal("excluded canonical", canonicals.length, 0);
+		equal("excluded title", tags.filter((node) => node.tagName === "title").map(content), expected.title === void 0 ? [] : [expected.title]);
+		one("description", void 0, "name");
+		equal("excluded alternates", tags.filter((node) => hasRel(node, "alternate")).length, 0);
+		return issues;
+	}
+	if (expected.graph === false) {
+		equal("pending graph", graph.length, 0);
+		equal("document title", tags.filter((node) => node.tagName === "title").map(content), expected.title === void 0 ? [] : [expected.title]);
+		equal("canonical", canonicals.map((node) => attr(node, "href")), expected.canonical === void 0 ? [] : [expected.canonical]);
+		one("description", expected.description, "name");
+		equal("hreflang links", tags.filter((node) => hasRel(node, "alternate")).map((node) => ({
+			lang: attr(node, "hreflang"),
+			url: attr(node, "href")
+		})), expected.alternates ?? []);
+		return issues;
+	}
+	for (const key of [
+		"title",
+		"canonical",
+		"description",
+		"siteName",
+		"locale",
+		"type"
+	]) if (!expected[key]) issues.push(`Missing independent expectation: ${key}`);
+	if (!expected.images?.length) issues.push("Missing independent image expectations");
+	if (!/(?:^|\s)og:\s+https:\/\/ogp\.me\/ns#(?:\s|$)/u.test(root && attr(root, "prefix") || "")) issues.push("Missing OG namespace");
+	equal("document title", tags.filter((node) => node.tagName === "title").map(content), [expected.title]);
+	equal("canonical", canonicals.map((node) => attr(node, "href")), [expected.canonical]);
+	one("description", expected.description, "name");
+	for (const [key, value] of Object.entries({
+		title: expected.shareTitle ?? expected.title,
+		type: expected.type,
+		url: expected.canonical,
+		description: expected.description,
+		site_name: expected.siteName,
+		locale: expected.locale
+	})) one(`og:${key}`, value);
+	const imageTags = graph.filter((node) => /^og:image(?::|$)/u.test(attr(node, "property") ?? ""));
+	const wantedImages = expected.images?.flatMap((image) => [
+		["og:image", image.url],
+		["og:image:alt", image.alt],
+		["og:image:width", String(image.width)],
+		["og:image:height", String(image.height)],
+		...image.type ? [["og:image:type", image.type]] : []
+	]) ?? [];
+	equal("ordered image groups", imageTags.map((node) => [attr(node, "property"), attr(node, "content")]), wantedImages);
+	equal("locale alternates", values("og:locale:alternate"), expected.localeAlternates ?? []);
+	equal("hreflang links", tags.filter((node) => hasRel(node, "alternate")).map((node) => ({
+		lang: attr(node, "hreflang"),
+		url: attr(node, "href")
+	})), expected.alternates ?? []);
+	one("article:published_time", expected.article?.publishedTime);
+	one("article:modified_time", expected.article?.modifiedTime);
+	equal("article authors", values("article:author"), expected.article?.authors ?? []);
+	const allowed = /* @__PURE__ */ new Set([
+		"og:title",
+		"og:type",
+		"og:url",
+		"og:description",
+		"og:site_name",
+		"og:locale",
+		"og:locale:alternate",
+		"og:image",
+		"og:image:alt",
+		"og:image:width",
+		"og:image:height",
+		"og:image:type",
+		"article:published_time",
+		"article:modified_time",
+		"article:author"
+	]);
+	for (const node of graph) if (!allowed.has(attr(node, "property") ?? "")) issues.push("Unexpected graph property or name-only OG tag");
+	return issues;
+}
+function assertMetadataHtml(html, expected) {
+	const issues = inspectMetadataHtml(html, expected);
+	if (issues.length) throw new Error(`Metadata HTML acceptance failed:\n${issues.join("\n")}`);
+}
+//#endregion
+export { assertMetadataHtml, inspectMetadataHtml };

package/dist/metadata.d.ts

@@ -0,0 +1,94 @@
+//#region frontend/src/metadata.d.ts
+/** Scoped OG-1 candidate contract; adoption and public asset verification are separate gates. */
+export declare const metadataBaseline: "OG-1";
+export interface MetadataImage {
+  url: string;
+  alt: string;
+  width: number;
+  height: number;
+  /** Verified asset MIME, never inferred from the URL extension. */
+  type?: "image/jpeg" | "image/png";
+}
+export interface MetadataLocale {
+  /** BCP 47 HTML language. */
+  lang: string;
+  /** WordPress regional locale or an explicitly configured OG regional locale. */
+  locale: string;
+  dir: "ltr" | "rtl";
+}
+export interface MetadataFacts {
+  title?: string;
+  description?: string;
+  images?: readonly MetadataImage[];
+}
+export interface MetadataSite extends MetadataFacts {
+  /** Reviewed configuration, never an incoming Host header. One HTTPS origin, no path. */
+  origin: string;
+  name: string;
+  /** Configured Site default; input.language identifies the actual page language. */
+  language: MetadataLocale;
+  /** Only these query keys may participate in canonical identity. */
+  identityQueryKeys?: readonly string[];
+}
+export interface MetadataTranslation extends MetadataLocale {
+  canonical: string;
+  published: boolean;
+}
+export interface MetadataArticle {
+  publishedTime?: string;
+  modifiedTime?: string;
+  /** Verified public author profile URLs, not names or private account URLs. */
+  authors?: readonly string[];
+}
+export interface MetadataInput {
+  site: MetadataSite;
+  state: "public" | "private" | "preview" | "withdrawn" | "error" | "redirect";
+  /** A successful graph applies only to status 200. */
+  status: number;
+  /** Explicit safe public status copy for excluded routes; never selected from page/site facts. */
+  statusTitle?: string;
+  canonical?: string;
+  kind?: "website" | "article" | "product" | "listing";
+  language?: MetadataLocale;
+  page?: MetadataFacts;
+  overrides?: MetadataFacts & {
+    shareTitle?: string;
+  };
+  translations?: readonly MetadataTranslation[];
+  article?: MetadataArticle;
+  /** A public page may intentionally opt out of indexing. This is not access control. */
+  noindex?: boolean;
+}
+export type HeadDescriptor = {
+  tag: "title";
+  text: string;
+} | {
+  tag: "meta" | "link";
+  attrs: Record<string, string>;
+};
+export interface MetadataDiagnostic {
+  code: string;
+  field: string;
+  message: string;
+}
+export interface ResolvedMetadata {
+  baseline: typeof metadataBaseline;
+  /** Overall applicable metadata readiness; an OG gap does not remove valid document basics. */
+  ready: boolean;
+  documentReady: boolean;
+  graphReady: boolean;
+  applicable: boolean;
+  htmlAttributes: {
+    lang: string;
+    dir: "ltr" | "rtl";
+    prefix?: string;
+  };
+  head: HeadDescriptor[];
+  diagnostics: MetadataDiagnostic[];
+}
+/** Inputs are plain text. Source-specific HTML/entity decoding belongs in the mapper. */
+export declare function normalizeMetadataText(value: string): string;
+export declare function resolveMetadata(input: MetadataInput): ResolvedMetadata;
+/** Safe HTML fragment for Astro set:html or other server serialization; preserves repeated image groups. */
+export declare function renderMetadataHead(metadata: ResolvedMetadata): string;
+//#endregion