@escape-game-over/atlas 0.1.20 → 0.1.22

package/docs/client-scripts.md

@@ -41,7 +41,7 @@ finding them.
 | `./astro/youtube`          | the swap from poster to player, on the click and not before    | the poster, the button, the iframe's classes    |
 | `./astro/background-video` | playing or paused, playable or not, and which cut is loaded    | the play/pause control, its icons and its label |
 | `./astro/consent`          | remembering an answer, expiring it, handing it to Google       | the banner — its wording, its buttons, its law  |
-| `./astro/element`          | the two lifetimes a custom element has, and one abort signal   | what the element is and does                    |
+| `./astro/element`          | registering a custom element, and ending what it started        | what the element does while it is on the page   |
 | `./astro/dom`              | scoped `one`/`all` lookups, typed                              | the selectors                                   |
 | `./astro/dev-log`          | a panel a failed wiring can announce itself in, in dev only    | calling it behind `import.meta.env.DEV`         |
 
@@ -55,11 +55,10 @@ never reaches the HTML. Gate the render on that and keep the runtime check for
 the banner that is rendered. See NOT-BUILT.md on where the halves divide.
 
 **A script imports one path: `@escape-game-over/atlas/client`**, which re-exports
-every module above. It is browser-only — `element.ts` evaluates
-`class AtlasElement extends HTMLElement` as it loads, which throws in Node — so
-frontmatter and `astro.config.ts` cannot use it. A component's contract is the
-one thing both halves need, and it stays on `./astro/markup`, which touches
-nothing.
+every module above. All of it exists to touch a live document, so it belongs in
+a `<script src>` and not in frontmatter or `astro.config.ts`. A component's
+contract is the one thing both halves need, and it stays on `./astro/markup`,
+which touches nothing.
 
 ## Lifetimes are the recurring bug
 
@@ -76,15 +75,23 @@ const detach = loop.attach(video);            // background-video: the <video>
 const detach = trailer.attach(button, box);   // youtube: what is pressed, what it replaces
 ```
 
-`AtlasElement` says the same thing in the shape a custom element needs, because
-an element is constructed once and may be connected many times — moving it in
-the DOM runs `disconnectedCallback` and then `connectedCallback` again:
+`defineElement` says the same thing in the shape a custom element needs. One
+function per element: it runs when the element enters the page, `signal` ends
+what it registered when the element leaves, and what it returns is the undo for
+everything else.
 
 ```ts
-protected setup(): void { … }     // once, ever: what the element is
-protected connect(): void { … }   // every connection: bind with this.signal
+defineElement("atlas-thing", (host, signal) => {
+    host.addEventListener("click", open, { signal });   // ends with the visit
+    return loop.attach(host);                           // and so does this
+});
 ```
 
+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
+carousel example does with its index.
+
 **The trap this exists for is view transitions.** A bundled `<script src>` is an
 ES module, cached by URL, so it executes once per session — not once per
 navigation. Bind at module scope with `ClientRouter` on and the incoming page
@@ -472,12 +479,9 @@ export const faq = component("go-faq", {
 ```
 
 ```ts
-class Faq extends AtlasElement {
-    protected connect(): void {
-        for (const { element, values } of faq.row.all(this)) { … }
-    }
-}
-faq.define(Faq);
+defineElement(faq.tag, (host, signal) => {
+    for (const { element, values } of faq.row.all(host)) { … }
+});
 ```
 
 - **Names come from the tag.** Every attribute is `data-<tag>-<role>` plus the
@@ -490,8 +494,10 @@ faq.define(Faq);
   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
-  `faq.define` registers the class under it.
+- **The tag is written once.** `faq.tag` is what the template renders and 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
   that is not camelCase, is a compile error where it is written — the rules are
   types, character by character, as in `i18n/placeholders.ts`. Nothing is
@@ -501,9 +507,9 @@ faq.define(Faq);
 - **Most roles carry nothing**, and say so: `search: marker` rather than
   `search: {}`, which reads like options somebody forgot to fill in.
 
-`tag` and `define` 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`.
+`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`.
 
 ## `youtube`
 

package/package.json

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

package/src/astro/client.ts

@@ -2,13 +2,13 @@
  * Everything a client script needs, from one import.
  *
  * ```ts
- * import { AtlasElement, filters, searchBox } from "@escape-game-over/atlas/client";
+ * import { filters, searchBox } from "@escape-game-over/atlas/client";
  * ```
  *
- * **Browser only.** `element.ts` evaluates `class AtlasElement extends
- * HTMLElement` as this module loads, which throws in Node — so frontmatter and
- * `astro.config.ts` must not import it. A component's contract is the one thing
- * both halves need, and it stays on `astro/markup`, which touches nothing.
+ * **For the browser.** Everything here exists to touch a live document, and is
+ * meant for a `<script src>`, not for frontmatter or `astro.config.ts`. A
+ * component's contract is the one thing both halves need, and it stays on
+ * `astro/markup`, which touches nothing.
  */
 
 export * from "./background-video.ts";

package/src/astro/element.ts

@@ -1,155 +1,112 @@
 import { reportDevError } from "./dev-log.ts";
 
 /**
- * A base for custom elements: two lifetimes, and one abort signal.
+ * What is left to undo when the element leaves, or nothing.
+ *
+ * Nothing is the common case — a connect that registered everything with
+ * `signal` has already said how it comes down — so `void` rather than
+ * `undefined`, which would make every connect end in a `return`.
+ */
+// biome-ignore lint/suspicious/noConfusingVoidType: that is the distinction.
+type Undo = void | (() => void);
+
+/**
+ * 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.
+ */
+export type Connect = (host: HTMLElement, signal: AbortSignal) => Undo;
+
+/**
+ * Registers a custom element whose behaviour is one function.
  *
  * ```ts
- * class Thing extends AtlasElement {
- *     protected setup(): void { … }        // once, ever: what the element is
- *     protected connect(): void {          // every connection: bind with signal
- *         this.querySelector("form")?.addEventListener("submit", send, {
- *             signal: this.signal,
- *         });
- *     }
- * }
- * customElements.define("atlas-thing", Thing);
+ * defineElement("atlas-thing", (host, signal) => {
+ *     host.querySelector("form")?.addEventListener("submit", send, { signal });
+ *     return loop.attach(host); // runs when the element leaves the page
+ * });
  * ```
  *
- * - **An element is constructed once and connected many times.** Moving it in
- *   the DOM runs `disconnectedCallback` then `connectedCallback` again, so
- *   state belongs in `setup` and listeners in `connect`. Anything registered
- *   with `signal` is dropped on disconnect and rebound on the next connect.
- * - **Override `setup`, `connect` and `disconnect`, never the callbacks.**
- *   Overriding `connectedCallback` skips the controller and leaks every
- *   listener; that mistake throws in development, below.
+ * - **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.
  * - **The defining script must stay a deferred module.** Astro emits
- *   `<script src>` as `type="module"`, so the element has its children when it
- *   is upgraded. `is:inline` runs it too early and every lookup finds nothing.
- * - **`attributeChangedCallback` runs before `connectedCallback`**, where
- *   `signal` is not readable yet. Record what changed and act on it in
- *   `connect`.
- * - **`disconnect` is not a destructor.** A move fires it and connects again a
- *   moment later, so it is connection teardown and nothing else.
+ *   `<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.
  *
  * See docs/client-scripts.md.
  */
-export abstract class AtlasElement extends HTMLElement {
-    /**
-     * This connection's listeners, and only this connection's. Remade on every
-     * connect: an `AbortController` is single-use, and a reused one comes back
-     * already aborted, leaving the element inert but normal-looking.
-     */
-    #ac?: AbortController;
-
-    #ready = false;
-
-    constructor() {
-        super();
-        // The bare expression Vite substitutes, so this collapses to
-        // `if (false)` and the method below leaves the bundle.
-        if (import.meta.env.DEV) this.#assertHooks();
-    }
-
-    /**
-     * Refuses a subclass that overrode the wrong lifecycle method. An override
-     * is an *own* property of the subclass prototype; the loop covers an
-     * intermediate base class that got it wrong.
-     */
-    #assertHooks(): void {
-        // A tuple array, not an object: `Object.entries` would widen the keys
-        // back to `string` and stop checking the pairing.
-        const wrong = [
-            ["connectedCallback", "connect"],
-            ["disconnectedCallback", "disconnect"],
-        ] as const;
-
-        for (
-            let proto = Object.getPrototypeOf(this);
-            proto && proto !== AtlasElement.prototype;
-            proto = Object.getPrototypeOf(proto)
-        ) {
-            for (const [callback, hook] of wrong) {
-                if (Object.hasOwn(proto, callback)) {
-                    const error = new Error(
-                        `override "${hook}", not "${callback}" — see AtlasElement`
-                    );
-                    // Reported before throwing: this runs during upgrade, where
-                    // a throw would only surface as an uncaught console error.
-                    reportDevError(this.constructor.name, error);
-                    throw error;
+export function defineElement(tag: string, connect: Connect): void {
+    // 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.
+    customElements.define(
+        tag,
+        class extends HTMLElement {
+            /**
+             * This visit's listeners, and only this visit's. Remade every time:
+             * an `AbortController` is single-use, and a reused one comes back
+             * already aborted, leaving the element inert but normal-looking.
+             */
+            #ac?: AbortController;
+
+            /** What `connect` handed back, if anything. */
+            #undo?: () => void;
+
+            connectedCallback(): void {
+                // Insurance: a live controller still here would orphan its
+                // listeners.
+                this.#end();
+
+                const ac = new AbortController();
+                this.#ac = ac;
+                try {
+                    this.#undo = connect(this, ac.signal) ?? undefined;
+                } catch (error) {
+                    this.#report(error);
                 }
             }
-        }
-    }
-
-    /**
-     * Pass to `addEventListener`, observers, anything that should stop when the
-     * element leaves the document. Throws outside a connection.
-     */
-    protected get signal(): AbortSignal {
-        if (!this.#ac) {
-            throw new Error(
-                `${this.localName}: signal read outside a connection`
-            );
-        }
-        return this.#ac.signal;
-    }
-
-    connectedCallback(): void {
-        // Insurance: overwriting a live controller would orphan its listeners.
-        this.#ac?.abort();
-        this.#ac = new AbortController();
 
-        // Caught so one broken element logs and sits inert rather than taking
-        // its siblings with it — which is what lets `require` throw.
-        try {
-            if (!this.#ready) {
-                this.setup();
-                // Only once it returned, so a `setup` that threw is retried
-                // rather than leaving `connect` to run against nothing.
-                this.#ready = true;
+            disconnectedCallback(): void {
+                this.#end();
             }
-            this.connect();
-        } catch (error) {
-            this.#report(error);
-        }
-    }
-
-    disconnectedCallback(): void {
-        // Idempotent, so `adoptedCallback` can delegate here.
-        if (!this.#ac) return;
-        this.#ac.abort();
 
-        try {
-            // Before `#ac` is cleared, so `this.signal` is readable and already
-            // aborted: an async continuation can check it and bail.
-            this.disconnect();
-        } catch (error) {
-            this.#report(error);
-        }
-
-        this.#ac = undefined;
-    }
+            /** Moving to another document ends the old document's visit. */
+            adoptedCallback(): void {
+                this.#end();
+            }
 
-    /** Moving to another document ends the old document's connection. */
-    adoptedCallback(): void {
-        this.disconnectedCallback();
-    }
+            #end(): void {
+                // Aborted before the undo runs, so an async continuation that
+                // checks the signal can see the visit is over.
+                this.#ac?.abort();
+                this.#ac = undefined;
+
+                const undo = this.#undo;
+                this.#undo = undefined;
+                try {
+                    undo?.();
+                } catch (error) {
+                    this.#report(error);
+                }
+            }
 
-    #report(error: unknown): void {
-        if (import.meta.env.DEV) {
-            reportDevError(this.localName, error);
-            return;
+            #report(error: unknown): void {
+                // The bare expression Vite substitutes, so this collapses to
+                // `if (false)` and the dev panel leaves the bundle.
+                if (import.meta.env.DEV) {
+                    reportDevError(this.localName, error);
+                    return;
+                }
+                console.error(`${this.localName}:`, error);
+            }
         }
-        console.error(`${this.localName}:`, error);
-    }
-
-    /** Runs once per element, before its first `connect`. State belongs here. */
-    protected setup(): void {}
-
-    /** Runs on every connect, with `signal` and the children both available. */
-    protected abstract connect(): void;
-
-    /** Runs on every disconnect, once the signal has been aborted. */
-    protected disconnect(): void {}
+    );
 }

package/src/astro/markup.ts

@@ -514,14 +514,13 @@ export function markup<
 /** A component's roles, by name: each is the fields of one `markup` role. */
 export type ComponentRoles = Readonly<Record<string, MarkupFields>>;
 
-/** Keys the component object uses itself, so no role may take them. */
-type Reserved = "tag" | "define";
+/** The key the component object uses itself, so no role may take it. */
+type Reserved = "tag";
 
 export type Component<Tag extends string, R extends ComponentRoles> = {
-    /** The custom element's name: what the template renders. */
+    /** The custom element's name: what the template renders, and what
+     * `defineElement` registers the behaviour under. */
     readonly tag: Tag;
-    /** Registers the element's class under `tag`. */
-    define(element: CustomElementConstructor): void;
 } & { readonly [K in keyof R]: Markup<R[K]> };
 
 /**
@@ -535,7 +534,7 @@ export type Component<Tag extends string, R extends ComponentRoles> = {
  * });
  *
  * // template: <faq.tag> … <details {...faq.row.attrs({ key, text })}>
- * // script:   faq.row.all(this); faq.define(Faq);
+ * // script:   defineElement(faq.tag, (host) => faq.row.all(host).forEach(…));
  * ```
  *
  * Two things `markup` alone leaves to the project:
@@ -579,9 +578,9 @@ export function component<
         name: string,
         fields: MarkupFields
     ): Markup<MarkupFields> => {
-        // A compile error already, and cheap to keep: these two would overwrite
-        // the component's own keys and leave nothing to define the element with.
-        if (name === "tag" || name === "define") {
+        // A compile error already, and cheap to keep: this one would overwrite
+        // the component's own key and leave nothing to render the element as.
+        if (name === "tag") {
             throw new Error(
                 `component(${show(tag)}): ${show(name)} is taken by the component itself`
             );
@@ -631,11 +630,7 @@ export function component<
         };
     };
 
-    const built: Record<string, unknown> = {
-        tag,
-        define: (element: CustomElementConstructor) =>
-            customElements.define(tag, element),
-    };
+    const built: Record<string, unknown> = { tag };
     for (const [name, fields] of Object.entries(roles)) {
         built[name] = scoped(name, fields);
     }

package/src/llms.ts

@@ -151,10 +151,18 @@ export function buildLlms(input: LlmsInput): GeneratedFile {
         lines.push("");
     }
 
+    // Opens with a byte-order mark, because `contentType` does not survive the
+    // build. Only the dev middleware sends it; once written to `dist` the file
+    // is served with whatever the host picks, and `astro preview` picks
+    // `text/plain` with no charset. A browser then reads the bytes as
+    // Windows-1252, and every `—`, `²` and line of Greek turns to `—`. This
+    // is the one generated file written in prose, so it is the one that breaks.
+    // The mark is the encoding stated by the bytes themselves, which a browser
+    // honours over a missing charset and a UTF-8 decoder strips.
     return {
         name: input.name,
         url: joinUrl(input.siteUrl, `/${input.name}`),
-        body: `${lines.join("\n").trimEnd()}\n`,
+        body: `\uFEFF${lines.join("\n").trimEnd()}\n`,
         contentType: "text/markdown; charset=utf-8",
     };
 }