@escape-game-over/atlas 0.1.1

package/src/meta/share-image.ts

@@ -0,0 +1,232 @@
+import type { ImageAsset } from "../image.ts";
+import { absoluteUrl, type HttpsUrl } from "../url.ts";
+import { warn } from "../warn.ts";
+import { link, type MetaTag } from "./tag.ts";
+
+export type ImageFormat = "png" | "jpg" | "webp";
+
+const IMAGE_MIME: Readonly<Record<ImageFormat, string>> = {
+    png: "image/png",
+    jpg: "image/jpeg",
+    webp: "image/webp",
+};
+
+/**
+ * The MIME type of an asset's format, where lib knows one.
+ *
+ * `undefined` rather than a guess for anything else. Both the tags this feeds —
+ * `og:image:type` and the icon's `type` — are hints that let a client skip a
+ * fetch, so a missing one costs nothing and a wrong one sends it to the wrong
+ * decoder. An asset's `format` is a string off an import, so this is where the
+ * question of whether it is one lib recognises gets answered, once.
+ */
+function imageMime(format: string | undefined): string | undefined {
+    const key = format?.toLowerCase();
+    // `Object.hasOwn`, not `in`, for the reason `familyGuard` uses it: `in`
+    // walks the prototype, so `"constructor"` and `"toString"` answer true and
+    // the cast below then hands back a function as a MIME type. Absurd input,
+    // but the check costs the same either way and the guard should not depend
+    // on nobody producing it.
+    return key !== undefined && Object.hasOwn(IMAGE_MIME, key)
+        ? IMAGE_MIME[key as ImageFormat]
+        : undefined;
+}
+
+/**
+ * A page's share image and the text describing it.
+ *
+ * One unit on purpose: alt text describes *this* image, so the two are declared
+ * together and cannot drift apart or be supplied from different places.
+ */
+export interface ShareImage {
+    /**
+     * The image itself, at **1200×630** — near enough to 1.91:1, the box every
+     * large link preview uses: Facebook, LinkedIn, iMessage, Slack, Discord,
+     * Telegram.
+     *
+     * Wide even though some surfaces want a square — WhatsApp's chat thumbnail,
+     * Twitter's `summary` card — because there is only one `og:image` and the
+     * two crops are not symmetrical. A square surface takes the centre of a wide
+     * image, which for a logo padded to the box is the logo itself; a wide
+     * surface takes a band out of the middle of a square one, and cuts the top
+     * and bottom off. Wide degrades, square destroys.
+     *
+     * Anything much smaller is upscaled: the common mistake is reusing a
+     * favicon, which produces a card with a logo adrift in the middle of it.
+     * Below roughly 600×315 some platforms drop the large card entirely and
+     * fall back to a thumbnail — which is a reason to meet the size rather than
+     * an option to choose. lib always asks for the wide card and offers no way
+     * to request the square one; a logo belongs in the box via
+     * `shareImage(src, { fit: "contain", background })`, not in a smaller card.
+     *
+     * Nothing here enforces the size, because an imported image's real
+     * dimensions are a fact about the file rather than about its type. Passing
+     * `shareImage(source)` from the package's `astro/images` derives a correct one from
+     * any large-enough source and refuses to upscale.
+     *
+     * Format: PNG or JPEG. Both are read by every scraper; WebP is not.
+     */
+    readonly asset: ImageAsset;
+    /**
+     * Describes what is *in* the image, for `og:image:alt` and
+     * `twitter:image:alt`. Never the page title unless the image renders it.
+     */
+    readonly alt: string;
+}
+
+/**
+ * The site's icon: one square asset, used for every icon link.
+ *
+ * Site-wide rather than per page, because search engines use one favicon per
+ * hostname, read from the home page — a per-page icon changes the browser tab
+ * and nothing else.
+ *
+ * One asset rather than a set, because one square PNG already covers every
+ * consumer: browsers accept PNG for `rel="icon"`, and Apple scales it for
+ * `apple-touch-icon`. A `/favicon.ico` in `public/` is still requested by
+ * browsers on its own if you want the legacy fallback.
+ *
+ * Unlike `og:image`, the href stays as written — root-relative is correct for an
+ * icon, and absolutising it would only hard-code the origin.
+ */
+export type SiteIcon = ImageAsset;
+
+/** One page's resolved share image. */
+export interface OgImage {
+    readonly url: HttpsUrl;
+    readonly width: number;
+    readonly height: number;
+    /** Only when the format is known; `og:image:type` is the least important. */
+    readonly mime?: string;
+    readonly alt: string;
+}
+
+/**
+ * The box every large link preview crops to, and the only shape worth serving.
+ *
+ * Wide is not a preference between two options. A square surface — WhatsApp's
+ * thumbnail — takes the *centre* of a wide image, which is where the subject
+ * is; a wide surface takes a band out of the middle of a square one and cuts the
+ * top and bottom off. Wide degrades, square destroys, and there is one
+ * `og:image` to satisfy both.
+ */
+const SHARE_BOX = { width: 1200, height: 630 } as const;
+
+/** Below this, a preview carries no image at all — not a small one, none. */
+const NO_PREVIEW_BELOW = 200;
+
+/**
+ * Where each surface starts cutting text off.
+ *
+ * One string feeds `description`, `og:description` and `twitter:description`, so
+ * the tightest is the one that counts. Facebook's mobile preview is that: a line
+ * under it survives everywhere, while a line written to Google's 160 is already
+ * clipped in a share. A title is cut far sooner, by the surface people search on.
+ */
+const LENGTH_LIMITS = {
+    title: {
+        limit: 60,
+        why: "a search result cuts a title around there, and the end of it is usually the part that identifies the page",
+    },
+    description: {
+        limit: 125,
+        why: "search truncates nearer 160 and X caps at 200, but a share preview on mobile is the tightest of the three",
+    },
+} as const;
+
+/**
+ * Warns rather than throws: a long description is not broken, it is edited by
+ * someone else's ellipsis. The page still renders, the preview still appears,
+ * and the last clause is silently gone — which is precisely the kind of thing
+ * nobody notices without being told.
+ */
+export function warnIfClipped(
+    field: keyof typeof LENGTH_LIMITS,
+    value: string,
+    at: string
+): void {
+    const { limit, why } = LENGTH_LIMITS[field];
+    if (value.length <= limit) return;
+
+    warn(at, `${field} is ${value.length} characters, past ~${limit}: ${why}.`);
+}
+
+/**
+ * Warns about a share image rather than rejecting it.
+ *
+ * A wrong-sized image still produces a page, still produces a preview, and is
+ * still worth shipping while someone finds a better one — so this is a warning
+ * and not a throw. It fires wherever `metaFor` runs, which is every page in a
+ * build and every page in dev.
+ *
+ * Checked here rather than in `shareImage`, because this is the path every page
+ * takes: that helper is optional, and an imported asset can be passed straight
+ * through. The size of one is a fact about a file, so no type can see it.
+ */
+export function warnAboutShareImage(image: OgImage, at: string): void {
+    const { width, height } = image;
+    // The page is named by `at`, and it has one share image — repeating the
+    // asset URL only pastes a `/_image?href=…` endpoint into every dev warning.
+    const say = (problem: string) =>
+        warn(
+            at,
+            `share image is ${width}x${height}: ${problem}. ${SHARE_BOX.width}x${SHARE_BOX.height} is what every surface crops to.`
+        );
+
+    if (width < NO_PREVIEW_BELOW || height < NO_PREVIEW_BELOW) {
+        say(
+            `below ${NO_PREVIEW_BELOW}x${NO_PREVIEW_BELOW}, so the preview will carry no image at all`
+        );
+        return;
+    }
+    if (width < SHARE_BOX.width || height < SHARE_BOX.height) {
+        say(
+            "smaller than the box, so platforms will scale it up or fall back to a small preview"
+        );
+        return;
+    }
+    // 1.5 rather than the box's own 1.91: a 16:9 photograph crops cleanly, and
+    // warning about it would be noise. A squarer image loses its top and bottom.
+    if (width / height < 1.5) {
+        say("not wide, so wide surfaces will crop the top and bottom off");
+    }
+}
+
+/** Resolves the page's share image against the site origin. */
+export function resolveShareImage(
+    siteUrl: HttpsUrl,
+    image: ShareImage
+): OgImage {
+    return {
+        url: absoluteUrl(siteUrl, image.asset.src, "share image"),
+        width: image.asset.width,
+        height: image.asset.height,
+        alt: image.alt,
+        mime: imageMime(image.asset.format),
+    };
+}
+
+/**
+ * The icon links: one asset, two `rel`s.
+ *
+ * Browsers read `icon`, Apple reads `apple-touch-icon` and scales it, and both
+ * point at the same file — so they are built together rather than left to a
+ * layout to remember the second one. `sizes` is stated so a browser need not
+ * fetch the file to find out what it is choosing between.
+ *
+ * The href stays as written. Unlike `og:image` these are read by a browser that
+ * already has the page, so root-relative is correct and making it absolute would
+ * only hard-code the origin.
+ */
+export function iconLinks(icon: SiteIcon): MetaTag[] {
+    const mime = imageMime(icon.format);
+    const attrs = {
+        href: icon.src,
+        sizes: `${icon.width}x${icon.height}`,
+        ...(mime !== undefined ? { type: mime } : {}),
+    };
+    return [
+        link({ rel: "icon", ...attrs }),
+        link({ rel: "apple-touch-icon", ...attrs }),
+    ];
+}

package/src/meta/tag.ts

@@ -0,0 +1,133 @@
+import type { AnalyticsTag } from "../analytics/index.ts";
+
+/**
+ * A head tag as data, not markup.
+ *
+ * lib does not render HTML — that would tie it to one framework and to one
+ * templating syntax. It describes the tags; the consumer spreads them.
+ */
+export type MetaTag =
+    | { readonly kind: "title"; readonly text: string }
+    | {
+          readonly kind: "meta";
+          readonly attrs: Readonly<Record<string, string>>;
+      }
+    | {
+          readonly kind: "link";
+          readonly attrs: Readonly<Record<string, string>>;
+      }
+    /**
+     * A block of text in a `<script>` — structured data, and nothing else.
+     *
+     * `content` is already escaped for the element it goes in, so a renderer
+     * must write it *raw*: escaping it again as HTML would turn every quote in
+     * the JSON into an entity and the block into gibberish.
+     */
+    | {
+          readonly kind: "script";
+          /** Omitted for JavaScript, which needs none. */
+          readonly type?: string;
+          readonly content: string;
+      }
+    /**
+     * A script fetched from somewhere else — analytics, and so far only that.
+     *
+     * Deliberately *not* a slot a consumer can put anything in. Nothing takes
+     * one of these as input: the only way to get one is to declare typed
+     * settings that lib knows how to build a script from, which is the
+     * difference between machinery and the passthrough rule 1 forbids.
+     *
+     * Always deferred. A third-party script that blocks the parser is a
+     * measurement that costs the thing it measures.
+     */
+    | {
+          readonly kind: "externalScript";
+          readonly src: string;
+          readonly attrs: Readonly<Record<string, string>>;
+      }
+    /**
+     * A hidden iframe inside `<noscript>`, for the body rather than the head.
+     *
+     * Tag Manager's documented fallback, and the only thing lib emits that does
+     * not belong in `<head>` — which is why `buildMeta` returns two lists
+     * rather than one. Structured rather than a string of markup, for the
+     * reason `externalScript` is.
+     */
+    | {
+          readonly kind: "noscriptFrame";
+          readonly src: string;
+      };
+
+export const meta = (attrs: Readonly<Record<string, string>>): MetaTag => ({
+    kind: "meta",
+    attrs,
+});
+
+export const link = (attrs: Readonly<Record<string, string>>): MetaTag => ({
+    kind: "link",
+    attrs,
+});
+
+/**
+ * An analytics tag as a head tag. The two vocabularies overlap but are not the
+ * same type: `analytics/` knows nothing of `MetaTag`, which is what keeps this
+ * folder free to import it without a cycle.
+ *
+ * Every kind is named rather than left to a trailing `else`, so that adding one
+ * to `AnalyticsTag` and forgetting it here is a *compile* error and not a tag
+ * that quietly disappears: `script` narrows to `never` only while the list is
+ * complete, and assigning anything else to `never` does not type-check.
+ */
+export function asMetaTag(script: AnalyticsTag): MetaTag {
+    if (script.kind === "inline") {
+        return { kind: "script", content: script.content };
+    }
+    if (script.kind === "external") {
+        return {
+            kind: "externalScript",
+            src: script.src,
+            attrs: script.attributes,
+        };
+    }
+    if (script.kind === "noscriptFrame") {
+        return { kind: "noscriptFrame", src: script.src };
+    }
+    const unhandled: never = script;
+    throw new Error(`Unhandled analytics tag: ${JSON.stringify(unhandled)}`);
+}
+
+const DEFAULT_VIEWPORT = "width=device-width, initial-scale=1";
+
+interface Preamble {
+    readonly title: string;
+    /**
+     * The real URL of what this document represents.
+     *
+     * Optional for the one document that represents nothing: a 404 stands for
+     * whatever was requested and is not there, so naming a canonical would tell
+     * a crawler the missing page and that URL are the same thing.
+     */
+    readonly canonical?: string;
+    readonly viewport?: string;
+}
+
+/**
+ * What every document in the site opens with: what encoding it is in, how to
+ * scale it, what it is called, and — for anything that stands for a URL — which
+ * URL that is.
+ *
+ * A function returning the *head* of the list rather than something appended
+ * later: the spec requires `charset` within the first 1024 bytes, so its
+ * position is part of its meaning.
+ */
+export function preamble(input: Preamble): MetaTag[] {
+    const tags: MetaTag[] = [
+        meta({ charset: "utf-8" }),
+        meta({ name: "viewport", content: input.viewport ?? DEFAULT_VIEWPORT }),
+        { kind: "title", text: input.title },
+    ];
+    if (input.canonical !== undefined) {
+        tags.push(link({ rel: "canonical", href: input.canonical }));
+    }
+    return tags;
+}

package/src/meta/verification.ts

@@ -0,0 +1,53 @@
+import { type MetaTag, meta } from "./tag.ts";
+
+/**
+ * Ownership tokens from webmaster tools, as `<meta name="…" content="token">`.
+ *
+ * An object with one key rather than a bare token, so the day a site needs Bing,
+ * Yandex or Meta the field grows a sibling instead of changing shape. Each of
+ * those is a fixed, unmemorable tag name — Bing's is `msvalidate.01` — and a
+ * misspelled one fails silently, so they get named keys if they are ever needed
+ * rather than a free `name`/`content` pair now.
+ */
+export interface SiteVerification {
+    /**
+     * Google Search Console.
+     *
+     * One token or several. Several is normal: a token identifies an *owner*, so
+     * a site verified by two people, or claimed as both a domain and a URL
+     * prefix, legitimately carries more than one, and each is checked
+     * independently.
+     */
+    readonly google?: string | readonly string[];
+}
+
+/**
+ * The tag name each key is written as.
+ *
+ * Adding a service is this table plus its key on `SiteVerification`, and the
+ * `satisfies` is what keeps that a pair: a key with no tag name here, or a name
+ * here for a key that does not exist, fails to compile. Bing is
+ * `msvalidate.01`, Yandex `yandex-verification`, Meta
+ * `facebook-domain-verification`, Pinterest `p:domain_verify` — none of them
+ * guessable, and all of them silently inert when wrong.
+ */
+const VERIFICATION_TAG_NAME = {
+    google: "google-site-verification",
+} as const satisfies Readonly<Record<keyof SiteVerification, string>>;
+
+export function verificationTags(
+    verification: SiteVerification | undefined
+): readonly MetaTag[] {
+    if (verification === undefined) return [];
+
+    const tags: MetaTag[] = [];
+    for (const [key, name] of Object.entries(VERIFICATION_TAG_NAME)) {
+        const tokens = verification[key as keyof SiteVerification];
+        if (tokens === undefined) continue;
+
+        for (const token of typeof tokens === "string" ? [tokens] : tokens) {
+            tags.push(meta({ name, content: token }));
+        }
+    }
+    return tags;
+}

package/src/money.ts

@@ -0,0 +1,237 @@
+import type { Letter } from "./types.ts";
+
+/**
+ * An ISO 4217 currency code: `"EUR"`, `"RON"`, `"GBP"`.
+ *
+ * Three uppercase letters, which is what `priceCurrency` is read as. A symbol —
+ * `€`, `lei` — is how a price is *printed* in one place for one audience, and
+ * two currencies can share one symbol, so it identifies nothing.
+ */
+export type CurrencyCode = `${Letter}${Letter}${Letter}`;
+
+/**
+ * An amount and what it is denominated in, kept together.
+ *
+ * A bare number is the mistake this exists to stop. Two deployments of one
+ * template charge 28 and 120 for the same thing because one is in euros and the
+ * other is not, and nothing about `28` says which — least of all to a search
+ * engine reading it as a price.
+ *
+ * `amount` is a number rather than a string: it is arithmetic to whoever sets
+ * it, and formatting it for a reader is a separate job needing a locale this
+ * type has no business holding.
+ */
+export interface Price {
+    readonly amount: number;
+    readonly currency: CurrencyCode;
+}
+
+/**
+ * What one quantity band costs.
+ *
+ * `quantity` takes a count or a range, because both occur and the range alone
+ * would make the ordinary case noisy: `{ min: 2, max: 2 }` five times over says
+ * nothing `2, 3, 4, 5, 6` does not. Same shape as `ThemeColor` — a scalar for
+ * the common case, an object when it genuinely varies.
+ */
+export interface PriceTier {
+    readonly quantity: number | { readonly min: number; readonly max: number };
+    /**
+     * What one unit costs at this quantity — not the total for the band.
+     *
+     * Named for what it is, because the two readings differ by a factor of the
+     * group size and both are plausible numbers. A room at 22 for four people
+     * is 88 or it is 22, and a field called `amount` does not say which.
+     */
+    readonly amountPerUnit: number;
+}
+
+/**
+ * A price that depends on how many are bought.
+ *
+ * One currency for the whole table rather than one per tier: a product priced
+ * in two currencies at once is not a discount, it is a mistake, and stating it
+ * once removes the chance of writing it.
+ */
+export interface TieredPrice {
+    readonly currency: CurrencyCode;
+    /**
+     * The bands, cheapest quantity first. Never empty — a product with no price
+     * at all is an offer of nothing.
+     */
+    readonly tiers: readonly [PriceTier, ...PriceTier[]];
+    /**
+     * What the quantity counts: `"players"`, `"seats"`, `"nights"`.
+     *
+     * lib has no idea what is being sold, and a bare number in the output reads
+     * as "how many items" — which for a room booked by the group is wrong.
+     */
+    readonly unit?: string;
+}
+
+/** The band a tier covers, with a bare count widened to a range of one. */
+export function tierRange(tier: PriceTier): {
+    readonly min: number;
+    readonly max: number;
+} {
+    return typeof tier.quantity === "number"
+        ? { min: tier.quantity, max: tier.quantity }
+        : tier.quantity;
+}
+
+/**
+ * The whole span a price table covers, floor of the first band to ceiling of
+ * the last.
+ *
+ * Worth having at all because the alternative is storing the span beside the
+ * table, where the two can disagree and only one of them can be right.
+ *
+ * Internal, and not exported from the package: on its own it is only half an
+ * answer, true of a run and an overstatement of a table with holes in it. What
+ * a caller wants is `formatQuantities` or `quantitiesFor`, which pick between
+ * this and `quantitiesOf` by reading the tiers.
+ */
+export function quantityRange(tiers: readonly [PriceTier, ...PriceTier[]]): {
+    readonly min: number;
+    readonly max: number;
+} {
+    const first = tierRange(tiers[0]);
+    const last = tiers.at(-1);
+    return {
+        min: first.min,
+        // Non-empty by type, so `at(-1)` cannot really miss; answering with the
+        // first band's ceiling beats inventing a number for a case that is
+        // unreachable.
+        max: last === undefined ? first.max : tierRange(last).max,
+    };
+}
+
+/**
+ * Every quantity a table actually sells, ascending.
+ *
+ * The honest form of `quantityRange` for a table with holes in it. A room sold
+ * to twos, fours and sixes spans 2 to 6 and is not sellable at 3 — so the span
+ * is a claim about two sizes that cannot be booked, while this is a list of the
+ * ones that can.
+ *
+ * Both exist because they answer different questions and structured data wants
+ * different things: a contiguous table is one `QuantitativeValue` with a min and
+ * a max, and a table with holes has to enumerate.
+ */
+export function quantitiesOf(
+    tiers: readonly [PriceTier, ...PriceTier[]]
+): readonly number[] {
+    const sizes = new Set<number>();
+    for (const tier of tiers) {
+        const band = tierRange(tier);
+        for (let size = band.min; size <= band.max; size++) {
+            sizes.add(size);
+        }
+    }
+    return [...sizes].sort((a, b) => a - b);
+}
+
+/**
+ * Whether a table's quantities run without a break.
+ *
+ * What decides how the quantities are published: a run gets a min and a max, a
+ * broken set has to be listed. Derived rather than declared, so it cannot
+ * disagree with the tiers it describes.
+ */
+export function isContiguous(
+    tiers: readonly [PriceTier, ...PriceTier[]]
+): boolean {
+    const sizes = quantitiesOf(tiers);
+    const first = sizes[0];
+    const last = sizes.at(-1);
+
+    // Both ends exist — `tiers` is non-empty and every band contributes at
+    // least one size — but the type cannot see it, so the unreachable case
+    // answers "yes" rather than being asserted away.
+    if (first === undefined || last === undefined) return true;
+
+    // A run of n sizes spans exactly n - 1 steps. Counting beats comparing
+    // neighbours: the sizes are already deduplicated and sorted.
+    return sizes.length === last - first + 1;
+}
+
+/**
+ * The quantities a table sells, written out for a reader.
+ *
+ * The prose half of `quantitiesFor`, and it exists for the same reason: a run
+ * reads as `2–6`, and a table that skips sizes has to say `2, 4, 6`, because
+ * a range would tell someone they can book a three when they cannot.
+ *
+ * Which form to use is decided here rather than by the caller — it follows from
+ * the tiers, and there is one right answer per table. What the caller supplies
+ * is punctuation, exactly as `formatHours` takes its separators: lib has no
+ * language and no opinion about dashes.
+ */
+export function formatQuantities(
+    tiers: readonly [PriceTier, ...PriceTier[]],
+    format: {
+        /** Between the ends of a run: `2–6`. */
+        readonly between?: string;
+        /** Between sizes that are listed one by one: `2, 4, 6`. */
+        readonly and?: string;
+    } = {}
+): string {
+    const sizes = quantitiesOf(tiers);
+    const first = sizes[0];
+    const last = sizes.at(-1);
+    if (first === undefined || last === undefined) return "";
+
+    if (!isContiguous(tiers)) return sizes.join(format.and ?? ", ");
+    return first === last
+        ? `${first}`
+        : `${first}${format.between ?? "–"}${last}`;
+}
+
+/**
+ * Throws on a price table that cannot be read as one.
+ *
+ * Two failures, and both are contradictions rather than omissions. An overlap
+ * gives one quantity two prices, and whichever a reader sees is the one they
+ * will expect to pay. A backwards band names no quantity at all.
+ *
+ * Throws rather than warns, for the reason a wrong opening time does: this is a
+ * number a customer acts on.
+ *
+ * **A gap is not an error.** The tiers *are* the list of what is sold, so a
+ * table running 2, 4, 6 describes a thing sold to twos, fours and sixes — not
+ * one missing its odd sizes. Rejecting that would need the table to carry a
+ * second field saying which reading applies, and a field that can contradict
+ * the data beside it is the thing worth avoiding: it goes stale the moment a
+ * tier is added. What a gap changes is how the quantities are *published*,
+ * which `quantitiesFor` derives rather than being told.
+ */
+export function assertPriceTiers(price: TieredPrice, at: string): void {
+    const problems: string[] = [];
+    let previous: { min: number; max: number } | undefined;
+
+    for (const tier of price.tiers) {
+        const range = tierRange(tier);
+
+        if (range.max < range.min) {
+            problems.push(
+                `a tier covers ${range.min} to ${range.max}, which is backwards.`
+            );
+        } else if (previous !== undefined) {
+            if (range.min <= previous.max) {
+                problems.push(
+                    `${range.min} to ${range.max} overlaps ${previous.min} to ${previous.max}, so one quantity has two prices.`
+                );
+            }
+        }
+
+        previous = range;
+    }
+
+    if (problems.length > 0) {
+        throw new Error(
+            `${at}: price tiers do not describe a single table.\n${problems
+                .map((problem) => `  - ${problem}`)
+                .join("\n")}`
+        );
+    }
+}