@haruhimemoe/next-kit 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-28
+
+### Added
+
+- `@haruhimemoe/next-kit/seo`, for www, packs, pools and bb. No runtime imports (Next's types only).
+  - Metadata: `siteMetadata`, `homeMetadata`, `pageMetadata`, `notFoundMetadata`, `pageTitle` ("keyword · host") and `clampDescription` (160 characters, cut at a word). `pageMetadata` always sets the canonical and og:url together and always writes a full openGraph with the site's images, so a page never loses its preview.
+  - `robots` with the AI crawler stance written down (`"allow"`, `"block-training"` or `"block-all"`) and the `AI_BOTS` table.
+  - `sitemapEntries`: absolute URLs, one per URL, lastmod only when it's a real date, and an error past 50,000 URLs.
+  - JSON-LD builders in `ld` (graph, Organization, WebSite with SearchAction, WebApplication, BreadcrumbList, ItemList, FAQPage, HowTo, TechArticle, CreativeWork, Dataset) with stable `@id`s, `HARUHIME_ORG`, and `serializeLd` for script-safe JSON.
+  - `llmsTxt`, `llmsFull` and `textResponse` for /llms.txt and /llms-full.txt.
+
+## [0.2.1] - 2026-09-28
+
+### Fixed
+
+- The `@haruhimemoe/osu` peer range also allows `^0.4.0`, so apps on osu 0.4.0 install without npm's ERESOLVE.
+
 ## [0.2.0] - 2026-09-28
 
 ### Added
@@ -29,6 +46,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `@haruhimemoe/next-kit/auth-react`: `createSignedInMarker`, `createAccountStore`, `useAccount`, `createAccount`, `RestoreSignedIn` and `osuSignIn`.
 - `@haruhimemoe/next-kit/testing`: `startMemoryMongo`, `setupTestDb`, `setupMsw` and the fake osu! app env.
 
-[unreleased]: https://github.com/haruhimemoe/next-kit/compare/v0.2.0...HEAD
+[unreleased]: https://github.com/haruhimemoe/next-kit/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/haruhimemoe/next-kit/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/haruhimemoe/next-kit/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/haruhimemoe/next-kit/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/haruhimemoe/next-kit/releases/tag/v0.1.0

package/README.md

@@ -9,6 +9,7 @@ The Next.js server plumbing the haruhime.moe tools share. [packs.haruhime.moe](h
 - **`/mongo`:** one MongoClient per process with Mongoose on the same client, index builds that never take the site down, and frozen collection names.
 - **`/auth`:** better-auth with osu! as the only way in, the indexes its collections need, and reading the caller.
 - **`/auth-react`:** the browser half: the signed-in marker cookie, the account store and `useAccount`, `RestoreSignedIn`, and the account components (Sign in with osu!, Sign out, the header's account menu, Delete my account) styled with `@haruhimemoe/ui`.
+- **`/seo`:** Next.js metadata that keeps each page's canonical, og:url and preview image together, robots.txt with the AI crawler stance written down, sitemap entries with honest lastmod, schema.org JSON-LD builders, and llms.txt. No runtime imports; all four haruhime.moe sites use it.
 - **`/testing`:** Vitest helpers: one in-memory MongoDB per run, an msw server that refuses unhandled requests, and a fake env.
 
 Every name, path, limit and message comes from the caller. There is no root entry point; import a subpath.
@@ -29,6 +30,7 @@ bun add @haruhimemoe/next-kit zod
 | `mongo` | `mongodb` ^7.6.0, `mongoose` ^9.10.2 |
 | `auth` | `better-auth` ^1.7.5, `mongodb`, `@haruhimemoe/osu` 0.2 or 0.3 |
 | `auth-react` | `react` ^19.3.0, `next` ^16.3.6, `@haruhimemoe/ui` ^0.5.0 (with its theme set up) |
+| `seo` | `next` ^16.3.6 types only (nothing loads at runtime) |
 | `testing` | `vitest` ^5.0.1, `msw` ^2.15.0, `mongodb-memory-server` ^11.3.0 |
 
 ## Use
@@ -116,6 +118,35 @@ export const { SignInWithOsu, SignOutButton, AccountMenu, DeleteAccountForm } =
 
 Build the auth instance once (memoize `getAuth`), and use the same cookie name on both sides.
 
+SEO: one `Site` per app, then one call per file.
+
+```ts
+// src/constants/seo.ts
+import { HARUHIME_ORG, type Site } from "@haruhimemoe/next-kit/seo";
+export const SEO_SITE: Site = {
+  name: "pools",
+  url: "https://pools.haruhime.moe",
+  title: "osu! tournament mappool builder",
+  description: "Build an osu! tournament mappool: search every ranked map under HR or DT, check the content rules, then download it as a pack.",
+  ogImages: [{ url: "/opengraph-image.png", width: 1200, height: 630, alt: "pools" }],
+  organization: HARUHIME_ORG,
+  parent: { name: "haruhime.moe", url: "https://www.haruhime.moe" },
+};
+
+// src/app/layout.tsx: export const metadata = siteMetadata(SEO_SITE);
+// src/app/page.tsx:   export const metadata = homeMetadata(SEO_SITE);
+// src/app/search/page.tsx
+export const metadata = pageMetadata(SEO_SITE, { path: "/search", title: "Search osu! tournament mappools" });
+// src/app/robots.ts
+export default () => robots(SEO_SITE, { disallow: ["/api/", "/admin"], aiBots: "allow" });
+// src/app/sitemap.ts
+export default async () => sitemapEntries(SEO_SITE, [["/", "/search"], pools.map((p) => ({ path: `/pools/${p.id}`, lastModified: p.contentUpdatedAt }))]);
+// src/app/page.tsx (render with @haruhimemoe/ui's JsonLd)
+<JsonLd data={ld.graph(ld.webSite(SEO_SITE, { searchUrlTemplate: "/search?q={search_term_string}" }), ld.webApplication(SEO_SITE, { category: "UtilitiesApplication" }))} />
+// src/app/llms.txt/route.ts
+export const GET = () => textResponse(llmsTxt({ title: "pools.haruhime.moe", summary: SEO_SITE.description, sections }));
+```
+
 ## API
 
 ### server
@@ -184,6 +215,33 @@ Build the auth instance once (memoize `getAuth`), and use the same cookie name o
 | `DeleteAccountForm({ username, appName, deletes, onDeleted, endpoint?, homeHref?, homeLabel?, fetcher? })` | Since 0.2.0. ui's `TypeToConfirm` on the username, then `DELETE endpoint` (default `/api/account`) with `{ username }`. 204: `onDeleted`, "Your account is deleted." and home. Another 2xx: `onDeleted` and the answer's `notice` after that line, staying. A refusal shows `error.message` (else "Deleting failed (status)."); no answer, "Couldn't reach <appName>. Your account is still there." `deletes` is inline content in a `<p>`. |
 | `osuAvatarSrc(url)`, `OSU_AVATAR_HOSTS` | Since 0.2.0. An osu! avatar URL on https when it's on a.ppy.sh or osu.ppy.sh (a bare path is osu.ppy.sh's), else null. |
 
+### seo
+
+Since 0.3.0. Every helper takes the app's `Site`: `name`, `url` (the canonical origin), `title` (the home page's primary keyword), `titleSuffix?` (defaults to the host), `description`, `locale?` (en_US), `twitter?`, `ogImages`, `organization` and `parent?`.
+
+| Export | What it does |
+| --- | --- |
+| `siteMetadata(site)` | The root layout's `Metadata`: `metadataBase`, title default "keyword · host" and template "%s · host", the clamped description, `applicationName`, openGraph (type, site name, locale, images) and the twitter card. No canonical (a layout canonical leaks into every child) and no icons (the app's icon files). |
+| `homeMetadata(site, { title?, description? })` | `pageMetadata` for `/` with the site's keyword title. |
+| `pageMetadata(site, { path, title, description?, index?, ogType?, images?, modifiedTime?, publishedTime? })` | An absolute "keyword · host" title, the description clamped to 160, `alternates.canonical` and `openGraph.url` set together to the same absolute URL, and a full openGraph and twitter card (images default to `site.ogImages`: Next replaces a layout's openGraph, it doesn't merge it). `index: false` adds noindex, follow. `ogType: "article"` writes the ISO times it has. Throws on a relative path, another origin or a blank title. |
+| `notFoundMetadata(site, what?)` | "Pack not found · host" and noindex, for a `generateMetadata` whose record is missing. |
+| `clampDescription(text, max?)`, `DESCRIPTION_MAX` | One line, at most `max` (160) characters: cut at a word, trailing punctuation dropped, "…" added. |
+| `pageTitle(site, title)`, `TITLE_SEPARATOR` | "keyword · host", the suffix added once. |
+| `robots(site, { allow?, disallow?, aiBots? })` | `MetadataRoute.Robots`: the `*` group, one group naming the allowed AI bots with the same rules (a bot with its own group ignores `*`), a `Disallow: /` group for blocked ones, the sitemap and the host. `aiBots`: `"allow"` (default), `"block-training"`, or `"block-all"` (Bingbot stays, or the site leaves Bing). |
+| `AI_BOTS` | The named crawlers, each `{ userAgent, operator, kind: "training" \| "search", searchEngine? }`: GPTBot, OAI-SearchBot, ChatGPT-User, PerplexityBot, Perplexity-User, ClaudeBot, Claude-SearchBot, Claude-User, anthropic-ai, Google-Extended, Applebot-Extended, Bingbot, CCBot, Bytespider, meta-externalagent. |
+| `sitemapEntries(site, groups)`, `SITEMAP_MAX_URLS` | `MetadataRoute.Sitemap` from groups of paths and `{ path, lastModified?, changeFrequency?, priority? }` records: absolute URLs on the canonical origin, the first entry per URL, `lastModified` only when it's a real date (never made up). Throws past 50,000 URLs or on a priority outside 0 to 1. |
+| `ld.graph(...nodes)` | `{ "@context": "https://schema.org", "@graph": nodes }`. `@context` goes only here. |
+| `ld.organization(org)`, `HARUHIME_ORG` | Organization with `@id` `https://www.haruhime.moe/#organization` and `sameAs` (GitHub, Discord, npm). |
+| `ld.webSite(site, { searchUrlTemplate? })`, `SEARCH_TERM` | WebSite (`#website`) with publisher and parent by `@id`, and a SearchAction when the template holds `{search_term_string}`. |
+| `ld.webApplication(site, { category, name?, description?, features?, path?, browserRequirements? })` | WebApplication (`#app`, or `<path>#app` for a sub-tool), free Offer, operatingSystem "Any", publisher the organization. |
+| `ld.breadcrumbs(site, trail)`, `ld.itemList(site, items, { name? })` | BreadcrumbList and ItemList, positions from 1, absolute URLs. |
+| `ld.faq(items)`, `ld.howTo({ name, description?, steps })` | FAQPage from `{ q, a }` and HowTo with numbered HowToSteps. |
+| `ld.techArticle(site, opts)`, `ld.creativeWork(site, opts)`, `ld.dataset(site, opts)` | TechArticle (author defaults to the organization), CreativeWork and Dataset, with `dateModified` only when known and `isBasedOn` paths resolved. |
+| `serializeLd(data)` | JSON with `<`, `>`, `&`, U+2028 and U+2029 escaped, safe inside a `<script>`. |
+| `llmsTxt({ title, summary, notes?, sections })` | llms.txt (llmstxt.org): H1, blockquote, notes, then `## heading` link lists `- [title](url): note`. Brackets in titles are escaped, spaces and parens in URLs encoded, empty sections left out. |
+| `llmsFull(parts, head?)` | llms-full.txt: each `{ title, url?, markdown }` as its own document, separated by `---`. |
+| `textResponse(body, { maxAge?, sMaxAge?, type? })` | A 200 `text/plain; charset=utf-8` (or `text/markdown`) with public `Cache-Control` (an hour by default) and nosniff. |
+
 ### testing
 
 | Export | What it does |
@@ -211,7 +269,7 @@ For pools.haruhime.moe, `createMongo` runs `onConnect` (the privilege check, ind
 
 ## Compatibility
 
-ES modules for Node 22.12+ on the server. `auth-react` also runs in browsers; its hook and component files keep `"use client"`, and it loads only `react`, `next/navigation.js` and `@haruhimemoe/ui`. `server` loads `node:crypto` for machine auth.
+ES modules for Node 22.12+ on the server. `auth-react` also runs in browsers; its hook and component files keep `"use client"`, and it loads only `react`, `next/navigation.js` and `@haruhimemoe/ui`. `server` loads `node:crypto` for machine auth. `seo` loads nothing at runtime (Next's types only), so it runs anywhere.
 
 ## License
 

package/dist/seo/describe.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file src/seo/describe.ts
+ * @desc Meta descriptions: one line, at most 160 characters, cut at a word with "…" and no
+ *       dangling comma, colon or dash before it (audit O4: pools served a 248-character default).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** The longest description search results show in full. */
+export declare const DESCRIPTION_MAX = 160;
+/**
+ * @function clampDescription
+ * @param text {string} the description, maybe long or spread over lines
+ * @param max {number} the longest result, "…" included (default 160)
+ * @returns {string} the text on one line; when it's longer than max, cut at the last word that
+ *          fits, trailing punctuation dropped, and "…" added. A single word longer than max is
+ *          cut mid-word.
+ * @throws {RangeError} when max is under 2
+ */
+export declare const clampDescription: (text: string, max?: number) => string;

package/dist/seo/describe.js

@@ -0,0 +1,34 @@
+/**
+ * @file src/seo/describe.ts
+ * @desc Meta descriptions: one line, at most 160 characters, cut at a word with "…" and no
+ *       dangling comma, colon or dash before it (audit O4: pools served a 248-character default).
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** The longest description search results show in full. */
+export const DESCRIPTION_MAX = 160;
+const ELLIPSIS = "…";
+/** Punctuation, dashes and open brackets that shouldn't sit right before the "…". */
+const TRAILING = /[\s,;:.!?\-–—(["'“‘/&+]+$/u;
+/**
+ * @function clampDescription
+ * @param text {string} the description, maybe long or spread over lines
+ * @param max {number} the longest result, "…" included (default 160)
+ * @returns {string} the text on one line; when it's longer than max, cut at the last word that
+ *          fits, trailing punctuation dropped, and "…" added. A single word longer than max is
+ *          cut mid-word.
+ * @throws {RangeError} when max is under 2
+ */
+export const clampDescription = (text, max = DESCRIPTION_MAX) => {
+    if (!Number.isInteger(max) || max < 2)
+        throw new RangeError("seo: max must be 2 or more");
+    const line = text.replace(/\s+/g, " ").trim();
+    if (line.length <= max)
+        return line;
+    const room = line.slice(0, max - ELLIPSIS.length + 1);
+    const space = room.lastIndexOf(" ");
+    const cut = space > 0 ? room.slice(0, space) : room.slice(0, max - ELLIPSIS.length);
+    const clean = cut.replace(TRAILING, "");
+    return `${clean || cut}${ELLIPSIS}`;
+};

package/dist/seo/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file src/seo/index.ts
+ * @desc @haruhimemoe/next-kit/seo: metadata for the root layout and every page (canonical and
+ *       og:url together, openGraph never dropped), robots.txt with an explicit AI stance, sitemap
+ *       entries with honest lastmod, schema.org JSON-LD builders and script-safe serialization,
+ *       and llms.txt. No runtime imports: Next's types only, so it runs anywhere.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { clampDescription, DESCRIPTION_MAX } from "./describe.js";
+export { ld, serializeLd } from "./ld.js";
+export type { CreativeWorkOptions, DatasetOptions, HowToOptions, LdAgent, TechArticleOptions, } from "./ld-content.js";
+export { type LdGraph, type LdLink, type LdNode, SEARCH_TERM, type WebApplicationOptions, } from "./ld-site.js";
+export { type LlmsFullPart, type LlmsLink, type LlmsSection, type LlmsTxtOptions, llmsFull, llmsTxt, type TextResponseOptions, textResponse, } from "./llms.js";
+export { homeMetadata, notFoundMetadata, type PageMetadataOptions, pageMetadata, siteMetadata, } from "./metadata.js";
+export { AI_BOTS, type AiBot, type AiBotKind, type AiBotsPolicy, type RobotsOptions, robots, } from "./robots.js";
+export { HARUHIME_ORG, type OgImage, type Organization, pageTitle, type Site, TITLE_SEPARATOR, } from "./site.js";
+export { type ChangeFrequency, SITEMAP_MAX_URLS, type SitemapGroup, type SitemapRecord, sitemapEntries, } from "./sitemap.js";

package/dist/seo/index.js

@@ -0,0 +1,18 @@
+/**
+ * @file src/seo/index.ts
+ * @desc @haruhimemoe/next-kit/seo: metadata for the root layout and every page (canonical and
+ *       og:url together, openGraph never dropped), robots.txt with an explicit AI stance, sitemap
+ *       entries with honest lastmod, schema.org JSON-LD builders and script-safe serialization,
+ *       and llms.txt. No runtime imports: Next's types only, so it runs anywhere.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+export { clampDescription, DESCRIPTION_MAX } from "./describe.js";
+export { ld, serializeLd } from "./ld.js";
+export { SEARCH_TERM, } from "./ld-site.js";
+export { llmsFull, llmsTxt, textResponse, } from "./llms.js";
+export { homeMetadata, notFoundMetadata, pageMetadata, siteMetadata, } from "./metadata.js";
+export { AI_BOTS, robots, } from "./robots.js";
+export { HARUHIME_ORG, pageTitle, TITLE_SEPARATOR, } from "./site.js";
+export { SITEMAP_MAX_URLS, sitemapEntries, } from "./sitemap.js";

package/dist/seo/ld-content.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @file src/seo/ld-content.ts
+ * @desc schema.org JSON-LD for content pages: FAQPage, HowTo, TechArticle, CreativeWork and
+ *       Dataset. Dates go out as ISO 8601 and only when known (audit A5); the author and
+ *       publisher default to the site's organization by @id.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { type LdNode } from "./ld-site.js";
+import { type Site } from "./site.js";
+/** A person or group credited by name, or a node by @id. */
+export type LdAgent = string | {
+    name: string;
+    url?: string;
+} | {
+    "@id": string;
+};
+type When = string | Date | null | undefined;
+/**
+ * @function faq
+ * @param items {readonly { q: string; a: string }[]} the questions and their answers, as shown
+ * @returns {LdNode} FAQPage with one Question and acceptedAnswer per item
+ * @throws {Error} when items is empty
+ */
+export declare const faq: (items: readonly {
+    q: string;
+    a: string;
+}[]) => LdNode;
+/** howTo's input. */
+export type HowToOptions = {
+    name: string;
+    description?: string;
+    steps: readonly {
+        name: string;
+        text: string;
+        url?: string;
+    }[];
+};
+/**
+ * @function howTo
+ * @param options {HowToOptions} the task and its steps, in order
+ * @returns {LdNode} HowTo with HowToSteps numbered from 1
+ * @throws {Error} when steps is empty
+ */
+export declare const howTo: (options: HowToOptions) => LdNode;
+/** techArticle's input. */
+export type TechArticleOptions = {
+    path: string;
+    headline: string;
+    description?: string;
+    dateModified?: When;
+    datePublished?: When;
+    /** Defaults to the site's organization. */
+    author?: LdAgent;
+    /** What the article is about, like "osu! BBCode [imagemap] tag". */
+    about?: string;
+};
+/**
+ * @function techArticle
+ * @param site {Site} the site
+ * @param options {TechArticleOptions} the article
+ * @returns {LdNode} TechArticle with url, mainEntityOfPage, publisher and author
+ */
+export declare const techArticle: (site: Site, options: TechArticleOptions) => LdNode;
+/** creativeWork's input. */
+export type CreativeWorkOptions = {
+    path: string;
+    name: string;
+    description?: string;
+    author?: LdAgent;
+    dateModified?: When;
+    /** What it was made from: a path on this site or an absolute URL, or several. */
+    isBasedOn?: string | readonly string[];
+    numberOfItems?: number;
+    genre?: string;
+};
+/**
+ * @function creativeWork
+ * @param site {Site} the site
+ * @param options {CreativeWorkOptions} the work (a pack, a template, a map page)
+ * @returns {LdNode} CreativeWork with url, publisher, and whatever else is known
+ */
+export declare const creativeWork: (site: Site, options: CreativeWorkOptions) => LdNode;
+/** dataset's input. */
+export type DatasetOptions = {
+    path: string;
+    name: string;
+    /** Google requires 50 to 5000 characters. */
+    description: string;
+    creator?: LdAgent;
+    /** A year or ISO interval, like "2023". */
+    temporalCoverage?: string;
+    isBasedOn?: string | readonly string[];
+    license?: string;
+    dateModified?: When;
+};
+/**
+ * @function dataset
+ * @param site {Site} the site
+ * @param options {DatasetOptions} the dataset (a past tournament pool)
+ * @returns {LdNode} Dataset with url, publisher, and creator as an Organization when given
+ */
+export declare const dataset: (site: Site, options: DatasetOptions) => LdNode;
+export {};

package/dist/seo/ld-content.js

@@ -0,0 +1,120 @@
+/**
+ * @file src/seo/ld-content.ts
+ * @desc schema.org JSON-LD for content pages: FAQPage, HowTo, TechArticle, CreativeWork and
+ *       Dataset. Dates go out as ISO 8601 and only when known (audit A5); the author and
+ *       publisher default to the site's organization by @id.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { orgRef } from "./ld-site.js";
+import { absoluteUrl, compact, isoDate } from "./site.js";
+const agent = (value, type = "Person") => typeof value === "string"
+    ? { "@type": type, name: value }
+    : "@id" in value
+        ? value
+        : compact({ "@type": type, name: value.name, url: value.url });
+const urls = (site, value) => {
+    if (value === undefined)
+        return undefined;
+    const list = (typeof value === "string" ? [value] : [...value]).map((url) => url.startsWith("/") ? absoluteUrl(site, url) : url);
+    return list.length === 1 ? list[0] : list;
+};
+/**
+ * @function faq
+ * @param items {readonly { q: string; a: string }[]} the questions and their answers, as shown
+ * @returns {LdNode} FAQPage with one Question and acceptedAnswer per item
+ * @throws {Error} when items is empty
+ */
+export const faq = (items) => {
+    if (!items.length)
+        throw new Error("seo: a FAQ needs at least one question");
+    return {
+        "@type": "FAQPage",
+        mainEntity: items.map(({ q, a }) => ({
+            "@type": "Question",
+            name: q,
+            acceptedAnswer: { "@type": "Answer", text: a },
+        })),
+    };
+};
+/**
+ * @function howTo
+ * @param options {HowToOptions} the task and its steps, in order
+ * @returns {LdNode} HowTo with HowToSteps numbered from 1
+ * @throws {Error} when steps is empty
+ */
+export const howTo = (options) => {
+    if (!options.steps.length)
+        throw new Error("seo: a HowTo needs at least one step");
+    return compact({
+        "@type": "HowTo",
+        name: options.name,
+        description: options.description,
+        step: options.steps.map((step, i) => compact({
+            "@type": "HowToStep",
+            position: i + 1,
+            name: step.name,
+            text: step.text,
+            url: step.url,
+        })),
+    });
+};
+/**
+ * @function techArticle
+ * @param site {Site} the site
+ * @param options {TechArticleOptions} the article
+ * @returns {LdNode} TechArticle with url, mainEntityOfPage, publisher and author
+ */
+export const techArticle = (site, options) => {
+    const url = absoluteUrl(site, options.path);
+    return compact({
+        "@type": "TechArticle",
+        headline: options.headline,
+        description: options.description,
+        url,
+        mainEntityOfPage: url,
+        about: options.about,
+        datePublished: isoDate(options.datePublished),
+        dateModified: isoDate(options.dateModified),
+        author: options.author ? agent(options.author) : orgRef(site),
+        publisher: orgRef(site),
+    });
+};
+/**
+ * @function creativeWork
+ * @param site {Site} the site
+ * @param options {CreativeWorkOptions} the work (a pack, a template, a map page)
+ * @returns {LdNode} CreativeWork with url, publisher, and whatever else is known
+ */
+export const creativeWork = (site, options) => compact({
+    "@type": "CreativeWork",
+    name: options.name,
+    description: options.description,
+    url: absoluteUrl(site, options.path),
+    author: options.author ? agent(options.author) : undefined,
+    dateModified: isoDate(options.dateModified),
+    isBasedOn: urls(site, options.isBasedOn),
+    numberOfItems: options.numberOfItems,
+    genre: options.genre,
+    publisher: orgRef(site),
+});
+/**
+ * @function dataset
+ * @param site {Site} the site
+ * @param options {DatasetOptions} the dataset (a past tournament pool)
+ * @returns {LdNode} Dataset with url, publisher, and creator as an Organization when given
+ */
+export const dataset = (site, options) => compact({
+    "@type": "Dataset",
+    name: options.name,
+    description: options.description,
+    url: absoluteUrl(site, options.path),
+    creator: options.creator ? agent(options.creator, "Organization") : undefined,
+    temporalCoverage: options.temporalCoverage,
+    isBasedOn: urls(site, options.isBasedOn),
+    license: options.license,
+    dateModified: isoDate(options.dateModified),
+    isAccessibleForFree: true,
+    publisher: orgRef(site),
+});

package/dist/seo/ld-site.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @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 { type Organization, type Site } from "./site.js";
+/** One schema.org node, without `@context`. */
+export type LdNode = {
+    "@type": string;
+    "@id"?: string;
+    [key: string]: unknown;
+};
+/** A JSON-LD document: `@context` once, the nodes in `@graph`. */
+export type LdGraph = {
+    "@context": "https://schema.org";
+    "@graph": LdNode[];
+};
+/** A page named by its path on the site. */
+export type LdLink = {
+    name: string;
+    path: string;
+};
+/** The placeholder a SearchAction's urlTemplate must hold. */
+export declare 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 declare const graph: (...nodes: LdNode[]) => LdGraph;
+/**
+ * @function organization
+ * @param org {Organization} the organization, like HARUHIME_ORG
+ * @returns {LdNode} Organization with @id `${origin}/#organization`
+ */
+export declare const organization: (org: Organization) => LdNode;
+/** A reference to the site's organization by @id. */
+export declare const orgRef: (site: Site) => {
+    "@id": string;
+};
+/**
+ * @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 declare const webSite: (site: Site, options?: {
+    searchUrlTemplate?: string;
+}) => LdNode;
+/** webApplication's input. */
+export type WebApplicationOptions = {
+    /** Defaults to the site's name. */
+    name?: string;
+    /** Defaults to the site's description. */
+    description?: string;
+    /** A schema.org category, like "UtilitiesApplication". */
+    category: string;
+    features?: readonly string[];
+    /** Defaults to "/". A sub-tool (bb's /collab) passes its own path; its @id is then url#app. */
+    path?: string;
+    /** Default "Requires JavaScript. Works in any modern browser." */
+    browserRequirements?: string;
+};
+/**
+ * @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 declare const webApplication: (site: Site, options: WebApplicationOptions) => LdNode;
+/**
+ * @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 declare const breadcrumbs: (site: Site, trail: readonly LdLink[]) => LdNode;
+/**
+ * @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 declare const itemList: (site: Site, items: readonly LdLink[], options?: {
+    name?: string;
+}) => LdNode;