@escape-game-over/atlas 0.1.1

package/src/jsonld/quantity.ts

@@ -0,0 +1,55 @@
+import {
+    isContiguous,
+    type PriceTier,
+    quantitiesOf,
+    quantityRange,
+} from "../money.ts";
+import type { JsonLdNode } from "./node.ts";
+
+/**
+ * A quantity, as schema.org states one: an exact count, or a range.
+ *
+ * Its own helper because the shape recurs — how many people, how long, how far
+ * — and because the naive spelling of a range is a string like `"2–5"`, which
+ * reads correctly to a person and is one opaque value to everything else.
+ *
+ * The same `number | { min, max }` shape as `PriceTier.quantity`, so a caller
+ * moves between the two without translating, and a *set* of exact quantities is
+ * `sizes.map(quantitativeValue)` — which is how a thing sold at some sizes and
+ * not the ones between says so, where a min and a max would claim the gaps.
+ *
+ * Reference: <https://schema.org/QuantitativeValue>
+ */
+export function quantitativeValue(
+    quantity: number | { readonly min: number; readonly max: number }
+): JsonLdNode {
+    return typeof quantity === "number"
+        ? { "@type": "QuantitativeValue", value: quantity }
+        : {
+              "@type": "QuantitativeValue",
+              minValue: quantity.min,
+              maxValue: quantity.max,
+          };
+}
+
+/**
+ * The quantities a price table sells, in whichever form states them honestly.
+ *
+ * One node when the sizes run without a break — `minValue` 2, `maxValue` 6 —
+ * and one node per size when they do not. A thing sold to twos, fours and sixes
+ * published as a range from 2 to 6 advertises two bookings nobody can make, and
+ * a run published as three separate values is merely noisy.
+ *
+ * The choice is made here rather than by a caller because it is not a
+ * preference: it follows from the tiers, and there is exactly one right answer
+ * for any table. A consumer assigns the result and does not branch.
+ *
+ * Reference: <https://schema.org/QuantitativeValue>
+ */
+export function quantitiesFor(
+    tiers: readonly [PriceTier, ...PriceTier[]]
+): JsonLdNode | readonly JsonLdNode[] {
+    return isContiguous(tiers)
+        ? quantitativeValue(quantityRange(tiers))
+        : quantitiesOf(tiers).map(quantitativeValue);
+}

package/src/jsonld/service.ts

@@ -0,0 +1,237 @@
+import type { HttpsUrl } from "../url.ts";
+import type { BusinessId, OrganizationId } from "./ids.ts";
+import { serviceId } from "./ids.ts";
+import type { JsonLdNode } from "./node.ts";
+
+/**
+ * What a business *does*, for the sites that sell work rather than tickets.
+ *
+ * The B2B half of `product.ts`. A venue sells a room at a price, and `Product`
+ * carries the number a result can render; a B2B site sells construction, a
+ * franchise, marketing — things quoted rather than priced, which is why nothing
+ * here takes a `Price`. An `Offer` with no amount says less than no offer, and
+ * a placeholder `PriceSpecification` carrying only a currency says nothing at
+ * all.
+ *
+ * **Google renders nothing for this.** There is no `Service` rich result, and
+ * that is worth knowing before writing much of it: the payoff is entity
+ * understanding — what this company does, for whom, where — rather than
+ * anything you will see in a SERP. It is here because without it the graph of a
+ * B2B site says "this is a business" and stops, while the same site's whole
+ * subject is the work it takes on.
+ */
+
+/**
+ * Where a service is offered.
+ *
+ * `kind` is a schema.org `Place` subtype and is not checked against the
+ * vocabulary, for the reason `LocalBusinessInput.type` is not: the list is long,
+ * it moves, and a name lib rejected would be a name a crawler accepted. Use
+ * `"Country"` for a franchise territory, `"City"` for a local trade, and the
+ * default when it is neither.
+ */
+export interface ServiceArea {
+    readonly name: string;
+    /** Defaults to `"AdministrativeArea"`, which is the honest general case. */
+    readonly kind?: string;
+}
+
+export interface ServiceInput {
+    readonly name: string;
+    /**
+     * This service's own page — and, through `serviceId`, its identity.
+     *
+     * Required rather than optional because the id is the point: a service
+     * described on its own page and listed in a catalogue elsewhere has to be
+     * one thing in the graph, and the URL is what makes it one.
+     */
+    readonly url: HttpsUrl;
+    readonly description?: string;
+    /**
+     * What kind of work it is, in your own words — "Escape room construction".
+     *
+     * Free text by design. schema.org offers no enumeration here, so this is
+     * the category as a human would say it, not a code from a list.
+     */
+    readonly serviceType?: string;
+    /**
+     * Who does the work, as an `@id` — the venue or the brand.
+     *
+     * A reference rather than a repeat, exactly as `ProductInput.seller` is:
+     * the provider is described once, in the node that carries its address and
+     * its hours.
+     *
+     * Optional here and required on `OfferCatalogInput`, because this node has
+     * an `@id` and that one does not: a service is reachable from any catalogue
+     * that lists it, so the graph joins up even when this is left out. Worth
+     * setting anyway on a service page that carries no catalogue, which is the
+     * case where nothing else says whose work it is.
+     */
+    readonly provider?: BusinessId | OrganizationId;
+    /**
+     * Who it is for — "Escape room operators", "Property developers".
+     *
+     * Taken as a string and wrapped in an `Audience` node here, rather than
+     * asking a project for the node: there is exactly one shape it can take,
+     * and a hand-written `{"@type": "Audiance"}` type-checks against every
+     * `JsonLdNode` lib accepts. The string is the part only a project knows.
+     */
+    readonly audience?: string;
+    /** Where the work is offered. Omitted rather than emitted empty. */
+    readonly areaServed?: readonly ServiceArea[];
+}
+
+/** An `Audience` node, or nothing. See `ServiceInput.audience`. */
+function audienceFor(audienceType: string | undefined): {
+    readonly audience?: JsonLdNode;
+} {
+    return audienceType === undefined
+        ? {}
+        : { audience: { "@type": "Audience", audienceType } };
+}
+
+/** `areaServed`, as `Place` nodes. See `ServiceArea`. */
+function areasFor(areas: readonly ServiceArea[] | undefined): {
+    readonly areaServed?: readonly JsonLdNode[];
+} {
+    // Length rather than presence: a service that serves nowhere in particular
+    // says nothing, and an empty list is a claim to have been asked and had no
+    // answer.
+    if (areas === undefined || areas.length === 0) return {};
+
+    return {
+        areaServed: areas.map((area) => ({
+            "@type": area.kind ?? "AdministrativeArea",
+            name: area.name,
+        })),
+    };
+}
+
+/**
+ * One service, on the page that describes it.
+ *
+ * Reference: <https://schema.org/Service>
+ */
+export function service(input: ServiceInput): JsonLdNode {
+    return {
+        "@type": "Service",
+        "@id": serviceId(input.url),
+        name: input.name,
+        url: input.url,
+        ...(input.description === undefined
+            ? {}
+            : { description: input.description }),
+        ...(input.serviceType === undefined
+            ? {}
+            : { serviceType: input.serviceType }),
+        ...(input.provider === undefined
+            ? {}
+            : { provider: { "@id": input.provider } }),
+        ...audienceFor(input.audience),
+        ...areasFor(input.areaServed),
+    };
+}
+
+/** One line of a catalogue: a service, named, and linked if it has a page. */
+export interface CatalogEntry {
+    readonly name: string;
+    /**
+     * The page describing this service, where there is one.
+     *
+     * Supplying it is what ties this line to the full node that page emits,
+     * through the id both derive from `serviceId`. Leave it out for something
+     * offered but not written up, and the entry stands alone as a name.
+     */
+    readonly url?: HttpsUrl;
+    readonly description?: string;
+}
+
+export interface OfferCatalogInput {
+    /** What the list is called — "What we do", "Franchise packages". */
+    readonly name: string;
+    readonly description?: string;
+    /**
+     * Who offers them, as an `@id` — the venue or the brand.
+     *
+     * **Required**, unlike `ServiceInput.provider`, and the difference is not
+     * an oversight. A service node carries an `@id` of its own, so a catalogue
+     * elsewhere can point at it and the graph joins up either way. This node
+     * has no id and nothing refers to it, so `provider` is the *only* edge it
+     * has: without one it is a list of services belonging to nobody, sitting in
+     * a graph beside a business it never mentions.
+     *
+     * There is always an answer to hand. Every page that renders this also
+     * renders the site graph, so the venue's `businessId` and the brand's
+     * `organizationId` are both already built.
+     */
+    readonly provider: BusinessId | OrganizationId;
+    readonly entries: readonly CatalogEntry[];
+}
+
+/**
+ * Everything the business offers, listed in one place.
+ *
+ * ## Which page this goes on
+ *
+ * **The page that shows the offerings** — a "what we do" index, a services
+ * page. Failing that, the home page, exactly as `website()` does and for the
+ * same reason: it is a fact about the whole site, and one page has to carry it.
+ * Pass it through that view's own `jsonLd`, never through the site-wide graph.
+ *
+ * There is deliberately no way to hang a catalogue off `localBusiness()` or
+ * `organization()` as `hasOfferCatalog`. That says the same thing to a crawler
+ * as this node's `provider` does in reverse, and those two nodes are normally
+ * built once and emitted on every URL — so the nested form would drag the whole
+ * list onto every page of the site to state a fact already stated here. One
+ * shape, on one page.
+ *
+ * ## What it emits
+ *
+ * Each entry names a service and, where that service has a page, carries the
+ * same `@id` that page's own node does: one thing in the graph, described
+ * twice, rather than two things spelled alike.
+ *
+ * The catalogue itself has **no `@id`** — nothing points at one, which is the
+ * test `ids.ts` applies, and it is in the same position as `Product`, `Article`
+ * and `BreadcrumbList`. Two things make that comfortable rather than merely
+ * defensible: a catalogue has no natural unique key, so a minted fragment could
+ * collide with a second catalogue on the same page and silently merge the two
+ * lists; and if something ever does point at one — a `Service` gaining
+ * `hasOfferCatalog` — the id is an optional input field added then, which
+ * breaks no existing call. `provider` is required precisely because of this:
+ * with no id and nothing referring to it, that edge is the node's only
+ * attachment to the rest of the graph.
+ *
+ * Entries are wrapped in `Offer` because that is what an `OfferCatalog` holds —
+ * `itemListElement` takes offers, and `itemOffered` is where the service goes.
+ * The offers carry no price, deliberately: see the note at the top of this file.
+ *
+ * Reference: <https://schema.org/OfferCatalog>
+ */
+export function offerCatalog(input: OfferCatalogInput): JsonLdNode {
+    return {
+        "@type": "OfferCatalog",
+        name: input.name,
+        ...(input.description === undefined
+            ? {}
+            : { description: input.description }),
+        // Unconditional: this is the node's only link to anything.
+        provider: { "@id": input.provider },
+        itemListElement: input.entries.map((entry) => ({
+            "@type": "Offer",
+            itemOffered: {
+                "@type": "Service",
+                // The id only where there is a page to hang it on. A fragment
+                // invented for an entry with no page would be an identity for
+                // something nothing else can ever refer to.
+                ...(entry.url === undefined
+                    ? {}
+                    : { "@id": serviceId(entry.url), url: entry.url }),
+                name: entry.name,
+                ...(entry.description === undefined
+                    ? {}
+                    : { description: entry.description }),
+            },
+        })),
+    };
+}

package/src/jsonld/video.ts

@@ -0,0 +1,239 @@
+import type { ImageAsset } from "../image.ts";
+import type { IsoDate } from "../types.ts";
+import { absoluteUrl, type HttpsUrl } from "../url.ts";
+import { warn } from "../warn.ts";
+import { type JsonLdNode, oneOrMany } from "./node.ts";
+
+interface VideoDetails {
+    /** What the video is called — not the page's title unless they match. */
+    readonly name: string;
+    /**
+     * The site's own origin, which the thumbnails are made absolute against.
+     *
+     * An origin rather than the page's URL: `joinUrl` puts a path on the end of
+     * what it is given, so handing it `…/challenges/cardio` would produce
+     * `…/challenges/cardio/thumb.png`. The same bargain `localBusiness` strikes,
+     * named for what it actually needs.
+     */
+    readonly origin: HttpsUrl;
+    /**
+     * Still frames. Required by Google, and worth giving several: their
+     * thumbnail guidance asks for one per aspect ratio a result may use, which
+     * is what `photoSet` in `astro/images.ts` cuts from one source.
+     *
+     * An asset *or* an absolute URL, because the two hosting stories differ. A
+     * self-hosted clip has a still in the repo; a YouTube one already has
+     * thumbnails on `i.ytimg.com` and copying them locally would be keeping a
+     * second copy of somebody else's file.
+     */
+    readonly thumbnail: readonly [
+        ImageAsset | HttpsUrl,
+        ...(ImageAsset | HttpsUrl)[],
+    ];
+    /**
+     * When it was first published.
+     *
+     * Google asks for ISO 8601 and recommends a timezone; a date is valid
+     * ISO 8601 at reduced precision, and is the precision anyone actually has
+     * for "when did we put the trailer up".
+     */
+    readonly uploadDate: IsoDate;
+    readonly description?: string;
+    /**
+     * How long it runs, **in seconds**.
+     *
+     * A number rather than the `PT1M30S` the spec wants, because that format is
+     * lib's problem and not a project's. The same trade `RobotsPolicy` makes
+     * with `-1` and `0`: state the fact, let the helper spell it.
+     */
+    readonly durationSeconds?: number;
+}
+
+/**
+ * How a crawler reaches the video. At least one way, and both are allowed.
+ *
+ * *Not* mutually exclusive, which is the tempting reading. Google states a
+ * preference rather than a choice: *"We recommend that you provide the
+ * `contentUrl` property, if possible… If `contentUrl` isn't available, provide
+ * `embedUrl` as an alternative."* A self-hosted clip that also has a player
+ * page has both, both are true, and neither is ignored — the file is used and
+ * the player is there to fall back to. Forbidding that would invent a rule.
+ *
+ * What the union does forbid is *neither*. Both are merely recommended by
+ * Google, so a `VideoObject` with no way to fetch the video is valid markup —
+ * and useless, which is the failure this file keeps making unwritable rather
+ * than detecting. A video nobody can reach is a claim that a video exists.
+ *
+ * Neither may be the **watch page**. Google is explicit about that, and
+ * `youtube.com/watch?v=<id>` is exactly what a watch page is — the URL anyone
+ * reaches for first, and the one that belongs in neither field.
+ */
+export type VideoSource =
+    | {
+          /**
+           * The video file itself — the bytes. *"The most effective way"* for
+           * Google to fetch it, so prefer it where the file is yours.
+           */
+          readonly contentUrl: HttpsUrl;
+          /** A player for it, where one exists as well. */
+          readonly embedUrl?: HttpsUrl;
+      }
+    | {
+          readonly contentUrl?: undefined;
+          /**
+           * A player for this video, for when the file is not yours to expose.
+           *
+           * **The YouTube case.** The video need not be hosted here at all;
+           * what Google asks for is a way to reach it, and for YouTube that is
+           * the *embed* URL — `https://www.youtube.com/embed/<id>`.
+           */
+          readonly embedUrl: HttpsUrl;
+      };
+
+/** Everything about the video, plus one of the two ways to reach it. */
+export type VideoInput = VideoDetails & VideoSource;
+
+/**
+ * The hosts that serve a YouTube watch page, spelled out.
+ *
+ * A set rather than a pattern, so `notyoutube.com` cannot match by containing
+ * the name, and a new subdomain is one line rather than a puzzle.
+ */
+const YOUTUBE_WATCH_HOSTS = new Set([
+    "youtube.com",
+    "www.youtube.com",
+    "m.youtube.com",
+    "music.youtube.com",
+]);
+
+/**
+ * Whether a URL is the page a video is *watched* on, rather than the video.
+ *
+ * Parsed rather than matched. A pattern over the whole string cannot tell a
+ * host from a path, so `https://x.example/?ref=youtube.com/watch` reads as a
+ * watch page to it, and so does `https://notyoutube.com/watch` — and a warning
+ * that fires on innocent URLs is one people learn to ignore. The `hostname` and
+ * the `pathname` are the two things actually being asked about, so those are
+ * the two things to look at.
+ *
+ * Anything unparseable is not a watch page as far as this is concerned: the
+ * argument is typed `https://…`, and a URL this cannot read is a problem for
+ * somewhere else to report.
+ */
+function isWatchPage(url: string): boolean {
+    let parsed: URL;
+    try {
+        parsed = new URL(url);
+    } catch {
+        return false;
+    }
+
+    if (YOUTUBE_WATCH_HOSTS.has(parsed.hostname)) {
+        return parsed.pathname === "/watch";
+    }
+    // A youtu.be link is only ever a watch link: the id is the whole path.
+    if (parsed.hostname === "youtu.be") return parsed.pathname.length > 1;
+    return false;
+}
+
+/**
+ * Seconds as ISO 8601, which is what `duration` is read as: `PT1M30S`.
+ *
+ * `undefined` for anything that is not a length — absent, fractional, negative,
+ * or zero. A video of no duration is not a video, so there is nothing to state,
+ * and the empty case that would have produced a bare `PT` cannot arise.
+ *
+ * The whole rule lives here rather than half here and half at the call site.
+ * Written twice, the two could disagree about what counts as a length, and the
+ * caller would emit something this function had already judged unusable.
+ */
+function isoDuration(seconds: number | undefined): string | undefined {
+    if (seconds === undefined) return undefined;
+    if (!Number.isInteger(seconds) || seconds <= 0) return undefined;
+
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const rest = seconds % 60;
+    return `PT${hours > 0 ? `${hours}H` : ""}${minutes > 0 ? `${minutes}M` : ""}${rest > 0 ? `${rest}S` : ""}`;
+}
+
+/**
+ * A video on this page — a room trailer, a walkthrough.
+ *
+ * Its own node rather than a property of something else: Google reads a
+ * `VideoObject` from the page it plays on, and a video is a thing in its own
+ * right rather than a field of the room it depicts.
+ *
+ * `name`, `thumbnailUrl` and `uploadDate` are required by Google and are
+ * required here. The rest of its recommended list — `expires`, `hasPart`,
+ * `interactionStatistic`, `publication`, `regionsAllowed` — is deliberately
+ * absent: each answers a question this site does not have (a video that
+ * expires, chapters, view counts, a live broadcast, geo-restriction), and a
+ * field with nothing to put in it is a field that gets filled in wrongly.
+ *
+ * Reference:
+ * <https://developers.google.com/search/docs/appearance/structured-data/video>
+ */
+export function videoObject(video: VideoInput): JsonLdNode {
+    // The one mistake Google names outright, and the one anyone makes: a watch
+    // page in a field that wants the file or the player. It is what the address
+    // bar holds while you are looking at the video, so it is what gets pasted.
+    //
+    // A warning rather than a type, because "watch page" is not a shape — it is
+    // a fact about one platform's URLs. Recognising YouTube's catches almost
+    // every instance without lib growing a list of video hosts, and without
+    // refusing a URL it has merely not heard of: anything unrecognised passes,
+    // which is the right way for a heuristic to fail.
+    for (const [field, url] of [
+        ["contentUrl", video.contentUrl],
+        ["embedUrl", video.embedUrl],
+    ] as const) {
+        if (url !== undefined && isWatchPage(url)) {
+            warn(
+                video.origin,
+                `video "${video.name}" gives a watch page as ${field}. Google asks for the file or the player and not the page it is watched on — for YouTube that is https://www.youtube.com/embed/<id> as embedUrl.`
+            );
+        }
+    }
+
+    // Asked for and not usable, which is the only case worth a line: absent is
+    // absent, and `isoDuration` has already decided what counts as a length.
+    const duration = isoDuration(video.durationSeconds);
+    if (video.durationSeconds !== undefined && duration === undefined) {
+        warn(
+            video.origin,
+            `video "${video.name}" has a duration of ${video.durationSeconds}, which is not a length: expected a whole number of seconds above zero. Leaving it out — a duration a crawler cannot parse is one it drops.`
+        );
+    }
+
+    return {
+        "@type": "VideoObject",
+        name: video.name,
+        // `absoluteUrl` already takes either an `https://` URL or a path from
+        // the root, so a remote thumbnail passes through and a local asset is
+        // joined — the same call serves a YouTube still and a file in `src/`.
+        //
+        // Through `oneOrMany` for the reason `@type` is: the input is a list
+        // because Google asks for several ratios, but a video with one still
+        // should say so as a string rather than as a list of one. Same rule,
+        // same file, no exemption to explain.
+        thumbnailUrl: oneOrMany(
+            video.thumbnail.map((frame) =>
+                absoluteUrl(
+                    video.origin,
+                    typeof frame === "string" ? frame : frame.src,
+                    `video thumbnail for "${video.name}"`
+                )
+            )
+        ),
+        uploadDate: video.uploadDate,
+        ...(video.description === undefined
+            ? {}
+            : { description: video.description }),
+        ...(duration === undefined ? {} : { duration }),
+        ...(video.contentUrl === undefined
+            ? {}
+            : { contentUrl: video.contentUrl }),
+        ...(video.embedUrl === undefined ? {} : { embedUrl: video.embedUrl }),
+    };
+}

package/src/jsonld/website.ts

@@ -0,0 +1,58 @@
+import type { HttpsUrl } from "../url.ts";
+import { type OrganizationId, websiteId } from "./ids.ts";
+import { alternateName, type JsonLdNode } from "./node.ts";
+
+export interface WebsiteInput {
+    /**
+     * What the site is called — the name a result should show above the URL.
+     *
+     * Google reads `og:site_name`, the `<title>` and the home page's headings
+     * too, and mostly gets it right from those. Stating it here is the only way
+     * to express a *preference* rather than leave it to be inferred, and the
+     * only way to offer the alternate below.
+     */
+    readonly name: string;
+    /** The site's own home page. Also its identity, see `@id`. */
+    readonly url: HttpsUrl;
+    /**
+     * A shorter name or an acronym, offered as a fallback.
+     *
+     * The one thing this node can say that nothing else can. A venue called
+     * "Acme Rome" whose brand is "Acme" has a second name worth naming, and
+     * there is no meta tag for it.
+     */
+    readonly alternateName?: string;
+    /** The `@id` of the organization that publishes it, from `organization()`. */
+    readonly publisher?: OrganizationId;
+}
+
+/**
+ * The site itself, as an entity.
+ *
+ * **Home page only.** Google: *"The `WebSite` structured data must be on the
+ * home page of the site."* On any other page it is ignored at best, so this is
+ * the one node here that a layout must not emit everywhere — pass it through a
+ * view's own `jsonLd`.
+ *
+ * Worth emitting despite Google saying it *"does not guarantee"* to use the
+ * name: the cost is one small node on one page, and an inferred name that comes
+ * out wrong is not otherwise correctable.
+ *
+ * No `potentialAction`. The `SearchAction` that once put a search box in a
+ * result was retired in November 2024 — see `NOT-BUILT.md`.
+ *
+ * Reference:
+ * <https://developers.google.com/search/docs/appearance/site-names>
+ */
+export function website(site: WebsiteInput): JsonLdNode {
+    return {
+        "@type": "WebSite",
+        "@id": websiteId(site.url),
+        name: site.name,
+        url: site.url,
+        ...alternateName(site.name, site.alternateName),
+        ...(site.publisher === undefined
+            ? {}
+            : { publisher: { "@id": site.publisher } }),
+    };
+}