npm - @escape-game-over/atlas - Versions diffs - 0.1.2 → 0.1.4 - Mend

@escape-game-over/atlas 0.1.2 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/README.md +17 -1
package/docs/NOT-BUILT.md +33 -18
package/docs/checks.md +20 -5
package/docs/client-scripts.md +307 -0
package/package.json +11 -4
package/src/astro/build-cache.ts +80 -0
package/src/astro/filters-view.ts +253 -0
package/src/astro/filters.ts +505 -0
package/src/astro/images.ts +73 -0
package/src/astro/site-routes.ts +15 -0
package/src/contact-form.ts +1 -1
package/src/index.ts +2 -0
package/src/jsonld/faq.ts +105 -0
package/src/jsonld/index.ts +1 -0
package/src/jsonld/video.ts +2 -2
package/src/meta/index.ts +79 -32
package/src/site/create.ts +12 -1

package/src/jsonld/faq.ts ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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;

package/src/meta/index.ts CHANGED Viewed

@@ -78,7 +78,7 @@ export type MetaInput<L extends string> = Omit<MetaContentBase, "image"> &
     PageKind &
     MetaInputDerived<L>;
-interface MetaInputDerived<L extends string> {
+interface MetaInputDerived<L extends string> extends ChromeInput {
     /** The locale of *this* page, not the site default. */
     readonly locale: L;
     readonly canonical: HttpsUrl;
@@ -119,8 +119,6 @@ interface MetaInputDerived<L extends string> {
      * Graph equivalent to fall back to. Site-level, like `siteName`.
      */
     readonly twitterSite?: string;
-    /** The site's square icon, used for every icon link. */
-    readonly icon: SiteIcon;
     /**
      * Webmaster-tool ownership tokens. Site-level, like `siteName`.
      *
@@ -144,6 +142,20 @@ interface MetaInputDerived<L extends string> {
      * generated — a link to a missing one is worse than no link.
      */
     readonly llmsUrl?: HttpsUrl;
+}
+/**
+ * The site's own furniture, as opposed to anything about a page.
+ *
+ * Its own interface because it is what the 404 shares with every real page and
+ * nearly all it shares: that document has no canonical, no description, no
+ * alternates and no share image, but it is still served under the site's name
+ * in the site's tab, and a reader who lands on it should not be able to tell
+ * from the chrome that they left.
+ */
+export interface ChromeInput {
+    /** The site's square icon, used for every icon link. */
+    readonly icon: SiteIcon;
     /**
      * Tints the browser UI — Android Chrome's bar, iOS Safari, an installed PWA.
      * Two values emit one tag per `prefers-color-scheme`.
@@ -172,6 +184,45 @@ export interface DocumentTags {
     readonly body: MetaTag[];
 }
+/**
+ * What the browser dresses its own furniture with: the tab's icon, the tint of
+ * the address bar, and which schemes the page renders form controls for.
+ *
+ * Pulled out of `buildMeta` because the 404 needs exactly this and nothing else
+ * around it. Sharing the code is the point rather than a convenience: these are
+ * the tags a reader sees *as* the site — a 404 with a different tab icon looks
+ * like it came from somewhere else, which is the opposite of what a 404 is for —
+ * and two copies of a four-branch block is how one of them quietly stops
+ * matching the other.
+ */
+function chromeTags(input: ChromeInput): MetaTag[] {
+    const tags: MetaTag[] = [...iconLinks(input.icon)];
+    if (input.colorScheme !== undefined) {
+        tags.push(meta({ name: "color-scheme", content: input.colorScheme }));
+    }
+    if (typeof input.themeColor === "string") {
+        tags.push(meta({ name: "theme-color", content: input.themeColor }));
+    } else if (input.themeColor !== undefined) {
+        tags.push(
+            meta({
+                name: "theme-color",
+                media: "(prefers-color-scheme: light)",
+                content: input.themeColor.light,
+            })
+        );
+        tags.push(
+            meta({
+                name: "theme-color",
+                media: "(prefers-color-scheme: dark)",
+                content: input.themeColor.dark,
+            })
+        );
+    }
+    return tags;
+}
 /** Builds the head tags every page needs. */
 export function buildMeta<L extends string>(input: MetaInput<L>): DocumentTags {
     const tags: MetaTag[] = [
@@ -209,29 +260,7 @@ export function buildMeta<L extends string>(input: MetaInput<L>): DocumentTags {
         tags.push(link({ rel: "describedby", href: input.llmsUrl }));
     }
-    for (const iconLink of iconLinks(input.icon)) tags.push(iconLink);
-    if (input.colorScheme !== undefined) {
-        tags.push(meta({ name: "color-scheme", content: input.colorScheme }));
-    }
-    if (typeof input.themeColor === "string") {
-        tags.push(meta({ name: "theme-color", content: input.themeColor }));
-    } else if (input.themeColor !== undefined) {
-        tags.push(
-            meta({
-                name: "theme-color",
-                media: "(prefers-color-scheme: light)",
-                content: input.themeColor.light,
-            })
-        );
-        tags.push(
-            meta({
-                name: "theme-color",
-                media: "(prefers-color-scheme: dark)",
-                content: input.themeColor.dark,
-            })
-        );
-    }
+    for (const tag of chromeTags(input)) tags.push(tag);
     for (const alternate of input.alternates) {
         tags.push(
@@ -400,6 +429,20 @@ export function buildMeta<L extends string>(input: MetaInput<L>): DocumentTags {
     return { head: tags, body: bodyTags };
 }
+/**
+ * What a 404 needs, which is the site's furniture and a title and nothing else.
+ *
+ * An object rather than the positional arguments this took before: the two it
+ * gained are both site-level and both optional-looking at a call site, and
+ * `buildNotFoundMeta(title, icon, themeColor, analytics)` is four positions
+ * where three of them are interchangeable to a reader.
+ */
+export interface NotFoundInput extends ChromeInput {
+    readonly title: string;
+    /** Site-level, and only Umami reaches this page — see `notFoundAnalytics`. */
+    readonly analytics?: AnalyticsSettings;
+}
 /**
  * Builds the head of a 404 page.
  *
@@ -412,13 +455,16 @@ export function buildMeta<L extends string>(input: MetaInput<L>): DocumentTags {
  * host serves this file at the address that was requested, so what gets
  * recorded is the missing path itself, which is the difference between knowing
  * there are 404s and knowing which redirect to write.
+ *
+ * It also carries the site's chrome, through the same `chromeTags` every real
+ * page goes through. A 404 is the one page a visitor reaches by accident, and
+ * the tab it opens in is how they judge whether they are still on the site they
+ * meant to be on — an unstyled tab showing the browser's default globe reads as
+ * a different origin, or as nothing at all.
  */
-export function buildNotFoundMeta(
-    title: string,
-    analytics?: AnalyticsSettings
-): MetaTag[] {
+export function buildNotFoundMeta(input: NotFoundInput): MetaTag[] {
     return [
-        ...preamble({ title }),
+        ...preamble({ title: input.title }),
         // Through the same builder as every other page, so the one document lib
         // writes for itself cannot spell the tag differently from the ones it
         // writes for a project. Links are still followed: a 404 often carries
@@ -427,6 +473,7 @@ export function buildNotFoundMeta(
             name: "robots",
             content: robotsContent({ index: false, follow: true }),
         }),
-        ...notFoundAnalytics(analytics).map(asMetaTag),
+        ...notFoundAnalytics(input.analytics).map(asMetaTag),
+        ...chromeTags(input),
     ];
 }

package/src/site/create.ts CHANGED Viewed

@@ -322,7 +322,18 @@ export function createSite<
             // Umami only, tagged so the misses read on their own — the point
             // of measuring this page is finding a redirect somebody forgot,
             // not counting the people who mistype. See `notFoundAnalytics`.
-            tags: buildNotFoundMeta(title, project.analytics),
+            //
+            // `checkedIcon()` rather than `project.icon`: the 404 is held to the
+            // same square-and-PNG rules as every other page. It is also the one
+            // page that could plausibly render before any other, so letting it
+            // read the icon unchecked would move where a bad one is caught.
+            tags: buildNotFoundMeta({
+                title,
+                analytics: project.analytics,
+                icon: checkedIcon(),
+                themeColor: project.themeColor,
+                colorScheme: project.colorScheme,
+            }),
             // Nothing. The body channel exists for Tag Manager's `<noscript>`,
             // and no Google tag reaches this page.
             bodyTags: [],