@warlock.js/sitemap 5.19.1 → 5.21.0

package/esm/sitemap-index-options.mjs

@@ -7,6 +7,7 @@ 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 shardPathPrefix = normalizeShardPathPrefix(options.shardPathPrefix);
 	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)}.`);
@@ -15,16 +16,24 @@ function normalizeSitemapIndexOptions(options) {
 		baseUrl,
 		filePrefix: options.filePrefix ?? "sitemap",
 		indexFileName: options.indexFileName ?? "sitemap_index.xml",
+		shardPathPrefix,
 		gzip: options.gzip ?? false,
 		maxUrlsPerFile,
 		maxBytesPerFile,
 		defaults: {
 			changefreq: options.changefreq,
 			priority: options.priority,
-			lastmod: options.lastmod
+			lastmod: options.lastmod,
+			onImageLimitExceeded: options.onImageLimitExceeded
 		}
 	};
 }
+function normalizeShardPathPrefix(value) {
+	if (value === void 0 || value === "" || value === "/") return "";
+	const prefix = value.replace(/^\//, "").replace(/\/$/, "");
+	if (prefix.length === 0 || prefix.split("/").some((segment) => !/^[A-Za-z0-9_-]+$/.test(segment))) throw new TypeError("shardPathPrefix must contain only safe URL path segments.");
+	return `${prefix}/`;
+}
 
 //#endregion
 export { normalizeSitemapIndexOptions };

package/esm/sitemap-index-options.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sitemap-index-options.mjs","names":[],"sources":["../../../../../../sitemap/src/sitemap-index-options.ts"],"sourcesContent":["import type { SitemapOptions } from \"./types\";\nimport { normalizeBaseUrl } from \"./url\";\nimport type { SitemapIndexOptions } from \"./sitemap-index-types\";\n\n/** The sitemaps.org limits. Never clamped to — a silently clamped option is a lie about what was written. */\nexport const PROTOCOL_MAX_URLS_PER_FILE = 50_000;\nexport const PROTOCOL_MAX_BYTES_PER_FILE = 50 * 1024 * 1024;\n\nexport type ResolvedSitemapIndexOptions = {\n  readonly baseUrl: string;\n  readonly filePrefix: string;\n  readonly indexFileName: string;\n  readonly gzip: boolean;\n  readonly maxUrlsPerFile: number;\n  readonly maxBytesPerFile: number;\n  readonly defaults: Pick<SitemapOptions, \"changefreq\" | \"priority\" | \"lastmod\">;\n};\n\n/** Validates and folds in defaults, once, at the constructor — the same discipline as `Sitemap`. */\nexport function normalizeSitemapIndexOptions(\n  options: SitemapIndexOptions,\n): ResolvedSitemapIndexOptions {\n  const baseUrl = normalizeBaseUrl(options?.baseUrl);\n\n  const maxUrlsPerFile = options.maxUrlsPerFile ?? PROTOCOL_MAX_URLS_PER_FILE;\n  const maxBytesPerFile = options.maxBytesPerFile ?? PROTOCOL_MAX_BYTES_PER_FILE;\n\n  if (\n    !Number.isInteger(maxUrlsPerFile) ||\n    maxUrlsPerFile < 1 ||\n    maxUrlsPerFile > PROTOCOL_MAX_URLS_PER_FILE\n  ) {\n    throw new RangeError(\n      `maxUrlsPerFile must be an integer between 1 and the sitemaps.org ceiling of ` +\n        `${PROTOCOL_MAX_URLS_PER_FILE}, got ${JSON.stringify(maxUrlsPerFile)}.`,\n    );\n  }\n\n  if (\n    !Number.isFinite(maxBytesPerFile) ||\n    maxBytesPerFile < 1 ||\n    maxBytesPerFile > PROTOCOL_MAX_BYTES_PER_FILE\n  ) {\n    throw new RangeError(\n      `maxBytesPerFile must be between 1 and the sitemaps.org ceiling of ` +\n        `${PROTOCOL_MAX_BYTES_PER_FILE} bytes, got ${JSON.stringify(maxBytesPerFile)}.`,\n    );\n  }\n\n  return {\n    baseUrl,\n    filePrefix: options.filePrefix ?? \"sitemap\",\n    indexFileName: options.indexFileName ?? \"sitemap_index.xml\",\n    gzip: options.gzip ?? false,\n    maxUrlsPerFile,\n    maxBytesPerFile,\n    defaults: {\n      changefreq: options.changefreq,\n      priority: options.priority,\n      lastmod: options.lastmod,\n    },\n  };\n}\n"],"mappings":";;;;AAKA,MAAa,6BAA6B;AAC1C,MAAa,8BAA8B,KAAK,OAAO;;AAavD,SAAgB,6BACd,SAC6B;CAC7B,MAAM,UAAU,iBAAiB,SAAS,OAAO;CAEjD,MAAM,iBAAiB,QAAQ;CAC/B,MAAM,kBAAkB,QAAQ;CAEhC,IACE,CAAC,OAAO,UAAU,cAAc,KAChC,iBAAiB,KACjB,sBAEA,MAAM,IAAI,WACR,+EACK,2BAA2B,QAAQ,KAAK,UAAU,cAAc,EAAE,EACzE;CAGF,IACE,CAAC,OAAO,SAAS,eAAe,KAChC,kBAAkB,KAClB,4BAEA,MAAM,IAAI,WACR,qEACK,4BAA4B,cAAc,KAAK,UAAU,eAAe,EAAE,EACjF;CAGF,OAAO;EACL;EACA,YAAY,QAAQ,cAAc;EAClC,eAAe,QAAQ,iBAAiB;EACxC,MAAM,QAAQ,QAAQ;EACtB;EACA;EACA,UAAU;GACR,YAAY,QAAQ;GACpB,UAAU,QAAQ;GAClB,SAAS,QAAQ;EACnB;CACF;AACF"}
+{"version":3,"file":"sitemap-index-options.mjs","names":[],"sources":["../../../../../../sitemap/src/sitemap-index-options.ts"],"sourcesContent":["import type { SitemapOptions } from \"./types\";\nimport { normalizeBaseUrl } from \"./url\";\nimport type { SitemapIndexOptions } from \"./sitemap-index-types\";\n\n/** The sitemaps.org limits. Never clamped to — a silently clamped option is a lie about what was written. */\nexport const PROTOCOL_MAX_URLS_PER_FILE = 50_000;\nexport const PROTOCOL_MAX_BYTES_PER_FILE = 50 * 1024 * 1024;\n\nexport type ResolvedSitemapIndexOptions = {\n  readonly baseUrl: string;\n  readonly filePrefix: string;\n  readonly indexFileName: string;\n  readonly shardPathPrefix: string;\n  readonly gzip: boolean;\n  readonly maxUrlsPerFile: number;\n  readonly maxBytesPerFile: number;\n  readonly defaults: Pick<\n    SitemapOptions,\n    \"changefreq\" | \"priority\" | \"lastmod\" | \"onImageLimitExceeded\"\n  >;\n};\n\n/** Validates and folds in defaults, once, at the constructor — the same discipline as `Sitemap`. */\nexport function normalizeSitemapIndexOptions(\n  options: SitemapIndexOptions,\n): ResolvedSitemapIndexOptions {\n  const baseUrl = normalizeBaseUrl(options?.baseUrl);\n  const shardPathPrefix = normalizeShardPathPrefix(options.shardPathPrefix);\n\n  const maxUrlsPerFile = options.maxUrlsPerFile ?? PROTOCOL_MAX_URLS_PER_FILE;\n  const maxBytesPerFile = options.maxBytesPerFile ?? PROTOCOL_MAX_BYTES_PER_FILE;\n\n  if (\n    !Number.isInteger(maxUrlsPerFile) ||\n    maxUrlsPerFile < 1 ||\n    maxUrlsPerFile > PROTOCOL_MAX_URLS_PER_FILE\n  ) {\n    throw new RangeError(\n      `maxUrlsPerFile must be an integer between 1 and the sitemaps.org ceiling of ` +\n        `${PROTOCOL_MAX_URLS_PER_FILE}, got ${JSON.stringify(maxUrlsPerFile)}.`,\n    );\n  }\n\n  if (\n    !Number.isFinite(maxBytesPerFile) ||\n    maxBytesPerFile < 1 ||\n    maxBytesPerFile > PROTOCOL_MAX_BYTES_PER_FILE\n  ) {\n    throw new RangeError(\n      `maxBytesPerFile must be between 1 and the sitemaps.org ceiling of ` +\n        `${PROTOCOL_MAX_BYTES_PER_FILE} bytes, got ${JSON.stringify(maxBytesPerFile)}.`,\n    );\n  }\n\n  return {\n    baseUrl,\n    filePrefix: options.filePrefix ?? \"sitemap\",\n    indexFileName: options.indexFileName ?? \"sitemap_index.xml\",\n    shardPathPrefix,\n    gzip: options.gzip ?? false,\n    maxUrlsPerFile,\n    maxBytesPerFile,\n    defaults: {\n      changefreq: options.changefreq,\n      priority: options.priority,\n      lastmod: options.lastmod,\n      onImageLimitExceeded: options.onImageLimitExceeded,\n    },\n  };\n}\n\nfunction normalizeShardPathPrefix(value: string | undefined): string {\n  if (value === undefined || value === \"\" || value === \"/\") return \"\";\n\n  const prefix = value.replace(/^\\//, \"\").replace(/\\/$/, \"\");\n  if (\n    prefix.length === 0 ||\n    prefix.split(\"/\").some((segment) => !/^[A-Za-z0-9_-]+$/.test(segment))\n  ) {\n    throw new TypeError(\"shardPathPrefix must contain only safe URL path segments.\");\n  }\n\n  return `${prefix}/`;\n}\n"],"mappings":";;;;AAKA,MAAa,6BAA6B;AAC1C,MAAa,8BAA8B,KAAK,OAAO;;AAiBvD,SAAgB,6BACd,SAC6B;CAC7B,MAAM,UAAU,iBAAiB,SAAS,OAAO;CACjD,MAAM,kBAAkB,yBAAyB,QAAQ,eAAe;CAExE,MAAM,iBAAiB,QAAQ;CAC/B,MAAM,kBAAkB,QAAQ;CAEhC,IACE,CAAC,OAAO,UAAU,cAAc,KAChC,iBAAiB,KACjB,sBAEA,MAAM,IAAI,WACR,+EACK,2BAA2B,QAAQ,KAAK,UAAU,cAAc,EAAE,EACzE;CAGF,IACE,CAAC,OAAO,SAAS,eAAe,KAChC,kBAAkB,KAClB,4BAEA,MAAM,IAAI,WACR,qEACK,4BAA4B,cAAc,KAAK,UAAU,eAAe,EAAE,EACjF;CAGF,OAAO;EACL;EACA,YAAY,QAAQ,cAAc;EAClC,eAAe,QAAQ,iBAAiB;EACxC;EACA,MAAM,QAAQ,QAAQ;EACtB;EACA;EACA,UAAU;GACR,YAAY,QAAQ;GACpB,UAAU,QAAQ;GAClB,SAAS,QAAQ;GACjB,sBAAsB,QAAQ;EAChC;CACF;AACF;AAEA,SAAS,yBAAyB,OAAmC;CACnE,IAAI,UAAU,UAAa,UAAU,MAAM,UAAU,KAAK,OAAO;CAEjE,MAAM,SAAS,MAAM,QAAQ,OAAO,EAAE,CAAC,CAAC,QAAQ,OAAO,EAAE;CACzD,IACE,OAAO,WAAW,KAClB,OAAO,MAAM,GAAG,CAAC,CAAC,MAAM,YAAY,CAAC,mBAAmB,KAAK,OAAO,CAAC,GAErE,MAAM,IAAI,UAAU,2DAA2D;CAGjF,OAAO,GAAG,OAAO;AACnB"}

package/esm/sitemap-index-types.d.mts

@@ -1,4 +1,4 @@
-import { ChangeFreq, DuplicateReport, RouteSummary, SitemapEntry } from "./types.mjs";
+import { ChangeFreq, DuplicateReport, RouteSummary, SitemapEntry, SitemapImageLimitExceeded } from "./types.mjs";
 
 //#region ../sitemap/src/sitemap-index-types.d.ts
 /** What a source factory produces: one walk over a group's entries. */
@@ -12,13 +12,15 @@ type SitemapSourceFactory = () => SitemapSource | Promise<SitemapSource>;
 type SitemapIndexOptions = {
   /** Absolute origin, validated exactly as `Sitemap` validates it. */readonly baseUrl: string; /** Shard file name prefix. Default `sitemap`, giving `sitemap-0001.xml`. */
   readonly filePrefix?: string; /** Index file name. Default `sitemap_index.xml`. */
-  readonly indexFileName?: string; /** Write `.xml.gz` beside each shard and point the index at it. Default false. */
+  readonly indexFileName?: string; /** URL directory for shard links, independent of their on-disk directory. */
+  readonly shardPathPrefix?: string; /** Write `.xml.gz` beside each shard and point the index at it. Default false. */
   readonly gzip?: boolean; /** Hard ceiling per shard. Default 50_000; never accepted above the protocol ceiling. */
   readonly maxUrlsPerFile?: number; /** Hard ceiling per shard in bytes, uncompressed. Default 50 * 1024 * 1024. */
   readonly maxBytesPerFile?: number;
   readonly changefreq?: ChangeFreq;
   readonly priority?: number;
-  readonly lastmod?: string | Date;
+  readonly lastmod?: string | Date; /** Called once per route when an entry exceeds Google's 1,000-image limit. */
+  readonly onImageLimitExceeded?: (event: SitemapImageLimitExceeded) => void;
 };
 type SitemapSetResult = {
   readonly indexPath: string;

package/esm/sitemap-index-xml.mjs

@@ -8,9 +8,9 @@ import { escapeXml } from "./xml.mjs";
 * 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) {
+function buildSitemapIndexXml(files, baseUrl, shardPathPrefix = "") {
 	const body = files.filter((file) => file.urls > 0).map((file) => {
-		return `  <sitemap>\n    <loc>${escapeXml(joinOrigin(baseUrl, file.fileName))}</loc>\n  </sitemap>`;
+		return `  <sitemap>\n    <loc>${escapeXml(joinOrigin(baseUrl, `${shardPathPrefix}${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`;
 }

package/esm/sitemap-index-xml.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sitemap-index-xml.mjs","names":[],"sources":["../../../../../../sitemap/src/sitemap-index-xml.ts"],"sourcesContent":["import { escapeXml } from \"./xml\";\nimport { joinOrigin } from \"./url\";\nimport type { ShardFile } from \"./sitemap-shard-writer\";\n\n/**\n * Serialises the flat master `sitemapindex` document: every shard of every\n * group, directly, in the order the groups and shards were produced — no\n * nested per-group indexes, and never a zero-url row (that is a diagnostic\n * for `files`, not something a crawler should be told to fetch).\n */\nexport function buildSitemapIndexXml(files: readonly ShardFile[], baseUrl: string): string {\n  const body = files\n    .filter((file) => file.urls > 0)\n    .map((file) => {\n      const loc = escapeXml(joinOrigin(baseUrl, file.fileName));\n\n      return `  <sitemap>\\n    <loc>${loc}</loc>\\n  </sitemap>`;\n    })\n    .join(\"\\n\");\n\n  return (\n    `<?xml version=\"1.0\" encoding=\"UTF-8\"?>\\n` +\n    `<sitemapindex xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\\n` +\n    (body.length > 0 ? `${body}\\n` : \"\") +\n    `</sitemapindex>\\n`\n  );\n}\n"],"mappings":";;;;;;;;;;AAUA,SAAgB,qBAAqB,OAA6B,SAAyB;CACzF,MAAM,OAAO,MACV,QAAQ,SAAS,KAAK,OAAO,CAAC,CAAC,CAC/B,KAAK,SAAS;EAGb,OAAO,yBAFK,UAAU,WAAW,SAAS,KAAK,QAAQ,CAErB,EAAE;CACtC,CAAC,CAAC,CACD,KAAK,IAAI;CAEZ,OACE,wHAEC,KAAK,SAAS,IAAI,GAAG,KAAK,MAAM,MACjC;AAEJ"}
+{"version":3,"file":"sitemap-index-xml.mjs","names":[],"sources":["../../../../../../sitemap/src/sitemap-index-xml.ts"],"sourcesContent":["import { escapeXml } from \"./xml\";\nimport { joinOrigin } from \"./url\";\nimport type { ShardFile } from \"./sitemap-shard-writer\";\n\n/**\n * Serialises the flat master `sitemapindex` document: every shard of every\n * group, directly, in the order the groups and shards were produced — no\n * nested per-group indexes, and never a zero-url row (that is a diagnostic\n * for `files`, not something a crawler should be told to fetch).\n */\nexport function buildSitemapIndexXml(\n  files: readonly ShardFile[],\n  baseUrl: string,\n  shardPathPrefix = \"\",\n): string {\n  const body = files\n    .filter((file) => file.urls > 0)\n    .map((file) => {\n      const loc = escapeXml(joinOrigin(baseUrl, `${shardPathPrefix}${file.fileName}`));\n\n      return `  <sitemap>\\n    <loc>${loc}</loc>\\n  </sitemap>`;\n    })\n    .join(\"\\n\");\n\n  return (\n    `<?xml version=\"1.0\" encoding=\"UTF-8\"?>\\n` +\n    `<sitemapindex xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">\\n` +\n    (body.length > 0 ? `${body}\\n` : \"\") +\n    `</sitemapindex>\\n`\n  );\n}\n"],"mappings":";;;;;;;;;;AAUA,SAAgB,qBACd,OACA,SACA,kBAAkB,IACV;CACR,MAAM,OAAO,MACV,QAAQ,SAAS,KAAK,OAAO,CAAC,CAAC,CAC/B,KAAK,SAAS;EAGb,OAAO,yBAFK,UAAU,WAAW,SAAS,GAAG,kBAAkB,KAAK,UAAU,CAE5C,EAAE;CACtC,CAAC,CAAC,CACD,KAAK,IAAI;CAEZ,OACE,wHAEC,KAAK,SAAS,IAAI,GAAG,KAAK,MAAM,MACjC;AAEJ"}

package/esm/sitemap-index.d.mts

@@ -15,6 +15,7 @@ declare class SitemapIndex {
   private readonly namedGroups;
   /** Canonical (lowercased) keys already registered, so a case collision is caught at `addSource()`. */
   private readonly registeredKeys;
+  private readonly warnedImageRoutes;
   constructor(options: SitemapIndexOptions);
   addSource(source: SitemapSourceFactory): this;
   addSource(key: string, source: SitemapSourceFactory): this;
@@ -25,6 +26,7 @@ declare class SitemapIndex {
    * named groups key-then-ordinal.
    */
   saveTo(outDir: string): Promise<SitemapSetResult>;
+  private reportImageLimit;
 }
 //#endregion
 export { SitemapIndex };

package/esm/sitemap-index.mjs

@@ -24,6 +24,7 @@ var SitemapIndex = class {
 	namedGroups = [];
 	/** Canonical (lowercased) keys already registered, so a case collision is caught at `addSource()`. */
 	registeredKeys = /* @__PURE__ */ new Set();
+	warnedImageRoutes = /* @__PURE__ */ new Set();
 	constructor(options) {
 		this.options = normalizeSitemapIndexOptions(options);
 	}
@@ -63,13 +64,16 @@ var SitemapIndex = class {
 					gzip: this.options.gzip,
 					maxUrlsPerFile: this.options.maxUrlsPerFile,
 					maxBytesPerFile: this.options.maxBytesPerFile,
-					defaults: this.options.defaults,
+					defaults: {
+						...this.options.defaults,
+						onImageLimitExceeded: (event) => this.reportImageLimit(event)
+					},
 					duplicates,
 					routes
 				});
 				shardFiles.push(...files);
 			}
-			const indexXml = buildSitemapIndexXml(shardFiles, this.options.baseUrl);
+			const indexXml = buildSitemapIndexXml(shardFiles, this.options.baseUrl, this.options.shardPathPrefix);
 			await writeFile(join(tempDir, this.options.indexFileName), indexXml, "utf8");
 			return [...shardFiles.filter((file) => file.urls > 0).map((file) => file.fileName), this.options.indexFileName];
 		};
@@ -89,6 +93,13 @@ var SitemapIndex = class {
 			routes: routes.summary()
 		};
 	}
+	reportImageLimit(event) {
+		const key = event.route ?? "unattributed";
+		if (this.warnedImageRoutes.has(key)) return;
+		this.warnedImageRoutes.add(key);
+		if (this.options.defaults.onImageLimitExceeded) this.options.defaults.onImageLimitExceeded(event);
+		else console.warn(`[warlock:sitemap] ${key} exceeded the 1,000-image limit; dropped ${event.dropped} image(s).`);
+	}
 };
 
 //#endregion

package/esm/sitemap-index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sitemap-index.mjs","names":[],"sources":["../../../../../../sitemap/src/sitemap-index.ts"],"sourcesContent":["import { join } from \"node:path\";\nimport { writeFile } from \"node:fs/promises\";\nimport { DuplicateSourceKeyError } from \"./errors\";\nimport {\n  normalizeSitemapIndexOptions,\n  type ResolvedSitemapIndexOptions,\n} from \"./sitemap-index-options\";\nimport { canonicalizeSourceKey } from \"./shard-name\";\nimport { publishAtomically } from \"./atomic-publish\";\nimport { writeShardGroup, type ShardFile, type ShardGroup } from \"./sitemap-shard-writer\";\nimport { buildSitemapIndexXml } from \"./sitemap-index-xml\";\nimport { DuplicatePathTracker } from \"./duplicate-path-tracker\";\nimport { RouteCounter } from \"./route-counter\";\nimport type {\n  SitemapFileResult,\n  SitemapIndexOptions,\n  SitemapSetResult,\n  SitemapSourceFactory,\n} from \"./sitemap-index-types\";\n\n/**\n * The streaming path for 300–500K URLs: shards, one flat master index, gzip,\n * and an atomic publish. It is a SECOND mode, not a bigger `Sitemap` — it\n * retains only the current shard's buffer and the set of paths it has seen.\n * There is no `entries()`, `toXML()` or `size`; anyone who can afford those\n * is in `Sitemap` and should be there instead.\n */\nexport class SitemapIndex {\n  private readonly options: ResolvedSitemapIndexOptions;\n\n  /** Every unnamed `addSource(factory)` call merges into this one group, sharing one shard counter. */\n  private readonly unnamedFactories: SitemapSourceFactory[] = [];\n\n  private readonly namedGroups: ShardGroup[] = [];\n\n  /** Canonical (lowercased) keys already registered, so a case collision is caught at `addSource()`. */\n  private readonly registeredKeys = new Set<string>();\n\n  public constructor(options: SitemapIndexOptions) {\n    this.options = normalizeSitemapIndexOptions(options);\n  }\n\n  public addSource(source: SitemapSourceFactory): this;\n  public addSource(key: string, source: SitemapSourceFactory): this;\n  public addSource(\n    keyOrSource: string | SitemapSourceFactory,\n    maybeSource?: SitemapSourceFactory,\n  ): this {\n    if (typeof keyOrSource === \"string\") {\n      const canonicalKey = canonicalizeSourceKey(keyOrSource);\n\n      if (this.registeredKeys.has(canonicalKey)) {\n        throw new DuplicateSourceKeyError(keyOrSource);\n      }\n\n      this.registeredKeys.add(canonicalKey);\n      this.namedGroups.push({ key: keyOrSource, factories: [maybeSource as SitemapSourceFactory] });\n    } else {\n      this.unnamedFactories.push(keyOrSource);\n    }\n\n    return this;\n  }\n\n  /**\n   * Walks every group one at a time — never all at once — into a sibling\n   * temp directory, then publishes the whole set atomically. `files` is\n   * reported in registration order: the unnamed group first (if any), then\n   * named groups key-then-ordinal.\n   */\n  public async saveTo(outDir: string): Promise<SitemapSetResult> {\n    const groups: ShardGroup[] = [\n      ...(this.unnamedFactories.length > 0\n        ? [{ key: undefined, factories: this.unnamedFactories }]\n        : []),\n      ...this.namedGroups,\n    ];\n\n    const duplicates = new DuplicatePathTracker();\n    const routes = new RouteCounter();\n    let shardFiles: ShardFile[] = [];\n\n    const write = async (tempDir: string): Promise<readonly string[]> => {\n      shardFiles = [];\n\n      for (const group of groups) {\n        const files = await writeShardGroup(group, {\n          tempDir,\n          baseUrl: this.options.baseUrl,\n          filePrefix: this.options.filePrefix,\n          gzip: this.options.gzip,\n          maxUrlsPerFile: this.options.maxUrlsPerFile,\n          maxBytesPerFile: this.options.maxBytesPerFile,\n          defaults: this.options.defaults,\n          duplicates,\n          routes,\n        });\n\n        shardFiles.push(...files);\n      }\n\n      const indexXml = buildSitemapIndexXml(shardFiles, this.options.baseUrl);\n\n      await writeFile(join(tempDir, this.options.indexFileName), indexXml, \"utf8\");\n\n      const writtenShardNames = shardFiles\n        .filter((file) => file.urls > 0)\n        .map((file) => file.fileName);\n\n      return [...writtenShardNames, this.options.indexFileName];\n    };\n\n    await publishAtomically(outDir, write);\n\n    const files: SitemapFileResult[] = shardFiles.map((file) => ({\n      path: join(outDir, file.fileName),\n      ...(file.key !== undefined ? { key: file.key } : {}),\n      urls: file.urls,\n      bytes: file.bytes,\n      gzipped: file.gzipped,\n    }));\n\n    return {\n      indexPath: join(outDir, this.options.indexFileName),\n      files,\n      totalUrls: files.reduce((total, file) => total + file.urls, 0),\n      duplicates: duplicates.report(),\n      routes: routes.summary(),\n    };\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA2BA,IAAa,eAAb,MAA0B;CACxB,AAAiB;;CAGjB,AAAiB,mBAA2C,CAAC;CAE7D,AAAiB,cAA4B,CAAC;;CAG9C,AAAiB,iCAAiB,IAAI,IAAY;CAElD,AAAO,YAAY,SAA8B;EAC/C,KAAK,UAAU,6BAA6B,OAAO;CACrD;CAIA,AAAO,UACL,aACA,aACM;EACN,IAAI,OAAO,gBAAgB,UAAU;GACnC,MAAM,eAAe,sBAAsB,WAAW;GAEtD,IAAI,KAAK,eAAe,IAAI,YAAY,GACtC,MAAM,IAAI,wBAAwB,WAAW;GAG/C,KAAK,eAAe,IAAI,YAAY;GACpC,KAAK,YAAY,KAAK;IAAE,KAAK;IAAa,WAAW,CAAC,WAAmC;GAAE,CAAC;EAC9F,OACE,KAAK,iBAAiB,KAAK,WAAW;EAGxC,OAAO;CACT;;;;;;;CAQA,MAAa,OAAO,QAA2C;EAC7D,MAAM,SAAuB,CAC3B,GAAI,KAAK,iBAAiB,SAAS,IAC/B,CAAC;GAAE,KAAK;GAAW,WAAW,KAAK;EAAiB,CAAC,IACrD,CAAC,GACL,GAAG,KAAK,WACV;EAEA,MAAM,aAAa,IAAI,qBAAqB;EAC5C,MAAM,SAAS,IAAI,aAAa;EAChC,IAAI,aAA0B,CAAC;EAE/B,MAAM,QAAQ,OAAO,YAAgD;GACnE,aAAa,CAAC;GAEd,KAAK,MAAM,SAAS,QAAQ;IAC1B,MAAM,QAAQ,MAAM,gBAAgB,OAAO;KACzC;KACA,SAAS,KAAK,QAAQ;KACtB,YAAY,KAAK,QAAQ;KACzB,MAAM,KAAK,QAAQ;KACnB,gBAAgB,KAAK,QAAQ;KAC7B,iBAAiB,KAAK,QAAQ;KAC9B,UAAU,KAAK,QAAQ;KACvB;KACA;IACF,CAAC;IAED,WAAW,KAAK,GAAG,KAAK;GAC1B;GAEA,MAAM,WAAW,qBAAqB,YAAY,KAAK,QAAQ,OAAO;GAEtE,MAAM,UAAU,KAAK,SAAS,KAAK,QAAQ,aAAa,GAAG,UAAU,MAAM;GAM3E,OAAO,CAAC,GAJkB,WACvB,QAAQ,SAAS,KAAK,OAAO,CAAC,CAAC,CAC/B,KAAK,SAAS,KAAK,QAEK,GAAG,KAAK,QAAQ,aAAa;EAC1D;EAEA,MAAM,kBAAkB,QAAQ,KAAK;EAErC,MAAM,QAA6B,WAAW,KAAK,UAAU;GAC3D,MAAM,KAAK,QAAQ,KAAK,QAAQ;GAChC,GAAI,KAAK,QAAQ,SAAY,EAAE,KAAK,KAAK,IAAI,IAAI,CAAC;GAClD,MAAM,KAAK;GACX,OAAO,KAAK;GACZ,SAAS,KAAK;EAChB,EAAE;EAEF,OAAO;GACL,WAAW,KAAK,QAAQ,KAAK,QAAQ,aAAa;GAClD;GACA,WAAW,MAAM,QAAQ,OAAO,SAAS,QAAQ,KAAK,MAAM,CAAC;GAC7D,YAAY,WAAW,OAAO;GAC9B,QAAQ,OAAO,QAAQ;EACzB;CACF;AACF"}
+{"version":3,"file":"sitemap-index.mjs","names":[],"sources":["../../../../../../sitemap/src/sitemap-index.ts"],"sourcesContent":["import { join } from \"node:path\";\nimport { writeFile } from \"node:fs/promises\";\nimport { DuplicateSourceKeyError } from \"./errors\";\nimport {\n  normalizeSitemapIndexOptions,\n  type ResolvedSitemapIndexOptions,\n} from \"./sitemap-index-options\";\nimport { canonicalizeSourceKey } from \"./shard-name\";\nimport { publishAtomically } from \"./atomic-publish\";\nimport { writeShardGroup, type ShardFile, type ShardGroup } from \"./sitemap-shard-writer\";\nimport { buildSitemapIndexXml } from \"./sitemap-index-xml\";\nimport { DuplicatePathTracker } from \"./duplicate-path-tracker\";\nimport { RouteCounter } from \"./route-counter\";\nimport type {\n  SitemapFileResult,\n  SitemapIndexOptions,\n  SitemapSetResult,\n  SitemapSourceFactory,\n} from \"./sitemap-index-types\";\n\n/**\n * The streaming path for 300–500K URLs: shards, one flat master index, gzip,\n * and an atomic publish. It is a SECOND mode, not a bigger `Sitemap` — it\n * retains only the current shard's buffer and the set of paths it has seen.\n * There is no `entries()`, `toXML()` or `size`; anyone who can afford those\n * is in `Sitemap` and should be there instead.\n */\nexport class SitemapIndex {\n  private readonly options: ResolvedSitemapIndexOptions;\n\n  /** Every unnamed `addSource(factory)` call merges into this one group, sharing one shard counter. */\n  private readonly unnamedFactories: SitemapSourceFactory[] = [];\n\n  private readonly namedGroups: ShardGroup[] = [];\n\n  /** Canonical (lowercased) keys already registered, so a case collision is caught at `addSource()`. */\n  private readonly registeredKeys = new Set<string>();\n\n  private readonly warnedImageRoutes = new Set<string>();\n\n  public constructor(options: SitemapIndexOptions) {\n    this.options = normalizeSitemapIndexOptions(options);\n  }\n\n  public addSource(source: SitemapSourceFactory): this;\n  public addSource(key: string, source: SitemapSourceFactory): this;\n  public addSource(\n    keyOrSource: string | SitemapSourceFactory,\n    maybeSource?: SitemapSourceFactory,\n  ): this {\n    if (typeof keyOrSource === \"string\") {\n      const canonicalKey = canonicalizeSourceKey(keyOrSource);\n\n      if (this.registeredKeys.has(canonicalKey)) {\n        throw new DuplicateSourceKeyError(keyOrSource);\n      }\n\n      this.registeredKeys.add(canonicalKey);\n      this.namedGroups.push({ key: keyOrSource, factories: [maybeSource as SitemapSourceFactory] });\n    } else {\n      this.unnamedFactories.push(keyOrSource);\n    }\n\n    return this;\n  }\n\n  /**\n   * Walks every group one at a time — never all at once — into a sibling\n   * temp directory, then publishes the whole set atomically. `files` is\n   * reported in registration order: the unnamed group first (if any), then\n   * named groups key-then-ordinal.\n   */\n  public async saveTo(outDir: string): Promise<SitemapSetResult> {\n    const groups: ShardGroup[] = [\n      ...(this.unnamedFactories.length > 0\n        ? [{ key: undefined, factories: this.unnamedFactories }]\n        : []),\n      ...this.namedGroups,\n    ];\n\n    const duplicates = new DuplicatePathTracker();\n    const routes = new RouteCounter();\n    let shardFiles: ShardFile[] = [];\n\n    const write = async (tempDir: string): Promise<readonly string[]> => {\n      shardFiles = [];\n\n      for (const group of groups) {\n        const files = await writeShardGroup(group, {\n          tempDir,\n          baseUrl: this.options.baseUrl,\n          filePrefix: this.options.filePrefix,\n          gzip: this.options.gzip,\n          maxUrlsPerFile: this.options.maxUrlsPerFile,\n          maxBytesPerFile: this.options.maxBytesPerFile,\n          defaults: {\n            ...this.options.defaults,\n            onImageLimitExceeded: (event) => this.reportImageLimit(event),\n          },\n          duplicates,\n          routes,\n        });\n\n        shardFiles.push(...files);\n      }\n\n      const indexXml = buildSitemapIndexXml(\n        shardFiles,\n        this.options.baseUrl,\n        this.options.shardPathPrefix,\n      );\n\n      await writeFile(join(tempDir, this.options.indexFileName), indexXml, \"utf8\");\n\n      const writtenShardNames = shardFiles\n        .filter((file) => file.urls > 0)\n        .map((file) => file.fileName);\n\n      return [...writtenShardNames, this.options.indexFileName];\n    };\n\n    await publishAtomically(outDir, write);\n\n    const files: SitemapFileResult[] = shardFiles.map((file) => ({\n      path: join(outDir, file.fileName),\n      ...(file.key !== undefined ? { key: file.key } : {}),\n      urls: file.urls,\n      bytes: file.bytes,\n      gzipped: file.gzipped,\n    }));\n\n    return {\n      indexPath: join(outDir, this.options.indexFileName),\n      files,\n      totalUrls: files.reduce((total, file) => total + file.urls, 0),\n      duplicates: duplicates.report(),\n      routes: routes.summary(),\n    };\n  }\n\n  private reportImageLimit(event: { readonly route?: string; readonly dropped: number }): void {\n    const key = event.route ?? \"unattributed\";\n    if (this.warnedImageRoutes.has(key)) return;\n\n    this.warnedImageRoutes.add(key);\n    if (this.options.defaults.onImageLimitExceeded)\n      this.options.defaults.onImageLimitExceeded(event);\n    else\n      console.warn(\n        `[warlock:sitemap] ${key} exceeded the 1,000-image limit; dropped ${event.dropped} image(s).`,\n      );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA2BA,IAAa,eAAb,MAA0B;CACxB,AAAiB;;CAGjB,AAAiB,mBAA2C,CAAC;CAE7D,AAAiB,cAA4B,CAAC;;CAG9C,AAAiB,iCAAiB,IAAI,IAAY;CAElD,AAAiB,oCAAoB,IAAI,IAAY;CAErD,AAAO,YAAY,SAA8B;EAC/C,KAAK,UAAU,6BAA6B,OAAO;CACrD;CAIA,AAAO,UACL,aACA,aACM;EACN,IAAI,OAAO,gBAAgB,UAAU;GACnC,MAAM,eAAe,sBAAsB,WAAW;GAEtD,IAAI,KAAK,eAAe,IAAI,YAAY,GACtC,MAAM,IAAI,wBAAwB,WAAW;GAG/C,KAAK,eAAe,IAAI,YAAY;GACpC,KAAK,YAAY,KAAK;IAAE,KAAK;IAAa,WAAW,CAAC,WAAmC;GAAE,CAAC;EAC9F,OACE,KAAK,iBAAiB,KAAK,WAAW;EAGxC,OAAO;CACT;;;;;;;CAQA,MAAa,OAAO,QAA2C;EAC7D,MAAM,SAAuB,CAC3B,GAAI,KAAK,iBAAiB,SAAS,IAC/B,CAAC;GAAE,KAAK;GAAW,WAAW,KAAK;EAAiB,CAAC,IACrD,CAAC,GACL,GAAG,KAAK,WACV;EAEA,MAAM,aAAa,IAAI,qBAAqB;EAC5C,MAAM,SAAS,IAAI,aAAa;EAChC,IAAI,aAA0B,CAAC;EAE/B,MAAM,QAAQ,OAAO,YAAgD;GACnE,aAAa,CAAC;GAEd,KAAK,MAAM,SAAS,QAAQ;IAC1B,MAAM,QAAQ,MAAM,gBAAgB,OAAO;KACzC;KACA,SAAS,KAAK,QAAQ;KACtB,YAAY,KAAK,QAAQ;KACzB,MAAM,KAAK,QAAQ;KACnB,gBAAgB,KAAK,QAAQ;KAC7B,iBAAiB,KAAK,QAAQ;KAC9B,UAAU;MACR,GAAG,KAAK,QAAQ;MAChB,uBAAuB,UAAU,KAAK,iBAAiB,KAAK;KAC9D;KACA;KACA;IACF,CAAC;IAED,WAAW,KAAK,GAAG,KAAK;GAC1B;GAEA,MAAM,WAAW,qBACf,YACA,KAAK,QAAQ,SACb,KAAK,QAAQ,eACf;GAEA,MAAM,UAAU,KAAK,SAAS,KAAK,QAAQ,aAAa,GAAG,UAAU,MAAM;GAM3E,OAAO,CAAC,GAJkB,WACvB,QAAQ,SAAS,KAAK,OAAO,CAAC,CAAC,CAC/B,KAAK,SAAS,KAAK,QAEK,GAAG,KAAK,QAAQ,aAAa;EAC1D;EAEA,MAAM,kBAAkB,QAAQ,KAAK;EAErC,MAAM,QAA6B,WAAW,KAAK,UAAU;GAC3D,MAAM,KAAK,QAAQ,KAAK,QAAQ;GAChC,GAAI,KAAK,QAAQ,SAAY,EAAE,KAAK,KAAK,IAAI,IAAI,CAAC;GAClD,MAAM,KAAK;GACX,OAAO,KAAK;GACZ,SAAS,KAAK;EAChB,EAAE;EAEF,OAAO;GACL,WAAW,KAAK,QAAQ,KAAK,QAAQ,aAAa;GAClD;GACA,WAAW,MAAM,QAAQ,OAAO,SAAS,QAAQ,KAAK,MAAM,CAAC;GAC7D,YAAY,WAAW,OAAO;GAC9B,QAAQ,OAAO,QAAQ;EACzB;CACF;CAEA,AAAQ,iBAAiB,OAAoE;EAC3F,MAAM,MAAM,MAAM,SAAS;EAC3B,IAAI,KAAK,kBAAkB,IAAI,GAAG,GAAG;EAErC,KAAK,kBAAkB,IAAI,GAAG;EAC9B,IAAI,KAAK,QAAQ,SAAS,sBACxB,KAAK,QAAQ,SAAS,qBAAqB,KAAK;OAEhD,QAAQ,KACN,qBAAqB,IAAI,2CAA2C,MAAM,QAAQ,WACpF;CACJ;AACF"}

package/esm/sitemap-shard-writer.mjs

@@ -1,5 +1,5 @@
 import { normalizeEntry } from "./normalize-entry.mjs";
-import { XHTML_NAMESPACE_ATTR, buildSitemapXml, renderUrlBlock } from "./xml.mjs";
+import { IMAGE_NAMESPACE_ATTR, XHTML_NAMESPACE_ATTR, buildSitemapXml, renderUrlBlock } from "./xml.mjs";
 import { shardFileName } from "./shard-name.mjs";
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
@@ -17,6 +17,7 @@ function envelopeBytes(baseUrl) {
 * shard's real bytes on disk exceed the ceiling it was rolled against.
 */
 const NAMESPACE_BYTES = Buffer.byteLength(XHTML_NAMESPACE_ATTR, "utf8");
+const IMAGE_NAMESPACE_BYTES = Buffer.byteLength(IMAGE_NAMESPACE_ATTR, "utf8");
 async function writeShardFile(ctx, fileName, entries) {
 	const xml = buildSitemapXml(entries, ctx.baseUrl);
 	const filePath = join(ctx.tempDir, fileName);
@@ -38,6 +39,7 @@ async function writeShardGroup(group, ctx) {
 	let buffer = [];
 	let bufferBytes = envelopeBytes(ctx.baseUrl);
 	let bufferHasAlternates = false;
+	let bufferHasImages = false;
 	let ordinal = 1;
 	const flush = async () => {
 		if (buffer.length === 0) return;
@@ -54,6 +56,7 @@ async function writeShardGroup(group, ctx) {
 		buffer = [];
 		bufferBytes = envelopeBytes(ctx.baseUrl);
 		bufferHasAlternates = false;
+		bufferHasImages = false;
 	};
 	for (const factory of group.factories) {
 		const source = await factory();
@@ -61,15 +64,18 @@ async function writeShardGroup(group, ctx) {
 			const resolved = normalizeEntry(rawEntry, ctx.defaults);
 			if (!ctx.duplicates.attempt(resolved.path, resolved.route)) continue;
 			const entryHasAlternates = (resolved.alternates?.length ?? 0) > 0;
+			const entryHasImages = (resolved.images?.length ?? 0) > 0;
 			const blockBytes = Buffer.byteLength(renderUrlBlock(resolved, ctx.baseUrl), "utf8") + 1;
-			const addedBytes = blockBytes + (entryHasAlternates && !bufferHasAlternates ? NAMESPACE_BYTES : 0);
+			const addedBytes = blockBytes + (entryHasAlternates && !bufferHasAlternates ? NAMESPACE_BYTES : 0) + (entryHasImages && !bufferHasImages ? IMAGE_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;
+			const addsImageNamespaceNow = entryHasImages && !bufferHasImages;
 			buffer.push(resolved);
-			bufferBytes += blockBytes + (addsNamespaceNow ? NAMESPACE_BYTES : 0);
+			bufferBytes += blockBytes + (addsNamespaceNow ? NAMESPACE_BYTES : 0) + (addsImageNamespaceNow ? IMAGE_NAMESPACE_BYTES : 0);
 			if (addsNamespaceNow) bufferHasAlternates = true;
+			if (addsImageNamespaceNow) bufferHasImages = true;
 			ctx.routes.record(resolved.route);
 		}
 	}

package/esm/sitemap-shard-writer.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sitemap-shard-writer.mjs","names":[],"sources":["../../../../../../sitemap/src/sitemap-shard-writer.ts"],"sourcesContent":["import { writeFile } from \"node:fs/promises\";\nimport { gzipSync } from \"node:zlib\";\nimport { join } from \"node:path\";\nimport { normalizeEntry } from \"./normalize-entry\";\nimport { shardFileName } from \"./shard-name\";\nimport type { ResolvedSitemapEntry, SitemapOptions } from \"./types\";\nimport type { DuplicatePathTracker } from \"./duplicate-path-tracker\";\nimport type { RouteCounter } from \"./route-counter\";\nimport type { SitemapSourceFactory } from \"./sitemap-index-types\";\nimport { buildSitemapXml, renderUrlBlock, XHTML_NAMESPACE_ATTR } from \"./xml\";\n\n/** One `addSource` group: the unnamed group merges every unkeyed call; a keyed group holds exactly one factory. */\nexport type ShardGroup = {\n  readonly key?: string;\n  readonly factories: readonly SitemapSourceFactory[];\n};\n\nexport type ShardWriterContext = {\n  readonly tempDir: string;\n  readonly baseUrl: string;\n  readonly filePrefix: string;\n  readonly gzip: boolean;\n  readonly maxUrlsPerFile: number;\n  readonly maxBytesPerFile: number;\n  readonly defaults: Pick<SitemapOptions, \"changefreq\" | \"priority\" | \"lastmod\">;\n  readonly duplicates: DuplicatePathTracker;\n  readonly routes: RouteCounter;\n};\n\n/** A shard actually written, or the zero-url row reported for a group that produced nothing. */\nexport type ShardFile = {\n  readonly fileName: string;\n  readonly key?: string;\n  readonly urls: number;\n  readonly bytes: number;\n  readonly gzipped: boolean;\n};\n\nfunction envelopeBytes(baseUrl: string): number {\n  return Buffer.byteLength(buildSitemapXml([], baseUrl), \"utf8\");\n}\n\n/**\n * The extra bytes `<urlset>` gains for `xmlns:xhtml=\"…\"` once a shard holds\n * an entry with alternates. Charged separately from `envelopeBytes()` so the\n * ceiling check can add it exactly once — the moment the first alternate\n * enters the buffer — rather than missing it entirely, which would let a\n * shard's real bytes on disk exceed the ceiling it was rolled against.\n */\nconst NAMESPACE_BYTES = Buffer.byteLength(XHTML_NAMESPACE_ATTR, \"utf8\");\n\nasync function writeShardFile(\n  ctx: ShardWriterContext,\n  fileName: string,\n  entries: readonly ResolvedSitemapEntry[],\n): Promise<{ bytes: number }> {\n  const xml = buildSitemapXml(entries, ctx.baseUrl);\n  const filePath = join(ctx.tempDir, fileName);\n\n  if (ctx.gzip) {\n    const compressed = gzipSync(Buffer.from(xml, \"utf8\"));\n\n    await writeFile(filePath, compressed);\n\n    return { bytes: compressed.byteLength };\n  }\n\n  await writeFile(filePath, xml, \"utf8\");\n\n  return { bytes: Buffer.byteLength(xml, \"utf8\") };\n}\n\n/**\n * Walks one group's factories, one at a time, rolling to a new shard on\n * whichever ceiling — URL count or serialised bytes — is hit first. Holds\n * only the current shard's buffer, never the whole group.\n */\nexport async function writeShardGroup(\n  group: ShardGroup,\n  ctx: ShardWriterContext,\n): Promise<ShardFile[]> {\n  const results: ShardFile[] = [];\n\n  let buffer: ResolvedSitemapEntry[] = [];\n  let bufferBytes = envelopeBytes(ctx.baseUrl);\n  // Charged once, the moment the buffer's first alternate-bearing entry is added — mirrors\n  // buildSitemapXml()'s own \"at least one entry has alternates\" rule for the same shard.\n  let bufferHasAlternates = false;\n  let ordinal = 1;\n\n  const flush = async () => {\n    if (buffer.length === 0) return;\n\n    const fileName = shardFileName(ctx.filePrefix, group.key, ordinal, ctx.gzip);\n    const { bytes } = await writeShardFile(ctx, fileName, buffer);\n\n    results.push({ fileName, key: group.key, urls: buffer.length, bytes, gzipped: ctx.gzip });\n\n    ordinal += 1;\n    buffer = [];\n    bufferBytes = envelopeBytes(ctx.baseUrl);\n    bufferHasAlternates = false;\n  };\n\n  for (const factory of group.factories) {\n    const source = await factory();\n\n    for await (const rawEntry of source) {\n      const resolved = normalizeEntry(rawEntry, ctx.defaults);\n\n      // Duplicate paths are SKIPPED, not overridden: the earlier one is already on disk.\n      if (!ctx.duplicates.attempt(resolved.path, resolved.route)) continue;\n\n      const entryHasAlternates = (resolved.alternates?.length ?? 0) > 0;\n      const blockBytes = Buffer.byteLength(renderUrlBlock(resolved, ctx.baseUrl), \"utf8\") + 1;\n      // What this entry would add to the CURRENT shard: its own block, plus the namespace\n      // attribute if this is the shard's first alternate and the buffer doesn't carry it yet.\n      const addedBytes =\n        blockBytes + (entryHasAlternates && !bufferHasAlternates ? NAMESPACE_BYTES : 0);\n\n      const hitsUrlCeiling = buffer.length >= ctx.maxUrlsPerFile;\n      // A single entry can never be split, so the byte ceiling only rolls an already-nonempty shard.\n      const hitsByteCeiling = buffer.length > 0 && bufferBytes + addedBytes > ctx.maxBytesPerFile;\n\n      if (hitsUrlCeiling || hitsByteCeiling) await flush();\n\n      const addsNamespaceNow = entryHasAlternates && !bufferHasAlternates;\n\n      buffer.push(resolved);\n      bufferBytes += blockBytes + (addsNamespaceNow ? NAMESPACE_BYTES : 0);\n      if (addsNamespaceNow) bufferHasAlternates = true;\n      ctx.routes.record(resolved.route);\n    }\n  }\n\n  await flush();\n\n  if (results.length === 0) {\n    // Reported, never written: an empty shard in an index is a section someone lost.\n    results.push({\n      fileName: shardFileName(ctx.filePrefix, group.key, 1, ctx.gzip),\n      key: group.key,\n      urls: 0,\n      bytes: 0,\n      gzipped: false,\n    });\n  }\n\n  return results;\n}\n"],"mappings":";;;;;;;;AAsCA,SAAS,cAAc,SAAyB;CAC9C,OAAO,OAAO,WAAW,gBAAgB,CAAC,GAAG,OAAO,GAAG,MAAM;AAC/D;;;;;;;;AASA,MAAM,kBAAkB,OAAO,WAAW,sBAAsB,MAAM;AAEtE,eAAe,eACb,KACA,UACA,SAC4B;CAC5B,MAAM,MAAM,gBAAgB,SAAS,IAAI,OAAO;CAChD,MAAM,WAAW,KAAK,IAAI,SAAS,QAAQ;CAE3C,IAAI,IAAI,MAAM;EACZ,MAAM,aAAa,SAAS,OAAO,KAAK,KAAK,MAAM,CAAC;EAEpD,MAAM,UAAU,UAAU,UAAU;EAEpC,OAAO,EAAE,OAAO,WAAW,WAAW;CACxC;CAEA,MAAM,UAAU,UAAU,KAAK,MAAM;CAErC,OAAO,EAAE,OAAO,OAAO,WAAW,KAAK,MAAM,EAAE;AACjD;;;;;;AAOA,eAAsB,gBACpB,OACA,KACsB;CACtB,MAAM,UAAuB,CAAC;CAE9B,IAAI,SAAiC,CAAC;CACtC,IAAI,cAAc,cAAc,IAAI,OAAO;CAG3C,IAAI,sBAAsB;CAC1B,IAAI,UAAU;CAEd,MAAM,QAAQ,YAAY;EACxB,IAAI,OAAO,WAAW,GAAG;EAEzB,MAAM,WAAW,cAAc,IAAI,YAAY,MAAM,KAAK,SAAS,IAAI,IAAI;EAC3E,MAAM,EAAE,UAAU,MAAM,eAAe,KAAK,UAAU,MAAM;EAE5D,QAAQ,KAAK;GAAE;GAAU,KAAK,MAAM;GAAK,MAAM,OAAO;GAAQ;GAAO,SAAS,IAAI;EAAK,CAAC;EAExF,WAAW;EACX,SAAS,CAAC;EACV,cAAc,cAAc,IAAI,OAAO;EACvC,sBAAsB;CACxB;CAEA,KAAK,MAAM,WAAW,MAAM,WAAW;EACrC,MAAM,SAAS,MAAM,QAAQ;EAE7B,WAAW,MAAM,YAAY,QAAQ;GACnC,MAAM,WAAW,eAAe,UAAU,IAAI,QAAQ;GAGtD,IAAI,CAAC,IAAI,WAAW,QAAQ,SAAS,MAAM,SAAS,KAAK,GAAG;GAE5D,MAAM,sBAAsB,SAAS,YAAY,UAAU,KAAK;GAChE,MAAM,aAAa,OAAO,WAAW,eAAe,UAAU,IAAI,OAAO,GAAG,MAAM,IAAI;GAGtF,MAAM,aACJ,cAAc,sBAAsB,CAAC,sBAAsB,kBAAkB;GAE/E,MAAM,iBAAiB,OAAO,UAAU,IAAI;GAE5C,MAAM,kBAAkB,OAAO,SAAS,KAAK,cAAc,aAAa,IAAI;GAE5E,IAAI,kBAAkB,iBAAiB,MAAM,MAAM;GAEnD,MAAM,mBAAmB,sBAAsB,CAAC;GAEhD,OAAO,KAAK,QAAQ;GACpB,eAAe,cAAc,mBAAmB,kBAAkB;GAClE,IAAI,kBAAkB,sBAAsB;GAC5C,IAAI,OAAO,OAAO,SAAS,KAAK;EAClC;CACF;CAEA,MAAM,MAAM;CAEZ,IAAI,QAAQ,WAAW,GAErB,QAAQ,KAAK;EACX,UAAU,cAAc,IAAI,YAAY,MAAM,KAAK,GAAG,IAAI,IAAI;EAC9D,KAAK,MAAM;EACX,MAAM;EACN,OAAO;EACP,SAAS;CACX,CAAC;CAGH,OAAO;AACT"}
+{"version":3,"file":"sitemap-shard-writer.mjs","names":[],"sources":["../../../../../../sitemap/src/sitemap-shard-writer.ts"],"sourcesContent":["import { writeFile } from \"node:fs/promises\";\nimport { gzipSync } from \"node:zlib\";\nimport { join } from \"node:path\";\nimport { normalizeEntry } from \"./normalize-entry\";\nimport { shardFileName } from \"./shard-name\";\nimport type { ResolvedSitemapEntry, SitemapOptions } from \"./types\";\nimport type { DuplicatePathTracker } from \"./duplicate-path-tracker\";\nimport type { RouteCounter } from \"./route-counter\";\nimport type { SitemapSourceFactory } from \"./sitemap-index-types\";\nimport { buildSitemapXml, IMAGE_NAMESPACE_ATTR, renderUrlBlock, XHTML_NAMESPACE_ATTR } from \"./xml\";\n\n/** One `addSource` group: the unnamed group merges every unkeyed call; a keyed group holds exactly one factory. */\nexport type ShardGroup = {\n  readonly key?: string;\n  readonly factories: readonly SitemapSourceFactory[];\n};\n\nexport type ShardWriterContext = {\n  readonly tempDir: string;\n  readonly baseUrl: string;\n  readonly filePrefix: string;\n  readonly gzip: boolean;\n  readonly maxUrlsPerFile: number;\n  readonly maxBytesPerFile: number;\n  readonly defaults: Pick<\n    SitemapOptions,\n    \"changefreq\" | \"priority\" | \"lastmod\" | \"onImageLimitExceeded\"\n  >;\n  readonly duplicates: DuplicatePathTracker;\n  readonly routes: RouteCounter;\n};\n\n/** A shard actually written, or the zero-url row reported for a group that produced nothing. */\nexport type ShardFile = {\n  readonly fileName: string;\n  readonly key?: string;\n  readonly urls: number;\n  readonly bytes: number;\n  readonly gzipped: boolean;\n};\n\nfunction envelopeBytes(baseUrl: string): number {\n  return Buffer.byteLength(buildSitemapXml([], baseUrl), \"utf8\");\n}\n\n/**\n * The extra bytes `<urlset>` gains for `xmlns:xhtml=\"…\"` once a shard holds\n * an entry with alternates. Charged separately from `envelopeBytes()` so the\n * ceiling check can add it exactly once — the moment the first alternate\n * enters the buffer — rather than missing it entirely, which would let a\n * shard's real bytes on disk exceed the ceiling it was rolled against.\n */\nconst NAMESPACE_BYTES = Buffer.byteLength(XHTML_NAMESPACE_ATTR, \"utf8\");\nconst IMAGE_NAMESPACE_BYTES = Buffer.byteLength(IMAGE_NAMESPACE_ATTR, \"utf8\");\n\nasync function writeShardFile(\n  ctx: ShardWriterContext,\n  fileName: string,\n  entries: readonly ResolvedSitemapEntry[],\n): Promise<{ bytes: number }> {\n  const xml = buildSitemapXml(entries, ctx.baseUrl);\n  const filePath = join(ctx.tempDir, fileName);\n\n  if (ctx.gzip) {\n    const compressed = gzipSync(Buffer.from(xml, \"utf8\"));\n\n    await writeFile(filePath, compressed);\n\n    return { bytes: compressed.byteLength };\n  }\n\n  await writeFile(filePath, xml, \"utf8\");\n\n  return { bytes: Buffer.byteLength(xml, \"utf8\") };\n}\n\n/**\n * Walks one group's factories, one at a time, rolling to a new shard on\n * whichever ceiling — URL count or serialised bytes — is hit first. Holds\n * only the current shard's buffer, never the whole group.\n */\nexport async function writeShardGroup(\n  group: ShardGroup,\n  ctx: ShardWriterContext,\n): Promise<ShardFile[]> {\n  const results: ShardFile[] = [];\n\n  let buffer: ResolvedSitemapEntry[] = [];\n  let bufferBytes = envelopeBytes(ctx.baseUrl);\n  // Charged once, the moment the buffer's first alternate-bearing entry is added — mirrors\n  // buildSitemapXml()'s own \"at least one entry has alternates\" rule for the same shard.\n  let bufferHasAlternates = false;\n  let bufferHasImages = false;\n  let ordinal = 1;\n\n  const flush = async () => {\n    if (buffer.length === 0) return;\n\n    const fileName = shardFileName(ctx.filePrefix, group.key, ordinal, ctx.gzip);\n    const { bytes } = await writeShardFile(ctx, fileName, buffer);\n\n    results.push({ fileName, key: group.key, urls: buffer.length, bytes, gzipped: ctx.gzip });\n\n    ordinal += 1;\n    buffer = [];\n    bufferBytes = envelopeBytes(ctx.baseUrl);\n    bufferHasAlternates = false;\n    bufferHasImages = false;\n  };\n\n  for (const factory of group.factories) {\n    const source = await factory();\n\n    for await (const rawEntry of source) {\n      const resolved = normalizeEntry(rawEntry, ctx.defaults);\n\n      // Duplicate paths are SKIPPED, not overridden: the earlier one is already on disk.\n      if (!ctx.duplicates.attempt(resolved.path, resolved.route)) continue;\n\n      const entryHasAlternates = (resolved.alternates?.length ?? 0) > 0;\n      const entryHasImages = (resolved.images?.length ?? 0) > 0;\n      const blockBytes = Buffer.byteLength(renderUrlBlock(resolved, ctx.baseUrl), \"utf8\") + 1;\n      // What this entry would add to the CURRENT shard: its own block, plus the namespace\n      // attribute if this is the shard's first alternate and the buffer doesn't carry it yet.\n      const addedBytes =\n        blockBytes +\n        (entryHasAlternates && !bufferHasAlternates ? NAMESPACE_BYTES : 0) +\n        (entryHasImages && !bufferHasImages ? IMAGE_NAMESPACE_BYTES : 0);\n\n      const hitsUrlCeiling = buffer.length >= ctx.maxUrlsPerFile;\n      // A single entry can never be split, so the byte ceiling only rolls an already-nonempty shard.\n      const hitsByteCeiling = buffer.length > 0 && bufferBytes + addedBytes > ctx.maxBytesPerFile;\n\n      if (hitsUrlCeiling || hitsByteCeiling) await flush();\n\n      const addsNamespaceNow = entryHasAlternates && !bufferHasAlternates;\n      const addsImageNamespaceNow = entryHasImages && !bufferHasImages;\n\n      buffer.push(resolved);\n      bufferBytes +=\n        blockBytes +\n        (addsNamespaceNow ? NAMESPACE_BYTES : 0) +\n        (addsImageNamespaceNow ? IMAGE_NAMESPACE_BYTES : 0);\n      if (addsNamespaceNow) bufferHasAlternates = true;\n      if (addsImageNamespaceNow) bufferHasImages = true;\n      ctx.routes.record(resolved.route);\n    }\n  }\n\n  await flush();\n\n  if (results.length === 0) {\n    // Reported, never written: an empty shard in an index is a section someone lost.\n    results.push({\n      fileName: shardFileName(ctx.filePrefix, group.key, 1, ctx.gzip),\n      key: group.key,\n      urls: 0,\n      bytes: 0,\n      gzipped: false,\n    });\n  }\n\n  return results;\n}\n"],"mappings":";;;;;;;;AAyCA,SAAS,cAAc,SAAyB;CAC9C,OAAO,OAAO,WAAW,gBAAgB,CAAC,GAAG,OAAO,GAAG,MAAM;AAC/D;;;;;;;;AASA,MAAM,kBAAkB,OAAO,WAAW,sBAAsB,MAAM;AACtE,MAAM,wBAAwB,OAAO,WAAW,sBAAsB,MAAM;AAE5E,eAAe,eACb,KACA,UACA,SAC4B;CAC5B,MAAM,MAAM,gBAAgB,SAAS,IAAI,OAAO;CAChD,MAAM,WAAW,KAAK,IAAI,SAAS,QAAQ;CAE3C,IAAI,IAAI,MAAM;EACZ,MAAM,aAAa,SAAS,OAAO,KAAK,KAAK,MAAM,CAAC;EAEpD,MAAM,UAAU,UAAU,UAAU;EAEpC,OAAO,EAAE,OAAO,WAAW,WAAW;CACxC;CAEA,MAAM,UAAU,UAAU,KAAK,MAAM;CAErC,OAAO,EAAE,OAAO,OAAO,WAAW,KAAK,MAAM,EAAE;AACjD;;;;;;AAOA,eAAsB,gBACpB,OACA,KACsB;CACtB,MAAM,UAAuB,CAAC;CAE9B,IAAI,SAAiC,CAAC;CACtC,IAAI,cAAc,cAAc,IAAI,OAAO;CAG3C,IAAI,sBAAsB;CAC1B,IAAI,kBAAkB;CACtB,IAAI,UAAU;CAEd,MAAM,QAAQ,YAAY;EACxB,IAAI,OAAO,WAAW,GAAG;EAEzB,MAAM,WAAW,cAAc,IAAI,YAAY,MAAM,KAAK,SAAS,IAAI,IAAI;EAC3E,MAAM,EAAE,UAAU,MAAM,eAAe,KAAK,UAAU,MAAM;EAE5D,QAAQ,KAAK;GAAE;GAAU,KAAK,MAAM;GAAK,MAAM,OAAO;GAAQ;GAAO,SAAS,IAAI;EAAK,CAAC;EAExF,WAAW;EACX,SAAS,CAAC;EACV,cAAc,cAAc,IAAI,OAAO;EACvC,sBAAsB;EACtB,kBAAkB;CACpB;CAEA,KAAK,MAAM,WAAW,MAAM,WAAW;EACrC,MAAM,SAAS,MAAM,QAAQ;EAE7B,WAAW,MAAM,YAAY,QAAQ;GACnC,MAAM,WAAW,eAAe,UAAU,IAAI,QAAQ;GAGtD,IAAI,CAAC,IAAI,WAAW,QAAQ,SAAS,MAAM,SAAS,KAAK,GAAG;GAE5D,MAAM,sBAAsB,SAAS,YAAY,UAAU,KAAK;GAChE,MAAM,kBAAkB,SAAS,QAAQ,UAAU,KAAK;GACxD,MAAM,aAAa,OAAO,WAAW,eAAe,UAAU,IAAI,OAAO,GAAG,MAAM,IAAI;GAGtF,MAAM,aACJ,cACC,sBAAsB,CAAC,sBAAsB,kBAAkB,MAC/D,kBAAkB,CAAC,kBAAkB,wBAAwB;GAEhE,MAAM,iBAAiB,OAAO,UAAU,IAAI;GAE5C,MAAM,kBAAkB,OAAO,SAAS,KAAK,cAAc,aAAa,IAAI;GAE5E,IAAI,kBAAkB,iBAAiB,MAAM,MAAM;GAEnD,MAAM,mBAAmB,sBAAsB,CAAC;GAChD,MAAM,wBAAwB,kBAAkB,CAAC;GAEjD,OAAO,KAAK,QAAQ;GACpB,eACE,cACC,mBAAmB,kBAAkB,MACrC,wBAAwB,wBAAwB;GACnD,IAAI,kBAAkB,sBAAsB;GAC5C,IAAI,uBAAuB,kBAAkB;GAC7C,IAAI,OAAO,OAAO,SAAS,KAAK;EAClC;CACF;CAEA,MAAM,MAAM;CAEZ,IAAI,QAAQ,WAAW,GAErB,QAAQ,KAAK;EACX,UAAU,cAAc,IAAI,YAAY,MAAM,KAAK,GAAG,IAAI,IAAI;EAC9D,KAAK,MAAM;EACX,MAAM;EACN,OAAO;EACP,SAAS;CACX,CAAC;CAGH,OAAO;AACT"}

package/esm/sitemap.d.mts

@@ -14,6 +14,8 @@ import { DuplicateReport, ResolvedSitemapEntry, RouteSummary, SitemapEntry, Site
 declare class Sitemap {
   private readonly baseUrl;
   private readonly defaults;
+  private readonly warnedImageRoutes;
+  private readonly optionsImageReporter;
   /** Keyed by path: a duplicate `<loc>` makes the document invalid, so the later add wins. */
   private readonly entriesByPath;
   /** Insertion order per path, so `duplicates()` can name every colliding source. */
@@ -21,6 +23,7 @@ declare class Sitemap {
   /** Declared patterns, including ones that never contributed a URL. */
   private readonly declaredRoutes;
   constructor(options: SitemapOptions);
+  private reportImageLimit;
   add(entry: SitemapEntry): this;
   addMany(entries: Iterable<SitemapEntry>): this;
   /**

package/esm/sitemap.mjs

@@ -20,6 +20,8 @@ import { dirname, join } from "node:path";
 var Sitemap = class {
 	baseUrl;
 	defaults;
+	warnedImageRoutes = /* @__PURE__ */ new Set();
+	optionsImageReporter;
 	/** 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. */
@@ -28,12 +30,21 @@ var Sitemap = class {
 	declaredRoutes = /* @__PURE__ */ new Set();
 	constructor(options) {
 		this.baseUrl = normalizeBaseUrl(options?.baseUrl);
+		this.optionsImageReporter = options.onImageLimitExceeded;
 		this.defaults = {
 			changefreq: options.changefreq,
 			priority: options.priority,
-			lastmod: options.lastmod
+			lastmod: options.lastmod,
+			onImageLimitExceeded: (event) => this.reportImageLimit(event)
 		};
 	}
+	reportImageLimit(event) {
+		const key = event.route ?? "unattributed";
+		if (this.warnedImageRoutes.has(key)) return;
+		this.warnedImageRoutes.add(key);
+		if (this.optionsImageReporter) this.optionsImageReporter(event);
+		else console.warn(`[warlock:sitemap] ${key} exceeded the 1,000-image limit; dropped ${event.dropped} image(s).`);
+	}
 	add(entry) {
 		const resolved = normalizeEntry(entry, this.defaults);
 		this.entriesByPath.set(resolved.path, resolved);

package/esm/sitemap.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sitemap.mjs","names":[],"sources":["../../../../../../sitemap/src/sitemap.ts"],"sourcesContent":["import { mkdir, writeFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { publishAtomically } from \"./atomic-publish\";\nimport { atomicWriteFile } from \"./atomic-write-file\";\nimport { normalizeEntry } from \"./normalize-entry\";\nimport type {\n  DuplicateReport,\n  ResolvedSitemapEntry,\n  RouteSummary,\n  SitemapEntry,\n  SitemapOptions,\n} from \"./types\";\nimport { normalizeBaseUrl } from \"./url\";\nimport { buildSitemapXml } from \"./xml\";\n\n/**\n * A bounded sitemap builder: it RETAINS every entry, which is what makes\n * `entries()` and a repeatable `toXML()` possible, and is exactly right up to\n * the sitemaps.org ceiling of 50,000 URLs / 50MB.\n *\n * Above that ceiling this is the wrong tool — the streaming writer retains\n * nothing and emits shards plus an index instead. The two modes are separate\n * on purpose: a class that promised not to retain entries and still offered\n * `entries()` would be lying about one of them.\n */\nexport class Sitemap {\n  private readonly baseUrl: string;\n\n  private readonly defaults: Pick<SitemapOptions, \"changefreq\" | \"priority\" | \"lastmod\">;\n\n  /** Keyed by path: a duplicate `<loc>` makes the document invalid, so the later add wins. */\n  private readonly entriesByPath = new Map<string, ResolvedSitemapEntry>();\n\n  /** Insertion order per path, so `duplicates()` can name every colliding source. */\n  private readonly routesByPath = new Map<string, (string | undefined)[]>();\n\n  /** Declared patterns, including ones that never contributed a URL. */\n  private readonly declaredRoutes = new Set<string>();\n\n  public constructor(options: SitemapOptions) {\n    this.baseUrl = normalizeBaseUrl(options?.baseUrl);\n    this.defaults = {\n      changefreq: options.changefreq,\n      priority: options.priority,\n      lastmod: options.lastmod,\n    };\n  }\n\n  public add(entry: SitemapEntry): this {\n    const resolved = normalizeEntry(entry, this.defaults);\n\n    this.entriesByPath.set(resolved.path, resolved);\n\n    const seen = this.routesByPath.get(resolved.path);\n\n    if (seen) {\n      seen.push(resolved.route);\n    } else {\n      this.routesByPath.set(resolved.path, [resolved.route]);\n    }\n\n    if (resolved.route !== undefined) this.declaredRoutes.add(resolved.route);\n\n    return this;\n  }\n\n  public addMany(entries: Iterable<SitemapEntry>): this {\n    for (const entry of entries) this.add(entry);\n\n    return this;\n  }\n\n  /**\n   * Names a pattern the caller EXPECTS to contribute URLs, so that one which\n   * contributes none shows up in `routes()` as a `count: 0` row instead of as\n   * silence. A dynamic route whose supplier returned nothing is the failure\n   * this package exists to make visible.\n   */\n  public declareRoute(route: string): this {\n    this.declaredRoutes.add(route);\n\n    return this;\n  }\n\n  public get size(): number {\n    return this.entriesByPath.size;\n  }\n\n  public entries(): readonly ResolvedSitemapEntry[] {\n    return [...this.entriesByPath.values()];\n  }\n\n  public routes(): readonly RouteSummary[] {\n    const counts = new Map<string, number>();\n\n    for (const route of this.declaredRoutes) counts.set(route, 0);\n\n    for (const entry of this.entriesByPath.values()) {\n      if (entry.route === undefined) continue;\n\n      counts.set(entry.route, (counts.get(entry.route) ?? 0) + 1);\n    }\n\n    return [...counts].map(([route, count]) => ({ route, count }));\n  }\n\n  /**\n   * Every path added more than once. The override is silent — it is not\n   * hidden: a collision between static discovery and a dynamic supplier is a\n   * real defect, and the CALLER decides whether it fails their build. This\n   * package reports; it never prints and never throws over a duplicate.\n   */\n  public duplicates(): readonly DuplicateReport[] {\n    const reports: DuplicateReport[] = [];\n\n    for (const [path, routes] of this.routesByPath) {\n      if (routes.length < 2) continue;\n\n      reports.push({ path, count: routes.length, routes: [...routes] });\n    }\n\n    return reports;\n  }\n\n  /** Pure and repeatable: calling it twice returns the same string and mutates nothing. */\n  public toXML(): string {\n    return buildSitemapXml(this.entries(), this.baseUrl);\n  }\n\n  /**\n   * Writes the document, creating parent directories so a clean checkout\n   * works. The write is atomic: a failed or interrupted publish leaves\n   * whatever was already at `filePath` untouched instead of truncating it.\n   */\n  public async saveTo(filePath: string): Promise<void> {\n    await mkdir(dirname(filePath), { recursive: true });\n    await atomicWriteFile(filePath, this.toXML());\n  }\n\n  /**\n   * Publishes the document as the whole content of `outDir`, exactly the way\n   * `SitemapIndex.saveTo` publishes a set: swapped in atomically, and marked\n   * as owned. So a site that later outgrows one file can publish an index\n   * into the same directory, and a later single file removes stale shards.\n   * Refuses a non-empty directory this package did not write\n   * (`UnownedOutputDirectoryError`). Returns the published file's path.\n   */\n  public async publishTo(outDir: string, fileName = \"sitemap.xml\"): Promise<string> {\n    const xml = this.toXML();\n\n    await publishAtomically(outDir, async (tempDir) => {\n      await writeFile(join(tempDir, fileName), xml, \"utf8\");\n\n      return [fileName];\n    });\n\n    return join(outDir, fileName);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAyBA,IAAa,UAAb,MAAqB;CACnB,AAAiB;CAEjB,AAAiB;;CAGjB,AAAiB,gCAAgB,IAAI,IAAkC;;CAGvE,AAAiB,+BAAe,IAAI,IAAoC;;CAGxE,AAAiB,iCAAiB,IAAI,IAAY;CAElD,AAAO,YAAY,SAAyB;EAC1C,KAAK,UAAU,iBAAiB,SAAS,OAAO;EAChD,KAAK,WAAW;GACd,YAAY,QAAQ;GACpB,UAAU,QAAQ;GAClB,SAAS,QAAQ;EACnB;CACF;CAEA,AAAO,IAAI,OAA2B;EACpC,MAAM,WAAW,eAAe,OAAO,KAAK,QAAQ;EAEpD,KAAK,cAAc,IAAI,SAAS,MAAM,QAAQ;EAE9C,MAAM,OAAO,KAAK,aAAa,IAAI,SAAS,IAAI;EAEhD,IAAI,MACF,KAAK,KAAK,SAAS,KAAK;OAExB,KAAK,aAAa,IAAI,SAAS,MAAM,CAAC,SAAS,KAAK,CAAC;EAGvD,IAAI,SAAS,UAAU,QAAW,KAAK,eAAe,IAAI,SAAS,KAAK;EAExE,OAAO;CACT;CAEA,AAAO,QAAQ,SAAuC;EACpD,KAAK,MAAM,SAAS,SAAS,KAAK,IAAI,KAAK;EAE3C,OAAO;CACT;;;;;;;CAQA,AAAO,aAAa,OAAqB;EACvC,KAAK,eAAe,IAAI,KAAK;EAE7B,OAAO;CACT;CAEA,IAAW,OAAe;EACxB,OAAO,KAAK,cAAc;CAC5B;CAEA,AAAO,UAA2C;EAChD,OAAO,CAAC,GAAG,KAAK,cAAc,OAAO,CAAC;CACxC;CAEA,AAAO,SAAkC;EACvC,MAAM,yBAAS,IAAI,IAAoB;EAEvC,KAAK,MAAM,SAAS,KAAK,gBAAgB,OAAO,IAAI,OAAO,CAAC;EAE5D,KAAK,MAAM,SAAS,KAAK,cAAc,OAAO,GAAG;GAC/C,IAAI,MAAM,UAAU,QAAW;GAE/B,OAAO,IAAI,MAAM,QAAQ,OAAO,IAAI,MAAM,KAAK,KAAK,KAAK,CAAC;EAC5D;EAEA,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY;GAAE;GAAO;EAAM,EAAE;CAC/D;;;;;;;CAQA,AAAO,aAAyC;EAC9C,MAAM,UAA6B,CAAC;EAEpC,KAAK,MAAM,CAAC,MAAM,WAAW,KAAK,cAAc;GAC9C,IAAI,OAAO,SAAS,GAAG;GAEvB,QAAQ,KAAK;IAAE;IAAM,OAAO,OAAO;IAAQ,QAAQ,CAAC,GAAG,MAAM;GAAE,CAAC;EAClE;EAEA,OAAO;CACT;;CAGA,AAAO,QAAgB;EACrB,OAAO,gBAAgB,KAAK,QAAQ,GAAG,KAAK,OAAO;CACrD;;;;;;CAOA,MAAa,OAAO,UAAiC;EACnD,MAAM,MAAM,QAAQ,QAAQ,GAAG,EAAE,WAAW,KAAK,CAAC;EAClD,MAAM,gBAAgB,UAAU,KAAK,MAAM,CAAC;CAC9C;;;;;;;;;CAUA,MAAa,UAAU,QAAgB,WAAW,eAAgC;EAChF,MAAM,MAAM,KAAK,MAAM;EAEvB,MAAM,kBAAkB,QAAQ,OAAO,YAAY;GACjD,MAAM,UAAU,KAAK,SAAS,QAAQ,GAAG,KAAK,MAAM;GAEpD,OAAO,CAAC,QAAQ;EAClB,CAAC;EAED,OAAO,KAAK,QAAQ,QAAQ;CAC9B;AACF"}
+{"version":3,"file":"sitemap.mjs","names":[],"sources":["../../../../../../sitemap/src/sitemap.ts"],"sourcesContent":["import { mkdir, writeFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { publishAtomically } from \"./atomic-publish\";\nimport { atomicWriteFile } from \"./atomic-write-file\";\nimport { normalizeEntry } from \"./normalize-entry\";\nimport type {\n  DuplicateReport,\n  ResolvedSitemapEntry,\n  RouteSummary,\n  SitemapEntry,\n  SitemapOptions,\n} from \"./types\";\nimport { normalizeBaseUrl } from \"./url\";\nimport { buildSitemapXml } from \"./xml\";\n\n/**\n * A bounded sitemap builder: it RETAINS every entry, which is what makes\n * `entries()` and a repeatable `toXML()` possible, and is exactly right up to\n * the sitemaps.org ceiling of 50,000 URLs / 50MB.\n *\n * Above that ceiling this is the wrong tool — the streaming writer retains\n * nothing and emits shards plus an index instead. The two modes are separate\n * on purpose: a class that promised not to retain entries and still offered\n * `entries()` would be lying about one of them.\n */\nexport class Sitemap {\n  private readonly baseUrl: string;\n\n  private readonly defaults: Pick<\n    SitemapOptions,\n    \"changefreq\" | \"priority\" | \"lastmod\" | \"onImageLimitExceeded\"\n  >;\n\n  private readonly warnedImageRoutes = new Set<string>();\n\n  private readonly optionsImageReporter: SitemapOptions[\"onImageLimitExceeded\"];\n\n  /** Keyed by path: a duplicate `<loc>` makes the document invalid, so the later add wins. */\n  private readonly entriesByPath = new Map<string, ResolvedSitemapEntry>();\n\n  /** Insertion order per path, so `duplicates()` can name every colliding source. */\n  private readonly routesByPath = new Map<string, (string | undefined)[]>();\n\n  /** Declared patterns, including ones that never contributed a URL. */\n  private readonly declaredRoutes = new Set<string>();\n\n  public constructor(options: SitemapOptions) {\n    this.baseUrl = normalizeBaseUrl(options?.baseUrl);\n    this.optionsImageReporter = options.onImageLimitExceeded;\n    this.defaults = {\n      changefreq: options.changefreq,\n      priority: options.priority,\n      lastmod: options.lastmod,\n      onImageLimitExceeded: (event) => this.reportImageLimit(event),\n    };\n  }\n\n  private reportImageLimit(event: { readonly route?: string; readonly dropped: number }): void {\n    const key = event.route ?? \"unattributed\";\n    if (this.warnedImageRoutes.has(key)) return;\n\n    this.warnedImageRoutes.add(key);\n    if (this.optionsImageReporter) this.optionsImageReporter(event);\n    else\n      console.warn(\n        `[warlock:sitemap] ${key} exceeded the 1,000-image limit; dropped ${event.dropped} image(s).`,\n      );\n  }\n\n  public add(entry: SitemapEntry): this {\n    const resolved = normalizeEntry(entry, this.defaults);\n\n    this.entriesByPath.set(resolved.path, resolved);\n\n    const seen = this.routesByPath.get(resolved.path);\n\n    if (seen) {\n      seen.push(resolved.route);\n    } else {\n      this.routesByPath.set(resolved.path, [resolved.route]);\n    }\n\n    if (resolved.route !== undefined) this.declaredRoutes.add(resolved.route);\n\n    return this;\n  }\n\n  public addMany(entries: Iterable<SitemapEntry>): this {\n    for (const entry of entries) this.add(entry);\n\n    return this;\n  }\n\n  /**\n   * Names a pattern the caller EXPECTS to contribute URLs, so that one which\n   * contributes none shows up in `routes()` as a `count: 0` row instead of as\n   * silence. A dynamic route whose supplier returned nothing is the failure\n   * this package exists to make visible.\n   */\n  public declareRoute(route: string): this {\n    this.declaredRoutes.add(route);\n\n    return this;\n  }\n\n  public get size(): number {\n    return this.entriesByPath.size;\n  }\n\n  public entries(): readonly ResolvedSitemapEntry[] {\n    return [...this.entriesByPath.values()];\n  }\n\n  public routes(): readonly RouteSummary[] {\n    const counts = new Map<string, number>();\n\n    for (const route of this.declaredRoutes) counts.set(route, 0);\n\n    for (const entry of this.entriesByPath.values()) {\n      if (entry.route === undefined) continue;\n\n      counts.set(entry.route, (counts.get(entry.route) ?? 0) + 1);\n    }\n\n    return [...counts].map(([route, count]) => ({ route, count }));\n  }\n\n  /**\n   * Every path added more than once. The override is silent — it is not\n   * hidden: a collision between static discovery and a dynamic supplier is a\n   * real defect, and the CALLER decides whether it fails their build. This\n   * package reports; it never prints and never throws over a duplicate.\n   */\n  public duplicates(): readonly DuplicateReport[] {\n    const reports: DuplicateReport[] = [];\n\n    for (const [path, routes] of this.routesByPath) {\n      if (routes.length < 2) continue;\n\n      reports.push({ path, count: routes.length, routes: [...routes] });\n    }\n\n    return reports;\n  }\n\n  /** Pure and repeatable: calling it twice returns the same string and mutates nothing. */\n  public toXML(): string {\n    return buildSitemapXml(this.entries(), this.baseUrl);\n  }\n\n  /**\n   * Writes the document, creating parent directories so a clean checkout\n   * works. The write is atomic: a failed or interrupted publish leaves\n   * whatever was already at `filePath` untouched instead of truncating it.\n   */\n  public async saveTo(filePath: string): Promise<void> {\n    await mkdir(dirname(filePath), { recursive: true });\n    await atomicWriteFile(filePath, this.toXML());\n  }\n\n  /**\n   * Publishes the document as the whole content of `outDir`, exactly the way\n   * `SitemapIndex.saveTo` publishes a set: swapped in atomically, and marked\n   * as owned. So a site that later outgrows one file can publish an index\n   * into the same directory, and a later single file removes stale shards.\n   * Refuses a non-empty directory this package did not write\n   * (`UnownedOutputDirectoryError`). Returns the published file's path.\n   */\n  public async publishTo(outDir: string, fileName = \"sitemap.xml\"): Promise<string> {\n    const xml = this.toXML();\n\n    await publishAtomically(outDir, async (tempDir) => {\n      await writeFile(join(tempDir, fileName), xml, \"utf8\");\n\n      return [fileName];\n    });\n\n    return join(outDir, fileName);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAyBA,IAAa,UAAb,MAAqB;CACnB,AAAiB;CAEjB,AAAiB;CAKjB,AAAiB,oCAAoB,IAAI,IAAY;CAErD,AAAiB;;CAGjB,AAAiB,gCAAgB,IAAI,IAAkC;;CAGvE,AAAiB,+BAAe,IAAI,IAAoC;;CAGxE,AAAiB,iCAAiB,IAAI,IAAY;CAElD,AAAO,YAAY,SAAyB;EAC1C,KAAK,UAAU,iBAAiB,SAAS,OAAO;EAChD,KAAK,uBAAuB,QAAQ;EACpC,KAAK,WAAW;GACd,YAAY,QAAQ;GACpB,UAAU,QAAQ;GAClB,SAAS,QAAQ;GACjB,uBAAuB,UAAU,KAAK,iBAAiB,KAAK;EAC9D;CACF;CAEA,AAAQ,iBAAiB,OAAoE;EAC3F,MAAM,MAAM,MAAM,SAAS;EAC3B,IAAI,KAAK,kBAAkB,IAAI,GAAG,GAAG;EAErC,KAAK,kBAAkB,IAAI,GAAG;EAC9B,IAAI,KAAK,sBAAsB,KAAK,qBAAqB,KAAK;OAE5D,QAAQ,KACN,qBAAqB,IAAI,2CAA2C,MAAM,QAAQ,WACpF;CACJ;CAEA,AAAO,IAAI,OAA2B;EACpC,MAAM,WAAW,eAAe,OAAO,KAAK,QAAQ;EAEpD,KAAK,cAAc,IAAI,SAAS,MAAM,QAAQ;EAE9C,MAAM,OAAO,KAAK,aAAa,IAAI,SAAS,IAAI;EAEhD,IAAI,MACF,KAAK,KAAK,SAAS,KAAK;OAExB,KAAK,aAAa,IAAI,SAAS,MAAM,CAAC,SAAS,KAAK,CAAC;EAGvD,IAAI,SAAS,UAAU,QAAW,KAAK,eAAe,IAAI,SAAS,KAAK;EAExE,OAAO;CACT;CAEA,AAAO,QAAQ,SAAuC;EACpD,KAAK,MAAM,SAAS,SAAS,KAAK,IAAI,KAAK;EAE3C,OAAO;CACT;;;;;;;CAQA,AAAO,aAAa,OAAqB;EACvC,KAAK,eAAe,IAAI,KAAK;EAE7B,OAAO;CACT;CAEA,IAAW,OAAe;EACxB,OAAO,KAAK,cAAc;CAC5B;CAEA,AAAO,UAA2C;EAChD,OAAO,CAAC,GAAG,KAAK,cAAc,OAAO,CAAC;CACxC;CAEA,AAAO,SAAkC;EACvC,MAAM,yBAAS,IAAI,IAAoB;EAEvC,KAAK,MAAM,SAAS,KAAK,gBAAgB,OAAO,IAAI,OAAO,CAAC;EAE5D,KAAK,MAAM,SAAS,KAAK,cAAc,OAAO,GAAG;GAC/C,IAAI,MAAM,UAAU,QAAW;GAE/B,OAAO,IAAI,MAAM,QAAQ,OAAO,IAAI,MAAM,KAAK,KAAK,KAAK,CAAC;EAC5D;EAEA,OAAO,CAAC,GAAG,MAAM,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY;GAAE;GAAO;EAAM,EAAE;CAC/D;;;;;;;CAQA,AAAO,aAAyC;EAC9C,MAAM,UAA6B,CAAC;EAEpC,KAAK,MAAM,CAAC,MAAM,WAAW,KAAK,cAAc;GAC9C,IAAI,OAAO,SAAS,GAAG;GAEvB,QAAQ,KAAK;IAAE;IAAM,OAAO,OAAO;IAAQ,QAAQ,CAAC,GAAG,MAAM;GAAE,CAAC;EAClE;EAEA,OAAO;CACT;;CAGA,AAAO,QAAgB;EACrB,OAAO,gBAAgB,KAAK,QAAQ,GAAG,KAAK,OAAO;CACrD;;;;;;CAOA,MAAa,OAAO,UAAiC;EACnD,MAAM,MAAM,QAAQ,QAAQ,GAAG,EAAE,WAAW,KAAK,CAAC;EAClD,MAAM,gBAAgB,UAAU,KAAK,MAAM,CAAC;CAC9C;;;;;;;;;CAUA,MAAa,UAAU,QAAgB,WAAW,eAAgC;EAChF,MAAM,MAAM,KAAK,MAAM;EAEvB,MAAM,kBAAkB,QAAQ,OAAO,YAAY;GACjD,MAAM,UAAU,KAAK,SAAS,QAAQ,GAAG,KAAK,MAAM;GAEpD,OAAO,CAAC,QAAQ;EAClB,CAAC;EAED,OAAO,KAAK,QAAQ,QAAQ;CAC9B;AACF"}

package/esm/types.d.mts

@@ -14,6 +14,14 @@ type SitemapAlternate = {
   readonly hreflang: string; /** A path resolved against `baseUrl`, or an absolute URL used as given. */
   readonly path: string;
 };
+/** One image associated with a page URL in Google's image sitemap extension. */
+type SitemapImage = {
+  /** An absolute HTTP(S) URL. It may point at a verified external CDN. */readonly loc: string;
+};
+type SitemapImageLimitExceeded = {
+  readonly route?: string;
+  readonly dropped: number;
+};
 /**
  * One `<url>` block. Only `path` is required; `name` and `route` are carried
  * for the diagnostics in `routes()` and `duplicates()` and never serialised.
@@ -25,7 +33,8 @@ type SitemapEntry = {
   readonly lastmod?: string | Date;
   readonly changefreq?: ChangeFreq;
   readonly priority?: number; /** Language versions of THIS page, conventionally including itself. */
-  readonly alternates?: readonly SitemapAlternate[];
+  readonly alternates?: readonly SitemapAlternate[]; /** Images discoverable from this page. At most 1,000 are emitted per URL. */
+  readonly images?: readonly SitemapImage[];
 };
 /**
  * An entry after normalisation: the path carries its leading slash, the
@@ -40,7 +49,8 @@ type SitemapOptions = {
   /** Absolute origin: `https://example.com` or `https://example.com/base`. */readonly baseUrl: string; /** Applied to every entry that does not set its own. */
   readonly changefreq?: ChangeFreq;
   readonly priority?: number;
-  readonly lastmod?: string | Date;
+  readonly lastmod?: string | Date; /** Called once per route when an entry exceeds Google's 1,000-image limit. */
+  readonly onImageLimitExceeded?: (event: SitemapImageLimitExceeded) => void;
 };
 /**
  * How many URLs a route contributed. A `count: 0` row is the interesting one:
@@ -60,5 +70,5 @@ type DuplicateReport = {
   readonly routes: readonly (string | undefined)[];
 };
 //#endregion
-export { ChangeFreq, DuplicateReport, ResolvedSitemapEntry, RouteSummary, SitemapAlternate, SitemapEntry, SitemapOptions };
+export { ChangeFreq, DuplicateReport, ResolvedSitemapEntry, RouteSummary, SitemapAlternate, SitemapEntry, SitemapImage, SitemapImageLimitExceeded, SitemapOptions };
 //# sourceMappingURL=types.d.mts.map

package/esm/xml.mjs

@@ -13,12 +13,15 @@ function escapeXml(value) {
 	return value.replace(/[&<>"']/g, (char) => XML_ESCAPES[char] ?? char);
 }
 const XHTML_NAMESPACE = "http://www.w3.org/1999/xhtml";
+const IMAGE_NAMESPACE = "http://www.google.com/schemas/sitemap-image/1.1";
 /**
 * 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}"`;
+/** See {@link XHTML_NAMESPACE_ATTR}; measured by the shard writer before roll-over. */
+const IMAGE_NAMESPACE_ATTR = ` xmlns:image="${IMAGE_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
@@ -34,6 +37,11 @@ function renderUrlBlock(entry, baseUrl) {
 		const href = escapeXml(resolveAgainstBase(baseUrl, alternate.path));
 		lines.push(`    <xhtml:link rel="alternate" hreflang="${escapeXml(alternate.hreflang)}" href="${href}"/>`);
 	}
+	for (const image of entry.images ?? []) {
+		lines.push(`    <image:image>`);
+		lines.push(`      <image:loc>${escapeXml(resolveAgainstBase(baseUrl, image.loc))}</image:loc>`);
+		lines.push(`    </image:image>`);
+	}
 	lines.push(`  </url>`);
 	return lines.join("\n");
 }
@@ -47,11 +55,13 @@ function renderUrlBlock(entry, baseUrl) {
 * alternate — an unused namespace on every single-language sitemap is noise.
 */
 function buildSitemapXml(entries, baseUrl) {
-	const namespaces = entries.some((entry) => (entry.alternates?.length ?? 0) > 0) ? XHTML_NAMESPACE_ATTR : "";
+	const hasAlternates = entries.some((entry) => (entry.alternates?.length ?? 0) > 0);
+	const hasImages = entries.some((entry) => (entry.images?.length ?? 0) > 0);
+	const namespaces = `${hasAlternates ? XHTML_NAMESPACE_ATTR : ""}${hasImages ? IMAGE_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
-export { XHTML_NAMESPACE_ATTR, buildSitemapXml, escapeXml, renderUrlBlock };
+export { IMAGE_NAMESPACE_ATTR, XHTML_NAMESPACE_ATTR, buildSitemapXml, escapeXml, renderUrlBlock };
 //# sourceMappingURL=xml.mjs.map

package/esm/xml.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"xml.mjs","names":[],"sources":["../../../../../../sitemap/src/xml.ts"],"sourcesContent":["import type { ResolvedSitemapEntry } from \"./types\";\nimport { resolveAgainstBase } from \"./url\";\n\nconst XML_ESCAPES: Record<string, string> = {\n  \"&\": \"&amp;\",\n  \"<\": \"&lt;\",\n  \">\": \"&gt;\",\n  '\"': \"&quot;\",\n  \"'\": \"&apos;\",\n};\n\n/** Escapes the five XML-significant characters. A URL's query string routinely contains `&`. */\nexport function escapeXml(value: string): string {\n  // The character class and the table are written together, so the lookup can\n  // only miss if one is edited without the other; falling back to the original\n  // character keeps that editing mistake from silently emitting `undefined`\n  // into a URL.\n  return value.replace(/[&<>\"']/g, (char) => XML_ESCAPES[char] ?? char);\n}\n\nconst XHTML_NAMESPACE = \"http://www.w3.org/1999/xhtml\";\n\n/**\n * The `xmlns:xhtml` attribute exactly as it appears on `<urlset>`, including\n * its leading space. Exported so the shard writer can charge its byte length\n * against the ceiling without duplicating the string it measures.\n */\nexport const XHTML_NAMESPACE_ATTR = ` xmlns:xhtml=\"${XHTML_NAMESPACE}\"`;\n\n/**\n * Renders one `<url>` block. Exported so the streaming writer can measure the\n * exact bytes it is about to append before deciding whether the byte ceiling\n * forces a new shard — a separate approximation could disagree with what is\n * actually written.\n */\nexport function renderUrlBlock(entry: ResolvedSitemapEntry, baseUrl: string): string {\n  const lines = [`  <url>`, `    <loc>${escapeXml(resolveAgainstBase(baseUrl, entry.path))}</loc>`];\n\n  if (entry.lastmod !== undefined) {\n    lines.push(`    <lastmod>${escapeXml(entry.lastmod)}</lastmod>`);\n  }\n\n  if (entry.changefreq !== undefined) {\n    lines.push(`    <changefreq>${entry.changefreq}</changefreq>`);\n  }\n\n  if (entry.priority !== undefined) {\n    lines.push(`    <priority>${entry.priority}</priority>`);\n  }\n\n  for (const alternate of entry.alternates ?? []) {\n    const href = escapeXml(resolveAgainstBase(baseUrl, alternate.path));\n\n    lines.push(\n      `    <xhtml:link rel=\"alternate\" hreflang=\"${escapeXml(alternate.hreflang)}\" href=\"${href}\"/>`,\n    );\n  }\n\n  lines.push(`  </url>`);\n\n  return lines.join(\"\\n\");\n}\n\n/**\n * Serialises entries into a `urlset` sitemap document — the sitemaps.org\n * namespace, `<url>` per entry, element order `loc` / `lastmod` / `changefreq`\n * / `priority` (schema order; a validator that checks order rejects any other),\n * then any `xhtml:link` alternates.\n *\n * The xhtml namespace is declared only when some entry actually carries an\n * alternate — an unused namespace on every single-language sitemap is noise.\n */\nexport function buildSitemapXml(entries: readonly ResolvedSitemapEntry[], baseUrl: string): string {\n  const hasAlternates = entries.some((entry) => (entry.alternates?.length ?? 0) > 0);\n  const namespaces = hasAlternates ? XHTML_NAMESPACE_ATTR : \"\";\n  const body = entries.map((entry) => renderUrlBlock(entry, baseUrl)).join(\"\\n\");\n\n  return (\n    `<?xml version=\"1.0\" encoding=\"UTF-8\"?>\\n` +\n    `<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\"${namespaces}>\\n` +\n    (body.length > 0 ? `${body}\\n` : \"\") +\n    `</urlset>\\n`\n  );\n}\n"],"mappings":";;;AAGA,MAAM,cAAsC;CAC1C,KAAK;CACL,KAAK;CACL,KAAK;CACL,MAAK;CACL,KAAK;AACP;;AAGA,SAAgB,UAAU,OAAuB;CAK/C,OAAO,MAAM,QAAQ,aAAa,SAAS,YAAY,SAAS,IAAI;AACtE;AAEA,MAAM,kBAAkB;;;;;;AAOxB,MAAa,uBAAuB,iBAAiB,gBAAgB;;;;;;;AAQrE,SAAgB,eAAe,OAA6B,SAAyB;CACnF,MAAM,QAAQ,CAAC,WAAW,YAAY,UAAU,mBAAmB,SAAS,MAAM,IAAI,CAAC,EAAE,OAAO;CAEhG,IAAI,MAAM,YAAY,QACpB,MAAM,KAAK,gBAAgB,UAAU,MAAM,OAAO,EAAE,WAAW;CAGjE,IAAI,MAAM,eAAe,QACvB,MAAM,KAAK,mBAAmB,MAAM,WAAW,cAAc;CAG/D,IAAI,MAAM,aAAa,QACrB,MAAM,KAAK,iBAAiB,MAAM,SAAS,YAAY;CAGzD,KAAK,MAAM,aAAa,MAAM,cAAc,CAAC,GAAG;EAC9C,MAAM,OAAO,UAAU,mBAAmB,SAAS,UAAU,IAAI,CAAC;EAElE,MAAM,KACJ,6CAA6C,UAAU,UAAU,QAAQ,EAAE,UAAU,KAAK,IAC5F;CACF;CAEA,MAAM,KAAK,UAAU;CAErB,OAAO,MAAM,KAAK,IAAI;AACxB;;;;;;;;;;AAWA,SAAgB,gBAAgB,SAA0C,SAAyB;CAEjG,MAAM,aADgB,QAAQ,MAAM,WAAW,MAAM,YAAY,UAAU,KAAK,CACjD,IAAI,uBAAuB;CAC1D,MAAM,OAAO,QAAQ,KAAK,UAAU,eAAe,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI;CAE7E,OACE,sGAC8D,WAAW,QACxE,KAAK,SAAS,IAAI,GAAG,KAAK,MAAM,MACjC;AAEJ"}
+{"version":3,"file":"xml.mjs","names":[],"sources":["../../../../../../sitemap/src/xml.ts"],"sourcesContent":["import type { ResolvedSitemapEntry } from \"./types\";\nimport { resolveAgainstBase } from \"./url\";\n\nconst XML_ESCAPES: Record<string, string> = {\n  \"&\": \"&amp;\",\n  \"<\": \"&lt;\",\n  \">\": \"&gt;\",\n  '\"': \"&quot;\",\n  \"'\": \"&apos;\",\n};\n\n/** Escapes the five XML-significant characters. A URL's query string routinely contains `&`. */\nexport function escapeXml(value: string): string {\n  // The character class and the table are written together, so the lookup can\n  // only miss if one is edited without the other; falling back to the original\n  // character keeps that editing mistake from silently emitting `undefined`\n  // into a URL.\n  return value.replace(/[&<>\"']/g, (char) => XML_ESCAPES[char] ?? char);\n}\n\nconst XHTML_NAMESPACE = \"http://www.w3.org/1999/xhtml\";\nconst IMAGE_NAMESPACE = \"http://www.google.com/schemas/sitemap-image/1.1\";\n\n/**\n * The `xmlns:xhtml` attribute exactly as it appears on `<urlset>`, including\n * its leading space. Exported so the shard writer can charge its byte length\n * against the ceiling without duplicating the string it measures.\n */\nexport const XHTML_NAMESPACE_ATTR = ` xmlns:xhtml=\"${XHTML_NAMESPACE}\"`;\n/** See {@link XHTML_NAMESPACE_ATTR}; measured by the shard writer before roll-over. */\nexport const IMAGE_NAMESPACE_ATTR = ` xmlns:image=\"${IMAGE_NAMESPACE}\"`;\n\n/**\n * Renders one `<url>` block. Exported so the streaming writer can measure the\n * exact bytes it is about to append before deciding whether the byte ceiling\n * forces a new shard — a separate approximation could disagree with what is\n * actually written.\n */\nexport function renderUrlBlock(entry: ResolvedSitemapEntry, baseUrl: string): string {\n  const lines = [`  <url>`, `    <loc>${escapeXml(resolveAgainstBase(baseUrl, entry.path))}</loc>`];\n\n  if (entry.lastmod !== undefined) {\n    lines.push(`    <lastmod>${escapeXml(entry.lastmod)}</lastmod>`);\n  }\n\n  if (entry.changefreq !== undefined) {\n    lines.push(`    <changefreq>${entry.changefreq}</changefreq>`);\n  }\n\n  if (entry.priority !== undefined) {\n    lines.push(`    <priority>${entry.priority}</priority>`);\n  }\n\n  for (const alternate of entry.alternates ?? []) {\n    const href = escapeXml(resolveAgainstBase(baseUrl, alternate.path));\n\n    lines.push(\n      `    <xhtml:link rel=\"alternate\" hreflang=\"${escapeXml(alternate.hreflang)}\" href=\"${href}\"/>`,\n    );\n  }\n\n  for (const image of entry.images ?? []) {\n    lines.push(`    <image:image>`);\n    lines.push(`      <image:loc>${escapeXml(resolveAgainstBase(baseUrl, image.loc))}</image:loc>`);\n    lines.push(`    </image:image>`);\n  }\n\n  lines.push(`  </url>`);\n\n  return lines.join(\"\\n\");\n}\n\n/**\n * Serialises entries into a `urlset` sitemap document — the sitemaps.org\n * namespace, `<url>` per entry, element order `loc` / `lastmod` / `changefreq`\n * / `priority` (schema order; a validator that checks order rejects any other),\n * then any `xhtml:link` alternates.\n *\n * The xhtml namespace is declared only when some entry actually carries an\n * alternate — an unused namespace on every single-language sitemap is noise.\n */\nexport function buildSitemapXml(entries: readonly ResolvedSitemapEntry[], baseUrl: string): string {\n  const hasAlternates = entries.some((entry) => (entry.alternates?.length ?? 0) > 0);\n  const hasImages = entries.some((entry) => (entry.images?.length ?? 0) > 0);\n  const namespaces = `${hasAlternates ? XHTML_NAMESPACE_ATTR : \"\"}${hasImages ? IMAGE_NAMESPACE_ATTR : \"\"}`;\n  const body = entries.map((entry) => renderUrlBlock(entry, baseUrl)).join(\"\\n\");\n\n  return (\n    `<?xml version=\"1.0\" encoding=\"UTF-8\"?>\\n` +\n    `<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\"${namespaces}>\\n` +\n    (body.length > 0 ? `${body}\\n` : \"\") +\n    `</urlset>\\n`\n  );\n}\n"],"mappings":";;;AAGA,MAAM,cAAsC;CAC1C,KAAK;CACL,KAAK;CACL,KAAK;CACL,MAAK;CACL,KAAK;AACP;;AAGA,SAAgB,UAAU,OAAuB;CAK/C,OAAO,MAAM,QAAQ,aAAa,SAAS,YAAY,SAAS,IAAI;AACtE;AAEA,MAAM,kBAAkB;AACxB,MAAM,kBAAkB;;;;;;AAOxB,MAAa,uBAAuB,iBAAiB,gBAAgB;;AAErE,MAAa,uBAAuB,iBAAiB,gBAAgB;;;;;;;AAQrE,SAAgB,eAAe,OAA6B,SAAyB;CACnF,MAAM,QAAQ,CAAC,WAAW,YAAY,UAAU,mBAAmB,SAAS,MAAM,IAAI,CAAC,EAAE,OAAO;CAEhG,IAAI,MAAM,YAAY,QACpB,MAAM,KAAK,gBAAgB,UAAU,MAAM,OAAO,EAAE,WAAW;CAGjE,IAAI,MAAM,eAAe,QACvB,MAAM,KAAK,mBAAmB,MAAM,WAAW,cAAc;CAG/D,IAAI,MAAM,aAAa,QACrB,MAAM,KAAK,iBAAiB,MAAM,SAAS,YAAY;CAGzD,KAAK,MAAM,aAAa,MAAM,cAAc,CAAC,GAAG;EAC9C,MAAM,OAAO,UAAU,mBAAmB,SAAS,UAAU,IAAI,CAAC;EAElE,MAAM,KACJ,6CAA6C,UAAU,UAAU,QAAQ,EAAE,UAAU,KAAK,IAC5F;CACF;CAEA,KAAK,MAAM,SAAS,MAAM,UAAU,CAAC,GAAG;EACtC,MAAM,KAAK,mBAAmB;EAC9B,MAAM,KAAK,oBAAoB,UAAU,mBAAmB,SAAS,MAAM,GAAG,CAAC,EAAE,aAAa;EAC9F,MAAM,KAAK,oBAAoB;CACjC;CAEA,MAAM,KAAK,UAAU;CAErB,OAAO,MAAM,KAAK,IAAI;AACxB;;;;;;;;;;AAWA,SAAgB,gBAAgB,SAA0C,SAAyB;CACjG,MAAM,gBAAgB,QAAQ,MAAM,WAAW,MAAM,YAAY,UAAU,KAAK,CAAC;CACjF,MAAM,YAAY,QAAQ,MAAM,WAAW,MAAM,QAAQ,UAAU,KAAK,CAAC;CACzE,MAAM,aAAa,GAAG,gBAAgB,uBAAuB,KAAK,YAAY,uBAAuB;CACrG,MAAM,OAAO,QAAQ,KAAK,UAAU,eAAe,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI;CAE7E,OACE,sGAC8D,WAAW,QACxE,KAAK,SAAS,IAAI,GAAG,KAAK,MAAM,MACjC;AAEJ"}