@escape-game-over/atlas 0.1.1

package/src/index.ts

@@ -0,0 +1,222 @@
+/**
+ * The public API. A consuming project should need nothing outside this module.
+ *
+ * The flow is four steps, each inferring its types from the values of the last:
+ *
+ * ```ts
+ * // 1. site.config.ts — which languages exist, how URLs are shaped
+ * export default defineSiteConfig({ locales: {...}, defaultRouting: {...} })
+ *
+ * // 2. src/data — the base copy and routes
+ * export const baseMessages = defineMessages(config, {...})
+ * export const baseRoutes   = defineRoutes(config, {...})
+ *
+ * // 3. projects/<name>/project.ts — one deployment's overlay
+ * export default defineProject(config, baseMessages, baseRoutes, {...})
+ *
+ * // 4. src/site.ts — the API the pages use
+ * export const site = createSite(config, baseMessages, baseRoutes, project)
+ * ```
+ */
+
+export {
+    type AnalyticsSettings,
+    type AnalyticsTag,
+    type AnalyticsTags,
+    CONSENT_UPDATE_GLOBAL,
+    type ConsentDefaults,
+    type ConsentState,
+    type GoogleSettings,
+    type UmamiReplay,
+    type UmamiSettings,
+    type UmamiTracker,
+} from "./analytics/index.ts";
+export {
+    defineSiteConfig,
+    type LanguageTag,
+    type LocaleMeta,
+    type LocalesOf,
+    type ResolvedLocaleMeta,
+    type RoutingConfig,
+    type SiteConfigShape,
+} from "./config.ts";
+export {
+    assertCoordinates,
+    type CallingCode,
+    type Coordinates,
+    type CountryCode,
+    type EmailAddress,
+    e164,
+    formatPhone,
+    mailtoHref,
+    type PhoneNumber,
+    type PostalAddress,
+    telHref,
+} from "./contact.ts";
+export type { GeneratedFile } from "./file.ts";
+export type { PublicFilePath, PublicFileRegistry } from "./files.ts";
+export {
+    assertHours,
+    type DayHours,
+    type FormattedHours,
+    formatHours,
+    groupHours,
+    type HoursFormat,
+    type HoursGroup,
+    type TimeOfDay,
+    type TimeRange,
+    type Weekday,
+    type WeeklyHours,
+} from "./hours.ts";
+export {
+    type BaseCatalog,
+    type CatalogCovers,
+    defineMessageOverrides,
+    defineMessages,
+    type MessageOverrides,
+    type OverrideCatalog,
+} from "./i18n/define.ts";
+export type {
+    EntryPlaceholders,
+    Placeholders,
+} from "./i18n/placeholders.ts";
+export type {
+    MessageParamsOf,
+    TranslateArgsOf,
+    TranslateFor,
+} from "./i18n/translate.ts";
+export type { ImageAsset } from "./image.ts";
+export {
+    type ArticleInput,
+    article,
+    type BreadcrumbStep,
+    type BusinessId,
+    breadcrumbList,
+    businessId,
+    type CatalogEntry,
+    geoCoordinates,
+    type JsonLdNode,
+    type LocalBusinessInput,
+    localBusiness,
+    type OfferCatalogInput,
+    type OrganizationId,
+    type OrganizationInput,
+    offerCatalog,
+    openingHours,
+    organization,
+    organizationId,
+    type ProductInput,
+    postalAddress,
+    product,
+    quantitativeValue,
+    quantitiesFor,
+    type ServiceArea,
+    type ServiceId,
+    type ServiceInput,
+    serializeJsonLd,
+    service,
+    serviceId,
+    type VideoInput,
+    type VideoSource,
+    videoObject,
+    type WebsiteId,
+    type WebsiteInput,
+    website,
+    websiteId,
+} from "./jsonld/index.ts";
+export {
+    buildLlms,
+    type LlmsConfig,
+    type LlmsItem,
+    type LlmsSection,
+} from "./llms.ts";
+export {
+    type ArticleContent,
+    buildMeta,
+    buildNotFoundMeta,
+    type ImageFormat,
+    type MetaContent,
+    type MetaTag,
+    type OgImage,
+    type OpenGraphType,
+    type PageKind,
+    type RobotsPolicy,
+    type ShareImage,
+    type SiteVerification,
+} from "./meta/index.ts";
+// `quantitiesOf`, `quantityRange` and `isContiguous` are deliberately not here.
+// They are how lib decides between "2–6" and "2, 4, 6", and a consumer holding
+// them writes that decision a second time — which is how `llms.txt` came to
+// advertise a range for a room that skips sizes. `formatQuantities` answers it
+// for prose and `quantitiesFor` for structured data; both read the same tiers.
+export {
+    assertPriceTiers,
+    type CurrencyCode,
+    formatQuantities,
+    type Price,
+    type PriceTier,
+    type TieredPrice,
+    tierRange,
+} from "./money.ts";
+export { defineProject, type ProjectInput } from "./project.ts";
+export {
+    buildCloudflareRedirects,
+    buildRedirects,
+    type CloudflareRedirectsOptions,
+    type ExternalUrl,
+    type RedirectKind,
+    type RedirectRule,
+    type RedirectStatus,
+    type RedirectTarget,
+    type ResolvedRedirect,
+    type SitePath,
+    type ValidateRedirectTargets,
+} from "./redirects.ts";
+export type { RobotsConfig, RobotsGroup } from "./robots.ts";
+export {
+    type ChangeFreq,
+    defineRouteOverrides,
+    defineRoutes,
+    type EnabledRouteIdFor,
+    type RouteData,
+    type RouteOverride,
+    type RouteRegistry,
+    type RouteSitemap,
+} from "./routes/define.ts";
+export {
+    enableRoutes,
+    type FamilyMember,
+    type FamilyMemberInput,
+    type FamilyOptions,
+    familyGuard,
+    type RouteIdsOf,
+    routeFamily,
+} from "./routes/family.ts";
+export type { RouteEntry } from "./routes/resolve.ts";
+export {
+    type Alternate,
+    type Crumb,
+    createSite,
+    type LinkOptions,
+    type LlmsOptions,
+    type LocaleLink,
+    type PageContent,
+    type PageMeta,
+    type PageProps,
+    type PerRoute,
+    type RouteIdOf,
+    type Site,
+    type StaticPath,
+    type WhenEnabled,
+} from "./site/index.ts";
+export type { Sitemap, SitemapConfig } from "./sitemap.ts";
+export type { IsoDate, Letter, StringKeys } from "./types.ts";
+export {
+    absoluteUrl,
+    type HttpsUrl,
+    isHttpsUrl,
+    isUrlPath,
+    joinUrl,
+    normalizeOrigin,
+    type UrlPath,
+} from "./url.ts";

package/src/jsonld/article.ts

@@ -0,0 +1,165 @@
+import type { IsoDate } from "../types.ts";
+import type { HttpsUrl } from "../url.ts";
+import { warn } from "../warn.ts";
+import type { BusinessId, OrganizationId } from "./ids.ts";
+import { type JsonLdNode, oneOrMany } from "./node.ts";
+
+export interface ArticleInput {
+    /**
+     * The title, as the page shows it.
+     *
+     * Google truncates a headline past about 110 characters, which this warns
+     * about rather than refuses: the article is still recognised, it is only
+     * the words after the cut that go.
+     */
+    readonly headline: string;
+    readonly description?: string;
+    /** The article's own page. */
+    readonly url: HttpsUrl;
+    /**
+     * A picture of it, absolute — or the same picture at several ratios.
+     *
+     * A list is what Google asks for: *"we recommend providing multiple
+     * high-resolution images with the following aspect ratios: 16x9, 4x3, and
+     * 1x1"*, since a result renders the photo in whichever shape that surface
+     * uses and supplying one ratio leaves the other two to be cropped by rules
+     * you do not control. `photoSet` in `astro/images.ts` cuts exactly those
+     * three from one source, which is where the list normally comes from.
+     *
+     * A single URL stays valid and is what a page with only its share image
+     * ends up with. Checked August 2026.
+     */
+    readonly image?: HttpsUrl | readonly HttpsUrl[];
+    /**
+     * When it was published.
+     *
+     * The field that makes this node worth emitting: a date is what turns a
+     * result into a dated one, and it is not derivable from anything else on
+     * the page. A date-only `IsoDate` rather than a timestamp, because a venue
+     * publishes on a day and not at an instant.
+     */
+    readonly datePublished: IsoDate;
+    /**
+     * When it last changed, if it has.
+     *
+     * Left out where nothing has been revised. Emitting it equal to
+     * `datePublished` is not more information — it is the same fact twice, and
+     * on a page that says it was updated the day it was written.
+     */
+    readonly dateModified?: IsoDate;
+    /**
+     * Who wrote it, as an `@id` — the venue, or the brand.
+     *
+     * A reference rather than a name: the node it points at already carries the
+     * name, the URL and the address that make an author identifiable, and a
+     * bare string here would be a second copy of the first of those.
+     *
+     * An organization rather than a person is normal for a venue's own news,
+     * and Google accepts either.
+     */
+    readonly author?: OrganizationId | BusinessId;
+    /**
+     * Who published it — the organization, as an `@id`.
+     *
+     * Not in Google's required-or-recommended property table, and not in any of
+     * its primary examples, so it feeds no rich result. It *is* documented, in
+     * the author best-practices: *"The publisher property should be used for
+     * the organization publishing the article, separate from the author."*
+     * Checked August 2026.
+     *
+     * Separate *roles*, which is not the same as separate parties. Google's
+     * example pairs a person with the paper they write for; a venue writing its
+     * own news fills both roles itself, and naming it twice is how you say so.
+     * A site that leaves this out has not said who stands behind the piece — it
+     * has only said who typed it.
+     *
+     * Takes a business id as readily as an organization one, because a
+     * `LocalBusiness` *is* an `Organization` and the venue publishing its own
+     * page is the ordinary case here.
+     */
+    readonly publisher?: OrganizationId | BusinessId;
+    /**
+     * What the article is about, as `keywords`.
+     *
+     * Subjects rather than a section: `articleSection` is the one part of a
+     * publication a piece lives in, which for a site with a single feed is a
+     * constant the URL already states. These vary per post, which is what makes
+     * them worth writing down.
+     *
+     * Emitted as a list rather than the comma-joined string `keywords` also
+     * accepts. Both are read; a list cannot be misparsed by a tag that contains
+     * a comma, and does not ask a caller to know that rule.
+     *
+     * Google's `Article` table lists no `keywords`, so this earns nothing from
+     * that rich result. Unlike `publisher` it is still worth carrying: it
+     * describes content the page really shows, rather than restating a
+     * relationship the graph already holds.
+     */
+    readonly tags?: readonly string[];
+    /**
+     * Which flavour of article. Defaults to `Article`.
+     *
+     * One type that replaces, like `LocalBusinessInput.type` and unlike
+     * `ProductInput.alsoA`: these three are alternatives rather than layers.
+     * `BlogPosting` *is* an `Article`, so `["Article", "BlogPosting"]` states
+     * one thing twice — where `Product` and `Game` are two claims, neither
+     * implying the other.
+     *
+     * All three earn the same rich result, so the choice is editorial: what a
+     * reader would call the thing.
+     */
+    readonly kind?: "Article" | "NewsArticle" | "BlogPosting";
+}
+
+/**
+ * A dated piece of writing — a post, an announcement, a news item.
+ *
+ * What it adds over the page being in the sitemap: a headline distinct from the
+ * `<title>`, a publication date, and an author that resolves to the business
+ * already described in this graph. That is what a dated search result is built
+ * from, and none of it is inferable from the markup around it.
+ *
+ * `mainEntityOfPage` says the article *is* this page rather than something the
+ * page mentions — the distinction that stops a crawler treating a list page and
+ * the post it links as two copies of one article.
+ *
+ * Reference:
+ * <https://developers.google.com/search/docs/appearance/structured-data/article>
+ */
+export function article(item: ArticleInput): JsonLdNode {
+    if (item.headline.length > 110) {
+        warn(
+            item.url,
+            `headline is ${item.headline.length} characters, past the ~110 Google shows: the rest is dropped from the result. The page's own <h1> is unaffected.`
+        );
+    }
+
+    return {
+        "@type": item.kind ?? "Article",
+        headline: item.headline,
+        ...(item.description === undefined
+            ? {}
+            : { description: item.description }),
+        // Not `url`: an article is a thing, and this is the page it is *on*.
+        mainEntityOfPage: item.url,
+        datePublished: item.datePublished,
+        ...(item.dateModified === undefined
+            ? {}
+            : { dateModified: item.dateModified }),
+        // Passed through in the shape it arrived in, bar a list of one — which
+        // is `schemaType`'s rule applied to a second field: writing `[x]` is
+        // fine, emitting it reads as a bug.
+        ...(item.image === undefined ? {} : { image: oneOrMany(item.image) }),
+        ...(item.author === undefined
+            ? {}
+            : { author: { "@id": item.author } }),
+        ...(item.publisher === undefined
+            ? {}
+            : { publisher: { "@id": item.publisher } }),
+        // An empty list is not a set of no keywords, it is a field saying
+        // nothing — so it is left out, as every optional here is.
+        ...(item.tags === undefined || item.tags.length === 0
+            ? {}
+            : { keywords: item.tags }),
+    };
+}

package/src/jsonld/breadcrumb.ts

@@ -0,0 +1,34 @@
+import type { HttpsUrl } from "../url.ts";
+import type { JsonLdNode } from "./node.ts";
+
+/** One step of a trail, ready for `BreadcrumbList`. */
+export interface BreadcrumbStep {
+    readonly name: string;
+    readonly url: HttpsUrl;
+}
+
+/**
+ * The trail, as the one structured-data type that shows up in a search result.
+ *
+ * Every step keeps its `item`, including the last. Google permits omitting it
+ * there, and nothing is gained by doing so — while a *missing* intermediate
+ * `item` invalidates the list, which is why a step with no page is dropped
+ * before it reaches here rather than being emitted without a URL.
+ *
+ * `position` is 1-based, and is what orders the trail: the array order is not
+ * read.
+ *
+ * Reference:
+ * <https://developers.google.com/search/docs/appearance/structured-data/breadcrumb>
+ */
+export function breadcrumbList(steps: readonly BreadcrumbStep[]): JsonLdNode {
+    return {
+        "@type": "BreadcrumbList",
+        itemListElement: steps.map((step, index) => ({
+            "@type": "ListItem",
+            position: index + 1,
+            name: step.name,
+            item: step.url,
+        })),
+    };
+}

package/src/jsonld/business.ts

@@ -0,0 +1,196 @@
+import {
+    type Coordinates,
+    type EmailAddress,
+    e164,
+    type PhoneNumber,
+    type PostalAddress,
+} from "../contact.ts";
+import type { WeeklyHours } from "../hours.ts";
+import type { ImageAsset } from "../image.ts";
+import { absoluteUrl, type HttpsUrl } from "../url.ts";
+import { businessId, type OrganizationId } from "./ids.ts";
+import { alternateName, type JsonLdNode, schemaType } from "./node.ts";
+import { geoCoordinates, openingHours, postalAddress } from "./place.ts";
+
+export interface LocalBusinessInput {
+    readonly name: string;
+    /** The site's own origin. Also the node's identity, see `@id` below. */
+    readonly url: HttpsUrl;
+    readonly address: PostalAddress;
+    /**
+     * Another name this venue actually goes by.
+     *
+     * Not in Google's `LocalBusiness` property table, and covered anyway: the
+     * page says *"since LocalBusiness is a subtype of Organization, we
+     * recommend following the fields for Organization in addition to the fields
+     * required and recommended below"*, and `alternateName` is documented
+     * there. Reading only the table is how you conclude it does nothing.
+     *
+     * Same test as on the brand: a name people use. A venue known locally as
+     * something shorter than its registered name has one; a naming scheme
+     * invented for the markup does not.
+     */
+    readonly alternateName?: string;
+    /**
+     * Where the door is.
+     *
+     * Worth supplying alongside the address rather than instead of it: the
+     * address is what matches a listing, and this is what a map pins. For a
+     * venue up a side street or inside a larger building the two differ by
+     * enough to send someone to the wrong entrance.
+     */
+    readonly geo?: Coordinates;
+    /**
+     * What a visit costs, roughly — `"20-38"`, or `"$$"`.
+     *
+     * Deliberately vague, and read as such: it places the venue against its
+     * neighbours in a local result rather than quoting anything. Google ignores
+     * the field entirely past 100 characters.
+     */
+    readonly priceRange?: string;
+    /**
+     * Photographs of the place.
+     *
+     * Taken as assets and made absolute here, against `url` above — the same
+     * bargain `resolveShareImage` strikes, and for the same reason: this
+     * function is holding the origin, so asking a caller to join the two would
+     * be asking it to repeat what it just handed over.
+     *
+     * Several rather than one, and the same photograph at each of the ratios a
+     * result may render it in — see `photoSet` in `astro/images.ts`, which cuts
+     * them from a single source.
+     *
+     * They must depict *this venue*. A logo is not a photograph of a building,
+     * and a stock interior is a picture of somewhere else: both are the kind of
+     * claim this file exists to avoid making on a project's behalf.
+     */
+    readonly image?: readonly ImageAsset[];
+    readonly telephone?: PhoneNumber;
+    readonly email?: EmailAddress;
+    /**
+     * When the venue is open.
+     *
+     * Worth supplying: this is what puts "Open now" or "Closes at 23:30" beside
+     * a result, and it is the one field a would-be visitor checks before
+     * setting out.
+     */
+    readonly hours?: WeeklyHours;
+    /**
+     * The `@id` of the brand this venue belongs to, from `organization()`.
+     *
+     * A reference, not a copy: the brand is described once, in its own node,
+     * and every venue points at it. Repeating the brand's details inside each
+     * business is how two venues end up disagreeing about their own company.
+     *
+     * Typed as the id rather than as a URL, so handing over the brand's plain
+     * address — the one plausible slip here — does not compile.
+     */
+    readonly parentOrganization?: OrganizationId;
+    /**
+     * What this place *is* — `"EntertainmentBusiness"`, `"Restaurant"`.
+     * Defaults to `LocalBusiness`.
+     *
+     * Named `type` because it becomes `@type`, and because that is what
+     * distinguishes it from `ProductInput.alsoA` at a glance: this one is the
+     * type, that one is a further one. Not `additionalTypes`, which reads as
+     * schema.org's `additionalType` property — a different thing, and one
+     * Google's local-business page explicitly does not support.
+     *
+     * It *replaces* the general type rather than joining it, which is what
+     * Google asks for: *"Use the most specific `LocalBusiness` sub-type
+     * possible; for example, `Restaurant`, `DaySpa`, `HealthClub`, and so
+     * on."* Every subtype is a `LocalBusiness` by schema.org's hierarchy, so a
+     * consumer that resolves types — Google does — loses nothing, and the
+     * generic one on its own is equally true of a dentist.
+     *
+     * Including *physicality*, which is the reason someone reaches for the
+     * parent again. `LocalBusiness` descends from both `Organization` and
+     * `Place`, and a subtype inherits both chains — `Thing > Place >
+     * LocalBusiness > EntertainmentBusiness`. So this is not the colloquial
+     * sense in which a streaming service is an entertainment business: that one
+     * could not use this type at all, because the type *is* a place. Naming the
+     * parent adds nothing the child did not already carry.
+     *
+     * An array is for a business that is genuinely several things at once, and
+     * Google's example is the shape: `["Electrician", "Plumber", "Locksmith"]`
+     * — siblings, none of them subsuming another. Pairing a type with its own
+     * parent is not that, and is the thing this field used to produce.
+     *
+     * Not checked against schema.org's vocabulary: a misspelling here is
+     * emitted and then ignored by every reader. Deliberately so: schema.org is
+     * open and still growing, and a partial enumeration would reject types that
+     * are perfectly valid — which gets cast past, at which point the check is
+     * theatre. Catching a typo belongs against the built output, where the
+     * whole vocabulary is available. See NOT-BUILT.md.
+     *
+     * Reference:
+     * <https://developers.google.com/search/docs/appearance/structured-data/local-business>
+     */
+    readonly type?: string | readonly [string, ...string[]];
+    /**
+     * Pages elsewhere that are unmistakably this same venue.
+     *
+     * Google: *"the URL of a page on another website with additional
+     * information about your organization… a profile page on a social media or
+     * review site."* It is how a search engine decides this site, that Facebook
+     * page and that directory listing are one entity rather than three — which
+     * is what a knowledge panel is assembled from.
+     *
+     * Profiles the business controls or that authoritatively identify it:
+     * social accounts, Wikipedia, Wikidata, a trade listing. Not partner links
+     * or press mentions, which are pages about *something* it did rather than
+     * pages that are it.
+     */
+    readonly sameAs?: readonly HttpsUrl[];
+}
+
+/**
+ * The business the site is for.
+ *
+ * The one node here that earns a visible result: address, telephone and opening
+ * hours are what a knowledge panel and a local pack are built from. Everything
+ * comes from the project — lib has no business details and invents none.
+ *
+ * Given an `@id` so later nodes can point at it rather than repeating it. It is
+ * the site's origin with a fragment, which is stable across every page the
+ * business appears on and unique to this deployment.
+ *
+ * Reference:
+ * <https://developers.google.com/search/docs/appearance/structured-data/local-business>
+ */
+export function localBusiness(business: LocalBusinessInput): JsonLdNode {
+    return {
+        "@type": schemaType(business.type ?? "LocalBusiness"),
+        "@id": businessId(business.url),
+        name: business.name,
+        ...alternateName(business.name, business.alternateName),
+        url: business.url,
+        address: postalAddress(business.address),
+        ...(business.geo === undefined
+            ? {}
+            : { geo: geoCoordinates(business.geo) }),
+        ...(business.priceRange === undefined
+            ? {}
+            : { priceRange: business.priceRange }),
+        ...(business.image === undefined || business.image.length === 0
+            ? {}
+            : {
+                  image: business.image.map((photo) =>
+                      absoluteUrl(business.url, photo.src, "venue photo")
+                  ),
+              }),
+        ...(business.telephone === undefined
+            ? {}
+            : { telephone: e164(business.telephone) }),
+        ...(business.email === undefined ? {} : { email: business.email }),
+        ...(business.hours === undefined
+            ? {}
+            : { openingHoursSpecification: openingHours(business.hours) }),
+        ...(business.sameAs === undefined ? {} : { sameAs: business.sameAs }),
+        ...(business.parentOrganization === undefined
+            ? {}
+            : {
+                  parentOrganization: { "@id": business.parentOrganization },
+              }),
+    };
+}