@escape-game-over/atlas 0.1.3 → 0.1.5

package/src/countries.ts

@@ -0,0 +1,314 @@
+/**
+ * Every country a form can offer, as ISO 3166-1 alpha-2.
+ *
+ * Codes rather than names, which is the point on a multilingual site:
+ * `countriesFor` turns each one into the reader's own word for it and sorts
+ * them the way that language sorts. A list of English names would put "Czech
+ * Republic" in front of a Romanian reader and file it under C.
+ *
+ * The code is also what a form should submit, so an enquiry from Germany files
+ * the same whether it was picked as "Deutschland" or "Germany".
+ *
+ * Derived from ICU's region list rather than typed out: every two-letter code
+ * it answers to, less the withdrawn and transitional reservations it still
+ * knows (`SU`, `YU`, `DD`, `ZR`, `AN`, `UK`…) and the aggregates that are not
+ * countries (`EU`, `UN`, `QO`…). 250 entries: the 249 ISO assigns, plus `XK`
+ * for Kosovo, which is user-assigned and in common use.
+ *
+ * **This is a list, not a policy.** It says which codes are well-formed, not
+ * which countries a business will trade with — that is a per-project answer and
+ * belongs in the project, by filtering this.
+ */
+export const COUNTRY_CODES = [
+    "AD",
+    "AE",
+    "AF",
+    "AG",
+    "AI",
+    "AL",
+    "AM",
+    "AO",
+    "AQ",
+    "AR",
+    "AS",
+    "AT",
+    "AU",
+    "AW",
+    "AX",
+    "AZ",
+    "BA",
+    "BB",
+    "BD",
+    "BE",
+    "BF",
+    "BG",
+    "BH",
+    "BI",
+    "BJ",
+    "BL",
+    "BM",
+    "BN",
+    "BO",
+    "BQ",
+    "BR",
+    "BS",
+    "BT",
+    "BV",
+    "BW",
+    "BY",
+    "BZ",
+    "CA",
+    "CC",
+    "CD",
+    "CF",
+    "CG",
+    "CH",
+    "CI",
+    "CK",
+    "CL",
+    "CM",
+    "CN",
+    "CO",
+    "CR",
+    "CU",
+    "CV",
+    "CW",
+    "CX",
+    "CY",
+    "CZ",
+    "DE",
+    "DJ",
+    "DK",
+    "DM",
+    "DO",
+    "DZ",
+    "EC",
+    "EE",
+    "EG",
+    "EH",
+    "ER",
+    "ES",
+    "ET",
+    "FI",
+    "FJ",
+    "FK",
+    "FM",
+    "FO",
+    "FR",
+    "GA",
+    "GB",
+    "GD",
+    "GE",
+    "GF",
+    "GG",
+    "GH",
+    "GI",
+    "GL",
+    "GM",
+    "GN",
+    "GP",
+    "GQ",
+    "GR",
+    "GS",
+    "GT",
+    "GU",
+    "GW",
+    "GY",
+    "HK",
+    "HM",
+    "HN",
+    "HR",
+    "HT",
+    "HU",
+    "ID",
+    "IE",
+    "IL",
+    "IM",
+    "IN",
+    "IO",
+    "IQ",
+    "IR",
+    "IS",
+    "IT",
+    "JE",
+    "JM",
+    "JO",
+    "JP",
+    "KE",
+    "KG",
+    "KH",
+    "KI",
+    "KM",
+    "KN",
+    "KP",
+    "KR",
+    "KW",
+    "KY",
+    "KZ",
+    "LA",
+    "LB",
+    "LC",
+    "LI",
+    "LK",
+    "LR",
+    "LS",
+    "LT",
+    "LU",
+    "LV",
+    "LY",
+    "MA",
+    "MC",
+    "MD",
+    "ME",
+    "MF",
+    "MG",
+    "MH",
+    "MK",
+    "ML",
+    "MM",
+    "MN",
+    "MO",
+    "MP",
+    "MQ",
+    "MR",
+    "MS",
+    "MT",
+    "MU",
+    "MV",
+    "MW",
+    "MX",
+    "MY",
+    "MZ",
+    "NA",
+    "NC",
+    "NE",
+    "NF",
+    "NG",
+    "NI",
+    "NL",
+    "NO",
+    "NP",
+    "NR",
+    "NU",
+    "NZ",
+    "OM",
+    "PA",
+    "PE",
+    "PF",
+    "PG",
+    "PH",
+    "PK",
+    "PL",
+    "PM",
+    "PN",
+    "PR",
+    "PS",
+    "PT",
+    "PW",
+    "PY",
+    "QA",
+    "RE",
+    "RO",
+    "RS",
+    "RU",
+    "RW",
+    "SA",
+    "SB",
+    "SC",
+    "SD",
+    "SE",
+    "SG",
+    "SH",
+    "SI",
+    "SJ",
+    "SK",
+    "SL",
+    "SM",
+    "SN",
+    "SO",
+    "SR",
+    "SS",
+    "ST",
+    "SV",
+    "SX",
+    "SY",
+    "SZ",
+    "TC",
+    "TD",
+    "TF",
+    "TG",
+    "TH",
+    "TJ",
+    "TK",
+    "TL",
+    "TM",
+    "TN",
+    "TO",
+    "TR",
+    "TT",
+    "TV",
+    "TW",
+    "TZ",
+    "UA",
+    "UG",
+    "UM",
+    "US",
+    "UY",
+    "UZ",
+    "VA",
+    "VC",
+    "VE",
+    "VG",
+    "VI",
+    "VN",
+    "VU",
+    "WF",
+    "WS",
+    "XK",
+    "YE",
+    "YT",
+    "ZA",
+    "ZM",
+    "ZW",
+] as const;
+
+/**
+ * An ISO 3166-1 alpha-2 country code: `"IT"`, `"GR"`, `"RO"`.
+ *
+ * Read off the list above rather than described as a shape. `${Letter}${Letter}`
+ * admits all 676 two-letter strings, of which some 400 are not countries, so it
+ * accepted `"XX"` and every typo that happened to be two capitals. This accepts
+ * the 250 that exist and nothing else — including refusing the withdrawn codes
+ * (`SU`, `YU`, `AN`), which look plausible and are the ones worth catching.
+ *
+ * A name — `"Italy"`, `"Ιταλία"` — is a translation of a country rather than an
+ * identifier for one, and belongs in the sentence a page prints. `countriesFor`
+ * is what turns one of these into that.
+ */
+export type CountryCode = (typeof COUNTRY_CODES)[number];
+
+/** One country, in one language. */
+export interface NamedCountry {
+    readonly code: CountryCode;
+    readonly name: string;
+}
+
+/**
+ * The list as one locale reads it: each code with its own name, A to Z in that
+ * language.
+ *
+ * Both halves are locale-dependent, so neither can be cached across locales —
+ * "Ägypten" sorts second in German and "Egypt" fifth in English, and a build
+ * that sorted once would ship one language's order to all of them.
+ *
+ * `Intl.DisplayNames` falls back to the code itself for anything it does not
+ * know, which is what keeps this total: an option always has a label.
+ */
+export function countriesFor(locale: string): readonly NamedCountry[] {
+    const names = new Intl.DisplayNames([locale], { type: "region" });
+    const collator = new Intl.Collator(locale);
+    return COUNTRY_CODES.map((code) => ({
+        code,
+        name: names.of(code) ?? code,
+    })).sort((a, b) => collator.compare(a.name, b.name));
+}

package/src/index.ts

@@ -60,6 +60,11 @@ export {
     type MailEndpoint,
     sendContactMessage,
 } from "./contact-form.ts";
+export {
+    COUNTRY_CODES,
+    countriesFor,
+    type NamedCountry,
+} from "./countries.ts";
 export type { GeneratedFile } from "./file.ts";
 export type { PublicFilePath, PublicFileRegistry } from "./files.ts";
 export {
@@ -101,6 +106,8 @@ export {
     breadcrumbList,
     businessId,
     type CatalogEntry,
+    type FaqEntry,
+    faqPage,
     geoCoordinates,
     type JsonLdNode,
     type LocalBusinessInput,

package/src/jsonld/faq.ts

@@ -0,0 +1,105 @@
+import { warn } from "../warn.ts";
+import type { JsonLdNode } from "./node.ts";
+
+/** One question and the answer the page gives for it. */
+export interface FaqEntry {
+    readonly question: string;
+    /**
+     * The answer, as plain text.
+     *
+     * Google accepts a small amount of HTML here — `<p>`, `<br>`, `<ol>`,
+     * `<ul>`, `<li>`, `<a>`, `<b>`, `<strong>`, `<i>`, `<em>` — and drops
+     * everything else. Plain text is what a caller passing a translated string
+     * has anyway, and it cannot be silently half-rendered, so nothing here
+     * builds markup for you. Pass the markup yourself if the answer needs it.
+     *
+     * Checked August 2026.
+     */
+    readonly answer: string;
+}
+
+/**
+ * The questions a page answers, as a `FAQPage`.
+ *
+ * **Read this before calling it: it renders nowhere, and it is not free.** This
+ * node was in `docs/NOT-BUILT.md` until it was asked for, and the reasoning
+ * there is the reason it stays opt-in rather than something `metaFor()` emits.
+ *
+ * Google restricted FAQ rich results to *"well-known, authoritative government
+ * and health websites"* in 2023, then removed them from Search entirely on
+ * 7 May 2026 and archived the documentation. There is no expandable Q&A under a
+ * commercial result any more, and no flag to earn one back.
+ *
+ * **A model does not read it either** — the argument for emitting it anyway,
+ * and it does not hold. JSON-LD sits in a `<script>` block, and the
+ * HTML-to-text pipelines feeding a model routinely drop `<script>` and often
+ * the whole `<head>`. Independent testing through 2025–26 repeatedly found that
+ * content present *only* in structured data goes unextracted, while the same
+ * content in visible headings and paragraphs is read reliably. A FAQ page's
+ * questions are already visible text; that is what gets read.
+ *
+ * **What it can still buy.** Schema is parsed at *indexing* time, so it reaches
+ * the surfaces built on a search index rather than only those fetching the page.
+ * Bing has said outright that its LLMs read schema, which is the live
+ * third-party payoff and the reason this exists at all.
+ *
+ * **The cost, which is the part that decides it.** Every other node here is
+ * metadata *about* a page — an address, a price, a date. This one is a verbatim
+ * *copy of* it: every question and every full answer a second time, in a script
+ * block on the page already showing them. A ten-question FAQ is several KB
+ * duplicated on every load, and page weight is paid per visitor, forever. Call
+ * this where that trade has been made deliberately, not by default.
+ *
+ * **Only questions the page actually shows.** The node is a description of the
+ * page, not a second copy of a FAQ that lives elsewhere: Google's first quality
+ * rule is that the content "must be visible to the user on the source page",
+ * and a node listing answers a reader cannot find is the kind of mismatch that
+ * earns a manual action rather than a warning. A page rendering a subset — the
+ * questions it has answers for, say — passes that subset.
+ *
+ * No `@id`: nothing in a graph refers to a `FAQPage`, and an id is for being
+ * pointed at. See the note at the top of `ids.ts`.
+ *
+ * Throws on an empty list rather than emitting an empty node. `mainEntity` is
+ * required, so a `FAQPage` holding no questions is not a thin node — it is an
+ * invalid one, saying the page is a FAQ and then naming nothing it answers.
+ * Whether a page has questions to show is the caller's to know, and a page with
+ * none should leave the node out of its graph rather than pass an empty list
+ * and hope.
+ *
+ * Reference, now archived rather than current guidance:
+ * <https://developers.google.com/search/docs/appearance/structured-data/faqpage>
+ *
+ * @param at What to name when this is wrong — the page's canonical URL.
+ */
+export function faqPage(entries: readonly FaqEntry[], at: string): JsonLdNode {
+    if (entries.length === 0) {
+        throw new Error(
+            `${at}: a FAQPage needs at least one question. Leave the node out of the graph on a page that shows none, rather than emitting one that answers nothing.`
+        );
+    }
+
+    const seen = new Set<string>();
+    for (const entry of entries) {
+        const key = entry.question.trim().toLowerCase();
+        if (seen.has(key)) {
+            warn(
+                at,
+                `two questions read "${entry.question}". Google merges a repeated question rather than listing it twice, so the second answer is dropped.`
+            );
+        }
+        seen.add(key);
+    }
+
+    return {
+        "@type": "FAQPage",
+        mainEntity: entries.map((entry) => ({
+            "@type": "Question",
+            name: entry.question,
+            acceptedAnswer: {
+                "@type": "Answer",
+                text: entry.answer,
+            },
+        })),
+    };
+}

package/src/jsonld/index.ts

@@ -32,6 +32,7 @@
 export { type ArticleInput, article } from "./article.ts";
 export { type BreadcrumbStep, breadcrumbList } from "./breadcrumb.ts";
 export { type LocalBusinessInput, localBusiness } from "./business.ts";
+export { type FaqEntry, faqPage } from "./faq.ts";
 export {
     type BusinessId,
     businessId,

package/src/jsonld/video.ts

@@ -11,8 +11,8 @@ interface VideoDetails {
      * 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,
+     * what it is given, so handing it `…/rooms/blue-room` would produce
+     * `…/rooms/blue-room/thumb.png`. The same bargain `localBusiness` strikes,
      * named for what it actually needs.
      */
     readonly origin: HttpsUrl;