@growth-labs/seo 0.1.5 → 0.2.1

package/dist/utils/json-ld/article.d.ts

@@ -1,4 +1,16 @@
 import type { ResolvedSeoOptions } from '../../options.js';
 import type { ContentItem, JsonLdObject } from '../../types.js';
-export declare function generateArticleJsonLd(item: ContentItem, options: ResolvedSeoOptions): JsonLdObject;
+/**
+ * Redaction mode for gated content.
+ *   'full'      — no redaction. Used for verified search crawlers under Flexible Sampling
+ *                 and for the member's own request.
+ *   'redacted'  — members-safe output: description truncated, articleBody absent, FAQ
+ *                 answers truncated. Google Rich Results still passes (description is
+ *                 truncated, not omitted).
+ */
+export type ArticleRenderMode = 'full' | 'redacted';
+export interface GenerateArticleJsonLdOptions {
+    mode?: ArticleRenderMode;
+}
+export declare function generateArticleJsonLd(item: ContentItem, options: ResolvedSeoOptions, renderOptions?: GenerateArticleJsonLdOptions): JsonLdObject;
 //# sourceMappingURL=article.d.ts.map

package/dist/utils/json-ld/article.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"article.d.ts","sourceRoot":"","sources":["../../../src/utils/json-ld/article.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAG/D,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,kBAAkB,GACzB,YAAY,CAiEd"}
+{"version":3,"file":"article.d.ts","sourceRoot":"","sources":["../../../src/utils/json-ld/article.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAE/D;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,UAAU,CAAA;AAInD,MAAM,WAAW,4BAA4B;IAC5C,IAAI,CAAC,EAAE,iBAAiB,CAAA;CACxB;AAED,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,kBAAkB,EAC3B,aAAa,GAAE,4BAAiC,GAC9C,YAAY,CAkFd"}

package/dist/utils/json-ld/article.js

@@ -1,16 +1,23 @@
-import { buildDiscoverImageUrls } from '../discover.js';
-export function generateArticleJsonLd(item, options) {
+const MAX_REDACTED_DESCRIPTION_CHARS = 160;
+export function generateArticleJsonLd(item, options, renderOptions = {}) {
     const { organization, schemaType, audioNarration } = options;
+    const mode = renderOptions.mode ?? 'full';
+    const isMemberItem = item.access === 'members';
+    const applyRedaction = mode === 'redacted' && isMemberItem;
     const authors = (item.authors ?? []).map((author) => {
         const person = { '@type': 'Person', name: author.name };
         if (author.url)
             person.url = author.url;
         if (author.jobTitle)
             person.jobTitle = author.jobTitle;
+        if (author.knowsAbout?.length)
+            person.knowsAbout = author.knowsAbout;
         if (author.sameAs?.length)
             person.sameAs = author.sameAs;
         return person;
     });
+    // Derive isAccessibleForFree: explicit field wins, otherwise derive from access.
+    const isAccessibleForFree = item.isAccessibleForFree ?? item.access !== 'members';
     const result = {
         '@context': 'https://schema.org',
         '@type': schemaType,
@@ -29,21 +36,30 @@ export function generateArticleJsonLd(item, options) {
             },
         },
         author: authors,
-        isAccessibleForFree: item.isAccessibleForFree ?? true,
+        // Google requires the string form 'True'/'False' for Rich Results when paywall markup is emitted.
+        // See https://developers.google.com/search/docs/appearance/structured-data/paywalled-content
+        isAccessibleForFree: isAccessibleForFree ? 'True' : 'False',
     };
     if (item.image) {
-        result.image = buildDiscoverImageUrls(item.image, options.site);
+        // Consumers compose @growth-labs/media if they need multi-aspect-ratio variants;
+        // this utility takes whatever URL(s) the consumer supplied in the ContentItem.
+        result.image = Array.isArray(item.image) ? item.image : [item.image];
+    }
+    if (item.description) {
+        result.description = applyRedaction
+            ? truncateDescription(item.description, MAX_REDACTED_DESCRIPTION_CHARS)
+            : item.description;
     }
-    if (item.description)
-        result.description = item.description;
     if (item.datePublished)
         result.datePublished = item.datePublished;
     if (item.dateModified)
         result.dateModified = item.dateModified;
-    if (item.isAccessibleForFree === false && item.paywallCssSelector) {
+    // hasPart paywall marker — emitted whenever the item is gated (either via explicit
+    // isAccessibleForFree: false or via access: 'members').
+    if (!isAccessibleForFree && item.paywallCssSelector) {
         result.hasPart = {
             '@type': 'WebPageElement',
-            isAccessibleForFree: false,
+            isAccessibleForFree: 'False',
             cssSelector: item.paywallCssSelector,
         };
     }
@@ -63,4 +79,17 @@ export function generateArticleJsonLd(item, options) {
     }
     return result;
 }
+/**
+ * Truncate a description to `maxChars` graphemes, on a word boundary if possible,
+ * with ellipsis suffix. Returns the original if shorter than maxChars.
+ */
+function truncateDescription(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const targetLen = maxChars - 1; // reserve for ellipsis
+    const sliced = text.slice(0, targetLen);
+    const lastSpace = sliced.lastIndexOf(' ');
+    const cutAt = lastSpace > targetLen * 0.6 ? lastSpace : targetLen;
+    return `${sliced.slice(0, cutAt).trimEnd()}…`;
+}
 //# sourceMappingURL=article.js.map

package/dist/utils/json-ld/article.js.map

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

package/dist/utils/llms-full.d.ts

@@ -0,0 +1,29 @@
+import type { ContentItem } from '../types.js';
+export interface GenerateLlmsFullOptions {
+    items: ContentItem[];
+    siteName: string;
+    contentMarkdown?: (item: ContentItem) => string | undefined;
+    maxBytes?: number;
+}
+/**
+ * Generate `/llms-full.txt` — a bulk public corpus dump for LLM retrievers.
+ *
+ * Structure:
+ *   # <siteName>
+ *
+ *   ## <article title>
+ *   URL: <canonical>
+ *
+ *   <markdown body>
+ *
+ *   ---
+ *
+ *   [next article...]
+ *
+ * Rules:
+ *   - Members items excluded UNCONDITIONALLY.
+ *   - Size cap honored; on-boundary truncation with a note.
+ *   - Deterministic order: items passed in, order preserved.
+ */
+export declare function generateLlmsFull({ items, siteName, contentMarkdown, maxBytes, }: GenerateLlmsFullOptions): string;
+//# sourceMappingURL=llms-full.d.ts.map

package/dist/utils/llms-full.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-full.d.ts","sourceRoot":"","sources":["../../src/utils/llms-full.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAG9C,MAAM,WAAW,uBAAuB;IACvC,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;IAGhB,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,GAAG,SAAS,CAAA;IAI3D,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAID;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,EAChC,KAAK,EACL,QAAQ,EACR,eAAe,EACf,QAA4B,GAC5B,EAAE,uBAAuB,GAAG,MAAM,CA4BlC"}

package/dist/utils/llms-full.js

@@ -0,0 +1,67 @@
+import { forLlmsFull } from './content-filter.js';
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+/**
+ * Generate `/llms-full.txt` — a bulk public corpus dump for LLM retrievers.
+ *
+ * Structure:
+ *   # <siteName>
+ *
+ *   ## <article title>
+ *   URL: <canonical>
+ *
+ *   <markdown body>
+ *
+ *   ---
+ *
+ *   [next article...]
+ *
+ * Rules:
+ *   - Members items excluded UNCONDITIONALLY.
+ *   - Size cap honored; on-boundary truncation with a note.
+ *   - Deterministic order: items passed in, order preserved.
+ */
+export function generateLlmsFull({ items, siteName, contentMarkdown, maxBytes = DEFAULT_MAX_BYTES, }) {
+    const filtered = forLlmsFull(items);
+    const encoder = new TextEncoder();
+    const header = `# ${siteName}\n\n`;
+    let byteCount = encoder.encode(header).length;
+    const parts = [header];
+    let truncated = false;
+    for (const item of filtered) {
+        const body = contentMarkdown?.(item);
+        const chunk = buildChunk(item, body);
+        const chunkBytes = encoder.encode(chunk).length;
+        if (byteCount + chunkBytes > maxBytes) {
+            truncated = true;
+            break;
+        }
+        parts.push(chunk);
+        byteCount += chunkBytes;
+    }
+    if (truncated) {
+        parts.push('\n\n---\n\n> Corpus truncated at configured size cap. See /sitemap-markdown.xml for the full twin URL list.\n');
+    }
+    return parts.join('');
+}
+function buildChunk(item, body) {
+    const lines = [];
+    lines.push(`## ${item.title}`);
+    lines.push('');
+    lines.push(`URL: ${item.url}`);
+    if (item.datePublished)
+        lines.push(`Published: ${item.datePublished}`);
+    if (item.dateModified)
+        lines.push(`Modified: ${item.dateModified}`);
+    lines.push('');
+    if (body) {
+        lines.push(body.trim());
+    }
+    else if (item.description) {
+        lines.push(item.description.trim());
+    }
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=llms-full.js.map

package/dist/utils/llms-full.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-full.js","sourceRoot":"","sources":["../../src/utils/llms-full.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAcjD,MAAM,iBAAiB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAChC,KAAK,EACL,QAAQ,EACR,eAAe,EACf,QAAQ,GAAG,iBAAiB,GACH;IACzB,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,CAAA;IACnC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAA;IAEjC,MAAM,MAAM,GAAG,KAAK,QAAQ,MAAM,CAAA;IAClC,IAAI,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,CAAA;IAC7C,MAAM,KAAK,GAAa,CAAC,MAAM,CAAC,CAAA;IAChC,IAAI,SAAS,GAAG,KAAK,CAAA;IAErB,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC7B,MAAM,IAAI,GAAG,eAAe,EAAE,CAAC,IAAI,CAAC,CAAA;QACpC,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QACpC,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAA;QAC/C,IAAI,SAAS,GAAG,UAAU,GAAG,QAAQ,EAAE,CAAC;YACvC,SAAS,GAAG,IAAI,CAAA;YAChB,MAAK;QACN,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACjB,SAAS,IAAI,UAAU,CAAA;IACxB,CAAC;IAED,IAAI,SAAS,EAAE,CAAC;QACf,KAAK,CAAC,IAAI,CACT,+GAA+G,CAC/G,CAAA;IACF,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;AACtB,CAAC;AAED,SAAS,UAAU,CAAC,IAAiB,EAAE,IAAwB;IAC9D,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,KAAK,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;IAC9B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACd,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;IAC9B,IAAI,IAAI,CAAC,aAAa;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,aAAa,EAAE,CAAC,CAAA;IACtE,IAAI,IAAI,CAAC,YAAY;QAAE,KAAK,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,YAAY,EAAE,CAAC,CAAA;IACnE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACd,IAAI,IAAI,EAAE,CAAC;QACV,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;IACxB,CAAC;SAAM,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAA;IACpC,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACd,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACjB,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACd,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAA;AAC/B,CAAC"}

package/dist/utils/meta.d.ts

@@ -3,5 +3,8 @@ import type { CanonicalLink, ContentItem, MetaTag } from '../types.js';
 export type OgVariant = 'article' | 'product' | 'website';
 export declare function applyTrailingSlash(url: string, policy: string): string;
 export declare function generateCanonical(url: string, options: ResolvedSeoOptions): CanonicalLink;
-export declare function generateMeta(item: ContentItem, variant: OgVariant, options: ResolvedSeoOptions): MetaTag[];
+export interface GenerateMetaOptions {
+    flexibleSamplingActive?: boolean;
+}
+export declare function generateMeta(item: ContentItem, variant: OgVariant, options: ResolvedSeoOptions, metaOptions?: GenerateMetaOptions): MetaTag[];
 //# sourceMappingURL=meta.d.ts.map

package/dist/utils/meta.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/utils/meta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAEtE,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;AAEzD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAmCtE;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,aAAa,CAKzF;AAED,wBAAgB,YAAY,CAC3B,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,SAAS,EAClB,OAAO,EAAE,kBAAkB,GACzB,OAAO,EAAE,CA+FX"}
+{"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/utils/meta.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAEtE,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;AAEzD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAmCtE;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,aAAa,CAKzF;AAED,MAAM,WAAW,mBAAmB;IAKnC,sBAAsB,CAAC,EAAE,OAAO,CAAA;CAChC;AAED,wBAAgB,YAAY,CAC3B,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,SAAS,EAClB,OAAO,EAAE,kBAAkB,EAC3B,WAAW,GAAE,mBAAwB,GACnC,OAAO,EAAE,CAyHX"}

package/dist/utils/meta.js

@@ -42,11 +42,12 @@ export function generateCanonical(url, options) {
         href: applyTrailingSlash(url, options.trailingSlash),
     };
 }
-export function generateMeta(item, variant, options) {
+export function generateMeta(item, variant, options, metaOptions = {}) {
     const tags = [];
     const { defaults, organization } = options;
     const canonicalUrl = applyTrailingSlash(item.url, options.trailingSlash);
-    const image = item.image ?? defaults.defaultImage ?? '';
+    const firstImage = Array.isArray(item.image) ? item.image[0] : item.image;
+    const image = firstImage ?? defaults.defaultImage ?? '';
     const ogType = variant === 'article' ? 'article' : variant === 'product' ? 'og:product' : 'website';
     // og:type
     tags.push({ property: 'og:type', content: ogType });
@@ -93,6 +94,28 @@ export function generateMeta(item, variant, options) {
     }
     // robots
     tags.push({ name: 'robots', content: 'max-image-preview:large' });
+    // Flexible Sampling: prevent Google from serving the premium body from cache.
+    if (metaOptions.flexibleSamplingActive) {
+        tags.push({ name: 'googlebot', content: 'noarchive' });
+    }
+    // Apple News meta tags.
+    // `apple-news-publishable` is opt-in for the channel to pick up the article.
+    // Resolved at item level: `appleNewsPublishable: 'no'` overrides the channel default.
+    // Channel default comes from options.appleNews.defaultPublishable.
+    if (options.appleNews?.enabled) {
+        const channelDefault = options.appleNews.defaultPublishable;
+        const effective = item.appleNewsPublishable ?? channelDefault;
+        if (effective === 'yes' && item.access !== 'members') {
+            tags.push({ name: 'apple-news-publishable', content: 'yes' });
+        }
+        if (item.appleNewsId) {
+            tags.push({ name: 'apple-news-id', content: item.appleNewsId });
+        }
+    }
+    // news_keywords — read by both Google News and Apple News.
+    if (item.newsKeywords?.length) {
+        tags.push({ name: 'news_keywords', content: item.newsKeywords.join(', ') });
+    }
     // Article-specific
     if (variant === 'article') {
         if (item.datePublished) {

package/dist/utils/meta.js.map

@@ -1 +1 @@
-{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/utils/meta.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/utils/meta.ts"],"names":[],"mappings":"AAKA,MAAM,UAAU,kBAAkB,CAAC,GAAW,EAAE,MAAc;IAC7D,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;QACxB,+CAA+C;QAC/C,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;YACtC,IAAI,CAAC;gBACJ,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;gBAC3B,IAAI,MAAM,CAAC,QAAQ,KAAK,GAAG,EAAE,CAAC;oBAC7B,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;oBACrD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAA;gBACzB,CAAC;gBACD,OAAO,GAAG,CAAA;YACX,CAAC;YAAC,MAAM,CAAC;gBACR,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;YACpE,CAAC;QACF,CAAC;QACD,OAAO,GAAG,CAAA;IACX,CAAC;IACD,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC;gBACJ,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAA;gBAC3B,oDAAoD;gBACpD,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;oBACpC,MAAM,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;oBACtD,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAA;gBACzB,CAAC;gBACD,OAAO,GAAG,CAAA;YACX,CAAC;YAAC,MAAM,CAAC;gBACR,OAAO,GAAG,GAAG,GAAG,CAAA;YACjB,CAAC;QACF,CAAC;QACD,OAAO,GAAG,CAAA;IACX,CAAC;IACD,SAAS;IACT,OAAO,GAAG,CAAA;AACX,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,OAA2B;IACzE,OAAO;QACN,GAAG,EAAE,WAAW;QAChB,IAAI,EAAE,kBAAkB,CAAC,GAAG,EAAE,OAAO,CAAC,aAAa,CAAC;KACpD,CAAA;AACF,CAAC;AAUD,MAAM,UAAU,YAAY,CAC3B,IAAiB,EACjB,OAAkB,EAClB,OAA2B,EAC3B,cAAmC,EAAE;IAErC,MAAM,IAAI,GAAc,EAAE,CAAA;IAC1B,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,CAAA;IAC1C,MAAM,YAAY,GAAG,kBAAkB,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC,aAAa,CAAC,CAAA;IACxE,MAAM,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAA;IACzE,MAAM,KAAK,GAAG,UAAU,IAAI,QAAQ,CAAC,YAAY,IAAI,EAAE,CAAA;IAEvD,MAAM,MAAM,GACX,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAA;IAErF,UAAU;IACV,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAA;IAEnD,WAAW;IACX,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;IAExD,iBAAiB;IACjB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAA;IACrE,CAAC;IAED,SAAS;IACT,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAA;IAExD,WAAW;IACX,IAAI,KAAK,EAAE,CAAC;QACX,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;QACnD,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAA;QAC1D,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,iBAAiB,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;IAC3D,CAAC;IAED,eAAe;IACf,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,YAAY,CAAC,IAAI,EAAE,CAAC,CAAA;IAEnE,YAAY;IACZ,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAA;IAC7C,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAA;IAErD,sBAAsB;IACtB,IAAI,IAAI,CAAC,gBAAgB,EAAE,MAAM,EAAE,CAAC;QACnC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,gBAAgB,EAAE,CAAC;YACzC,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,qBAAqB,EAAE,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAA;QAClE,CAAC;IACF,CAAC;IAED,eAAe;IACf,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,QAAQ,CAAC,eAAe,EAAE,CAAC,CAAA;IAEtE,eAAe;IACf,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;QAC1B,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAA;IACnE,CAAC;IAED,gBAAgB;IAChB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;IAEzD,sBAAsB;IACtB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAA;IACtE,CAAC;IAED,gBAAgB;IAChB,IAAI,KAAK,EAAE,CAAC;QACX,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;IACrD,CAAC;IAED,SAAS;IACT,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAC,CAAA;IAEjE,8EAA8E;IAC9E,IAAI,WAAW,CAAC,sBAAsB,EAAE,CAAC;QACxC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAA;IACvD,CAAC;IAED,wBAAwB;IACxB,6EAA6E;IAC7E,sFAAsF;IACtF,mEAAmE;IACnE,IAAI,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,CAAC;QAChC,MAAM,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC,kBAAkB,CAAA;QAC3D,MAAM,SAAS,GAAG,IAAI,CAAC,oBAAoB,IAAI,cAAc,CAAA;QAC7D,IAAI,SAAS,KAAK,KAAK,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACtD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAA;QAC9D,CAAC;QACD,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAA;QAChE,CAAC;IACF,CAAC;IAED,2DAA2D;IAC3D,IAAI,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IAC5E,CAAC;IAED,mBAAmB;IACnB,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACxB,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,wBAAwB,EAAE,OAAO,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAA;QAC/E,CAAC;QACD,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,uBAAuB,EAAE,OAAO,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAA;QAC7E,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;YAC1B,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACnC,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;YAC9E,CAAC;QACF,CAAC;IACF,CAAC;IAED,mBAAmB;IACnB,IAAI,OAAO,KAAK,SAAS,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QAC3C,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAA;QACtB,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,sBAAsB,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;QACzE,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,wBAAwB,EAAE,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAA;QACtE,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,sBAAsB,EAAE,OAAO,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,CAAA;QACxE,IAAI,CAAC,CAAC,KAAK,EAAE,CAAC;YACb,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAA;QAC3D,CAAC;IACF,CAAC;IAED,OAAO,IAAI,CAAA;AACZ,CAAC"}

package/dist/utils/sitemap-markdown.d.ts

@@ -0,0 +1,24 @@
+import type { ContentItem } from '../types.js';
+export interface MarkdownSitemapEntry {
+    primaryTwinUrl: string;
+    lastmod?: string;
+    freshLayerLastModified?: string;
+}
+export interface GenerateMarkdownSitemapOptions {
+    items: ContentItem[];
+    twinUrl?: (articleUrl: string) => string;
+    freshLayerLastmod?: Map<string, string>;
+}
+/**
+ * Generate `/sitemap-markdown.xml` — the AEO twin URL sitemap.
+ *
+ * Google discovers URLs via crawlable links and sitemaps, not MIME-probing. This
+ * sitemap lists every emitted `.md` twin URL so the markdown corpus is discoverable
+ * the same way HTML pages are.
+ *
+ * Filtering rules (centralized in content-filter.forMarkdownSitemap):
+ *   - Members items excluded unconditionally (no .md twin exists for them).
+ *   - Public items with `includeInSitemap: false` excluded.
+ */
+export declare function generateMarkdownSitemap({ items, twinUrl, freshLayerLastmod, }: GenerateMarkdownSitemapOptions): string;
+//# sourceMappingURL=sitemap-markdown.d.ts.map

package/dist/utils/sitemap-markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap-markdown.d.ts","sourceRoot":"","sources":["../../src/utils/sitemap-markdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAwB9C,MAAM,WAAW,oBAAoB;IACpC,cAAc,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAGhB,sBAAsB,CAAC,EAAE,MAAM,CAAA;CAC/B;AAED,MAAM,WAAW,8BAA8B;IAC9C,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAA;IAGxC,iBAAiB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACvC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,EACvC,KAAK,EACL,OAAwB,EACxB,iBAAiB,GACjB,EAAE,8BAA8B,GAAG,MAAM,CAkBzC"}

package/dist/utils/sitemap-markdown.js

@@ -0,0 +1,57 @@
+import { forMarkdownSitemap } from './content-filter.js';
+function escapeXml(str) {
+    return str
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/**
+ * Map an article URL to its primary markdown twin URL. Default appends `.md` to
+ * the URL, collapsing any trailing slash.
+ *
+ * Consumers can override via `aeoTwins.twinUrl` in config; when overridden, the
+ * same function drives both twin emission and sitemap discovery URL.
+ */
+function defaultTwinUrl(articleUrl) {
+    const trimmed = articleUrl.replace(/\/+$/, '');
+    return `${trimmed}.md`;
+}
+/**
+ * Generate `/sitemap-markdown.xml` — the AEO twin URL sitemap.
+ *
+ * Google discovers URLs via crawlable links and sitemaps, not MIME-probing. This
+ * sitemap lists every emitted `.md` twin URL so the markdown corpus is discoverable
+ * the same way HTML pages are.
+ *
+ * Filtering rules (centralized in content-filter.forMarkdownSitemap):
+ *   - Members items excluded unconditionally (no .md twin exists for them).
+ *   - Public items with `includeInSitemap: false` excluded.
+ */
+export function generateMarkdownSitemap({ items, twinUrl = defaultTwinUrl, freshLayerLastmod, }) {
+    const filtered = forMarkdownSitemap(items);
+    const entries = filtered
+        .map((item) => {
+        const url = twinUrl(item.url);
+        const freshMod = freshLayerLastmod?.get(item.url);
+        const buildMod = item.dateModified ?? item.datePublished ?? '';
+        // Pick the most recent of build-time and fresh-layer lastmod.
+        const lastmod = pickLatest(freshMod, buildMod);
+        const lastmodTag = lastmod ? `\n    <lastmod>${escapeXml(lastmod)}</lastmod>` : '';
+        return `  <url>\n    <loc>${escapeXml(url)}</loc>${lastmodTag}\n  </url>`;
+    })
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${entries}
+</urlset>`;
+}
+function pickLatest(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return new Date(a).getTime() >= new Date(b).getTime() ? a : b;
+}
+//# sourceMappingURL=sitemap-markdown.js.map

package/dist/utils/sitemap-markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap-markdown.js","sourceRoot":"","sources":["../../src/utils/sitemap-markdown.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAExD,SAAS,SAAS,CAAC,GAAW;IAC7B,OAAO,GAAG;SACR,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC;SACtB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC;SACrB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;AAC1B,CAAC;AAED;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,UAAkB;IACzC,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;IAC9C,OAAO,GAAG,OAAO,KAAK,CAAA;AACvB,CAAC;AAkBD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,uBAAuB,CAAC,EACvC,KAAK,EACL,OAAO,GAAG,cAAc,EACxB,iBAAiB,GACe;IAChC,MAAM,QAAQ,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAA;IAC1C,MAAM,OAAO,GAAG,QAAQ;SACtB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACb,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAC7B,MAAM,QAAQ,GAAG,iBAAiB,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACjD,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,aAAa,IAAI,EAAE,CAAA;QAC9D,8DAA8D;QAC9D,MAAM,OAAO,GAAG,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAA;QAC9C,MAAM,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,kBAAkB,SAAS,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAA;QAClF,OAAO,qBAAqB,SAAS,CAAC,GAAG,CAAC,SAAS,UAAU,YAAY,CAAA;IAC1E,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAA;IAEZ,OAAO;;EAEN,OAAO;UACC,CAAA;AACV,CAAC;AAED,SAAS,UAAU,CAAC,CAAqB,EAAE,CAAqB;IAC/D,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAA;IAChB,IAAI,CAAC,CAAC;QAAE,OAAO,CAAC,CAAA;IAChB,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAC9D,CAAC"}

package/dist/utils/staleness.d.ts

@@ -0,0 +1,27 @@
+import type { ContentItem } from '../types.js';
+/**
+ * Compute a SHA-256 content hash for staleness validation. Uses `crypto.subtle`
+ * so the same implementation runs in Node (build-time) and Workers (runtime).
+ * Never node:crypto.
+ *
+ * The hash input is deterministic: item title + description + rendered body.
+ * Order matters: changes to any field produce a new hash. Whitespace-insensitive
+ * if the consumer normalizes before calling.
+ */
+export declare function computeContentHash(item: Pick<ContentItem, 'title' | 'description'>, renderedBody: string): Promise<string>;
+export interface StalenessDriftRecord {
+    url: string;
+    expectedHash: string;
+    actualHash: string;
+}
+/**
+ * Compare expected-vs-actual content hashes across a batch of items. Used by the
+ * build-time validator to detect drift between two `contentProvider` calls made
+ * during the same build (rare but possible when provider pulls from a mutating
+ * source).
+ *
+ * Returns the list of items whose hash differs. Callers log these as warnings;
+ * the build does NOT fail on drift (spec 1403: "does not fail the build").
+ */
+export declare function checkStaleness(items: ContentItem[], expectedHashes: Map<string, string>, renderBody: (item: ContentItem) => string | Promise<string>): Promise<StalenessDriftRecord[]>;
+//# sourceMappingURL=staleness.d.ts.map

package/dist/utils/staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.d.ts","sourceRoot":"","sources":["../../src/utils/staleness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,aAAa,CAAC,EAChD,YAAY,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CAKjB;AAUD,MAAM,WAAW,oBAAoB;IACpC,GAAG,EAAE,MAAM,CAAA;IACX,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CACnC,KAAK,EAAE,WAAW,EAAE,EACpB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,UAAU,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GACzD,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAYjC"}

package/dist/utils/staleness.js

@@ -0,0 +1,46 @@
+/**
+ * Compute a SHA-256 content hash for staleness validation. Uses `crypto.subtle`
+ * so the same implementation runs in Node (build-time) and Workers (runtime).
+ * Never node:crypto.
+ *
+ * The hash input is deterministic: item title + description + rendered body.
+ * Order matters: changes to any field produce a new hash. Whitespace-insensitive
+ * if the consumer normalizes before calling.
+ */
+export async function computeContentHash(item, renderedBody) {
+    const input = [item.title, item.description ?? '', renderedBody].join('\u0001');
+    const bytes = new TextEncoder().encode(input);
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return toHex(new Uint8Array(digest));
+}
+function toHex(bytes) {
+    let out = '';
+    for (const b of bytes) {
+        out += b.toString(16).padStart(2, '0');
+    }
+    return out;
+}
+/**
+ * Compare expected-vs-actual content hashes across a batch of items. Used by the
+ * build-time validator to detect drift between two `contentProvider` calls made
+ * during the same build (rare but possible when provider pulls from a mutating
+ * source).
+ *
+ * Returns the list of items whose hash differs. Callers log these as warnings;
+ * the build does NOT fail on drift (spec 1403: "does not fail the build").
+ */
+export async function checkStaleness(items, expectedHashes, renderBody) {
+    const drift = [];
+    for (const item of items) {
+        const expected = expectedHashes.get(item.url);
+        if (!expected)
+            continue;
+        const body = await renderBody(item);
+        const actual = await computeContentHash(item, body);
+        if (actual !== expected) {
+            drift.push({ url: item.url, expectedHash: expected, actualHash: actual });
+        }
+    }
+    return drift;
+}
+//# sourceMappingURL=staleness.js.map

package/dist/utils/staleness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"staleness.js","sourceRoot":"","sources":["../../src/utils/staleness.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACvC,IAAgD,EAChD,YAAoB;IAEpB,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE,EAAE,YAAY,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC/E,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC7C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,CAAA;IAC3D,OAAO,KAAK,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAA;AACrC,CAAC;AAED,SAAS,KAAK,CAAC,KAAiB;IAC/B,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACvB,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IACvC,CAAC;IACD,OAAO,GAAG,CAAA;AACX,CAAC;AAQD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,KAAoB,EACpB,cAAmC,EACnC,UAA2D;IAE3D,MAAM,KAAK,GAA2B,EAAE,CAAA;IACxC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAC7C,IAAI,CAAC,QAAQ;YAAE,SAAQ;QACvB,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,CAAA;QACnC,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QACnD,IAAI,MAAM,KAAK,QAAQ,EAAE,CAAC;YACzB,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAA;QAC1E,CAAC;IACF,CAAC;IACD,OAAO,KAAK,CAAA;AACb,CAAC"}

package/dist/utils/validation.d.ts

@@ -15,4 +15,45 @@ export declare function validateJsonLd(jsonLd: Record<string, unknown>): Validat
  * Validate an HTML string for common on-page SEO issues.
  */
 export declare function validatePage(html: string, options: PageValidationOptions): ValidationResult;
+import type { ContentItem } from '../types.js';
+export interface HreflangReciprocityIssue {
+    url: string;
+    missingReciprocal: {
+        from: string;
+        lang: string;
+        expectedBackReference: string;
+    };
+}
+/**
+ * Verify that every `alternateLocales` entry has a reciprocal entry on the
+ * target side. For search engines, missing reciprocals are a hard error — Google
+ * will ignore the hreflang annotations altogether.
+ *
+ * Runs in O(N^2) worst-case but N is bounded by the number of translated articles,
+ * not the entire catalog, so this is fine at build time.
+ *
+ * Returns the list of reciprocity violations. Callers log these as errors in the
+ * build-time validation hook.
+ */
+export declare function validateHreflangReciprocity(items: ContentItem[]): HreflangReciprocityIssue[];
+export interface PrerenderGuardIssue {
+    route: string;
+    access: 'members';
+    message: string;
+}
+/**
+ * Fails the build when a route whose ContentItem has `access: 'members'` is
+ * configured as `prerender: true`. This is the load-bearing check that makes
+ * Flexible Sampling + static mode the only known-bad combo. The consumer's
+ * Astro integration iterates the build manifest and calls this with the
+ * prerendered-route URL set crossed against contentProvider output.
+ *
+ * Spec lines 1389-1405.
+ *
+ * Returns an empty array on success; non-empty means the build MUST fail.
+ */
+export declare function validatePrerenderedGatedRoutes({ prerenderedUrls, items, }: {
+    prerenderedUrls: Set<string>;
+    items: ContentItem[];
+}): PrerenderGuardIssue[];
 //# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,MAAM,WAAW,qBAAqB;IACrC,cAAc,EAAE,MAAM,CAAA;IACtB,oBAAoB,EAAE,MAAM,CAAA;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,CAqEhF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,gBAAgB,CAqF3F"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,MAAM,WAAW,qBAAqB;IACrC,cAAc,EAAE,MAAM,CAAA;IACtB,oBAAoB,EAAE,MAAM,CAAA;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,CAqEhF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,gBAAgB,CAqF3F;AAID,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C,MAAM,WAAW,wBAAwB;IACxC,GAAG,EAAE,MAAM,CAAA;IACX,iBAAiB,EAAE;QAClB,IAAI,EAAE,MAAM,CAAA;QACZ,IAAI,EAAE,MAAM,CAAA;QACZ,qBAAqB,EAAE,MAAM,CAAA;KAC7B,CAAA;CACD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,wBAAwB,EAAE,CAkC5F;AAID,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,SAAS,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,8BAA8B,CAAC,EAC9C,eAAe,EACf,KAAK,GACL,EAAE;IACF,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;IAC5B,KAAK,EAAE,WAAW,EAAE,CAAA;CACpB,GAAG,mBAAmB,EAAE,CAmBxB"}

package/dist/utils/validation.js

@@ -138,4 +138,82 @@ export function validatePage(html, options) {
     }
     return { errors, warnings };
 }
+/**
+ * Verify that every `alternateLocales` entry has a reciprocal entry on the
+ * target side. For search engines, missing reciprocals are a hard error — Google
+ * will ignore the hreflang annotations altogether.
+ *
+ * Runs in O(N^2) worst-case but N is bounded by the number of translated articles,
+ * not the entire catalog, so this is fine at build time.
+ *
+ * Returns the list of reciprocity violations. Callers log these as errors in the
+ * build-time validation hook.
+ */
+export function validateHreflangReciprocity(items) {
+    const byUrl = new Map();
+    for (const item of items)
+        byUrl.set(item.url, item);
+    const issues = [];
+    for (const item of items) {
+        if (!item.alternateLocales || item.alternateLocales.length === 0)
+            continue;
+        for (const alt of item.alternateLocales) {
+            const altItem = byUrl.get(alt.url);
+            if (!altItem) {
+                issues.push({
+                    url: item.url,
+                    missingReciprocal: {
+                        from: alt.url,
+                        lang: alt.lang,
+                        expectedBackReference: item.url,
+                    },
+                });
+                continue;
+            }
+            const hasBackRef = altItem.alternateLocales?.some((a) => a.url === item.url);
+            if (!hasBackRef) {
+                issues.push({
+                    url: item.url,
+                    missingReciprocal: {
+                        from: alt.url,
+                        lang: alt.lang,
+                        expectedBackReference: item.url,
+                    },
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Fails the build when a route whose ContentItem has `access: 'members'` is
+ * configured as `prerender: true`. This is the load-bearing check that makes
+ * Flexible Sampling + static mode the only known-bad combo. The consumer's
+ * Astro integration iterates the build manifest and calls this with the
+ * prerendered-route URL set crossed against contentProvider output.
+ *
+ * Spec lines 1389-1405.
+ *
+ * Returns an empty array on success; non-empty means the build MUST fail.
+ */
+export function validatePrerenderedGatedRoutes({ prerenderedUrls, items, }) {
+    const issues = [];
+    for (const item of items) {
+        if (item.access !== 'members')
+            continue;
+        const path = new URL(item.url).pathname;
+        if (prerenderedUrls.has(path) || prerenderedUrls.has(`${path}/`)) {
+            issues.push({
+                route: path,
+                access: 'members',
+                message: `Route ${path} is prerendered but serves a members-gated item. ` +
+                    `Prerendered HTML is the same bytes for every requester — there is no ` +
+                    `way to serve a teaser to anonymous users and the full body to verified ` +
+                    `Googlebot from the same static file. Set export const prerender = false ` +
+                    `on this route, or mark this item access: 'public'.`,
+            });
+        }
+    }
+    return issues;
+}
 //# sourceMappingURL=validation.js.map