@menapo/seo 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 menapo
+
+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,28 @@
-# Temporary Holding Version
+# @menapo/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.
+Head tags, hreflang and sitemaps for kit apps: one `head()` call per page,
+in React, Preact, Vue, Svelte, Solid, Astro and plain code. The output is
+DOM and response edits, never components.
+
+**Status: built, private until 1.0.** `head()` in the browser and on the
+server, `withHead()` from `/server`, `/test`'s `headOf()`, and the plugin
+(defaults, vi18n hreflang, `index.html` defaults, `sitemap.xml` and
+`robots.txt` after the build) are implemented and tested;
+`examples/seo-vanilla` prerenders through `withHead()` and navigates in
+Chromium. The release waits on the owner's review.
+
+```ts
+// vite.config.ts
+plugins: [vi18n(), seo({ site: "https://acme.com", title: "%s · Acme", image: "/og.png" })];
+```
+
+```ts
+import { head } from "@menapo/seo";
+
+head({ title: t("Pricing"), description: t("Plans for every team") });
+```
+
+- [Guide](./docs/guide/README.md): the plugin, `head()`, servers, the sitemap.
+- [Plan](./docs/PLAN.md): the design, its decisions and measurements.
+- Benchmarks: `vp run --filter @menapo/bench bench:seo`
+  ([bench/README.md](../../bench/README.md#menaposeo)).

package/dist/html-Cs8NzYrD.js

@@ -0,0 +1,76 @@
+import { t as keyOf } from "./tags-N6pWK3eY.js";
+//#region src/html.ts
+/**
+* Head HTML as text, for the server's response rewrite, the plugin's
+* `index.html` step and the sitemap's crawl. Not a parser: it reads the
+* `<title>`, `<meta>`, `<link>` and `<script>` elements of one `<head>`,
+* which is all seo writes or needs to read.
+*/
+const ESCAPES = {
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;"
+};
+const ESCAPE = /[&<>"]/;
+const escape = (s) => ESCAPE.test(s) ? s.replace(/[&<>"]/g, (c) => ESCAPES[c]) : s;
+const ENTITIES = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	"#39": "'",
+	apos: "'"
+};
+const unescape = (s) => s.replace(/&(amp|lt|gt|quot|#39|apos);/g, (_, e) => ENTITIES[e]);
+/** The tags as HTML. JSON-LD is already escaped for a script body. */
+function render(tags) {
+	let out = "";
+	for (const t of tags) {
+		let attrs = "";
+		for (const name in t.attrs) attrs += " " + name + "=\"" + escape(t.attrs[name]) + "\"";
+		const text = t.tag === "title" ? escape(t.text ?? "") : t.text ?? "";
+		out += t.tag === "meta" || t.tag === "link" ? `<${t.tag}${attrs}>` : `<${t.tag}${attrs}>${text}</${t.tag}>`;
+	}
+	return out;
+}
+const ELEMENT = /<(title|script)\b([^>]*)>[\s\S]*?<\/\1\s*>|<(meta|link)\b([^>]*?)\/?>/gi;
+const ATTR = /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+/** The elements seo reads in `head` (the text of one `<head>`). */
+function scan(head) {
+	const out = [];
+	for (const m of head.matchAll(ELEMENT)) {
+		const attrs = {};
+		for (const a of (m[2] ?? m[4] ?? "").matchAll(ATTR)) attrs[a[1].toLowerCase()] = unescape(a[2] ?? a[3] ?? a[4] ?? "");
+		out.push({
+			tag: (m[1] ?? m[3]).toLowerCase(),
+			attrs,
+			start: m.index,
+			end: m.index + m[0].length
+		});
+	}
+	return out;
+}
+const HEAD_END = /<\/head\s*>/i;
+/** The index of `</head>` in `html`, or -1. */
+const headEnd = (html) => html.search(HEAD_END);
+/**
+* `html` (a document up to and including `</head>`) with every element whose
+* key one of `tags` has removed, and `tags` inserted before `</head>`.
+*/
+function rewrite(html, tags) {
+	const end = headEnd(html);
+	if (end < 0) return html;
+	const start = Math.max(0, html.search(/<head\b[^>]*>/i));
+	const keys = new Set(tags.map((t) => keyOf(t.tag, t.attrs)));
+	let out = "";
+	let at = start;
+	for (const f of scan(html.slice(start, end))) {
+		if (!keys.has(keyOf(f.tag, f.attrs))) continue;
+		out += html.slice(at, start + f.start);
+		at = start + f.end;
+	}
+	return html.slice(0, start) + out + html.slice(at, end) + render(tags) + html.slice(end);
+}
+//#endregion
+export { render as n, rewrite as r, headEnd as t };

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { a as Tag, i as SeoDefaults, n as Image, r as JsonLd, t as HeadInput } from "./types-C_iXY4pr.js";
+//#region src/index.d.ts
+/**
+ * Sets the page's head: the plugin's defaults with `input` on top. Each call
+ * replaces the previous one's tags, so the next page needs no cleanup.
+ */
+export declare function head(input?: HeadInput): void;
+//#endregion
+export type { HeadInput, Image, JsonLd, SeoDefaults, Tag };

package/dist/index.js

@@ -0,0 +1,66 @@
+import { n as tags, t as keyOf } from "./tags-N6pWK3eY.js";
+import { t as shared } from "./scope-B-mGqw0E.js";
+//#region src/dom.ts
+/**
+* The browser's half of `head()` (PLAN D3): the owned tags of `document.head`
+* become exactly `tags`. Elements whose key and values already match are
+* left alone, so the head a server wrote is adopted on hydration with no
+* DOM write; owned tags the call did not write are removed.
+*/
+const OWNED = "title,meta[name],meta[property],link[rel=canonical],link[rel=alternate][hreflang],script[type=\"application/ld+json\"]";
+function attrsOf(el) {
+	const out = {};
+	for (const a of el.attributes) out[a.name] = a.value;
+	return out;
+}
+function apply(tags) {
+	const head = document.head;
+	const old = /* @__PURE__ */ new Map();
+	for (const el of head.querySelectorAll(OWNED)) {
+		const key = keyOf(el.localName, attrsOf(el));
+		if (key === void 0) continue;
+		if (old.has(key)) el.remove();
+		else old.set(key, el);
+	}
+	let prev;
+	for (const t of tags) {
+		const key = keyOf(t.tag, t.attrs);
+		let el = old.get(key);
+		old.delete(key);
+		if (!el) {
+			el = document.createElement(t.tag);
+			if (prev) prev.after(el);
+			else head.append(el);
+		}
+		prev = el;
+		for (const [name, value] of Object.entries(t.attrs)) if (el.getAttribute(name) !== value) el.setAttribute(name, value);
+		if (t.text !== void 0 && el.textContent !== t.text) el.textContent = t.text;
+	}
+	for (const el of old.values()) el.remove();
+}
+//#endregion
+//#region src/index.ts
+/**
+* `@menapo/seo`: one `head()` call per page (PLAN §1). In the browser it
+* updates `document.head`; on the server it records into the request that
+* `withHead()` from `/server` opened, which writes the tags into the
+* response. Imports nothing from the build side: the plugin's defaults
+* arrive as the `__SEO__` define.
+*/
+const DEFAULTS = typeof __SEO__ === "undefined" ? {} : __SEO__;
+/**
+* Sets the page's head: the plugin's defaults with `input` on top. Each call
+* replaces the previous one's tags, so the next page needs no cleanup.
+*/
+function head(input = {}) {
+	if (typeof document === "undefined") {
+		const scope = shared().scope?.();
+		if (!scope) throw new Error("seo: head() ran on the server outside a request. Wrap the request handler in withHead(request, render) from \"@menapo/seo/server\".");
+		tags(input, DEFAULTS, scope.url);
+		scope.input = input;
+		return;
+	}
+	apply(tags(input, DEFAULTS, new URL(location.href)));
+}
+//#endregion
+export { head };

package/dist/locales/none.d.ts

@@ -0,0 +1,16 @@
+//#region src/locales/none.d.ts
+/**
+ * The locale module without vi18n: no hreflang. The plugin loads
+ * `vi18n.ts` in its place when `vi18n()` is in the Vite config (PLAN D7),
+ * so apps without locales ship none of it.
+ */
+export interface Alternates {
+  /** The page's canonical in its own locale. */
+  readonly canonical: string;
+  /** `[hreflang, href]`, `x-default` last; empty when every locale shares one URL. */
+  readonly links: readonly (readonly [string, string])[];
+  /** `og:locale`, then `og:locale:alternate` values, in `ll_TT` form. */
+  readonly og: readonly string[];
+}
+export declare function alternates(_url: URL): Alternates | undefined;
+//#endregion

package/dist/locales/none.js

@@ -0,0 +1,4 @@
+//#region src/locales/none.ts
+function alternates(_url) {}
+//#endregion
+export { alternates };

package/dist/locales/vi18n.d.ts

@@ -0,0 +1,5 @@
+import { Alternates } from "./none.js";
+//#region src/locales/vi18n.d.ts
+export declare function alternates(url: URL): Alternates;
+//#endregion
+export type { Alternates };

package/dist/locales/vi18n.js

@@ -0,0 +1,40 @@
+import { getLocale, locales, localizeUrl } from "@menapo/vi18n";
+//#region src/locales/vi18n.ts
+/**
+* The locale module with vi18n (PLAN D7): every advertised locale's URL of
+* the page from vi18n's own `localizeUrl`, so prefixes, localized paths and
+* domains come out as vi18n routes them, on the server and in the browser
+* alike. The source and pseudo-locales are read from vi18n's page state,
+* the protocol surface its runtime copies share, until vi18n exports them
+* (PLAN §7); tests/vi18n.test.ts pins the shape against the real runtime.
+*/
+/** `pt-BR` → `pt_BR`; a missing region from the likely subtags (`de` → `de_DE`), as vi18n's `ogLocale`. */
+function og(locale) {
+	try {
+		const l = new Intl.Locale(locale);
+		const region = l.region ?? l.maximize().region;
+		return region ? l.language + "_" + region : l.language;
+	} catch {
+		return locale;
+	}
+}
+function alternates(url) {
+	const config = globalThis[Symbol.for("menapo.vi18n")]?.registration?.config;
+	const pseudo = config?.pseudoLocales ?? [];
+	const listed = locales.filter((l) => !pseudo.includes(l));
+	const at = (l) => {
+		const u = localizeUrl(url, l);
+		return u.origin + u.pathname;
+	};
+	const current = getLocale();
+	const hrefs = listed.map(at);
+	const links = new Set(hrefs).size > 1 ? listed.map((l, i) => [l, hrefs[i]]) : [];
+	if (links.length) links.push(["x-default", at(config?.sourceLocale ?? listed[0])]);
+	return {
+		canonical: at(current),
+		links,
+		og: [current, ...listed.filter((l) => l !== current)].map(og)
+	};
+}
+//#endregion
+export { alternates };

package/dist/scope-B-mGqw0E.js

@@ -0,0 +1,4 @@
+//#region src/scope.ts
+const shared = () => globalThis[Symbol.for("menapo.seo")] ??= {};
+//#endregion
+export { shared as t };

package/dist/server.d.ts

@@ -0,0 +1,21 @@
+//#region src/server/index.d.ts
+/**
+ * `@menapo/seo/server` (PLAN D8): `withHead(request, render)` runs `render`
+ * in a scope of its own, where `head()` records the page's input, and
+ * writes the tags into the response's `<head>` as it streams. Its own
+ * entry, so browser bundles carry no `node:async_hooks`.
+ */
+/**
+ * Renders `request` with `render`, then puts the page's head into the
+ * response: the plugin's defaults, the canonical, `og:url` and hreflang
+ * from the request's URL, and whatever `head()` set during the render. Only
+ * `text/html` bodies are touched, and only their `<head>`; a page that never
+ * called `head()` still gets the defaults and its URL.
+ *
+ * ```ts
+ * export const onRequest = (ctx, next) => withHead(ctx.request, next); // Astro
+ * export const handle = ({ event, resolve }) => withHead(event.request, () => resolve(event)); // SvelteKit
+ * ```
+ */
+export declare function withHead(request: Request, render: () => Response | Promise<Response>): Promise<Response>;
+//#endregion

package/dist/server.js

@@ -0,0 +1,70 @@
+import { n as tags } from "./tags-N6pWK3eY.js";
+import { t as shared } from "./scope-B-mGqw0E.js";
+import { r as rewrite, t as headEnd } from "./html-Cs8NzYrD.js";
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/server/index.ts
+/**
+* `@menapo/seo/server` (PLAN D8): `withHead(request, render)` runs `render`
+* in a scope of its own, where `head()` records the page's input, and
+* writes the tags into the response's `<head>` as it streams. Its own
+* entry, so browser bundles carry no `node:async_hooks`.
+*/
+const DEFAULTS = typeof __SEO__ === "undefined" ? {} : __SEO__;
+const global = shared();
+const scopes = global.als ??= new AsyncLocalStorage();
+global.scope ??= () => scopes.getStore();
+/**
+* Renders `request` with `render`, then puts the page's head into the
+* response: the plugin's defaults, the canonical, `og:url` and hreflang
+* from the request's URL, and whatever `head()` set during the render. Only
+* `text/html` bodies are touched, and only their `<head>`; a page that never
+* called `head()` still gets the defaults and its URL.
+*
+* ```ts
+* export const onRequest = (ctx, next) => withHead(ctx.request, next); // Astro
+* export const handle = ({ event, resolve }) => withHead(event.request, () => resolve(event)); // SvelteKit
+* ```
+*/
+async function withHead(request, render) {
+	const scope = {
+		url: new URL(request.url),
+		input: void 0
+	};
+	const within = AsyncLocalStorage.snapshot();
+	const response = await scopes.run(scope, render);
+	if (!response.body || !/^text\/html\b/i.test(response.headers.get("content-type") ?? "")) return response;
+	const headers = new Headers(response.headers);
+	headers.delete("content-length");
+	return new Response(response.body.pipeThrough(inject(() => within(() => tags(scope.input ?? {}, DEFAULTS, scope.url)))), {
+		status: response.status,
+		statusText: response.statusText,
+		headers
+	});
+}
+/**
+* Holds the document back until `</head>`, rewrites it, then streams the
+* rest untouched. The tags are taken at `</head>`, when a streaming
+* renderer has run the shell, which is where a page's `head()` call runs.
+*/
+function inject(make) {
+	const decoder = new TextDecoder();
+	const encoder = new TextEncoder();
+	let held = "";
+	let done = false;
+	return new TransformStream({
+		transform(chunk, controller) {
+			if (done) return controller.enqueue(chunk);
+			held += decoder.decode(chunk, { stream: true });
+			if (headEnd(held) < 0) return;
+			done = true;
+			controller.enqueue(encoder.encode(rewrite(held, make())));
+			held = "";
+		},
+		flush(controller) {
+			held += decoder.decode();
+			if (held) controller.enqueue(encoder.encode(held));
+		}
+	});
+}
+//#endregion
+export { withHead };

package/dist/tags-N6pWK3eY.js

@@ -0,0 +1,135 @@
+import { alternates } from "./locales/none.js";
+//#region src/tags.ts
+/**
+* Input and defaults → the ordered tags of one page (PLAN §1.2): each fact
+* written once and fanned out. Pure, shared by the browser, the server, the
+* plugin's `index.html` step and `/test`, so all four write the same head.
+*/
+const SEPARATORS = /^[\s·|•–—:-]+|[\s·|•–—:-]+$/g;
+/** An absolute http(s) URL, or an error that shows the value and the fix. */
+function absolute(value, base, what) {
+	let url;
+	try {
+		url = new URL(value, base);
+	} catch {}
+	if (url?.protocol !== "https:" && url?.protocol !== "http:") throw new Error(`seo: ${what} ${JSON.stringify(String(value))} is not an absolute http(s) URL. Pass one, or set seo({ site }) to resolve it against.`);
+	return url;
+}
+let siteText;
+let siteUrl;
+const iso = (d) => typeof d === "string" ? d : d.toISOString();
+/**
+* `url` is the page's address (request, `location` or `input.url`), or
+* undefined for site-wide tags (an SPA's `index.html`, PLAN D9).
+*/
+function tags(input, defaults, url) {
+	const out = [];
+	const meta = (key, k, content) => {
+		if (content !== void 0 && content !== "") out.push({
+			tag: "meta",
+			attrs: key === "name" ? {
+				name: k,
+				content: "" + content
+			} : {
+				property: k,
+				content: "" + content
+			}
+		});
+	};
+	if (defaults.site !== siteText) {
+		siteUrl = defaults.site ? absolute(defaults.site, void 0, "site") : void 0;
+		siteText = defaults.site;
+	}
+	const site = siteUrl;
+	if (input.url !== void 0) url = absolute(input.url, site, "url");
+	const page = url && site && url.origin !== site.origin ? new URL(url.pathname + url.search, site) : url;
+	const template = defaults.title;
+	const isTemplate = template?.includes("%s") ?? false;
+	const name = defaults.name ?? (isTemplate ? template.replace("%s", "").replace(SEPARATORS, "") : void 0);
+	const title = input.title !== void 0 ? isTemplate ? template.replace("%s", input.title) : input.title : isTemplate ? name : template;
+	if (title) out.push({
+		tag: "title",
+		attrs: {},
+		text: title
+	});
+	const description = input.description ?? defaults.description;
+	meta("name", "description", description);
+	meta("name", "robots", input.robots);
+	const alt = page && /* @__PURE__ */ alternates(page);
+	let canonical;
+	if (page) {
+		canonical = alt?.canonical ?? page.origin + page.pathname;
+		out.push({
+			tag: "link",
+			attrs: {
+				rel: "canonical",
+				href: canonical
+			}
+		});
+		for (const [hreflang, href] of alt?.links ?? []) out.push({
+			tag: "link",
+			attrs: {
+				rel: "alternate",
+				hreflang,
+				href
+			}
+		});
+	}
+	meta("property", "og:type", input.published !== void 0 || input.modified !== void 0 ? "article" : "website");
+	meta("property", "og:title", title);
+	meta("property", "og:description", description);
+	meta("property", "og:url", canonical);
+	meta("property", "og:site_name", name);
+	const [locale, ...others] = alt?.og ?? [];
+	meta("property", "og:locale", locale);
+	for (const l of others) meta("property", "og:locale:alternate", l);
+	const raw = input.image ?? defaults.image;
+	const image = typeof raw === "string" ? { url: raw } : raw;
+	if (image) {
+		meta("property", "og:image", absolute(image.url, page ?? site, "image").href);
+		meta("property", "og:image:width", image.width);
+		meta("property", "og:image:height", image.height);
+		meta("property", "og:image:alt", image.alt);
+	}
+	if (input.published !== void 0) meta("property", "article:published_time", iso(input.published));
+	if (input.modified !== void 0) meta("property", "article:modified_time", iso(input.modified));
+	meta("name", "twitter:card", image ? "summary_large_image" : "summary");
+	meta("name", "twitter:site", defaults.twitter);
+	if (input.jsonLd) out.push({
+		tag: "script",
+		attrs: { type: "application/ld+json" },
+		text: jsonLd(input.jsonLd)
+	});
+	return out;
+}
+/** `@context` added, several nodes as one `@graph`, escaped so data cannot close the script. */
+function jsonLd(value) {
+	const doc = Array.isArray(value) ? {
+		"@context": "https://schema.org",
+		"@graph": value
+	} : {
+		"@context": "https://schema.org",
+		...value
+	};
+	return JSON.stringify(doc).replace(/[<>&\u2028\u2029]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+}
+/**
+* The identity a tag replaces another by (PLAN D3): repeated properties
+* (`og:locale:alternate`) are told apart by their value. Undefined for a
+* tag seo does not own.
+*/
+function keyOf(tag, attrs) {
+	if (tag === "title") return "title";
+	if (tag === "script") return attrs.type === "application/ld+json" ? "ld" : void 0;
+	if (tag === "link") {
+		if (attrs.rel === "canonical") return "canonical";
+		return attrs.rel === "alternate" && attrs.hreflang ? "h:" + attrs.hreflang : void 0;
+	}
+	if (tag !== "meta") return void 0;
+	const n = attrs.name;
+	if (n === "description" || n === "robots" || n?.startsWith("twitter:")) return "n:" + n;
+	const p = attrs.property;
+	if (p?.startsWith("og:") || p?.startsWith("article:")) return "p:" + p + (p === "og:locale:alternate" ? "=" + attrs.content : "");
+}
+//#endregion
+export { tags as n, keyOf as t };

package/dist/test.d.ts

@@ -0,0 +1,13 @@
+import { a as Tag, i as SeoDefaults, t as HeadInput } from "./types-C_iXY4pr.js";
+//#region src/test/index.d.ts
+export interface HeadOfOptions {
+  /** The page's URL, as a request or `location` would give it. */
+  readonly url?: string | URL;
+  readonly defaults?: SeoDefaults;
+}
+/** The ordered tags `head(input)` writes at `options.url`. */
+export declare function headOf(input?: HeadInput, options?: HeadOfOptions): Tag[];
+/** The same tags as HTML, as the server writes them into `<head>`. */
+export declare function headHtml(input?: HeadInput, options?: HeadOfOptions): string;
+//#endregion
+export type { Tag };

package/dist/test.js

@@ -0,0 +1,20 @@
+import { n as tags } from "./tags-N6pWK3eY.js";
+import { n as render } from "./html-Cs8NzYrD.js";
+//#region src/test/index.ts
+/**
+* `@menapo/seo/test`: the tags one `head()` call writes, as data, for unit
+* tests that assert a page's head without a DOM or a server. Defaults are
+* passed in (a test's plugin config may differ from the app's); in a Vitest
+* run with `seo()` in the config they default to the plugin's.
+*/
+/** The ordered tags `head(input)` writes at `options.url`. */
+function headOf(input = {}, options = {}) {
+	const defaults = options.defaults ?? (typeof __SEO__ === "undefined" ? {} : __SEO__);
+	return tags(input, defaults, options.url === void 0 ? void 0 : new URL(options.url));
+}
+/** The same tags as HTML, as the server writes them into `<head>`. */
+function headHtml(input = {}, options = {}) {
+	return render(headOf(input, options));
+}
+//#endregion
+export { headHtml, headOf };

package/dist/types-C_iXY4pr.d.ts

@@ -0,0 +1,54 @@
+//#region src/types.d.ts
+/** An image as `@menapo/og` returns it, or any `{ url }`; a string is its URL. */
+interface Image {
+  readonly url: string;
+  readonly width?: number;
+  readonly height?: number;
+  readonly alt?: string;
+}
+/**
+ * One schema.org node. `schema-dts` types (`Product`, `Article` …) fit it,
+ * so `satisfies Product` gives completion without seo depending on them.
+ */
+interface JsonLd {
+  readonly "@type": string | readonly string[];
+  readonly [key: string]: unknown;
+}
+/** What one page says about itself: `head(input)`. Every key is optional. */
+interface HeadInput {
+  /** The page's title, put through the plugin's `title` template. */
+  readonly title?: string;
+  readonly description?: string;
+  /** A URL (relative to the page) or `{ url, width, height, alt }`. */
+  readonly image?: string | Image;
+  /** Makes the page an article; the sitemap's `lastmod` is `modified`, else this. */
+  readonly published?: Date | string;
+  readonly modified?: Date | string;
+  /** As Google documents it: `"noindex"` also keeps the page out of the sitemap. */
+  readonly robots?: string;
+  readonly jsonLd?: JsonLd | readonly JsonLd[];
+  /** The page's URL where there is no request or `location` to read it from. */
+  readonly url?: string | URL;
+}
+/** The plugin's options: defaults that each page's `head()` input replaces. */
+interface SeoDefaults {
+  /** The public origin (and base path), for canonicals, the sitemap and robots.txt. Default: `SITE_URL`. */
+  readonly site?: string;
+  /** `"%s · Acme"` is a template (a page without a title gets `Acme`); a plain string is the default title. */
+  readonly title?: string;
+  readonly description?: string;
+  readonly image?: string | Image;
+  /** `og:site_name`. Default: the title template without `%s` and its separator. */
+  readonly name?: string;
+  /** `twitter:site`, such as `"@acme"`. */
+  readonly twitter?: string;
+}
+/** One head element, as `/test`'s `headOf()` returns it. */
+interface Tag {
+  readonly tag: "title" | "meta" | "link" | "script";
+  readonly attrs: Readonly<Record<string, string>>;
+  /** The element's text: the title, or the JSON-LD. */
+  readonly text?: string;
+}
+//#endregion
+export { Tag as a, SeoDefaults as i, Image as n, JsonLd as r, HeadInput as t };

package/dist/vite.d.ts

@@ -0,0 +1,28 @@
+import { Plugin } from "vite";
+//#region src/types.d.ts
+/** An image as `@menapo/og` returns it, or any `{ url }`; a string is its URL. */
+interface Image {
+  readonly url: string;
+  readonly width?: number;
+  readonly height?: number;
+  readonly alt?: string;
+}
+/** The plugin's options: defaults that each page's `head()` input replaces. */
+interface SeoDefaults {
+  /** The public origin (and base path), for canonicals, the sitemap and robots.txt. Default: `SITE_URL`. */
+  readonly site?: string;
+  /** `"%s · Acme"` is a template (a page without a title gets `Acme`); a plain string is the default title. */
+  readonly title?: string;
+  readonly description?: string;
+  readonly image?: string | Image;
+  /** `og:site_name`. Default: the title template without `%s` and its separator. */
+  readonly name?: string;
+  /** `twitter:site`, such as `"@acme"`. */
+  readonly twitter?: string;
+}
+//#endregion
+//#region src/vite/index.d.ts
+/** `plugins: [seo({ site, title: "%s · Acme", image })]` in a Vite config; every option is optional. */
+export declare function seo(options?: SeoDefaults): Plugin;
+//#endregion
+export type { SeoDefaults };

package/dist/vite.js

@@ -0,0 +1,426 @@
+import { join, posix, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+//#endregion
+//#region src/tags.ts
+/**
+* Input and defaults → the ordered tags of one page (PLAN §1.2): each fact
+* written once and fanned out. Pure, shared by the browser, the server, the
+* plugin's `index.html` step and `/test`, so all four write the same head.
+*/
+const SEPARATORS = /^[\s·|•–—:-]+|[\s·|•–—:-]+$/g;
+/** An absolute http(s) URL, or an error that shows the value and the fix. */
+function absolute(value, base, what) {
+	let url;
+	try {
+		url = new URL(value, base);
+	} catch {}
+	if (url?.protocol !== "https:" && url?.protocol !== "http:") throw new Error(`seo: ${what} ${JSON.stringify(String(value))} is not an absolute http(s) URL. Pass one, or set seo({ site }) to resolve it against.`);
+	return url;
+}
+let siteText;
+let siteUrl;
+const iso = (d) => typeof d === "string" ? d : d.toISOString();
+/**
+* `url` is the page's address (request, `location` or `input.url`), or
+* undefined for site-wide tags (an SPA's `index.html`, PLAN D9).
+*/
+function tags(input, defaults, url) {
+	const out = [];
+	const meta = (key, k, content) => {
+		if (content !== void 0 && content !== "") out.push({
+			tag: "meta",
+			attrs: key === "name" ? {
+				name: k,
+				content: "" + content
+			} : {
+				property: k,
+				content: "" + content
+			}
+		});
+	};
+	if (defaults.site !== siteText) {
+		siteUrl = defaults.site ? absolute(defaults.site, void 0, "site") : void 0;
+		siteText = defaults.site;
+	}
+	const site = siteUrl;
+	if (input.url !== void 0) url = absolute(input.url, site, "url");
+	const page = url && site && url.origin !== site.origin ? new URL(url.pathname + url.search, site) : url;
+	const template = defaults.title;
+	const isTemplate = template?.includes("%s") ?? false;
+	const name = defaults.name ?? (isTemplate ? template.replace("%s", "").replace(SEPARATORS, "") : void 0);
+	const title = input.title !== void 0 ? isTemplate ? template.replace("%s", input.title) : input.title : isTemplate ? name : template;
+	if (title) out.push({
+		tag: "title",
+		attrs: {},
+		text: title
+	});
+	const description = input.description ?? defaults.description;
+	meta("name", "description", description);
+	meta("name", "robots", input.robots);
+	const alt = page && void 0;
+	let canonical;
+	if (page) {
+		canonical = alt?.canonical ?? page.origin + page.pathname;
+		out.push({
+			tag: "link",
+			attrs: {
+				rel: "canonical",
+				href: canonical
+			}
+		});
+		for (const [hreflang, href] of alt?.links ?? []) out.push({
+			tag: "link",
+			attrs: {
+				rel: "alternate",
+				hreflang,
+				href
+			}
+		});
+	}
+	meta("property", "og:type", input.published !== void 0 || input.modified !== void 0 ? "article" : "website");
+	meta("property", "og:title", title);
+	meta("property", "og:description", description);
+	meta("property", "og:url", canonical);
+	meta("property", "og:site_name", name);
+	const [locale, ...others] = alt?.og ?? [];
+	meta("property", "og:locale", locale);
+	for (const l of others) meta("property", "og:locale:alternate", l);
+	const raw = input.image ?? defaults.image;
+	const image = typeof raw === "string" ? { url: raw } : raw;
+	if (image) {
+		meta("property", "og:image", absolute(image.url, page ?? site, "image").href);
+		meta("property", "og:image:width", image.width);
+		meta("property", "og:image:height", image.height);
+		meta("property", "og:image:alt", image.alt);
+	}
+	if (input.published !== void 0) meta("property", "article:published_time", iso(input.published));
+	if (input.modified !== void 0) meta("property", "article:modified_time", iso(input.modified));
+	meta("name", "twitter:card", image ? "summary_large_image" : "summary");
+	meta("name", "twitter:site", defaults.twitter);
+	if (input.jsonLd) out.push({
+		tag: "script",
+		attrs: { type: "application/ld+json" },
+		text: jsonLd(input.jsonLd)
+	});
+	return out;
+}
+/** `@context` added, several nodes as one `@graph`, escaped so data cannot close the script. */
+function jsonLd(value) {
+	const doc = Array.isArray(value) ? {
+		"@context": "https://schema.org",
+		"@graph": value
+	} : {
+		"@context": "https://schema.org",
+		...value
+	};
+	return JSON.stringify(doc).replace(/[<>&\u2028\u2029]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+}
+/**
+* The identity a tag replaces another by (PLAN D3): repeated properties
+* (`og:locale:alternate`) are told apart by their value. Undefined for a
+* tag seo does not own.
+*/
+function keyOf(tag, attrs) {
+	if (tag === "title") return "title";
+	if (tag === "script") return attrs.type === "application/ld+json" ? "ld" : void 0;
+	if (tag === "link") {
+		if (attrs.rel === "canonical") return "canonical";
+		return attrs.rel === "alternate" && attrs.hreflang ? "h:" + attrs.hreflang : void 0;
+	}
+	if (tag !== "meta") return void 0;
+	const n = attrs.name;
+	if (n === "description" || n === "robots" || n?.startsWith("twitter:")) return "n:" + n;
+	const p = attrs.property;
+	if (p?.startsWith("og:") || p?.startsWith("article:")) return "p:" + p + (p === "og:locale:alternate" ? "=" + attrs.content : "");
+}
+//#endregion
+//#region src/html.ts
+/**
+* Head HTML as text, for the server's response rewrite, the plugin's
+* `index.html` step and the sitemap's crawl. Not a parser: it reads the
+* `<title>`, `<meta>`, `<link>` and `<script>` elements of one `<head>`,
+* which is all seo writes or needs to read.
+*/
+const ESCAPES = {
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;"
+};
+const ESCAPE = /[&<>"]/;
+const escape = (s) => ESCAPE.test(s) ? s.replace(/[&<>"]/g, (c) => ESCAPES[c]) : s;
+const ENTITIES = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	"#39": "'",
+	apos: "'"
+};
+const unescape = (s) => s.replace(/&(amp|lt|gt|quot|#39|apos);/g, (_, e) => ENTITIES[e]);
+/** The tags as HTML. JSON-LD is already escaped for a script body. */
+function render(tags) {
+	let out = "";
+	for (const t of tags) {
+		let attrs = "";
+		for (const name in t.attrs) attrs += " " + name + "=\"" + escape(t.attrs[name]) + "\"";
+		const text = t.tag === "title" ? escape(t.text ?? "") : t.text ?? "";
+		out += t.tag === "meta" || t.tag === "link" ? `<${t.tag}${attrs}>` : `<${t.tag}${attrs}>${text}</${t.tag}>`;
+	}
+	return out;
+}
+const ELEMENT = /<(title|script)\b([^>]*)>[\s\S]*?<\/\1\s*>|<(meta|link)\b([^>]*?)\/?>/gi;
+const ATTR = /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+/** The elements seo reads in `head` (the text of one `<head>`). */
+function scan(head) {
+	const out = [];
+	for (const m of head.matchAll(ELEMENT)) {
+		const attrs = {};
+		for (const a of (m[2] ?? m[4] ?? "").matchAll(ATTR)) attrs[a[1].toLowerCase()] = unescape(a[2] ?? a[3] ?? a[4] ?? "");
+		out.push({
+			tag: (m[1] ?? m[3]).toLowerCase(),
+			attrs,
+			start: m.index,
+			end: m.index + m[0].length
+		});
+	}
+	return out;
+}
+const HEAD_END = /<\/head\s*>/i;
+/** The index of `</head>` in `html`, or -1. */
+const headEnd = (html) => html.search(HEAD_END);
+/**
+* `html` (a document up to and including `</head>`) with every element whose
+* key one of `tags` has removed, and `tags` inserted before `</head>`.
+*/
+function rewrite(html, tags) {
+	const end = headEnd(html);
+	if (end < 0) return html;
+	const start = Math.max(0, html.search(/<head\b[^>]*>/i));
+	const keys = new Set(tags.map((t) => keyOf(t.tag, t.attrs)));
+	let out = "";
+	let at = start;
+	for (const f of scan(html.slice(start, end))) {
+		if (!keys.has(keyOf(f.tag, f.attrs))) continue;
+		out += html.slice(at, start + f.start);
+		at = start + f.end;
+	}
+	return html.slice(0, start) + out + html.slice(at, end) + render(tags) + html.slice(end);
+}
+//#endregion
+//#region src/vite/sitemap.ts
+/**
+* `sitemap.xml` and `robots.txt` from the built pages (PLAN D10). Each page's
+* `<head>` is the truth: `loc` is its canonical, its alternates are its
+* hreflang links, `lastmod` its article dates. `noindex` pages, error pages
+* and pages canonical to another URL are left out.
+*/
+/** Google's limit per sitemap file; past it the sitemap becomes an index. */
+const LIMIT = 5e4;
+const ERROR_PAGE = /^(?:404|500)(?:\.html|\/index\.html)$/;
+function htmlFiles(dir) {
+	const out = [];
+	for (const d of readdirSync(dir, {
+		recursive: true,
+		withFileTypes: true
+	})) if (d.isFile() && d.name.endsWith(".html")) out.push(relative(dir, join(d.parentPath, d.name)).split(sep).join("/"));
+	return out.sort();
+}
+const trim = (path) => path.replace(/(?:\/index)?(?:\.html)?$/, "").replace(/\/$/, "");
+/** The entries of every page under `dir`, plus the messages that would make the sitemap wrong. */
+function crawl(dir, site, base) {
+	const entries = [];
+	const warnings = [];
+	const files = htmlFiles(dir);
+	for (const file of files) {
+		if (ERROR_PAGE.test(file)) continue;
+		const html = readFileSync(join(dir, file), "utf8");
+		const end = headEnd(html);
+		let canonical;
+		let noindex = false;
+		let modified;
+		let published;
+		const alternates = [];
+		for (const { tag, attrs } of scan(end < 0 ? "" : html.slice(0, end))) if (tag === "link" && attrs.rel === "canonical") canonical = attrs.href;
+		else if (tag === "link" && attrs.rel === "alternate" && attrs.hreflang && attrs.href) alternates.push([attrs.hreflang, attrs.href]);
+		else if (tag === "meta" && attrs.name === "robots") noindex = /\bnoindex\b/i.test(attrs.content ?? "");
+		else if (tag === "meta" && attrs.property === "article:modified_time") modified = attrs.content;
+		else if (tag === "meta" && attrs.property === "article:published_time") published = attrs.content;
+		if (noindex) continue;
+		const own = posix.join(base, file.replace(/(?:^|\/)index\.html$/, "/").replace(/\.html$/, ""));
+		let loc;
+		if (canonical) {
+			if (trim(new URL(canonical).pathname) !== trim(own)) continue;
+			loc = canonical;
+		} else if (site) loc = new URL(own, site).href;
+		else {
+			warnings.push(`${file} has no canonical and the site is unknown, so it is left out. Set seo({ site }) or SITE_URL.`);
+			continue;
+		}
+		const lastmod = modified ?? published;
+		entries.push(lastmod ? {
+			loc,
+			lastmod,
+			alternates
+		} : {
+			loc,
+			alternates
+		});
+	}
+	const byLoc = new Map(entries.map((e) => [e.loc, e]));
+	for (const e of entries) for (const [hreflang, href] of e.alternates) {
+		const other = byLoc.get(href);
+		if (other && href !== e.loc && !other.alternates.some(([, h]) => h === e.loc)) warnings.push(`${e.loc} links hreflang="${hreflang}" to ${href}, which does not link back. Call head() on both pages with vi18n in the config, which writes both directions.`);
+	}
+	return {
+		entries,
+		pages: files.length,
+		warnings
+	};
+}
+const XML = {
+	"&": "&amp;",
+	"<": "&lt;",
+	">": "&gt;",
+	"\"": "&quot;",
+	"'": "&apos;"
+};
+const xml = (s) => s.replace(/[&<>"']/g, (c) => XML[c]);
+function urlset(entries) {
+	let out = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\" xmlns:xhtml=\"http://www.w3.org/1999/xhtml\">\n";
+	for (const e of entries) {
+		out += `<url><loc>${xml(e.loc)}</loc>`;
+		if (e.lastmod) out += `<lastmod>${xml(e.lastmod)}</lastmod>`;
+		for (const [hreflang, href] of e.alternates) out += `<xhtml:link rel="alternate" hreflang="${xml(hreflang)}" href="${xml(href)}"/>`;
+		out += "</url>\n";
+	}
+	return out + "</urlset>\n";
+}
+/**
+* Writes `sitemap.xml` (an index of `sitemap-N.xml` past 50,000 URLs) and,
+* when the app has none, `robots.txt`. Returns the warnings, and the number
+* of HTML pages found, so the plugin can wait for a framework that writes
+* its pages later.
+*/
+function writeSitemap(dir, site, base = "/") {
+	if (!existsSync(dir)) return {
+		pages: 0,
+		warnings: []
+	};
+	const { entries, pages, warnings } = crawl(dir, site, base);
+	const origin = site ?? (entries[0] && new URL(entries[0].loc));
+	if (!entries.length || !origin) return {
+		pages,
+		warnings
+	};
+	const at = (file) => new URL(posix.join(base, file), origin).href;
+	if (entries.length <= LIMIT) writeFileSync(join(dir, "sitemap.xml"), urlset(entries));
+	else {
+		let index = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<sitemapindex xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n";
+		for (let i = 0; i * LIMIT < entries.length; i++) {
+			writeFileSync(join(dir, `sitemap-${i}.xml`), urlset(entries.slice(i * LIMIT, (i + 1) * LIMIT)));
+			index += `<sitemap><loc>${xml(at(`sitemap-${i}.xml`))}</loc></sitemap>\n`;
+		}
+		writeFileSync(join(dir, "sitemap.xml"), index + "</sitemapindex>\n");
+	}
+	const robots = join(dir, "robots.txt");
+	const line = `Sitemap: ${at("sitemap.xml")}`;
+	if (!existsSync(robots)) writeFileSync(robots, `User-agent: *\nAllow: /\n\n${line}\n`);
+	else if (!/^\s*sitemap:/im.test(readFileSync(robots, "utf8"))) warnings.push(`robots.txt has no Sitemap line. Add "${line}" to it.`);
+	return {
+		pages,
+		warnings
+	};
+}
+//#endregion
+//#region src/vite/index.ts
+/**
+* `@menapo/seo/vite`: `seo(defaults)` (PLAN §1, §4). It hands the defaults
+* to the runtime as the `__SEO__` define, swaps in the vi18n locale module
+* when `vi18n()` is in the config (D7), writes the site-wide tags into an
+* SPA's `index.html` (D9), and writes `sitemap.xml` and `robots.txt` from
+* the built pages after the build (D10).
+*/
+const EXT = import.meta.url.endsWith(".ts") ? ".ts" : ".js";
+const ROOT = new URL(EXT === ".ts" ? "../" : "./", import.meta.url);
+const posix$1 = (path) => path.replaceAll("\\", "/");
+const NONE = posix$1(fileURLToPath(new URL("locales/none" + EXT, ROOT)));
+const VI18N = posix$1(fileURLToPath(new URL("locales/vi18n" + EXT, ROOT)));
+function siteOf(value) {
+	if (!value) return void 0;
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new Error(`seo: site ${JSON.stringify(value)} is not an absolute URL. Pass seo({ site: "https://example.com" }).`);
+	}
+	if (url.protocol !== "https:" && url.protocol !== "http:") throw new Error(`seo: site ${JSON.stringify(value)} is not an http(s) URL.`);
+	return url;
+}
+/** `plugins: [seo({ site, title: "%s · Acme", image })]` in a Vite config; every option is optional. */
+function seo(options = {}) {
+	const site = siteOf(options.site ?? process.env.SITE_URL);
+	const defaults = site ? {
+		...options,
+		site: site.href
+	} : options;
+	let config;
+	let vi18n = false;
+	let written = false;
+	let hooked = false;
+	const sitemap = () => {
+		const { pages, warnings } = writeSitemap(resolve(config.root, config.environments.client?.build.outDir ?? config.build.outDir), site, config.base.startsWith("/") ? config.base : "/");
+		for (const w of warnings) config.logger.warn(`seo: ${w}`);
+		return pages;
+	};
+	const write = () => {
+		written = sitemap() > 0;
+	};
+	const last = () => {
+		process.once("beforeExit", () => void (written || write()));
+	};
+	return {
+		name: "seo",
+		config: () => ({
+			define: { __SEO__: JSON.stringify(defaults) },
+			optimizeDeps: { exclude: [
+				"@menapo/seo",
+				"@menapo/seo/server",
+				"@menapo/seo/test"
+			] },
+			ssr: { noExternal: ["@menapo/seo"] }
+		}),
+		configResolved(resolved) {
+			config = resolved;
+			vi18n = resolved.plugins.some((p) => p.name === "vi18n:config");
+		},
+		load: {
+			filter: { id: /locales[\\/]none\.[jt]s$/ },
+			handler(id) {
+				if (!vi18n || posix$1(id.replace(/[?#].*$/, "")) !== NONE) return null;
+				return `export { alternates } from ${JSON.stringify(VI18N)};`;
+			}
+		},
+		transformIndexHtml(html) {
+			return rewrite(html, tags({}, defaults, void 0));
+		},
+		closeBundle() {
+			if (config.command !== "build" || this.environment.config.consumer !== "client") return;
+			if (hooked) write();
+			else last();
+		},
+		buildApp: {
+			order: "post",
+			handler: async (builder) => {
+				hooked = true;
+				if (builder.environments.client?.isBuilt) {
+					hooked = false;
+					write();
+				}
+			}
+		}
+	};
+}
+//#endregion
+export { seo };

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@menapo/seo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Head tags, hreflang and sitemaps for kit apps: one head({ title, description, image }) call per page, in every framework",
+  "keywords": [
+    "head",
+    "meta",
+    "open-graph",
+    "seo",
+    "sitemap",
+    "vite",
+    "vite-plugin"
+  ],
+  "homepage": "https://github.com/menapo/kit/blob/main/packages/seo/README.md",
+  "bugs": {
+    "url": "https://github.com/menapo/kit/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/menapo/kit.git",
+    "directory": "packages/seo"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.js",
+    "./server": "./dist/server.js",
+    "./test": "./dist/test.js",
+    "./vite": "./dist/vite.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@menapo/vi18n": "0.1.1",
+    "@playwright/test": "^1.64.1",
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2",
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",
+    "vite-plus": "1.3.0"
+  },
+  "peerDependencies": {
+    "@menapo/vi18n": "^0.1.1",
+    "vite": "^8.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@menapo/vi18n": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "check": "vp check",
+    "test": "vp test run",
+    "smoke:packed": "node scripts/smoke-packed.ts"
+  }
 }