@ultimat3/seo 29.4.0 → 30.0.0

package/CLAUDE.md

@@ -164,6 +164,7 @@ Tier 1. May import `@ultimat3/core`, `@ultimat3/schema`, `@ultimat3/i18n`. Nothi
 | `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 — encodes png/jpeg/webp |
+| `static-export.ts` | the static build's seam (`globalThis`-slotted, like render's asset table): variant URLs as export files, `og.capture` as a 1200 x 630 `og:image`. Absent in a served process — never read a build fact here |
 
 ## Commands
 

package/README.md

@@ -3,6 +3,16 @@
 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.
 
+`bun add @ultimat3/seo` · guide: [SEO](https://github.com/developerz-ai/ultimate/wiki/SEO)
+
+```ts
+import { buildSitemap, type RouteRecord } from '@ultimat3/seo';
+
+declare const routes: readonly RouteRecord[];
+
+await buildSitemap(routes, { baseUrl: 'https://example.com', locales: ['en'], defaultLocale: 'en' });
+```
+
 `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
@@ -46,6 +56,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | File | Owns |
 |---|---|
 | `meta.ts` | the metadata model, `renderMeta()` → head tags: title template, canonical, robots, `og:*`, `twitter:*`, hreflang + `x-default`, `theme-color` per colour scheme. **`robots: { index: false }` withdraws every `og:*`, `article:*` and `twitter:*` tag** — declared or derived; the one opt-in is `socialCard: true` |
+| `static-export.ts` | `setStaticExport()` — the seam a static build installs while it renders: `responsiveImage()` names the export's `/_img/` files instead of `?w=&f=`, and `og: { capture: '/og/<page>' }` (exclusive with `og.image`, by type) becomes `og:image` at 1200 x 630. Unset in a served process, which therefore emits no `og:image` for a capture. `As of 2026-11` |
 | `validate.ts` | the build gate — `validateMeta()` (`--json`-shaped) and `assertMeta()` |
 | `ld.ts` | typed JSON-LD builders; required fields are required in the **input type** |
 | `sitemap.ts` | `buildSitemap()` from the route table + each route's `prerender()`, per-locale alternates. One urlset at `/sitemap.xml`; past a cap (`SITEMAP_MAX_URLS` 50,000, `SITEMAP_MAX_BYTES` 50 MB) the index stays `/sitemap.xml` and the parts are `/sitemaps/<n>.xml` (`SITEMAP_PARTS_DIR`). With `sections` it is always an index of `/sitemaps/<name>-<n>.xml` — see below |
@@ -86,7 +97,7 @@ import { buildSitemap, type RouteRecord } from '@ultimat3/seo';
 declare const routes: readonly RouteRecord[];
 
 await buildSitemap(routes, {
-  baseUrl: 'https://notificado.co',
+  baseUrl: 'https://example.com',
   locales: ['es-co', 'en'],
   defaultLocale: 'es-co',
   maxUrls: 1000,                                      // page size; default 50,000

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "@ultimat3/seo",
-  "version": "29.4.0",
+  "version": "30.0.0",
   "description": "Enforced SEO: typed meta, JSON-LD, sitemap, robots, feeds, responsive images, perf budgets",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "seo",
+    "sitemap",
+    "json-ld",
+    "meta"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/SEO",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -32,7 +42,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "29.4.0",
-    "@ultimat3/schema": "29.4.0"
+    "@ultimat3/core": "30.0.0",
+    "@ultimat3/schema": "30.0.0"
   }
 }

package/src/errors.ts

@@ -20,6 +20,8 @@ export const SEO_ERROR_CODES = {
   imageQueryInvalid: 'X_IMAGE_QUERY_INVALID',
   linkInvalid: 'X_SEO_LINK_INVALID',
   sitemapEntryInvalid: 'X_SITEMAP_ENTRY_INVALID',
+  llmsDescriptionMissing: 'X_SEO_LLMS_DESCRIPTION_MISSING',
+  ogImageConflict: 'X_SEO_OG_IMAGE_CONFLICT',
 } as const;
 
 export type SeoErrorCode = (typeof SEO_ERROR_CODES)[keyof typeof SEO_ERROR_CODES];
@@ -46,6 +48,8 @@ registerErrorCodes({
   X_SITEMAP_ENTRY_INVALID: {
     title: 'a sitemap entry carries a lastmod or a locale the sitemap cannot write',
   },
+  X_SEO_LLMS_DESCRIPTION_MISSING: { title: 'a page listed in llms.txt has no description' },
+  X_SEO_OG_IMAGE_CONFLICT: { title: 'a route meta og declares both image and capture' },
 });
 
 export interface SeoErrorInit {
@@ -134,6 +138,21 @@ export function linkInvalid(link: string, problem: string, file?: string): SeoEr
   });
 }
 
+/**
+ * `meta.og` naming both a hosted `image` and a `capture`: the type forbids it, a cast or a JS
+ * caller does not, and the two renders would disagree (the export publishes the capture, a served
+ * page names no `og:image`). `file` as for `linkInvalid`.
+ */
+export function ogImageConflict(file?: string): SeoError {
+  const where = file === undefined ? 'the route' : file;
+  return new SeoError({
+    code: SEO_ERROR_CODES.ogImageConflict,
+    cause: `${where} declares meta.og with both image and capture`,
+    fix: `og: { image: '/card.png' }   # or og: { capture: '/og/<page>' }, never both, in defineRoute({ meta }) in ${where}`,
+    meta: file === undefined ? {} : { file },
+  });
+}
+
 export function ldInvalid(type: string, field: string, hint: string): SeoError {
   return new SeoError({
     code: SEO_ERROR_CODES.ldInvalid,

package/src/images.ts

@@ -5,6 +5,7 @@
 
 import { canEncode, finiteCount } from '@ultimat3/core';
 import { imageQueryInvalid } from './errors';
+import { currentStaticExport, isExportableSrc } from './static-export';
 import { attributes, escapeXml } from './xml';
 
 /** Ordered widest-first is wrong for `srcset`; browsers want ascending. */
@@ -98,6 +99,18 @@ function defaultUrlFor(src: string, width: number, format?: string): string {
   return `${src}${separator}${widthParam}${formatParam}`;
 }
 
+/**
+ * The variant URL while a static export renders: a FILE path the export writes, because a dumb
+ * file server ignores `?w=&f=` and hands back the full original under a `<source type="image/webp">`.
+ * `undefined` in a served process (no export installed) and for a remote `src`, which keep the
+ * query URLs the media route — or a CDN — answers. A caller's own `urlFor` always wins.
+ */
+function exportUrlFor(src: string): ResponsiveImageOptions['urlFor'] {
+  const exported = currentStaticExport();
+  if (exported === undefined || !isExportableSrc(src)) return undefined;
+  return (from, width, format) => exported.imageUrl({ src: from, width, format });
+}
+
 export interface ImageQuery {
   readonly width?: number | undefined;
   readonly format?: string | undefined;
@@ -220,7 +233,7 @@ export function responsiveImage(
   input: ImageInput,
   options: ResponsiveImageOptions = {},
 ): ResponsiveImage {
-  const urlFor = options.urlFor ?? defaultUrlFor;
+  const urlFor = options.urlFor ?? exportUrlFor(input.src) ?? defaultUrlFor;
   const widths = usableWidths(input.width, options.widths ?? DEFAULT_WIDTHS);
   const sizes = input.sizes ?? '100vw';
   const formats = options.formats ?? DEFAULT_FORMATS;

package/src/index.ts

@@ -76,6 +76,8 @@ export {
 } from './ld';
 export type { HeadLink, HeadLinkAs, HeadLinkRel } from './links';
 export { linkProblem } from './links';
+export type { LlmsSite } from './llms';
+export { buildLlmsTxt, LLMS_PATH, llmsDescriptionIssues } from './llms';
 export type { LocalizedPage, MetaLocalization } from './locale-tags';
 export { hreflangTag, ogLocaleTag } from './locale-tags';
 export type {
@@ -123,6 +125,8 @@ export {
 export { sitemapDatetime } from './sitemap-datetime';
 export type { SitemapSection } from './sitemap-sections';
 export { sectionOf } from './sitemap-sections';
+export type { StaticExport, StaticImageRequest } from './static-export';
+export { currentStaticExport, isExportableSrc, setStaticExport } from './static-export';
 export type { MetaIssue, MetaValidationReport, ValidateMetaOptions } from './validate';
 export { assertMeta, validateMeta } from './validate';
 export { absoluteUrl, escapeXml } from './xml';

package/src/llms.ts

@@ -0,0 +1,74 @@
+// Single responsibility: `/llms.txt` — the site's public pages, by title and description, for a
+// language model — built from the same route records the sitemap reads. One answer, served by a
+// running web role and written by the static export alike, and empty outside production for
+// `robots.txt`'s reason: a branch deploy must not be what a model learns the site from.
+
+import type { Environment } from '@ultimat3/core';
+import { DEFAULT_ENVIRONMENT, tryResolveEnvironment } from '@ultimat3/core';
+import { SEO_ERROR_CODES } from './errors';
+import { isIndexable } from './robots';
+import type { RouteRecord } from './routes';
+import { isDynamic } from './routes';
+import type { MetaIssue } from './validate';
+import { absoluteUrl } from './xml';
+
+export const LLMS_PATH = '/llms.txt';
+
+export interface LlmsSite {
+  readonly baseUrl: string;
+  /** Omitted: `ULTIMATE_ENV`. Anything but `production` answers an empty document. */
+  readonly environment?: Environment | undefined;
+  /** `seo.llms` — `false` answers an empty document everywhere. */
+  readonly enabled?: boolean | undefined;
+}
+
+/** A listed page: an indexable `site/` route whose meta resolved without a request. */
+const listed = (route: RouteRecord): boolean =>
+  route.surface === 'site' &&
+  route.noindex !== true &&
+  route.meta?.robots?.index !== false &&
+  route.meta?.title !== undefined &&
+  !isDynamic(route.path);
+
+/** One line, so a newline in a title cannot open a second Markdown entry. */
+const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim();
+const linkText = (text: string): string => oneLine(text).replace(/[[\]]/g, '\\$&');
+
+/**
+ * `# <home title>`, `> <home description>`, then `- [title](url): description` per listed page,
+ * in path order. The home page names the site: no second site name to keep in step with its title.
+ */
+export function buildLlmsTxt(routes: readonly RouteRecord[], site: LlmsSite): string {
+  const environment = site.environment ?? tryResolveEnvironment() ?? DEFAULT_ENVIRONMENT;
+  if (site.enabled === false || !isIndexable(environment)) return '';
+  const pages = routes
+    .filter(listed)
+    .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const home = pages.find((route) => route.path === '/');
+  const lines = [`# ${oneLine(home?.meta?.title ?? site.baseUrl)}`, ''];
+  const summary = home?.meta?.description;
+  if (summary !== undefined) lines.push(`> ${oneLine(summary)}`, '');
+  for (const route of pages) {
+    const description = route.meta?.description;
+    const link = `- [${linkText(route.meta?.title ?? route.path)}](${absoluteUrl(site.baseUrl, route.path)})`;
+    lines.push(description === undefined ? link : `${link}: ${oneLine(description)}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * The convention's build error: every page `/llms.txt` lists says what it is. The `seo` step asks
+ * only while `seo.llms` is on; a page with no description is a line that tells a model nothing.
+ * `validateMeta`'s issue shape, so the step reports both through one projection.
+ */
+export function llmsDescriptionIssues(routes: readonly RouteRecord[]): readonly MetaIssue[] {
+  return routes
+    .filter((route) => listed(route) && route.meta?.description === undefined)
+    .map((route) => ({
+      code: SEO_ERROR_CODES.llmsDescriptionMissing,
+      route: route.path,
+      file: route.file,
+      cause: `${route.file} (route "${route.path}") is listed in /llms.txt and has no meta.description, so its line says nothing about the page`,
+      fix: `x verify --only seo --json   # then add description to defineRoute({ meta }) in ${route.file}, or set seo: { llms: false } in app.config.ts`,
+    }));
+}

package/src/meta.ts

@@ -2,8 +2,10 @@
 // for a global default: a route that does not declare a description does not get
 // one, it fails the build (see validate.ts).
 
+import { ogImageConflict } from './errors';
 import { type HeadLink, linkTags } from './links';
 import { hreflangTag, type MetaLocalization, ogLocaleTag } from './locale-tags';
+import { currentStaticExport } from './static-export';
 import { absoluteUrl } from './xml';
 
 /**
@@ -32,14 +34,13 @@ export interface OpenGraphImage {
   type?: string;
 }
 
-export interface OpenGraph {
+interface OpenGraphFields {
   type?: 'website' | 'article' | 'profile' | 'product' | 'video.other';
   title?: string;
   description?: string;
   url?: string;
   siteName?: string;
   locale?: string;
-  image?: string | OpenGraphImage;
   publishedTime?: string;
   modifiedTime?: string;
   author?: string;
@@ -47,6 +48,20 @@ export interface OpenGraph {
   tags?: readonly string[];
 }
 
+/**
+ * The card's picture: a URL you host (`image`), or a `site/` page the static build photographs at
+ * 1200 x 630 (`capture: '/og/post/hello'`, a concrete path) — one or the other, never both, which
+ * the type refuses. A captured card is written to `/_og/<path>.png` and stamped as `og:image` with
+ * its size by `x build --target static`; a served document carries no `og:image` for it, because
+ * the container holds neither the export's PNG nor a browser to take one, and an `og:image` naming
+ * a file nothing serves is a broken preview a crawler caches. Served, the card is `image`'s.
+ */
+export type OpenGraph = OpenGraphFields &
+  (
+    | { image?: string | OpenGraphImage; capture?: undefined }
+    | { capture: string; image?: undefined }
+  );
+
 export interface TwitterCard {
   card?: 'summary' | 'summary_large_image' | 'app' | 'player';
   site?: string;
@@ -269,8 +284,12 @@ function socialTags(
       });
     }
   }
-  if (og.image !== undefined) {
-    const image = typeof og.image === 'string' ? { url: og.image } : og.image;
+  // A capture is the export's to publish (`static-export.ts`); served, it has no file to name.
+  if (og.image !== undefined && og.capture !== undefined) throw ogImageConflict();
+  const declared =
+    og.capture === undefined ? og.image : currentStaticExport()?.cardImage(og.capture);
+  if (declared !== undefined) {
+    const image = typeof declared === 'string' ? { url: declared } : declared;
     tags.push({ tag: 'meta', attrs: { property: 'og:image', content: abs(image.url) } });
     if (image.width !== undefined) {
       tags.push({
@@ -306,7 +325,7 @@ function socialTags(
   // --- Twitter ---------------------------------------------------------------
   const twitter = meta.twitter ?? {};
   const twitterEntries: Array<[string, string | undefined]> = [
-    ['twitter:card', twitter.card ?? (og.image === undefined ? 'summary' : 'summary_large_image')],
+    ['twitter:card', twitter.card ?? (declared === undefined ? 'summary' : 'summary_large_image')],
     ['twitter:site', twitter.site],
     ['twitter:creator', twitter.creator],
     ['twitter:title', og.title ?? meta.title],

package/src/static-export.ts

@@ -0,0 +1,49 @@
+// The seam a static export installs while it renders: where an image variant and a captured social
+// card live as FILES. Absent at serve time, so a served document never pays for it — and a dumb
+// file server ignores `?w=&f=`, which is why the export cannot use the query URLs the media route
+// answers. The exporter owns the files; this package only asks it for their URLs.
+
+import type { OpenGraphImage } from './meta';
+
+/** One variant a document asked for: `format` undefined is the source's own encoding. */
+export interface StaticImageRequest {
+  readonly src: string;
+  readonly width: number;
+  readonly format: string | undefined;
+}
+
+export interface StaticExport {
+  /** The site path one variant is written at, e.g. `/_img/3f2a1b9c-640.webp`. Records it. */
+  imageUrl(request: StaticImageRequest): string;
+  /** The `og:image` a declared `og.capture` is published as. Records the capture. */
+  cardImage(capturePath: string): OpenGraphImage;
+}
+
+/**
+ * Registered globally, like render's asset table, so two copies of this module — the app's and the
+ * CLI's, resolved through different `node_modules` — read the seam the one export installed.
+ */
+const SLOT: unique symbol = Symbol.for('ultimate.seo.staticExport') as never;
+
+interface Holder {
+  [SLOT]?: StaticExport | undefined;
+}
+
+const holder = globalThis as unknown as Holder;
+
+/** Installed by the static export around its renders; `undefined` uninstalls. */
+export function setStaticExport(exported: StaticExport | undefined): void {
+  holder[SLOT] = exported;
+}
+
+/** The installed export, or `undefined` — always `undefined` in a served process. */
+export function currentStaticExport(): StaticExport | undefined {
+  return holder[SLOT];
+}
+
+/**
+ * A `src` the export reads from its own tree: a site path. A remote URL (`https:`, `//`) or an
+ * inline `data:` image is somebody else's bytes, and keeps the query URL a CDN may answer.
+ */
+export const isExportableSrc = (src: string): boolean =>
+  src.startsWith('/') && !src.startsWith('//');

package/src/validate.ts

@@ -10,6 +10,7 @@ import {
   duplicateMeta,
   metaMissing,
   metaTooLong,
+  ogImageConflict,
   SeoError,
   type SeoErrorCode,
   titleTemplateSlotMissing,
@@ -138,6 +139,11 @@ export function validateMeta(
       }
     }
 
+    // The renderer's refusal, at the route FILE and before any request.
+    if (meta.og?.image !== undefined && meta.og.capture !== undefined) {
+      issues.push(issueOf(ogImageConflict(route.file), route.path, route.file));
+    }
+
     // A canonical is only checkable for a static path: a dynamic route's
     // canonical is produced per-item at render time.
     if (meta.canonical !== undefined && options.baseUrl !== undefined && !isDynamic(route.path)) {