@ultimat3/seo 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -16,7 +16,7 @@ Tier 1. May import `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n`. Nothi
   the SHAPE of a check, and it must not be read as a claim that CI fails on one. What is actually
   reached from outside this package is `renderMeta` (through `@ultimat3/render`'s `seoRenderers`),
   `ld.*` (an app's own `meta`), `buildFeed`, and the image contract (`parseImageQuery` /
-  `builtinImageDriver` / `responsiveImage`, through `@ultimat3/cli`'s `dev-assets.ts`).
+  `builtinImageDriver` / `responsiveImage`, through `@ultimat3/cli`'s `runtime-assets.ts`).
   `validateMeta`/`assertMeta`, `buildSitemap`, `buildRobots`, `isIndexable` and
   `indexableRoutes`/`expandRoute` have **no caller anywhere** — no step of `x verify` runs them.
   Wiring them is a `HostCheck` on an existing step in `packages/cli/src/cmd-verify.ts`; until that
@@ -78,6 +78,23 @@ Tier 1. May import `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n`. Nothi
   `head-seo.ts` had to write down that it binds no `renderLd` half on purpose. Deleted
   `As of 2026-08`. Never add it back: an app that found it on the public surface and called it from
   `meta` emitted its graph twice, which is exactly the duplicate that comment was defending against.
+- **`responsiveImage` never mints what its own reader or the default driver refuses.**
+  `usableWidths` caps at `min(intrinsic, MAX_IMAGE_WIDTH)` and keeps whole positive widths only
+  (`?w=10000` was `X_IMAGE_QUERY_INVALID`). `DEFAULT_FORMATS` is `FORMAT_ORDER` filtered through
+  core's `canEncode` — `webp` — because a browser does not fall back from a `<source>` that
+  errors; AVIF is opt-in (`formats: FORMAT_ORDER`) for an app whose driver encodes it.
+  `image-driver.test.ts` runs every default format through `builtinImageDriver`.
+- **`seo.robots.disallow` goes into EVERY group**, and a `*` group is appended when none is
+  declared: a crawler obeys only the group naming it. De-duplicated per group.
+- **The brand test in `applyTitleTemplate` is a WORD match** (`containsWord`, Unicode letters and
+  digits), never `includes`: `Ultimately fast` still gets its brand.
+- **`ogLocaleTag` is `Intl.Locale` language + region** — `zh_TW`, never `zh_Hant_TW`.
+- **Feed authors**: Atom takes `<author>` (name, email, uri), `<rights>`, `<icon>`. An RSS item
+  author is `<author>email (name)</author>` or, with no email, `<dc:creator>`. An item `image` is
+  Atom `<link rel="enclosure">` and RSS `<media:content>` — never RSS `<enclosure>`, which
+  requires a byte length. `xmlns:dc`/`xmlns:media` are declared only when used.
+- **`usableWidths` refuses an intrinsic width that is not a size** — core's `finiteCount`
+  (`X_INVARIANT`) on the floored value, so `NaN`, `Infinity`, `0` and negatives never reach a URL.
 - **`builtinImageDriver({ read })` takes its reader.** `TransformRequest.src` is a string, and
   whether that string is a path, a storage key or a URL is the app's fact, not seo's — never add
   a filesystem fallback. Pixels come from `@ultimat3/core`'s pipeline; seo owns no second scaler,
@@ -97,8 +114,8 @@ Tier 1. May import `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n`. Nothi
   names; that refusal stays `image-driver.ts`'s `X_IMAGE_UNSUPPORTED`, so one bad URL never
   carries two codes.
 - **`xml.ts` drops what XML 1.0 cannot represent, `As of 2026-08-23`.** The C0 controls other than
-  tab, LF and CR, plus U+FFFE and U+FFFF, are removed in `escapeXml`, `escapeAttribute` and
-  `cdata` — so `xmlElement`, `attributes`, every sitemap and every feed inherit it. Dropped and not
+  tab, LF and CR, plus U+FFFE and U+FFFF, are removed in `escapeXml` (core's `escapeHtml` table
+  after the strip — `'` is `&#39;`, valid XML and HTML alike) and `cdata` — so `xmlElement`, `attributes`, every sitemap and every feed inherit it. Dropped and not
   escaped, because there is no escape: `&#1;` is illegal in XML 1.0 for exactly the reason the raw
   byte is. It has to happen in the escaper rather than at each call site, because ONE such byte in
   ONE `FeedItem` title makes the whole document not well-formed and a reader answers with "invalid
@@ -132,7 +149,7 @@ Tier 1. May import `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n`. Nothi
 | `rss.ts` | `buildFeed()` — the three feed formats; owns markup, never a date |
 | `feed-dates.ts` | all timestamp parsing and formatting for feeds. Never `Date.parse` in another module |
 | `images.ts` | what the markup promises: `srcset` widths, `<picture>` order, inlined dimensions — plus `IMAGE_QUERY_KEYS` and `parseImageQuery`, the contract that reads a minted URL back. Decodes nothing |
-| `image-driver.ts` | the bytes behind that promise: `ImageTransformDriver` + `builtinImageDriver({ read })` over core's pipeline — png/jpeg only |
+| `image-driver.ts` | the bytes behind that promise: `ImageTransformDriver` + `builtinImageDriver({ read })` over core's pipeline — encodes png/jpeg/webp |
 
 ## Commands
 

package/README.md

@@ -47,11 +47,11 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `meta.ts` | the metadata model, `renderMeta()` → head tags: title template, canonical, robots, `og:*`, `twitter:*`, hreflang + `x-default`, `theme-color` per colour scheme. **`robots: { index: false }` withdraws every `og:*`, `article:*` and `twitter:*` tag** — declared or derived; there is no `social` switch |
 | `validate.ts` | the build gate — `validateMeta()` (`--json`-shaped) and `assertMeta()` |
 | `ld.ts` | typed JSON-LD builders; required fields are required in the **input type** |
-| `sitemap.ts` | `buildSitemap()` from the route table + each route's `prerender()`, per-locale alternates, automatic index splitting past 50k |
-| `robots.ts` | `buildRobots()`, environment-aware and fail-closed |
-| `rss.ts` | `buildFeed()` → RSS 2.0 + Atom + JSON Feed from one item list |
+| `sitemap.ts` | `buildSitemap()` from the route table + each route's `prerender()`, per-locale alternates, automatic index splitting past 50k — the index stays `/sitemap.xml`, the parts are `/sitemaps/<n>.xml` (`SITEMAP_PARTS_DIR`) |
+| `robots.ts` | `buildRobots()`, environment-aware and fail-closed; `disallow` reaches **every** group, and a `User-agent: *` group is emitted for it when none is declared |
+| `rss.ts` | `buildFeed()` → RSS 2.0 + Atom + JSON Feed from one item list. Channel `author`/`copyright`/`icon` → Atom `<author>`/`<rights>`/`<icon>`; an item `author` → Atom `<author>`, RSS `<author>` when it has an email, `<dc:creator>` when it does not; an item `image` → Atom `<link rel="enclosure">`, RSS `<media:content medium="image">`. Extra RSS namespaces are declared only when used |
 | `feed-dates.ts` | the one place a feed timestamp is parsed or formatted — an item date that will not parse is *absent*, never `Invalid Date` and never a crash |
-| `images.ts` | `srcset` widths, AVIF → WebP → original, inlined intrinsic dimensions, and `parseImageQuery()` — reads a minted URL back into a transform request |
+| `images.ts` | `srcset` widths (never past the intrinsic width or `MAX_IMAGE_WIDTH`, 8192), modern formats before the original — `DEFAULT_FORMATS` is what the built-in driver encodes (`webp`); pass `formats: FORMAT_ORDER` for AVIF behind a CDN driver — inlined intrinsic dimensions, and `parseImageQuery()` — reads a minted URL back into a transform request |
 | `image-driver.ts` | `ImageTransformDriver` + `builtinImageDriver()`: the variant bytes and the blur placeholder |
 
 ## Type-level enforcement
@@ -88,27 +88,32 @@ const images = builtinImageDriver({ read: (src) => Bun.file(`public${src}`).byte
 
 // a 1200x630 source
 await images.transform({ src: '/img/hero.png', width: 640 });
-// → { bytes, contentType: 'image/jpeg', width: 640, height: 336 }
+// → { bytes, contentType: 'image/png', width: 640, height: 336 }
 await images.blurPlaceholder('/img/hero.png');
 // → 'data:image/png;base64,…'
 ```
 
 | | |
 |---|---|
-| decodes | `png`, `jpeg` |
-| encodes | `png`, `jpeg` |
-| probes only | `webp`, `avif`, `gif`, `svg` — intrinsic size, never a transform |
+| decodes | `png`, `jpeg`, `webp`, `gif` |
+| encodes | `png`, `jpeg`, `webp` |
+| probes only | `avif`, `svg` — intrinsic size, never a transform |
+
+The two lists are `@ultimat3/core`'s `DECODABLE_FORMATS` and `ENCODABLE_FORMATS`
+(`packages/core/src/image/pipeline.ts`), `As of 2026-10`.
 
 - **`read` is required.** `src` is a string and only the app knows whether it is a path, a
   storage key or a URL. Guessing would mean a filesystem read off a URL-shaped string.
-- **No `format` → the pixels decide:** PNG when the raster has alpha, JPEG otherwise. A logo
-  never grows a black background because nobody passed a format.
-- **`format: 'avif'` or `'webp'` → `X_IMAGE_UNSUPPORTED`,** with the fix line. Those `<source>`
-  entries need a CDN driver; the framework will not pretend to encode what it cannot.
+- **No `format` → the source's format is kept** when the pipeline can write it, PNG otherwise. A
+  logo never grows a black background because nobody passed a format.
+- **`format: 'avif'` → `X_IMAGE_UNSUPPORTED`,** with the fix line. That `<source>` needs a CDN
+  driver, so `responsiveImage()` does not offer it unless asked (`formats: FORMAT_ORDER`): a
+  browser picks the first `<source>` it supports and does not fall back from an error.
 - **`width`/`height` are probed off the output bytes,** never echoed from the request. A width
   above the intrinsic one clamps to the source and reports the source's size, so the box the
   browser reserves is the box the bytes fill.
-- `blurPlaceholder()` returns a 16px-wide PNG `data:` URI, ready for `ImageInput.blurDataUrl`.
+- `blurPlaceholder()` returns a PNG `data:` URI at most 32px on its long edge, ready for
+  `ImageInput.blurDataUrl`.
 
 ### Reading the URL back
 
@@ -156,7 +161,7 @@ export const config = defineRoute({
     alternates: post.locales.map((l) => ({ hreflang: l, href: `/${l}/blog/${post.slug}` })),
     ld: [ld.Article({ headline: post.title, datePublished: post.publishedAt, author: post.author })],
   }),
-  budget: { js: '0kb', lcp: 2000 },
+  budget: { js: '0kb' },
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/seo",
-  "version": "23.0.0",
+  "version": "25.0.0",
   "description": "Enforced SEO: typed meta, JSON-LD, sitemap, robots, feeds, responsive images, perf budgets",
   "license": "MIT",
   "type": "module",
@@ -25,14 +25,14 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.0"
+    "bun": ">=1.4.2"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "23.0.0",
-    "@ultimat3/schema": "23.0.0"
+    "@ultimat3/core": "25.0.0",
+    "@ultimat3/schema": "25.0.0"
   }
 }

package/src/errors.ts

@@ -3,7 +3,7 @@
 // of 2026-08`, is a build gate: no step of `x verify` calls the asserts that throw them (see
 // `README.md`), so they fail the app that calls one itself and nothing else.
 
-import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+import { NotImplementedError, registerErrorCodes, UltimateError } from '@ultimat3/core';
 // errors.ts <-> images.ts: images.ts throws imageQueryInvalid() and this file spells its fix
 // using images.ts's IMAGE_QUERY_KEYS. Safe like core's errors.ts <-> error-codes.ts cycle:
 // nothing at this module's top level reads the import, only the factory body below does, and by
@@ -29,7 +29,9 @@ export type SeoErrorCode = (typeof SEO_ERROR_CODES)[keyof typeof SEO_ERROR_CODES
  * deliberately not among them: `@ultimat3/render` owns `X_BUDGET_EXCEEDED` and `@ultimat3/cli`'s
  * `checkBudgets` is the gate that throws it, so seo naming the same condition was a second code
  * for one fault whose only thrower was its own test. `errors.test.ts` pins the set.
- * `X_NOT_IMPLEMENTED` and `X_IMAGE_UNSUPPORTED` are core's; `SeoError` throws them, untitled here.
+ * `X_NOT_IMPLEMENTED` is core's, and so is its one constructor: `notImplementedDriver` below builds
+ * core's `NotImplementedError`, never a `SeoError` carrying the code. `X_IMAGE_UNSUPPORTED` is
+ * core's codec's, untitled here.
  */
 registerErrorCodes({
   X_SEO_META_MISSING: { title: 'a site/ route is missing required metadata' },
@@ -43,7 +45,7 @@ registerErrorCodes({
 });
 
 export interface SeoErrorInit {
-  readonly code: SeoErrorCode | 'X_NOT_IMPLEMENTED';
+  readonly code: SeoErrorCode;
   readonly cause: string;
   readonly fix: string;
   readonly meta?: Readonly<Record<string, unknown>>;
@@ -180,9 +182,12 @@ export function imageQueryInvalid(param: string, value: string, reason: string):
  * `at` is the driver's own module path — pass `import.meta.path`. It is required because
  * `driver` is a display name, and a fix an agent cannot open is not a fix.
  */
-export function notImplementedDriver(driver: string, capability: string, at: string): SeoError {
-  return new SeoError({
-    code: 'X_NOT_IMPLEMENTED',
+export function notImplementedDriver(
+  driver: string,
+  capability: string,
+  at: string,
+): NotImplementedError {
+  return new NotImplementedError({
     cause: `the ${driver} image driver does not implement ${capability} yet`,
     fix:
       `implement ${capability} in ${at}, or swap the driver for builtinImageDriver({ read }) ` +

package/src/image-driver.ts

@@ -61,8 +61,8 @@ function requestedFormat(format: string | undefined): ImageFormat | undefined {
 
 /**
  * The zero-dependency pipeline in `@ultimat3/core`: PNG, JPEG, WebP and GIF in, PNG, JPEG and
- * WebP out. `<picture>` still offers AVIF, and nothing here synthesises it — asking for one
- * raises core's `X_IMAGE_UNSUPPORTED`, and that variant belongs on a CDN driver instead.
+ * WebP out. Nothing here synthesises AVIF — asking for one raises core's `X_IMAGE_UNSUPPORTED` —
+ * which is why `images.ts`'s `DEFAULT_FORMATS` does not offer it; that variant is a CDN driver's.
  */
 export function builtinImageDriver(options: BuiltinImageDriverOptions): ImageTransformDriver {
   return {

package/src/images.ts

@@ -3,17 +3,31 @@
 // so the browser reserves the box before the bytes arrive, keeping CLS at 0. Producing those
 // bytes is `image-driver.ts`; nothing here decodes a pixel.
 
+import { canEncode, finiteCount } from '@ultimat3/core';
 import { imageQueryInvalid } from './errors';
-import { attributes, escapeAttribute } from './xml';
+import { attributes, escapeXml } from './xml';
 
 /** Ordered widest-first is wrong for `srcset`; browsers want ascending. */
 export const DEFAULT_WIDTHS: readonly number[] = [320, 480, 640, 768, 1024, 1280, 1536, 1920];
 
-/** Most-preferred first. The original format is always appended last. */
+/** Every modern format the markup can offer, most-preferred first. The original comes last. */
 export const FORMAT_ORDER = ['avif', 'webp'] as const;
 
 export type ModernFormat = (typeof FORMAT_ORDER)[number];
 
+/**
+ * What `responsiveImage` offers when the caller names no `formats`: the part of `FORMAT_ORDER`
+ * the built-in pipeline can ENCODE, read off core's own capability list so the two cannot drift.
+ *
+ * A `<source>` is a promise the browser does not hedge: it picks the first type it supports and
+ * never falls back from an error response. Offering AVIF by default made that pick a URL the
+ * default driver answers with `X_IMAGE_UNSUPPORTED`. An app whose driver does encode AVIF — a
+ * CDN — says so: `responsiveImage(input, { formats: FORMAT_ORDER })`.
+ */
+export const DEFAULT_FORMATS: readonly ModernFormat[] = FORMAT_ORDER.filter((format) =>
+  canEncode(format),
+);
+
 export const MIME_TYPES: Readonly<Record<string, string>> = {
   avif: 'image/avif',
   webp: 'image/webp',
@@ -124,7 +138,7 @@ function parseQuality(raw: string): number {
  * Hard, not configurable: the shape `packages/mcp/src/query-limits.ts:48-56` uses — a caller may
  * narrow a request by asking for less, never widen it by asking for more.
  */
-const MAX_IMAGE_WIDTH = 8192;
+export const MAX_IMAGE_WIDTH = 8192;
 
 function parseWidth(raw: string): number {
   const width = parsePositiveInt(IMAGE_QUERY_KEYS.width, raw);
@@ -165,11 +179,22 @@ export function parseImageQuery(params: URLSearchParams): ImageQuery | null {
   };
 }
 
-/** Never upscale: drop candidate widths above the intrinsic width. */
+/**
+ * Never upscale, and never mint what `parseImageQuery` refuses: candidates are whole pixel counts
+ * from 1 to the intrinsic width or `MAX_IMAGE_WIDTH`, whichever is smaller, and that cap closes
+ * the list. A 10,000-wide source used to put `?w=10000` in its own `srcset` — the widest
+ * candidate, the one a large display picks, answered `X_IMAGE_QUERY_INVALID`.
+ *
+ * The intrinsic width is floored (an SVG may measure a fraction) and then has to BE a size: `NaN`
+ * fails every comparison below, so it came back as the only candidate and went out as `?w=NaN`.
+ */
 export function usableWidths(intrinsic: number, widths: readonly number[]): readonly number[] {
-  const usable = widths.filter((width) => width <= intrinsic);
-  if (usable.length === 0) return [intrinsic];
-  return usable.includes(intrinsic) ? usable : [...usable, intrinsic];
+  const cap = Math.min(
+    finiteCount('usableWidths', 'intrinsic', Math.floor(intrinsic), 1),
+    MAX_IMAGE_WIDTH,
+  );
+  const usable = widths.filter((width) => Number.isInteger(width) && width >= 1 && width <= cap);
+  return usable.includes(cap) ? usable : [...usable, cap];
 }
 
 /** The widest candidate, or `undefined` for an empty list — never `Math.max()`'s `-Infinity`. */
@@ -198,7 +223,7 @@ export function responsiveImage(
   const urlFor = options.urlFor ?? defaultUrlFor;
   const widths = usableWidths(input.width, options.widths ?? DEFAULT_WIDTHS);
   const sizes = input.sizes ?? '100vw';
-  const formats = options.formats ?? FORMAT_ORDER;
+  const formats = options.formats ?? DEFAULT_FORMATS;
 
   const sources: ImageSourceSet[] = formats.map((format) => ({
     // `Object.hasOwn`, never a bare index: `MIME_TYPES` is a `{}`-prototyped literal, so an
@@ -238,7 +263,7 @@ export function responsiveImage(
   };
 }
 
-/** `<picture>` with AVIF, then WebP, then the original. */
+/** `<picture>`: each offered modern format in order, then the original as the `<img>`. */
 export function renderPicture(image: ResponsiveImage): string {
   const sources = image.sources
     .map(
@@ -263,5 +288,5 @@ export function renderPicture(image: ResponsiveImage): string {
 
 /** Escapes a data URI for inline `style`, for callers assembling their own tags. */
 export function inlineBlur(dataUrl: string): string {
-  return escapeAttribute(`background-image:url(${dataUrl});background-size:cover`);
+  return escapeXml(`background-image:url(${dataUrl});background-size:cover`);
 }

package/src/index.ts

@@ -31,10 +31,12 @@ export type {
   ResponsiveImageOptions,
 } from './images';
 export {
+  DEFAULT_FORMATS,
   DEFAULT_WIDTHS,
   FORMAT_ORDER,
   IMAGE_QUERY_KEYS,
   inlineBlur,
+  MAX_IMAGE_WIDTH,
   MIME_TYPES,
   parseImageQuery,
   renderPicture,
@@ -113,9 +115,9 @@ export {
   chunk,
   SITEMAP_INDEX_MAX_FILES,
   SITEMAP_MAX_URLS,
+  SITEMAP_PARTS_DIR,
   sitemapUrls,
 } from './sitemap';
 export type { MetaIssue, MetaValidationReport, ValidateMetaOptions } from './validate';
 export { assertMeta, validateMeta } from './validate';
-
-export { absoluteUrl, escapeAttribute, escapeXml } from './xml';
+export { absoluteUrl, escapeXml } from './xml';

package/src/locale-tags.ts

@@ -15,9 +15,18 @@ export function hreflangTag(locale: string): string {
   }
 }
 
-/** `es-co` → `es_CO`: Open Graph's `language_TERRITORY`. */
+/**
+ * `es-co` → `es_CO`, `zh-hant-tw` → `zh_TW`: Open Graph's `language_TERRITORY`, which has no slot
+ * for a script, a variant or an extension. Replacing hyphens in the BCP 47 tag produced
+ * `zh_Hant_TW`, a value no consumer recognises. Total, for `hreflangTag`'s reason.
+ */
 export function ogLocaleTag(locale: string): string {
-  return hreflangTag(locale).replace(/-/g, '_');
+  try {
+    const { language, region } = new Intl.Locale(locale);
+    return region === undefined ? language : `${language}_${region}`;
+  } catch {
+    return locale.replace(/-/g, '_');
+  }
 }
 
 /** A page in one locale: the locale and the page's own path in it. */

package/src/meta.ts

@@ -143,6 +143,28 @@ export function localizedAlternates(
  */
 const TEMPLATE_SEPARATORS = /^[\s\-–—|·:>/]+|[\s\-–—|·:>/]+$/g;
 
+const WORD_CHARACTER = /[\p{L}\p{N}]/u;
+
+const isWordCharacter = (char: string | undefined): boolean =>
+  char !== undefined && WORD_CHARACTER.test(char);
+
+/**
+ * `word` standing alone in `text`: `\b`, but for every script. `'Ultimately fast'.includes(
+ * 'Ultimate')` is true, so that page shipped with no brand at all. A side of the word that is not
+ * itself a letter or digit (`C++`) needs no boundary, exactly as `\b` would not find one there.
+ */
+function containsWord(text: string, word: string): boolean {
+  const [first, last] = [[...word][0], [...word].at(-1)];
+  for (let at = text.indexOf(word); at !== -1; at = text.indexOf(word, at + 1)) {
+    const before = [...text.slice(0, at)].at(-1);
+    const after = [...text.slice(at + word.length)][0];
+    const opens = !isWordCharacter(first) || !isWordCharacter(before);
+    const closes = !isWordCharacter(last) || !isWordCharacter(after);
+    if (opens && closes) return true;
+  }
+  return false;
+}
+
 /** Where the page's own title goes. Case-sensitive: `%S` names no slot, and neither does absence. */
 export const TITLE_SLOT = '%s';
 
@@ -159,7 +181,7 @@ export function applyTitleTemplate(title: string, template?: string): string {
   // can name the file.
   if (!template.includes(TITLE_SLOT)) return title;
   const brand = template.replace(TITLE_SLOT, '').replace(TEMPLATE_SEPARATORS, '');
-  if (brand !== '' && title.includes(brand)) return title;
+  if (brand !== '' && containsWord(title, brand)) return title;
   // A FUNCTION as the replacement, never the string: `replace` expands `$$`, `$&` and `$'` in a
   // replacement literal, and a title is app data — "Save $$ on shoes" rendered one dollar.
   return template.replace(TITLE_SLOT, () => title);

package/src/robots.ts

@@ -19,9 +19,9 @@ export interface RobotsConfig {
   environment?: Environment | undefined;
   groups?: readonly RobotsGroup[];
   /**
-   * Paths every crawler is kept out of — `app.config.ts`'s `seo.robots.disallow`. Added to the
-   * default `User-agent: *` group, or to each declared group that names `*`. Production only: a
-   * non-production `robots.txt` already disallows everything.
+   * Paths every crawler is kept out of — `app.config.ts`'s `seo.robots.disallow`. Added to EVERY
+   * group, and a `User-agent: *` group is emitted to carry it when none is declared. Production
+   * only: a non-production `robots.txt` already disallows everything.
    */
   disallow?: readonly string[];
   /** Sitemap paths or absolute URLs. Only emitted in production. */
@@ -67,12 +67,19 @@ export function buildRobots(config: RobotsConfig): string {
     config.groups === undefined || config.groups.length === 0
       ? [{ userAgent: '*', allow: ['/'] }]
       : config.groups;
+  // A crawler obeys the ONE group that names it most specifically and never reads `*` beside it,
+  // so "every crawler" means every group. Appending to `*` alone left the list out of exactly
+  // the groups an app had written for a named crawler — and out of the file when no group named `*`.
   const extra = config.disallow ?? [];
-  const groups = declared.map((group) =>
-    extra.length === 0 || !agents(group.userAgent).includes('*')
-      ? group
-      : { ...group, disallow: [...(group.disallow ?? []), ...extra] },
-  );
+  const everywhere = declared.map((group) => ({
+    ...group,
+    disallow: [...new Set([...(group.disallow ?? []), ...extra])],
+  }));
+  const namesEveryone = declared.some((group) => agents(group.userAgent).includes('*'));
+  const groups: readonly RobotsGroup[] =
+    extra.length === 0 || namesEveryone
+      ? everywhere
+      : [...everywhere, { userAgent: '*', disallow: extra }];
 
   for (const group of groups) {
     for (const agent of agents(group.userAgent)) lines.push(`User-agent: ${agent}`);

package/src/rss.ts

@@ -84,8 +84,33 @@ function byNewest(a: DatedItem, b: DatedItem): number {
   return b.published - a.published;
 }
 
+/** Atom's person construct (RFC 4287 §3.2): a name, and whichever of email and uri is known. */
+function atomAuthor(author: FeedAuthor): string {
+  const email = author.email === undefined ? '' : xmlElement('email', author.email);
+  const uri = author.url === undefined ? '' : xmlElement('uri', author.url);
+  return `<author>${xmlElement('name', author.name)}${email}${uri}</author>`;
+}
+
+/** RSS 2.0's `<author>` IS an e-mail address; a name with none is Dublin Core's `dc:creator`. */
+const needsCreator = (author: FeedAuthor | undefined): author is FeedAuthor =>
+  author !== undefined && author.email === undefined;
+
+function rssAuthor(author: FeedAuthor): string {
+  return author.email === undefined
+    ? xmlElement('dc:creator', author.name)
+    : xmlElement('author', `${author.email} (${author.name})`);
+}
+
 function buildRss(channel: FeedChannel, items: readonly DatedItem[], updated: number): string {
   const self = absoluteUrl(channel.siteUrl, channel.feedUrl);
+  // Declared only when used: a namespace on every feed would change bytes no reader asked for.
+  const dublinCore = items.some(({ item }) => needsCreator(item.author))
+    ? ' xmlns:dc="http://purl.org/dc/elements/1.1/"'
+    : '';
+  // Media RSS, not `<enclosure>`: RSS 2.0 requires a byte `length` there and nothing here has one.
+  const media = items.some(({ item }) => item.image !== undefined)
+    ? ' xmlns:media="http://search.yahoo.com/mrss/"'
+    : '';
   const entries = items
     .map(({ item, published }) => {
       const parts = [
@@ -94,18 +119,23 @@ function buildRss(channel: FeedChannel, items: readonly DatedItem[], updated: nu
         `      <guid isPermaLink="false">${escapeXml(item.id)}</guid>`,
       ];
       if (published !== undefined) parts.push(xmlElement('pubDate', rfc822Of(published)));
+      if (item.author !== undefined) parts.push(rssAuthor(item.author));
       if (item.summary !== undefined) parts.push(xmlElement('description', item.summary));
       if (item.contentHtml !== undefined) {
         parts.push(`      <content:encoded>${cdata(item.contentHtml)}</content:encoded>`);
       }
       for (const tag of item.tags ?? []) parts.push(xmlElement('category', tag));
+      if (item.image !== undefined) {
+        const url = escapeXml(absoluteUrl(channel.siteUrl, item.image));
+        parts.push(`      <media:content url="${url}" medium="image"/>`);
+      }
       return `    <item>\n${parts.map((line) => (line.startsWith('      ') ? line : `      ${line}`)).join('\n')}\n    </item>`;
     })
     .join('\n');
 
   return [
     '<?xml version="1.0" encoding="UTF-8"?>',
-    '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/">',
+    `<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"${dublinCore}${media}>`,
     '  <channel>',
     `    ${xmlElement('title', channel.title)}`,
     `    ${xmlElement('link', channel.siteUrl)}`,
@@ -142,29 +172,43 @@ function buildAtom(channel: FeedChannel, items: readonly DatedItem[], updated: n
       if (item.contentHtml !== undefined) {
         parts.push(`      <content type="html">${escapeXml(item.contentHtml)}</content>`);
       }
-      if (item.author !== undefined) {
-        parts.push(`      <author>${xmlElement('name', item.author.name)}</author>`);
-      }
+      if (item.author !== undefined) parts.push(`      ${atomAuthor(item.author)}`);
       for (const tag of item.tags ?? []) {
         parts.push(`      <category term="${escapeXml(tag)}"/>`);
       }
+      if (item.image !== undefined) {
+        const href = escapeXml(absoluteUrl(channel.siteUrl, item.image));
+        parts.push(`      <link rel="enclosure" href="${href}"/>`);
+      }
       return `    <entry>\n${parts.join('\n')}\n    </entry>`;
     })
     .join('\n');
 
-  return [
-    '<?xml version="1.0" encoding="UTF-8"?>',
-    `<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="${escapeXml(channel.language)}">`,
-    `  ${xmlElement('title', channel.title)}`,
-    `  ${xmlElement('subtitle', channel.description)}`,
-    `  ${xmlElement('id', channel.siteUrl)}`,
-    `  ${xmlElement('updated', isoOf(updated))}`,
-    `  <link href="${escapeXml(channel.siteUrl)}"/>`,
-    `  <link href="${escapeXml(self)}" rel="self" type="application/atom+xml"/>`,
-    entries,
-    '</feed>',
-    '',
-  ].join('\n');
+  return (
+    [
+      '<?xml version="1.0" encoding="UTF-8"?>',
+      `<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="${escapeXml(channel.language)}">`,
+      `  ${xmlElement('title', channel.title)}`,
+      `  ${xmlElement('subtitle', channel.description)}`,
+      `  ${xmlElement('id', channel.siteUrl)}`,
+      `  ${xmlElement('updated', isoOf(updated))}`,
+      `  <link href="${escapeXml(channel.siteUrl)}"/>`,
+      `  <link href="${escapeXml(self)}" rel="self" type="application/atom+xml"/>`,
+      // RFC 4287 §4.1.1: a feed carries an author unless every entry does. The channel's was read
+      // by the JSON builder alone, so an Atom feed with authorless entries was not a valid one.
+      channel.author === undefined ? '' : `  ${atomAuthor(channel.author)}`,
+      channel.copyright === undefined ? '' : `  ${xmlElement('rights', channel.copyright)}`,
+      channel.icon === undefined
+        ? ''
+        : `  ${xmlElement('icon', absoluteUrl(channel.siteUrl, channel.icon))}`,
+      entries,
+      '</feed>',
+      '',
+    ]
+      // The trailing '' is the document's final newline; only an absent optional line is dropped.
+      .filter((line, index, lines) => line !== '' || index === lines.length - 1)
+      .join('\n')
+  );
 }
 
 function buildJsonFeed(channel: FeedChannel, items: readonly DatedItem[]): string {

package/src/sitemap.ts

@@ -12,6 +12,13 @@ import { absoluteUrl, attributes, escapeXml } from './xml';
 export const SITEMAP_MAX_URLS = 50_000;
 export const SITEMAP_INDEX_MAX_FILES = 50_000;
 
+/**
+ * Where the parts of a split sitemap live: `/sitemaps/1.xml`, `/sitemaps/2.xml`, … — one directory,
+ * so a running server answers every part from ONE route (`/sitemaps/:file`). `/sitemap-N.xml` needed
+ * a parameter inside a segment, which no router here has, and every part 404'd from the web role.
+ */
+export const SITEMAP_PARTS_DIR = '/sitemaps';
+
 export interface SitemapAlternate {
   hreflang: string;
   href: string;
@@ -26,7 +33,7 @@ export interface SitemapUrl {
 }
 
 export interface SitemapFile {
-  /** Path relative to the site root, e.g. `/sitemap-1.xml`. */
+  /** Path relative to the site root: `/sitemap.xml`, or a part, `/sitemaps/1.xml`. */
   path: string;
   xml: string;
   urlCount: number;
@@ -214,7 +221,7 @@ export async function buildSitemap(
   }
 
   const files: SitemapFile[] = groups.map((group, position) => ({
-    path: `/sitemap-${position + 1}.xml`,
+    path: `${SITEMAP_PARTS_DIR}/${position + 1}.xml`,
     xml: renderUrlSet(group),
     urlCount: group.length,
   }));

package/src/xml.ts

@@ -1,13 +1,8 @@
-// XML/HTML escaping and tag emission. One implementation, because a sitemap, a
-// feed, and a <head> tag all fail the same way on an unescaped ampersand.
+// XML/HTML escaping and tag emission. The character table is `@ultimat3/core`'s `escapeHtml`; this
+// file adds only what XML needs on top of it — the characters XML cannot carry at all — because a
+// sitemap, a feed and a <head> tag all fail the same way on an unescaped ampersand.
 
-const XML_ESCAPES: Readonly<Record<string, string>> = {
-  '&': '&amp;',
-  '<': '&lt;',
-  '>': '&gt;',
-  '"': '&quot;',
-  "'": '&apos;',
-};
+import { escapeHtml } from '@ultimat3/core';
 
 /**
  * The characters XML 1.0 excludes from `Char`: the C0 controls other than tab, LF and CR, and the
@@ -29,13 +24,13 @@ const ILLEGAL_XML = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]/g;
 /** Never a surrogate range: an astral character is a legal PAIR, and half of one is worse. */
 const legal = (value: string): string => value.replace(ILLEGAL_XML, '');
 
+/**
+ * Element text and attribute values alike: the XML-illegal characters dropped, then core's one
+ * character table. `&#39;` is a numeric reference, so the same output is well-formed XML and valid
+ * HTML — which is why the `<head>` tags and `<picture>` markup this package writes use it too.
+ */
 export function escapeXml(value: string): string {
-  return legal(value).replace(/[&<>"']/g, (char) => XML_ESCAPES[char] ?? char);
-}
-
-/** Attribute values only ever need these three; apostrophes stay readable. */
-export function escapeAttribute(value: string): string {
-  return legal(value).replace(/[&<>"]/g, (char) => XML_ESCAPES[char] ?? char);
+  return escapeHtml(legal(value));
 }
 
 export function xmlElement(name: string, text: string): string {
@@ -49,7 +44,7 @@ export function cdata(value: string): string {
 
 export function attributes(attrs: Readonly<Record<string, string>>): string {
   return Object.entries(attrs)
-    .map(([key, value]) => ` ${key}="${escapeAttribute(value)}"`)
+    .map(([key, value]) => ` ${key}="${escapeXml(value)}"`)
     .join('');
 }