@ultimat3/seo 22.6.1 → 22.7.0

package/package.json

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

package/src/errors.ts

@@ -18,6 +18,7 @@ export const SEO_ERROR_CODES = {
   ldInvalid: 'X_LD_INVALID',
   sitemapTooLarge: 'X_SITEMAP_TOO_LARGE',
   imageQueryInvalid: 'X_IMAGE_QUERY_INVALID',
+  linkInvalid: 'X_SEO_LINK_INVALID',
 } as const;
 
 export type SeoErrorCode = (typeof SEO_ERROR_CODES)[keyof typeof SEO_ERROR_CODES];
@@ -38,6 +39,7 @@ registerErrorCodes({
   X_LD_INVALID: { title: 'JSON-LD node is missing a required schema.org field' },
   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' },
+  X_SEO_LINK_INVALID: { title: 'a route meta link is unsafe or would fetch nothing' },
 });
 
 export interface SeoErrorInit {
@@ -111,6 +113,21 @@ export function canonicalMismatch(file: string, canonical: string, expected: str
   });
 }
 
+/**
+ * A `meta.links` entry that cannot ship: an href that is not a path or an http(s) URL, a preload
+ * with no `as`, a font preload with no `crossorigin`. `file` is known to the build gate and not to
+ * a render — the renderer's message names the link, which the route's source contains verbatim.
+ */
+export function linkInvalid(link: string, problem: string, file?: string): SeoError {
+  const where = file === undefined ? 'the route' : file;
+  return new SeoError({
+    code: SEO_ERROR_CODES.linkInvalid,
+    cause: `${where} declares meta ${link}, which ${problem}`,
+    fix: `edit links in defineRoute({ meta }) in ${where}: a path or an http(s) href, \`as\` on every preload, crossorigin: 'anonymous' on a font preload`,
+    meta: { link, problem, ...(file === undefined ? {} : { file }) },
+  });
+}
+
 export function ldInvalid(type: string, field: string, hint: string): SeoError {
   return new SeoError({
     code: SEO_ERROR_CODES.ldInvalid,

package/src/index.ts

@@ -7,6 +7,7 @@ export {
   duplicateMeta,
   imageQueryInvalid,
   ldInvalid,
+  linkInvalid,
   metaMissing,
   metaTooLong,
   notImplementedDriver,
@@ -70,6 +71,8 @@ export {
   SoftwareApplication,
   WebSite,
 } from './ld';
+export type { HeadLink, HeadLinkAs, HeadLinkRel } from './links';
+export { linkProblem } from './links';
 export type { LocalizedPage, MetaLocalization } from './locale-tags';
 export { hreflangTag, ogLocaleTag } from './locale-tags';
 export type {

package/src/links.ts

@@ -0,0 +1,114 @@
+// `RouteMeta.links`: the `<link>` tags a route adds to `<head>` beyond the two this package
+// already derives (canonical, hreflang). A font preload, a preconnect, a feed. Typed so a rel the
+// framework owns elsewhere — `canonical` (`meta.canonical`), `stylesheet` (the surface bundle) —
+// is not spellable here, and checked so an href is always a URL a browser fetches: the value lands
+// in an attribute of the document every visitor loads, and `javascript:` in a `<link href>` is
+// script the page never meant to carry.
+
+import { linkInvalid, type SeoError } from './errors';
+import type { HeadTag } from './meta';
+
+/**
+ * Every rel a route may declare. `canonical` and `alternate`+`hreflang` have their own fields;
+ * `stylesheet` is the surface bundle's, emitted once per document by the renderer.
+ */
+export type HeadLinkRel =
+  | 'preload'
+  | 'modulepreload'
+  | 'prefetch'
+  | 'preconnect'
+  | 'dns-prefetch'
+  | 'icon'
+  | 'apple-touch-icon'
+  | 'manifest'
+  | 'alternate'
+  | 'author'
+  | 'license'
+  | 'help'
+  | 'privacy-policy'
+  | 'terms-of-service'
+  | 'search'
+  | 'me';
+
+/** The destinations a preload can name (HTML's `as` keywords). */
+export type HeadLinkAs =
+  | 'audio'
+  | 'document'
+  | 'embed'
+  | 'fetch'
+  | 'font'
+  | 'image'
+  | 'object'
+  | 'script'
+  | 'style'
+  | 'track'
+  | 'video'
+  | 'worker';
+
+export interface HeadLink {
+  readonly rel: HeadLinkRel;
+  /** A path (`/assets/…`, from `asset()`) or an `http(s)` URL. Nothing else is fetched. */
+  readonly href: string;
+  /** Required on `preload`: a preload without it fetches nothing. */
+  readonly as?: HeadLinkAs;
+  /** A MIME type: `font/woff2`, `application/rss+xml`. */
+  readonly type?: string;
+  /** Required on a font preload: fonts are CORS requests, and a mismatched preload is a 2nd fetch. */
+  readonly crossorigin?: 'anonymous' | 'use-credentials';
+  /** A media query: the link applies only where it matches. */
+  readonly media?: string;
+}
+
+/**
+ * The scheme of `href`, or `undefined` for a relative reference. Read the way a browser's URL
+ * parser reads it: ASCII tab and newline are removed anywhere and leading C0/space trimmed first,
+ * so `java\tscript:` and ` javascript:` are the scheme they execute as.
+ */
+function schemeOf(href: string): string | undefined {
+  let start = 0;
+  while (start < href.length && href.charCodeAt(start) <= 0x20) start += 1;
+  const normalised = href.slice(start).replace(/[\t\n\r]/g, '');
+  const match = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(normalised);
+  return match?.[1]?.toLowerCase();
+}
+
+/** Why `link` cannot ship, or `undefined`. One predicate for the renderer and the build gate. */
+export function linkProblem(link: HeadLink): string | undefined {
+  if (typeof link.href !== 'string' || link.href.trim() === '') return 'has an empty href';
+  const scheme = schemeOf(link.href);
+  if (scheme !== undefined && scheme !== 'http' && scheme !== 'https') {
+    return `has an href with the "${scheme}:" scheme — only a path or an http(s) URL is fetched`;
+  }
+  if (link.rel === 'preload' && link.as === undefined) {
+    return 'is a preload with no `as` — the browser ignores it and fetches nothing early';
+  }
+  if (link.rel === 'preload' && link.as === 'font' && link.crossorigin === undefined) {
+    return "is a font preload with no crossorigin — fonts are fetched in CORS mode, so the preload is not reused and the font downloads twice (crossorigin: 'anonymous')";
+  }
+  return undefined;
+}
+
+const describe = (link: HeadLink): string => `link { rel: '${link.rel}', href: '${link.href}' }`;
+
+/** The error a bad link is, at `file` when the caller knows the route. */
+export function linkError(link: HeadLink, problem: string, file?: string): SeoError {
+  return linkInvalid(describe(link), problem, file);
+}
+
+/**
+ * The tags, in declaration order, attributes in a fixed order and only those given. Throws
+ * `X_SEO_LINK_INVALID` on the first bad link: this runs for every SSR request and every prerendered
+ * page, and a document carrying an unsafe href is worse than no document.
+ */
+export function linkTags(links: readonly HeadLink[]): HeadTag[] {
+  return links.map((link) => {
+    const problem = linkProblem(link);
+    if (problem !== undefined) throw linkError(link, problem);
+    const attrs: Record<string, string> = { rel: link.rel, href: link.href };
+    if (link.as !== undefined) attrs['as'] = link.as;
+    if (link.type !== undefined) attrs['type'] = link.type;
+    if (link.crossorigin !== undefined) attrs['crossorigin'] = link.crossorigin;
+    if (link.media !== undefined) attrs['media'] = link.media;
+    return { tag: 'link', attrs };
+  });
+}

package/src/meta.ts

@@ -2,6 +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 { type HeadLink, linkTags } from './links';
 import { hreflangTag, type MetaLocalization, ogLocaleTag } from './locale-tags';
 import { absoluteUrl } from './xml';
 
@@ -82,6 +83,12 @@ export interface RouteMeta {
   themeColor?: readonly ThemeColor[];
   /** JSON-LD nodes from `ld.*`. Rendered as one script tag per node. */
   ld?: readonly Readonly<Record<string, unknown>>[];
+  /**
+   * Extra `<link>` tags for `<head>`, in order: a font preload, a preconnect, a feed. An href is a
+   * path or an http(s) URL, a preload names `as`, a font preload names `crossorigin` — anything
+   * else is `X_SEO_LINK_INVALID`. Never absolutised: a preload must hit the origin the page did.
+   */
+  links?: readonly HeadLink[];
 }
 
 export interface HeadTag {
@@ -303,6 +310,9 @@ export function renderMeta(meta: RouteMeta, options: RenderMetaOptions = {}): re
     });
   }
 
+  // --- the route's own links --------------------------------------------------
+  tags.push(...linkTags(meta.links ?? []));
+
   // --- theme-color per colour scheme ----------------------------------------
   for (const entry of meta.themeColor ?? []) {
     tags.push({

package/src/validate.ts

@@ -14,6 +14,7 @@ import {
   type SeoErrorCode,
   titleTemplateSlotMissing,
 } from './errors';
+import { linkError, linkProblem } from './links';
 import { applyTitleTemplate, DESCRIPTION_MAX_LENGTH, TITLE_MAX_LENGTH, TITLE_SLOT } from './meta';
 import { indexableRoutes, isDynamic, type RouteRecord } from './routes';
 import { absoluteUrl } from './xml';
@@ -128,6 +129,15 @@ export function validateMeta(
       push(descriptions, meta.description, route.file);
     }
 
+    // The same predicate the renderer throws on, reported here at the route FILE and before any
+    // request: an unsafe href in a static route's meta fails the build rather than a visitor.
+    for (const link of meta.links ?? []) {
+      const problem = linkProblem(link);
+      if (problem !== undefined) {
+        issues.push(issueOf(linkError(link, problem, 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)) {