@haruhimemoe/next-kit 0.2.0 → 0.3.0

package/dist/seo/ld-site.js

@@ -0,0 +1,135 @@
+/**
+ * @file src/seo/ld-site.ts
+ * @desc schema.org JSON-LD for the site itself: the graph wrapper (the only place `@context`
+ *       goes), Organization, WebSite with its SearchAction, WebApplication, BreadcrumbList and
+ *       ItemList. Stable @ids tie every tool to one organization (audit A3, A6).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { absoluteUrl, compact, nodeId } from "./site.js";
+/** The placeholder a SearchAction's urlTemplate must hold. */
+export const SEARCH_TERM = "{search_term_string}";
+/**
+ * @function graph
+ * @param nodes {LdNode[]} the page's nodes
+ * @returns {LdGraph} one JSON-LD document with `@context` on the root only
+ */
+export const graph = (...nodes) => ({
+    "@context": "https://schema.org",
+    "@graph": nodes,
+});
+/**
+ * @function organization
+ * @param org {Organization} the organization, like HARUHIME_ORG
+ * @returns {LdNode} Organization with @id `${origin}/#organization`
+ */
+export const organization = (org) => compact({
+    "@type": "Organization",
+    "@id": nodeId(org.url, "organization"),
+    name: org.name,
+    url: org.url,
+    logo: org.logo,
+    email: org.email,
+    sameAs: org.sameAs?.length ? [...org.sameAs] : undefined,
+});
+/** A reference to the site's organization by @id. */
+export const orgRef = (site) => ({
+    "@id": nodeId(site.organization.url, "organization"),
+});
+/**
+ * @function webSite
+ * @param site {Site} the site
+ * @param options {{ searchUrlTemplate?: string }} a search URL holding {search_term_string},
+ *        like "/search?q={search_term_string}"
+ * @returns {LdNode} WebSite with @id `${origin}/#website`, publisher → the organization,
+ *          isPartOf → the parent site, and a SearchAction when a template is given
+ * @throws {Error} when the template lacks {search_term_string} or isn't on the site
+ */
+export const webSite = (site, options = {}) => {
+    const template = options.searchUrlTemplate;
+    if (template !== undefined && !template.includes(SEARCH_TERM)) {
+        throw new Error(`seo: searchUrlTemplate must hold ${SEARCH_TERM}`);
+    }
+    return compact({
+        "@type": "WebSite",
+        "@id": nodeId(site.url, "website"),
+        name: site.name,
+        alternateName: new URL(site.url).host,
+        url: absoluteUrl(site, "/"),
+        description: site.description,
+        inLanguage: (site.locale ?? "en_US").replace("_", "-"),
+        publisher: orgRef(site),
+        isPartOf: site.parent ? { "@id": nodeId(site.parent.url, "website") } : undefined,
+        potentialAction: template
+            ? {
+                "@type": "SearchAction",
+                target: { "@type": "EntryPoint", urlTemplate: absoluteUrl(site, template) },
+                "query-input": "required name=search_term_string",
+            }
+            : undefined,
+    });
+};
+/**
+ * @function webApplication
+ * @param site {Site} the site
+ * @param options {WebApplicationOptions} category, and optional name, features and path
+ * @returns {LdNode} WebApplication, free (Offer price 0), operatingSystem "Any", publisher →
+ *          the organization
+ */
+export const webApplication = (site, options) => {
+    const url = absoluteUrl(site, options.path ?? "/");
+    return compact({
+        "@type": "WebApplication",
+        "@id": options.path && options.path !== "/" ? `${url}#app` : nodeId(site.url, "app"),
+        name: options.name ?? site.name,
+        url,
+        description: options.description ?? site.description,
+        applicationCategory: options.category,
+        operatingSystem: "Any",
+        browserRequirements: options.browserRequirements ?? "Requires JavaScript. Works in any modern browser.",
+        featureList: options.features?.length ? [...options.features] : undefined,
+        isAccessibleForFree: true,
+        offers: { "@type": "Offer", price: "0", priceCurrency: "USD" },
+        publisher: orgRef(site),
+        isPartOf: { "@id": nodeId(site.url, "website") },
+    });
+};
+/**
+ * @function breadcrumbs
+ * @param site {Site} the site
+ * @param trail {readonly LdLink[]} from the home page down to this page
+ * @returns {LdNode} BreadcrumbList, positions from 1, absolute item URLs
+ * @throws {Error} when the trail is empty
+ */
+export const breadcrumbs = (site, trail) => {
+    if (!trail.length)
+        throw new Error("seo: breadcrumbs need at least one page");
+    return {
+        "@type": "BreadcrumbList",
+        itemListElement: trail.map((link, i) => ({
+            "@type": "ListItem",
+            position: i + 1,
+            name: link.name,
+            item: absoluteUrl(site, link.path),
+        })),
+    };
+};
+/**
+ * @function itemList
+ * @param site {Site} the site
+ * @param items {readonly LdLink[]} the listed pages, in order
+ * @param options {{ name?: string }} the list's name
+ * @returns {LdNode} ItemList with numberOfItems and ListItems (position, name, url)
+ */
+export const itemList = (site, items, options = {}) => compact({
+    "@type": "ItemList",
+    name: options.name,
+    numberOfItems: items.length,
+    itemListElement: items.map((item, i) => ({
+        "@type": "ListItem",
+        position: i + 1,
+        name: item.name,
+        url: absoluteUrl(site, item.path),
+    })),
+});

package/dist/seo/ld.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file src/seo/ld.ts
+ * @desc The `ld` namespace of JSON-LD builders, and serializeLd: JSON that is safe inside a
+ *       `<script>` tag. @haruhimemoe/ui's JsonLd escapes "<" only; serializeLd also escapes ">",
+ *       "&" and U+2028/U+2029, so the output is safe in any HTML or JavaScript context.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { creativeWork, dataset, faq, howTo, techArticle } from "./ld-content.js";
+import { breadcrumbs, graph, itemList, organization, webApplication, webSite } from "./ld-site.js";
+/** The JSON-LD builders: plain schema.org objects, rendered with @haruhimemoe/ui's JsonLd. */
+export declare const ld: {
+    readonly graph: typeof graph;
+    readonly organization: typeof organization;
+    readonly webSite: typeof webSite;
+    readonly webApplication: typeof webApplication;
+    readonly breadcrumbs: typeof breadcrumbs;
+    readonly itemList: typeof itemList;
+    readonly faq: typeof faq;
+    readonly howTo: typeof howTo;
+    readonly techArticle: typeof techArticle;
+    readonly creativeWork: typeof creativeWork;
+    readonly dataset: typeof dataset;
+};
+/**
+ * @function serializeLd
+ * @param data {object} a JSON-LD document or node
+ * @returns {string} JSON with <, >, & and U+2028/U+2029 written as \u escapes: the same data to
+ *          a JSON parser, and nothing a `<script>` tag or an HTML comment can end on
+ */
+export declare const serializeLd: (data: object) => string;

package/dist/seo/ld.js

@@ -0,0 +1,39 @@
+/**
+ * @file src/seo/ld.ts
+ * @desc The `ld` namespace of JSON-LD builders, and serializeLd: JSON that is safe inside a
+ *       `<script>` tag. @haruhimemoe/ui's JsonLd escapes "<" only; serializeLd also escapes ">",
+ *       "&" and U+2028/U+2029, so the output is safe in any HTML or JavaScript context.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { creativeWork, dataset, faq, howTo, techArticle } from "./ld-content.js";
+import { breadcrumbs, graph, itemList, organization, webApplication, webSite } from "./ld-site.js";
+/** The JSON-LD builders: plain schema.org objects, rendered with @haruhimemoe/ui's JsonLd. */
+export const ld = {
+    graph,
+    organization,
+    webSite,
+    webApplication,
+    breadcrumbs,
+    itemList,
+    faq,
+    howTo,
+    techArticle,
+    creativeWork,
+    dataset,
+};
+const ESCAPES = {
+    "<": "\\u003c",
+    ">": "\\u003e",
+    "&": "\\u0026",
+    "\u2028": "\\u2028",
+    "\u2029": "\\u2029",
+};
+/**
+ * @function serializeLd
+ * @param data {object} a JSON-LD document or node
+ * @returns {string} JSON with <, >, & and U+2028/U+2029 written as \u escapes: the same data to
+ *          a JSON parser, and nothing a `<script>` tag or an HTML comment can end on
+ */
+export const serializeLd = (data) => JSON.stringify(data).replace(/[<>&\u2028\u2029]/g, (char) => ESCAPES[char]);

package/dist/seo/llms.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @file src/seo/llms.ts
+ * @desc /llms.txt (https://llmstxt.org): an H1, a blockquote summary, note paragraphs, then H2
+ *       sections of "- [title](url): note" links. /llms-full.txt: whole documents in one file.
+ *       And the text/plain response both are served with. One builder, so escaping and section
+ *       format stay the same on every site (audit A2).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** One link in a section. */
+export type LlmsLink = {
+    title: string;
+    url: string;
+    note?: string;
+};
+/** An H2 section of links. A section with no links is left out. */
+export type LlmsSection = {
+    heading: string;
+    links: readonly LlmsLink[];
+};
+/** llmsTxt's input. */
+export type LlmsTxtOptions = {
+    /** The H1, like "pools.haruhime.moe". */
+    title: string;
+    /** The blockquote: what the site is, in one paragraph. */
+    summary: string;
+    /** Paragraphs a reader needs before following any link. */
+    notes?: readonly string[];
+    sections: readonly LlmsSection[];
+};
+/** One document in llms-full.txt. */
+export type LlmsFullPart = {
+    title: string;
+    url?: string;
+    markdown: string;
+};
+/**
+ * @function llmsTxt
+ * @param options {LlmsTxtOptions} title, summary, notes and link sections
+ * @returns {string} the llms.txt body, ending in one newline
+ * @throws {Error} when the title, summary, a heading, a link title or a URL is blank
+ */
+export declare const llmsTxt: ({ title, summary, notes, sections }: LlmsTxtOptions) => string;
+/**
+ * @function llmsFull
+ * @param parts {readonly LlmsFullPart[]} the documents, in order, as Markdown
+ * @param head {{ title: string; summary?: string }} an H1 and summary for the whole file
+ * @returns {string} one Markdown file: the head, then each document with its source URL,
+ *          separated by horizontal rules, ending in one newline. Each document's Markdown is
+ *          kept as is (code blocks included).
+ */
+export declare const llmsFull: (parts: readonly LlmsFullPart[], head?: {
+    title: string;
+    summary?: string;
+}) => string;
+/** textResponse's options. */
+export type TextResponseOptions = {
+    /** Browser cache seconds. Default 3600. */
+    maxAge?: number;
+    /** CDN cache seconds. Defaults to maxAge. */
+    sMaxAge?: number;
+    /** Default "text/plain". /docs/*.md mirrors use "text/markdown". */
+    type?: "text/plain" | "text/markdown";
+};
+/**
+ * @function textResponse
+ * @param body {string} the text
+ * @param options {TextResponseOptions} cache lifetimes and type
+ * @returns {Response} 200 with `<type>; charset=utf-8`, public Cache-Control and nosniff
+ */
+export declare const textResponse: (body: string, options?: TextResponseOptions) => Response;

package/dist/seo/llms.js

@@ -0,0 +1,85 @@
+/**
+ * @file src/seo/llms.ts
+ * @desc /llms.txt (https://llmstxt.org): an H1, a blockquote summary, note paragraphs, then H2
+ *       sections of "- [title](url): note" links. /llms-full.txt: whole documents in one file.
+ *       And the text/plain response both are served with. One builder, so escaping and section
+ *       format stay the same on every site (audit A2).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+const oneLine = (text) => text.replace(/\s+/g, " ").trim();
+/** Link text can't end the link early: brackets and backslashes are escaped. */
+const linkText = (text) => oneLine(text).replace(/[\\[\]]/g, "\\$&");
+/** A URL can't hold a space or end the link early: those are percent-encoded. */
+const linkUrl = (url) => url.trim().replace(/[\s()<>]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+const required = (value, what) => {
+    const line = oneLine(value);
+    if (!line)
+        throw new Error(`seo: llms.txt ${what} can't be blank`);
+    return line;
+};
+/**
+ * @function llmsTxt
+ * @param options {LlmsTxtOptions} title, summary, notes and link sections
+ * @returns {string} the llms.txt body, ending in one newline
+ * @throws {Error} when the title, summary, a heading, a link title or a URL is blank
+ */
+export const llmsTxt = ({ title, summary, notes = [], sections }) => {
+    const lines = [`# ${required(title, "title")}`, "", `> ${required(summary, "summary")}`];
+    for (const note of notes) {
+        const line = oneLine(note);
+        if (line)
+            lines.push("", line);
+    }
+    for (const { heading, links } of sections) {
+        if (!links.length)
+            continue;
+        lines.push("", `## ${required(heading, "heading")}`, "");
+        for (const link of links) {
+            const note = link.note ? oneLine(link.note) : "";
+            const text = linkText(required(link.title, "link title"));
+            const href = linkUrl(required(link.url, "link URL"));
+            lines.push(`- [${text}](${href})${note ? `: ${note}` : ""}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+};
+/**
+ * @function llmsFull
+ * @param parts {readonly LlmsFullPart[]} the documents, in order, as Markdown
+ * @param head {{ title: string; summary?: string }} an H1 and summary for the whole file
+ * @returns {string} one Markdown file: the head, then each document with its source URL,
+ *          separated by horizontal rules, ending in one newline. Each document's Markdown is
+ *          kept as is (code blocks included).
+ */
+export const llmsFull = (parts, head) => {
+    const blocks = [];
+    if (head) {
+        blocks.push([
+            `# ${required(head.title, "title")}`,
+            ...(head.summary ? ["", `> ${oneLine(head.summary)}`] : []),
+        ].join("\n"));
+    }
+    for (const part of parts) {
+        const source = part.url ? `\n\nSource: ${linkUrl(part.url)}` : "";
+        blocks.push(`# ${required(part.title, "part title")}${source}\n\n${part.markdown.trim()}`);
+    }
+    return `${blocks.join("\n\n---\n\n")}\n`;
+};
+/**
+ * @function textResponse
+ * @param body {string} the text
+ * @param options {TextResponseOptions} cache lifetimes and type
+ * @returns {Response} 200 with `<type>; charset=utf-8`, public Cache-Control and nosniff
+ */
+export const textResponse = (body, options = {}) => {
+    const maxAge = options.maxAge ?? 3600;
+    return new Response(body, {
+        headers: {
+            "Content-Type": `${options.type ?? "text/plain"}; charset=utf-8`,
+            "Cache-Control": `public, max-age=${maxAge}, s-maxage=${options.sMaxAge ?? maxAge}`,
+            "X-Content-Type-Options": "nosniff",
+        },
+    });
+};

package/dist/seo/metadata.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @file src/seo/metadata.ts
+ * @desc Next.js Metadata for the root layout, the home page, every other page and not-found.
+ *       A page's openGraph replaces the layout's whole object in Next (it isn't merged), so
+ *       pageMetadata always rebuilds it in full: site name, locale, type, url and images (audit T2),
+ *       with the canonical and og:url set together from one path (T1, T3).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { Metadata } from "next";
+import { type OgImage, type Site } from "./site.js";
+/** pageMetadata's input. */
+export type PageMetadataOptions = {
+    /** The page's path, like "/search". Canonical and og:url both come from it. */
+    path: string;
+    /** The primary keyword; " · host" is added (pageTitle). */
+    title: string;
+    /** Defaults to the site's description. Clamped to 160 characters. */
+    description?: string;
+    /** false: noindex, follow. Default true. */
+    index?: boolean;
+    /** Default "website". "article" also writes the published and modified times. */
+    ogType?: "website" | "article";
+    /** Defaults to the site's ogImages, so a page never loses its preview. */
+    images?: readonly OgImage[];
+    modifiedTime?: string | Date;
+    publishedTime?: string | Date;
+};
+/**
+ * @function siteMetadata
+ * @param site {Site} the site
+ * @returns {Metadata} the root layout's metadata: metadataBase, the title default and template,
+ *          description, applicationName, openGraph (type, site name, locale, images) and the
+ *          twitter card. No canonical: a layout canonical would leak to every child page.
+ *          Icons stay with the app (its icon files).
+ */
+export declare const siteMetadata: (site: Site) => Metadata;
+/**
+ * @function pageMetadata
+ * @param site {Site} the site
+ * @param options {PageMetadataOptions} the page
+ * @returns {Metadata} an absolute "keyword · host" title, the clamped description, the
+ *          canonical and og:url (always together, as absolute URLs), a full openGraph and
+ *          twitter card, and robots noindex when index is false
+ * @throws {Error} when path doesn't start with "/" or the title is blank
+ */
+export declare const pageMetadata: (site: Site, options: PageMetadataOptions) => Metadata;
+/**
+ * @function homeMetadata
+ * @param site {Site} the site
+ * @param options {{ title?: string; description?: string }} overrides for the site's own
+ * @returns {Metadata} pageMetadata for "/": "keyword · host", canonical and og:url on the origin
+ */
+export declare const homeMetadata: (site: Site, options?: {
+    title?: string;
+    description?: string;
+}) => Metadata;
+/**
+ * @function notFoundMetadata
+ * @param site {Site} the site
+ * @param what {string} what's missing, like "Pack" (default "Page")
+ * @returns {Metadata} "Pack not found · host", noindex, and no canonical (audit T8: missing
+ *          records returned {} and got the site's default title)
+ */
+export declare const notFoundMetadata: (site: Site, what?: string) => Metadata;

package/dist/seo/metadata.js

@@ -0,0 +1,106 @@
+/**
+ * @file src/seo/metadata.ts
+ * @desc Next.js Metadata for the root layout, the home page, every other page and not-found.
+ *       A page's openGraph replaces the layout's whole object in Next (it isn't merged), so
+ *       pageMetadata always rebuilds it in full: site name, locale, type, url and images (audit T2),
+ *       with the canonical and og:url set together from one path (T1, T3).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { clampDescription } from "./describe.js";
+import { absoluteUrl, compact, isoDate, pageTitle, TITLE_SEPARATOR, titleSuffix, } from "./site.js";
+const DEFAULT_LOCALE = "en_US";
+const twitter = (site, extra = {}) => compact({
+    card: "summary_large_image",
+    site: site.twitter?.site,
+    creator: site.twitter?.creator,
+    ...extra,
+});
+/**
+ * @function siteMetadata
+ * @param site {Site} the site
+ * @returns {Metadata} the root layout's metadata: metadataBase, the title default and template,
+ *          description, applicationName, openGraph (type, site name, locale, images) and the
+ *          twitter card. No canonical: a layout canonical would leak to every child page.
+ *          Icons stay with the app (its icon files).
+ */
+export const siteMetadata = (site) => {
+    return {
+        metadataBase: new URL(site.url),
+        title: {
+            default: pageTitle(site, site.title),
+            template: `%s${TITLE_SEPARATOR}${titleSuffix(site)}`,
+        },
+        description: clampDescription(site.description),
+        applicationName: site.name,
+        openGraph: {
+            type: "website",
+            siteName: site.name,
+            locale: site.locale ?? DEFAULT_LOCALE,
+            images: [...site.ogImages],
+        },
+        twitter: twitter(site, { images: site.ogImages.map((image) => image.url) }),
+    };
+};
+/**
+ * @function pageMetadata
+ * @param site {Site} the site
+ * @param options {PageMetadataOptions} the page
+ * @returns {Metadata} an absolute "keyword · host" title, the clamped description, the
+ *          canonical and og:url (always together, as absolute URLs), a full openGraph and
+ *          twitter card, and robots noindex when index is false
+ * @throws {Error} when path doesn't start with "/" or the title is blank
+ */
+export const pageMetadata = (site, options) => {
+    const url = absoluteUrl(site, options.path);
+    const title = pageTitle(site, options.title);
+    const description = clampDescription(options.description ?? site.description);
+    const images = [...(options.images ?? site.ogImages)];
+    const base = {
+        title,
+        description,
+        url,
+        siteName: site.name,
+        locale: site.locale ?? DEFAULT_LOCALE,
+        images,
+    };
+    const openGraph = options.ogType === "article"
+        ? compact({
+            ...base,
+            type: "article",
+            publishedTime: isoDate(options.publishedTime),
+            modifiedTime: isoDate(options.modifiedTime),
+        })
+        : { ...base, type: "website" };
+    return {
+        title: { absolute: title },
+        description,
+        alternates: { canonical: url },
+        openGraph,
+        twitter: twitter(site, { title, description, images: images.map((image) => image.url) }),
+        ...(options.index === false ? { robots: { index: false, follow: true } } : {}),
+    };
+};
+/**
+ * @function homeMetadata
+ * @param site {Site} the site
+ * @param options {{ title?: string; description?: string }} overrides for the site's own
+ * @returns {Metadata} pageMetadata for "/": "keyword · host", canonical and og:url on the origin
+ */
+export const homeMetadata = (site, options = {}) => pageMetadata(site, {
+    path: "/",
+    title: options.title ?? site.title,
+    ...(options.description === undefined ? {} : { description: options.description }),
+});
+/**
+ * @function notFoundMetadata
+ * @param site {Site} the site
+ * @param what {string} what's missing, like "Pack" (default "Page")
+ * @returns {Metadata} "Pack not found · host", noindex, and no canonical (audit T8: missing
+ *          records returned {} and got the site's default title)
+ */
+export const notFoundMetadata = (site, what = "Page") => ({
+    title: { absolute: pageTitle(site, `${what} not found`) },
+    robots: { index: false, follow: false },
+});

package/dist/seo/robots.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @file src/seo/robots.ts
+ * @desc robots.txt with the AI stance written down (audit A1). A crawler that matches a named
+ *       group ignores the `*` group (RFC 9309), so every allowed AI bot gets a group with the same
+ *       rules as `*`, and a blocked one gets `Disallow: /`. Changing the stance is one word.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { MetadataRoute } from "next";
+import { type Site } from "./site.js";
+/** What a bot fetches for: model training, or search and answers (user fetches included). */
+export type AiBotKind = "training" | "search";
+/** One AI or search crawler, by its robots.txt user-agent token. */
+export type AiBot = {
+    userAgent: string;
+    operator: string;
+    kind: AiBotKind;
+    /** A web search engine's own crawler: "block-all" keeps it, or the site leaves that engine. */
+    searchEngine?: true;
+};
+/** The crawlers robots() names. Order is the order their groups list them. */
+export declare const AI_BOTS: readonly AiBot[];
+/** The AI stance: allow every bot, block training only, or block every AI bot. */
+export type AiBotsPolicy = "allow" | "block-training" | "block-all";
+/** robots()'s options. */
+export type RobotsOptions = {
+    /** Paths every crawler may fetch. Default ["/"]. */
+    allow?: readonly string[];
+    /** Private paths, like "/api/" or "/admin". Longest match wins over allow. */
+    disallow?: readonly string[];
+    /** Default "allow". */
+    aiBots?: AiBotsPolicy;
+};
+/**
+ * @function robots
+ * @param site {Site} the site (sitemap and host come from its origin)
+ * @param options {RobotsOptions} allow, disallow and the AI stance
+ * @returns {MetadataRoute.Robots} the `*` group, one group for the allowed AI bots with the same
+ *          rules (Bingbot is always there), one `Disallow: /` group for the blocked ones (when
+ *          any are), the sitemap URL and the host
+ */
+export declare const robots: (site: Site, options?: RobotsOptions) => MetadataRoute.Robots;

package/dist/seo/robots.js

@@ -0,0 +1,55 @@
+/**
+ * @file src/seo/robots.ts
+ * @desc robots.txt with the AI stance written down (audit A1). A crawler that matches a named
+ *       group ignores the `*` group (RFC 9309), so every allowed AI bot gets a group with the same
+ *       rules as `*`, and a blocked one gets `Disallow: /`. Changing the stance is one word.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { absoluteUrl, origin } from "./site.js";
+/** The crawlers robots() names. Order is the order their groups list them. */
+export const AI_BOTS = [
+    { userAgent: "GPTBot", operator: "OpenAI", kind: "training" },
+    { userAgent: "OAI-SearchBot", operator: "OpenAI", kind: "search" },
+    { userAgent: "ChatGPT-User", operator: "OpenAI", kind: "search" },
+    { userAgent: "PerplexityBot", operator: "Perplexity", kind: "search" },
+    { userAgent: "Perplexity-User", operator: "Perplexity", kind: "search" },
+    { userAgent: "ClaudeBot", operator: "Anthropic", kind: "training" },
+    { userAgent: "Claude-SearchBot", operator: "Anthropic", kind: "search" },
+    { userAgent: "Claude-User", operator: "Anthropic", kind: "search" },
+    { userAgent: "anthropic-ai", operator: "Anthropic", kind: "training" },
+    { userAgent: "Google-Extended", operator: "Google", kind: "training" },
+    { userAgent: "Applebot-Extended", operator: "Apple", kind: "training" },
+    { userAgent: "Bingbot", operator: "Microsoft", kind: "search", searchEngine: true },
+    { userAgent: "CCBot", operator: "Common Crawl", kind: "training" },
+    { userAgent: "Bytespider", operator: "ByteDance", kind: "training" },
+    { userAgent: "meta-externalagent", operator: "Meta", kind: "training" },
+];
+const blocked = (bot, policy) => policy === "block-all"
+    ? !bot.searchEngine
+    : policy === "block-training" && bot.kind === "training";
+/**
+ * @function robots
+ * @param site {Site} the site (sitemap and host come from its origin)
+ * @param options {RobotsOptions} allow, disallow and the AI stance
+ * @returns {MetadataRoute.Robots} the `*` group, one group for the allowed AI bots with the same
+ *          rules (Bingbot is always there), one `Disallow: /` group for the blocked ones (when
+ *          any are), the sitemap URL and the host
+ */
+export const robots = (site, options = {}) => {
+    const policy = options.aiBots ?? "allow";
+    const allow = [...(options.allow ?? ["/"])];
+    const rules = { allow, ...(options.disallow?.length ? { disallow: [...options.disallow] } : {}) };
+    const allowed = AI_BOTS.filter((bot) => !blocked(bot, policy)).map((bot) => bot.userAgent);
+    const denied = AI_BOTS.filter((bot) => blocked(bot, policy)).map((bot) => bot.userAgent);
+    return {
+        rules: [
+            { userAgent: "*", ...rules },
+            { userAgent: allowed, ...rules },
+            ...(denied.length ? [{ userAgent: denied, disallow: "/" }] : []),
+        ],
+        sitemap: absoluteUrl(site, "/sitemap.xml"),
+        host: origin(site.url),
+    };
+};