@at-flux/astro-feature-flags 1.0.3 → 1.0.4

package/README.md

@@ -180,18 +180,19 @@ The dev toolbar changes client-side preview state only.
 
 ### Top-level options
 
-| Option             | Type                                  | Default         | Notes                                                                                                                                              |
-| ------------------ | ------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `configRoot`       | `string`                              | `process.cwd()` | Resolves relative `jsonConfigPath` values (root + per-environment).                                                                                |
-| `jsonConfigPath`   | `string`                              | unset           | Optional **root** JSON file merged after inline config (see merge order for per-environment files).                                                |
-| `forceEnvironment` | `string`                              | unset           | Pin the active layer (skips `when` / `AFF_ENVIRONMENT` validation).                                                                                |
-| `mode`             | `string`                              | `NODE_ENV`      | Optional advanced override for runtime resolution (mainly tests/tooling). Most apps should omit this and rely on `NODE_ENV` + `environments.when`. |
-| `env`              | `Record<string, string \| undefined>` | `process.env`   | `AFF_FEATURE_*` / `ASTRO_FEATURE_FLAGS` (not applied in `dev` layer).                                                                              |
-| `tokenNamespace`   | `string`                              | `'ff'`          | CSS var namespace (`--ff-c-*`).                                                                                                                    |
-| `flags`            | `Record<string, FlagConfig>`          | `{}`            | Flag declarations.                                                                                                                                 |
-| `environments`     | `Record<string, EnvironmentConfig>`   | _(see below)_   | Declare non-`dev` layers only; reserved `dev` is injected. At least one other key; exactly one `when: true` unless forced.                         |
-| `css`              | `DevOutlineCssOptions`                | defaults        | Global badge/outline layout and styling.                                                                                                           |
-| `staticMinify`     | `boolean`                             | `true`          | For static builds: route-prune disabled prefixes + cull gated HTML in `dist/`. Set `false` to keep emitted files untouched.                        |
+| Option             | Type                                  | Default         | Notes                                                                                                                                                                                              |
+| ------------------ | ------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `configRoot`       | `string`                              | `process.cwd()` | Resolves relative `jsonConfigPath` values (root + per-environment).                                                                                                                                |
+| `jsonConfigPath`   | `string`                              | unset           | Optional **root** JSON file merged after inline config (see merge order for per-environment files).                                                                                                |
+| `forceEnvironment` | `string`                              | unset           | Pin the active layer (skips `when` / `AFF_ENVIRONMENT` validation).                                                                                                                                |
+| `mode`             | `string`                              | `NODE_ENV`      | Optional advanced override for runtime resolution (mainly tests/tooling). Most apps should omit this and rely on `NODE_ENV` + `environments.when`.                                                 |
+| `env`              | `Record<string, string \| undefined>` | `process.env`   | `AFF_FEATURE_*` / `ASTRO_FEATURE_FLAGS` (not applied in `dev` layer).                                                                                                                              |
+| `tokenNamespace`   | `string`                              | `'ff'`          | CSS var namespace (`--ff-c-*`).                                                                                                                                                                    |
+| `flags`            | `Record<string, FlagConfig>`          | `{}`            | Flag declarations.                                                                                                                                                                                 |
+| `environments`     | `Record<string, EnvironmentConfig>`   | _(see below)_   | Declare non-`dev` layers only; reserved `dev` is injected. At least one other key; exactly one `when: true` unless forced.                                                                         |
+| `css`              | `DevOutlineCssOptions`                | defaults        | Global badge/outline layout and styling.                                                                                                                                                           |
+| `staticMinify`     | `boolean`                             | `true`          | For static builds: route-prune disabled prefixes + cull gated HTML in `dist/`. Set `false` to keep emitted files untouched.                                                                        |
+| `pruneSitemap`     | `boolean`                             | `true`          | Drop pruned routes from generated sitemaps in `dist/`. Needs this integration **after** `sitemap()` in `integrations`. See [Hide flagged routes from sitemaps](docs/how-to/hide-from-sitemaps.md). |
 
 If you omit `environments`, the integration injects a minimal reserved `dev` plus **`prod`** tied to `NODE_ENV` (or `mode` only if you explicitly override it) so `astroFeatureFlags()` still runs in small demos.
 

package/dist/index.d.mts

@@ -41,6 +41,12 @@ declare function normalizeElementBadgeLayout(input: ElementBadgeLayoutOptions |
 declare function elementBadgePositionBlock(layout: NormalizedElementBadgeLayout): string;
 //#endregion
 //#region src/dev-outline-css.d.ts
+/**
+ * Cascade layer for the declarations the app must be able to override without
+ * writing `!important`. Named rather than anonymous so the order statement in
+ * {@link affHeadInlineRuntime} can name it too.
+ */
+declare const DEV_LAYER = "aff-dev";
 type DevOutlineHiddenStrategy = "visibility" | "display";
 interface DevOutlineCssOptions extends ElementBadgeLayoutOptions {
   outlineWidth?: string;
@@ -65,6 +71,28 @@ interface DevOutlineCssOptions extends ElementBadgeLayoutOptions {
  * Dev-only styles: `data-ff="token"` (or space-separated tokens) gates outlines/badges.
  * `html[data-ff-route="<token>"]` (dev) adds a fixed top-right route badge (label only).
  * Toolbar toggles: `data-ff-enabled-*`, `data-ff-outline-*`, `data-ff-badge-*`, `--<namespace>-c-*`.
+ *
+ * The badge is an absolutely positioned `::before`, so its host has to be a
+ * containing block, and the host also wants rounding for the outline to follow.
+ * Both of those are the app's business, not ours: a flagged element that the app
+ * positions itself, or rounds itself, must keep doing so. Marking a flagged
+ * element must not move it.
+ *
+ * So `position` and `border-radius` are emitted inside `:where()` *and* inside
+ * the `aff-dev` cascade layer. `:where()` alone is not enough: an unlayered rule
+ * beats a layered one before specificity is ever consulted, so a zero-specificity
+ * unlayered rule still overrides Tailwind's `.rounded-full` and `.absolute`,
+ * which live in `@layer utilities`. Layering ours is what lets the app win.
+ *
+ * Layer priority follows the order layers are first declared, so the layer only
+ * sorts below the app's own layers if `@layer aff-dev;` appears before them in
+ * document order. The sheet opens with that statement for the case where it
+ * lands first, and {@link affHeadInlineRuntime} also prepends a style element
+ * carrying it as the first child of `<head>`, which is what actually guarantees
+ * the order at runtime.
+ *
+ * Everything else here is dev chrome the app has no opinion about, and stays at
+ * its natural specificity.
  */
 declare function createFeatureFlagStyles(runtime: ResolvedFeatureRuntime, css?: DevOutlineCssOptions): string;
 /**
@@ -85,11 +113,56 @@ declare function cullProductionHtml(html: string, runtime: ResolvedFeatureRuntim
  */
 declare function applyProductionHtmlCullToDist(outDir: string, runtime: ResolvedFeatureRuntime): void;
 //#endregion
+//#region src/sitemap-prune.d.ts
+/**
+ * Drop every `<url>` whose `<loc>` points at a route this runtime prunes.
+ *
+ * The alternative is asking every site to duplicate the flag decision in its own
+ * `sitemap({ filter })`, which is what the docs used to say and what the site this
+ * package was written for got subtly wrong: a substring test culled `/blog/about-x/`
+ * along with `/about/`. Deciding it here, from the same runtime that deletes the
+ * files, means the two answers cannot drift.
+ *
+ * String surgery rather than an XML parse, so the untouched entries come back
+ * byte-identical and the diff of a rebuild stays readable.
+ */
+declare function pruneSitemapXml(xml: string, runtime: ResolvedFeatureRuntime): string;
+/** Number of `<url>` entries left in a urlset. */
+declare function sitemapUrlCount(xml: string): number;
+/**
+ * Remove the `<sitemap>` entries of an index that point at files which no longer exist.
+ */
+declare function pruneSitemapIndexXml(xml: string, removedFiles: readonly string[]): string;
+interface SitemapPruneResult {
+  /** Sitemap files rewritten with fewer entries. */
+  rewritten: string[];
+  /** Sitemap files deleted because nothing was left in them. */
+  removed: string[];
+  /** Whether any sitemap file was found at all. */
+  found: boolean;
+}
+/**
+ * Walk `outDir` (Astro `dist/`) and take the pruned routes out of every sitemap.
+ *
+ * Runs in `astro:build:done`, which means this integration has to sit **after**
+ * `@astrojs/sitemap` in `integrations` — Astro runs the hook in array order, and a
+ * sitemap written after this pass would keep its dead URLs.
+ */
+declare function applySitemapPruneToDist(outDir: string, runtime: ResolvedFeatureRuntime): SitemapPruneResult;
+//#endregion
 //#region src/index.d.ts
 interface AstroFeatureFlagsOptions extends ResolveFeatureRuntimeOptions {
   css?: DevOutlineCssOptions;
   /** When false, keeps static build output untouched (no route pruning / HTML cull). */
   staticMinify?: boolean;
+  /**
+   * When false, leaves generated sitemaps alone. On by default: a pruned route that is
+   * still advertised in `sitemap-0.xml` is a 404 handed to every crawler that reads it.
+   *
+   * Needs this integration to sit **after** `@astrojs/sitemap` in `integrations`, because
+   * Astro runs `astro:build:done` in array order.
+   */
+  pruneSitemap?: boolean;
 }
 /** Prefer `prod` if present; else first non-`dev` key (sorted); else `"prod"`. */
 declare function primaryNonDevEnvironmentKey(flagsByEnvironment: Record<string, FeatureFlagMap>): string;
@@ -98,5 +171,5 @@ declare function getResolvedFeatures(options?: ResolveFeatureRuntimeOptions): Re
 declare function featureRouteIncluded(pathname: string, runtime: ResolvedFeatureRuntime): boolean;
 declare function astroFeatureFlags(options?: AstroFeatureFlagsOptions): any;
 //#endregion
-export { AstroFeatureFlagsOptions, type DevOutlineCssOptions, type DevOutlineHiddenStrategy, type ElementBadgeHorizontalAlign, type ElementBadgeLayoutOptions, type ElementBadgeVerticalAnchor, type FeatureFlagMap, type NormalizedElementBadgeLayout, applyProductionHtmlCullToDist, createFeatureFlagStyles, createProductionGateStyles, createVirtualModuleSource, cullProductionHtml, astroFeatureFlags as default, elementBadgePositionBlock, featureRouteIncluded, getResolvedFeatures, longestMatchingRoutePrefix, mergeFlagsWithProcessEnvOverrides, normalizeElementBadgeLayout, primaryNonDevEnvironmentKey, resolveFeatureFlagsByEnvironment, routePatternToPrefix };
+export { AstroFeatureFlagsOptions, DEV_LAYER, type DevOutlineCssOptions, type DevOutlineHiddenStrategy, type ElementBadgeHorizontalAlign, type ElementBadgeLayoutOptions, type ElementBadgeVerticalAnchor, type FeatureFlagMap, type NormalizedElementBadgeLayout, type SitemapPruneResult, applyProductionHtmlCullToDist, applySitemapPruneToDist, createFeatureFlagStyles, createProductionGateStyles, createVirtualModuleSource, cullProductionHtml, astroFeatureFlags as default, elementBadgePositionBlock, featureRouteIncluded, getResolvedFeatures, longestMatchingRoutePrefix, mergeFlagsWithProcessEnvOverrides, normalizeElementBadgeLayout, primaryNonDevEnvironmentKey, pruneSitemapIndexXml, pruneSitemapXml, resolveFeatureFlagsByEnvironment, routePatternToPrefix, sitemapUrlCount };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/badge-layout.ts","../src/dev-outline-css.ts","../src/production-html-cull.ts","../src/index.ts"],"mappings":";;KAAY;;KAGA;;UAGK;;;;;EAKf,8BAA8B;;;;;EAK9B;;;;;EAKA;;EAEA,6BAA6B;;KAGnB;EAEN;EACA,iBAAiB;EACjB;EACA,gBAAgB;;EAGhB;EACA;EACA;EACA,gBAAgB;;iBAQN,4BACd,OAAO,wCACN;;;;iBA+Ba,0BACd,QAAQ;;;KCrEE;UAEK,6BAA6B;EAC5C;;EAEA;;EAEA,sBAAsB;EACtB;EACA;;EAGA;;EAEA;EACA,oBAAoB;EAEpB,iBAAiB;;;;EAKjB;;;;;;;iBAsEc,wBACd,SAAS,wBACT,MAAM;;;;;iBAyTQ,2BACd,SAAS;;;;;;;;iBC9UK,mBACd,cACA,SAAS;;;;iBAqCK,8BACd,gBACA,SAAS;;;UCtEM,iCAAiC;EAChD,MAAM;;EAEN;;;iBAIc,4BACd,oBAAoB,eAAe;iBAoCrB,0BACd,SAAS,wBACT,MAAM,sBACN,qBAAoB,eAAe,iBACnC;iBA8Kc,oBACd,UAAS,+BACR;iBAIa,qBACd,kBACA,SAAS;iBAkBa,kBACtB,UAAS"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/badge-layout.ts","../src/dev-outline-css.ts","../src/production-html-cull.ts","../src/sitemap-prune.ts","../src/index.ts"],"mappings":";;KAAY;;KAGA;;UAGK;;;;;EAKf,8BAA8B;;;;;EAK9B;;;;;EAKA;;EAEA,6BAA6B;;KAGnB;EAEN;EACA,iBAAiB;EACjB;EACA,gBAAgB;;EAGhB;EACA;EACA;EACA,gBAAgB;;iBAQN,4BACd,OAAO,wCACN;;;;iBA+Ba,0BACd,QAAQ;;;;;;;;cChEG;KAED;UAEK,6BAA6B;EAC5C;;EAEA;;EAEA,sBAAsB;EACtB;EACA;;EAGA;;EAEA;EACA,oBAAoB;EAEpB,iBAAiB;;;;EAKjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA4Fc,wBACd,SAAS,wBACT,MAAM;;;;;iBAiUQ,2BACd,SAAS;;;;;;;;iBCnXK,mBACd,cACA,SAAS;;;;iBAqCK,8BACd,gBACA,SAAS;;;;;;;;;;;;;;;iBC3DK,gBACd,aACA,SAAS;;iBAgBK,gBAAgB;;;;iBAOhB,qBACd,aACA;UAWe;;EAEf;;EAEA;;EAEA;;;;;;;;;iBAUc,wBACd,gBACA,SAAS,yBACR;;;UC3Dc,iCAAiC;EAChD,MAAM;;EAEN;;;;;;;;EAQA;;;iBAIc,4BACd,oBAAoB,eAAe;iBAoCrB,0BACd,SAAS,wBACT,MAAM,sBACN,qBAAoB,eAAe,iBACnC;iBA8Kc,oBACd,UAAS,+BACR;iBAIa,qBACd,kBACA,SAAS;iBAkBa,kBACtB,UAAS"}

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { t as DEV_TOOLBAR_FLAG_ICON_SVG } from "./dev-toolbar-flag-icon-MQsIFekv.mjs";
 import { longestMatchingRoutePrefix, mergeFlagsWithProcessEnvOverrides, resolveFeatureFlagsByEnvironment, resolveFeatureRuntime, routePathsToPrune, routePatternToPrefix, shouldIncludeRoute, toEnumKey, toToken } from "./runtime.mjs";
 import { readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse } from "node-html-parser";
 //#region src/badge-layout.ts
@@ -101,8 +101,18 @@ function affHeadInlineRuntime(payload) {
 		return p.endsWith("/") ? p : `${p}/`;
 	};
 	try {
-		const { featureFlagStyles, routeFlags: RF, flagNameToToken: M } = payload;
+		const { featureFlagStyles, routeFlags: RF, flagNameToToken: M, devLayer: L } = payload;
+		const ensureLayerOrder = () => {
+			if (document.querySelector("style[data-astro-feature-flags-layer]")) return;
+			const head = document.head || document.documentElement;
+			const s = document.createElement("style");
+			s.setAttribute("data-astro-feature-flags-layer", "");
+			s.setAttribute("data-astro-transition-persist", "astro-feature-flags-layer");
+			s.textContent = `@layer ${L};`;
+			head.insertBefore(s, head.firstChild);
+		};
 		const ensureFeatureFlagStyles = () => {
+			ensureLayerOrder();
 			if (document.querySelector("style[data-astro-feature-flags]")) return;
 			const s = document.createElement("style");
 			s.setAttribute("data-astro-feature-flags", "");
@@ -403,6 +413,12 @@ function affDevBootstrapRuntime(payload) {
 }
 //#endregion
 //#region src/dev-outline-css.ts
+/**
+* Cascade layer for the declarations the app must be able to override without
+* writing `!important`. Named rather than anonymous so the order statement in
+* {@link affHeadInlineRuntime} can name it too.
+*/
+const DEV_LAYER = "aff-dev";
 const defaultDevOutlineCssOptions = {
 	outlineWidth: "2px",
 	outlineColor: "rgb(220 38 38)",
@@ -441,6 +457,28 @@ function featureColorVar(token, namespace) {
 * Dev-only styles: `data-ff="token"` (or space-separated tokens) gates outlines/badges.
 * `html[data-ff-route="<token>"]` (dev) adds a fixed top-right route badge (label only).
 * Toolbar toggles: `data-ff-enabled-*`, `data-ff-outline-*`, `data-ff-badge-*`, `--<namespace>-c-*`.
+*
+* The badge is an absolutely positioned `::before`, so its host has to be a
+* containing block, and the host also wants rounding for the outline to follow.
+* Both of those are the app's business, not ours: a flagged element that the app
+* positions itself, or rounds itself, must keep doing so. Marking a flagged
+* element must not move it.
+*
+* So `position` and `border-radius` are emitted inside `:where()` *and* inside
+* the `aff-dev` cascade layer. `:where()` alone is not enough: an unlayered rule
+* beats a layered one before specificity is ever consulted, so a zero-specificity
+* unlayered rule still overrides Tailwind's `.rounded-full` and `.absolute`,
+* which live in `@layer utilities`. Layering ours is what lets the app win.
+*
+* Layer priority follows the order layers are first declared, so the layer only
+* sorts below the app's own layers if `@layer aff-dev;` appears before them in
+* document order. The sheet opens with that statement for the case where it
+* lands first, and {@link affHeadInlineRuntime} also prepends a style element
+* carrying it as the first child of `<head>`, which is what actually guarantees
+* the order at runtime.
+*
+* Everything else here is dev chrome the app has no opinion about, and stays at
+* its natural specificity.
 */
 function createFeatureFlagStyles(runtime, css) {
 	const nsAttr = `data-${toToken(runtime.namespace) || "ff"}`;
@@ -474,11 +512,15 @@ html {
 html:not([data-ff-outline-${token}="off"]) {
   --aff-outline-c-${token}: var(${v}, ${col});
 }
+@layer ${DEV_LAYER} {
+  :where(${selOutline}) {
+    position: relative;
+    border-radius: ${opts.borderRadius};
+  }
+}
 ${selOutline} {
-  position: relative;
   outline: ${opts.outlineWidth} solid var(--aff-outline-c-${token});
   outline-offset: ${opts.outlineOffset};
-  border-radius: ${opts.borderRadius};
 }
 html:not([data-ff-badge-${token}="off"]) ${selIsSingleBadge}::before {
   box-sizing: border-box;
@@ -560,11 +602,15 @@ html[data-ff-enabled-${token}="off"] ${selIs} {
 `);
 	}
 	chunks.push(`
+@layer ${DEV_LAYER} {
+  :where([${nsAttr}*=" "]) {
+    position: relative;
+    border-radius: ${opts.borderRadius};
+  }
+}
 [${nsAttr}*=" "] {
-  position: relative;
   outline: none !important;
   outline-offset: 0 !important;
-  border-radius: ${opts.borderRadius};
 }
 html [${nsAttr}*=" "]::after {
   content: "";
@@ -732,7 +778,7 @@ html[data-ff-outline-${token}="off"] ${selIs}[${nsAttr}*=" "]::after {
 }
 `);
 	}
-	return "\n" + chunks.join("\n") + "\n";
+	return `\n@layer ${DEV_LAYER};\n` + chunks.join("\n") + "\n";
 }
 /**
 * CSS-only hiding for disabled flags. The Astro integration no longer injects this into
@@ -842,6 +888,134 @@ function applyProductionHtmlCullToDist(outDir, runtime) {
 	}
 }
 //#endregion
+//#region src/sitemap-prune.ts
+/**
+* `@astrojs/sitemap` names its output `sitemap-0.xml`, `sitemap-1.xml`, … alongside a
+* `sitemap-index.xml`. Other generators write a plain `sitemap.xml`. Match the family.
+*/
+const SITEMAP_FILE = /^sitemap[\w.-]*\.xml$/i;
+function walkSitemapFiles(dir) {
+	const out = [];
+	for (const ent of readdirSync(dir, { withFileTypes: true })) {
+		const p = join(dir, ent.name);
+		if (ent.isDirectory()) out.push(...walkSitemapFiles(p));
+		else if (ent.isFile() && SITEMAP_FILE.test(ent.name)) out.push(p);
+	}
+	return out;
+}
+/**
+* `<loc>` is XML, so the five predefined entities and numeric references are all
+* legal in it. `&amp;` is the one that actually turns up (a query string with two
+* parameters), but a path that came through an escaper wholesale can carry the
+* others, and an entity left undecoded turns into a pathname that matches no
+* route and is silently kept.
+*/
+function decodeXmlEntities(value) {
+	return value.replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(Number.parseInt(hex, 16))).replace(/&#(\d+);/g, (_, dec) => String.fromCodePoint(Number.parseInt(dec, 10))).replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, "\"").replace(/&apos;/g, "'").replace(/&amp;/g, "&");
+}
+function locPathname(entry) {
+	const loc = /<loc>\s*([\s\S]*?)\s*<\/loc>/i.exec(entry)?.[1];
+	if (!loc) return null;
+	const href = decodeXmlEntities(loc).trim();
+	try {
+		return new URL(href).pathname;
+	} catch {
+		return href.startsWith("/") ? href : null;
+	}
+}
+/**
+* Drop every `<url>` whose `<loc>` points at a route this runtime prunes.
+*
+* The alternative is asking every site to duplicate the flag decision in its own
+* `sitemap({ filter })`, which is what the docs used to say and what the site this
+* package was written for got subtly wrong: a substring test culled `/blog/about-x/`
+* along with `/about/`. Deciding it here, from the same runtime that deletes the
+* files, means the two answers cannot drift.
+*
+* String surgery rather than an XML parse, so the untouched entries come back
+* byte-identical and the diff of a rebuild stays readable.
+*/
+function pruneSitemapXml(xml, runtime) {
+	return xml.replace(/[ \t]*<url>[\s\S]*?<\/url>\s*/gi, (entry) => {
+		const pathname = locPathname(entry);
+		if (!pathname) return entry;
+		return shouldIncludeRoute({
+			pathname,
+			routeFlags: runtime.routeFlags,
+			flags: runtime.flags,
+			isDev: false
+		}) ? entry : "";
+	});
+}
+/** Number of `<url>` entries left in a urlset. */
+function sitemapUrlCount(xml) {
+	return (xml.match(/<url>/gi) ?? []).length;
+}
+/**
+* Remove the `<sitemap>` entries of an index that point at files which no longer exist.
+*/
+function pruneSitemapIndexXml(xml, removedFiles) {
+	if (!removedFiles.length) return xml;
+	const removed = new Set(removedFiles);
+	return xml.replace(/[ \t]*<sitemap>[\s\S]*?<\/sitemap>\s*/gi, (entry) => {
+		const pathname = locPathname(entry);
+		if (!pathname) return entry;
+		return removed.has(basename(pathname)) ? "" : entry;
+	});
+}
+/**
+* Walk `outDir` (Astro `dist/`) and take the pruned routes out of every sitemap.
+*
+* Runs in `astro:build:done`, which means this integration has to sit **after**
+* `@astrojs/sitemap` in `integrations` — Astro runs the hook in array order, and a
+* sitemap written after this pass would keep its dead URLs.
+*/
+function applySitemapPruneToDist(outDir, runtime) {
+	const result = {
+		rewritten: [],
+		removed: [],
+		found: false
+	};
+	let files;
+	try {
+		files = walkSitemapFiles(outDir);
+	} catch {
+		return result;
+	}
+	result.found = files.length > 0;
+	const indexes = [];
+	for (const file of files) {
+		const before = readFileSync(file, "utf8");
+		if (!/<urlset[\s>]/i.test(before)) {
+			if (/<sitemapindex[\s>]/i.test(before)) indexes.push(file);
+			continue;
+		}
+		const after = pruneSitemapXml(before, runtime);
+		if (after === before) continue;
+		if (sitemapUrlCount(after) === 0) {
+			rmSync(file, { force: true });
+			result.removed.push(file);
+		} else {
+			writeFileSync(file, after, "utf8");
+			result.rewritten.push(file);
+		}
+	}
+	const removedNames = result.removed.map((file) => basename(file));
+	for (const file of indexes) {
+		const before = readFileSync(file, "utf8");
+		const after = pruneSitemapIndexXml(before, removedNames);
+		if (after === before) continue;
+		if (!/<sitemap>/i.test(after)) {
+			rmSync(file, { force: true });
+			result.removed.push(file);
+		} else {
+			writeFileSync(file, after, "utf8");
+			result.rewritten.push(file);
+		}
+	}
+	return result;
+}
+//#endregion
 //#region src/dev-head-inject.ts
 /**
 * Single `injectScript('head-inline', …)` payload for `astro dev`: dev-only outline CSS,
@@ -854,7 +1028,8 @@ function buildAffDevHeadInline(args) {
 	return `${inlineInvoke(affHeadInlineRuntime, {
 		featureFlagStyles,
 		routeFlags: runtime.routeFlags,
-		flagNameToToken
+		flagNameToToken,
+		devLayer: DEV_LAYER
 	})}\n${affDevBootstrap}`;
 }
 //#endregion
@@ -1052,17 +1227,23 @@ function featureRouteIncluded(pathname, runtime) {
 	});
 }
 function astroFeatureFlags(options = {}) {
-	const { css, staticMinify = true, ...flagOpts } = options;
+	const { css, staticMinify = true, pruneSitemap = true, ...flagOpts } = options;
 	const opts = withDefaultEnvironments(flagOpts);
 	const mode = opts.mode ?? process.env.NODE_ENV ?? "development";
 	const runtime = resolveFeatureRuntime({
 		...opts,
 		mode
 	});
+	/**
+	* Set in `astro:config:setup`, read in `astro:build:done`, so that a sitemap this
+	* pass never saw can be reported as an ordering mistake rather than silently skipped.
+	*/
+	let sitemapIntegrationPresent = false;
 	return {
 		name: "astro-feature-flags",
 		hooks: {
-			"astro:config:setup": ({ updateConfig, addDevToolbarApp, command, injectScript }) => {
+			"astro:config:setup": ({ config, updateConfig, addDevToolbarApp, command, injectScript }) => {
+				sitemapIntegrationPresent = (config?.integrations ?? []).some((integration) => integration?.name === "@astrojs/sitemap");
 				const flagNames = Object.keys(runtime.flags);
 				const flagTokens = flagNames.map((name) => toToken(name));
 				const flagsByEnvironment = resolveFeatureFlagsByEnvironment(opts);
@@ -1094,7 +1275,7 @@ function astroFeatureFlags(options = {}) {
 					}
 				}] } });
 			},
-			"astro:build:done": ({ dir }) => {
+			"astro:build:done": ({ dir, logger }) => {
 				if (runtime.isDev || !staticMinify) return;
 				const outDir = fileURLToPath(dir);
 				const prunePaths = routePathsToPrune({
@@ -1106,11 +1287,13 @@ function astroFeatureFlags(options = {}) {
 					force: true
 				});
 				applyProductionHtmlCullToDist(outDir, runtime);
+				if (!pruneSitemap) return;
+				if (!applySitemapPruneToDist(outDir, runtime).found && sitemapIntegrationPresent && prunePaths.length) logger?.warn("@astrojs/sitemap is configured but no sitemap was on disk yet, so pruned routes may still be listed. Move astroFeatureFlags() after sitemap() in `integrations`.");
 			}
 		}
 	};
 }
 //#endregion
-export { applyProductionHtmlCullToDist, createFeatureFlagStyles, createProductionGateStyles, createVirtualModuleSource, cullProductionHtml, astroFeatureFlags as default, elementBadgePositionBlock, featureRouteIncluded, getResolvedFeatures, longestMatchingRoutePrefix, mergeFlagsWithProcessEnvOverrides, normalizeElementBadgeLayout, primaryNonDevEnvironmentKey, resolveFeatureFlagsByEnvironment, routePatternToPrefix };
+export { DEV_LAYER, applyProductionHtmlCullToDist, applySitemapPruneToDist, createFeatureFlagStyles, createProductionGateStyles, createVirtualModuleSource, cullProductionHtml, astroFeatureFlags as default, elementBadgePositionBlock, featureRouteIncluded, getResolvedFeatures, longestMatchingRoutePrefix, mergeFlagsWithProcessEnvOverrides, normalizeElementBadgeLayout, primaryNonDevEnvironmentKey, pruneSitemapIndexXml, pruneSitemapXml, resolveFeatureFlagsByEnvironment, routePatternToPrefix, sitemapUrlCount };
 
 //# sourceMappingURL=index.mjs.map