@warlock.js/sitemap 5.15.0 → 5.17.0

package/cjs/index.cjs

@@ -1,90 +1,252 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+let node_zlib = require("node:zlib");
 
-//#region ../sitemap/src/collect-entries.ts
-const DYNAMIC_SEGMENT = /(^|\/):[A-Za-z_][A-Za-z0-9_]*/;
-/** A route path carries a dynamic segment (`[id]` -> `:id`) it cannot enumerate on its own. */
-function isDynamicRoutePath(routePath) {
-	return DYNAMIC_SEGMENT.test(routePath);
-}
-function isNoindex(robots) {
-	return robots !== void 0 && /noindex/i.test(robots);
-}
-/** Applies the config's `defaults` to any entry that omits `changefreq`/`priority` — shared by page-derived and app-supplied entries alike. */
-function withDefaults(entry, defaults) {
-	return {
-		...entry,
-		changefreq: entry.changefreq ?? defaults?.changefreq,
-		priority: entry.priority ?? defaults?.priority
-	};
+//#region ../sitemap/src/errors.ts
+/**
+* The `baseUrl` given to a `Sitemap` is not an absolute http(s) URL.
+*
+* Thrown from the CONSTRUCTOR: a sitemap that cannot produce a valid URL
+* should not exist, and the mistake belongs at the line that wrote the value
+* rather than at the first request that reads it.
+*/
+var InvalidBaseUrlError = class extends Error {
+	constructor(value, reason) {
+		super(`Invalid sitemap baseUrl ${JSON.stringify(value)}: ${reason}.`);
+		this.name = "InvalidBaseUrlError";
+	}
+};
+/** An entry the sitemap protocol cannot represent. Thrown from `add()`. */
+var InvalidSitemapEntryError = class extends Error {
+	constructor(reason) {
+		super(`Invalid sitemap entry: ${reason}.`);
+		this.name = "InvalidSitemapEntryError";
+	}
+};
+/**
+* Two `SitemapIndex` source keys collide once canonicalised (`en-US` and
+* `en-us` would produce the same filename on a case-insensitive filesystem
+* and silently overwrite one another). Thrown from `addSource()`, not at
+* `saveTo()`, so the mistake is caught at the line that registered it.
+*/
+var DuplicateSourceKeyError = class extends Error {
+	constructor(key) {
+		super(`Duplicate sitemap source key ${JSON.stringify(key)}: keys collide case-insensitively and would overwrite one another's shard files.`);
+		this.name = "DuplicateSourceKeyError";
+	}
+};
+/**
+* `SitemapIndex.saveTo(outDir)` swaps the ENTIRE `outDir` for a freshly
+* written set (`atomic-publish.ts`). That is safe only when `outDir` is a
+* directory this package already owns — marked by its own
+* `.sitemap-set.json` from a prior publish. A non-empty directory with no
+* marker is presumed to belong to someone else (a caller's `public/`, most
+* dangerously) and is never swapped or deleted; this is thrown instead, from
+* `saveTo()` before anything is written.
+*/
+var UnownedOutputDirectoryError = class extends Error {
+	constructor(outDir) {
+		super(`Refusing to publish a sitemap set to ${JSON.stringify(outDir)}: this directory already has content but no ".sitemap-set.json" marker from a previous @warlock.js/sitemap publish, so it is not safe to swap or delete. Point saveTo() at a dedicated, sitemap-only directory instead.`);
+		this.name = "UnownedOutputDirectoryError";
+	}
+};
+
+//#endregion
+//#region ../sitemap/src/atomic-publish.ts
+/**
+* Marks a directory as one `publishAtomically` swapped into place. Its
+* presence is the ONLY thing that lets a later publish treat the directory
+* as safe to swap out from under itself — see {@link assertOutDirIsOwned}.
+*/
+const OWNERSHIP_MARKER_FILE = ".sitemap-set.json";
+const OWNERSHIP_MARKER_VERSION = 1;
+async function validateShards(tempDir, fileNames) {
+	for (const fileName of fileNames) {
+		const info = await (0, node_fs_promises.stat)((0, node_path.join)(tempDir, fileName)).catch(() => void 0);
+		if (!info || !info.isFile() || info.size === 0) throw new Error(`sitemap publish aborted: shard "${fileName}" is missing or empty.`);
+	}
 }
 /**
-* Combines page-derived entries with app-supplied ones (`SitemapConnectorOptions.entries`),
-* deduplicating by `path`. App-supplied entries are ADDED, not substituted — an
-* app with both a page graph and extra URLs (e.g. rows the page graph can't
-* see) wants both — but where the same path appears in both, the app-supplied
-* entry wins, since it was written for that exact path on purpose.
+* `outDir` is safe to take over when it does not exist yet, is empty, or
+* already carries {@link OWNERSHIP_MARKER_FILE} from a previous publish.
+* Anything else — a non-empty directory this package never wrote — is
+* refused rather than swapped or deleted (`de97020e`).
 */
-function mergeSitemapEntries(pageEntries, appEntries) {
-	const byPath = /* @__PURE__ */ new Map();
-	for (const entry of pageEntries) byPath.set(entry.path, entry);
-	for (const entry of appEntries) byPath.set(entry.path, entry);
-	return Array.from(byPath.values());
+async function assertOutDirIsOwned(outDir) {
+	const entries = await (0, node_fs_promises.readdir)(outDir).catch((error) => {
+		if (error.code === "ENOENT") return void 0;
+		throw error;
+	});
+	if (entries === void 0 || entries.length === 0) return;
+	if (!entries.includes(OWNERSHIP_MARKER_FILE)) throw new UnownedOutputDirectoryError(outDir);
 }
 /**
-* Walks the routable pages and produces the entries + the unresolved-dynamic
-* diagnostic input, applying every exclusion rule:
+* Writes a complete set into a sibling temp directory, validates that every
+* file it named actually exists and is non-empty, then swaps it into
+* `outDir`. A crawler arriving mid-write sees the previous complete set or
+* the new one, never a partial one, and a failed run leaves the previous set
+* untouched and rejects.
 *
-* - `metadata.robots` says `noindex` -> excluded.
-* - `sitemap: false` -> excluded.
-* - a `sitemap` export (any route) -> its returned entries, in place of the
-*   page's own route path.
-* - a dynamic route with no `sitemap` export -> omitted, name collected.
-* - everything else (static routes) -> one entry at the page's own route path.
-*
-* Not-found and error pages are excluded by construction: the caller is
-* expected to hand this only `DiscoveredRoutablePage`-derived entries, and
-* the not-found route is never one of those (`@warlock.js/web`'s discovery
-* reports it as a routable page for the client matcher, but the runtime
-* wiring filters it out before calling here — see the sitemap README).
+* `write` performs the writes and returns the file names (relative to the
+* temp dir) that must be present for the set to be considered valid — it is
+* only known after writing, since shard count depends on what was walked.
 */
-async function collectSitemapEntries(pages, options = {}) {
-	const entries = [];
-	const unresolvedDynamicRoutes = [];
-	for (const page of pages) {
-		if (isNoindex(page.robots)) continue;
-		if (page.sitemap === false) continue;
-		if (typeof page.sitemap === "function") {
-			const produced = await page.sitemap();
-			for (const entry of produced) entries.push(withDefaults(entry, options.defaults));
-			continue;
+async function publishAtomically(outDir, write) {
+	await assertOutDirIsOwned(outDir);
+	const parent = (0, node_path.dirname)(outDir);
+	await (0, node_fs_promises.mkdir)(parent, { recursive: true });
+	const tempDir = (0, node_path.join)(parent, `.${(0, node_path.basename)(outDir)}.tmp-${process.pid}-${Date.now()}`);
+	await (0, node_fs_promises.mkdir)(tempDir, { recursive: true });
+	try {
+		await validateShards(tempDir, await write(tempDir));
+		await (0, node_fs_promises.writeFile)((0, node_path.join)(tempDir, OWNERSHIP_MARKER_FILE), JSON.stringify({
+			package: "@warlock.js/sitemap",
+			version: OWNERSHIP_MARKER_VERSION
+		}), "utf8");
+		const displacedDir = (0, node_path.join)(parent, `.${(0, node_path.basename)(outDir)}.previous-${Date.now()}`);
+		let displacedPrevious = false;
+		try {
+			await (0, node_fs_promises.rename)(outDir, displacedDir);
+			displacedPrevious = true;
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
 		}
-		if (isDynamicRoutePath(page.routePath)) {
-			unresolvedDynamicRoutes.push(page.routeName);
-			continue;
+		try {
+			await (0, node_fs_promises.rename)(tempDir, outDir);
+		} catch (error) {
+			if (displacedPrevious) await (0, node_fs_promises.rename)(displacedDir, outDir);
+			throw error;
 		}
-		entries.push(withDefaults({ path: page.routePath }, options.defaults));
+		if (displacedPrevious) await (0, node_fs_promises.rm)(displacedDir, {
+			recursive: true,
+			force: true
+		});
+	} catch (error) {
+		await (0, node_fs_promises.rm)(tempDir, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+}
+
+//#endregion
+//#region ../sitemap/src/atomic-write-file.ts
+const defaultDeps = {
+	writeFile: node_fs_promises.writeFile,
+	rename: node_fs_promises.rename,
+	rm: node_fs_promises.rm
+};
+const RENAME_RETRY_ATTEMPTS = 5;
+const RENAME_RETRY_DELAY_MS = 20;
+function delay(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Windows can report a rename over an existing file as EPERM/EBUSY while something briefly holds the target (an AV scan, a reader) — retrying is correct there, not a masked bug. */
+function isTransientRenameError(error) {
+	const code = error?.code;
+	return code === "EPERM" || code === "EBUSY";
+}
+async function renameWithRetry(from, to, deps) {
+	for (let attempt = 1; attempt <= RENAME_RETRY_ATTEMPTS; attempt++) try {
+		await deps.rename(from, to);
+		return;
+	} catch (error) {
+		if (attempt === RENAME_RETRY_ATTEMPTS || !isTransientRenameError(error)) throw error;
+		await delay(RENAME_RETRY_DELAY_MS * attempt);
+	}
+}
+/**
+* Writes `content` to `filePath` atomically: the content lands in a unique
+* sibling temp file first — same directory, so same filesystem, so the
+* rename that follows is atomic — and only then is renamed over the target.
+* An interrupted or failing write never truncates or otherwise touches the
+* existing target; on any failure the temp file is removed and the error is
+* rethrown.
+*/
+async function atomicWriteFile(filePath, content, deps = defaultDeps) {
+	const tempPath = (0, node_path.join)((0, node_path.dirname)(filePath), `.${(0, node_path.basename)(filePath)}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+	try {
+		await deps.writeFile(tempPath, content, "utf8");
+		await renameWithRetry(tempPath, filePath, deps);
+	} catch (error) {
+		await deps.rm(tempPath, { force: true }).catch(() => void 0);
+		throw error;
 	}
-	return {
-		entries,
-		unresolvedDynamicRoutes
-	};
 }
 
 //#endregion
-//#region ../sitemap/src/diagnostic.ts
+//#region ../sitemap/src/lastmod.ts
 /**
-* The dev-mode diagnostic for dynamic routes {@link collectSitemapEntries}
-* (`collect-entries.ts`) could not enumerate — the whole reason this package
-* is written carefully. A dynamic route cannot be enumerated without
-* application data; what the framework controls is whether the developer
-* finds out. Returns `undefined` when there is nothing to report, so a caller
-* can `if (message) console.warn(message)` without an extra length check.
+* Serialises a `lastmod` value.
+*
+* A `Date` becomes W3C datetime, which is what the schema wants and what
+* `toISOString()` already produces. A string is passed through UNTOUCHED: a
+* caller who already holds an ISO string gets it back verbatim rather than
+* having us re-parse it and risk shifting it across a timezone.
 */
-function describeUnresolvedDynamicRoutes(routeNames) {
-	if (routeNames.length === 0) return void 0;
-	const plural = routeNames.length === 1 ? "" : "s";
-	const named = routeNames.map((name) => `  - ${name}`).join("\n");
-	return `[warlock:sitemap] ${routeNames.length} dynamic route${plural} ${routeNames.length === 1 ? "has" : "have"} no \`sitemap\` export and ${routeNames.length === 1 ? "is" : "are"} OMITTED from sitemap.xml:\n${named}\nA dynamic route cannot be enumerated without application data. Add \`export const sitemap: SitemapEntries = async () => [...]\` to each page above, or \`export const sitemap = false\` to keep it out of the sitemap deliberately.`;
+function formatLastmod(value) {
+	if (value instanceof Date) {
+		if (Number.isNaN(value.getTime())) throw new InvalidSitemapEntryError("lastmod is an invalid Date");
+		return value.toISOString();
+	}
+	if (typeof value !== "string" || value.trim() === "") throw new InvalidSitemapEntryError("lastmod must be a non-empty string or a Date");
+	return value;
+}
+
+//#endregion
+//#region ../sitemap/src/normalize-entry.ts
+const CHANGE_FREQS = [
+	"always",
+	"hourly",
+	"daily",
+	"weekly",
+	"monthly",
+	"yearly",
+	"never"
+];
+function assertChangeFreq(value) {
+	if (!CHANGE_FREQS.includes(value)) throw new InvalidSitemapEntryError(`changefreq ${JSON.stringify(value)} is not one of ${CHANGE_FREQS.join(", ")}`);
+}
+function assertPriority(value) {
+	if (typeof value !== "number" || Number.isNaN(value) || value < 0 || value > 1) throw new InvalidSitemapEntryError(`priority ${JSON.stringify(value)} is outside the protocol range 0.0–1.0`);
+}
+/** Every stored path carries its leading slash, so `/a` and `a` are one entry, not two. */
+function normalizePath(path) {
+	if (typeof path !== "string" || path.trim() === "") throw new InvalidSitemapEntryError("path is required and must be a non-empty string");
+	if (/^https?:\/\//i.test(path)) return path;
+	return path.startsWith("/") ? path : `/${path}`;
+}
+/**
+* Validates one entry and folds the builder's defaults into it. Defaults are
+* resolved HERE rather than at serialisation time so that `entries()` shows
+* what will actually be emitted — a diagnostic that reports something other
+* than the output is worse than none.
+*/
+function normalizeEntry(entry, defaults) {
+	const path = normalizePath(entry.path);
+	const changefreq = entry.changefreq ?? defaults.changefreq;
+	const priority = entry.priority ?? defaults.priority;
+	const lastmod = entry.lastmod ?? defaults.lastmod;
+	if (changefreq !== void 0) assertChangeFreq(changefreq);
+	if (priority !== void 0) assertPriority(priority);
+	const alternates = entry.alternates?.map((alternate) => {
+		if (typeof alternate?.hreflang !== "string" || alternate.hreflang.trim() === "") throw new InvalidSitemapEntryError("alternate hreflang is required");
+		return {
+			hreflang: alternate.hreflang,
+			path: normalizePath(alternate.path)
+		};
+	});
+	return {
+		path,
+		...entry.name !== void 0 ? { name: entry.name } : {},
+		...entry.route !== void 0 ? { route: entry.route } : {},
+		...lastmod !== void 0 ? { lastmod: formatLastmod(lastmod) } : {},
+		...changefreq !== void 0 ? { changefreq } : {},
+		...priority !== void 0 ? { priority } : {},
+		...alternates !== void 0 ? { alternates } : {}
+	};
 }
 
 //#endregion
@@ -98,26 +260,31 @@ function joinOrigin(origin, routePath) {
 	return `${origin.endsWith("/") ? origin.slice(0, -1) : origin}${routePath.startsWith("/") ? routePath : `/${routePath}`}`;
 }
 /**
-* Raised when the sitemap is enabled but no public origin is configured.
-* Refuses to boot rather than falling back to a request-derived origin: a
-* sitemap served with the wrong host is worse than one that refuses to
-* start, because nothing downstream ever tells you it was wrong.
+* Validates a `baseUrl` and returns it without its trailing slash.
+*
+* `new URL()` accepts `mailto:` and `file:` happily, so the protocol is
+* checked explicitly — a sitemap `<loc>` that is not http(s) is not a document
+* any crawler will fetch.
 */
-var MissingPublicUrlError = class extends Error {
-	constructor() {
-		super("Sitemap is enabled but no public origin is configured. Set `app.publicUrl` in warlock.config.ts, or the PUBLIC_APP_URL environment variable.");
-		this.name = "MissingPublicUrlError";
+function normalizeBaseUrl(value) {
+	if (typeof value !== "string" || value.trim() === "") throw new InvalidBaseUrlError(value, "expected a non-empty string");
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		throw new InvalidBaseUrlError(value, "not an absolute URL");
 	}
-};
-/**
-* The origin the sitemap is served from: `app.publicUrl` first, then the
-* `PUBLIC_APP_URL` env fallback. Throws {@link MissingPublicUrlError} when
-* neither is set — this is the boot-time check, called once, not per-request.
-*/
-function resolveOrigin(options = {}) {
-	const origin = options.publicUrl ?? options.env?.PUBLIC_APP_URL;
-	if (!origin) throw new MissingPublicUrlError();
-	return origin;
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new InvalidBaseUrlError(value, `unsupported protocol "${parsed.protocol}"`);
+	const href = parsed.href;
+	return href.endsWith("/") ? href.slice(0, -1) : href;
+}
+/** True for a value already usable as a `<loc>` without joining an origin. */
+function isAbsoluteUrl(value) {
+	return /^https?:\/\//i.test(value);
+}
+/** Resolves an entry or alternate path against the base URL, unless it is already absolute. */
+function resolveAgainstBase(baseUrl, path) {
+	return isAbsoluteUrl(path) ? path : joinOrigin(baseUrl, path);
 }
 
 //#endregion
@@ -133,147 +300,456 @@ const XML_ESCAPES = {
 function escapeXml(value) {
 	return value.replace(/[&<>"']/g, (char) => XML_ESCAPES[char] ?? char);
 }
-function entryXml(entry, origin) {
-	const lines = [`  <url>`, `    <loc>${escapeXml(joinOrigin(origin, entry.path))}</loc>`];
+const XHTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+/**
+* The `xmlns:xhtml` attribute exactly as it appears on `<urlset>`, including
+* its leading space. Exported so the shard writer can charge its byte length
+* against the ceiling without duplicating the string it measures.
+*/
+const XHTML_NAMESPACE_ATTR = ` xmlns:xhtml="${XHTML_NAMESPACE}"`;
+/**
+* Renders one `<url>` block. Exported so the streaming writer can measure the
+* exact bytes it is about to append before deciding whether the byte ceiling
+* forces a new shard — a separate approximation could disagree with what is
+* actually written.
+*/
+function renderUrlBlock(entry, baseUrl) {
+	const lines = [`  <url>`, `    <loc>${escapeXml(resolveAgainstBase(baseUrl, entry.path))}</loc>`];
 	if (entry.lastmod !== void 0) lines.push(`    <lastmod>${escapeXml(entry.lastmod)}</lastmod>`);
 	if (entry.changefreq !== void 0) lines.push(`    <changefreq>${entry.changefreq}</changefreq>`);
 	if (entry.priority !== void 0) lines.push(`    <priority>${entry.priority}</priority>`);
+	for (const alternate of entry.alternates ?? []) {
+		const href = escapeXml(resolveAgainstBase(baseUrl, alternate.path));
+		lines.push(`    <xhtml:link rel="alternate" hreflang="${escapeXml(alternate.hreflang)}" href="${href}"/>`);
+	}
 	lines.push(`  </url>`);
 	return lines.join("\n");
 }
 /**
 * Serialises entries into a `urlset` sitemap document — the sitemaps.org
 * namespace, `<url>` per entry, element order `loc` / `lastmod` / `changefreq`
-* / `priority` (schema order; a validator that checks order rejects any other).
+* / `priority` (schema order; a validator that checks order rejects any other),
+* then any `xhtml:link` alternates.
+*
+* The xhtml namespace is declared only when some entry actually carries an
+* alternate — an unused namespace on every single-language sitemap is noise.
 */
-function buildSitemapXml(entries, origin) {
-	const body = entries.map((entry) => entryXml(entry, origin)).join("\n");
-	return "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n" + (body.length > 0 ? `${body}\n` : "") + `</urlset>\n`;
+function buildSitemapXml(entries, baseUrl) {
+	const namespaces = entries.some((entry) => (entry.alternates?.length ?? 0) > 0) ? XHTML_NAMESPACE_ATTR : "";
+	const body = entries.map((entry) => renderUrlBlock(entry, baseUrl)).join("\n");
+	return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"${namespaces}>\n` + (body.length > 0 ? `${body}\n` : "") + `</urlset>\n`;
 }
 
 //#endregion
-//#region ../sitemap/src/sitemap-connector.ts
-/** Default path when `src/config/sitemap.ts` does not set one. */
-const DEFAULT_SITEMAP_PATH = "/sitemap.xml";
-/**
-* Boots after the HTTP connector (`ConnectorPriority.HTTP` is `5`) and after
-* web (`5.5`, `web-connector-factory.ts`) — the route it registers has to
-* land on the same router web's pages already share, and `listRoutablePages`
-* only has a page graph to read once web has scanned it.
-*/
-const SITEMAP_CONNECTOR_PRIORITY = 5.6;
+//#region ../sitemap/src/sitemap.ts
 /**
-* Raised at `boot()` when the sitemap is enabled but has no way to produce
-* entries: `@warlock.js/web` is not installed, so there is no page registry
-* for `listRoutablePages()` to read, AND no `entries` option was supplied.
-* Refuses to boot rather than registering a route that would silently serve
-* an empty `<urlset>` — the same reasoning as {@link MissingPublicUrlError}:
-* a sitemap that looks complete while producing nothing is worse than one
-* that never started.
+* A bounded sitemap builder: it RETAINS every entry, which is what makes
+* `entries()` and a repeatable `toXML()` possible, and is exactly right up to
+* the sitemaps.org ceiling of 50,000 URLs / 50MB.
+*
+* Above that ceiling this is the wrong tool — the streaming writer retains
+* nothing and emits shards plus an index instead. The two modes are separate
+* on purpose: a class that promised not to retain entries and still offered
+* `entries()` would be lying about one of them.
 */
-var NoPageRegistryError = class extends Error {
-	constructor() {
-		super("Sitemap is enabled but has no source of entries: `@warlock.js/web` is not installed, so there is no page registry to read, and no `entries` option was supplied either. Fix this by installing `@warlock.js/web`, or by passing `sitemapConnector({ entries: async () => [...] })` with your own supplier.");
-		this.name = "NoPageRegistryError";
+var Sitemap = class {
+	baseUrl;
+	defaults;
+	/** Keyed by path: a duplicate `<loc>` makes the document invalid, so the later add wins. */
+	entriesByPath = /* @__PURE__ */ new Map();
+	/** Insertion order per path, so `duplicates()` can name every colliding source. */
+	routesByPath = /* @__PURE__ */ new Map();
+	/** Declared patterns, including ones that never contributed a URL. */
+	declaredRoutes = /* @__PURE__ */ new Set();
+	constructor(options) {
+		this.baseUrl = normalizeBaseUrl(options?.baseUrl);
+		this.defaults = {
+			changefreq: options.changefreq,
+			priority: options.priority,
+			lastmod: options.lastmod
+		};
+	}
+	add(entry) {
+		const resolved = normalizeEntry(entry, this.defaults);
+		this.entriesByPath.set(resolved.path, resolved);
+		const seen = this.routesByPath.get(resolved.path);
+		if (seen) seen.push(resolved.route);
+		else this.routesByPath.set(resolved.path, [resolved.route]);
+		if (resolved.route !== void 0) this.declaredRoutes.add(resolved.route);
+		return this;
+	}
+	addMany(entries) {
+		for (const entry of entries) this.add(entry);
+		return this;
+	}
+	/**
+	* Names a pattern the caller EXPECTS to contribute URLs, so that one which
+	* contributes none shows up in `routes()` as a `count: 0` row instead of as
+	* silence. A dynamic route whose supplier returned nothing is the failure
+	* this package exists to make visible.
+	*/
+	declareRoute(route) {
+		this.declaredRoutes.add(route);
+		return this;
+	}
+	get size() {
+		return this.entriesByPath.size;
+	}
+	entries() {
+		return [...this.entriesByPath.values()];
+	}
+	routes() {
+		const counts = /* @__PURE__ */ new Map();
+		for (const route of this.declaredRoutes) counts.set(route, 0);
+		for (const entry of this.entriesByPath.values()) {
+			if (entry.route === void 0) continue;
+			counts.set(entry.route, (counts.get(entry.route) ?? 0) + 1);
+		}
+		return [...counts].map(([route, count]) => ({
+			route,
+			count
+		}));
+	}
+	/**
+	* Every path added more than once. The override is silent — it is not
+	* hidden: a collision between static discovery and a dynamic supplier is a
+	* real defect, and the CALLER decides whether it fails their build. This
+	* package reports; it never prints and never throws over a duplicate.
+	*/
+	duplicates() {
+		const reports = [];
+		for (const [path, routes] of this.routesByPath) {
+			if (routes.length < 2) continue;
+			reports.push({
+				path,
+				count: routes.length,
+				routes: [...routes]
+			});
+		}
+		return reports;
+	}
+	/** Pure and repeatable: calling it twice returns the same string and mutates nothing. */
+	toXML() {
+		return buildSitemapXml(this.entries(), this.baseUrl);
+	}
+	/**
+	* Writes the document, creating parent directories so a clean checkout
+	* works. The write is atomic: a failed or interrupted publish leaves
+	* whatever was already at `filePath` untouched instead of truncating it.
+	*/
+	async saveTo(filePath) {
+		await (0, node_fs_promises.mkdir)((0, node_path.dirname)(filePath), { recursive: true });
+		await atomicWriteFile(filePath, this.toXML());
+	}
+	/**
+	* Publishes the document as the whole content of `outDir`, exactly the way
+	* `SitemapIndex.saveTo` publishes a set: swapped in atomically, and marked
+	* as owned. So a site that later outgrows one file can publish an index
+	* into the same directory, and a later single file removes stale shards.
+	* Refuses a non-empty directory this package did not write
+	* (`UnownedOutputDirectoryError`). Returns the published file's path.
+	*/
+	async publishTo(outDir, fileName = "sitemap.xml") {
+		const xml = this.toXML();
+		await publishAtomically(outDir, async (tempDir) => {
+			await (0, node_fs_promises.writeFile)((0, node_path.join)(tempDir, fileName), xml, "utf8");
+			return [fileName];
+		});
+		return (0, node_path.join)(outDir, fileName);
 	}
 };
-/** Adapts one `listRoutablePages()` result into the package's own minimal `RoutablePage` shape. */
-function toRoutablePage(page) {
-	const metadata = page.metadata;
-	const robots = metadata !== null && typeof metadata === "object" && "robots" in metadata ? metadata.robots : void 0;
+
+//#endregion
+//#region ../sitemap/src/sitemap-index-options.ts
+/** The sitemaps.org limits. Never clamped to — a silently clamped option is a lie about what was written. */
+const PROTOCOL_MAX_URLS_PER_FILE = 5e4;
+const PROTOCOL_MAX_BYTES_PER_FILE = 50 * 1024 * 1024;
+/** Validates and folds in defaults, once, at the constructor — the same discipline as `Sitemap`. */
+function normalizeSitemapIndexOptions(options) {
+	const baseUrl = normalizeBaseUrl(options?.baseUrl);
+	const maxUrlsPerFile = options.maxUrlsPerFile ?? 5e4;
+	const maxBytesPerFile = options.maxBytesPerFile ?? 52428800;
+	if (!Number.isInteger(maxUrlsPerFile) || maxUrlsPerFile < 1 || maxUrlsPerFile > 5e4) throw new RangeError(`maxUrlsPerFile must be an integer between 1 and the sitemaps.org ceiling of ${PROTOCOL_MAX_URLS_PER_FILE}, got ${JSON.stringify(maxUrlsPerFile)}.`);
+	if (!Number.isFinite(maxBytesPerFile) || maxBytesPerFile < 1 || maxBytesPerFile > 52428800) throw new RangeError(`maxBytesPerFile must be between 1 and the sitemaps.org ceiling of ${PROTOCOL_MAX_BYTES_PER_FILE} bytes, got ${JSON.stringify(maxBytesPerFile)}.`);
 	return {
-		routeName: page.routeName,
-		routePath: page.routePath,
-		robots: typeof robots === "string" ? robots : void 0,
-		sitemap: page.sitemap
+		baseUrl,
+		filePrefix: options.filePrefix ?? "sitemap",
+		indexFileName: options.indexFileName ?? "sitemap_index.xml",
+		gzip: options.gzip ?? false,
+		maxUrlsPerFile,
+		maxBytesPerFile,
+		defaults: {
+			changefreq: options.changefreq,
+			priority: options.priority,
+			lastmod: options.lastmod
+		}
 	};
 }
+
+//#endregion
+//#region ../sitemap/src/shard-name.ts
+const SAFE_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
 /**
-* Construct the sitemap connector.
-*
-* At `boot()`: reads the `sitemap` config (a no-op when `enabled` is not
-* `true`), resolves the public origin ONCE — failing loud via
-* {@link resolveOrigin}'s {@link MissingPublicUrlError} rather than falling
-* back to a request-derived host — and registers `GET <config.path>`.
-*
-* The route itself re-reads the page graph on every request via
-* `listRoutablePages()`, not once at boot: the registry can change under
-* `warlock dev`, and a sitemap that only reflects the app's shape at the
-* moment it booted is stale in exactly the way that made `2ede40cf`-class
-* defects expensive.
+* Canonical form used to detect a case collision before it reaches the
+* filesystem: `en-US` and `en-us` would produce the same file on a
+* case-insensitive filesystem and silently overwrite one another.
 *
-* @example
-* // warlock.config.ts
-* import { sitemapConnector } from "@warlock.js/sitemap";
-*
-* export default defineConfig({ connectors: [sitemapConnector()] });
+* The key reaches the filename and nothing else — it is validated as a
+* filename fragment, not interpreted as a locale or anything else.
 */
-function sitemapConnector(options = {}) {
-	let active = false;
-	const connector = {
-		name: "sitemap",
-		priority: SITEMAP_CONNECTOR_PRIORITY,
-		lifecyclePhase: "late",
-		isActive: () => active,
-		async boot() {
-			const { config, router } = await import("@warlock.js/core");
-			const sitemapConfig = options.config ?? config.get("sitemap");
-			if (!sitemapConfig?.enabled) return;
-			const origin = resolveOrigin({
-				publicUrl: config.get("app")?.publicUrl,
-				env: process.env
-			});
-			const path = sitemapConfig.path || "/sitemap.xml";
-			let listRoutablePages;
-			try {
-				({listRoutablePages} = await import("@warlock.js/web/build"));
-			} catch {
-				listRoutablePages = void 0;
-			}
-			if (!listRoutablePages && !options.entries) throw new NoPageRegistryError();
-			router.get(path, async ({ response }) => {
-				const { entries: pageEntries, unresolvedDynamicRoutes } = await collectSitemapEntries(listRoutablePages ? (await listRoutablePages({ appRoot: process.cwd() })).map(toRoutablePage) : [], { defaults: sitemapConfig.defaults });
-				const entries = mergeSitemapEntries(pageEntries, options.entries ? (await options.entries()).map((entry) => withDefaults(entry, sitemapConfig.defaults)) : []);
-				if (process.env.NODE_ENV !== "production") {
-					const diagnostic = describeUnresolvedDynamicRoutes(unresolvedDynamicRoutes);
-					if (diagnostic) console.warn(diagnostic);
-				}
-				const xml = buildSitemapXml(entries, origin);
-				return response.setContentType("application/xml").send(xml);
-			});
-			active = true;
-		},
-		async start() {},
-		async restart() {
-			await connector.shutdown();
-			await connector.boot();
-		},
-		async shutdown() {
-			active = false;
-		},
-		shouldRestart(changedFiles) {
-			return changedFiles.some((file) => {
-				const normalized = file.replace(/\\/g, "/");
-				return normalized === "src/config/sitemap.ts" || normalized.endsWith("/src/config/sitemap.ts");
-			});
-		}
+function canonicalizeSourceKey(key) {
+	if (typeof key !== "string" || !SAFE_KEY_PATTERN.test(key)) throw new RangeError(`sitemap source key ${JSON.stringify(key)} must be a non-empty filename fragment (letters, digits, "-", "_").`);
+	return key.toLowerCase();
+}
+/**
+* Stable, zero-padded, ordinal from shard one. A group that later crosses a
+* ceiling GAINS a file; it never renames the first one, so a crawler that has
+* already indexed `sitemap-en-0001.xml` never loses it because the site grew.
+*/
+function shardFileName(filePrefix, key, ordinal, gzip) {
+	const paddedOrdinal = String(ordinal).padStart(4, "0");
+	const base = key !== void 0 ? `${filePrefix}-${key}-${paddedOrdinal}` : `${filePrefix}-${paddedOrdinal}`;
+	return gzip ? `${base}.xml.gz` : `${base}.xml`;
+}
+
+//#endregion
+//#region ../sitemap/src/sitemap-shard-writer.ts
+function envelopeBytes(baseUrl) {
+	return Buffer.byteLength(buildSitemapXml([], baseUrl), "utf8");
+}
+/**
+* The extra bytes `<urlset>` gains for `xmlns:xhtml="…"` once a shard holds
+* an entry with alternates. Charged separately from `envelopeBytes()` so the
+* ceiling check can add it exactly once — the moment the first alternate
+* enters the buffer — rather than missing it entirely, which would let a
+* shard's real bytes on disk exceed the ceiling it was rolled against.
+*/
+const NAMESPACE_BYTES = Buffer.byteLength(XHTML_NAMESPACE_ATTR, "utf8");
+async function writeShardFile(ctx, fileName, entries) {
+	const xml = buildSitemapXml(entries, ctx.baseUrl);
+	const filePath = (0, node_path.join)(ctx.tempDir, fileName);
+	if (ctx.gzip) {
+		const compressed = (0, node_zlib.gzipSync)(Buffer.from(xml, "utf8"));
+		await (0, node_fs_promises.writeFile)(filePath, compressed);
+		return { bytes: compressed.byteLength };
+	}
+	await (0, node_fs_promises.writeFile)(filePath, xml, "utf8");
+	return { bytes: Buffer.byteLength(xml, "utf8") };
+}
+/**
+* Walks one group's factories, one at a time, rolling to a new shard on
+* whichever ceiling — URL count or serialised bytes — is hit first. Holds
+* only the current shard's buffer, never the whole group.
+*/
+async function writeShardGroup(group, ctx) {
+	const results = [];
+	let buffer = [];
+	let bufferBytes = envelopeBytes(ctx.baseUrl);
+	let bufferHasAlternates = false;
+	let ordinal = 1;
+	const flush = async () => {
+		if (buffer.length === 0) return;
+		const fileName = shardFileName(ctx.filePrefix, group.key, ordinal, ctx.gzip);
+		const { bytes } = await writeShardFile(ctx, fileName, buffer);
+		results.push({
+			fileName,
+			key: group.key,
+			urls: buffer.length,
+			bytes,
+			gzipped: ctx.gzip
+		});
+		ordinal += 1;
+		buffer = [];
+		bufferBytes = envelopeBytes(ctx.baseUrl);
+		bufferHasAlternates = false;
 	};
-	return connector;
+	for (const factory of group.factories) {
+		const source = await factory();
+		for await (const rawEntry of source) {
+			const resolved = normalizeEntry(rawEntry, ctx.defaults);
+			if (!ctx.duplicates.attempt(resolved.path, resolved.route)) continue;
+			const entryHasAlternates = (resolved.alternates?.length ?? 0) > 0;
+			const blockBytes = Buffer.byteLength(renderUrlBlock(resolved, ctx.baseUrl), "utf8") + 1;
+			const addedBytes = blockBytes + (entryHasAlternates && !bufferHasAlternates ? NAMESPACE_BYTES : 0);
+			const hitsUrlCeiling = buffer.length >= ctx.maxUrlsPerFile;
+			const hitsByteCeiling = buffer.length > 0 && bufferBytes + addedBytes > ctx.maxBytesPerFile;
+			if (hitsUrlCeiling || hitsByteCeiling) await flush();
+			const addsNamespaceNow = entryHasAlternates && !bufferHasAlternates;
+			buffer.push(resolved);
+			bufferBytes += blockBytes + (addsNamespaceNow ? NAMESPACE_BYTES : 0);
+			if (addsNamespaceNow) bufferHasAlternates = true;
+			ctx.routes.record(resolved.route);
+		}
+	}
+	await flush();
+	if (results.length === 0) results.push({
+		fileName: shardFileName(ctx.filePrefix, group.key, 1, ctx.gzip),
+		key: group.key,
+		urls: 0,
+		bytes: 0,
+		gzipped: false
+	});
+	return results;
+}
+
+//#endregion
+//#region ../sitemap/src/sitemap-index-xml.ts
+/**
+* Serialises the flat master `sitemapindex` document: every shard of every
+* group, directly, in the order the groups and shards were produced — no
+* nested per-group indexes, and never a zero-url row (that is a diagnostic
+* for `files`, not something a crawler should be told to fetch).
+*/
+function buildSitemapIndexXml(files, baseUrl) {
+	const body = files.filter((file) => file.urls > 0).map((file) => {
+		return `  <sitemap>\n    <loc>${escapeXml(joinOrigin(baseUrl, file.fileName))}</loc>\n  </sitemap>`;
+	}).join("\n");
+	return "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<sitemapindex xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\n" + (body.length > 0 ? `${body}\n` : "") + `</sitemapindex>\n`;
 }
 
 //#endregion
-exports.DEFAULT_SITEMAP_PATH = DEFAULT_SITEMAP_PATH;
-exports.MissingPublicUrlError = MissingPublicUrlError;
-exports.NoPageRegistryError = NoPageRegistryError;
-exports.SITEMAP_CONNECTOR_PRIORITY = SITEMAP_CONNECTOR_PRIORITY;
+//#region ../sitemap/src/duplicate-path-tracker.ts
+/**
+* The streaming equivalent of `Sitemap`'s `routesByPath` map. A streaming
+* writer cannot compare an entry against 500K predecessors, so it keeps only
+* the paths (and contributing routes) it has already seen. A duplicate is
+* SKIPPED here, not last-wins — the earlier one is already on disk.
+*/
+var DuplicatePathTracker = class {
+	routesByPath = /* @__PURE__ */ new Map();
+	/** Records an attempt to write `path`. Returns `false` when it was already seen — skip it. */
+	attempt(path, route) {
+		const seen = this.routesByPath.get(path);
+		if (seen) {
+			seen.push(route);
+			return false;
+		}
+		this.routesByPath.set(path, [route]);
+		return true;
+	}
+	report() {
+		const reports = [];
+		for (const [path, routes] of this.routesByPath) {
+			if (routes.length < 2) continue;
+			reports.push({
+				path,
+				count: routes.length,
+				routes: [...routes]
+			});
+		}
+		return reports;
+	}
+};
+
+//#endregion
+//#region ../sitemap/src/route-counter.ts
+/** Counts URLs actually written per declared route, across every shard of every group. */
+var RouteCounter = class {
+	counts = /* @__PURE__ */ new Map();
+	record(route) {
+		if (route === void 0) return;
+		this.counts.set(route, (this.counts.get(route) ?? 0) + 1);
+	}
+	summary() {
+		return [...this.counts].map(([route, count]) => ({
+			route,
+			count
+		}));
+	}
+};
+
+//#endregion
+//#region ../sitemap/src/sitemap-index.ts
+/**
+* The streaming path for 300–500K URLs: shards, one flat master index, gzip,
+* and an atomic publish. It is a SECOND mode, not a bigger `Sitemap` — it
+* retains only the current shard's buffer and the set of paths it has seen.
+* There is no `entries()`, `toXML()` or `size`; anyone who can afford those
+* is in `Sitemap` and should be there instead.
+*/
+var SitemapIndex = class {
+	options;
+	/** Every unnamed `addSource(factory)` call merges into this one group, sharing one shard counter. */
+	unnamedFactories = [];
+	namedGroups = [];
+	/** Canonical (lowercased) keys already registered, so a case collision is caught at `addSource()`. */
+	registeredKeys = /* @__PURE__ */ new Set();
+	constructor(options) {
+		this.options = normalizeSitemapIndexOptions(options);
+	}
+	addSource(keyOrSource, maybeSource) {
+		if (typeof keyOrSource === "string") {
+			const canonicalKey = canonicalizeSourceKey(keyOrSource);
+			if (this.registeredKeys.has(canonicalKey)) throw new DuplicateSourceKeyError(keyOrSource);
+			this.registeredKeys.add(canonicalKey);
+			this.namedGroups.push({
+				key: keyOrSource,
+				factories: [maybeSource]
+			});
+		} else this.unnamedFactories.push(keyOrSource);
+		return this;
+	}
+	/**
+	* Walks every group one at a time — never all at once — into a sibling
+	* temp directory, then publishes the whole set atomically. `files` is
+	* reported in registration order: the unnamed group first (if any), then
+	* named groups key-then-ordinal.
+	*/
+	async saveTo(outDir) {
+		const groups = [...this.unnamedFactories.length > 0 ? [{
+			key: void 0,
+			factories: this.unnamedFactories
+		}] : [], ...this.namedGroups];
+		const duplicates = new DuplicatePathTracker();
+		const routes = new RouteCounter();
+		let shardFiles = [];
+		const write = async (tempDir) => {
+			shardFiles = [];
+			for (const group of groups) {
+				const files = await writeShardGroup(group, {
+					tempDir,
+					baseUrl: this.options.baseUrl,
+					filePrefix: this.options.filePrefix,
+					gzip: this.options.gzip,
+					maxUrlsPerFile: this.options.maxUrlsPerFile,
+					maxBytesPerFile: this.options.maxBytesPerFile,
+					defaults: this.options.defaults,
+					duplicates,
+					routes
+				});
+				shardFiles.push(...files);
+			}
+			const indexXml = buildSitemapIndexXml(shardFiles, this.options.baseUrl);
+			await (0, node_fs_promises.writeFile)((0, node_path.join)(tempDir, this.options.indexFileName), indexXml, "utf8");
+			return [...shardFiles.filter((file) => file.urls > 0).map((file) => file.fileName), this.options.indexFileName];
+		};
+		await publishAtomically(outDir, write);
+		const files = shardFiles.map((file) => ({
+			path: (0, node_path.join)(outDir, file.fileName),
+			...file.key !== void 0 ? { key: file.key } : {},
+			urls: file.urls,
+			bytes: file.bytes,
+			gzipped: file.gzipped
+		}));
+		return {
+			indexPath: (0, node_path.join)(outDir, this.options.indexFileName),
+			files,
+			totalUrls: files.reduce((total, file) => total + file.urls, 0),
+			duplicates: duplicates.report(),
+			routes: routes.summary()
+		};
+	}
+};
+
+//#endregion
+exports.DuplicateSourceKeyError = DuplicateSourceKeyError;
+exports.InvalidBaseUrlError = InvalidBaseUrlError;
+exports.InvalidSitemapEntryError = InvalidSitemapEntryError;
+exports.Sitemap = Sitemap;
+exports.SitemapIndex = SitemapIndex;
+exports.UnownedOutputDirectoryError = UnownedOutputDirectoryError;
 exports.buildSitemapXml = buildSitemapXml;
-exports.collectSitemapEntries = collectSitemapEntries;
-exports.describeUnresolvedDynamicRoutes = describeUnresolvedDynamicRoutes;
 exports.escapeXml = escapeXml;
-exports.isDynamicRoutePath = isDynamicRoutePath;
 exports.joinOrigin = joinOrigin;
-exports.mergeSitemapEntries = mergeSitemapEntries;
-exports.resolveOrigin = resolveOrigin;
-exports.sitemapConnector = sitemapConnector;
-exports.withDefaults = withDefaults;
+exports.renderUrlBlock = renderUrlBlock;
 //# sourceMappingURL=index.cjs.map