@cogenta/seo 0.1.0

package/dist/feeds.d.ts

@@ -0,0 +1,66 @@
+import { type IndexableOptions } from './indexable.js';
+import type { SeoResource, SeoSite } from './types.js';
+/**
+ * RSS 2.0 and Atom 1.0, from the same item list.
+ *
+ * Both are produced because both are still consumed: readers and podcast
+ * clients speak RSS, while Atom is the one with a specified date format and a
+ * real notion of entry identity. Generating one from the other at runtime would
+ * be cheaper and is exactly how feeds acquire subtly different content.
+ *
+ * Content is escaped, never wrapped in `CDATA`. `CDATA` looks like it removes
+ * the escaping problem and instead moves it: the sequence `]]>` inside an
+ * article — which appears in any post about XML — terminates the section early
+ * and corrupts the feed, with no visible symptom until a reader silently stops
+ * updating.
+ */
+export interface FeedItem {
+    readonly title: string;
+    readonly link: string;
+    /** Globally unique and permanent. The canonical URL, unless the entry moves. */
+    readonly id: string;
+    /** RFC 3339. Converted to RFC 822 for RSS. */
+    readonly updated: string;
+    readonly published?: string;
+    readonly summary?: string;
+    readonly authorName?: string;
+    readonly categories?: readonly string[];
+}
+export interface FeedInput {
+    readonly site: SeoSite;
+    readonly title?: string;
+    readonly description?: string;
+    /** Site-relative path this feed is served at, for the `self` link. */
+    readonly selfPath: string;
+    readonly language?: string;
+    readonly items: readonly FeedItem[];
+    /** Injected so a feed is byte-stable in tests. */
+    readonly updated?: string;
+}
+/**
+ * RFC 822 date, as RSS 2.0 requires.
+ *
+ * Hand-rolled rather than taken from `toUTCString`: that method emits `GMT`,
+ * and while RFC 822 allows the name, several validators and at least one large
+ * reader expect the `+0000` numeric offset. Building it also keeps the day and
+ * month names in English regardless of the server locale, which `toLocaleString`
+ * would not.
+ */
+export declare function toRfc822(value: string): string;
+export declare function renderRssFeed(input: FeedInput): string;
+export declare function renderAtomFeed(input: FeedInput): string;
+export interface FeedItemsOptions extends IndexableOptions {
+    /** Feeds are a recency list, not an archive. Defaults to 50. */
+    readonly limit?: number;
+    readonly summaryLength?: number;
+}
+/**
+ * Feed items for a set of resources, newest first.
+ *
+ * Drafts are removed by `indexableResources` before anything else happens. A
+ * feed is the one output that cannot be retracted: readers cache, and a digest
+ * mail forwards. So the filter is not an option here and there is no parameter
+ * to turn it off.
+ */
+export declare function feedItemsFor(site: SeoSite, resources: readonly SeoResource[], options?: FeedItemsOptions): readonly FeedItem[];
+//# sourceMappingURL=feeds.d.ts.map

package/dist/feeds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feeds.d.ts","sourceRoot":"","sources":["../src/feeds.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,gBAAgB,EAAsB,MAAM,gBAAgB,CAAA;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAItD;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACxC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAA;IACnC,kDAAkD;IAClD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAkBD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS9C;AAUD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAmDtD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAiDvD;AAED,MAAM,WAAW,gBAAiB,SAAQ,gBAAgB;IACxD,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AA2BD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,OAAO,GAAE,gBAAqB,GAC7B,SAAS,QAAQ,EAAE,CAuBrB"}

package/dist/feeds.js

@@ -0,0 +1,199 @@
+import { condense, extractRichText } from '@cogenta/schema';
+import { indexableResources } from './indexable.js';
+import { absoluteUrl, canonicalUrl } from './url.js';
+import { renderXmlDocument } from './xml.js';
+const RSS_DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const RSS_MONTHS = [
+    'Jan',
+    'Feb',
+    'Mar',
+    'Apr',
+    'May',
+    'Jun',
+    'Jul',
+    'Aug',
+    'Sep',
+    'Oct',
+    'Nov',
+    'Dec',
+];
+/**
+ * RFC 822 date, as RSS 2.0 requires.
+ *
+ * Hand-rolled rather than taken from `toUTCString`: that method emits `GMT`,
+ * and while RFC 822 allows the name, several validators and at least one large
+ * reader expect the `+0000` numeric offset. Building it also keeps the day and
+ * month names in English regardless of the server locale, which `toLocaleString`
+ * would not.
+ */
+export function toRfc822(value) {
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return value;
+    const day = RSS_DAYS[date.getUTCDay()] ?? 'Sun';
+    const month = RSS_MONTHS[date.getUTCMonth()] ?? 'Jan';
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${day}, ${pad(date.getUTCDate())} ${month} ${date.getUTCFullYear()} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())} +0000`;
+}
+function newestUpdate(items, fallback) {
+    let newest = fallback;
+    for (const item of items) {
+        if (newest === undefined || item.updated > newest)
+            newest = item.updated;
+    }
+    return newest ?? new Date(0).toISOString();
+}
+export function renderRssFeed(input) {
+    const { site, items } = input;
+    const selfUrl = absoluteUrl(site, input.selfPath);
+    const channel = [
+        { name: 'title', text: input.title ?? site.name },
+        { name: 'link', text: absoluteUrl(site, '/') },
+        { name: 'description', text: input.description ?? site.description ?? site.name },
+        { name: 'language', text: input.language ?? site.defaultLocale },
+        { name: 'lastBuildDate', text: toRfc822(newestUpdate(items, input.updated)) },
+        // The self link is an Atom element inside RSS. It is not decoration: it is
+        // how a reader that has been redirected knows the feed's real address, and
+        // how the feed validators identify duplicates.
+        {
+            name: 'atom:link',
+            attributes: { href: selfUrl, rel: 'self', type: 'application/rss+xml' },
+        },
+        { name: 'generator', text: 'Cogenta' },
+    ];
+    for (const item of items) {
+        const children = [
+            { name: 'title', text: item.title },
+            { name: 'link', text: item.link },
+            // `isPermaLink="true"` would tell a reader the guid is a fetchable URL.
+            // It usually is, but a moved entry keeps its id and stops being one, so
+            // the safe declaration is the one that stays true.
+            { name: 'guid', attributes: { isPermaLink: 'false' }, text: item.id },
+            { name: 'pubDate', text: toRfc822(item.published ?? item.updated) },
+        ];
+        if (item.summary !== undefined)
+            children.push({ name: 'description', text: item.summary });
+        if (item.authorName !== undefined) {
+            // RSS `author` is specified as an email address; a bare name there fails
+            // validation. `dc:creator` is the element every reader actually displays.
+            children.push({ name: 'dc:creator', text: item.authorName });
+        }
+        for (const category of item.categories ?? []) {
+            children.push({ name: 'category', text: category });
+        }
+        channel.push({ name: 'item', children });
+    }
+    return renderXmlDocument({
+        name: 'rss',
+        attributes: {
+            version: '2.0',
+            'xmlns:atom': 'http://www.w3.org/2005/Atom',
+            'xmlns:dc': 'http://purl.org/dc/elements/1.1/',
+        },
+        children: [{ name: 'channel', children: channel }],
+    });
+}
+export function renderAtomFeed(input) {
+    const { site, items } = input;
+    const selfUrl = absoluteUrl(site, input.selfPath);
+    const children = [
+        { name: 'title', text: input.title ?? site.name },
+        // The feed's own id must be a permanent IRI, and must not change when the
+        // feed moves — hence the site root rather than the feed URL.
+        { name: 'id', text: absoluteUrl(site, '/') },
+        { name: 'updated', text: newestUpdate(items, input.updated) },
+        { name: 'link', attributes: { rel: 'self', type: 'application/atom+xml', href: selfUrl } },
+        {
+            name: 'link',
+            attributes: { rel: 'alternate', type: 'text/html', href: absoluteUrl(site, '/') },
+        },
+        { name: 'generator', text: 'Cogenta' },
+    ];
+    if (input.description !== undefined || site.description !== undefined) {
+        children.push({ name: 'subtitle', text: input.description ?? site.description ?? '' });
+    }
+    for (const item of items) {
+        const entry = [
+            { name: 'title', text: item.title },
+            { name: 'id', text: item.id },
+            { name: 'updated', text: item.updated },
+            { name: 'link', attributes: { rel: 'alternate', type: 'text/html', href: item.link } },
+        ];
+        if (item.published !== undefined)
+            entry.push({ name: 'published', text: item.published });
+        if (item.summary !== undefined) {
+            entry.push({ name: 'summary', attributes: { type: 'text' }, text: item.summary });
+        }
+        if (item.authorName !== undefined) {
+            entry.push({ name: 'author', children: [{ name: 'name', text: item.authorName }] });
+        }
+        for (const category of item.categories ?? []) {
+            entry.push({ name: 'category', attributes: { term: category } });
+        }
+        children.push({ name: 'entry', children: entry });
+    }
+    return renderXmlDocument({
+        name: 'feed',
+        attributes: {
+            xmlns: 'http://www.w3.org/2005/Atom',
+            'xml:lang': input.language ?? site.defaultLocale,
+        },
+        children,
+    });
+}
+const DEFAULT_FEED_LIMIT = 50;
+const DEFAULT_SUMMARY_LENGTH = 400;
+const SUMMARY_FIELDS = ['excerpt', 'description', 'summary', 'subtitle', 'teaser'];
+const TITLE_FIELDS = ['title', 'name', 'label', 'heading'];
+function pick(resource, candidates) {
+    for (const candidate of candidates) {
+        if (resource.collection.fields[candidate] === undefined)
+            continue;
+        const value = resource.entry.values[candidate];
+        if (typeof value === 'string' && value.trim().length > 0)
+            return condense(value);
+    }
+    return undefined;
+}
+function bodySummary(resource, limit) {
+    for (const [name, field] of Object.entries(resource.collection.fields)) {
+        if (field.kind !== 'richText')
+            continue;
+        const text = extractRichText(resource.entry.values[name]);
+        if (text.length === 0)
+            continue;
+        return text.length > limit ? `${text.slice(0, limit).trimEnd()}…` : text;
+    }
+    return undefined;
+}
+/**
+ * Feed items for a set of resources, newest first.
+ *
+ * Drafts are removed by `indexableResources` before anything else happens. A
+ * feed is the one output that cannot be retracted: readers cache, and a digest
+ * mail forwards. So the filter is not an option here and there is no parameter
+ * to turn it off.
+ */
+export function feedItemsFor(site, resources, options = {}) {
+    const summaryLength = options.summaryLength ?? DEFAULT_SUMMARY_LENGTH;
+    const published = indexableResources(site, resources, options);
+    const items = [];
+    for (const resource of published) {
+        const link = canonicalUrl(site, resource);
+        if (link === null)
+            continue;
+        const summary = pick(resource, SUMMARY_FIELDS) ?? bodySummary(resource, summaryLength);
+        items.push({
+            title: pick(resource, TITLE_FIELDS) ?? site.name,
+            link,
+            id: link,
+            updated: resource.entry.updatedAt,
+            ...(resource.entry.publishedAt === null ? {} : { published: resource.entry.publishedAt }),
+            ...(summary === undefined ? {} : { summary }),
+        });
+    }
+    return items
+        .sort((a, b) => (b.published ?? b.updated).localeCompare(a.published ?? a.updated))
+        .slice(0, options.limit ?? DEFAULT_FEED_LIMIT);
+}
+//# sourceMappingURL=feeds.js.map

package/dist/feeds.js.map

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

package/dist/hreflang.d.ts

@@ -0,0 +1,63 @@
+import { type IndexableOptions } from './indexable.js';
+import type { SeoResource, SeoSite } from './types.js';
+/**
+ * `hreflang`, derived from the translation family (ADR-0014).
+ *
+ * The model is one entry per language, translations pointing at their source
+ * through `translationOf`. The set of entries sharing a source is the family,
+ * and the family *is* the annotation: contract A says so explicitly, so nothing
+ * here reads a per-field translation or a locale suffix.
+ *
+ * ## Why reciprocity is a shape, not a check
+ *
+ * Google discards a whole `hreflang` cluster the moment one page fails to point
+ * back. The usual way to get this wrong is to compute alternates per page —
+ * "what are the other languages of *this* entry" — because then each page owns
+ * its own answer and the answers drift the instant one of them is filtered
+ * differently.
+ *
+ * So the alternate list is computed **once per family** and handed unchanged to
+ * every member, self included. Reciprocity then cannot fail: A and B are not
+ * two lists that happen to agree, they are the same list. The test suite still
+ * asserts it, because the property is the whole point of the module.
+ */
+export interface HreflangAlternate {
+    /** A BCP 47 tag, or `x-default`. */
+    readonly hreflang: string;
+    readonly href: string;
+}
+export interface TranslationFamily {
+    /** The id of the source entry, which is the family's identity. */
+    readonly sourceId: string;
+    /** Indexable members only, sorted by locale so output is stable. */
+    readonly members: readonly SeoResource[];
+}
+/**
+ * Groups resources into translation families, dropping everything unpublished
+ * first.
+ *
+ * The filter runs **before** grouping on purpose. A draft German translation
+ * must not appear as an alternate of the published French one: the tag would
+ * advertise a URL that 404s, and a crawler that follows it distrusts the rest
+ * of the cluster.
+ */
+export declare function groupTranslationFamilies(site: SeoSite, resources: readonly SeoResource[], options?: IndexableOptions): readonly TranslationFamily[];
+/**
+ * The alternate set of a family: one entry per language, plus `x-default`.
+ *
+ * `x-default` names the page a crawler should serve to a user whose language
+ * the site does not cover, and the only defensible answer is the **source**
+ * entry — the one with no `translationOf`. When the source is not published,
+ * no `x-default` is emitted at all: picking a translation instead would be a
+ * guess, and a wrong `x-default` sends every unmatched visitor to a language
+ * chosen at random by insertion order.
+ */
+export declare function alternatesFor(site: SeoSite, family: TranslationFamily): readonly HreflangAlternate[];
+/**
+ * Alternates keyed by entry id, for a whole page set.
+ *
+ * Every member of a family maps to the *same array instance*. That is what
+ * makes reciprocity structural rather than emergent.
+ */
+export declare function buildHreflangMap(site: SeoSite, resources: readonly SeoResource[], options?: IndexableOptions): ReadonlyMap<string, readonly HreflangAlternate[]>;
+//# sourceMappingURL=hreflang.d.ts.map

package/dist/hreflang.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hreflang.d.ts","sourceRoot":"","sources":["../src/hreflang.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAe,MAAM,gBAAgB,CAAA;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAGtD;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,WAAW,iBAAiB;IAChC,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,CAAA;CACzC;AAOD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,OAAO,GAAE,gBAAqB,GAC7B,SAAS,iBAAiB,EAAE,CAiB9B;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,iBAAiB,GACxB,SAAS,iBAAiB,EAAE,CAqB9B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,OAAO,GAAE,gBAAqB,GAC7B,WAAW,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC,CAanD"}

package/dist/hreflang.js

@@ -0,0 +1,86 @@
+import { isIndexable } from './indexable.js';
+import { canonicalUrl } from './url.js';
+/** A translation points at its source; a source points at nothing (ADR-0014). */
+function familyIdOf(resource) {
+    return resource.entry.translationOf ?? resource.entry.id;
+}
+/**
+ * Groups resources into translation families, dropping everything unpublished
+ * first.
+ *
+ * The filter runs **before** grouping on purpose. A draft German translation
+ * must not appear as an alternate of the published French one: the tag would
+ * advertise a URL that 404s, and a crawler that follows it distrusts the rest
+ * of the cluster.
+ */
+export function groupTranslationFamilies(site, resources, options = {}) {
+    const families = new Map();
+    for (const resource of resources) {
+        if (!isIndexable(site, resource, options))
+            continue;
+        const id = familyIdOf(resource);
+        const existing = families.get(id);
+        if (existing === undefined)
+            families.set(id, [resource]);
+        else
+            existing.push(resource);
+    }
+    return [...families.entries()]
+        .map(([sourceId, members]) => ({
+        sourceId,
+        members: [...members].sort((a, b) => a.entry.locale.localeCompare(b.entry.locale)),
+    }))
+        .sort((a, b) => a.sourceId.localeCompare(b.sourceId));
+}
+/**
+ * The alternate set of a family: one entry per language, plus `x-default`.
+ *
+ * `x-default` names the page a crawler should serve to a user whose language
+ * the site does not cover, and the only defensible answer is the **source**
+ * entry — the one with no `translationOf`. When the source is not published,
+ * no `x-default` is emitted at all: picking a translation instead would be a
+ * guess, and a wrong `x-default` sends every unmatched visitor to a language
+ * chosen at random by insertion order.
+ */
+export function alternatesFor(site, family) {
+    const alternates = [];
+    const seen = new Set();
+    for (const member of family.members) {
+        const href = canonicalUrl(site, member);
+        // `isIndexable` already established the URL exists; the null branch is a
+        // type narrowing, not a case.
+        if (href === null)
+            continue;
+        if (seen.has(member.entry.locale))
+            continue;
+        seen.add(member.entry.locale);
+        alternates.push({ hreflang: member.entry.locale, href });
+    }
+    const source = family.members.find((member) => member.entry.translationOf === null);
+    if (source !== undefined) {
+        const href = canonicalUrl(site, source);
+        if (href !== null)
+            alternates.push({ hreflang: 'x-default', href });
+    }
+    return alternates;
+}
+/**
+ * Alternates keyed by entry id, for a whole page set.
+ *
+ * Every member of a family maps to the *same array instance*. That is what
+ * makes reciprocity structural rather than emergent.
+ */
+export function buildHreflangMap(site, resources, options = {}) {
+    const map = new Map();
+    for (const family of groupTranslationFamilies(site, resources, options)) {
+        // A family of one gets no alternates: a self-referencing `hreflang` on a
+        // page with no translation is noise, and Google says as much.
+        if (family.members.length < 2)
+            continue;
+        const alternates = alternatesFor(site, family);
+        for (const member of family.members)
+            map.set(member.entry.id, alternates);
+    }
+    return map;
+}
+//# sourceMappingURL=hreflang.js.map

package/dist/hreflang.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `@cogenta/seo` — the SEO floor every Cogenta site stands on (L3, task 14).
+ *
+ * Sitemaps, `robots.txt`, JSON-LD, Open Graph and Twitter Card, RSS and Atom,
+ * `hreflang`, canonicals, `llms.txt` and IndexNow. Two properties hold across
+ * all of them, and they are the reason the package exists as one unit rather
+ * than as helpers scattered through the theme:
+ *
+ * 1. **Nothing unpublished ever leaves.** One gate (`isIndexable`), asked by
+ *    every generator, so no output can forget.
+ * 2. **Every document is escaped by construction.** No caller ever concatenates
+ *    XML, so no title can invalidate a feed.
+ *
+ * The package holds no state, opens no socket except the explicit IndexNow
+ * ping, and never touches the database — it is safe inside the render sandbox
+ * (rule R5).
+ */
+export type { FeedInput, FeedItem, FeedItemsOptions } from './feeds.js';
+export { feedItemsFor, renderAtomFeed, renderRssFeed, toRfc822 } from './feeds.js';
+export type { HreflangAlternate, TranslationFamily } from './hreflang.js';
+export { alternatesFor, buildHreflangMap, groupTranslationFamilies } from './hreflang.js';
+export type { IndexableOptions } from './indexable.js';
+export { indexableResources, isIndexable, isPublished } from './indexable.js';
+export type { IndexNowFetch, IndexNowOptions, IndexNowResult } from './indexnow.js';
+export { INDEXNOW_MAX_URLS, indexNowKeyFile, pingIndexNow } from './indexnow.js';
+export type { JsonLdObject, JsonLdOptions, JsonLdValue } from './json-ld.js';
+export { buildJsonLd, renderJsonLdScript, schemaTypeFor } from './json-ld.js';
+export type { LlmsTxtLink, LlmsTxtOptions, LlmsTxtSection, LlmsTxtSectionsOptions, } from './llms-txt.js';
+export { llmsTxtSectionsFor, renderLlmsTxt } from './llms-txt.js';
+export type { MetadataOptions, MetaTag } from './metadata.js';
+export { buildMetaTags, escapeHtmlAttribute, escapeHtmlText, renderMetaTags, } from './metadata.js';
+export type { RobotsGroup, RobotsOptions } from './robots.js';
+export { renderRobotsTxt } from './robots.js';
+export type { ChangeFrequency, SitemapFile, SitemapOptions, SitemapUrl } from './sitemap.js';
+export { buildSitemap, SITEMAP_MAX_BYTES, SITEMAP_MAX_URLS, sitemapUrlsFor, } from './sitemap.js';
+export type { SeoImage, SeoReference, SeoResolvers, SeoResource, SeoSite } from './types.js';
+export { absoluteUrl, canonicalUrl, hasRoute, normaliseBaseUrl, routeParams } from './url.js';
+export type { XmlAttributes, XmlElement } from './xml.js';
+export { escapeXmlAttribute, escapeXmlText, renderXmlDocument, renderXmlElement, stripIllegalXmlChars, } from './xml.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACvE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAClF,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACzE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAA;AACzF,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACtD,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC7E,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AACnF,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAChF,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC5E,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC7E,YAAY,EACV,WAAW,EACX,cAAc,EACd,cAAc,EACd,sBAAsB,GACvB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AACjE,YAAY,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAC7D,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAC5F,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,GACf,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAC5F,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAC7F,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AACzD,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,UAAU,CAAA"}

package/dist/index.js

@@ -0,0 +1,29 @@
+/**
+ * `@cogenta/seo` — the SEO floor every Cogenta site stands on (L3, task 14).
+ *
+ * Sitemaps, `robots.txt`, JSON-LD, Open Graph and Twitter Card, RSS and Atom,
+ * `hreflang`, canonicals, `llms.txt` and IndexNow. Two properties hold across
+ * all of them, and they are the reason the package exists as one unit rather
+ * than as helpers scattered through the theme:
+ *
+ * 1. **Nothing unpublished ever leaves.** One gate (`isIndexable`), asked by
+ *    every generator, so no output can forget.
+ * 2. **Every document is escaped by construction.** No caller ever concatenates
+ *    XML, so no title can invalidate a feed.
+ *
+ * The package holds no state, opens no socket except the explicit IndexNow
+ * ping, and never touches the database — it is safe inside the render sandbox
+ * (rule R5).
+ */
+export { feedItemsFor, renderAtomFeed, renderRssFeed, toRfc822 } from './feeds.js';
+export { alternatesFor, buildHreflangMap, groupTranslationFamilies } from './hreflang.js';
+export { indexableResources, isIndexable, isPublished } from './indexable.js';
+export { INDEXNOW_MAX_URLS, indexNowKeyFile, pingIndexNow } from './indexnow.js';
+export { buildJsonLd, renderJsonLdScript, schemaTypeFor } from './json-ld.js';
+export { llmsTxtSectionsFor, renderLlmsTxt } from './llms-txt.js';
+export { buildMetaTags, escapeHtmlAttribute, escapeHtmlText, renderMetaTags, } from './metadata.js';
+export { renderRobotsTxt } from './robots.js';
+export { buildSitemap, SITEMAP_MAX_BYTES, SITEMAP_MAX_URLS, sitemapUrlsFor, } from './sitemap.js';
+export { absoluteUrl, canonicalUrl, hasRoute, normaliseBaseUrl, routeParams } from './url.js';
+export { escapeXmlAttribute, escapeXmlText, renderXmlDocument, renderXmlElement, stripIllegalXmlChars, } from './xml.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAElF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAA;AAEzF,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAE7E,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAEhF,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAO7E,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAEjE,OAAO,EACL,aAAa,EACb,mBAAmB,EACnB,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAA;AAEtB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE7C,OAAO,EACL,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,GACf,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE7F,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,UAAU,CAAA"}

package/dist/indexable.d.ts

@@ -0,0 +1,28 @@
+import type { ContentEntry } from '@cogenta/schema';
+import type { SeoResource, SeoSite } from './types.js';
+/**
+ * The single gate every public artefact passes through.
+ *
+ * There is one function rather than a filter per output because the failure
+ * mode is asymmetric: a draft missing from the sitemap is a delay, a draft
+ * present in the RSS feed is a publication. Feed readers cache, and mail
+ * digests forward — an unpublished article that reaches a feed cannot be
+ * recalled. So sitemap, feeds, `hreflang`, `llms.txt` and IndexNow all ask the
+ * same question here, and no caller is trusted to have filtered beforehand.
+ */
+export interface IndexableOptions {
+    /** Injected so a scheduled entry can be tested without waiting for the clock. */
+    readonly now?: Date;
+}
+export declare function isPublished(entry: ContentEntry, options?: IndexableOptions): boolean;
+/**
+ * Published **and** reachable at a URL.
+ *
+ * A published entry in a collection with no `routing` has nothing to put in a
+ * sitemap, and an entry whose route parameters are incomplete — a slug that was
+ * never filled — would produce a URL that 404s.
+ */
+export declare function isIndexable(site: SeoSite, resource: SeoResource, options?: IndexableOptions): boolean;
+/** The indexable subset of a list, in the order given. */
+export declare function indexableResources(site: SeoSite, resources: readonly SeoResource[], options?: IndexableOptions): readonly SeoResource[];
+//# sourceMappingURL=indexable.d.ts.map

package/dist/indexable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexable.d.ts","sourceRoot":"","sources":["../src/indexable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AACnD,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAGtD;;;;;;;;;GASG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAA;CACpB;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAmBxF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAGT;AAED,0DAA0D;AAC1D,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,OAAO,GAAE,gBAAqB,GAC7B,SAAS,WAAW,EAAE,CAExB"}

package/dist/indexable.js

@@ -0,0 +1,39 @@
+import { canonicalUrl } from './url.js';
+export function isPublished(entry, options = {}) {
+    // `scheduled` and `archived` are both "not public right now", and `draft`
+    // never was. Only one of the four statuses means published (contract A).
+    if (entry.status !== 'published')
+        return false;
+    // The working face carries edits nobody has published. Rendering a feed from
+    // it ships the unreviewed paragraph an editor typed a minute ago, which is
+    // the same leak as publishing a draft — just harder to notice, because the
+    // entry legitimately appears in the list.
+    if (entry.state !== 'published')
+        return false;
+    // A published status with a future `publishedAt` is a scheduled entry whose
+    // job has not run yet, or one that a scheduler pre-flipped. Either way it is
+    // not public.
+    if (entry.publishedAt === null)
+        return false;
+    const at = Date.parse(entry.publishedAt);
+    if (Number.isNaN(at))
+        return false;
+    return at <= (options.now ?? new Date()).getTime();
+}
+/**
+ * Published **and** reachable at a URL.
+ *
+ * A published entry in a collection with no `routing` has nothing to put in a
+ * sitemap, and an entry whose route parameters are incomplete — a slug that was
+ * never filled — would produce a URL that 404s.
+ */
+export function isIndexable(site, resource, options = {}) {
+    if (!isPublished(resource.entry, options))
+        return false;
+    return canonicalUrl(site, resource) !== null;
+}
+/** The indexable subset of a list, in the order given. */
+export function indexableResources(site, resources, options = {}) {
+    return resources.filter((resource) => isIndexable(site, resource, options));
+}
+//# sourceMappingURL=indexable.js.map

package/dist/indexable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexable.js","sourceRoot":"","sources":["../src/indexable.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAkBvC,MAAM,UAAU,WAAW,CAAC,KAAmB,EAAE,OAAO,GAAqB,EAAE;IAC7E,0EAA0E;IAC1E,yEAAyE;IACzE,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,KAAK,CAAA;IAE9C,6EAA6E;IAC7E,2EAA2E;IAC3E,2EAA2E;IAC3E,0CAA0C;IAC1C,IAAI,KAAK,CAAC,KAAK,KAAK,WAAW;QAAE,OAAO,KAAK,CAAA;IAE7C,4EAA4E;IAC5E,6EAA6E;IAC7E,cAAc;IACd,IAAI,KAAK,CAAC,WAAW,KAAK,IAAI;QAAE,OAAO,KAAK,CAAA;IAC5C,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,CAAC,CAAA;IACxC,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAAE,OAAO,KAAK,CAAA;IAElC,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAA;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CACzB,IAAa,EACb,QAAqB,EACrB,OAAO,GAAqB,EAAE;IAE9B,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QAAE,OAAO,KAAK,CAAA;IACvD,OAAO,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,KAAK,IAAI,CAAA;AAC9C,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,kBAAkB,CAChC,IAAa,EACb,SAAiC,EACjC,OAAO,GAAqB,EAAE;IAE9B,OAAO,SAAS,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAA;AAC7E,CAAC"}