@ultimat3/seo 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# @ultimat3/seo 🔍
+
+SEO is **enforced, not documented**. These are build errors, not lint warnings.
+
+## What fails the build
+
+| Code | Trigger | Why it is fatal |
+|---|---|---|
+| `X_SEO_META_MISSING` | a `site/` route with no `meta.title` or `meta.description` | a page with no description gets a snippet Google invents; that is the one string you cannot fix after launch |
+| `X_SEO_DUPLICATE_META` | two routes share a title or description | duplicate meta makes the pages compete with each other, and the wrong one wins |
+| `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 |
+
+Every error names the exact route **file** and the exact edit:
+
+```
+X_SEO_META_MISSING: a site/ route is missing required metadata
+  cause: apps/web/site/about/page.tsx (route "/about") has no meta.description
+  fix:   add description to defineRoute({ meta }) in apps/web/site/about/page.tsx
+```
+
+## Modules
+
+| File | Owns |
+|---|---|
+| `meta.ts` | the metadata model, `renderMeta()` → head tags: title template, canonical, robots, `og:*`, `twitter:*`, hreflang + `x-default`, `theme-color` per colour scheme |
+| `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, 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 |
+| `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
+
+```ts
+ld.Article({ headline: 'Ship it', author: { name: 'Ada' } });
+//  ^ error: Property 'datePublished' is missing — required by schema.org
+```
+
+A missing `datePublished` is a compile error, not a Search Console warning three
+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:
+
+```
+User-agent: *
+Disallow: /
+```
+
+No sitemap line either — advertising one invites the crawl that was just refused.
+
+## Image transforms
+
+`builtinImageDriver({ read })` is the one built-in `ImageTransformDriver`, and it runs
+`@ultimat3/core`'s pipeline — zero dependencies, no `sharp`, no native binary.
+
+```ts
+const images = builtinImageDriver({ read: (src) => Bun.file(`public${src}`).bytes() });
+
+// a 1200x630 source
+await images.transform({ src: '/img/hero.png', width: 640 });
+// → { bytes, contentType: 'image/jpeg', width: 640, height: 336 }
+await images.blurPlaceholder('/img/hero.png');
+// → 'data:image/png;base64,…'
+```
+
+| | |
+|---|---|
+| decodes | `png`, `jpeg` |
+| encodes | `png`, `jpeg` |
+| probes only | `webp`, `avif`, `gif`, `svg` — intrinsic size, never a transform |
+
+- **`read` is required.** `src` is a string and only the app knows whether it is a path, a
+  storage key or a URL. Guessing would mean a filesystem read off a URL-shaped string.
+- **No `format` → the pixels decide:** PNG when the raster has alpha, JPEG otherwise. A logo
+  never grows a black background because nobody passed a format.
+- **`format: 'avif'` or `'webp'` → `X_IMAGE_UNSUPPORTED`,** with the fix line. Those `<source>`
+  entries need a CDN driver; the framework will not pretend to encode what it cannot.
+- **`width`/`height` are probed off the output bytes,** never echoed from the request. A width
+  above the intrinsic one clamps to the source and reports the source's size, so the box the
+  browser reserves is the box the bytes fill.
+- `blurPlaceholder()` returns a 16px-wide PNG `data:` URI, ready for `ImageInput.blurDataUrl`.
+
+### Reading the URL back
+
+`images.ts` mints `?w=&f=` query strings; `parseImageQuery()` is the only place that reads one
+back, so a server route never hand-rolls its own parsing of what `responsiveImage()` wrote.
+
+```ts
+const query = parseImageQuery(new URL(req.url).searchParams);
+// null: none of w/f/q was present — a plain asset read, not a transform.
+if (query !== null) {
+  await images.transform({
+    src,
+    // `?f=webp` alone still needs a width, and the source's own is the only one that resizes
+    // nothing the caller did not ask to resize.
+    width: query.width ?? intrinsicWidth,
+    // Spread, not `format: query.format`: `TransformRequest` declares both keys optional and
+    // `exactOptionalPropertyTypes` refuses an explicit `undefined`. Forward all three or `?q=75`
+    // parses and is then silently dropped.
+    ...(query.format === undefined ? {} : { format: query.format }),
+    ...(query.quality === undefined ? {} : { quality: query.quality }),
+  });
+}
+```
+
+- **`null`** means no transform was asked for. A present-but-unusable `w` or `q` — empty, `0`,
+  negative, fractional, longer than an exact integer, or `q` over 100 — throws
+  `X_IMAGE_QUERY_INVALID` instead: serving the untransformed original against a `?w=320` URL is
+  the layout shift this contract exists to prevent.
+- **`f` is not checked against real format names here.** `?f=potato` parses fine; `transform()`
+  is what refuses an unencodable format, with `X_IMAGE_UNSUPPORTED`.
+- **`IMAGE_QUERY_KEYS`** (`{ width: 'w', format: 'f', quality: 'q' }`) is the one spelling of the
+  three keys — `defaultUrlFor` and `parseImageQuery` both read it, so the two can never drift.
+
+## Usage
+
+```ts
+export const config = defineRoute({
+  render: 'isr',
+  prerender: () => db.posts.slugs(),
+  meta: ({ post }) => ({
+    title: post.title,
+    titleTemplate: '%s — Ultimate',
+    description: post.excerpt,
+    og: { type: 'article', image: post.cover, publishedTime: post.publishedAt },
+    alternates: post.locales.map((l) => ({ hreflang: l, href: `/${l}/blog/${post.slug}` })),
+    ld: [ld.Article({ headline: post.title, datePublished: post.publishedAt, author: post.author })],
+  }),
+  budget: { js: '0kb', lcp: 2000 },
+});
+```
+
+## Commands
+
+```
+bun test                 # meta, validation, JSON-LD, sitemap, robots, feeds, images, budgets
+bun run typecheck
+```

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@ultimat3/seo",
+  "version": "1.0.0",
+  "description": "Enforced SEO: typed meta, JSON-LD, sitemap, robots, feeds, responsive images, perf budgets",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/seo"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "1.0.0"
+  }
+}

package/src/budgets.ts

@@ -0,0 +1,127 @@
+// 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,
+  );
+}

package/src/errors.ts

@@ -0,0 +1,177 @@
+// @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.
+
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+// errors.ts <-> images.ts: images.ts throws imageQueryInvalid() and this file spells its fix
+// using images.ts's IMAGE_QUERY_KEYS. Safe like core's errors.ts <-> error-codes.ts cycle:
+// nothing at this module's top level reads the import, only the factory body below does, and by
+// the time that runs both modules have finished loading.
+import { IMAGE_QUERY_KEYS } from './images';
+
+export const SEO_ERROR_CODES = {
+  metaMissing: 'X_SEO_META_MISSING',
+  duplicateMeta: 'X_SEO_DUPLICATE_META',
+  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;
+
+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.
+ * `X_NOT_IMPLEMENTED` and `X_IMAGE_UNSUPPORTED` are core's; `SeoError` throws them, untitled here.
+ */
+registerErrorCodes({
+  X_SEO_META_MISSING: { title: 'a site/ route is missing required metadata' },
+  X_SEO_DUPLICATE_META: { title: 'two routes share a title or description' },
+  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' },
+});
+
+export interface SeoErrorInit {
+  readonly code: SeoErrorCode | 'X_NOT_IMPLEMENTED';
+  readonly cause: string;
+  readonly fix: string;
+  readonly meta?: Readonly<Record<string, unknown>>;
+}
+
+export class SeoError extends UltimateError {
+  override readonly name: string = 'SeoError';
+
+  constructor(init: SeoErrorInit) {
+    super({
+      code: init.code,
+      cause: init.cause,
+      fix: init.fix,
+      docs: `https://ultimate.dev/errors/${init.code}`,
+      meta: init.meta,
+    });
+  }
+}
+
+/** A `site/` route without a title or description. Names the file, not the URL. */
+export function metaMissing(file: string, path: string, field: string): SeoError {
+  return new SeoError({
+    code: SEO_ERROR_CODES.metaMissing,
+    cause: `${file} (route "${path}") has no meta.${field}`,
+    fix: `add ${field} to defineRoute({ meta }) in ${file}`,
+    meta: { file, path, field },
+  });
+}
+
+export function duplicateMeta(field: string, value: string, files: readonly string[]): SeoError {
+  return new SeoError({
+    code: SEO_ERROR_CODES.duplicateMeta,
+    cause: `${files.length} routes share the same ${field} ${JSON.stringify(value)}: ${files.join(', ')}`,
+    fix: `give each route a unique ${field} in its defineRoute({ meta })`,
+    meta: { field, value, files },
+  });
+}
+
+export function metaTooLong(file: string, field: string, length: number, max: number): SeoError {
+  return new SeoError({
+    code: SEO_ERROR_CODES.metaTooLong,
+    cause: `${file} has a ${length}-character ${field}; search results truncate past ${max}`,
+    fix: `shorten meta.${field} in ${file} to <= ${max} characters`,
+    meta: { file, field, length, max },
+  });
+}
+
+export function canonicalMismatch(file: string, canonical: string, expected: string): SeoError {
+  return new SeoError({
+    code: SEO_ERROR_CODES.canonicalMismatch,
+    cause: `${file} declares canonical ${canonical} but the route resolves to ${expected}`,
+    fix: `set meta.canonical to ${expected} in ${file}, or delete it and let the route supply it`,
+    meta: { file, canonical, expected },
+  });
+}
+
+export function ldInvalid(type: string, field: string, hint: string): SeoError {
+  return new SeoError({
+    code: SEO_ERROR_CODES.ldInvalid,
+    cause: `ld.${type}() received an empty or missing "${field}" (${hint})`,
+    fix: `provide a non-empty ${field} to ld.${type}(); it is required by schema.org`,
+    meta: { type, field },
+  });
+}
+
+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,
+    cause: `sitemap index would hold ${count} sitemaps; the protocol limit is ${max}`,
+    fix: 'exclude non-indexable routes with noindex, or shard the site across hostnames',
+    meta: { count, max },
+  });
+}
+
+/**
+ * `parseImageQuery`'s only refusal: a `?w=`/`?q=`/`?f=` value present but not usable — serving
+ * the untransformed original against a URL that asked for a size would be the layout shift this
+ * contract exists to prevent, so an unusable value throws instead of falling back silently. A
+ * format string naming no *real* encoder is a different failure (`image-driver.ts`'s
+ * `X_IMAGE_UNSUPPORTED`); this code never covers it.
+ *
+ * The `fix` is written as an inline ternary, not a helper call, so the `errors` gate step can
+ * still read each branch as a literal — a `fix` computed behind a function call has nothing for
+ * a static scan to check, and the gate would silently wave the whole thing through.
+ */
+export function imageQueryInvalid(param: string, value: string, reason: string): SeoError {
+  return new SeoError({
+    code: SEO_ERROR_CODES.imageQueryInvalid,
+    cause: `?${param}=${value} is not usable: ${reason}`,
+    fix:
+      param === IMAGE_QUERY_KEYS.quality
+        ? `request ?${IMAGE_QUERY_KEYS.quality}=75 — a whole number from 1 to 100`
+        : param === IMAGE_QUERY_KEYS.format
+          ? `request ?${IMAGE_QUERY_KEYS.format}=webp — a non-empty format name`
+          : `request ?${IMAGE_QUERY_KEYS.width}=640 with a positive integer width`,
+    meta: { param, value, reason },
+  });
+}
+
+/**
+ * The vocabulary a **user-supplied** `ImageTransformDriver` uses to report a capability it
+ * does not implement — a CDN driver with no blur endpoint, say. `builtinImageDriver` needs it
+ * for nothing; it implements both entry points. Exported so a partial driver fails with a code
+ * and a fix instead of returning an unoptimised original and calling that a transform.
+ *
+ * `at` is the driver's own module path — pass `import.meta.path`. It is required because
+ * `driver` is a display name, and a fix an agent cannot open is not a fix.
+ */
+export function notImplementedDriver(driver: string, capability: string, at: string): SeoError {
+  return new SeoError({
+    code: 'X_NOT_IMPLEMENTED',
+    cause: `the ${driver} image driver does not implement ${capability} yet`,
+    fix:
+      `implement ${capability} in ${at}, or swap the driver for builtinImageDriver({ read }) ` +
+      '— png and jpeg, no dependencies — then run: x verify --json',
+    meta: { driver, capability, at },
+  });
+}

package/src/image-driver.ts

@@ -0,0 +1,91 @@
+// The bytes half of the image contract: `images.ts` decides what the markup promises, this
+// file produces the variant that promise refers to. Split because they fail differently — a
+// wrong `srcset` is a pure-function bug, a wrong variant is a decode — and because a project
+// swapping in a CDN replaces only this half.
+
+import {
+  blurDataUrl,
+  IMAGE_FORMATS,
+  IMAGE_MIME_TYPES,
+  type ImageFormat,
+  imageUnsupported,
+  probeImage,
+  transformImageBytes,
+} from '@ultimat3/core';
+
+export interface TransformRequest {
+  src: string;
+  width: number;
+  format?: string;
+  quality?: number;
+}
+
+export interface TransformedImage {
+  bytes: Uint8Array;
+  contentType: string;
+  width: number;
+  height: number;
+}
+
+/** Swappable so a project can route transforms through a CDN instead. */
+export interface ImageTransformDriver {
+  readonly name: string;
+  transform(request: TransformRequest): Promise<TransformedImage>;
+  /** Tiny base64 data URI (typically a 16px-wide blur) for the placeholder. */
+  blurPlaceholder(src: string): Promise<string>;
+}
+
+export interface BuiltinImageDriverOptions {
+  /**
+   * Resolves a `src` to its bytes. Required: seo must not guess whether a src is a path, a
+   * storage key or a URL — reading the filesystem off a URL-shaped string is exactly the
+   * ambient default this package forbids everywhere else.
+   */
+  readonly read: (src: string) => Promise<Uint8Array>;
+  /** Default JPEG quality for lossy output. */
+  readonly quality?: number | undefined;
+}
+
+const isImageFormat = (value: string): value is ImageFormat =>
+  (IMAGE_FORMATS as readonly string[]).includes(value);
+
+/** A string naming no format at all fails with the same code an unencodable format does. */
+function requestedFormat(format: string | undefined): ImageFormat | undefined {
+  if (format === undefined || isImageFormat(format)) return format;
+  throw imageUnsupported(
+    `"${format}" names no image format`,
+    `request one of ${IMAGE_FORMATS.join(', ')}, or omit format to keep the source's`,
+    { format },
+  );
+}
+
+/**
+ * The zero-dependency pipeline in `@ultimat3/core`: PNG and JPEG in, PNG and JPEG out.
+ * `<picture>` still offers AVIF and WebP, but nothing here synthesises them — asking for one
+ * raises core's `X_IMAGE_UNSUPPORTED`, and those variants belong on a CDN driver instead.
+ */
+export function builtinImageDriver(options: BuiltinImageDriverOptions): ImageTransformDriver {
+  return {
+    name: 'builtin',
+    async transform(request: TransformRequest): Promise<TransformedImage> {
+      const bytes = transformImageBytes(await options.read(request.src), {
+        width: request.width,
+        // Omitted means core picks by the pixels: PNG when the raster has alpha.
+        format: requestedFormat(request.format),
+        quality: request.quality ?? options.quality,
+      });
+      // Read back off the output, never assumed: a width clamped to the source has to report
+      // the source's size, or the box the browser reserved is the wrong one.
+      const info = probeImage(bytes);
+      return {
+        bytes,
+        contentType: IMAGE_MIME_TYPES[info.format],
+        width: info.width,
+        height: info.height,
+      };
+    },
+    async blurPlaceholder(src: string): Promise<string> {
+      return blurDataUrl(await options.read(src));
+    },
+  };
+}