@ultimat3/seo 6.0.0 → 8.0.0

package/CLAUDE.md

@@ -39,6 +39,13 @@ Tier 1. May import `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n`. Nothi
   because `DEFAULT_WIDTHS` happens to ascend — `widths: [1200, 640]` handed every browser without
   `srcset` support the 640 variant of a 1200-wide image. Never re-derive it from position, and
   never sort inside `usableWidths`: the `srcset` order is the caller's to choose.
+- **`x-default` names a URL the sitemap CONTAINS, or it is not emitted.** `buildSitemap` pushed
+  the unprefixed `path` for every route with `locales` set — and with no `defaultLocale`,
+  `localize` prefixes every locale, so the whole hreflang cluster pointed at a URL the sitemap
+  never lists. A dangling `x-default` is the shape a search engine drops the entire cluster for,
+  which costs the alternates that WERE right. `defaultLocaleUrl` answers `undefined` unless the
+  default locale's own URL is among the ones this route emits — the same explicit-fallback shape
+  `meta.ts`'s `hreflangSet` takes. Never re-derive it from `path`.
 - **Errors name the file, not the URL.** `RouteRecord.file` is in every cause and every fix; an agent must be able to open the source without guessing.
 - **Fail closed, and core reads the key.** `isIndexable()` is `environment === 'production'` and
   nothing else — `staging`, a laptop, a typo and an unset variable all disallow. `ULTIMATE_ENV` has

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/seo",
-  "version": "6.0.0",
+  "version": "8.0.0",
   "description": "Enforced SEO: typed meta, JSON-LD, sitemap, robots, feeds, responsive images, perf budgets",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "6.0.0"
+    "@ultimat3/core": "8.0.0"
   }
 }

package/src/index.ts

@@ -1,5 +1,6 @@
 // The public surface of @ultimat3/seo. Explicit named exports only.
 
+export type { RenderMode } from '@ultimat3/core';
 export type { SeoErrorCode, SeoErrorInit } from './errors';
 export {
   canonicalMismatch,
@@ -90,7 +91,7 @@ export {
 } from './meta';
 export type { RobotsConfig, RobotsGroup } from './robots';
 export { buildRobots, isIndexable } from './robots';
-export type { ChangeFreq, RenderMode, RouteRecord, Surface } from './routes';
+export type { ChangeFreq, RouteRecord, Surface } from './routes';
 export { expandRoute, indexableRoutes, isDynamic } from './routes';
 export type { BuildFeedOptions, Feed, FeedAuthor, FeedChannel, FeedItem } from './rss';
 export { buildFeed } from './rss';

package/src/routes.ts

@@ -2,10 +2,9 @@
 // `x.manifest.json`; every checker here reports against `file`, so an agent can
 // open the exact source rather than guess which route a URL came from.
 
+import type { RenderMode } from '@ultimat3/core';
 import type { RouteMeta } from './meta';
 
-export type RenderMode = 'static' | 'isr' | 'ssr' | 'stream';
-
 /** `site/` is the only surface SEO applies to; `app/` is behind auth. */
 export type Surface = 'site' | 'app' | 'api';
 

package/src/sitemap.ts

@@ -44,7 +44,10 @@ export interface BuildSitemapOptions {
   locales?: readonly string[];
   /** Defaults to `/{locale}{path}`. */
   localizePath?: (path: string, locale: string) => string;
-  /** The locale whose URLs are unprefixed and become `x-default`. */
+  /**
+   * The locale whose URLs are unprefixed and become `x-default`. **Omitted, no `x-default` is
+   * emitted at all** — there is no unprefixed URL in the sitemap for it to name.
+   */
   defaultLocale?: string;
   maxUrls?: number;
   lastmod?: string;
@@ -56,6 +59,24 @@ function localize(path: string, locale: string, options: BuildSitemapOptions): s
   return fn(path, locale);
 }
 
+/**
+ * The path `x-default` may point at: the default locale's own, and only when this route emits it.
+ * `undefined` when no `defaultLocale` was declared, or when it names a locale outside `locales` —
+ * in both cases the URL it would carry is one the sitemap does not contain.
+ *
+ * Matched on the LOCALE, never on the path. Recomputing the default's URL and asking whether any
+ * entry carries it made a `localizePath` that maps two locales onto one URL answer yes for a
+ * `defaultLocale` outside `locales`: the href existed, but it belonged to another locale, so
+ * `x-default` spoke for a locale this cluster does not carry. The entry that emits it is the only
+ * thing that can prove it exists, so read the answer off that entry.
+ */
+function defaultLocaleUrl(
+  localised: readonly { readonly locale: string; readonly path: string }[],
+  options: BuildSitemapOptions,
+): string | undefined {
+  return localised.find((entry) => entry.locale === options.defaultLocale)?.path;
+}
+
 /** Every concrete URL the route table produces, with per-locale alternates. */
 export async function sitemapUrls(
   routes: readonly RouteRecord[],
@@ -66,23 +87,33 @@ export async function sitemapUrls(
 
   for (const route of indexableRoutes(routes)) {
     for (const path of await expandRoute(route)) {
-      const alternates: SitemapAlternate[] = locales.map((locale) => ({
-        hreflang: locale,
-        href: absoluteUrl(options.baseUrl, localize(path, locale, options)),
+      // Localised once, then read three times — the alternates, the `x-default` candidate and the
+      // `<loc>`s below are three questions with one answer, and they drifted apart when each
+      // computed its own.
+      const localised = locales.map((locale) => ({
+        locale,
+        path: localize(path, locale, options),
       }));
-      if (alternates.length > 0) {
-        alternates.push({
-          hreflang: 'x-default',
-          href: absoluteUrl(options.baseUrl, path),
-        });
+      const alternates: SitemapAlternate[] = localised.map((entry) => ({
+        hreflang: entry.locale,
+        href: absoluteUrl(options.baseUrl, entry.path),
+      }));
+      // `x-default` only when it names a URL THIS sitemap lists. It was the bare `path` for every
+      // route: with `locales` set and no `defaultLocale`, every `<loc>` is prefixed and the
+      // unprefixed path is one the sitemap never mentions — an hreflang cluster pointing at a URL
+      // outside itself, which is the shape a search engine drops the whole cluster for. Same rule
+      // as `meta.ts`'s `hreflangSet`, which takes the fallback href explicitly rather than
+      // assuming one exists.
+      const fallback = defaultLocaleUrl(localised, options);
+      if (alternates.length > 0 && fallback !== undefined) {
+        alternates.push({ hreflang: 'x-default', href: absoluteUrl(options.baseUrl, fallback) });
       }
 
       const lastmod = route.lastmod ?? options.lastmod;
-      const emitFor =
-        locales.length === 0 ? [path] : locales.map((l) => localize(path, l, options));
-      for (const localised of emitFor) {
+      const emitFor = locales.length === 0 ? [path] : localised.map((entry) => entry.path);
+      for (const emitted of emitFor) {
         urls.push({
-          loc: absoluteUrl(options.baseUrl, localised),
+          loc: absoluteUrl(options.baseUrl, emitted),
           ...(lastmod === undefined ? {} : { lastmod }),
           ...(route.changefreq === undefined ? {} : { changefreq: route.changefreq }),
           ...(route.priority === undefined ? {} : { priority: route.priority }),