@haruhimemoe/next-kit 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-28
+
+### Added
+
+- `seo`: a short title suffix. `Site.shortTitleSuffix` (like "pools") and `pageMetadata`'s `titleSuffix` option: `"auto"` (the default) keeps "keyword · host" and switches to "keyword · pools" only when the full title passes 60 characters (`TITLE_MAX`) and the site sets a short suffix; `"full"`, `"short"` and `"none"` force one. `pageTitle` takes the same mode (default `"full"`) and `notFoundMetadata` shortens like `"auto"`. Sites without `shortTitleSuffix` get the same titles as before.
+
 ## [0.3.0] - 2026-09-28
 
 ### Added
@@ -46,7 +52,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.3.0...HEAD
+[unreleased]: https://github.com/haruhimemoe/next-kit/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/haruhimemoe/next-kit/compare/v0.3.0...v0.4.0
 [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

package/README.md

@@ -217,16 +217,16 @@ export const GET = () => textResponse(llmsTxt({ title: "pools.haruhime.moe", sum
 
 ### 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?`.
+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), `shortTitleSuffix?` (since 0.4.0, like "pools"), `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. |
+| `pageMetadata(site, { path, title, titleSuffix?, description?, index?, ogType?, images?, modifiedTime?, publishedTime? })` | An absolute "keyword · host" title (`titleSuffix` defaults to `"auto"`: "keyword · pools" when the full title passes 60 characters and the site sets `shortTitleSuffix`; `"full"`, `"short"` or `"none"` force one), 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" (shortened like `"auto"`) 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. |
+| `pageTitle(site, title, mode?)`, `TITLE_SEPARATOR`, `TITLE_MAX`, `TitleSuffixMode` | "keyword · host", the suffix added once (either suffix already there counts). `mode`: `"full"` (default), `"short"` (the full one when the site has none), `"none"`, or `"auto"` (short past `TITLE_MAX`, 60). |
 | `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. |

package/dist/seo/index.d.ts

@@ -15,5 +15,5 @@ export { type LdGraph, type LdLink, type LdNode, SEARCH_TERM, type WebApplicatio
 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 { HARUHIME_ORG, type OgImage, type Organization, pageTitle, type Site, TITLE_MAX, TITLE_SEPARATOR, type TitleSuffixMode, } from "./site.js";
 export { type ChangeFrequency, SITEMAP_MAX_URLS, type SitemapGroup, type SitemapRecord, sitemapEntries, } from "./sitemap.js";

package/dist/seo/index.js

@@ -14,5 +14,5 @@ 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 { HARUHIME_ORG, pageTitle, TITLE_MAX, TITLE_SEPARATOR, } from "./site.js";
 export { SITEMAP_MAX_URLS, sitemapEntries, } from "./sitemap.js";

package/dist/seo/metadata.d.ts

@@ -9,13 +9,18 @@
  * @modified Mon Sep 28, 2026
  */
 import type { Metadata } from "next";
-import { type OgImage, type Site } from "./site.js";
+import { type OgImage, type Site, type TitleSuffixMode } 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;
+    /**
+     * Default "auto": the full suffix, or the site's shortTitleSuffix when the full title would
+     * pass TITLE_MAX (60). "full", "short" and "none" force one.
+     */
+    titleSuffix?: TitleSuffixMode;
     /** Defaults to the site's description. Clamped to 160 characters. */
     description?: string;
     /** false: noindex, follow. Default true. */
@@ -40,7 +45,8 @@ 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
+ * @returns {Metadata} an absolute "keyword · host" title (or "keyword · short" past 60
+ *          characters, see titleSuffix), 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

package/dist/seo/metadata.js

@@ -47,14 +47,15 @@ export const siteMetadata = (site) => {
  * @function pageMetadata
  * @param site {Site} the site
  * @param options {PageMetadataOptions} the page
- * @returns {Metadata} an absolute "keyword · host" title, the clamped description, the
+ * @returns {Metadata} an absolute "keyword · host" title (or "keyword · short" past 60
+ *          characters, see titleSuffix), 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 title = pageTitle(site, options.title, options.titleSuffix ?? "auto");
     const description = clampDescription(options.description ?? site.description);
     const images = [...(options.images ?? site.ogImages)];
     const base = {
@@ -101,6 +102,6 @@ export const homeMetadata = (site, options = {}) => pageMetadata(site, {
  *          records returned {} and got the site's default title)
  */
 export const notFoundMetadata = (site, what = "Page") => ({
-    title: { absolute: pageTitle(site, `${what} not found`) },
+    title: { absolute: pageTitle(site, `${what} not found`, "auto") },
     robots: { index: false, follow: false },
 });

package/dist/seo/site.d.ts

@@ -35,6 +35,8 @@ export type Site = {
     title: string;
     /** What follows " · " in every title. Defaults to the host, like pools.haruhime.moe. */
     titleSuffix?: string;
+    /** A shorter suffix, like "pools", for titles that would pass TITLE_MAX with the full one. */
+    shortTitleSuffix?: string;
     /** The default description, 140 to 160 characters. */
     description: string;
     /** Open Graph locale. Defaults to en_US. */
@@ -79,6 +81,14 @@ export declare const absoluteUrl: (site: Pick<Site, "url">, path: string) => str
  * @returns {string} a stable JSON-LD @id, like https://www.haruhime.moe/#organization
  */
 export declare const nodeId: (url: string, name: string) => string;
+/** The longest title search results show in full; "auto" switches to the short suffix past it. */
+export declare const TITLE_MAX = 60;
+/**
+ * Which suffix a title gets: "full" (titleSuffix or the host), "short" (shortTitleSuffix, else
+ * full), "none" (the keyword alone), or "auto" (full, unless that passes TITLE_MAX and the site
+ * has a shortTitleSuffix).
+ */
+export type TitleSuffixMode = "auto" | "full" | "short" | "none";
 /**
  * @function titleSuffix
  * @param site {Site} the site
@@ -89,10 +99,11 @@ export declare const titleSuffix: (site: Site) => string;
  * @function pageTitle
  * @param site {Site} the site
  * @param title {string} the page's primary keyword, like "Search osu! tournament mappools"
- * @returns {string} "Primary keyword · host" (the suffix is added once, never twice)
+ * @param mode {TitleSuffixMode} which suffix to add (default "full")
+ * @returns {string} "Primary keyword · host" (a suffix already there is never added twice)
  * @throws {Error} when title is blank
  */
-export declare const pageTitle: (site: Site, title: string) => string;
+export declare const pageTitle: (site: Site, title: string, mode?: TitleSuffixMode) => string;
 /**
  * @function isoDate
  * @param value {string | Date | null | undefined} a date, maybe unknown

package/dist/seo/site.js

@@ -55,6 +55,8 @@ export const absoluteUrl = (site, path) => {
  * @returns {string} a stable JSON-LD @id, like https://www.haruhime.moe/#organization
  */
 export const nodeId = (url, name) => `${origin(url)}/#${name}`;
+/** The longest title search results show in full; "auto" switches to the short suffix past it. */
+export const TITLE_MAX = 60;
 /**
  * @function titleSuffix
  * @param site {Site} the site
@@ -65,15 +67,29 @@ export const titleSuffix = (site) => site.titleSuffix ?? new URL(site.url).host;
  * @function pageTitle
  * @param site {Site} the site
  * @param title {string} the page's primary keyword, like "Search osu! tournament mappools"
- * @returns {string} "Primary keyword · host" (the suffix is added once, never twice)
+ * @param mode {TitleSuffixMode} which suffix to add (default "full")
+ * @returns {string} "Primary keyword · host" (a suffix already there is never added twice)
  * @throws {Error} when title is blank
  */
-export const pageTitle = (site, title) => {
+export const pageTitle = (site, title, mode = "full") => {
     const keyword = title.replace(/\s+/g, " ").trim();
     if (!keyword)
         throw new Error("seo: a page title can't be blank");
-    const suffix = `${TITLE_SEPARATOR}${titleSuffix(site)}`;
-    return keyword.endsWith(suffix) ? keyword : `${keyword}${suffix}`;
+    const full = titleSuffix(site);
+    const suffixes = [full, site.shortTitleSuffix]
+        .filter(Boolean)
+        .map((s) => `${TITLE_SEPARATOR}${s}`);
+    if (mode === "none" || suffixes.some((suffix) => keyword.endsWith(suffix)))
+        return keyword;
+    const long = `${keyword}${TITLE_SEPARATOR}${full}`;
+    const short = site.shortTitleSuffix
+        ? `${keyword}${TITLE_SEPARATOR}${site.shortTitleSuffix}`
+        : long;
+    if (mode === "short")
+        return short;
+    if (mode === "auto" && long.length > TITLE_MAX)
+        return short;
+    return long;
 };
 /**
  * @function isoDate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haruhimemoe/next-kit",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The Next.js plumbing the haruhime.moe tools share: JSON route helpers, rate limits and budgets in MongoDB, bearer machine auth, zod env parsing, a connect-once MongoDB client with safe index builds, better-auth with osu! sign-in, the signed-in marker and account store for the browser, and SEO: metadata, robots.txt, sitemaps, JSON-LD and llms.txt.",
   "keywords": [
     "nextjs",