@escape-game-over/atlas 0.1.1

package/src/jsonld/ids.ts

@@ -0,0 +1,106 @@
+import { type HttpsUrl, normalizeOrigin } from "../url.ts";
+
+/**
+ * The `@id` each addressable node takes, and the types that keep them apart.
+ *
+ * Their own file because both ends need them: the node that *is* the thing, and
+ * every node that points at it. A fragment invented separately at each end is a
+ * dangling reference that no validator reports and no crawler resolves.
+ *
+ * ## Which nodes get one
+ *
+ * **An `@id` is for being pointed at.** That is the whole test, and it splits
+ * what lib emits cleanly in two:
+ *
+ * - *With* — `LocalBusiness`, `Organization`, `WebSite`, `Service`. Each is
+ *   referred to by something else: a product names its seller, an article its
+ *   publisher, a venue its parent brand, a catalogue the services it lists.
+ * - *Without* — `Product`, `Article`, `VideoObject`, `BreadcrumbList`,
+ *   `OfferCatalog`. Nothing in the graph refers to these, so a fragment on each
+ *   would be an identity kept in step with nothing. They are ordinary
+ *   unidentified nodes, as a `PostalAddress` inside a business is.
+ *
+ * Two things follow, and both have come up:
+ *
+ * 1. **An unused id is not free.** An `@id` is a claim that two nodes carrying
+ *    it are the same thing, so a crawler *merges* them. That is the mechanism
+ *    behind `organizationId` — and the reason not to mint fragments for nodes
+ *    with no natural key. A service page is one page and one service, so
+ *    `serviceId` cannot collide; a catalogue has no such key, and two on one
+ *    page deriving `#offer-catalog` alike would silently become one list.
+ * 2. **Adding one later is additive, not a migration.** The input gains an
+ *    optional field and every existing call still compiles, so nothing here is
+ *    being deferred at the cost of a sweep through the consuming projects.
+ *    Mint an id the day something points at the node, and not before.
+ */
+
+/**
+ * The identity of a business node: an origin with the `#business` fragment.
+ *
+ * A shape rather than an opaque brand, like `EmailAddress`. What makes an id
+ * valid is what it looks like, so the type says that and stays honest: a
+ * hand-written `"https://x.example#business"` is a perfectly good id and type
+ * -checks, while the mistake this exists to stop — passing a bare URL where a
+ * reference belongs — does not.
+ */
+export type BusinessId = `${HttpsUrl}#business`;
+
+/** The identity of a brand node. See `BusinessId`. */
+export type OrganizationId = `${HttpsUrl}#organization`;
+
+/** The identity of a site node. See `BusinessId`. */
+export type WebsiteId = `${HttpsUrl}#website`;
+
+/**
+ * The identity of a service node — a *page's* URL with `#service`, not an
+ * origin's.
+ *
+ * The one id here that is not site-level, and the reason it is not: a site has
+ * one business, one brand and one site node, so those three are fragments on an
+ * origin. It has as many services as it has service pages, and they need
+ * telling apart.
+ *
+ * It exists because two pages describe the same service: the page that *is* it,
+ * and the catalogue elsewhere that lists it among the others. Without a shared
+ * id those are two services that happen to be spelled alike — which is the same
+ * failure `organizationId` exists to stop, one level down.
+ */
+export type ServiceId = `${HttpsUrl}#service`;
+
+/**
+ * The `@id` a business node takes, from the site's origin.
+ *
+ * Exported because a reference has to be built by whoever points at it, and the
+ * fragment must match exactly — a node linking to `#local-business` when the
+ * business calls itself `#business` is a dangling reference that no validator
+ * reports and no crawler resolves. One definition, used by both ends.
+ */
+export function businessId(url: HttpsUrl): BusinessId {
+    return `${normalizeOrigin(url)}#business`;
+}
+
+/** The `@id` a brand node takes. See `businessId`. */
+export function organizationId(url: HttpsUrl): OrganizationId {
+    return `${normalizeOrigin(url)}#organization`;
+}
+
+/** The `@id` a site node takes. See `businessId`. */
+export function websiteId(url: HttpsUrl): WebsiteId {
+    return `${normalizeOrigin(url)}#website`;
+}
+
+/**
+ * The `@id` a service node takes, from **the service's own page**.
+ *
+ * The origin is deliberately not normalised away, unlike the three above: those
+ * identify things a site has one of, this identifies one of many. Pass the same
+ * URL the service page is canonical at, and the catalogue listing it will point
+ * at the node that page emits.
+ *
+ * The only per-page id here, and the only one lib mints beyond the three
+ * site-level ones — see the note at the top of this file for the test that
+ * decides which nodes get one.
+ */
+export function serviceId(url: HttpsUrl): ServiceId {
+    return `${url}#service`;
+}

package/src/jsonld/index.ts

@@ -0,0 +1,59 @@
+/**
+ * Structured data, as one `@graph` per page.
+ *
+ * One script rather than several: the nodes describe one page, and a node that
+ * names another by `@id` — a review pointing at the business it reviews — is
+ * resolved within the graph it shares. Separate blocks are read separately, so
+ * that reference has nothing to land on.
+ *
+ * lib emits only what it can *derive* — a breadcrumb is the route table read
+ * back — because everything else is a claim about a business, and a claim lib
+ * invented would be a claim nobody checked.
+ *
+ * **Who this is written for: Google.** Every other reader is welcome and none
+ * of them breaks a tie. It comes up more often than it looks, because the
+ * markup that suits a search engine and the markup that suits a naive scraper
+ * are not always the same — a scraper that string-matches `"LocalBusiness"`
+ * wants the general type stated, while Google asks for the most specific
+ * subtype and resolves the hierarchy itself. Where the two disagree, follow the
+ * documented guidance and let the scraper miss it.
+ *
+ * Which is why the doc on a field tends to quote Google verbatim and date the
+ * check. A rule you can trace to a sentence survives the next person who reads
+ * the schema.org page and concludes something reasonable and different.
+ *
+ * **One file per node.** Each is a self-contained answer to "what does Google
+ * read here, and why this shape" — several hundred lines of that reasoning,
+ * which is worth keeping beside its own node rather than a thousand lines from
+ * somewhere else. What they share lives in `node.ts` and `ids.ts`, and only
+ * `place.ts` and `quantity.ts` are used by more than one.
+ */
+
+export { type ArticleInput, article } from "./article.ts";
+export { type BreadcrumbStep, breadcrumbList } from "./breadcrumb.ts";
+export { type LocalBusinessInput, localBusiness } from "./business.ts";
+export {
+    type BusinessId,
+    businessId,
+    type OrganizationId,
+    organizationId,
+    type ServiceId,
+    serviceId,
+    type WebsiteId,
+    websiteId,
+} from "./ids.ts";
+export { type JsonLdNode, serializeJsonLd } from "./node.ts";
+export { type OrganizationInput, organization } from "./organization.ts";
+export { geoCoordinates, openingHours, postalAddress } from "./place.ts";
+export { type ProductInput, product } from "./product.ts";
+export { quantitativeValue, quantitiesFor } from "./quantity.ts";
+export {
+    type CatalogEntry,
+    type OfferCatalogInput,
+    offerCatalog,
+    type ServiceArea,
+    type ServiceInput,
+    service,
+} from "./service.ts";
+export { type VideoInput, type VideoSource, videoObject } from "./video.ts";
+export { type WebsiteInput, website } from "./website.ts";

package/src/jsonld/node.ts

@@ -0,0 +1,78 @@
+/**
+ * What a node is, and how a graph of them is written out.
+ *
+ * The mechanics rather than the vocabulary: every other file here builds one
+ * kind of node and imports these to do it.
+ */
+
+/** A node in the graph. Deliberately loose: `@type` is what a consumer varies. */
+export interface JsonLdNode {
+    readonly "@type": string | readonly string[];
+    readonly [key: string]: unknown;
+}
+
+/**
+ * A value as JSON-LD is normally written: bare for one, a list for several.
+ *
+ * Input and output are separate concerns here. A caller may write either shape,
+ * because always-an-array would mean `["Restaurant"]` at every call site to
+ * serve the rare case — but a list of one in the *output* reads as a bug to
+ * anyone who has seen ordinary JSON-LD, which is the same smell as the
+ * `["LocalBusiness"]` this file used to emit. So the shape is decided once,
+ * here, rather than passed through from whatever a caller happened to type.
+ *
+ * Generic because two fields want it and the rule is the same on both: `@type`,
+ * where several means a thing that is genuinely several things, and `image`,
+ * where several means one picture at several ratios.
+ */
+export function oneOrMany<T>(value: T | readonly T[]): T | readonly T[] {
+    if (!Array.isArray(value)) return value;
+    const [only, ...rest] = value as readonly T[];
+    return only !== undefined && rest.length === 0 ? only : value;
+}
+
+/** `@type`, in the shape JSON-LD is normally written. See `oneOrMany`. */
+export function schemaType(
+    type: string | readonly string[]
+): string | readonly string[] {
+    return oneOrMany(type);
+}
+
+/**
+ * `alternateName`, if there is a second name worth offering.
+ *
+ * Dropped when it matches the name it is an alternative to, because a search
+ * engine reads it as *another* name and a repeat of the first one is not that:
+ * it widens nothing and is one more string to reconcile. Decided here rather
+ * than by the caller — three nodes take the field, the rule is the same on all
+ * of them, and a project asked to write `name === alt ? {} : { alt }` at each
+ * one is being handed lib's rule to enforce by hand.
+ *
+ * Which makes `alternateName: brand.name` safe to pass unconditionally: a venue
+ * whose name already *is* the brand's simply emits nothing.
+ */
+export function alternateName(
+    name: string,
+    alternate: string | undefined
+): { readonly alternateName?: string } {
+    return alternate === undefined || alternate === name
+        ? {}
+        : { alternateName: alternate };
+}
+
+/**
+ * The graph, serialised for a `<script type="application/ld+json">`.
+ *
+ * Every `<` is replaced by its unicode escape, and that is the whole reason
+ * this is a function rather than a `JSON.stringify` at the call site. A script element ends at the first
+ * `</script` in its text, so a business name, a room description or an alt text
+ * containing one would close the block early and spill the rest of the graph
+ * into the page as markup. The escape is invisible to a JSON parser and to
+ * anything reading the data.
+ */
+export function serializeJsonLd(nodes: readonly JsonLdNode[]): string {
+    return JSON.stringify({
+        "@context": "https://schema.org",
+        "@graph": nodes,
+    }).replaceAll("<", "\\u003c");
+}

package/src/jsonld/organization.ts

@@ -0,0 +1,154 @@
+import {
+    type EmailAddress,
+    e164,
+    type PhoneNumber,
+    type PostalAddress,
+} from "../contact.ts";
+import { type HttpsUrl, joinUrl, type UrlPath } from "../url.ts";
+import { organizationId } from "./ids.ts";
+import { alternateName, type JsonLdNode } from "./node.ts";
+import { postalAddress } from "./place.ts";
+
+export interface OrganizationInput {
+    /** The brand's name, which is not necessarily any one venue's name. */
+    readonly name: string;
+    /** The brand's own home. Also its identity, see `@id` below. */
+    readonly url: HttpsUrl;
+    /**
+     * Another name the brand actually goes by — an acronym, a short form.
+     *
+     * Google's test is the word *common*: "another common name that your
+     * organization goes by". A name people use, not a convention invented for
+     * the markup — a form nobody types is worse than none, because it is a name
+     * offered to match queries that will never contain it.
+     *
+     * Google also says to keep this in step with the site name. That holds when
+     * one organization publishes one site; where a brand publishes a site per
+     * venue the two names differ on purpose, and it is the *brand's* aliases
+     * that belong here.
+     */
+    readonly alternateName?: string;
+    /**
+     * The brand's logo, as a path on `url` — `"/logo.png"`.
+     *
+     * The reason most sites want this node at all: it is what a knowledge panel
+     * shows. Google asks for at least 112×112 and prefers a plain mark on a
+     * clear background over a photograph.
+     *
+     * A path rather than a URL so it cannot be hosted anywhere but the brand's
+     * own origin. A node claiming the brand lives at one address while keeping
+     * its logo at another is the mistake this shape makes unwritable, and the
+     * origin stops being repeated in a second place that can disagree.
+     *
+     * Prefer a stable path over a bundled asset: `/_astro/logo.<hash>.png`
+     * moves whenever the file is touched, and this is entity data a search
+     * engine keeps, not a page resource it re-fetches.
+     */
+    readonly logo?: UrlPath;
+    /**
+     * The registered name, where it differs from the trading one.
+     *
+     * "Acme Entertainment SRL" against "Acme". Worth stating when they differ,
+     * because it is what ties the brand to public records.
+     */
+    readonly legalName?: string;
+    /**
+     * How to reach the *company*, as opposed to any one of its venues.
+     *
+     * Flat rather than a `ContactPoint`, which is the shape you would expect
+     * from reading schema.org. Google's Organization page documents `telephone`
+     * and `email` directly, and documents exactly two sub-properties under
+     * `contactPoint` — `telephone` and `email`. So the nested form carries the
+     * same two facts one level deeper.
+     *
+     * What would have justified the nesting is `contactType`, which separates a
+     * sales line from a support line. That belonged to the Corporate Contact
+     * feature, and Google retired it: its documentation now redirects to a
+     * knowledge-panel help page that does not mention structured data. Checked
+     * August 2026.
+     *
+     * Only worth filling in where the company really is reachable separately.
+     * A brand whose only number belongs to one of its venues should leave both
+     * out: putting that number here says that venue answers for the company,
+     * and a contact that misdirects is worse than one that is absent.
+     */
+    readonly telephone?: PhoneNumber;
+    readonly email?: EmailAddress;
+    /**
+     * Pages elsewhere that are unmistakably this brand.
+     *
+     * The same field as on a venue, one level up — social accounts, Wikipedia,
+     * Wikidata, a trade listing. It is what lets a search engine decide two
+     * mentions are the same company, which is the whole business of a knowledge
+     * panel. Pages *about* the brand that it does not control — a press
+     * write-up — are not it.
+     */
+    readonly sameAs?: readonly HttpsUrl[];
+    /**
+     * Where the company is, when there is a single answer.
+     *
+     * Optional, unlike `LocalBusinessInput.address`, and the difference is the
+     * whole distinction between the two nodes. A venue *is* a place and cannot
+     * be described without one. A company need not be: a brand with venues in
+     * three cities has three addresses, and each belongs to the venue that
+     * keeps it — stating one here would pick a favourite, and stating the head
+     * office would invite a search engine to put the wrong city beside every
+     * room.
+     *
+     * So it is for the other shape, which the second example is: one company,
+     * one workshop, no venue node at all. Without this the address reaches the
+     * contact page and nothing in the graph.
+     *
+     * Google lists it as recommended — *"The address (physical or mailing) of
+     * your organization, if applicable"* — and "if applicable" is doing the same
+     * work as the `?` here. Checked August 2026.
+     */
+    readonly address?: PostalAddress;
+}
+
+/**
+ * The brand behind the site.
+ *
+ * **Only worth emitting when the brand is bigger than the venue.** A
+ * `LocalBusiness` already *is* an `Organization` — the type extends it — so a
+ * single independent venue should put `logo` and `sameAs` straight on its
+ * business node and stop there. Two nodes for one entity is not more
+ * information, it is the same claim made twice for a crawler to reconcile.
+ *
+ * It earns its place when several venues share a name: each site declares its
+ * own `LocalBusiness` and points `parentOrganization` at the same brand `@id`,
+ * which is what says the Rome and Bucharest rooms are one company rather than
+ * two that happen to be spelled alike.
+ *
+ * The `@id` is the brand's URL with a fragment, and is therefore identical on
+ * every deployment — which is the entire mechanism. Point two sites at
+ * different ids and they are two brands.
+ *
+ * Reference:
+ * <https://developers.google.com/search/docs/appearance/structured-data/organization>
+ */
+export function organization(brand: OrganizationInput): JsonLdNode {
+    return {
+        "@type": "Organization",
+        "@id": organizationId(brand.url),
+        name: brand.name,
+        url: brand.url,
+        ...alternateName(brand.name, brand.alternateName),
+        ...(brand.logo === undefined
+            ? {}
+            : { logo: joinUrl(brand.url, brand.logo) }),
+        ...(brand.legalName === undefined
+            ? {}
+            : { legalName: brand.legalName }),
+        // E.164, as on the business: the only form that identifies a number
+        // unambiguously enough to match a company against a listing.
+        ...(brand.telephone === undefined
+            ? {}
+            : { telephone: e164(brand.telephone) }),
+        ...(brand.email === undefined ? {} : { email: brand.email }),
+        ...(brand.sameAs === undefined ? {} : { sameAs: brand.sameAs }),
+        ...(brand.address === undefined
+            ? {}
+            : { address: postalAddress(brand.address) }),
+    };
+}

package/src/jsonld/place.ts

@@ -0,0 +1,96 @@
+import {
+    assertCoordinates,
+    type Coordinates,
+    type PostalAddress,
+} from "../contact.ts";
+import {
+    assertHours,
+    groupHours,
+    schemaDays,
+    type WeeklyHours,
+} from "../hours.ts";
+import type { JsonLdNode } from "./node.ts";
+
+/**
+ * The sub-nodes that say where a place is and when it is open.
+ *
+ * Together because they are the same kind of thing — facts about a location,
+ * each checked at the point it becomes a claim — and because a venue node is
+ * the only thing that assembles all three.
+ */
+
+/**
+ * A `PostalAddress`, from the parts a project stores.
+ *
+ * A node rather than a string, which `address` also accepts: the components are
+ * what a search engine matches a business against a place with, and handing over
+ * one joined line makes it guess where the town ends. `region` is omitted rather
+ * than sent empty — a country that does not use one should not appear to have
+ * left it blank.
+ *
+ * Reference: <https://schema.org/PostalAddress>, read by Google inside a
+ * business's `address`:
+ * <https://developers.google.com/search/docs/appearance/structured-data/local-business>
+ */
+export function postalAddress(address: PostalAddress): JsonLdNode {
+    return {
+        "@type": "PostalAddress",
+        streetAddress: address.street,
+        addressLocality: address.locality,
+        postalCode: address.postalCode,
+        addressCountry: address.country,
+        ...(address.region === undefined
+            ? {}
+            : { addressRegion: address.region }),
+    };
+}
+
+/**
+ * A week as `openingHoursSpecification`.
+ *
+ * One node per set of hours rather than per day: days that open at the same
+ * time are listed together, which is how the vocabulary is meant to be used and
+ * turns seven nodes into two. A day with a lunch break yields one node per span,
+ * sharing the day list.
+ *
+ * Closed days are left out. The specification says when a venue *is* open, so a
+ * day that appears nowhere in it is shut — which is unambiguous, where a span
+ * from 00:00 to 00:00 could be read as either closed or around the clock.
+ *
+ * Reference:
+ * <https://developers.google.com/search/docs/appearance/structured-data/local-business#business-hours>
+ */
+export function openingHours(hours: WeeklyHours): readonly JsonLdNode[] {
+    assertHours(hours, "openingHours");
+
+    return groupHours(hours).flatMap((group) =>
+        group.hours === "closed"
+            ? []
+            : group.hours.map((range) => ({
+                  "@type": "OpeningHoursSpecification",
+                  dayOfWeek: schemaDays(group),
+                  opens: range.opens,
+                  closes: range.closes,
+              }))
+    );
+}
+
+/**
+ * A point on the map, checked before it is published.
+ *
+ * The precision rule is enforced here rather than left to the caller because
+ * this is the only place that knows the coordinate is about to become a claim
+ * about where a building is.
+ *
+ * Reference: <https://schema.org/GeoCoordinates>, and the `geo` property in
+ * <https://developers.google.com/search/docs/appearance/structured-data/local-business>
+ */
+export function geoCoordinates(where: Coordinates): JsonLdNode {
+    assertCoordinates(where, "geoCoordinates");
+
+    return {
+        "@type": "GeoCoordinates",
+        latitude: where.latitude,
+        longitude: where.longitude,
+    };
+}

package/src/jsonld/product.ts

@@ -0,0 +1,172 @@
+import {
+    assertPriceTiers,
+    type Price,
+    type PriceTier,
+    type TieredPrice,
+} from "../money.ts";
+import type { HttpsUrl } from "../url.ts";
+import type { BusinessId, OrganizationId } from "./ids.ts";
+import { type JsonLdNode, schemaType } from "./node.ts";
+import { quantitativeValue } from "./quantity.ts";
+
+export interface ProductInput {
+    readonly name: string;
+    readonly description: string;
+    /** This product's own page. */
+    readonly url: HttpsUrl;
+    /** A picture of it, absolute. */
+    readonly image?: HttpsUrl;
+    /**
+     * What it costs: one price, or a price per quantity.
+     *
+     * The reason to emit this node at all — an offer with a price and a
+     * currency is what a search result can show a number for. A product with no
+     * offer is a name and a picture, which the page already said.
+     *
+     * A table becomes an `AggregateOffer` carrying the range, with each band as
+     * an `Offer` inside it. Two bare prices on one product would otherwise read
+     * as a contradiction rather than as a discount.
+     */
+    readonly price: Price | TieredPrice;
+    /**
+     * The `@id` of whoever sells it — a venue, or the company itself.
+     *
+     * A reference rather than a repeat: the seller is described once, in its own
+     * node, with the address and the rest that make it a real entity.
+     *
+     * Both id types, matching `ServiceInput.provider`. schema.org's `seller`
+     * expects an `Organization`, and a `LocalBusiness` *is* one — the narrower
+     * type here was an accident of the first site that needed it, where the
+     * seller happened to be a venue. A company that sells from a workshop
+     * rather than a shopfront publishes one `Organization` and has no business
+     * node to point at, and could not name its seller at all.
+     */
+    readonly seller?: BusinessId | OrganizationId;
+    /**
+     * Further types alongside `Product`, e.g. `"Game"`.
+     *
+     * *Alongside*, and deliberately unlike `LocalBusinessInput.type`, which
+     * replaces. The difference is whether one type implies the other: an
+     * `EntertainmentBusiness` already is a `LocalBusiness`, so naming both says
+     * one thing twice — while a `Game` is not a `Product` and a `Product` is
+     * not a `Game`. Two unrelated branches of the hierarchy, and the node is
+     * genuinely both: `Product` is what makes the offer legible to a search
+     * result, `Game` is what the thing actually is.
+     *
+     * Not checked against schema.org's vocabulary — see
+     * `LocalBusinessInput.type` for why.
+     */
+    readonly alsoA?: readonly string[];
+}
+
+/**
+ * Something the site sells, with its price.
+ *
+ * Vocabulary only — no notion of what this site's products *are*. A consumer
+ * adds whatever its own type calls for by spreading the result: the node is a
+ * plain object, and `numberOfPlayers` on a `Game` or `timeRequired` on a course
+ * is a fact about that domain, which lib has no way to check and no business
+ * inventing.
+ *
+ * `availability` is stated as in stock. A page that exists for a thing you can
+ * book is saying exactly that, and an offer with no availability is read as
+ * unknown rather than as available.
+ *
+ * Reference:
+ * <https://developers.google.com/search/docs/appearance/structured-data/product>
+ */
+export function product(item: ProductInput): JsonLdNode {
+    return {
+        // Through `schemaType` like every other node, so the ordinary case — a
+        // product that is only a product — emits `"Product"` rather than a
+        // one-element list. The rule was centralised and this call site was
+        // left building its own array.
+        "@type": schemaType(["Product", ...(item.alsoA ?? [])]),
+        name: item.name,
+        description: item.description,
+        url: item.url,
+        ...(item.image === undefined ? {} : { image: item.image }),
+        offers: offersFor(item),
+    };
+}
+
+/** The common parts of every `Offer` this file writes. */
+function offerFor(
+    item: ProductInput,
+    amount: number,
+    band?: PriceTier
+): JsonLdNode {
+    // `currency` is on both members of the union, so no narrowing is needed;
+    // `unit` describes what a quantity counts and only a table has one.
+    const unit = "tiers" in item.price ? item.price.unit : undefined;
+
+    return {
+        "@type": "Offer",
+        price: amount,
+        priceCurrency: item.price.currency,
+        availability: "https://schema.org/InStock",
+        url: item.url,
+        ...(band === undefined
+            ? {}
+            : {
+                  // What makes two prices a table rather than a contradiction:
+                  // each one says the quantity it applies at.
+                  //
+                  // The quantity is passed as written, not through `tierRange`:
+                  // the two take the same `number | { min, max }`, and widening
+                  // first would publish a band of one as `minValue: 2,
+                  // maxValue: 2` — a range across a single size, where `value:
+                  // 2` is the same claim said plainly.
+                  eligibleQuantity: {
+                      ...quantitativeValue(band.quantity),
+                      ...(unit === undefined ? {} : { unitText: unit }),
+                  },
+              }),
+        ...(item.seller === undefined
+            ? {}
+            : { seller: { "@id": item.seller } }),
+    };
+}
+
+/** One `Offer`, or an `AggregateOffer` wrapping the bands. */
+function offersFor(item: ProductInput): JsonLdNode {
+    if ("amount" in item.price) {
+        return offerFor(item, item.price.amount);
+    }
+
+    assertPriceTiers(item.price, "product");
+
+    // A table of one is one price, whatever it was written as. Wrapping it
+    // would emit an `AggregateOffer` whose low and high are the same number
+    // and whose `offerCount` is 1 — a range across nothing, and a shape that
+    // says "prices vary" of a product whose price does not. The band is still
+    // passed through, so a single row covering 2 to 6 keeps its
+    // `eligibleQuantity`: what collapses is the wrapper, not the quantity.
+    const [only, ...rest] = item.price.tiers;
+    if (rest.length === 0) return offerFor(item, only.amountPerUnit, only);
+
+    const amounts = item.price.tiers.map((tier) => tier.amountPerUnit);
+
+    // The wrapper carries the *aggregate* facts and nothing else. `seller`,
+    // `url` and `availability` are per-offer and sit on the bands, so a reader
+    // that descends finds each one complete and a reader that does not gets the
+    // range, which is what a result renders.
+    //
+    // Worth stating because the asymmetry looks like an oversight from one
+    // angle: an untiered product carries `seller` at the top level and a tiered
+    // one does not. Adding it here alone would be the arbitrary choice — it is
+    // one of three omissions, not one — and repeating an `@id` once per band
+    // plus once more says nothing the bands have not already said.
+    return {
+        "@type": "AggregateOffer",
+        priceCurrency: item.price.currency,
+        // The range is what a result renders; the bands below are the detail
+        // behind it. Both, because either alone is a worse answer.
+        lowPrice: Math.min(...amounts),
+        highPrice: Math.max(...amounts),
+        offerCount: item.price.tiers.length,
+        offers: item.price.tiers.map((tier) =>
+            offerFor(item, tier.amountPerUnit, tier)
+        ),
+    };
+}