@ultimat3/seo 2.0.0 → 4.0.0

package/CLAUDE.md

@@ -28,6 +28,17 @@ Tier 1. May import `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n`. Nothi
   over the route manifest and the build's own stats, throwing `@ultimat3/render`'s
   `X_BUDGET_EXCEEDED`. seo is tier 1 and cannot see a build's bytes, so it was never the package
   that could answer. `errors.test.ts` pins the code set, so re-adding one is a failing test.
+- **A length bound with no enforcer does not ship.** `DESCRIPTION_MIN_LENGTH` (50) sat in
+  `meta.ts` under the comment "validate.ts enforces it", was re-exported from `index.ts`, and no
+  validator anywhere read it — a 10-character description passed the gate the constant claimed to
+  fail. Deleted `As of 2026-08`, comment included; `validateMeta` enforces maxima only. Adding a
+  minimum back means adding the check AND a new `X_SEO_*` code in the same change.
+  `meta.test.ts` pins the exported `*_LENGTH` set, so a bound with no enforcer is a failing test.
+- **The `<img src>` fallback is the LARGEST usable width, chosen with `Math.max`.**
+  `usableWidths` preserves the CALLER's order, so `widths[widths.length - 1]` was the largest only
+  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.
 - **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
@@ -38,6 +49,12 @@ Tier 1. May import `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n`. Nothi
   Never invert that default and never re-read the key here.
 - **Required schema.org fields are required in the input type.** Runtime `required()` only catches empty strings from a CMS; the type is the primary gate.
 - **No ambient defaults for meta.** A missing description is an error, never a fallback string.
+- **`applyTitleTemplate` is TOTAL; `validateMeta` is where a broken template is refused.**
+  `'Ultimate'.replace('%s', title)` on a template with no slot is a no-op that returned the BRAND,
+  so every route's `<title>` became the brand and the page's own title was discarded — visible only
+  as a duplicate-title issue, weeks later. The renderer runs per request, so it falls back to the
+  title rather than throwing; the refusal is `titleTemplateSlotMissing`, `X_SEO_META_MISSING`,
+  naming the file. Same split as every other check here: the renderer degrades, the gate refuses.
 - **Head tags are CONSTRUCTED here and serialised nowhere here.** `renderMeta` returns data;
   `HeadTag.text` is raw, and `@ultimat3/render`'s `renderHead` picks the escape from the element
   (raw text for code, the total `\uXXXX` JSON rule for a `type` ending in `json`). `meta.ts` had a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/seo",
-  "version": "2.0.0",
+  "version": "4.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": "2.0.0"
+    "@ultimat3/core": "4.0.0"
   }
 }

package/src/errors.ts

@@ -1,5 +1,7 @@
-// @ultimat3/seo error codes. SEO in Ultimate is enforced, not documented: these
-// are build errors, so every one names the exact route file and the exact fix.
+// @ultimat3/seo error codes. Every one names the exact route file and the exact edit, because an
+// SEO rule that cannot say which route broke it is a rule nobody acts on. What they are NOT, `As
+// 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';
 // errors.ts <-> images.ts: images.ts throws imageQueryInvalid() and this file spells its fix
@@ -69,6 +71,20 @@ export function metaMissing(file: string, path: string, field: string): SeoError
   });
 }
 
+/**
+ * A `titleTemplate` that cannot place the title. Reported under `X_SEO_META_MISSING` because that
+ * is what it produces — every page's `<title>` is the brand and the route's own title is gone —
+ * and the reader lands on the page about missing metadata, which is where the answer is.
+ */
+export function titleTemplateSlotMissing(file: string, path: string): SeoError {
+  return new SeoError({
+    code: SEO_ERROR_CODES.metaMissing,
+    cause: `${file} (route "${path}") declares a titleTemplate with no %s slot, so the page title is discarded and every route renders the brand alone`,
+    fix: `put the slot in the template — meta.titleTemplate: '%s — Ultimate' in ${file} — or delete titleTemplate and let meta.title stand alone`,
+    meta: { file, path, field: 'titleTemplate' },
+  });
+}
+
 export function duplicateMeta(field: string, value: string, files: readonly string[]): SeoError {
   return new SeoError({
     code: SEO_ERROR_CODES.duplicateMeta,

package/src/images.ts

@@ -69,10 +69,6 @@ export interface ResponsiveImageOptions {
   urlFor?: (src: string, width: number, format?: string) => string;
 }
 
-export function extensionOf(src: string): string {
-  return (src.split('?')[0]?.split('.').pop() ?? '').toLowerCase();
-}
-
 /**
  * The one spelling of the transform query keys. `defaultUrlFor` writes them and
  * `parseImageQuery` reads them back — a literal `'w'` in one place and a literal `'w'` in the
@@ -176,6 +172,11 @@ export function usableWidths(intrinsic: number, widths: readonly number[]): read
   return usable.includes(intrinsic) ? usable : [...usable, intrinsic];
 }
 
+/** The widest candidate, or `undefined` for an empty list — never `Math.max()`'s `-Infinity`. */
+function largestOf(widths: readonly number[]): number | undefined {
+  return widths.length === 0 ? undefined : Math.max(...widths);
+}
+
 export function srcsetFor(
   input: ImageInput,
   widths: readonly number[],
@@ -212,7 +213,10 @@ export function responsiveImage(
   return {
     sources,
     img: {
-      src: urlFor(input.src, widths[widths.length - 1] ?? input.width, undefined),
+      // `Math.max`, not the last element: `usableWidths` preserves the CALLER's order, so the
+      // tail was the largest only because `DEFAULT_WIDTHS` happens to ascend. `widths: [1200, 640]`
+      // handed every no-`srcset` browser the 640 variant of a 1200-wide image.
+      src: urlFor(input.src, largestOf(widths) ?? input.width, undefined),
       srcset: srcsetFor(input, widths, undefined, urlFor),
       sizes,
       alt: input.alt,

package/src/index.ts

@@ -30,7 +30,6 @@ export type {
 } from './images';
 export {
   DEFAULT_WIDTHS,
-  extensionOf,
   FORMAT_ORDER,
   IMAGE_QUERY_KEYS,
   inlineBlur,
@@ -84,7 +83,6 @@ export type {
 export {
   applyTitleTemplate,
   DESCRIPTION_MAX_LENGTH,
-  DESCRIPTION_MIN_LENGTH,
   hreflangSet,
   renderMeta,
   robotsContent,

package/src/meta.ts

@@ -4,9 +4,12 @@
 
 import { absoluteUrl } from './xml';
 
-/** Search results truncate past this; validate.ts enforces it. */
+/**
+ * Search results truncate past these; `validate.ts` enforces both, and only these two exist for
+ * that reason — a `DESCRIPTION_MIN_LENGTH` shipped here with no validator reading it, so the
+ * comment promised a gate that never ran. A bound with no enforcer does not ship.
+ */
 export const TITLE_MAX_LENGTH = 60;
-export const DESCRIPTION_MIN_LENGTH = 50;
 export const DESCRIPTION_MAX_LENGTH = 160;
 
 export interface RobotsDirectives {
@@ -105,6 +108,9 @@ export interface RenderMetaOptions {
  */
 const TEMPLATE_SEPARATORS = /^[\s\-–—|·:>/]+|[\s\-–—|·:>/]+$/g;
 
+/** Where the page's own title goes. Case-sensitive: `%S` names no slot, and neither does absence. */
+export const TITLE_SLOT = '%s';
+
 /**
  * The containment was `template.includes(title)` — inverted, so it only ever answered true when
  * the title EQUALLED the brand. `applyTitleTemplate('About Ultimate', '%s — Ultimate')` produced
@@ -112,9 +118,14 @@ const TEMPLATE_SEPARATORS = /^[\s\-–—|·:>/]+|[\s\-–—|·:>/]+$/g;
  */
 export function applyTitleTemplate(title: string, template?: string): string {
   if (template === undefined || template === '') return title;
-  const brand = template.replace('%s', '').replace(TEMPLATE_SEPARATORS, '');
+  // No slot, nothing to apply: `'Ultimate'.replace('%s', title)` is a no-op that returned the
+  // BRAND and threw the page's own title away, on every route in the app. Total on purpose —
+  // `renderMeta` runs per request, so the refusal belongs in `validate.ts`'s build gate, where it
+  // 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;
-  return template.replace('%s', title);
+  return template.replace(TITLE_SLOT, title);
 }
 
 export function robotsContent(directives: RobotsDirectives): string {

package/src/sitemap.ts

@@ -2,6 +2,7 @@
 // their `prerender()` enumerates, so the sitemap can never drift from what the
 // build actually produced. Splits into an index past the 50,000-URL protocol cap.
 
+import { assert } from '@ultimat3/core';
 import { sitemapTooLarge } from './errors';
 import { type ChangeFreq, expandRoute, indexableRoutes, type RouteRecord } from './routes';
 import { absoluteUrl, attributes, escapeXml } from './xml';
@@ -134,6 +135,15 @@ function renderIndex(files: readonly SitemapFile[], options: BuildSitemapOptions
 }
 
 export function chunk<T>(items: readonly T[], size: number): T[][] {
+  // The loop advances by `size`, so a non-positive one never moves the cursor: `maxUrls: 0` in a
+  // route config turned a build into an infinite loop allocating empty slices until the box ran
+  // out of memory. A fractional size is refused for a quieter reason — `slice` truncates it, so
+  // the groups silently stop being the size that was asked for.
+  assert(
+    Number.isSafeInteger(size) && size > 0,
+    `a chunk size must be a positive integer, got ${String(size)}: a non-positive step never advances and the loop cannot end`,
+    'pass a positive integer — buildSitemap(routes, { baseUrl, maxUrls: 50000 }), the sitemaps.org bound SITEMAP_MAX_URLS already carries',
+  );
   const out: T[][] = [];
   for (let index = 0; index < items.length; index += size) {
     out.push(items.slice(index, index + size));
@@ -145,8 +155,16 @@ export async function buildSitemap(
   routes: readonly RouteRecord[],
   options: BuildSitemapOptions,
 ): Promise<SitemapResult> {
-  const urls = await sitemapUrls(routes, options);
   const maxUrls = options.maxUrls ?? SITEMAP_MAX_URLS;
+  // Refused here and not only in `chunk`, so the answer does not depend on how many URLs the site
+  // happens to have today: `maxUrls: 2.5` is a typo whether or not this build has enough routes to
+  // reach the split, exactly as a metric refuses `maxSeries: 1.5` at declaration.
+  assert(
+    Number.isSafeInteger(maxUrls) && maxUrls > 0,
+    `buildSitemap({ maxUrls }) must be a positive integer, got ${String(maxUrls)}`,
+    'pass a positive integer — buildSitemap(routes, { baseUrl, maxUrls: 50000 }) — or omit it and take SITEMAP_MAX_URLS, the sitemaps.org bound',
+  );
+  const urls = await sitemapUrls(routes, options);
 
   if (urls.length <= maxUrls) {
     return {

package/src/validate.ts

@@ -10,8 +10,9 @@ import {
   metaTooLong,
   SeoError,
   type SeoErrorCode,
+  titleTemplateSlotMissing,
 } from './errors';
-import { applyTitleTemplate, DESCRIPTION_MAX_LENGTH, TITLE_MAX_LENGTH } from './meta';
+import { applyTitleTemplate, DESCRIPTION_MAX_LENGTH, TITLE_MAX_LENGTH, TITLE_SLOT } from './meta';
 import { indexableRoutes, isDynamic, type RouteRecord } from './routes';
 import { absoluteUrl } from './xml';
 
@@ -61,6 +62,14 @@ export function validateMeta(
     if (meta.title === undefined || meta.title.trim() === '') {
       issues.push(issueOf(metaMissing(route.file, route.path, 'title'), route.path, route.file));
     } else {
+      // An empty template is "no template" and applies nothing; a non-empty one that cannot place
+      // the title silently discards it, which is the one the renderer cannot report.
+      const template = meta.titleTemplate ?? '';
+      if (template !== '' && !template.includes(TITLE_SLOT)) {
+        issues.push(
+          issueOf(titleTemplateSlotMissing(route.file, route.path), route.path, route.file),
+        );
+      }
       const rendered = applyTitleTemplate(meta.title, meta.titleTemplate);
       if (rendered.length > titleMax) {
         issues.push(
@@ -133,7 +142,12 @@ function duplicates(index: Map<string, string[]>, field: string): MetaIssue[] {
   return out;
 }
 
-/** Fails the build on the first issue. `x verify` calls this. */
+/**
+ * Throws on the first issue. `x verify` does NOT call this — `As of 2026-08` nothing outside this
+ * package imports it, and wiring it is a `HostCheck` on an existing step in
+ * `packages/cli/src/cmd-verify.ts`. Today it fails an app that calls it itself, which is what
+ * `README.md` says and what this line claimed the opposite of.
+ */
 export function assertMeta(report: MetaValidationReport): void {
   const first = report.issues[0];
   if (first === undefined) return;