@escape-game-over/atlas 0.1.1

package/src/meta/index.ts

@@ -0,0 +1,432 @@
+/**
+ * The document head, built once from what a page and its project already know.
+ *
+ * Centralised because these tags are easy to get subtly wrong and invisible when
+ * they are: `og:url` must equal the canonical, `x-default` must point at the
+ * default locale, every alternate must use the locale's `hreflang` rather than
+ * its key, and a page calling itself an article must carry the date that makes
+ * the claim worth anything. Deriving them all in one pass from one input is what
+ * stops any two of them disagreeing.
+ *
+ * The pieces:
+ *
+ * - `tag.ts` — what a head tag is as data, and the opening tags every document
+ *   shares. lib describes tags; the consumer renders them.
+ * - `content.ts` — what only a page can supply: its words, its picture, and
+ *   whether it is an article.
+ * - `robots.ts` — the `robots` *meta tag*, which is not `lib/robots.ts`.
+ * - `share-image.ts` — the share image and the site icon, resolved and checked.
+ * - `verification.ts` — webmaster-tool ownership tokens.
+ *
+ * Anything lib does not model belongs in the consumer's own layout, rendered
+ * after these — there is no passthrough slot here for data lib cannot reason
+ * about.
+ */
+
+import {
+    type AnalyticsSettings,
+    analyticsScripts,
+    notFoundAnalytics,
+} from "../analytics/index.ts";
+import type { ResolvedLocaleMeta } from "../config.ts";
+import {
+    article,
+    type BreadcrumbStep,
+    breadcrumbList,
+    type JsonLdNode,
+    serializeJsonLd,
+} from "../jsonld/index.ts";
+import type { HttpsUrl } from "../url.ts";
+import type { MetaContentBase, PageKind, ThemeColor } from "./content.ts";
+import { robotsContent, warnAboutRobots } from "./robots.ts";
+import {
+    iconLinks,
+    type OgImage,
+    type SiteIcon,
+    warnAboutShareImage,
+    warnIfClipped,
+} from "./share-image.ts";
+import { asMetaTag, link, type MetaTag, meta, preamble } from "./tag.ts";
+import { type SiteVerification, verificationTags } from "./verification.ts";
+
+export type {
+    ArticleContent,
+    MetaContent,
+    OpenGraphType,
+    PageKind,
+    ThemeColor,
+} from "./content.ts";
+export type { RobotsDirective, RobotsPolicy } from "./robots.ts";
+export {
+    type ImageFormat,
+    type OgImage,
+    resolveShareImage,
+    type ShareImage,
+    type SiteIcon,
+} from "./share-image.ts";
+export type { MetaTag } from "./tag.ts";
+export type { SiteVerification } from "./verification.ts";
+
+/**
+ * Everything the head needs: what the page supplies, plus what lib derives.
+ *
+ * `PageKind` is intersected rather than inherited so that `Omit` applies to the
+ * base alone: omitting a key from a union would flatten it and lose the
+ * exclusivity that union exists for.
+ */
+export type MetaInput<L extends string> = Omit<MetaContentBase, "image"> &
+    PageKind &
+    MetaInputDerived<L>;
+
+interface MetaInputDerived<L extends string> {
+    /** The locale of *this* page, not the site default. */
+    readonly locale: L;
+    readonly canonical: HttpsUrl;
+    readonly alternates: readonly {
+        readonly locale: L;
+        readonly url: HttpsUrl;
+    }[];
+    readonly localeMeta: Readonly<Record<L, ResolvedLocaleMeta>>;
+    readonly defaultLocale: L;
+    /** The share image, already resolved against the site origin. */
+    readonly image: OgImage;
+    /**
+     * `ArticleContent.images`, already resolved against the site origin.
+     *
+     * A sibling of `article` rather than a field inside it, because `PageKind`
+     * is a union and `Omit` on a union flattens it — which is the whole reason
+     * `MetaInput` intersects that union separately instead of omitting through
+     * it. So the resolved form arrives beside the page's own, exactly as
+     * `image` does: a page states `ShareImage`, lib hands `buildMeta` an
+     * `OgImage`.
+     */
+    readonly articleImages?: readonly HttpsUrl[];
+    /**
+     * The page's breadcrumb trail, root first, or nothing.
+     *
+     * Empty and absent mean the same thing here — a page with no ancestors —
+     * and both emit no `BreadcrumbList`. Which pages those are is `siteFor`'s
+     * `breadcrumbFor` to decide; this only asks whether it was handed a trail.
+     */
+    readonly breadcrumb?: readonly BreadcrumbStep[];
+    /**
+     * `og:site_name`: the publisher's human-readable name. Site-level, so it
+     * comes from the project rather than being restated on every page.
+     */
+    readonly siteName: string;
+    /**
+     * `@handle` of the site. Attributes the card to your brand and has no Open
+     * Graph equivalent to fall back to. Site-level, like `siteName`.
+     */
+    readonly twitterSite?: string;
+    /** The site's square icon, used for every icon link. */
+    readonly icon: SiteIcon;
+    /**
+     * Webmaster-tool ownership tokens. Site-level, like `siteName`.
+     *
+     * On every page rather than only the home page: a URL-prefix property is
+     * verified at whatever URL you point the tool at, and a site whose token
+     * lives on one page alone silently loses verification the day that page is
+     * renamed.
+     */
+    readonly verification?: SiteVerification;
+    /**
+     * What this deployment records about its traffic. Site-level, like
+     * `verification` and for the same reason: it is one property in one
+     * dashboard, not a fact about a page.
+     */
+    readonly analytics?: AnalyticsSettings;
+    /**
+     * Absolute URL of the site's `llms.txt`, if it publishes one.
+     *
+     * Emitted as `rel="describedby"`, the relation llmstxt.org proposes for
+     * "the file that describes this page". Undefined when no such file is
+     * generated — a link to a missing one is worse than no link.
+     */
+    readonly llmsUrl?: HttpsUrl;
+    /**
+     * Tints the browser UI — Android Chrome's bar, iOS Safari, an installed PWA.
+     * Two values emit one tag per `prefers-color-scheme`.
+     */
+    readonly themeColor: ThemeColor;
+    /**
+     * Which schemes the page supports, e.g. `"light"` or `"dark light"`.
+     *
+     * Tells the browser how to render form controls and scrollbars, which is
+     * what stops the flash of a light control on a dark page.
+     */
+    readonly colorScheme?: string;
+}
+
+/** The tags a page needs, split by the element they belong in. */
+export interface DocumentTags {
+    readonly head: MetaTag[];
+    /**
+     * For immediately after `<body>`, and usually empty.
+     *
+     * Its own list because one tag genuinely belongs there — Tag Manager's
+     * `<noscript>` iframe, which is ignored in the head. Returning it
+     * separately means a layout cannot put it in the wrong place, and cannot
+     * silently drop it by rendering only the head.
+     */
+    readonly body: MetaTag[];
+}
+
+/** Builds the head tags every page needs. */
+export function buildMeta<L extends string>(input: MetaInput<L>): DocumentTags {
+    const tags: MetaTag[] = [
+        ...preamble({
+            title: input.title,
+            canonical: input.canonical,
+            viewport: input.viewport,
+        }),
+        meta({ name: "description", content: input.description }),
+    ];
+
+    warnIfClipped("title", input.title, input.canonical);
+    warnIfClipped("description", input.description, input.canonical);
+    warnAboutShareImage(input.image, input.canonical);
+
+    warnAboutRobots(input.robots, input.canonical);
+    tags.push(meta({ name: "robots", content: robotsContent(input.robots) }));
+
+    for (const tag of verificationTags(input.verification)) {
+        tags.push(tag);
+    }
+
+    // In the order `analyticsScripts` returned them, which is the order they
+    // have to load in: Google's consent defaults are queued by an inline block
+    // that must precede every tag reading them, and a tag that got there first
+    // would silently apply the permissive implicit default instead.
+    const analytics = analyticsScripts(input.analytics, input.canonical);
+    for (const script of analytics.head) tags.push(asMetaTag(script));
+    const bodyTags: MetaTag[] = analytics.body.map(asMetaTag);
+
+    if (input.llmsUrl !== undefined) {
+        // Points a client at the file describing this page, per llmstxt.org.
+        // `describedby` rather than `alternate`: that one means "the same page
+        // in another format", which an index of the whole site is not.
+        tags.push(link({ rel: "describedby", href: input.llmsUrl }));
+    }
+
+    for (const iconLink of iconLinks(input.icon)) tags.push(iconLink);
+
+    if (input.colorScheme !== undefined) {
+        tags.push(meta({ name: "color-scheme", content: input.colorScheme }));
+    }
+    if (typeof input.themeColor === "string") {
+        tags.push(meta({ name: "theme-color", content: input.themeColor }));
+    } else if (input.themeColor !== undefined) {
+        tags.push(
+            meta({
+                name: "theme-color",
+                media: "(prefers-color-scheme: light)",
+                content: input.themeColor.light,
+            })
+        );
+        tags.push(
+            meta({
+                name: "theme-color",
+                media: "(prefers-color-scheme: dark)",
+                content: input.themeColor.dark,
+            })
+        );
+    }
+
+    for (const alternate of input.alternates) {
+        tags.push(
+            link({
+                rel: "alternate",
+                hreflang: input.localeMeta[alternate.locale].htmlLang,
+                href: alternate.url,
+            })
+        );
+    }
+
+    const fallback = input.alternates.find(
+        (alternate) => alternate.locale === input.defaultLocale
+    );
+    if (fallback === undefined) {
+        // Unreachable through `createSite`, which validates that the default locale
+        // is published. Thrown rather than skipped because a silently missing
+        // `x-default` is exactly the kind of SEO gap nothing surfaces later.
+        throw new Error(
+            `No alternate for the default locale "${input.defaultLocale}", so x-default cannot be emitted.`
+        );
+    }
+    tags.push(
+        link({ rel: "alternate", hreflang: "x-default", href: fallback.url })
+    );
+
+    const { url: imageUrl, width, height, mime } = input.image;
+
+    // Open Graph
+    //
+    // The type follows the content rather than being stated beside it: a page
+    // that described an article and called itself a website would be two claims
+    // about one thing, and only one of them could be right.
+    tags.push(
+        meta({
+            property: "og:type",
+            content:
+                input.article === undefined
+                    ? (input.type ?? "website")
+                    : "article",
+        })
+    );
+    tags.push(meta({ property: "og:title", content: input.title }));
+    tags.push(meta({ property: "og:description", content: input.description }));
+    tags.push(meta({ property: "og:site_name", content: input.siteName }));
+    // Deliberately the canonical, never the request URL.
+    tags.push(meta({ property: "og:url", content: input.canonical }));
+    // This page's own locale, with every other published one advertised as an
+    // alternate. Emitting the site default here would label every translation
+    // with the same language.
+    const ogLocaleOf = (locale: L): string => input.localeMeta[locale].ogLocale;
+
+    tags.push(
+        meta({ property: "og:locale", content: ogLocaleOf(input.locale) })
+    );
+    for (const alternate of input.alternates) {
+        if (alternate.locale === input.locale) continue;
+        tags.push(
+            meta({
+                property: "og:locale:alternate",
+                content: ogLocaleOf(alternate.locale),
+            })
+        );
+    }
+
+    tags.push(meta({ property: "og:image", content: imageUrl }));
+    if (mime !== undefined) {
+        tags.push(meta({ property: "og:image:type", content: mime }));
+    }
+    tags.push(meta({ property: "og:image:width", content: String(width) }));
+    tags.push(meta({ property: "og:image:height", content: String(height) }));
+    tags.push(meta({ property: "og:image:alt", content: input.image.alt }));
+
+    // The dates, from the same object the `Article` node is built from below.
+    // A date-only value is a valid ISO 8601 datetime at reduced precision,
+    // which is the honest precision here: a venue publishes on a day.
+    //
+    // No `article:author`. Open Graph wants a URL to a profile page, and what
+    // this holds is a schema.org `@id` — a fragment on the site's own origin,
+    // which is a node in a graph rather than a page anyone can open. Emitting
+    // it would be answering a different question with the wrong value.
+    if (input.article !== undefined) {
+        tags.push(
+            meta({
+                property: "article:published_time",
+                content: input.article.datePublished,
+            })
+        );
+        if (input.article.dateModified !== undefined) {
+            tags.push(
+                meta({
+                    property: "article:modified_time",
+                    content: input.article.dateModified,
+                })
+            );
+        }
+        // One tag per property, which is how Open Graph spells an array — not
+        // one comma-joined value, which reads as a single very long subject.
+        for (const tag of input.article.tags ?? []) {
+            tags.push(meta({ property: "article:tag", content: tag }));
+        }
+    }
+
+    // Twitter
+    if (input.twitterSite !== undefined) {
+        // Twitter @handle
+        tags.push(meta({ name: "twitter:site", content: input.twitterSite }));
+    }
+
+    tags.push(
+        meta({
+            name: "twitter:card",
+            content: "summary_large_image",
+        })
+    );
+    tags.push(meta({ name: "twitter:title", content: input.title }));
+    tags.push(
+        meta({ name: "twitter:description", content: input.description })
+    );
+    tags.push(meta({ name: "twitter:image", content: imageUrl }));
+    tags.push(meta({ name: "twitter:image:alt", content: input.image.alt }));
+
+    // Everything structured, collected into one `@graph` and emitted as a
+    // single script: the nodes describe one page, and a node that refers to
+    // another by `@id` resolves within a graph it shares.
+    //
+    // Emitted whenever there is a trail at all. What counts as one — a page
+    // with no ancestors has none — is decided where the trail is built, so
+    // nothing here restates it.
+    const nodes: JsonLdNode[] = [...(input.jsonLd ?? [])];
+    if (input.article !== undefined) {
+        // The URL, the description and the picture are the ones this function
+        // has already settled for the head — the canonical rather than the
+        // request URL, and the share image already made absolute. A view that
+        // supplied them again would be supplying a second answer to a question
+        // lib had answered, and the two would agree only until one changed.
+        nodes.push(
+            article({
+                ...input.article,
+                headline: input.article.headline ?? input.title,
+                description: input.description,
+                url: input.canonical,
+                // The crops where the page cut them, the share card otherwise.
+                // Not both: the card is a 1.9:1 image with type often burnt
+                // into it, and mixing it into a set of photographs offers a
+                // search result a picture of the words rather than the thing.
+                image:
+                    input.articleImages !== undefined &&
+                    input.articleImages.length > 0
+                        ? input.articleImages
+                        : imageUrl,
+            })
+        );
+    }
+    if (input.breadcrumb !== undefined && input.breadcrumb.length > 0) {
+        nodes.push(breadcrumbList(input.breadcrumb));
+    }
+    if (nodes.length > 0) {
+        tags.push({
+            kind: "script",
+            type: "application/ld+json",
+            content: serializeJsonLd(nodes),
+        });
+    }
+
+    return { head: tags, body: bodyTags };
+}
+
+/**
+ * Builds the head of a 404 page.
+ *
+ * The one document with no canonical: it stands for whatever was asked for and
+ * is not there, so naming a canonical would assert that the missing URL and some
+ * real page are the same thing. `noindex` for the same reason — a 404 that gets
+ * indexed competes with the pages that do exist.
+ *
+ * It does carry analytics, and only Umami — see `notFoundAnalytics`. A static
+ * host serves this file at the address that was requested, so what gets
+ * recorded is the missing path itself, which is the difference between knowing
+ * there are 404s and knowing which redirect to write.
+ */
+export function buildNotFoundMeta(
+    title: string,
+    analytics?: AnalyticsSettings
+): MetaTag[] {
+    return [
+        ...preamble({ title }),
+        // Through the same builder as every other page, so the one document lib
+        // writes for itself cannot spell the tag differently from the ones it
+        // writes for a project. Links are still followed: a 404 often carries
+        // the nav, and those pages are real.
+        meta({
+            name: "robots",
+            content: robotsContent({ index: false, follow: true }),
+        }),
+        ...notFoundAnalytics(analytics).map(asMetaTag),
+    ];
+}

package/src/meta/robots.ts

@@ -0,0 +1,212 @@
+import { warn } from "../warn.ts";
+
+/**
+ * The `robots` *meta tag* — what a crawler may do with one page.
+ *
+ * Not `lib/robots.ts`, which writes `robots.txt` and is a different thing: that
+ * one is site-wide crawl rules served as a file, this one is a per-page
+ * decision emitted in the head. A page can be excluded by either and they do
+ * not mean the same thing.
+ */
+
+/**
+ * What a crawler may do with this page.
+ *
+ * An object rather than a list of directives, and that is the whole point: a
+ * list can hold `["index", "noindex"]` — two real directives that cannot both
+ * be obeyed — and a crawler resolves it by taking the restrictive half, so the
+ * page quietly stops being indexed. Here `index` is one field with one value,
+ * so the contradiction cannot be written down at all. No validator, no build
+ * check, nothing to keep in step.
+ *
+ * That also retires `all` and `none`, which were shorthand for two decisions at
+ * once and the source of the subtler half of those pairs — `["all", "noindex"]`
+ * reads as fine and is not.
+ *
+ * The two required fields are the two that decide whether the page has a result
+ * at all. They are required rather than defaulted for the reason the field was
+ * always required: the wrong answer is invisible in the output, so inheriting
+ * one is how a mistake ships without anyone choosing it. The rest are
+ * presentation, and every default is "show as much as you like".
+ */
+export interface RobotsPolicy {
+    /** Whether this page may appear in results at all. */
+    readonly index: boolean;
+    /** Whether the links on it may be followed. */
+    readonly follow: boolean;
+    /** Whether a cached copy may be offered. Default: yes. */
+    readonly archive?: boolean;
+    /** Whether a translation may be offered. Default: yes. */
+    readonly translate?: boolean;
+    /** Whether its images may be indexed. Default: yes. */
+    readonly imageIndex?: boolean;
+    /**
+     * How large an image may appear beside a result. Default: `"large"`.
+     *
+     * Worth stating as a default rather than leaving out: omitted, Google
+     * chooses, and it chooses a thumbnail — which for an image-led site is the
+     * difference between a result people click and one they scroll past.
+     */
+    readonly imagePreview?: "none" | "standard" | "large";
+    /**
+     * The text snippet: `false` for none, a whole number of characters to cap
+     * it at. Default: no limit.
+     *
+     * `-1` and `0` are what a crawler actually reads — no limit, and none — and
+     * are deliberately not the way to write them here: `true` and `false` say
+     * the same thing in words, and the two magic numbers stay inside lib.
+     */
+    readonly snippet?: boolean | number;
+    /**
+     * Video preview: `false` for none, a whole number of seconds to cap it at.
+     * Default: no limit.
+     */
+    readonly videoPreview?: boolean | number;
+}
+
+/**
+ * A `robots` meta directive — the vocabulary of the tag this file writes.
+ *
+ * Internal to the builder: a project states a `RobotsPolicy` and never writes
+ * one of these. Kept as a type because it is what stops a typo in the builder
+ * itself, which is the only thing that produces them.
+ */
+export type RobotsDirective =
+    | "index"
+    | "noindex"
+    | "follow"
+    | "nofollow"
+    | "noarchive"
+    | "nosnippet"
+    | "noimageindex"
+    | "notranslate"
+    | `max-snippet:${number}`
+    | `max-image-preview:${"none" | "standard" | "large"}`
+    | `max-video-preview:${number}`;
+
+/**
+ * Whether a number is a cap a crawler can act on: whole, and not negative.
+ *
+ * One predicate rather than two, because two things need the answer — the
+ * builder, to decide what to emit, and the warning, to decide whether to say
+ * anything. Written twice they could disagree about what counts as a bad limit,
+ * and only one of them would be right.
+ *
+ * A negative is rejected even though `-1` means something to a crawler: on this
+ * field it means somebody reached for the magic number that `true` exists to
+ * replace, and `-2` means nothing at all.
+ */
+function isCount(value: number): boolean {
+    return Number.isInteger(value) && value >= 0;
+}
+
+/**
+ * A `max-…` limit as a crawler reads it: `-1` for no limit, `0` for none.
+ *
+ * The two magic numbers live here rather than in the policy, so nobody writing
+ * a page has to know them — `true` and `false` say the same thing in words.
+ *
+ * A number that is not a count falls back to no limit rather than being passed
+ * through. A crawler would drop `max-snippet:200.5` and apply its own default
+ * anyway, so this changes nothing about the outcome and quite a lot about the
+ * markup: the tag then says what is actually going to happen, and lib never
+ * writes a directive that cannot be read. `warnAboutRobots` says so out loud.
+ */
+function limit(value: boolean | number | undefined): number {
+    if (value === undefined || value === true) return -1;
+    if (value === false) return 0;
+    return isCount(value) ? value : -1;
+}
+
+/**
+ * The `robots` tag's content, from what the page decided.
+ *
+ * The preview limits are always stated for an indexable page rather than left
+ * out: omitted, Google picks its own, and `max-image-preview` in particular
+ * falls back to a thumbnail. "Show as much as you like" is what an image-led
+ * site wants and is not what saying nothing gives you.
+ *
+ * A page that is not indexed gets the two decisions and whatever else it
+ * switched off, and nothing about presentation — those describe how a result
+ * may look, and there is no result.
+ *
+ * Reference:
+ * <https://developers.google.com/search/docs/crawling-indexing/robots-meta-tag>
+ */
+export function robotsContent(policy: RobotsPolicy): string {
+    const directives: RobotsDirective[] = [
+        policy.index ? "index" : "noindex",
+        policy.follow ? "follow" : "nofollow",
+    ];
+
+    if (policy.archive === false) directives.push("noarchive");
+    if (policy.imageIndex === false) directives.push("noimageindex");
+    if (policy.translate === false) directives.push("notranslate");
+
+    if (!policy.index) return directives.join(", ");
+
+    // `nosnippet` rather than `max-snippet:0`: the two are the same instruction
+    // and one of them says so in words.
+    if (policy.snippet === false) {
+        directives.push("nosnippet");
+    } else {
+        directives.push(`max-snippet:${limit(policy.snippet)}`);
+    }
+    directives.push(`max-image-preview:${policy.imagePreview ?? "large"}`);
+    directives.push(`max-video-preview:${limit(policy.videoPreview)}`);
+
+    return directives.join(", ");
+}
+
+/**
+ * Warns about a setting that will not do what it says.
+ *
+ * Both cases are warnings rather than errors, and for the same reason: neither
+ * is a contradiction. Every contradiction the old list could hold — `index`
+ * beside `noindex`, `nosnippet` beside a snippet length, no directives at all —
+ * is unwritable in this shape rather than detected, so there is nothing left to
+ * throw about and no rule kept in two places.
+ *
+ * A cap that is not a whole count is the one thing the object cannot rule out,
+ * since the field is a `number` and every number is one. It degrades rather
+ * than corrupts: `limit` falls back to no limit, which is what a crawler would
+ * have applied anyway after dropping the directive. Worth a line, not a build.
+ *
+ * A presentation setting on a page that is not indexed is coherent — `{ index:
+ * false, snippet: 200 }` asks for something real — it just asks for it of a
+ * result nobody will see.
+ */
+export function warnAboutRobots(policy: RobotsPolicy, at: string): void {
+    for (const [name, value] of [
+        ["snippet", policy.snippet],
+        ["videoPreview", policy.videoPreview],
+    ] as const) {
+        if (typeof value === "number" && !isCount(value)) {
+            warn(
+                at,
+                `robots.${name} is ${value}, which is not a cap a crawler can act on: it wants a whole number of ${name === "snippet" ? "characters" : "seconds"}, from 0. Falling back to no limit — and for no limit, write \`true\`.`
+            );
+        }
+    }
+
+    if (policy.index) return;
+
+    const moot = (
+        [
+            ["archive", policy.archive],
+            ["snippet", policy.snippet],
+            ["imageIndex", policy.imageIndex],
+            ["imagePreview", policy.imagePreview],
+            ["videoPreview", policy.videoPreview],
+        ] as const
+    )
+        .filter(([, value]) => value !== undefined)
+        .map(([name]) => name);
+
+    if (moot.length > 0) {
+        warn(
+            at,
+            `robots sets ${moot.join(", ")}, which shapes how a result looks — and this page is not indexed, so there is no result to shape.`
+        );
+    }
+}