@escape-game-over/atlas 0.1.23 → 0.1.24

package/README.md

@@ -166,7 +166,8 @@ route id or a URL. A slot is filled at the call site, where it is checked agains
 the routes this deployment builds and written once instead of once per language.
 
 `site.plain(locale)` reads the same message as words alone, for a
-`<meta description>` or `llms.txt`; `t()` refuses a message with marks rather
+`<meta description>` or `llms.txt`, and `html(rich(…))` as inline markup for a
+structured-data answer; `t()` refuses a message with marks rather
 than printing the brackets. See [`docs/rich-text.md`](docs/rich-text.md).
 
 ## What the build emits, and who asks for it

package/docs/rich-text.md

@@ -222,6 +222,18 @@ button label, an `aria-label`. Reach for `plain()` when the answer is prose: it
 keeps working on the day someone adds emphasis to the sentence, where `t()` would
 start throwing.
 
+## The same sentence as inline HTML
+
+`html(rich(…))` is for a structured-data field that accepts a little markup — a
+`FAQPage` answer's `text`. It emits `<a>`, `<strong>` and `<br>`, links by the
+absolute `url` because nothing reading it has a page to resolve a path against,
+and escapes all the copy. A `[v:]` role and an in-page anchor come out as their
+words.
+
+```ts
+faqPage([{ question, answer: html(rich("faq.city.a", { network: "network" })) }], at)
+```
+
 ## The renderer half
 
 lib decides which runs exist and what they say; the project decides what they

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.23",
+    "version": "0.1.24",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/analytics/tags.ts

@@ -77,8 +77,7 @@ export interface AnalyticsTags {
  * `JSON.stringify` handles quotes and backslashes. The `<` escape handles the
  * one thing it cannot: a `</script` anywhere in the text ends the element,
  * whatever JavaScript makes of it. `<` is a valid escape inside a JS
- * string and invisible to anything reading the value — the same bargain
- * `serializeJsonLd` strikes, for the same reason.
+ * string and invisible to anything reading the value, JSON parsers included.
  */
 export const literal = (value: unknown): string =>
     JSON.stringify(value).replaceAll("<", "\\u003c");

package/src/astro/filters.ts

@@ -346,8 +346,10 @@ export function filters<const F extends FieldMap>(
         const query = search.toString();
         // The bare path when nothing is left, rather than a trailing `?`.
         const url = query === "" ? window.location.pathname : `?${query}`;
-        if (history === "push") window.history.pushState({}, "", url);
-        else window.history.replaceState({}, "", url);
+        // `null` on a pushed step, so Astro's `ClientRouter` leaves its popstate
+        // to this module; a replaced entry keeps whatever state it already had.
+        if (history === "push") window.history.pushState(null, "", url);
+        else window.history.replaceState(window.history.state, "", url);
     }
 
     /** One field's value as the matcher and the URL will read it. */

package/src/astro/images.ts

@@ -158,16 +158,6 @@ export async function shareImage(
     // Not warned about here. `metaFor` already warns about an undersized
     // `og:image`, on every page and whether or not this helper made it, so
     // saying it twice would only halve the chance either line is read.
-    //
-    // Measured as a scale factor, not by comparing dimensions, because the two
-    // fits reach the box differently. `cover` scales until *both* sides are
-    // covered, so a source short in either dimension would be enlarged.
-    // `contain` scales until the *first* side fits, so an 800x800 logo lands at
-    // 630x630 — a reduction, though it is narrower than 1200.
-    const scale =
-        fit === "cover"
-            ? Math.max(width / source.width, height / source.height)
-            : Math.min(width / source.width, height / source.height);
     const image = await getImage({
         src: source,
         width,
@@ -187,20 +177,32 @@ export async function shareImage(
         })(),
     });
 
-    // The size that came *back*, not the size asked for.
-    //
-    // Neither `attributes` nor `options` can be trusted here: both echo the
-    // request, and the request is exactly what was not honoured. What is known
-    // is the rule — Astro refuses to enlarge — so a source too small for the box
-    // comes back untouched, at its own size. Reporting the request instead would
-    // put an `og:image:width` in every head that the file does not match, which
-    // is worse than a small image: a scraper lays out a space and finds
-    // something else in it.
-    const produced =
-        scale > 1
-            ? { width: source.width, height: source.height }
-            : { width, height };
-    return { src: image.src, ...produced, format };
+    return {
+        src: image.src,
+        ...producedSize(source, width, height, fit),
+        format,
+    };
+}
+
+/**
+ * The size `getImage` actually returns, not the size asked for.
+ *
+ * Neither `attributes` nor `options` can be trusted: both echo the request.
+ * Astro refuses to enlarge, so a source too small for the box comes back
+ * untouched, at its own size. Measured as a scale factor because the fits reach
+ * the box differently: `cover` scales until *both* sides are covered, `contain`
+ * until the *first* side fits.
+ */
+function producedSize(
+    source: ImageMetadata,
+    width: number,
+    height: number,
+    fit: "cover" | "contain"
+): { width: number; height: number } {
+    const pick = fit === "cover" ? Math.max : Math.min;
+    return pick(width / source.width, height / source.height) > 1
+        ? { width: source.width, height: source.height }
+        : { width, height };
 }
 
 /**
@@ -307,8 +309,7 @@ export async function photoSet(
             });
             return {
                 src: image.src,
-                width: ratio.width,
-                height: ratio.height,
+                ...producedSize(source, ratio.width, ratio.height, "cover"),
                 format,
             };
         })

package/src/astro/site-routes.ts

@@ -280,6 +280,7 @@ export function siteRoutes(options: SiteRoutesOptions): AstroIntegration {
                 // optional, so `buld: {…}` would be assignable and silently do
                 // nothing. The annotation is what makes a typo an error.
                 const config: ConfigUpdate = {
+                    site: site.url,
                     output: "static",
                     build: { format: "file" },
                     trailingSlash: "ignore",

package/src/content/index.ts

@@ -29,6 +29,7 @@ export { assertNoMarks, type ParsedSpan, parseMarks } from "./marks.ts";
 export {
     createPlainText,
     createRichText,
+    html,
     type LinkResolver,
     type LinkTarget,
     type PlainTextFor,

package/src/content/rich.ts

@@ -22,6 +22,7 @@ import {
     joinUrl,
     type UrlPath,
 } from "../url.ts";
+import { escapeXml } from "../xml.ts";
 import { type LinkNames, type ParsedSpan, parseMarks } from "./marks.ts";
 
 /**
@@ -493,6 +494,50 @@ export function plain(rich: RichText): string {
     );
 }
 
+/**
+ * The runs as inline HTML, for a field that takes markup rather than a page.
+ *
+ * Written for a `FAQPage` answer, whose `text` accepts a handful of tags —
+ * `<a>`, `<strong>`, `<br>` among them. Only those are emitted: a `[v:]` role
+ * is presentation, which structured data has no use for, so it is its words.
+ *
+ * Links carry their absolute `url`, since nothing reading this has a page to
+ * resolve a path against. An anchor has none, so it is its words too.
+ *
+ * Every piece of copy is escaped: the field is read as HTML, so an `&` or a `<`
+ * in a translation would otherwise be read as markup.
+ */
+export function html(rich: RichText): string {
+    return rich
+        .map((span) => {
+            switch (span.kind) {
+                case "text":
+                case "styled":
+                    return escapeXml(span.text);
+                case "bold":
+                    return `<strong>${escapeXml(span.text)}</strong>`;
+                case "link":
+                    return span.to === "anchor"
+                        ? escapeXml(span.text)
+                        : anchor(span.url, span.text);
+                case "email":
+                case "phone":
+                    return anchor(span.href, span.text);
+                case "break":
+                    return "<br>";
+                default: {
+                    const unreachable: never = span;
+                    return unreachable;
+                }
+            }
+        })
+        .join("");
+}
+
+function anchor(href: string, text: string): string {
+    return `<a href="${escapeXml(href)}">${escapeXml(text)}</a>`;
+}
+
 /**
  * Runs of whitespace become one, and the ends are trimmed.
  *

package/src/index.ts

@@ -72,6 +72,7 @@ export {
 // a slot filled with a route id resolves against nothing there. `site.rich(locale)` is
 // the only way in, and `Span` is what a renderer switches on.
 export {
+    html,
     type LinkTarget,
     type PlainTextFor,
     plain,

package/src/jsonld/faq.ts

@@ -11,7 +11,8 @@ export interface FaqEntry {
      * `<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.
+     * builds markup for you. An answer with links in it wants `html(rich(…))`,
+     * which emits only tags from that list and escapes the copy.
      *
      * Checked August 2026.
      */

package/src/jsonld/node.ts

@@ -5,6 +5,8 @@
  * kind of node and imports these to do it.
  */
 
+import { literal } from "../analytics/tags.ts";
+
 /** A node in the graph. Deliberately loose: `@type` is what a consumer varies. */
 export interface JsonLdNode {
     readonly "@type": string | readonly string[];
@@ -60,19 +62,7 @@ export function alternateName(
         : { 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.
- */
+/** The graph, serialised for a `<script type="application/ld+json">`. */
 export function serializeJsonLd(nodes: readonly JsonLdNode[]): string {
-    return JSON.stringify({
-        "@context": "https://schema.org",
-        "@graph": nodes,
-    }).replaceAll("<", "\\u003c");
+    return literal({ "@context": "https://schema.org", "@graph": nodes });
 }

package/src/meta/share-image.ts

@@ -3,12 +3,23 @@ import { absoluteUrl, type HttpsUrl } from "../url.ts";
 import { warn } from "../warn.ts";
 import { link, type MetaTag } from "./tag.ts";
 
-export type ImageFormat = "png" | "jpg" | "webp";
+export type ImageFormat =
+    | "png"
+    | "jpg"
+    | "jpeg"
+    | "webp"
+    | "avif"
+    | "gif"
+    | "svg";
 
 const IMAGE_MIME: Readonly<Record<ImageFormat, string>> = {
     png: "image/png",
     jpg: "image/jpeg",
+    jpeg: "image/jpeg",
     webp: "image/webp",
+    avif: "image/avif",
+    gif: "image/gif",
+    svg: "image/svg+xml",
 };
 
 /**