@ultimat3/seo 3.0.0 → 4.0.0

package/CLAUDE.md

@@ -49,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": "3.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": "3.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

package/src/index.ts

@@ -30,7 +30,6 @@ export type {
 } from './images';
 export {
   DEFAULT_WIDTHS,
-  extensionOf,
   FORMAT_ORDER,
   IMAGE_QUERY_KEYS,
   inlineBlur,

package/src/meta.ts

@@ -108,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
@@ -115,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;