@ultimat3/seo 21.0.0 → 22.1.0

package/README.md

@@ -3,10 +3,10 @@
 SEO is **enforced, not documented**: every rule below is an `assert*` that throws a coded
 `SeoError` with the route file and the exact edit, never a lint warning.
 
-`As of 2026-08` the half that *calls* those asserts is missing — nothing outside this package
-imports `assertMeta`, `buildSitemap` or `buildRobots`, so no step of `x verify` runs them yet.
-Wiring them is a `HostCheck` on an existing step in `packages/cli/src/cmd-verify.ts`. The shapes
-below are what will fail the build; today they fail an app that calls them itself.
+`x verify`'s **`seo`** step (`packages/cli/src/verify-checks.ts`) runs `validateMeta` over every
+`site/` route, so missing, duplicate and over-long meta fail the gate `As of 2026-09-23`. Canonical
+checks are skipped there — an app declares no base URL — and JSON-LD, sitemaps and robots are
+enforced where they are built: each builder throws.
 
 ## What fails the build
 
@@ -31,6 +31,15 @@ X_SEO_META_MISSING: a site/ route is missing required metadata
   fix:   add description to defineRoute({ meta }) in apps/web/site/about/page.tsx
 ```
 
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `SeoError` | any `SeoErrorCode` — `SEO_ERROR_CODES` | `src/errors.ts` |
+
 ## Modules
 
 | File | Owns |

package/package.json

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

package/src/feed-dates.ts

@@ -4,10 +4,24 @@
 // `toISOString()` as a `RangeError` that takes the whole route down over one bad row.
 
 import type { Clock } from '@ultimat3/core';
+import { logger } from '@ultimat3/core';
+import { isIsoDateTime } from '@ultimat3/schema';
 
-/** Milliseconds for a timestamp, or `undefined` when the string is not a date at all. */
+/**
+ * Milliseconds for a timestamp, or `undefined` when the string names no instant. An ISO date, or
+ * an ISO date-time carrying `Z` or an offset, is the whole accepted set — `@ultimat3/schema`'s
+ * `isIsoDateTime`, the rule `t.date` and `fromIso` answer with. `Date.parse` alone read
+ * `2026-03-14T09:00:00` through the PROCESS's zone, so a feed's `pubDate` moved with `TZ`; that
+ * form is treated as absent and logged, the screen `@ultimat3/flags` gives an expiry.
+ */
 export function epochOf(iso: string | undefined): number | undefined {
   if (iso === undefined) return undefined;
+  if (!isIsoDateTime(iso)) {
+    // Offsetless is the one refusal worth a line: it is a real date the author meant, and it
+    // used to render — adding a `Z` is exactly what makes it valid.
+    if (isIsoDateTime(`${iso}Z`)) logger.warn('seo.feed.date_offsetless', { value: iso });
+    return undefined;
+  }
   const ms = Date.parse(iso);
   return Number.isNaN(ms) ? undefined : ms;
 }

package/src/ld.ts

@@ -9,8 +9,13 @@ export type JsonLd = Readonly<Record<string, unknown>>;
 
 export const LD_CONTEXT = 'https://schema.org';
 
-function required(type: string, field: string, value: string, hint: string): string {
-  if (value.trim() === '') throw ldInvalid(type, field, hint);
+/**
+ * `typeof` first: the value is read from a CMS, whose missing field is `null`, and `.trim()` on it
+ * was a bare `TypeError` in place of the coded refusal. The input TYPE says `string`; a CMS row
+ * does not read the type.
+ */
+function required(type: string, field: string, value: unknown, hint: string): string {
+  if (typeof value !== 'string' || value.trim() === '') throw ldInvalid(type, field, hint);
   return value;
 }
 

package/src/meta.ts

@@ -125,7 +125,9 @@ export function applyTitleTemplate(title: string, template?: string): string {
   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(TITLE_SLOT, 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);
 }
 
 export function robotsContent(directives: RobotsDirectives): string {