@kitr/seo 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Platon Podkopov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @kitr/seo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**SEO.** Give every page a title, a share preview and a sitemap entry so search engines and chat apps show it well.
+
+```sh
+pnpm kitr add seo
+```
+
+`kitr add` installs the package and wires it into your app: the provider in `kitrrc.ts`, its config file and its `AGENTS.md` section. Import it from `@kitr/seo`.
+
+Read the guide at https://kitr.dev/packages/seo.
+
+Part of [kitr](https://kitr.dev), the TypeScript framework where everything is an add-on. MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+import { BuildPlatformKey } from "@kitr/core";
+/** Site-wide values for `seo()` and the build: name, canonical origin, default image, handle and locale. */
+export interface SeoSite {
+  /** Appended to page titles (`Pricing · Acme`) and sent as `og:site_name`. */
+  name?: string;
+  /** Canonical origin (`https://example.com`). Turns on the sitemap for prerendered routes. */
+  url?: string;
+  /** Share image for pages that set none. Use an absolute URL. */
+  image?: string;
+  /** The site's X (Twitter) handle, sent as `twitter:site`. */
+  twitter?: string;
+  /** Sent as `og:locale`, such as `en_US`. */
+  locale?: string;
+}
+/** Options for `config/seo.ts`. The build reads `prerender`, `site.url` and `robots`; `seo()` reads `site`; the router reads `ssr`. */
+export interface SeoConfig {
+  /** Site-wide defaults for `seo()`. */
+  site?: SeoSite;
+  /** Default rendering for routes that set no `ssr` of their own (the router's `defaultSsr`). `ssrRoute()` overrides it per route. */
+  ssr?: boolean | 'data-only';
+  /** Routes to prerender at build time; `crawlLinks` follows links from them. A `static` web platform prerenders everything. */
+  prerender?: string[] | {
+    routes: string[];
+    crawlLinks?: boolean;
+  };
+  /** Rules for `robotsTxt()`, which the build writes to `robots.txt` unless `public/robots.txt` exists. `false` writes none. */
+  robots?: false | {
+    allow?: string[];
+    disallow?: string[];
+    sitemap?: boolean;
+  };
+}
+declare module '@kitr/core' {
+  interface ConfigRegistry {
+    seo: SeoConfig;
+  }
+}
+/**
+ * Types the default export of `config/seo.ts`. The config lives on the app (`app.config.get('seo')`,
+ * set from the `config` that `app/app.ts` passes to `createApp`), not in this module, so two apps
+ * in one process keep their own site defaults and `seo()` reads them from the app it is given.
+ */
+export declare const defineConfig: <const C extends SeoConfig>(config: C) => C;
+/** What one page passes to `seo()`. Every field is optional; `site` supplies the defaults. */
+export interface SeoInput {
+  /** The page title, without the site name. */
+  title?: string;
+  /** The page summary for search results and share cards. */
+  description?: string;
+  /** Share image for this page; replaces `site.image`. Use an absolute URL. */
+  image?: string;
+  /** The page's canonical URL; falls back to `site.url`, so pass it on every page. */
+  url?: string;
+  /** `og:type`. Default `website`. */
+  type?: 'website' | 'article' | 'product';
+  /** Adds `robots: noindex, nofollow`. */
+  noIndex?: boolean;
+  /** Joined into a `keywords` meta tag. */
+  keywords?: string[];
+  /** Site defaults. Default: `site` from the app's `config/seo.ts`, found through the context passed as `seo`'s second argument. */
+  site?: SeoSite;
+}
+/**
+ * Where `seo()` finds the app for the site defaults: the argument of a route's `head` (its
+ * `match.context.app`, which `createKitrRouter` puts in every route's context), a loader or
+ * `beforeLoad` context, or the app itself.
+ */
+export type SeoContext = object;
+/**
+ * Meta tags for a route's `head()`: `head: (ctx) => seo({ title, description }, ctx)`.
+ * Covers title, description, Open Graph, Twitter cards, canonical and robots. Pass the `head`
+ * argument (or the app) as the second argument so the site name, image and origin from
+ * `config/seo.ts` apply; without it only `input.site` does.
+ */
+export declare function seo(input: SeoInput, context?: SeoContext): {
+  meta: Record<string, string>[];
+  links: Record<string, string>[];
+};
+/** A JSON-LD script for `head().scripts`: `scripts: [jsonLd({ '@type': 'Article', headline })]`. */
+export declare function jsonLd(data: Record<string, unknown> & {
+  '@type': string;
+}): {
+  type: string;
+  children: string;
+};
+/**
+ * JSON for inside a `<script>`: `<`, `>` and `&` as unicode escapes so a value such as
+ * `</script><script>…` from a user's title can't close the tag, and U+2028/U+2029 escaped too.
+ * Still valid JSON: parsers read the escapes back as the same characters.
+ */
+export declare function safeJson(value: unknown): string;
+export type SsrMode = boolean | 'data-only';
+/**
+ * Route option presets. Spread into `createFileRoute(...)({ ...ssrRoute('data-only'), ... })`.
+ * A table picks the mode per platform at build time, by platform name from kitrrc.ts, then type,
+ * then `default`: `ssrRoute({ www: true, web: 'data-only', default: false })` renders the marketing
+ * build on the server, other web builds data-only, and native shells on the client.
+ */
+export declare function ssrRoute(mode: SsrMode | (Partial<Record<BuildPlatformKey, SsrMode>> & {
+  default: SsrMode;
+})): {
+  ssr: SsrMode;
+};
+/**
+ * A `cache-control` header for TanStack Start's `headers` route option:
+ * `headers: () => cacheHeaders({ sMaxAge: 60 })`. Public unless `private` is set.
+ */
+export declare function cacheHeaders(options?: {
+  maxAge?: number;
+  sMaxAge?: number;
+  staleWhileRevalidate?: number;
+  private?: boolean;
+}): {
+  'cache-control': string;
+};
+/** `robots.txt` text from the config, or null when `robots` is false. The build writes it for web platforms. */
+export declare function robotsTxt(config: SeoConfig): string | null;

package/dist/index.js

@@ -0,0 +1,151 @@
+import { createDefineConfig, forBuildPlatform } from "@kitr/core";
+// src/index.ts
+/**
+* Types the default export of `config/seo.ts`. The config lives on the app (`app.config.get('seo')`,
+* set from the `config` that `app/app.ts` passes to `createApp`), not in this module, so two apps
+* in one process keep their own site defaults and `seo()` reads them from the app it is given.
+*/
+const defineConfig = createDefineConfig();
+function appOf(context) {
+	const isApp = (value) => !!value && typeof value === "object" && "config" in value && "container" in value;
+	const candidates = (value) => {
+		const v = value;
+		return [
+			value,
+			v?.app,
+			(v?.context)?.app,
+			(v?.match?.context)?.app
+		];
+	};
+	return candidates(context).find(isApp);
+}
+/**
+* Meta tags for a route's `head()`: `head: (ctx) => seo({ title, description }, ctx)`.
+* Covers title, description, Open Graph, Twitter cards, canonical and robots. Pass the `head`
+* argument (or the app) as the second argument so the site name, image and origin from
+* `config/seo.ts` apply; without it only `input.site` does.
+*/
+function seo(input, context) {
+	const configured = appOf(context)?.config.get("seo", {});
+	const site = input.site ?? configured?.site ?? {};
+	const title = input.title ? site.name && input.title !== site.name ? `${input.title} · ${site.name}` : input.title : site.name;
+	const image = input.image ?? site.image;
+	const url = input.url ?? site.url;
+	const meta = [];
+	if (title) meta.push({ title }, {
+		property: "og:title",
+		content: input.title ?? title
+	}, {
+		name: "twitter:title",
+		content: input.title ?? title
+	});
+	if (input.description) meta.push({
+		name: "description",
+		content: input.description
+	}, {
+		property: "og:description",
+		content: input.description
+	}, {
+		name: "twitter:description",
+		content: input.description
+	});
+	meta.push({
+		property: "og:type",
+		content: input.type ?? "website"
+	});
+	if (site.name) meta.push({
+		property: "og:site_name",
+		content: site.name
+	});
+	if (site.locale) meta.push({
+		property: "og:locale",
+		content: site.locale
+	});
+	if (url) meta.push({
+		property: "og:url",
+		content: url
+	});
+	if (image) meta.push({
+		property: "og:image",
+		content: image
+	}, {
+		name: "twitter:image",
+		content: image
+	}, {
+		name: "twitter:card",
+		content: "summary_large_image"
+	});
+	else meta.push({
+		name: "twitter:card",
+		content: "summary"
+	});
+	if (site.twitter) meta.push({
+		name: "twitter:site",
+		content: site.twitter
+	});
+	if (input.keywords?.length) meta.push({
+		name: "keywords",
+		content: input.keywords.join(", ")
+	});
+	if (input.noIndex) meta.push({
+		name: "robots",
+		content: "noindex, nofollow"
+	});
+	return {
+		meta,
+		links: url ? [{
+			rel: "canonical",
+			href: url
+		}] : []
+	};
+}
+/** A JSON-LD script for `head().scripts`: `scripts: [jsonLd({ '@type': 'Article', headline })]`. */
+function jsonLd(data) {
+	return {
+		type: "application/ld+json",
+		children: safeJson({
+			"@context": "https://schema.org",
+			...data
+		})
+	};
+}
+/**
+* JSON for inside a `<script>`: `<`, `>` and `&` as unicode escapes so a value such as
+* `<\/script><script>…` from a user's title can't close the tag, and U+2028/U+2029 escaped too.
+* Still valid JSON: parsers read the escapes back as the same characters.
+*/
+function safeJson(value) {
+	return JSON.stringify(value).replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+/**
+* Route option presets. Spread into `createFileRoute(...)({ ...ssrRoute('data-only'), ... })`.
+* A table picks the mode per platform at build time, by platform name from kitrrc.ts, then type,
+* then `default`: `ssrRoute({ www: true, web: 'data-only', default: false })` renders the marketing
+* build on the server, other web builds data-only, and native shells on the client.
+*/
+function ssrRoute(mode) {
+	if (typeof mode === "object") return { ssr: forBuildPlatform(mode) };
+	return { ssr: mode };
+}
+/**
+* A `cache-control` header for TanStack Start's `headers` route option:
+* `headers: () => cacheHeaders({ sMaxAge: 60 })`. Public unless `private` is set.
+*/
+function cacheHeaders(options = {}) {
+	const parts = [options.private ? "private" : "public"];
+	if (options.maxAge !== void 0) parts.push(`max-age=${options.maxAge}`);
+	if (options.sMaxAge !== void 0) parts.push(`s-maxage=${options.sMaxAge}`);
+	if (options.staleWhileRevalidate !== void 0) parts.push(`stale-while-revalidate=${options.staleWhileRevalidate}`);
+	return { "cache-control": parts.join(", ") };
+}
+/** `robots.txt` text from the config, or null when `robots` is false. The build writes it for web platforms. */
+function robotsTxt(config) {
+	if (config.robots === false) return null;
+	const rules = config.robots ?? {};
+	const lines = ["User-agent: *"];
+	for (const p of rules.allow ?? ["/"]) lines.push(`Allow: ${p}`);
+	for (const p of rules.disallow ?? []) lines.push(`Disallow: ${p}`);
+	if ((rules.sitemap ?? true) && config.site?.url) lines.push("", `Sitemap: ${config.site.url.replace(/\/$/, "")}/sitemap.xml`);
+	return `${lines.join("\n")}\n`;
+}
+export { cacheHeaders, defineConfig, jsonLd, robotsTxt, safeJson, seo, ssrRoute };

package/dist/kitr.d.ts

@@ -0,0 +1,11 @@
+/** `kitr add seo`: head helpers, JSON-LD, per-route rendering defaults, prerender list, robots and sitemap. */
+declare const _default: {
+  readonly name: "seo";
+  readonly client: true;
+  readonly add: (ctx: import("@kitr/core/package").AddContext) => void;
+  readonly remove: (ctx: import("@kitr/core/package").AddContext) => void;
+  readonly eject: {
+    readonly '@kitr/seo': "meta tags in head()";
+  };
+};
+export { _default as default };

package/dist/kitr.js

@@ -0,0 +1,16 @@
+import { definePackage } from "@kitr/core/package";
+// src/kitr.ts
+/** `kitr add seo`: head helpers, JSON-LD, per-route rendering defaults, prerender list, robots and sitemap. */
+var kitr_default = definePackage({
+	name: "seo",
+	client: true,
+	add(ctx) {
+		ctx.config("seo", `import { defineConfig } from '@kitr/seo'\n\nexport default defineConfig({\n  site: { name: '${ctx.pkg.name ?? "My app"}' },\n  // Routes prerendered at build time by a web platform in ssr mode; a static web platform prerenders everything.\n  prerender: [],\n})\n`);
+		ctx.agents.add("seo", `- \`head: (ctx) => seo({ title, description }, ctx)\` from \`@kitr/seo\` writes title, Open Graph, Twitter and canonical tags; \`jsonLd({...})\` adds structured data. Site defaults live in \`config/seo.ts\`.\n- Use \`...ssrRoute('data-only')\` for heavy, non-SEO pages; \`cacheHeaders({ sMaxAge })\` for the CDN.`);
+	},
+	remove(ctx) {
+		ctx.agents.remove("seo");
+	},
+	eject: { "@kitr/seo": "meta tags in head()" }
+});
+export { kitr_default as default };

package/docs/api.md

@@ -0,0 +1,183 @@
+---
+title: API reference
+description: Every export of @kitr/seo, with its signature.
+order: 2
+---
+
+# API reference
+
+Every export of `@kitr/seo`, read from the published type definitions. The [guide](/packages/seo/guide) shows them in use.
+
+## @kitr/seo
+
+### cacheHeaders
+
+```ts
+function cacheHeaders(options?: {
+  maxAge?: number;
+  sMaxAge?: number;
+  staleWhileRevalidate?: number;
+  private?: boolean;
+}): {
+  'cache-control': string;
+};
+```
+
+A `cache-control` header for TanStack Start's `headers` route option:
+`headers: () => cacheHeaders({ sMaxAge: 60 })`. Public unless `private` is set.
+
+### jsonLd
+
+```ts
+function jsonLd(data: Record<string, unknown> & {
+  '@type': string;
+}): {
+  type: string;
+  children: string;
+};
+```
+
+A JSON-LD script for `head().scripts`: `scripts: [jsonLd({ '@type': 'Article', headline })]`.
+
+### robotsTxt
+
+```ts
+function robotsTxt(config: SeoConfig): string | null;
+```
+
+`robots.txt` text from the config, or null when `robots` is false. The build writes it for web platforms.
+
+### safeJson
+
+```ts
+function safeJson(value: unknown): string;
+```
+
+JSON for inside a `<script>`: `<`, `>` and `&` as unicode escapes so a value such as
+`</script><script>…` from a user's title can't close the tag, and U+2028/U+2029 escaped too.
+Still valid JSON: parsers read the escapes back as the same characters.
+
+### seo
+
+```ts
+function seo(input: SeoInput, context?: SeoContext): {
+  meta: Record<string, string>[];
+  links: Record<string, string>[];
+};
+```
+
+Meta tags for a route's `head()`: `head: (ctx) => seo({ title, description }, ctx)`.
+Covers title, description, Open Graph, Twitter cards, canonical and robots. Pass the `head`
+argument (or the app) as the second argument so the site name, image and origin from
+`config/seo.ts` apply; without it only `input.site` does.
+
+### ssrRoute
+
+```ts
+function ssrRoute(mode: SsrMode | (Partial<Record<BuildPlatformKey, SsrMode>> & {
+  default: SsrMode;
+})): {
+  ssr: SsrMode;
+};
+```
+
+Route option presets. Spread into `createFileRoute(...)({ ...ssrRoute('data-only'), ... })`.
+A table picks the mode per platform at build time, by platform name from kitrrc.ts, then type,
+then `default`: `ssrRoute({ www: true, web: 'data-only', default: false })` renders the marketing
+build on the server, other web builds data-only, and native shells on the client.
+
+### defineConfig
+
+```ts
+const defineConfig: <const C extends SeoConfig>(config: C) => C;
+```
+
+Types the default export of `config/seo.ts`. The config lives on the app (`app.config.get('seo')`,
+set from the `config` that `app/app.ts` passes to `createApp`), not in this module, so two apps
+in one process keep their own site defaults and `seo()` reads them from the app it is given.
+
+### SeoConfig
+
+```ts
+interface SeoConfig {
+  /** Site-wide defaults for `seo()`. */
+  site?: SeoSite;
+  /** Default rendering for routes that set no `ssr` of their own (the router's `defaultSsr`). `ssrRoute()` overrides it per route. */
+  ssr?: boolean | 'data-only';
+  /** Routes to prerender at build time; `crawlLinks` follows links from them. A `static` web platform prerenders everything. */
+  prerender?: string[] | {
+    routes: string[];
+    crawlLinks?: boolean;
+  };
+  /** Rules for `robotsTxt()`, which the build writes to `robots.txt` unless `public/robots.txt` exists. `false` writes none. */
+  robots?: false | {
+    allow?: string[];
+    disallow?: string[];
+    sitemap?: boolean;
+  };
+}
+```
+
+Options for `config/seo.ts`. The build reads `prerender`, `site.url` and `robots`; `seo()` reads `site`; the router reads `ssr`.
+
+### SeoInput
+
+```ts
+interface SeoInput {
+  /** The page title, without the site name. */
+  title?: string;
+  /** The page summary for search results and share cards. */
+  description?: string;
+  /** Share image for this page; replaces `site.image`. Use an absolute URL. */
+  image?: string;
+  /** The page's canonical URL; falls back to `site.url`, so pass it on every page. */
+  url?: string;
+  /** `og:type`. Default `website`. */
+  type?: 'website' | 'article' | 'product';
+  /** Adds `robots: noindex, nofollow`. */
+  noIndex?: boolean;
+  /** Joined into a `keywords` meta tag. */
+  keywords?: string[];
+  /** Site defaults. Default: `site` from the app's `config/seo.ts`, found through the context passed as `seo`'s second argument. */
+  site?: SeoSite;
+}
+```
+
+What one page passes to `seo()`. Every field is optional; `site` supplies the defaults.
+
+### SeoSite
+
+```ts
+interface SeoSite {
+  /** Appended to page titles (`Pricing · Acme`) and sent as `og:site_name`. */
+  name?: string;
+  /** Canonical origin (`https://example.com`). Turns on the sitemap for prerendered routes. */
+  url?: string;
+  /** Share image for pages that set none. Use an absolute URL. */
+  image?: string;
+  /** The site's X (Twitter) handle, sent as `twitter:site`. */
+  twitter?: string;
+  /** Sent as `og:locale`, such as `en_US`. */
+  locale?: string;
+}
+```
+
+Site-wide values for `seo()` and the build: name, canonical origin, default image, handle and locale.
+
+### SeoContext
+
+```ts
+type SeoContext = object;
+```
+
+Where `seo()` finds the app for the site defaults: the argument of a route's `head` (its
+`match.context.app`, which `createKitrRouter` puts in every route's context), a loader or
+`beforeLoad` context, or the app itself.
+
+### SsrMode
+
+```ts
+type SsrMode = boolean | 'data-only';
+```
+
+<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->

package/docs/index.md

@@ -0,0 +1,541 @@
+---
+title: SEO
+description: Give every page a title, a share preview and a sitemap entry so search engines and chat apps show it well.
+order: 1
+---
+
+# SEO
+
+Paste a link into Slack or search for your product, and what people see comes from a few tags: title, description, share image. `@kitr/seo` writes them from one call, `seo({ title, description })`, adds structured data, and tells the build which pages to prerender. It builds on [TanStack Router's `head`](https://tanstack.com/router/latest/docs/framework/react/guide/document-head-management) and [TanStack Start's prerendering](https://tanstack.com/start/latest/docs/framework/react/guide/static-prerendering).
+
+> [!SUMMARY]
+> Gives every page a title, a share preview and a sitemap entry so search engines and chat apps show it well. Add it with `kitr add seo`; the overview is at [/packages/seo](/packages/seo).
+
+The helpers are plain functions that the server renders into HTML and the client keeps up to date. The examples follow Acme's marketing site at `acme.com`.
+
+> [!WARNING] Needs ssr or static mode
+> Tags only help when the HTML reaches crawlers. In an `spa` app, crawlers and link previews see the same empty shell for every URL.
+
+## Install
+
+```sh
+kitr add seo
+```
+
+<details>
+<summary>Everything kitr add changes</summary>
+
+What `kitr add` does:
+
+- Installs `@kitr/seo`.
+- Adds `'@kitr/seo'` to `packages` in `kitrrc.ts`. It registers no provider, so nothing runs at startup.
+- Writes `config/seo.ts` (shown in [Configure](#configure)) and regenerates `config/index.ts`.
+- Adds a `## kitr: seo` section to `AGENTS.md` telling coding agents to set `head: (ctx) => seo({ title, description }, ctx)` on routes, to add structured data with `jsonLd()`, and to use `ssrRoute()` and `cacheHeaders()` for rendering and CDN caching.
+
+It asks no questions and adds no env variables. The `fullstack`, `saas`, `site` and `realtime` kits include seo; the `site` kit writes its own `config/seo.ts`. In a server-only project `kitr add seo` prints a warning and skips it.
+
+`kitr remove seo` removes the `packages` entry, the dependency and the `AGENTS.md` section, and deletes `config/seo.ts`. It leaves the `seo()` calls in your routes.
+
+</details>
+
+To edit `package.json` without running the package manager, pass `--no-install`:
+
+```sh
+kitr add seo --no-install
+```
+
+## Configure
+
+`kitr add seo` writes this file, with `name` set to the `name` in your `package.json` (here `acme-site`):
+
+```ts
+// config/seo.ts
+import { defineConfig } from '@kitr/seo'
+
+export default defineConfig({
+  site: { name: 'acme-site' },
+  // Routes prerendered at build time by a web platform in ssr mode; a static web platform prerenders everything.
+  prerender: [],
+})
+```
+
+Fill in the rest of `site` before you launch:
+
+```ts
+// config/seo.ts
+import { defineConfig } from '@kitr/seo'
+
+export default defineConfig({
+  site: {
+    name: 'Acme',
+    url: 'https://acme.com',
+    image: 'https://acme.com/og/default.png',
+    twitter: '@acme',
+    locale: 'en_US',
+  },
+  prerender: { routes: ['/', '/pricing', '/blog'], crawlLinks: true },
+  robots: { disallow: ['/api'] },
+})
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `site.name` | none | Appended to page titles (`Pricing · Acme`) and sent as `og:site_name`. Also the title of a page that sets none. |
+| `site.url` | none | The site's address, `https://acme.com`. Turns on the [sitemap](#generate-a-sitemap). |
+| `site.image` | none | The share image for pages that set none. Use an absolute URL. |
+| `site.twitter` | none | The site's X (Twitter) handle, sent as `twitter:site`. |
+| `site.locale` | none | Sent as `og:locale`, such as `en_US`. |
+| `prerender` | `[]` | Routes the build renders to HTML files. An array of paths, or `{ routes, crawlLinks }`. |
+| `prerender.routes` | `[]` | The paths to prerender, such as `['/', '/pricing']`. |
+| `prerender.crawlLinks` | `false` | Also prerender every page linked from those routes. |
+| `robots` | `{}` | Rules for the `robots.txt` the build writes (see [Write robots.txt](#write-robotstxt)). `false` writes none. |
+| `robots.allow` | `['/']` | `Allow:` lines. |
+| `robots.disallow` | `[]` | `Disallow:` lines. |
+| `robots.sitemap` | `true` | Add `Sitemap: <site.url>/sitemap.xml` when `site.url` is set. |
+| `ssr` | `true` | How routes without their own `ssr` render: `true`, `'data-only'` or `false`. [`ssrRoute()`](#choose-how-a-route-renders) on a route overrides it. |
+
+> [!WARNING] Write them as literals
+> The build reads `prerender` and `site.url` from the file's source text without running it, so a value from an env variable or another file is not seen.
+
+`seo()` uses `site` as its defaults, finding the app through the `ctx` you pass it.
+
+## Give a page its title
+
+Set `head` on a route and return `seo()` from it, passing the `head` argument as the second argument so it can find the app's site defaults:
+
+```ts
+// app/routes.ts
+import { seo } from '@kitr/seo'
+
+r.page('/pricing', {
+  head: (ctx) => seo({ title: 'Pricing', description: 'Plans for every team size.' }, ctx),
+  lazy: () => import('./pages/pricing'),
+})
+```
+
+```tsx
+// app/pages/pricing.tsx
+export default function PricingPage() {
+  return <h1>Pricing</h1>
+}
+```
+
+View the page source of `/pricing`. The root route's `<HeadContent />` renders the tags into `<head>`:
+
+```html
+<title>Pricing</title>
+<meta property="og:title" content="Pricing">
+<meta name="twitter:title" content="Pricing">
+<meta name="description" content="Plans for every team size.">
+<meta property="og:description" content="Plans for every team size.">
+<meta name="twitter:description" content="Plans for every team size.">
+<meta property="og:type" content="website">
+<meta name="twitter:card" content="summary">
+```
+
+`seo()` returns `{ meta, links }`, the shape TanStack Router's `head` expects; the router swaps the tags on navigation.
+
+## Use your site defaults on every page
+
+`seo()` takes the site name, share image, handle and locale from `site`, so every title gets the site name once you pass `ctx`. Give each page its own URL:
+
+```ts
+// app/routes.ts
+import { seo } from '@kitr/seo'
+
+r.page('/pricing', {
+  head: (ctx) =>
+    seo(
+      {
+        title: 'Pricing',
+        description: 'Plans for every team size.',
+        url: 'https://acme.com/pricing',
+      },
+      ctx,
+    ),
+  lazy: () => import('./pages/pricing'),
+})
+```
+
+With the config from [Configure](#configure), the title becomes `Pricing · Acme`, and `og:site_name`, `og:locale`, `og:url`, `og:image`, `twitter:site` and a canonical link are filled in. A `site` passed to `seo()` replaces the config's, for a page that belongs to another brand. How the values combine:
+
+| Tag | Comes from |
+| --- | --- |
+| `<title>` | `title · site.name`; `title` alone when it equals `site.name`; `site.name` when there is no `title`. |
+| `og:title`, `twitter:title` | `title` without the site name. |
+| `description`, `og:description`, `twitter:description` | `description`, only when set. |
+| `og:url`, canonical link | `url`, else `site.url`. |
+| `og:image`, `twitter:image` | `image`, else `site.image`. |
+| `twitter:card` | `summary_large_image` when there is an image, else `summary`. |
+| `og:type` | `type`, default `'website'`. |
+
+> [!WARNING] Pass url on every page
+> Without it, `og:url` and the canonical link fall back to `site.url`, so the page tells search engines it is a copy of your home page and they may drop it.
+
+## Set defaults in the root route
+
+Tags from the root route apply to every page; a child route's `<title>` and tags with the same `name` or `property` replace the root's. Put the site-wide description in the root:
+
+```tsx
+// app/document.tsx
+import { HeadContent, Outlet, Scripts } from '@kitr/router'
+import { seo } from '@kitr/seo'
+
+/** `app/routes.ts` passes this to `.root({ head, component: RootDocument })`. */
+export function head(ctx: object) {
+  return {
+    meta: [
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+      ...seo({ description: 'Acme keeps your team’s projects, orders and invoices in one place.' }, ctx).meta,
+    ],
+  }
+}
+
+export function RootDocument() {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <Outlet />
+        <Scripts />
+      </body>
+    </html>
+  )
+}
+```
+
+> [!WARNING] Spread only .meta in the root
+> TanStack Router merges `links` from every matched route without removing duplicates, so a canonical link in the root plus the page's gives two canonical URLs.
+
+## Add a share image
+
+Chat apps show `og:image` as a large card. Pass an absolute URL, since most crawlers do not resolve a relative path:
+
+```ts
+// app/routes.ts
+import { seo } from '@kitr/seo'
+
+r.page('/pricing', {
+  head: (ctx) =>
+    seo(
+      {
+        title: 'Pricing',
+        description: 'Plans for every team size.',
+        url: 'https://acme.com/pricing',
+        image: 'https://acme.com/og/pricing.png',
+      },
+      ctx,
+    ),
+  lazy: () => import('./pages/pricing'),
+})
+```
+
+```tsx
+// app/pages/pricing.tsx
+export default () => <h1>Pricing</h1>
+```
+
+A 1200 × 630 PNG or JPEG works everywhere. Check the result with a preview tool such as [opengraph.xyz](https://www.opengraph.xyz) after you deploy.
+
+## Describe an article
+
+For a blog post, build the tags from the loader's data and set `type: 'article'`:
+
+```ts
+// app/routes.ts
+import { notFound } from '@kitr/router'
+import { getPost } from '#app/content/posts'
+import { seo } from '@kitr/seo'
+
+r.page('/blog/$slug', {
+  loader: ({ params }) => {
+    const post = getPost(params.slug)
+    if (!post) throw notFound()
+    return post
+  },
+  head: (ctx) =>
+    seo(
+      {
+        title: ctx.loaderData?.title,
+        description: ctx.loaderData?.excerpt,
+        url: `https://acme.com/blog/${ctx.params.slug}`,
+        type: 'article',
+        keywords: ctx.loaderData?.tags,
+      },
+      ctx,
+    ),
+  lazy: () => import('./pages/blog/slug'),
+})
+```
+
+```tsx
+// app/pages/blog/slug.tsx
+import { getRouteApi } from '@kitr/router'
+
+const route = getRouteApi('/blog/$slug')
+
+export default function PostPage() {
+  const post = route.useLoaderData()
+  return <h1>{post.title}</h1>
+}
+```
+
+`head` runs after the loader, on the server for the first request and on the client after each navigation. Search engines ignore `keywords`; it only helps your own site search.
+
+## Keep a page out of search results
+
+Sign-in pages, drafts and anything behind a login should stay out of search. Pass `noIndex: true`:
+
+```ts
+// app/routes.ts
+import { seo } from '@kitr/seo'
+
+r.page('/sign-in', {
+  head: (ctx) => seo({ title: 'Sign in', url: 'https://acme.com/sign-in', noIndex: true }, ctx),
+  lazy: () => import('./pages/sign-in'),
+})
+```
+
+```tsx
+// app/pages/sign-in.tsx
+export default () => <h1>Sign in to Acme</h1>
+```
+
+To keep a whole area out, such as `/app`, set `noIndex` in its layout route's `head`.
+
+> [!WARNING] Don't also block it in robots.txt
+> Crawlers must load the page to see the `noindex` tag.
+
+## Add structured data
+
+Structured data tells search engines what a page is about. `jsonLd()` turns a [schema.org](https://schema.org) object into a `<script type="application/ld+json">` for `head().scripts`, and adds `@context`:
+
+```ts
+// app/routes.ts
+import { jsonLd, seo } from '@kitr/seo'
+
+r.page('/', {
+  head: (ctx) => ({
+    ...seo({ title: 'Acme', url: 'https://acme.com' }, ctx),
+    scripts: [
+      jsonLd({
+        '@type': 'Organization',
+        name: 'Acme',
+        url: 'https://acme.com',
+        logo: 'https://acme.com/logo.png',
+      }),
+    ],
+  }),
+  lazy: () => import('./pages/index'),
+})
+```
+
+```tsx
+// app/pages/index.tsx
+export default () => <h1>Acme</h1>
+```
+
+Test the page with Google's [Rich Results Test](https://search.google.com/test/rich-results). `jsonLd()` escapes the JSON for a `<script>` tag (`<`, `>`, `&` and the line separators), so values from users are safe to pass. The same escaping is exported as `safeJson(value)` for your own inline scripts:
+
+```ts
+import { safeJson } from '@kitr/seo'
+
+safeJson({ headline: 'Q3 </script> report' })
+// => {"headline":"Q3 \u003c/script\u003e report"} (the string's characters)
+```
+
+## Prerender pages at build time
+
+Pages that are the same for every visitor can be built once into HTML files and served from a CDN. List them in `prerender`:
+
+```ts
+// config/seo.ts
+import { defineConfig } from '@kitr/seo'
+
+export default defineConfig({
+  site: { name: 'Acme', url: 'https://acme.com' },
+  prerender: { routes: ['/', '/pricing', '/blog'], crawlLinks: true },
+})
+```
+
+Then build the web platform:
+
+```sh
+kitr build site
+```
+
+Each route renders to `index.html` in its own folder (`/pricing/index.html`). With `crawlLinks: true` it also follows every link on those pages, so each blog post linked from `/blog` is prerendered too. Other pages keep rendering per request.
+
+What the build does with `prerender` in each web mode:
+
+| Web mode | Effect |
+| --- | --- |
+| `ssr` | Prerenders the listed routes (and the pages they link to, with `crawlLinks`). Everything else renders on the server. |
+| `static` | Prerenders every page, starting from `/` and following links. |
+| `spa` | Ignored. The build writes one HTML shell. |
+
+> [!WARNING] No computed lists
+> `prerender: posts.map(...)` is not seen. Write each path as a string, or list a page that links to all of them with `crawlLinks: true`.
+
+## Generate a sitemap
+
+Set `site.url` to a string literal, as in the config above, and the build turns on [TanStack Start's sitemap](https://tanstack.com/start/latest/docs/framework/react/guide/static-prerendering) with that host. It writes `sitemap.xml` from the pages it prerenders, so prerender (or crawl to) every page you want listed. `robotsTxt()` points crawlers at `<site.url>/sitemap.xml`.
+
+> [!WARNING] Quoted string only
+> `url: process.env.SITE_URL` does not turn the sitemap on: the build matches the source text.
+
+## Write robots.txt
+
+`robotsTxt(config)` returns the text of a `robots.txt` built from `robots` and `site.url`:
+
+```ts
+import { robotsTxt } from '@kitr/seo'
+
+robotsTxt({ site: { url: 'https://acme.com' }, robots: { disallow: ['/app', '/api'] } })
+// => 'User-agent: *\nAllow: /\nDisallow: /app\nDisallow: /api\n\nSitemap: https://acme.com/sitemap.xml\n'
+```
+
+The web build writes this text to `robots.txt` from `config/seo.ts`. It writes nothing when `robots` is `false`, and leaves your own `public/robots.txt` alone.
+
+## Choose how a route renders
+
+In `ssr` mode every route renders on the server by default, or as `ssr` in `config/seo.ts` says. Spread `ssrRoute()` into a route to change it for that route:
+
+```ts
+// app/routes.ts
+import { ssrRoute } from '@kitr/seo'
+
+app.page('/reports', {
+  ...ssrRoute('data-only'),
+  loader: async () => {
+    const response = await fetch('https://app.acme.com/api/reports/invoices')
+    return (await response.json()) as Array<{ month: string; total: number }>
+  },
+  lazy: () => import('./pages/reports'),
+})
+```
+
+```tsx
+// app/pages/reports.tsx
+import { getRouteApi } from '@kitr/router'
+
+const route = getRouteApi('/_app/reports')
+
+export default function ReportsPage() {
+  const rows = route.useLoaderData()
+  return <p>{rows.length} months of invoices</p>
+}
+```
+
+| Call | Returns | The route |
+| --- | --- | --- |
+| `ssrRoute(true)` | `{ ssr: true }` | Renders on the server. The default unless `config/seo.ts` sets `ssr`. |
+| `ssrRoute('data-only')` | `{ ssr: 'data-only' }` | Runs the loader on the server, renders in the browser. For heavy charts that crawlers don't need. |
+| `ssrRoute(false)` | `{ ssr: false }` | Loads and renders in the browser only. For pages that need `window`. |
+
+> [!WARNING] Crawlers need ssr: true
+> A route that does not render on the server sends no page content to crawlers. See TanStack Start's [selective SSR](https://tanstack.com/start/latest/docs/framework/react/guide/selective-ssr) for how it combines with parent routes.
+
+When one route table serves several platforms, the mode can differ per platform, resolved at build time by platform name, then type, then `default`:
+
+```ts
+// app/routes.ts
+import { ssrRoute } from '@kitr/seo'
+
+r.page('/', {
+  // The marketing build renders on the server for crawlers; the authed web app runs the loader
+  // on the server and renders in the browser; native shells have no server at all.
+  ...ssrRoute({ www: true, web: 'data-only', default: false }),
+  lazy: () => import('./pages/home'),
+})
+```
+
+The value is a constant in each bundle, so there is no run-time check.
+
+## Cache pages at the CDN
+
+`cacheHeaders()` builds a `cache-control` header for TanStack Start's `headers` route option:
+
+```ts
+// app/routes.ts
+import { cacheHeaders } from '@kitr/seo'
+import { seo } from '@kitr/seo'
+
+r.page('/blog/', {
+  headers: () => cacheHeaders({ sMaxAge: 60, staleWhileRevalidate: 300 }),
+  head: (ctx) => seo({ title: 'Blog', url: 'https://acme.com/blog' }, ctx),
+  lazy: () => import('./pages/blog/index'),
+})
+```
+
+```tsx
+// app/pages/blog/index.tsx
+export default () => <h1>Blog</h1>
+```
+
+```ts
+// => { 'cache-control': 'public, s-maxage=60, stale-while-revalidate=300' }
+```
+
+| Option | Adds |
+| --- | --- |
+| `maxAge` | `max-age=<seconds>`: how long browsers keep it. |
+| `sMaxAge` | `s-maxage=<seconds>`: how long CDNs and shared caches keep it. |
+| `staleWhileRevalidate` | `stale-while-revalidate=<seconds>`: how long a cache may serve the old copy while fetching a new one. |
+| `private` | Starts with `private` instead of `public`, so shared caches don't store it. |
+
+With no options it returns `{ 'cache-control': 'public' }`.
+
+> [!WARNING] Private pages
+> For a page that shows the signed-in user, use `cacheHeaders({ private: true, maxAge: 0 })`; a `public` header could let a CDN serve one person's page to another.
+
+## Testing
+
+`seo()` is a plain function, so test what your pages put in `head` without rendering. Make an app from `config/seo.ts`, pass it as the second argument, and assert on the tags:
+
+```ts
+// app/seo.test.ts
+import { createApp } from 'kitr/app'
+import { robotsTxt, seo } from '@kitr/seo'
+import { describe, expect, it } from 'vitest'
+import seoConfig from '#config/seo'
+
+const app = createApp({ config: { seo: seoConfig } })
+
+describe('seo', () => {
+  it('adds the site name and the canonical URL', () => {
+    const { meta, links } = seo(
+      {
+        title: 'Pricing',
+        description: 'Plans for every team size.',
+        url: 'https://acme.com/pricing',
+      },
+      app,
+    )
+    expect(meta).toContainEqual({ title: 'Pricing · Acme' })
+    expect(meta).toContainEqual({ property: 'og:title', content: 'Pricing' })
+    expect(meta).toContainEqual({ name: 'twitter:card', content: 'summary_large_image' })
+    expect(links).toEqual([{ rel: 'canonical', href: 'https://acme.com/pricing' }])
+  })
+
+  it('keeps the sign-in page out of search results', () => {
+    const { meta } = seo({ title: 'Sign in', url: 'https://acme.com/sign-in', noIndex: true }, app)
+    expect(meta).toContainEqual({ name: 'robots', content: 'noindex, nofollow' })
+  })
+
+  it('points crawlers at the sitemap', () => {
+    expect(robotsTxt(seoConfig)).toContain('Sitemap: https://acme.com/sitemap.xml')
+  })
+})
+```
+
+To check the final HTML of a prerendered page, run `kitr build site` and read `/pricing/index.html` from the build output.
+
+## Next steps
+
+- [API reference](/packages/seo/api): every export and type.
+- [Web](/packages/web): the `ssr`, `static` and `spa` modes that decide what crawlers see.
+- [Router](/packages/router): routes, loaders and `notFound()`.

package/docs/overview.md

@@ -0,0 +1,71 @@
+---
+title: Overview
+description: Give every page a title, a share preview and a sitemap entry so search engines and chat apps show it well.
+order: 0
+---
+
+# SEO
+
+## What it is
+
+`@kitr/seo` gives a route its tags in one call, `seo({ title, description })`, with site defaults from `config/seo.ts`. `jsonLd()` adds structured data, `ssrRoute()` picks how a route renders, and the build writes the sitemap and `robots.txt`.
+
+Runs on both sides. Tags only help when crawlers get HTML, so use the [web](/packages/web) platform in `ssr` or `static` mode.
+
+## Install
+
+```sh
+kitr add seo
+```
+
+Adds `@kitr/seo` and `config/seo.ts`. No provider. [Every change](/packages/seo/guide#install).
+
+## Quick start
+
+Set `head` on a route and return `seo()` from it:
+
+```ts
+// app/routes.ts
+import { seo } from '@kitr/seo'
+
+r.page('/pricing', {
+  head: () => seo({ title: 'Pricing', description: 'Plans for every team size.' }),
+  lazy: () => import('./pages/pricing'),
+})
+```
+
+Open `/pricing` and view the page source. The root route's `<HeadContent />` renders the tags into `<head>`:
+
+```html
+<title>Pricing</title>
+<meta property="og:title" content="Pricing">
+<meta name="twitter:title" content="Pricing">
+<meta name="description" content="Plans for every team size.">
+<meta property="og:description" content="Plans for every team size.">
+<meta name="twitter:description" content="Plans for every team size.">
+<meta property="og:type" content="website">
+<meta name="twitter:card" content="summary">
+```
+
+`seo()` returns `{ meta, links }`, the shape TanStack Router's `head` expects, with Open Graph and Twitter tags filled in. The router swaps tags on each navigation. Next in the guide: [Give a page its title](/packages/seo/guide#give-a-page-its-title).
+
+## Built on
+
+kitr adds the tag set, site defaults, JSON-LD helpers, the sitemap and `robots.txt`, and per-route rendering and caching choices.
+
+## Problems it solves
+
+- **Tags written by hand on every page.** [Give a page its title](/packages/seo/guide#give-a-page-its-title).
+- **Blank link previews.** [Add a share image](/packages/seo/guide#add-a-share-image).
+- **No rich results.** [Add structured data](/packages/seo/guide#add-structured-data).
+- **Private pages in search results.** [Keep a page out of search results](/packages/seo/guide#keep-a-page-out-of-search-results).
+- **Crawlers that see an empty shell.** [Prerender pages at build time](/packages/seo/guide#prerender-pages-at-build-time).
+- **A sitemap that drifts from the routes.** [Generate a sitemap](/packages/seo/guide#generate-a-sitemap).
+
+## Further reading
+
+- [Guide](/packages/seo/guide).
+- [API reference](/packages/seo/api).
+- [TanStack Router document head management](https://tanstack.com/router/latest/docs/framework/react/guide/document-head-management) and [TanStack Start static prerendering](https://tanstack.com/start/latest/docs/framework/react/guide/static-prerendering).
+- [Google Search Central](https://developers.google.com/search/docs).
+- [Web](/packages/web) and [Router](/packages/router).

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@kitr/seo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.1",
+  "description": "@kitr/seo: meta and Open Graph tags per route, prerender list, sitemap and robots, cache headers. Works for SSR, static sites, SPAs and PWAs.",
+  "kitr": {
+    "name": "seo",
+    "title": "SEO",
+    "summary": "Give every page a title, a share preview and a sitemap entry so search engines and chat apps show it well.",
+    "category": "pages",
+    "runsOn": "both",
+    "client": true,
+    "docs": "docs",
+    "setup": "./kitr"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitrjs/kitr.git",
+    "directory": "packages/seo"
+  },
+  "homepage": "https://kitr.dev/packages/seo",
+  "bugs": "https://github.com/kitrjs/kitr/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./kitr": {
+      "types": "./dist/kitr.d.ts",
+      "default": "./dist/kitr.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "dependencies": {
+    "@kitr/core": "0.2.1"
+  },
+  "peerDependencies": {},
+  "peerDependenciesMeta": {},
+  "devDependencies": {
+    "tsdown": "^0.23.7",
+    "typescript": "^5.9.3",
+    "@types/node": "^22.19.0"
+  },
+  "keywords": [
+    "kitr",
+    "kitr-package"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }