@escape-game-over/atlas 0.1.22 → 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/client-scripts.md

@@ -81,12 +81,15 @@ what it registered when the element leaves, and what it returns is the undo for
 everything else.
 
 ```ts
-defineElement("atlas-thing", (host, signal) => {
+defineElement(thing, (host, signal) => {
     host.addEventListener("click", open, { signal });   // ends with the visit
     return loop.attach(host);                           // and so does this
 });
 ```
 
+It takes the component rather than a tag name, so the element it registers and
+the roles it hands the function are the same contract the template spread.
+
 An element can enter the page more than once — moving it in the DOM runs the
 undo and then the function again — so it has to be able to run twice. State that
 must survive a move goes in a `WeakMap` keyed by `host`, which is what the
@@ -472,15 +475,15 @@ export const faq = component("go-faq", {
 ```
 
 ```astro
-<faq.tag>
+<faq.tag {...faq.root}>
     <input {...faq.search.attrs()} type="search">
     <details {...faq.row.attrs({ key, text })}>…</details>
 </faq.tag>
 ```
 
 ```ts
-defineElement(faq.tag, (host, signal) => {
-    for (const { element, values } of faq.row.all(host)) { … }
+defineElement(faq, (host, signal, { row }) => {
+    for (const { element, values } of row.all()) { … }
 });
 ```
 
@@ -494,8 +497,8 @@ defineElement(faq.tag, (host, signal) => {
   keeps its elements, and a lookup from an element inside the instance, like a
   dropdown's own panel, still counts as that instance. Elements are filtered
   before they are read, so a broken nested copy cannot fail the outer lookup.
-- **The tag is written once.** `faq.tag` is what the template renders and what
-  `defineElement` registers the behaviour under. A contract stays inert either
+- **The tag is written once.** `faq.tag` is what the template renders, and the
+  component itself is what `defineElement` registers the behaviour under. A contract stays inert either
   way: it names things, and nothing in it touches a document, which is why
   frontmatter can import it.
 - **The names are checked in the editor.** A tag without a hyphen, or a role
@@ -507,9 +510,17 @@ defineElement(faq.tag, (host, signal) => {
 - **Most roles carry nothing**, and say so: `search: marker` rather than
   `search: {}`, which reads like options somebody forgot to fill in.
 
-`tag` is the component's own key, so no role may take it. A role that lives
-outside every instance, such as a footer button that reopens a banner, is still
-plain `markup`.
+- **The roles arrive bound to the instance.** `defineElement` takes the
+  component, so `all`, `one` and `require` need no root: there is no way to
+  write `faq.row.all(document)`, which compiles and returns the roles belonging
+  to no instance at all.
+- **The root says it is one.** `{...faq.root}` writes `data-atlas-root`, so a
+  project gives every root a display in one stylesheet rule rather than a class
+  per component. Forget it and the element says so on the dev server.
+
+`tag` and `root` are the component's own keys, so no role may take them. A role
+that lives outside every instance, such as a footer button that reopens a
+banner, is still plain `markup`.
 
 ## `youtube`
 

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.22",
+    "version": "0.1.24",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,
@@ -59,9 +59,9 @@
     "devDependencies": {
         "@biomejs/biome": "2.5.13",
         "@types/node": "26.5.1",
-        "@vitest/coverage-istanbul": "5.0.0",
+        "@vitest/coverage-istanbul": "5.0.1",
         "astro": "7.3.2",
         "typescript": "6.0.3",
-        "vitest": "5.0.0"
+        "vitest": "5.0.1"
     }
 }

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/element.ts

@@ -1,4 +1,6 @@
 import { reportDevError } from "./dev-log.ts";
+import type { Marked, Markup } from "./markup.ts";
+import { ROOT_ATTRIBUTE } from "./markup.ts";
 
 /**
  * What is left to undo when the element leaves, or nothing.
@@ -10,43 +12,87 @@ import { reportDevError } from "./dev-log.ts";
 // biome-ignore lint/suspicious/noConfusingVoidType: that is the distinction.
 type Undo = void | (() => void);
 
+/** One role's lookups, already pointed at the element they belong to. */
+type Bound<M> =
+    M extends Markup<infer F>
+        ? {
+              all<T extends Element = HTMLElement>(): Marked<T, F>[];
+              one<T extends Element = HTMLElement>(): Marked<T, F> | null;
+              require<T extends Element = HTMLElement>(): Marked<T, F>;
+          }
+        : never;
+
+/**
+ * Every role of a component, bound to one instance.
+ *
+ * The root is not a parameter here, which is the point: `faq.row.all(document)`
+ * compiles and quietly returns the roles that belong to *no* instance, and this
+ * removes the chance to write it.
+ */
+export type Roles<C> = {
+    readonly [K in Exclude<keyof C, "tag" | "root">]: Bound<C[K]>;
+};
+
 /**
  * What an element does while it is on the page.
  *
- * `host` is the element itself and `signal` is aborted when it leaves, so
- * anything registered with `signal` comes down on its own. Whatever else has to
- * be undone is the returned function, which runs at the same moment.
+ * `host` is the element itself, `signal` is aborted when it leaves — so
+ * anything registered with `signal` comes down on its own — and `roles` are
+ * this instance's. Whatever else has to be undone is the returned function,
+ * which runs at the same moment.
  */
-export type Connect = (host: HTMLElement, signal: AbortSignal) => Undo;
+export type Connect<C> = (
+    host: HTMLElement,
+    signal: AbortSignal,
+    roles: Roles<C>
+) => Undo;
+
+/** The shape this file needs off a role, without importing its field types. */
+interface AnyRole {
+    all(root: ParentNode): unknown;
+    one(root: ParentNode): unknown;
+    require(root: ParentNode): unknown;
+}
 
 /**
- * Registers a custom element whose behaviour is one function.
+ * Registers a component's custom element, with its behaviour as one function.
  *
  * ```ts
- * defineElement("atlas-thing", (host, signal) => {
- *     host.querySelector("form")?.addEventListener("submit", send, { signal });
+ * export const faq = component("go-faq", { row: { key: { kind: "text" } } });
+ *
+ * defineElement(faq, (host, signal, { row }) => {
+ *     for (const { element, values } of row.all()) { … }
  *     return loop.attach(host); // runs when the element leaves the page
  * });
  * ```
  *
  * - **An element can enter the page more than once.** Moving it runs the undo
- *   and then `connect` again, so `connect` has to be able to run twice. State
- *   that must survive a move belongs in a `WeakMap` keyed by `host`, as the
- *   carousel example keeps its index.
+ *   and then `connect` again, so `connect` has to be able to run twice. Astro's
+ *   `ClientRouter` connects a persisted element three times per navigation.
+ *   State that must survive belongs in a `WeakMap` keyed by `host`.
  * - **The defining script must stay a deferred module.** Astro emits
  *   `<script src>` as `type="module"`, so the element has its children by the
  *   time it is upgraded. `is:inline` runs it too early and every lookup inside
  *   the element finds nothing.
  * - **A `connect` that throws leaves that one element inert** and reports it,
- *   rather than taking its siblings down with it — which is what lets a lookup
- *   like `require` throw and say what is missing.
+ *   rather than taking its siblings down with it.
  *
  * See docs/client-scripts.md.
  */
-export function defineElement(tag: string, connect: Connect): void {
+export function defineElement<C extends { readonly tag: string }>(
+    component: C,
+    connect: Connect<C>
+): void {
+    const { tag } = component;
+
+    // Read once: the roles are fixed when the component is built, and only the
+    // element they point at changes.
+    const roleNames = Object.keys(component).filter(
+        (key) => key !== "tag" && key !== "root"
+    );
+
     // The class is built in here rather than at module scope so `HTMLElement`
-    // is only read in a browser: `astro/markup` reaches this file, templates
-    // import it, and the build runs in Node.
+    // is only read in a browser.
     customElements.define(
         tag,
         class extends HTMLElement {
@@ -68,7 +114,16 @@ export function defineElement(tag: string, connect: Connect): void {
                 const ac = new AbortController();
                 this.#ac = ac;
                 try {
-                    this.#undo = connect(this, ac.signal) ?? undefined;
+                    if (
+                        import.meta.env.DEV &&
+                        !this.hasAttribute(ROOT_ATTRIBUTE)
+                    ) {
+                        throw new Error(
+                            `<${tag}> carries no ${ROOT_ATTRIBUTE} — does the template spread {...x.root} on it?`
+                        );
+                    }
+                    this.#undo =
+                        connect(this, ac.signal, this.#roles()) ?? undefined;
                 } catch (error) {
                     this.#report(error);
                 }
@@ -83,6 +138,22 @@ export function defineElement(tag: string, connect: Connect): void {
                 this.#end();
             }
 
+            /** This instance's roles: the component's, with the root supplied. */
+            #roles(): Roles<C> {
+                const bound: Record<string, unknown> = {};
+                for (const name of roleNames) {
+                    const role = (component as Record<string, unknown>)[
+                        name
+                    ] as AnyRole;
+                    bound[name] = {
+                        all: () => role.all(this),
+                        one: () => role.one(this),
+                        require: () => role.require(this),
+                    };
+                }
+                return bound as Roles<C>;
+            }
+
             #end(): void {
                 // Aborted before the undo runs, so an async continuation that
                 // checks the signal can see the visit is over.

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/markup.ts

@@ -514,13 +514,28 @@ export function markup<
 /** A component's roles, by name: each is the fields of one `markup` role. */
 export type ComponentRoles = Readonly<Record<string, MarkupFields>>;
 
-/** The key the component object uses itself, so no role may take it. */
-type Reserved = "tag";
+/** The keys the component object uses itself, so no role may take them. */
+type Reserved = "tag" | "root";
+
+/**
+ * What marks a component's root element.
+ *
+ * One name, so a project gives every root a display in a single stylesheet rule
+ * rather than a class per component, and so `defineElement` can say when a
+ * template forgot to spread it.
+ */
+export const ROOT_ATTRIBUTE = "data-atlas-root";
 
 export type Component<Tag extends string, R extends ComponentRoles> = {
     /** The custom element's name: what the template renders, and what
      * `defineElement` registers the behaviour under. */
     readonly tag: Tag;
+
+    /**
+     * What the root element carries, spread by the template that renders it:
+     * `<faq.tag {...faq.root}>`.
+     */
+    readonly root: Readonly<Record<string, string>>;
 } & { readonly [K in keyof R]: Markup<R[K]> };
 
 /**
@@ -533,8 +548,8 @@ export type Component<Tag extends string, R extends ComponentRoles> = {
  *     search: {},
  * });
  *
- * // template: <faq.tag> … <details {...faq.row.attrs({ key, text })}>
- * // script:   defineElement(faq.tag, (host) => faq.row.all(host).forEach(…));
+ * // template: <faq.tag {...faq.root}> … <details {...faq.row.attrs({ key, text })}>
+ * // script:   defineElement(faq, (host, signal, { row }) => row.all().forEach(…));
  * ```
  *
  * Two things `markup` alone leaves to the project:
@@ -630,7 +645,10 @@ export function component<
         };
     };
 
-    const built: Record<string, unknown> = { tag };
+    const built: Record<string, unknown> = {
+        tag,
+        root: { [ROOT_ATTRIBUTE]: "" },
+    };
     for (const [name, fields] of Object.entries(roles)) {
         built[name] = scoped(name, fields);
     }

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",
 };
 
 /**