@ultimat3/seo 1.2.0 → 2.0.0

package/CLAUDE.md

@@ -0,0 +1,98 @@
+# @ultimat3/seo — agent notes
+
+Tier 1. May import `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n`. Nothing above tier 1, no external deps.
+
+## Boundary
+
+| Owns | Does not own |
+|---|---|
+| metadata model, JSON-LD, sitemap/robots/feeds, image contract | rendering, routing, the route table itself (it consumes `RouteRecord`), **performance budgets** |
+
+## Hard rules
+
+- **Enforced, not documented — and `As of 2026-08` the gate half of this package is not yet
+  enforcing anything.** Every check here has an `assert*` that throws a coded `SeoError` beside a
+  `--json`-shaped report; a check that only returns a boolean does not exist. That is a rule about
+  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`).
+  `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
+  lands, do not restate the CI claim here, in `README.md` or in the wiki.
+- **Performance budgets are not this package's, `As of 2026-08`.** `checkBudgets`/`assertBudgets`/
+  `parseBytes`/`DEFAULT_BUDGET`/`BUDGET_UNITS`, `RouteBudget`, `RouteRecord.budget` and
+  `X_SEO_BUDGET_EXCEEDED` are deleted: the whole surface was callerless, and `parseBytes` reported a
+  malformed size string *as a budget violation*. The live gate is `@ultimat3/cli`'s `checkBudgets`
+  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.
+- **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
+  exactly one reader and it is `@ultimat3/core`'s (`Environment`, `tryResolveEnvironment`); this
+  package owns only what an *unnameable* environment means, which is core's `DEFAULT_ENVIRONMENT`
+  and never a throw — nothing in a web container's boot path resolves the environment
+  unconditionally, so a `robots.txt` render is routinely the first reader and it must answer.
+  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.
+- **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
+  `renderHeadTags` that emitted HTML with a weaker escape — `</` neutralised, `<!--<script>` not —
+  and **nothing called it**; deleted `As of 2026-08`. Never add it back, and never escape `text`
+  at construction: it would double-escape at tier 4, and the two rules would drift apart. seo
+  cannot import render's escapers either — seo is tier 1, render is tier 4. `xml.ts` stays the
+  package's one escaper for the XML and attribute surfaces it really does emit (sitemap, feeds,
+  robots, `<picture>`), whose rules are the opposite of a raw-text element's.
+- **One producer of the JSON-LD tags, and it is `renderMeta`.** `ld.*` builds nodes; `renderMeta`
+  emits `meta.ld` as one `<script type="application/ld+json">` **per node**. `ld.ts` also carried a
+  `renderLd(nodes)` that collapsed the same nodes into ONE script with a `@graph` — a second
+  serialisation of one input, exported, callerless, and the reason `@ultimat3/render`'s
+  `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.
+- **`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,
+  and the driver reports the size it probed off the output, never the size that was requested.
+- **One spelling of the transform query keys.** `IMAGE_QUERY_KEYS` in `images.ts` is the only
+  place `w`/`f`/`q` are spelled; `defaultUrlFor` writes them and `parseImageQuery` is the only
+  reader — never hand-roll either half against a literal. A present-but-unusable `w` or `q`
+  (`?w=0`, `?q=150`, empty, negative, fractional, or so many digits that `parseInt` returns
+  `Infinity`) throws `X_IMAGE_QUERY_INVALID` instead of
+  falling back to the untransformed original — that silent fallback is the layout shift this
+  whole contract exists to prevent. `parseImageQuery` never validates `f` against real format
+  names; that refusal stays `image-driver.ts`'s `X_IMAGE_UNSUPPORTED`, so one bad URL never
+  carries two codes.
+- **A feed date never throws and never lies.** `feed-dates.ts` is the only place a feed timestamp
+  is parsed or formatted; `buildFeed` resolves every date once, so no builder ever sees a string it
+  has to parse. An item date that will not parse is **absent** — the element is omitted (Atom's
+  required `<updated>` falls back to the feed's) — never `Invalid Date`, never today standing in
+  for it, and never a `RangeError` out of a route a reader is polling. Scan a feed with a loop, not
+  `Math.max(...times)`: a spread is one argument per item and the engine's limit is the caller's
+  stack depth, not the feed's size. "Now" arrives through `BuildFeedOptions.clock`; nothing in
+  `rss.ts` reads a clock of its own.
+- Only `site/` routes are SEO-checked — `app/` is behind auth and crawlers never authenticate.
+
+## Files
+
+| Path | Responsibility |
+|---|---|
+| `routes.ts` | the `RouteRecord` shape + `indexableRoutes` / `expandRoute` |
+| `meta.ts` | model + `renderMeta()`; the only place head tags are constructed, and no place they are serialised |
+| `validate.ts` | the gate; `MetaIssue` is the serialisable projection of a `SeoError` |
+| `xml.ts` | all escaping. Never hand-roll an escape in another module |
+| `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 |
+
+## Commands
+
+```
+bun test packages/seo
+bun run --filter @ultimat3/seo typecheck
+```

package/README.md

@@ -1,6 +1,12 @@
 # @ultimat3/seo 🔍
 
-SEO is **enforced, not documented**. These are build errors, not lint warnings.
+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.
 
 ## What fails the build
 
@@ -11,9 +17,12 @@ SEO is **enforced, not documented**. These are build errors, not lint warnings.
 | `X_SEO_META_TOO_LONG` | title > 60 chars, description > 160 | the tail is truncated in results — the words are paid for and never read |
 | `X_SEO_CANONICAL_MISMATCH` | `meta.canonical` does not resolve to the route's own URL | a wrong canonical de-indexes the page in favour of another |
 | `X_LD_INVALID` | a JSON-LD node missing a required schema.org field | invalid structured data drops the rich result silently |
-| `X_SEO_BUDGET_EXCEEDED` | a route over its `js` / `css` / `lcp` / `cls` / `inp` budget | performance is a ranking factor and regressions are invisible without a gate |
 | `X_SITEMAP_TOO_LARGE` | the sitemap index exceeds 50,000 files | past the protocol limit the whole sitemap is discarded |
 
+Performance budgets are **not** here: `x verify`'s `budgets` step is `@ultimat3/cli`'s
+`checkBudgets`, over the route manifest and the build's own stats, and it throws
+`@ultimat3/render`'s `X_BUDGET_EXCEEDED`. This package is tier 1 and cannot see a build's bytes.
+
 Every error names the exact route **file** and the exact edit:
 
 ```
@@ -32,9 +41,9 @@ X_SEO_META_MISSING: a site/ route is missing required metadata
 | `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 |
+| `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 |
 | `image-driver.ts` | `ImageTransformDriver` + `builtinImageDriver()`: the variant bytes and the blur placeholder |
-| `budgets.ts` | `checkBudgets()` / `assertBudgets()`, the CI gate |
 
 ## Type-level enforcement
 
@@ -49,8 +58,9 @@ weeks later.
 ## robots.txt is fail-closed
 
 Only the literal string `production` in `ULTIMATE_ENV` / `NODE_ENV` opts a deploy
-into indexing. A typo, an unset variable, or a branch deploy all resolve to
-`preview`, and preview emits:
+into indexing. The environment is `@ultimat3/core`'s `Environment` and its reader
+is core's — this package owns no second one. A branch deploy (`staging`), a
+laptop, a typo and an unset variable are all "not production", and each emits:
 
 ```
 User-agent: *
@@ -144,6 +154,6 @@ export const config = defineRoute({
 ## Commands
 
 ```
-bun test                 # meta, validation, JSON-LD, sitemap, robots, feeds, images, budgets
+bun test                 # meta, validation, JSON-LD, sitemap, robots, feeds, images, error codes
 bun run typecheck
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/seo",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Enforced SEO: typed meta, JSON-LD, sitemap, robots, feeds, responsive images, perf budgets",
   "license": "MIT",
   "type": "module",
@@ -19,6 +19,7 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "CLAUDE.md",
     "README.md",
     "LICENSE"
   ],
@@ -30,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "1.2.0"
+    "@ultimat3/core": "2.0.0"
   }
 }

package/src/errors.ts

@@ -14,7 +14,6 @@ export const SEO_ERROR_CODES = {
   metaTooLong: 'X_SEO_META_TOO_LONG',
   canonicalMismatch: 'X_SEO_CANONICAL_MISMATCH',
   ldInvalid: 'X_LD_INVALID',
-  budgetExceeded: 'X_SEO_BUDGET_EXCEEDED',
   sitemapTooLarge: 'X_SITEMAP_TOO_LARGE',
   imageQueryInvalid: 'X_IMAGE_QUERY_INVALID',
 } as const;
@@ -23,9 +22,10 @@ export type SeoErrorCode = (typeof SEO_ERROR_CODES)[keyof typeof SEO_ERROR_CODES
 
 /**
  * Every code here is seo's own, so the registration is unconditional and atomic — a collision must
- * surface as X_ERROR_CODE_DUPLICATE, never as a first-writer-wins title. `X_SEO_BUDGET_EXCEEDED` is
- * namespaced for exactly that reason: `X_BUDGET_EXCEEDED` is `@ultimat3/render`'s, seo is tier 1
- * and cannot import render, so sharing the code left the meaning up to import order.
+ * surface as X_ERROR_CODE_DUPLICATE, never as a first-writer-wins title. A performance budget is
+ * 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.
  */
 registerErrorCodes({
@@ -34,7 +34,6 @@ registerErrorCodes({
   X_SEO_META_TOO_LONG: { title: 'title or description exceeds what search results render' },
   X_SEO_CANONICAL_MISMATCH: { title: 'canonical URL does not match the route path' },
   X_LD_INVALID: { title: 'JSON-LD node is missing a required schema.org field' },
-  X_SEO_BUDGET_EXCEEDED: { title: 'route exceeded its performance budget' },
   X_SITEMAP_TOO_LARGE: { title: 'sitemap exceeds the 50,000-entry protocol limit' },
   X_IMAGE_QUERY_INVALID: { title: 'an image transform query parameter is present but unusable' },
 });
@@ -106,22 +105,6 @@ export function ldInvalid(type: string, field: string, hint: string): SeoError {
   });
 }
 
-export function budgetExceeded(
-  route: string,
-  file: string,
-  metric: string,
-  limit: number,
-  actual: number,
-  unit: string,
-): SeoError {
-  return new SeoError({
-    code: SEO_ERROR_CODES.budgetExceeded,
-    cause: `${route} (${file}) ${metric} is ${actual}${unit}, budget is ${limit}${unit}`,
-    fix: `x analyze ${route} --json   # then trim, or raise budget.${metric} in ${file}`,
-    meta: { route, file, metric, limit, actual, unit },
-  });
-}
-
 export function sitemapTooLarge(count: number, max: number): SeoError {
   return new SeoError({
     code: SEO_ERROR_CODES.sitemapTooLarge,

package/src/feed-dates.ts

@@ -0,0 +1,49 @@
+// The one place a feed timestamp is parsed or formatted. Item dates are app data — a CMS column,
+// a front-matter line — so a string that is not a date at all is a live possibility, and a feed is
+// a page a reader is polling, not a build step: `Date.parse` answers `NaN`, and `NaN` reaches
+// `toISOString()` as a `RangeError` that takes the whole route down over one bad row.
+
+import type { Clock } from '@ultimat3/core';
+
+/** Milliseconds for a timestamp, or `undefined` when the string is not a date at all. */
+export function epochOf(iso: string | undefined): number | undefined {
+  if (iso === undefined) return undefined;
+  const ms = Date.parse(iso);
+  return Number.isNaN(ms) ? undefined : ms;
+}
+
+/**
+ * The newest instant in a feed, or `undefined` when nothing in it carries a usable one.
+ *
+ * A loop, never `Math.max(...times)`: a spread passes one argument per item, so the call overflows
+ * the engine's stack in proportion to how well the blog did — and it overflows sooner the deeper
+ * the request stack already is, which makes the size that breaks it a property of the caller
+ * rather than of the feed.
+ */
+export function newestEpoch(times: Iterable<number | undefined>): number | undefined {
+  let max: number | undefined;
+  for (const ms of times) {
+    if (ms !== undefined && (max === undefined || ms > max)) max = ms;
+  }
+  return max;
+}
+
+/**
+ * The clock's instant, for a feed whose items carry no usable timestamp of their own. A `Clock`
+ * handing back an invalid `Date` is the caller's bug, and the epoch is a wrong-but-renderable
+ * answer — throwing here would be the crash this module exists to prevent, one seam over.
+ */
+export function nowEpoch(clock: Clock): number {
+  const ms = clock.now().getTime();
+  return Number.isFinite(ms) ? ms : 0;
+}
+
+/** RFC 3339, for Atom and JSON Feed. Takes an instant, so it can never be handed a `NaN`. */
+export function isoOf(ms: number): string {
+  return new Date(ms).toISOString();
+}
+
+/** RFC 822, RSS 2.0's only date format. Same guarantee. */
+export function rfc822Of(ms: number): string {
+  return new Date(ms).toUTCString();
+}

package/src/images.ts

@@ -118,6 +118,26 @@ function parseQuality(raw: string): number {
   return quality;
 }
 
+/**
+ * A safe integer is not a servable width. `?w=99999999` clears every gate above and then asks the
+ * encoder for a row buffer nothing can allocate — and on a surface that CACHES its output, each
+ * distinct width mints a new stored object, so an unbounded `w` is unbounded writes as well as one
+ * bad allocation. 8192 is past every display this can legitimately serve (`DEFAULT_SRCSET_WIDTHS`
+ * tops out two orders below it).
+ *
+ * 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;
+
+function parseWidth(raw: string): number {
+  const width = parsePositiveInt(IMAGE_QUERY_KEYS.width, raw);
+  if (width > MAX_IMAGE_WIDTH) {
+    throw imageQueryInvalid(IMAGE_QUERY_KEYS.width, raw, `must be ${MAX_IMAGE_WIDTH} or less`);
+  }
+  return width;
+}
+
 /**
  * Naming no *real* format is deliberately not refused here: `image-driver.ts`'s
  * `requestedFormat` already owns "is this an encodable format", and throwing in two places
@@ -143,7 +163,7 @@ export function parseImageQuery(params: URLSearchParams): ImageQuery | null {
   if (rawWidth === null && rawFormat === null && rawQuality === null) return null;
 
   return {
-    ...(rawWidth === null ? {} : { width: parsePositiveInt(IMAGE_QUERY_KEYS.width, rawWidth) }),
+    ...(rawWidth === null ? {} : { width: parseWidth(rawWidth) }),
     ...(rawFormat === null ? {} : { format: parseFormat(rawFormat) }),
     ...(rawQuality === null ? {} : { quality: parseQuality(rawQuality) }),
   };

package/src/index.ts

@@ -1,10 +1,7 @@
 // The public surface of @ultimat3/seo. Explicit named exports only.
 
-export type { BudgetMeasurement, BudgetMetric, BudgetReport, BudgetViolation } from './budgets';
-export { assertBudgets, BUDGET_UNITS, checkBudgets, DEFAULT_BUDGET, parseBytes } from './budgets';
 export type { SeoErrorCode, SeoErrorInit } from './errors';
 export {
-  budgetExceeded,
   canonicalMismatch,
   duplicateMeta,
   imageQueryInvalid,
@@ -70,7 +67,6 @@ export {
   Organization,
   Person,
   Product,
-  renderLd,
   SoftwareApplication,
   WebSite,
 } from './ld';
@@ -90,16 +86,15 @@ export {
   DESCRIPTION_MAX_LENGTH,
   DESCRIPTION_MIN_LENGTH,
   hreflangSet,
-  renderHeadTags,
   renderMeta,
   robotsContent,
   TITLE_MAX_LENGTH,
 } from './meta';
-export type { RobotsConfig, RobotsGroup, SeoEnvironment } from './robots';
-export { buildRobots, isIndexable, resolveEnvironment } from './robots';
-export type { ChangeFreq, RenderMode, RouteBudget, RouteRecord, Surface } from './routes';
+export type { RobotsConfig, RobotsGroup } from './robots';
+export { buildRobots, isIndexable } from './robots';
+export type { ChangeFreq, RenderMode, RouteRecord, Surface } from './routes';
 export { expandRoute, indexableRoutes, isDynamic } from './routes';
-export type { Feed, FeedAuthor, FeedChannel, FeedItem } from './rss';
+export type { BuildFeedOptions, Feed, FeedAuthor, FeedChannel, FeedItem } from './rss';
 export { buildFeed } from './rss';
 export type {
   BuildSitemapOptions,

package/src/ld.ts

@@ -4,7 +4,6 @@
 // type system cannot (a value read from a CMS).
 
 import { ldInvalid } from './errors';
-import type { HeadTag } from './meta';
 
 export type JsonLd = Readonly<Record<string, unknown>>;
 
@@ -310,16 +309,3 @@ export const ld = {
   SoftwareApplication,
   WebSite,
 } as const;
-
-/** One `<script type="application/ld+json">` holding a @graph of every node. */
-export function renderLd(nodes: readonly JsonLd[]): HeadTag {
-  const payload =
-    nodes.length === 1
-      ? nodes[0]
-      : { '@context': LD_CONTEXT, '@graph': nodes.map(({ '@context': _drop, ...rest }) => rest) };
-  return {
-    tag: 'script',
-    attrs: { type: 'application/ld+json' },
-    text: JSON.stringify(payload),
-  };
-}

package/src/meta.ts

@@ -2,7 +2,7 @@
 // for a global default: a route that does not declare a description does not get
 // one, it fails the build (see validate.ts).
 
-import { absoluteUrl, attributes, escapeXml } from './xml';
+import { absoluteUrl } from './xml';
 
 /** Search results truncate past this; validate.ts enforces it. */
 export const TITLE_MAX_LENGTH = 60;
@@ -83,7 +83,12 @@ export interface RouteMeta {
 export interface HeadTag {
   readonly tag: 'title' | 'meta' | 'link' | 'script';
   readonly attrs: Readonly<Record<string, string>>;
-  /** Text content, already safe to embed for `title`; escaped on render. */
+  /**
+   * Text content, raw. Escaping is the RENDERER's — `@ultimat3/render`'s `renderHead` picks the
+   * rule from the element and, for a `type` ending in `json`, from the fact that the body is data.
+   * Escaping here would double-escape there, and a second escaper is how one of them ends up
+   * missing a character.
+   */
   readonly text?: string;
 }
 
@@ -94,9 +99,22 @@ export interface RenderMetaOptions {
   path?: string;
 }
 
+/**
+ * Separators a title template puts between the slot and the brand. Stripped so the BRAND is what
+ * the containment test reads: `'%s — Ultimate'` means the brand is `Ultimate`, not `— Ultimate`.
+ */
+const TEMPLATE_SEPARATORS = /^[\s\-–—|·:>/]+|[\s\-–—|·:>/]+$/g;
+
+/**
+ * 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
+ * `'About Ultimate — Ultimate'`, which `validate.ts` then measured against `TITLE_MAX_LENGTH`.
+ */
 export function applyTitleTemplate(title: string, template?: string): string {
   if (template === undefined || template === '') return title;
-  return template.includes(title) ? title : template.replace('%s', title);
+  const brand = template.replace('%s', '').replace(TEMPLATE_SEPARATORS, '');
+  if (brand !== '' && title.includes(brand)) return title;
+  return template.replace('%s', title);
 }
 
 export function robotsContent(directives: RobotsDirectives): string {
@@ -254,16 +272,10 @@ export function renderMeta(meta: RouteMeta, options: RenderMetaOptions = {}): re
   return tags;
 }
 
-/** Serialise head tags to HTML. `<script>` content is JSON, escaped for `</`. */
-export function renderHeadTags(tags: readonly HeadTag[]): string {
-  return tags
-    .map((tag) => {
-      if (tag.tag === 'title') return `<title>${escapeXml(tag.text ?? '')}</title>`;
-      if (tag.tag === 'script') {
-        const safe = (tag.text ?? '').replaceAll('</', '<\\/');
-        return `<script${attributes(tag.attrs)}>${safe}</script>`;
-      }
-      return `<${tag.tag}${attributes(tag.attrs)}>`;
-    })
-    .join('\n');
-}
+// `renderHeadTags` lived here and was deleted `As of 2026-08`. It serialised these tags to HTML,
+// nothing called it, and its escaping was WEAKER than the path every document actually takes
+// (`@ultimat3/render`'s `renderHead`): it neutralised `</` and not `<!--<script>`, and it applied
+// that code-shaped rule to a JSON body where the total `\uXXXX` rule is available and cannot be
+// got wrong. Exported and vulnerable is a trap — it looks authoritative because it lives in the
+// package named `seo`. This module CONSTRUCTS head tags; serialising them is tier 4's job, and
+// there is now one way to do it. seo cannot borrow render's escapers either: render is tier 4.

package/src/robots.ts

@@ -1,11 +1,10 @@
 // robots.txt generation. Environment-aware, and the default is the safe one:
 // anything that is not explicitly production emits `Disallow: /`, because a
-// preview deploy that gets indexed outranks and cannibalises the real site.
+// branch deploy that gets indexed outranks and cannibalises the real site.
 
+import { DEFAULT_ENVIRONMENT, type Environment, tryResolveEnvironment } from '@ultimat3/core';
 import { absoluteUrl } from './xml';
 
-export type SeoEnvironment = 'production' | 'preview' | 'development' | 'test';
-
 export interface RobotsGroup {
   /** One or more user agents this group applies to. */
   userAgent: string | readonly string[];
@@ -16,8 +15,8 @@ export interface RobotsGroup {
 
 export interface RobotsConfig {
   baseUrl: string;
-  /** Omitted means "resolve from the environment", which defaults to preview. */
-  environment?: SeoEnvironment | undefined;
+  /** Omitted means "resolve from the environment"; anything but `production` disallows all. */
+  environment?: Environment | undefined;
   groups?: readonly RobotsGroup[];
   /** Sitemap paths or absolute URLs. Only emitted in production. */
   sitemaps?: readonly string[];
@@ -26,21 +25,22 @@ export interface RobotsConfig {
 }
 
 /**
- * Fail-closed: only the exact string `production` opts a deploy into indexing.
- * A typo, an unset variable, or a branch deploy all resolve to `preview`.
+ * Fail-closed: only the exact string `production` opts a deploy into indexing. A branch deploy
+ * (`staging`), a laptop, a typo and an unset variable are all "not production" and all disallow.
  */
-export function resolveEnvironment(
-  env: Readonly<Record<string, string | undefined>> = process.env,
-): SeoEnvironment {
-  const raw = env['ULTIMATE_ENV'] ?? env['NODE_ENV'];
-  if (raw === 'production') return 'production';
-  if (raw === 'test') return 'test';
-  if (raw === 'development') return 'development';
-  return 'preview';
+export function isIndexable(environment: Environment): boolean {
+  return environment === 'production';
 }
 
-export function isIndexable(environment: SeoEnvironment): boolean {
-  return environment === 'production';
+/**
+ * `@ultimat3/core` owns the read of `ULTIMATE_ENV`; this module owns only what an unreadable one
+ * means for a crawler. A typo in that key throws there, and a `robots.txt` render can be the first
+ * thing in a web process to ask — nothing in the container's boot path resolves the environment
+ * unconditionally — so an unnameable deploy resolves to core's own default here. The body was
+ * already going to be `Disallow: /`; a 500 would only cost the operator the reason.
+ */
+function ambientEnvironment(): Environment {
+  return tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT;
 }
 
 function agents(userAgent: string | readonly string[]): readonly string[] {
@@ -48,7 +48,7 @@ function agents(userAgent: string | readonly string[]): readonly string[] {
 }
 
 export function buildRobots(config: RobotsConfig): string {
-  const environment = config.environment ?? resolveEnvironment();
+  const environment = config.environment ?? ambientEnvironment();
   const lines: string[] = [`# environment: ${environment}`];
 
   if (!isIndexable(environment)) {

package/src/routes.ts

@@ -11,18 +11,6 @@ export type Surface = 'site' | 'app' | 'api';
 
 export type ChangeFreq = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
 
-export interface RouteBudget {
-  /** Byte budgets accept `'40kb'` or a raw number of bytes. */
-  js?: string | number;
-  css?: string | number;
-  /** Milliseconds. */
-  lcp?: number;
-  /** Unitless layout-shift score. */
-  cls?: number;
-  /** Milliseconds. */
-  inp?: number;
-}
-
 export interface RouteRecord {
   /** URL pattern, e.g. `/blog/:slug`. */
   path: string;
@@ -33,7 +21,6 @@ export interface RouteRecord {
   meta?: RouteMeta;
   /** Concrete paths for a dynamic route, from `defineRoute({ prerender })`. */
   prerender?: () => readonly string[] | Promise<readonly string[]>;
-  budget?: RouteBudget;
   /** Keep out of the sitemap and emit `noindex`. */
   noindex?: boolean;
   lastmod?: string;

package/src/rss.ts

@@ -2,6 +2,8 @@
 // one item list, because a site that ships RSS but not JSON Feed has simply
 // picked a winner for its readers.
 
+import { type Clock, systemClock } from '@ultimat3/core';
+import { epochOf, isoOf, newestEpoch, nowEpoch, rfc822Of } from './feed-dates';
 import { absoluteUrl, cdata, escapeXml, xmlElement } from './xml';
 
 export interface FeedAuthor {
@@ -48,26 +50,50 @@ export interface Feed {
   readonly json: string;
 }
 
-function newest(items: readonly FeedItem[]): string {
-  const times = items.map((item) => Date.parse(item.updated ?? item.published));
-  const max = times.length === 0 ? Date.now() : Math.max(...times);
-  return new Date(max).toISOString();
+export interface BuildFeedOptions {
+  /**
+   * Where "now" comes from when no item carries a usable timestamp. Defaults to `systemClock`;
+   * pass `frozenClock(at)` and the three formats are byte-for-byte reproducible.
+   */
+  clock?: Clock;
 }
 
-function rfc822(iso: string): string {
-  return new Date(iso).toUTCString();
+/**
+ * An item with its timestamps already resolved, so no builder below ever parses a date. A date the
+ * app supplied that will not parse is `undefined` here, and every format omits the element rather
+ * than emitting `Invalid Date` — a feed reader is entitled to reject a document over one, and the
+ * other twenty entries are fine.
+ */
+interface DatedItem {
+  readonly item: FeedItem;
+  readonly published: number | undefined;
+  readonly updated: number | undefined;
 }
 
-function buildRss(channel: FeedChannel, items: readonly FeedItem[], updated: string): string {
+function dated(item: FeedItem): DatedItem {
+  return { item, published: epochOf(item.published), updated: epochOf(item.updated) };
+}
+
+/**
+ * Newest first. An item with no usable `published` sorts last, rather than making the comparator
+ * answer `NaN` — which hands the order of the whole feed to the engine's sort implementation.
+ */
+function byNewest(a: DatedItem, b: DatedItem): number {
+  if (a.published === undefined) return b.published === undefined ? 0 : 1;
+  if (b.published === undefined) return -1;
+  return b.published - a.published;
+}
+
+function buildRss(channel: FeedChannel, items: readonly DatedItem[], updated: number): string {
   const self = absoluteUrl(channel.siteUrl, channel.feedUrl);
   const entries = items
-    .map((item) => {
+    .map(({ item, published }) => {
       const parts = [
         xmlElement('title', item.title),
         xmlElement('link', item.url),
         `      <guid isPermaLink="false">${escapeXml(item.id)}</guid>`,
-        xmlElement('pubDate', rfc822(item.published)),
       ];
+      if (published !== undefined) parts.push(xmlElement('pubDate', rfc822Of(published)));
       if (item.summary !== undefined) parts.push(xmlElement('description', item.summary));
       if (item.contentHtml !== undefined) {
         parts.push(`      <content:encoded>${cdata(item.contentHtml)}</content:encoded>`);
@@ -85,7 +111,7 @@ function buildRss(channel: FeedChannel, items: readonly FeedItem[], updated: str
     `    ${xmlElement('link', channel.siteUrl)}`,
     `    ${xmlElement('description', channel.description)}`,
     `    ${xmlElement('language', channel.language)}`,
-    `    ${xmlElement('lastBuildDate', rfc822(updated))}`,
+    `    ${xmlElement('lastBuildDate', rfc822Of(updated))}`,
     `    <atom:link href="${escapeXml(self)}" rel="self" type="application/rss+xml"/>`,
     channel.copyright === undefined ? '' : `    ${xmlElement('copyright', channel.copyright)}`,
     entries,
@@ -97,17 +123,21 @@ function buildRss(channel: FeedChannel, items: readonly FeedItem[], updated: str
     .join('\n');
 }
 
-function buildAtom(channel: FeedChannel, items: readonly FeedItem[], updated: string): string {
+function buildAtom(channel: FeedChannel, items: readonly DatedItem[], updated: number): string {
   const self = absoluteUrl(channel.siteUrl, channel.feedUrl);
   const entries = items
-    .map((item) => {
+    .map(({ item, published, updated: itemUpdated }) => {
       const parts = [
         `      ${xmlElement('title', item.title)}`,
         `      <link href="${escapeXml(item.url)}"/>`,
         `      ${xmlElement('id', item.id)}`,
-        `      ${xmlElement('updated', item.updated ?? item.published)}`,
-        `      ${xmlElement('published', item.published)}`,
+        // Atom requires <updated> on every entry, so an entry with no usable date of its own
+        // carries the feed's — the one instant in the document that is always real.
+        `      ${xmlElement('updated', isoOf(itemUpdated ?? published ?? updated))}`,
       ];
+      if (published !== undefined) {
+        parts.push(`      ${xmlElement('published', isoOf(published))}`);
+      }
       if (item.summary !== undefined) parts.push(`      ${xmlElement('summary', item.summary)}`);
       if (item.contentHtml !== undefined) {
         parts.push(`      <content type="html">${escapeXml(item.contentHtml)}</content>`);
@@ -128,7 +158,7 @@ function buildAtom(channel: FeedChannel, items: readonly FeedItem[], updated: st
     `  ${xmlElement('title', channel.title)}`,
     `  ${xmlElement('subtitle', channel.description)}`,
     `  ${xmlElement('id', channel.siteUrl)}`,
-    `  ${xmlElement('updated', updated)}`,
+    `  ${xmlElement('updated', isoOf(updated))}`,
     `  <link href="${escapeXml(channel.siteUrl)}"/>`,
     `  <link href="${escapeXml(self)}" rel="self" type="application/atom+xml"/>`,
     entries,
@@ -137,7 +167,7 @@ function buildAtom(channel: FeedChannel, items: readonly FeedItem[], updated: st
   ].join('\n');
 }
 
-function buildJsonFeed(channel: FeedChannel, items: readonly FeedItem[]): string {
+function buildJsonFeed(channel: FeedChannel, items: readonly DatedItem[]): string {
   return `${JSON.stringify(
     {
       version: 'https://jsonfeed.org/version/1.1',
@@ -148,15 +178,15 @@ function buildJsonFeed(channel: FeedChannel, items: readonly FeedItem[]): string
       language: channel.language,
       icon: channel.icon,
       authors: channel.author === undefined ? undefined : [channel.author],
-      items: items.map((item) => ({
+      items: items.map(({ item, published, updated }) => ({
         id: item.id,
         url: item.url,
         title: item.title,
         summary: item.summary,
         content_html: item.contentHtml,
         image: item.image,
-        date_published: item.published,
-        date_modified: item.updated,
+        date_published: published === undefined ? undefined : isoOf(published),
+        date_modified: updated === undefined ? undefined : isoOf(updated),
         tags: item.tags,
         authors: item.author === undefined ? undefined : [item.author],
       })),
@@ -166,10 +196,20 @@ function buildJsonFeed(channel: FeedChannel, items: readonly FeedItem[]): string
   )}\n`;
 }
 
-/** RSS 2.0, Atom, and JSON Feed 1.1 from one item list. */
-export function buildFeed(channel: FeedChannel, items: readonly FeedItem[]): Feed {
-  const ordered = [...items].sort((a, b) => Date.parse(b.published) - Date.parse(a.published));
-  const updated = channel.updated ?? newest(ordered);
+/**
+ * RSS 2.0, Atom, and JSON Feed 1.1 from one item list. Never throws over a date: an unparseable
+ * one is treated as absent, and the feed still renders for the items that have a real one.
+ */
+export function buildFeed(
+  channel: FeedChannel,
+  items: readonly FeedItem[],
+  options: BuildFeedOptions = {},
+): Feed {
+  const ordered = items.map(dated).sort(byNewest);
+  const updated =
+    epochOf(channel.updated) ??
+    newestEpoch(ordered.map((entry) => entry.updated ?? entry.published)) ??
+    nowEpoch(options.clock ?? systemClock);
   return {
     rss: buildRss(channel, ordered, updated),
     atom: buildAtom(channel, ordered, updated),

package/src/xml.ts

@@ -32,8 +32,17 @@ export function attributes(attrs: Readonly<Record<string, string>>): string {
     .join('');
 }
 
-/** Join a base URL and a path without producing `//` or dropping a segment. */
+/**
+ * Join a base URL and a path without producing `//` or dropping a segment.
+ *
+ * A trailing slash the PATH declares is kept: `/blog/` and `/blog` are different resources, and
+ * this builds every `<loc>` (`sitemap.ts`) and every canonical (`meta.ts`), so stripping it made a
+ * trailing-slash site publish URLs that redirect. Only the bare-root join — `''` or `'/'` — has
+ * nothing to keep, and it collapses to the base.
+ */
 export function absoluteUrl(baseUrl: string, path: string): string {
   if (/^https?:\/\//.test(path)) return path;
-  return `${baseUrl.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`.replace(/\/$/, '') || baseUrl;
+  const base = baseUrl.replace(/\/+$/, '');
+  const rest = path.replace(/^\/+/, '');
+  return rest === '' ? base : `${base}/${rest}`;
 }

package/src/budgets.ts

@@ -1,127 +0,0 @@
-// Per-route performance budgets. `checkBudgets()` returns a `--json`-shaped
-// report; `x verify` fails CI on it. A budget that only warns is a budget that
-// gets ignored, so the assert path throws X_SEO_BUDGET_EXCEEDED naming the route file.
-
-import { budgetExceeded, SEO_ERROR_CODES, SeoError } from './errors';
-import type { RouteBudget, RouteRecord } from './routes';
-
-/** Core Web Vitals "good" thresholds, as of 2026-07. */
-export const DEFAULT_BUDGET: Required<Pick<RouteBudget, 'lcp' | 'cls' | 'inp'>> = {
-  lcp: 2500,
-  cls: 0.1,
-  inp: 200,
-};
-
-export type BudgetMetric = 'js' | 'css' | 'lcp' | 'cls' | 'inp';
-
-export const BUDGET_UNITS: Readonly<Record<BudgetMetric, string>> = {
-  js: 'b',
-  css: 'b',
-  lcp: 'ms',
-  cls: '',
-  inp: 'ms',
-};
-
-/** What a build or a lab run measured for one route. */
-export interface BudgetMeasurement {
-  route: string;
-  js?: number;
-  css?: number;
-  lcp?: number;
-  cls?: number;
-  inp?: number;
-}
-
-export interface BudgetViolation {
-  readonly route: string;
-  readonly file: string;
-  readonly metric: BudgetMetric;
-  readonly limit: number;
-  readonly actual: number;
-  readonly overBy: number;
-  readonly unit: string;
-}
-
-export interface BudgetReport {
-  readonly ok: boolean;
-  readonly checked: number;
-  readonly violations: readonly BudgetViolation[];
-}
-
-const BYTE_UNITS: Readonly<Record<string, number>> = {
-  b: 1,
-  kb: 1024,
-  mb: 1024 * 1024,
-};
-
-/** `'40kb'` -> 40960. A raw number is already bytes. */
-export function parseBytes(value: string | number): number {
-  if (typeof value === 'number') return value;
-  const match = /^\s*(\d+(?:\.\d+)?)\s*(b|kb|mb)?\s*$/i.exec(value);
-  if (match === null) {
-    throw new SeoError({
-      code: SEO_ERROR_CODES.budgetExceeded,
-      cause: `budget size ${JSON.stringify(value)} is not a byte count or a size string`,
-      fix: "write the budget as a number of bytes or a string like '40kb'",
-      meta: { value },
-    });
-  }
-  const scale = BYTE_UNITS[(match[2] ?? 'b').toLowerCase()] ?? 1;
-  return Math.round(Number(match[1]) * scale);
-}
-
-function limitOf(budget: RouteBudget, metric: BudgetMetric): number | undefined {
-  if (metric === 'js' || metric === 'css') {
-    const raw = budget[metric];
-    return raw === undefined ? undefined : parseBytes(raw);
-  }
-  return budget[metric] ?? DEFAULT_BUDGET[metric];
-}
-
-export function checkBudgets(
-  routes: readonly RouteRecord[],
-  measurements: readonly BudgetMeasurement[],
-): BudgetReport {
-  const byRoute = new Map(measurements.map((measurement) => [measurement.route, measurement]));
-  const violations: BudgetViolation[] = [];
-  let checked = 0;
-
-  for (const route of routes) {
-    const measured = byRoute.get(route.path);
-    if (measured === undefined) continue;
-    checked += 1;
-    const budget = route.budget ?? {};
-
-    for (const metric of ['js', 'css', 'lcp', 'cls', 'inp'] as const) {
-      const actual = measured[metric];
-      const limit = limitOf(budget, metric);
-      if (actual === undefined || limit === undefined) continue;
-      if (actual <= limit) continue;
-      violations.push({
-        route: route.path,
-        file: route.file,
-        metric,
-        limit,
-        actual,
-        overBy: Number((actual - limit).toFixed(4)),
-        unit: BUDGET_UNITS[metric],
-      });
-    }
-  }
-
-  return { ok: violations.length === 0, checked, violations };
-}
-
-/** Fails the build on the first violation. `x verify` calls this. */
-export function assertBudgets(report: BudgetReport): void {
-  const first = report.violations[0];
-  if (first === undefined) return;
-  throw budgetExceeded(
-    first.route,
-    first.file,
-    first.metric,
-    first.limit,
-    first.actual,
-    first.unit,
-  );
-}