@ultimat3/seo 1.0.0

package/src/meta.ts

@@ -0,0 +1,269 @@
+// The typed metadata model and its rendering to head tags. Nothing here reaches
+// 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';
+
+/** Search results truncate past this; validate.ts enforces it. */
+export const TITLE_MAX_LENGTH = 60;
+export const DESCRIPTION_MIN_LENGTH = 50;
+export const DESCRIPTION_MAX_LENGTH = 160;
+
+export interface RobotsDirectives {
+  index?: boolean;
+  follow?: boolean;
+  maxSnippet?: number;
+  maxImagePreview?: 'none' | 'standard' | 'large';
+  maxVideoPreview?: number;
+  noarchive?: boolean;
+}
+
+export interface OpenGraphImage {
+  url: string;
+  /** 1200x630 is the card size every platform crops from. */
+  width?: number;
+  height?: number;
+  alt?: string;
+  type?: string;
+}
+
+export interface OpenGraph {
+  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;
+  section?: string;
+  tags?: readonly string[];
+}
+
+export interface TwitterCard {
+  card?: 'summary' | 'summary_large_image' | 'app' | 'player';
+  site?: string;
+  creator?: string;
+  image?: string;
+  imageAlt?: string;
+}
+
+export interface AlternateLocale {
+  /** BCP-47 tag, or `x-default`. */
+  hreflang: string;
+  href: string;
+}
+
+export interface ThemeColor {
+  /** Any CSS colour. Pull it from @ultimat3/ui's tokens at the call site. */
+  color: string;
+  scheme?: 'light' | 'dark';
+}
+
+export interface RouteMeta {
+  title?: string;
+  /** `'%s — Ultimate'`. Applied unless the title already contains the brand. */
+  titleTemplate?: string;
+  description?: string;
+  canonical?: string;
+  robots?: RobotsDirectives;
+  og?: OpenGraph;
+  twitter?: TwitterCard;
+  /** One entry per locale. `x-default` is added automatically when absent. */
+  alternates?: readonly AlternateLocale[];
+  /** The href `x-default` points at. Defaults to the canonical. */
+  xDefault?: string;
+  themeColor?: readonly ThemeColor[];
+  /** JSON-LD nodes from `ld.*`. Rendered as one script tag per node. */
+  ld?: readonly Readonly<Record<string, unknown>>[];
+}
+
+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. */
+  readonly text?: string;
+}
+
+export interface RenderMetaOptions {
+  /** Absolutises canonical, og:url, and alternates. */
+  baseUrl?: string;
+  /** Resolved path, used when `canonical` is omitted. */
+  path?: string;
+}
+
+export function applyTitleTemplate(title: string, template?: string): string {
+  if (template === undefined || template === '') return title;
+  return template.includes(title) ? title : template.replace('%s', title);
+}
+
+export function robotsContent(directives: RobotsDirectives): string {
+  const parts: string[] = [
+    directives.index === false ? 'noindex' : 'index',
+    directives.follow === false ? 'nofollow' : 'follow',
+  ];
+  if (directives.noarchive === true) parts.push('noarchive');
+  if (directives.maxSnippet !== undefined) parts.push(`max-snippet:${directives.maxSnippet}`);
+  if (directives.maxImagePreview !== undefined) {
+    parts.push(`max-image-preview:${directives.maxImagePreview}`);
+  }
+  if (directives.maxVideoPreview !== undefined) {
+    parts.push(`max-video-preview:${directives.maxVideoPreview}`);
+  }
+  return parts.join(',');
+}
+
+/**
+ * Full alternate set including `x-default`, which tells search engines which
+ * URL to serve when no declared locale matches the user. Omitting it is the most
+ * common i18n SEO bug, so it is added rather than merely allowed.
+ */
+export function hreflangSet(
+  alternates: readonly AlternateLocale[],
+  fallbackHref: string | undefined,
+): readonly AlternateLocale[] {
+  if (alternates.length === 0) return [];
+  const hasDefault = alternates.some((entry) => entry.hreflang === 'x-default');
+  if (hasDefault) return alternates;
+  const href = fallbackHref ?? alternates[0]?.href;
+  return href === undefined ? alternates : [...alternates, { hreflang: 'x-default', href }];
+}
+
+export function renderMeta(meta: RouteMeta, options: RenderMetaOptions = {}): readonly HeadTag[] {
+  const tags: HeadTag[] = [];
+  const abs = (value: string): string =>
+    options.baseUrl === undefined ? value : absoluteUrl(options.baseUrl, value);
+
+  const canonical = meta.canonical ?? (options.path === undefined ? undefined : options.path);
+  const canonicalHref = canonical === undefined ? undefined : abs(canonical);
+
+  if (meta.title !== undefined) {
+    tags.push({
+      tag: 'title',
+      attrs: {},
+      text: applyTitleTemplate(meta.title, meta.titleTemplate),
+    });
+  }
+  if (meta.description !== undefined) {
+    tags.push({ tag: 'meta', attrs: { name: 'description', content: meta.description } });
+  }
+  if (canonicalHref !== undefined) {
+    tags.push({ tag: 'link', attrs: { rel: 'canonical', href: canonicalHref } });
+  }
+  tags.push({
+    tag: 'meta',
+    attrs: { name: 'robots', content: robotsContent(meta.robots ?? {}) },
+  });
+
+  // --- Open Graph ------------------------------------------------------------
+  const og = meta.og ?? {};
+  const ogEntries: Array<[string, string | undefined]> = [
+    ['og:type', og.type ?? 'website'],
+    ['og:title', og.title ?? meta.title],
+    ['og:description', og.description ?? meta.description],
+    ['og:url', og.url === undefined ? canonicalHref : abs(og.url)],
+    ['og:site_name', og.siteName],
+    ['og:locale', og.locale],
+  ];
+  for (const [property, content] of ogEntries) {
+    if (content !== undefined) tags.push({ tag: 'meta', attrs: { property, content } });
+  }
+  if (og.image !== undefined) {
+    const image = typeof og.image === 'string' ? { url: og.image } : og.image;
+    tags.push({ tag: 'meta', attrs: { property: 'og:image', content: abs(image.url) } });
+    if (image.width !== undefined) {
+      tags.push({
+        tag: 'meta',
+        attrs: { property: 'og:image:width', content: String(image.width) },
+      });
+    }
+    if (image.height !== undefined) {
+      tags.push({
+        tag: 'meta',
+        attrs: { property: 'og:image:height', content: String(image.height) },
+      });
+    }
+    if (image.alt !== undefined) {
+      tags.push({ tag: 'meta', attrs: { property: 'og:image:alt', content: image.alt } });
+    }
+  }
+  if (og.type === 'article') {
+    const articleEntries: Array<[string, string | undefined]> = [
+      ['article:published_time', og.publishedTime],
+      ['article:modified_time', og.modifiedTime],
+      ['article:author', og.author],
+      ['article:section', og.section],
+    ];
+    for (const [property, content] of articleEntries) {
+      if (content !== undefined) tags.push({ tag: 'meta', attrs: { property, content } });
+    }
+    for (const tag of og.tags ?? []) {
+      tags.push({ tag: 'meta', attrs: { property: 'article:tag', content: tag } });
+    }
+  }
+
+  // --- Twitter ---------------------------------------------------------------
+  const twitter = meta.twitter ?? {};
+  const twitterEntries: Array<[string, string | undefined]> = [
+    ['twitter:card', twitter.card ?? (og.image === undefined ? 'summary' : 'summary_large_image')],
+    ['twitter:site', twitter.site],
+    ['twitter:creator', twitter.creator],
+    ['twitter:title', og.title ?? meta.title],
+    ['twitter:description', og.description ?? meta.description],
+    ['twitter:image', twitter.image === undefined ? undefined : abs(twitter.image)],
+    ['twitter:image:alt', twitter.imageAlt],
+  ];
+  for (const [name, content] of twitterEntries) {
+    if (content !== undefined) tags.push({ tag: 'meta', attrs: { name, content } });
+  }
+
+  // --- hreflang --------------------------------------------------------------
+  for (const alternate of hreflangSet(meta.alternates ?? [], meta.xDefault ?? canonicalHref)) {
+    tags.push({
+      tag: 'link',
+      attrs: { rel: 'alternate', hreflang: alternate.hreflang, href: abs(alternate.href) },
+    });
+  }
+
+  // --- theme-color per colour scheme ----------------------------------------
+  for (const entry of meta.themeColor ?? []) {
+    tags.push({
+      tag: 'meta',
+      attrs:
+        entry.scheme === undefined
+          ? { name: 'theme-color', content: entry.color }
+          : {
+              name: 'theme-color',
+              media: `(prefers-color-scheme: ${entry.scheme})`,
+              content: entry.color,
+            },
+    });
+  }
+
+  // --- JSON-LD ---------------------------------------------------------------
+  for (const node of meta.ld ?? []) {
+    tags.push({
+      tag: 'script',
+      attrs: { type: 'application/ld+json' },
+      text: JSON.stringify(node),
+    });
+  }
+
+  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');
+}

package/src/robots.ts

@@ -0,0 +1,79 @@
+// 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.
+
+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[];
+  allow?: readonly string[];
+  disallow?: readonly string[];
+  crawlDelay?: number;
+}
+
+export interface RobotsConfig {
+  baseUrl: string;
+  /** Omitted means "resolve from the environment", which defaults to preview. */
+  environment?: SeoEnvironment | undefined;
+  groups?: readonly RobotsGroup[];
+  /** Sitemap paths or absolute URLs. Only emitted in production. */
+  sitemaps?: readonly string[];
+  /** Extra lines appended verbatim, e.g. a `Host:` directive. */
+  extra?: readonly string[];
+}
+
+/**
+ * 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`.
+ */
+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: SeoEnvironment): boolean {
+  return environment === 'production';
+}
+
+function agents(userAgent: string | readonly string[]): readonly string[] {
+  return typeof userAgent === 'string' ? [userAgent] : userAgent;
+}
+
+export function buildRobots(config: RobotsConfig): string {
+  const environment = config.environment ?? resolveEnvironment();
+  const lines: string[] = [`# environment: ${environment}`];
+
+  if (!isIndexable(environment)) {
+    // No sitemap either: advertising one invites a crawl we just refused.
+    lines.push('User-agent: *', 'Disallow: /');
+    return `${lines.join('\n')}\n`;
+  }
+
+  const groups: readonly RobotsGroup[] =
+    config.groups === undefined || config.groups.length === 0
+      ? [{ userAgent: '*', allow: ['/'] }]
+      : config.groups;
+
+  for (const group of groups) {
+    for (const agent of agents(group.userAgent)) lines.push(`User-agent: ${agent}`);
+    for (const path of group.allow ?? []) lines.push(`Allow: ${path}`);
+    for (const path of group.disallow ?? []) lines.push(`Disallow: ${path}`);
+    if (group.crawlDelay !== undefined) lines.push(`Crawl-delay: ${group.crawlDelay}`);
+    lines.push('');
+  }
+
+  for (const sitemap of config.sitemaps ?? ['/sitemap.xml']) {
+    lines.push(`Sitemap: ${absoluteUrl(config.baseUrl, sitemap)}`);
+  }
+  for (const line of config.extra ?? []) lines.push(line);
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}

package/src/routes.ts

@@ -0,0 +1,62 @@
+// The route-table shape @ultimat3/seo consumes. Emitted by the framework into
+// `x.manifest.json`; every checker here reports against `file`, so an agent can
+// open the exact source rather than guess which route a URL came from.
+
+import type { RouteMeta } from './meta';
+
+export type RenderMode = 'static' | 'isr' | 'ssr' | 'stream' | 'spa';
+
+/** `site/` is the only surface SEO applies to; `app/` is behind auth. */
+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;
+  /** Source file relative to the app root — named verbatim in every error. */
+  file: string;
+  surface: Surface;
+  render: RenderMode;
+  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;
+  changefreq?: ChangeFreq;
+  /** 0.0–1.0. Omit unless the site genuinely has a priority hierarchy. */
+  priority?: number;
+}
+
+export function isDynamic(path: string): boolean {
+  return path.includes(':') || path.includes('*');
+}
+
+/** Routes that should appear in a sitemap: public, indexable, not app-only. */
+export function indexableRoutes(routes: readonly RouteRecord[]): readonly RouteRecord[] {
+  return routes.filter(
+    (route) =>
+      route.surface === 'site' && route.noindex !== true && route.meta?.robots?.index !== false,
+  );
+}
+
+/** Every concrete URL a route resolves to, expanding `prerender()`. */
+export async function expandRoute(route: RouteRecord): Promise<readonly string[]> {
+  if (!isDynamic(route.path)) return [route.path];
+  if (route.prerender === undefined) return [];
+  return await route.prerender();
+}

package/src/rss.ts

@@ -0,0 +1,178 @@
+// Feed generation from a route's enumerated items. All three formats come from
+// one item list, because a site that ships RSS but not JSON Feed has simply
+// picked a winner for its readers.
+
+import { absoluteUrl, cdata, escapeXml, xmlElement } from './xml';
+
+export interface FeedAuthor {
+  name: string;
+  email?: string;
+  url?: string;
+}
+
+export interface FeedItem {
+  /** Stable, permanent identifier. The canonical URL is a fine choice. */
+  id: string;
+  url: string;
+  title: string;
+  /** ISO 8601. */
+  published: string;
+  updated?: string;
+  summary?: string;
+  /** Full HTML body. Emitted as CDATA in RSS, escaped in Atom. */
+  contentHtml?: string;
+  author?: FeedAuthor;
+  tags?: readonly string[];
+  image?: string;
+}
+
+export interface FeedChannel {
+  title: string;
+  description: string;
+  /** Absolute site root. */
+  siteUrl: string;
+  /** Path or absolute URL of the feed itself. */
+  feedUrl: string;
+  /** BCP-47. */
+  language: string;
+  /** Defaults to the newest item's timestamp. */
+  updated?: string;
+  author?: FeedAuthor;
+  copyright?: string;
+  icon?: string;
+}
+
+export interface Feed {
+  readonly rss: string;
+  readonly atom: string;
+  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();
+}
+
+function rfc822(iso: string): string {
+  return new Date(iso).toUTCString();
+}
+
+function buildRss(channel: FeedChannel, items: readonly FeedItem[], updated: string): string {
+  const self = absoluteUrl(channel.siteUrl, channel.feedUrl);
+  const entries = items
+    .map((item) => {
+      const parts = [
+        xmlElement('title', item.title),
+        xmlElement('link', item.url),
+        `      <guid isPermaLink="false">${escapeXml(item.id)}</guid>`,
+        xmlElement('pubDate', rfc822(item.published)),
+      ];
+      if (item.summary !== undefined) parts.push(xmlElement('description', item.summary));
+      if (item.contentHtml !== undefined) {
+        parts.push(`      <content:encoded>${cdata(item.contentHtml)}</content:encoded>`);
+      }
+      for (const tag of item.tags ?? []) parts.push(xmlElement('category', tag));
+      return `    <item>\n${parts.map((line) => (line.startsWith('      ') ? line : `      ${line}`)).join('\n')}\n    </item>`;
+    })
+    .join('\n');
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/">',
+    '  <channel>',
+    `    ${xmlElement('title', channel.title)}`,
+    `    ${xmlElement('link', channel.siteUrl)}`,
+    `    ${xmlElement('description', channel.description)}`,
+    `    ${xmlElement('language', channel.language)}`,
+    `    ${xmlElement('lastBuildDate', rfc822(updated))}`,
+    `    <atom:link href="${escapeXml(self)}" rel="self" type="application/rss+xml"/>`,
+    channel.copyright === undefined ? '' : `    ${xmlElement('copyright', channel.copyright)}`,
+    entries,
+    '  </channel>',
+    '</rss>',
+    '',
+  ]
+    .filter((line) => line !== '')
+    .join('\n');
+}
+
+function buildAtom(channel: FeedChannel, items: readonly FeedItem[], updated: string): string {
+  const self = absoluteUrl(channel.siteUrl, channel.feedUrl);
+  const entries = items
+    .map((item) => {
+      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)}`,
+      ];
+      if (item.summary !== undefined) parts.push(`      ${xmlElement('summary', item.summary)}`);
+      if (item.contentHtml !== undefined) {
+        parts.push(`      <content type="html">${escapeXml(item.contentHtml)}</content>`);
+      }
+      if (item.author !== undefined) {
+        parts.push(`      <author>${xmlElement('name', item.author.name)}</author>`);
+      }
+      for (const tag of item.tags ?? []) {
+        parts.push(`      <category term="${escapeXml(tag)}"/>`);
+      }
+      return `    <entry>\n${parts.join('\n')}\n    </entry>`;
+    })
+    .join('\n');
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    `<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="${escapeXml(channel.language)}">`,
+    `  ${xmlElement('title', channel.title)}`,
+    `  ${xmlElement('subtitle', channel.description)}`,
+    `  ${xmlElement('id', channel.siteUrl)}`,
+    `  ${xmlElement('updated', updated)}`,
+    `  <link href="${escapeXml(channel.siteUrl)}"/>`,
+    `  <link href="${escapeXml(self)}" rel="self" type="application/atom+xml"/>`,
+    entries,
+    '</feed>',
+    '',
+  ].join('\n');
+}
+
+function buildJsonFeed(channel: FeedChannel, items: readonly FeedItem[]): string {
+  return `${JSON.stringify(
+    {
+      version: 'https://jsonfeed.org/version/1.1',
+      title: channel.title,
+      description: channel.description,
+      home_page_url: channel.siteUrl,
+      feed_url: absoluteUrl(channel.siteUrl, channel.feedUrl),
+      language: channel.language,
+      icon: channel.icon,
+      authors: channel.author === undefined ? undefined : [channel.author],
+      items: items.map((item) => ({
+        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,
+        tags: item.tags,
+        authors: item.author === undefined ? undefined : [item.author],
+      })),
+    },
+    null,
+    2,
+  )}\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);
+  return {
+    rss: buildRss(channel, ordered, updated),
+    atom: buildAtom(channel, ordered, updated),
+    json: buildJsonFeed(channel, ordered),
+  };
+}