@mapled/vanilla 0.0.1 → 0.1.1

package/dist/runtime.js

@@ -0,0 +1,725 @@
+/** The runtime of Mapled attributes (§19.2): finds what a page declared
+    with `data-mapled-*`, reads the release that is live, fills the page,
+    and says what it couldn't fill. The page's own HTML is the fallback —
+    nothing is touched before its replacement is in hand, and every run
+    starts again from what the author wrote.
+
+    What a page may declare:
+
+      data-mapled-bind="home.headline"        the element's content — text;
+                                              on <img>, the picture
+      data-mapled-format="markdown"           …as rich text; or "date",
+                                              "datetime", "number"
+      data-mapled-bind-href="home.cta-link"   an attribute: href, src, alt,
+                                              title, aria-label,
+                                              placeholder, datetime
+      data-mapled-link="/post.html?slug={slug}"  an address from a template
+      data-mapled-show / data-mapled-hide     shown while there is a value
+      data-mapled-list="posts"                a <template> inside, once per
+                                              record: data-mapled-sort,
+                                              -limit, -filter, -expand
+      data-mapled-each="features"             the same for the items of a
+                                              repeatable group
+      data-mapled-record="posts"              one record for what is inside:
+                                              data-mapled-slug, or
+                                              data-mapled-slug-param="slug"
+      <form data-mapled-form="contact">       posted to Mapled's form
+
+    Paths start at a single from the document (`home.headline`) and at the
+    record inside a list, an each or a record (`title`, `author.name`). */
+import { createClient, endPreview, MapledError, previewSession, submitForm } from "@mapled/client";
+import { isEmpty, parsePath, valueAt } from "./paths.js";
+import { ATTRIBUTES, FORMATS, formatted, setVisible, writable, writeAttribute, writeImage, writeLink, writeMarkdown, writeText } from "./sinks.js";
+import { fillTemplate } from "./url.js";
+/** Why a place wasn't filled. `missing` — no such single, record or
+    collection in the release; `empty` — the record is there, a value at
+    this path isn't; `failed` — the read didn't come back; `bad-path` —
+    the page's attribute isn't a path, a key or an option Mapled reads;
+    the rest are the sinks' refusals. */
+export const ISSUE_REASONS = ["missing", "empty", "failed", "bad-path", "unsafe-url", "type", "refused-element", "unsupported"];
+const P = "data-mapled-";
+/** Every attribute the runtime reads or writes, besides `bind-…`. */
+export const NAMES = new Set([
+    "bind", "format", "width", "show", "hide", "link", "list", "each", "record", "slug", "slug-param", "sort", "limit", "filter", "expand", "empty",
+    "form", "form-state", "form-sent", "form-failed", "consent", "end-preview", "state", "preview", "key", "api", "live",
+]);
+const KEY = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const DELIVERY_KEY = /^mk_[A-Za-z0-9_]{8,128}$/;
+const MAX_EACH_DEPTH = 4;
+/** The most a template repeats: the API's page, and the most items a
+    repeatable group holds — an answer that brings more is cut here. */
+const MAX_ITEMS = 100;
+/** How deep `expand` reaches: `author`, `related.author`. */
+const MAX_EXPAND_DEPTH = 2;
+/** A record as Mapled serves one — what every path walks: `data` an
+    object; `expanded`, when there, one linked record, a list of them or
+    null under each key, no deeper than `expand` can ask. An answer is
+    data, and so is its shape: what isn't a record is read as no answer. */
+function isRecord(value, depth = 0) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const { data, expanded } = value;
+    if (data === null || typeof data !== "object" || Array.isArray(data))
+        return false;
+    if (expanded === undefined)
+        return true;
+    if (expanded === null || typeof expanded !== "object" || Array.isArray(expanded))
+        return false;
+    const linked = Object.values(expanded);
+    if (depth >= MAX_EXPAND_DEPTH)
+        return linked.length === 0;
+    return linked.every((one) => one === null || (Array.isArray(one) ? one.every((r) => isRecord(r, depth + 1)) : isRecord(one, depth + 1)));
+}
+const isRecordList = (value) => Array.isArray(value) && value.every((r) => isRecord(r));
+/** The element as the page names it: `a#cta`. The id is the author's. */
+function nameOf(el) {
+    const id = el.getAttribute("id");
+    return `${el.localName}${id && /^[\w-]{1,40}$/.test(id) ? `#${id}` : ""}`;
+}
+const listOf = (text) => (text ?? "")
+    .split(",")
+    .map((t) => t.trim())
+    .filter((t) => /^[a-z0-9][a-z0-9_.-]{0,127}$/.test(t));
+const templateOf = (el) => Array.from(el.children).find((c) => c.localName === "template") ?? null;
+function declaredOn(el, issues) {
+    let d = null;
+    const get = () => (d ??= { format: "text", attrs: [], expand: [] });
+    for (const attr of Array.from(el.attributes)) {
+        if (!attr.name.startsWith(P))
+            continue;
+        const name = attr.name.slice(P.length);
+        if (name === "bind")
+            get().bind = attr.value;
+        else if (name.startsWith("bind-")) {
+            const target = name.slice(5);
+            if (Object.prototype.hasOwnProperty.call(ATTRIBUTES, target))
+                get().attrs.push([target, attr.value]);
+            else
+                issues.push({ path: attr.value.slice(0, 80), reason: "unsupported", on: `${nameOf(el)}[${attr.name.slice(0, 60)}]` });
+        }
+        else if (name === "show")
+            get().show = attr.value;
+        else if (name === "hide")
+            get().hide = attr.value;
+        else if (name === "link")
+            get().link = attr.value;
+        // a name Mapled doesn't read is most likely a typo of one it does
+        else if (!NAMES.has(name))
+            issues.push({ path: attr.value.slice(0, 80), reason: "unsupported", on: `${nameOf(el)}[${attr.name.slice(0, 60)}]` });
+    }
+    if (!d)
+        return null;
+    const declared = d;
+    const format = el.getAttribute(`${P}format`);
+    if (format !== null) {
+        if (FORMATS.includes(format))
+            declared.format = format;
+        else
+            issues.push({ path: format.slice(0, 80), reason: "bad-path", on: `${nameOf(el)}[${P}format]` });
+    }
+    const width = parseInt(el.getAttribute(`${P}width`) ?? "", 10);
+    if (width >= 16 && width <= 4096)
+        declared.width = width;
+    declared.expand = listOf(el.getAttribute(`${P}expand`));
+    return declared;
+}
+function listOptions(el, issues) {
+    const options = {};
+    const sort = el.getAttribute(`${P}sort`);
+    if (sort !== null) {
+        if (/^-?[a-z0-9][a-z0-9_-]{0,63}$/.test(sort.trim()))
+            options.sort = sort.trim();
+        else
+            issues.push({ path: sort.slice(0, 80), reason: "bad-path", on: `${nameOf(el)}[${P}sort]` });
+    }
+    const limit = parseInt(el.getAttribute(`${P}limit`) ?? "", 10);
+    if (limit >= 1 && limit <= 100)
+        options.limit = limit;
+    const filter = el.getAttribute(`${P}filter`);
+    if (filter !== null) {
+        for (const pair of filter.split(";")) {
+            if (pair.trim() === "")
+                continue;
+            const at = pair.indexOf("=");
+            const key = at === -1 ? "" : pair.slice(0, at).trim();
+            const value = at === -1 ? "" : pair.slice(at + 1).trim();
+            if (KEY.test(key) && value !== "" && value.length <= 200)
+                (options.filter ??= {})[key] = value;
+            else
+                issues.push({ path: pair.trim().slice(0, 80), reason: "bad-path", on: `${nameOf(el)}[${P}filter]` });
+        }
+    }
+    const expand = listOf(el.getAttribute(`${P}expand`));
+    if (expand.length > 0)
+        options.expand = expand;
+    return options;
+}
+/** Everything declared under `container`. Inside a template's clone a
+    list or a record of its own is not read (`page` is false): what
+    repeats there is the record's own data. */
+function compile(container, page) {
+    const block = { bound: [], eaches: [], lists: [], records: [], issues: [] };
+    const visit = (el) => {
+        if (el.hasAttributes()) {
+            const list = el.getAttribute(`${P}list`);
+            const record = el.getAttribute(`${P}record`);
+            const each = el.getAttribute(`${P}each`);
+            if (list !== null || record !== null) {
+                const collection = (list ?? record ?? "").trim();
+                if (!page)
+                    block.issues.push({ path: collection.slice(0, 80), reason: "unsupported", on: nameOf(el) });
+                else if (!KEY.test(collection))
+                    block.issues.push({ path: collection.slice(0, 80), reason: "bad-path", on: nameOf(el) });
+                else if (list !== null)
+                    block.lists.push({ el, collection, options: listOptions(el, block.issues) });
+                else {
+                    const param = el.getAttribute(`${P}slug-param`);
+                    const slug = el.getAttribute(`${P}slug`) ?? (param === null ? null : new URLSearchParams(el.ownerDocument.location?.search ?? "").get(param));
+                    const inner = compile(el, true);
+                    // a record inside a record has no address of its own to read a slug from
+                    for (const nested of inner.records)
+                        block.issues.push({ path: nested.collection, reason: "unsupported", on: nameOf(nested.el) });
+                    block.lists.push(...inner.lists);
+                    block.issues.push(...inner.issues);
+                    const own = declaredOn(el, block.issues);
+                    if (own)
+                        inner.bound.unshift({ el, d: own });
+                    block.records.push({
+                        el,
+                        collection,
+                        slug: slug !== null && slug.trim() !== "" && slug.length <= 200 ? slug.trim() : null,
+                        expand: listOf(el.getAttribute(`${P}expand`)),
+                        block: { ...inner, lists: [], records: [], issues: [] },
+                    });
+                }
+                return;
+            }
+            if (each !== null) {
+                block.eaches.push({ el, path: each });
+                return;
+            }
+            const d = declaredOn(el, block.issues);
+            if (d)
+                block.bound.push({ el, d });
+        }
+        for (const child of Array.from(el.children))
+            visit(child);
+    };
+    for (const child of Array.from(container.children))
+        visit(child);
+    return block;
+}
+/** The first segments of every path a block reads: the singles of a
+    page, the fields of a template. */
+function heads(block) {
+    const out = new Map();
+    const add = (path, expand = []) => {
+        const head = parsePath(path)?.[0];
+        if (!head)
+            return;
+        const set = out.get(head) ?? new Set();
+        for (const e of expand)
+            set.add(e);
+        out.set(head, set);
+    };
+    for (const { d } of block.bound) {
+        add(d.bind, d.expand);
+        for (const [, path] of d.attrs)
+            add(path, d.expand);
+        add(d.show, d.expand);
+        add(d.hide, d.expand);
+        for (const m of (d.link ?? "").matchAll(/\{([^{}]*)\}/g))
+            add(m[1], d.expand);
+    }
+    for (const each of block.eaches) {
+        add(each.path, listOf(each.el.getAttribute(`${P}expand`)));
+    }
+    return out;
+}
+function look(scope, path) {
+    const segments = parsePath(path);
+    if (!segments)
+        return { status: "bad-path" };
+    if (scope.kind === "record")
+        return { status: "value", value: valueAt(scope.source, segments) };
+    // from the document a path names a single, then a field of it
+    if (segments.length < 2)
+        return { status: "bad-path" };
+    const single = scope.singles.get(segments[0]);
+    if (!single || single.status !== "ok")
+        return { status: single?.status === "failed" ? "failed" : "missing" };
+    return { status: "value", value: valueAt(single.value, segments.slice(1)) };
+}
+/* ---- mount ---- */
+export function mount(options) {
+    if (typeof options?.key !== "string" || !DELIVERY_KEY.test(options.key)) {
+        // the value is never echoed: it may be a secret that was pasted by mistake
+        throw new Error("Mapled: data-mapled-key takes the delivery key (mk_…) — the one key that is safe in a page. A server key or a secret never goes into HTML.");
+    }
+    if (typeof document === "undefined")
+        throw new Error("Mapled: @mapled/vanilla fills a page — it runs in a browser. On a server read with @mapled/client.");
+    const root = options.root ?? document.documentElement;
+    const doc = root.ownerDocument;
+    const client = createClient({ key: options.key, apiUrl: options.apiUrl, appUrl: options.appUrl, fetch: options.fetch });
+    const sinks = { apiUrl: options.apiUrl, base: doc.baseURI };
+    /** what the author wrote, for everything a run changed: the next run starts from it */
+    const originals = new Map();
+    const original = (el) => {
+        let o = originals.get(el);
+        if (!o)
+            originals.set(el, (o = { attrs: new Map() }));
+        return o;
+    };
+    const keepContent = (el) => {
+        const o = original(el);
+        o.nodes ??= Array.from(el.childNodes);
+    };
+    const keepAttr = (el, name) => {
+        const o = original(el);
+        if (!o.attrs.has(name))
+            o.attrs.set(name, el.getAttribute(name));
+    };
+    const restore = () => {
+        for (const [el, o] of originals) {
+            if (o.nodes)
+                el.replaceChildren(...o.nodes);
+            for (const [name, value] of o.attrs) {
+                if (value === null)
+                    el.removeAttribute(name);
+                else
+                    el.setAttribute(name, value);
+            }
+        }
+        originals.clear();
+    };
+    let issues = [];
+    let bound = 0;
+    const note = (el, path, reason) => issues.push({ path: (path ?? "").trim().slice(0, 120), reason, on: nameOf(el) });
+    function fillElement(el, d, scope) {
+        if (d.bind !== undefined) {
+            const found = look(scope, d.bind);
+            if (found.status !== "value")
+                note(el, d.bind, found.status);
+            else if (!writable(el))
+                note(el, d.bind, "refused-element");
+            else {
+                const image = el.localName === "img";
+                if (image) {
+                    keepAttr(el, "src");
+                    keepAttr(el, "srcset");
+                    keepAttr(el, "hidden");
+                }
+                else
+                    keepContent(el);
+                if (isEmpty(found.value)) {
+                    // published, and there is nothing to show here
+                    if (image)
+                        setVisible(el, false);
+                    else
+                        el.textContent = "";
+                    note(el, d.bind, "empty");
+                }
+                else {
+                    let refusal;
+                    if (image)
+                        refusal = writeImage(el, found.value, sinks, d.width);
+                    else if (d.format === "markdown")
+                        refusal = writeMarkdown(el, found.value, sinks);
+                    else if (d.format === "text")
+                        refusal = writeText(el, found.value);
+                    else {
+                        const words = formatted(found.value, d.format, el.closest("[lang]")?.getAttribute("lang") ?? undefined);
+                        refusal = words === null ? "type" : writeText(el, words);
+                    }
+                    if (refusal)
+                        note(el, d.bind, refusal);
+                    else
+                        bound++;
+                }
+            }
+        }
+        for (const [name, path] of d.attrs) {
+            const found = look(scope, path);
+            if (found.status !== "value") {
+                note(el, path, found.status);
+                continue;
+            }
+            keepAttr(el, name);
+            if (isEmpty(found.value)) {
+                // an image without a description is a decorative one; any other attribute goes
+                if (name === "alt")
+                    el.setAttribute("alt", "");
+                else
+                    el.removeAttribute(name);
+                note(el, path, "empty");
+                continue;
+            }
+            const before = el.getAttribute(name);
+            const refusal = writeAttribute(el, name, found.value, sinks, d.width);
+            if (refusal) {
+                if (before === null)
+                    el.removeAttribute(name);
+                note(el, path, refusal);
+            }
+            else
+                bound++;
+        }
+        for (const [path, shows] of [[d.show, true], [d.hide, false]]) {
+            if (path === undefined)
+                continue;
+            const found = look(scope, path);
+            if (found.status !== "value") {
+                note(el, path, found.status);
+                continue;
+            }
+            keepAttr(el, "hidden");
+            const has = !isEmpty(found.value) && found.value !== false;
+            setVisible(el, has === shows);
+            bound++;
+        }
+        if (d.link !== undefined) {
+            const unread = [];
+            const filled = fillTemplate(d.link, sinks.base, (segments) => {
+                const found = look(scope, segments.join("."));
+                if (found.status === "value")
+                    return found.value;
+                unread.push(found.status);
+                return undefined;
+            });
+            if (unread[0])
+                note(el, d.link, unread[0]);
+            else if (!filled.ok)
+                note(el, filled.path, filled.reason);
+            else {
+                keepAttr(el, "href");
+                const refusal = writeLink(el, filled.url);
+                if (refusal)
+                    note(el, d.link, refusal);
+                else
+                    bound++;
+            }
+        }
+    }
+    /** The element's template, once per item; what else it held is its fallback. */
+    function repeat(el, sources, depth) {
+        const template = templateOf(el);
+        if (!template) {
+            note(el, "template", "unsupported");
+            return;
+        }
+        keepContent(el);
+        const kept = [template];
+        for (const child of Array.from(el.children)) {
+            if (!child.hasAttribute(`${P}empty`))
+                continue;
+            keepAttr(child, "hidden");
+            setVisible(child, sources.length === 0);
+            kept.push(child);
+        }
+        const items = [];
+        for (const source of sources.slice(0, MAX_ITEMS)) {
+            const clone = template.content.cloneNode(true);
+            fill(compile(clone, false), { kind: "record", source }, depth + 1);
+            items.push(...Array.from(clone.childNodes));
+        }
+        el.replaceChildren(...kept, ...items);
+        bound++;
+    }
+    function fill(block, scope, depth) {
+        issues.push(...block.issues);
+        for (const { el, d } of block.bound)
+            fillElement(el, d, scope);
+        for (const each of block.eaches) {
+            const found = look(scope, each.path);
+            if (found.status !== "value") {
+                note(each.el, each.path, found.status);
+                continue;
+            }
+            if (depth >= MAX_EACH_DEPTH) {
+                note(each.el, each.path, "unsupported");
+                continue;
+            }
+            // a repeatable group is a list of items; one that isn't repeatable is a single item
+            const value = found.value;
+            const items = Array.isArray(value) ? value : isEmpty(value) ? [] : [value];
+            if (items.some((item) => item === null || typeof item !== "object" || Array.isArray(item))) {
+                note(each.el, each.path, "type");
+                continue;
+            }
+            if (items.length === 0)
+                note(each.el, each.path, "empty");
+            repeat(each.el, items.map((item) => ({ data: item })), depth);
+        }
+    }
+    async function read(load, wellFormed) {
+        try {
+            const value = await load();
+            if (value === null)
+                return { status: "missing" };
+            // an answer of another shape than Mapled's is no answer: the place keeps the author's HTML
+            return wellFormed(value) ? { status: "ok", value } : { status: "failed", answered: true };
+        }
+        catch (err) {
+            // an unknown collection or single is the page's mistake, not an outage
+            return err instanceof MapledError && err.status === 404 && err.code !== "RELEASE_NOT_FOUND" ? { status: "missing" } : { status: "failed" };
+        }
+    }
+    let last = null;
+    let warned = "";
+    let stopWatching = null;
+    let expiry;
+    let stopped = false;
+    /** moves when preview is left: a fill that began before it commits nothing */
+    let generation = 0;
+    /** the generation of the last fill that committed: an exit's own fill is skipped when one already has */
+    let committed = -1;
+    /** how many times a fill starts over when the session changed under it */
+    const MAX_ATTEMPTS = 3;
+    const interval = typeof options.live === "number" ? options.live : undefined;
+    /** Preview is over — the page's own way out, or the session's end: the
+        page is as written again, and says so, before anything is asked of
+        Mapled; what is published follows when it is in hand. */
+    function leave() {
+        restore();
+        last = { state: "fallback", release: null, preview: false, bound: 0, issues: [] };
+        root.setAttribute(`${P}state`, "fallback");
+        root.removeAttribute(`${P}preview`);
+    }
+    /** Preview ends now, not after the fill in flight: the draft goes at
+        once, and whatever that fill brings back is dropped. */
+    function drop() {
+        generation++;
+        clearTimeout(expiry);
+        if (last?.preview)
+            leave();
+    }
+    /** The session's end is a fill of its own: no draft is shown past it —
+        the timer stays set through fills that fail or stall. */
+    function watchExpiry() {
+        clearTimeout(expiry);
+        const session = previewSession();
+        if (!session || stopped)
+            return;
+        const left = Date.parse(session.expiresAt) - Date.now();
+        expiry = setTimeout(() => {
+            if (previewSession() === null)
+                drop();
+            void refresh();
+        }, Math.min(Math.max(left, 0) + 1, 0x7fffffff));
+    }
+    async function run(known, attempt = 1) {
+        const first = last === null;
+        if (first)
+            root.setAttribute(`${P}state`, "loading");
+        const mine = generation;
+        const preview = await client.isPreview().catch(() => false);
+        // the session the drafts are read with: an answer read with another one is not this fill's
+        const session = preview ? (previewSession()?.draftToken ?? null) : null;
+        // a tab that left preview, or whose session ended, shows nothing of the drafts — before anything is asked
+        if (last !== null && last.preview && !preview)
+            leave();
+        // releases only grow (a rollback is a new one): a fill pinned to one the page already shows filled, or an older one, has nothing to add — a page left as written keeps trying
+        if (!preview && known !== undefined && last !== null && last.state === "ready" && !last.preview && last.release !== null && known <= last.release)
+            return last;
+        const finish = (report) => {
+            last = report;
+            committed = mine;
+            root.setAttribute(`${P}state`, report.state);
+            root.toggleAttribute(`${P}preview`, report.preview);
+            const loud = report.issues.filter((i) => i.reason !== "empty");
+            const text = loud.map((i) => `${i.path} (${i.reason}) on ${i.on}`).join("; ");
+            if (text !== warned) {
+                warned = text;
+                if (loud.length > 0)
+                    console.warn(`[mapled] ${loud.length === 1 ? "1 place" : `${loud.length} places`} couldn't be filled: ${text}`);
+            }
+            doc.dispatchEvent(new CustomEvent(first ? "mapled:ready" : "mapled:update", { detail: report }));
+            if (report.preview)
+                watchExpiry();
+            else {
+                clearTimeout(expiry);
+                // drafts don't move with releases: a tab watches once it shows what is published
+                if (options.live && stopWatching === null)
+                    stopWatching = client.watch((next) => void refresh(next.release), { interval });
+            }
+            return report;
+        };
+        // drafts have no release; what is published is read pinned to one, so a
+        // publish landing mid-read can't mix two — and a pinned answer is the
+        // browser's to keep
+        let release = null;
+        if (!preview) {
+            if (known !== undefined)
+                release = known;
+            else {
+                try {
+                    const pointer = await client.getRelease();
+                    if (pointer === null) {
+                        // nothing is published: the page is as written — a draft it showed goes too
+                        restore();
+                        return finish({ state: "unpublished", release: null, preview, bound: 0, issues: [] });
+                    }
+                    release = pointer.release;
+                }
+                catch {
+                    // out of reach: the page stays as it is — as written, or as last filled from what is published
+                    return last !== null && last.state === "ready" ? last : finish({ state: "fallback", release: null, preview, bound: 0, issues: [] });
+                }
+            }
+        }
+        const pin = release === null ? {} : { release };
+        const page = compile(root, true);
+        // the root element's own attributes belong to the page too
+        const onRoot = declaredOn(root, page.issues);
+        if (onRoot)
+            page.bound.unshift({ el: root, d: onRoot });
+        const singles = new Map();
+        const lists = new Map();
+        const records = new Map();
+        const reads = [];
+        for (const [key, expand] of heads(page)) {
+            reads.push(read(() => client.getSingle(key, { ...pin, ...(expand.size > 0 ? { expand: [...expand] } : {}) }), isRecord).then((r) => singles.set(key, r)));
+        }
+        for (const list of page.lists) {
+            const template = templateOf(list.el);
+            const fields = template ? [...heads(compile(template.content, false)).keys()] : [];
+            reads.push(read(async () => (await client.getRecords(list.collection, { ...list.options, ...pin, ...(fields.length > 0 ? { fields } : {}) })).records, isRecordList).then((r) => lists.set(list, r)));
+        }
+        for (const record of page.records) {
+            if (record.slug === null) {
+                records.set(record, { status: "missing" });
+                continue;
+            }
+            const slug = record.slug;
+            reads.push(read(() => client.getRecordBySlug(record.collection, slug, { ...pin, ...(record.expand.length > 0 ? { expand: record.expand } : {}) }), isRecord).then((r) => records.set(record, r)));
+        }
+        await Promise.all(reads);
+        // preview was left, or the session ended or was replaced, while the reads were on their way:
+        // what they brought is nobody's now — read again, with whatever the tab has
+        const now = (await client.isPreview().catch(() => false)) ? (previewSession()?.draftToken ?? null) : null;
+        if (mine !== generation || now !== session) {
+            if (attempt < MAX_ATTEMPTS)
+                return run(known, attempt + 1);
+            // the session keeps changing under the reads: show nothing of any of them — the page as written, until the next fill
+            restore();
+            return finish({ state: "fallback", release: null, preview: now !== null, bound: 0, issues: [] });
+        }
+        // nothing came back at all: an outage, and the page stays as it is — a wrong-shaped answer is still an answer, reported by its place
+        const answers = [...singles.values(), ...lists.values(), ...records.values()];
+        if (answers.length > 0 && answers.every((a) => a.status === "failed" && !a.answered)) {
+            return last !== null && last.state === "ready" ? last : finish({ state: "fallback", release, preview, bound: 0, issues: [] });
+        }
+        // one synchronous pass: back to what the author wrote, then filled
+        restore();
+        issues = [];
+        bound = 0;
+        fill(page, { kind: "page", singles }, 0);
+        for (const list of page.lists) {
+            const answer = lists.get(list);
+            if (answer?.status === "ok")
+                repeat(list.el, answer.value, 0);
+            else
+                note(list.el, list.collection, answer?.status ?? "failed");
+        }
+        for (const record of page.records) {
+            const answer = records.get(record);
+            if (answer?.status === "ok")
+                fill(record.block, { kind: "record", source: answer.value }, 0);
+            else
+                note(record.el, record.collection, answer?.status ?? "failed");
+        }
+        wireForms();
+        return finish({ state: "ready", release, preview, bound, issues });
+    }
+    /* ---- forms ---- */
+    const wired = new WeakSet();
+    const worded = new WeakSet();
+    function wireForms() {
+        for (const form of Array.from(root.querySelectorAll(`form[${P}form]`))) {
+            if (wired.has(form))
+                continue;
+            wired.add(form);
+            form.addEventListener("submit", (event) => {
+                event.preventDefault();
+                void send(form);
+            });
+        }
+    }
+    async function send(form) {
+        if (form.getAttribute(`${P}form-state`) === "sending")
+            return;
+        const key = (form.getAttribute(`${P}form`) ?? "").trim();
+        const sent = form.querySelector(`[${P}form-sent]`);
+        const failed = form.querySelector(`[${P}form-failed]`);
+        const buttons = Array.from(form.querySelectorAll("button, input[type=submit]")).filter((b) => !b.disabled);
+        form.setAttribute(`${P}form-state`, "sending");
+        for (const b of buttons)
+            b.disabled = true;
+        // the label of the consent box the visitor ticked is kept with the submission
+        const box = form.querySelector(`input[type=checkbox][${P}consent]`);
+        const consent = box?.checked ? (box.labels?.[0]?.textContent ?? box.closest("label")?.textContent ?? "").trim().slice(0, 500) : "";
+        const answer = KEY.test(key)
+            ? await submitForm(key, form, { key: options.key, apiUrl: options.apiUrl, fetch: options.fetch, ...(consent ? { consent } : {}) })
+            : { ok: false, status: 0, code: "BAD_FORM", message: "This form isn't set up yet." };
+        for (const b of buttons)
+            b.disabled = false;
+        form.setAttribute(`${P}form-state`, answer.ok ? "sent" : "failed");
+        if (answer.ok)
+            form.reset();
+        if (sent)
+            setVisible(sent, answer.ok);
+        if (failed) {
+            // the page's own words win; an element it left empty gets Mapled's
+            if (!answer.ok && (worded.has(failed) || (failed.textContent ?? "").trim() === "")) {
+                worded.add(failed);
+                failed.textContent = answer.message;
+            }
+            setVisible(failed, !answer.ok);
+        }
+        doc.dispatchEvent(new CustomEvent("mapled:form", { detail: answer.ok ? { form: key, ok: true } : { form: key, ok: false, status: answer.status, code: answer.code } }));
+    }
+    /* ---- the page ---- */
+    wireForms();
+    const guarded = async (known) => {
+        try {
+            return await run(known);
+        }
+        catch (err) {
+            console.error(`[mapled] ${err instanceof Error ? err.message : "The page couldn't be filled."}`);
+            return last ?? { state: "fallback", release: null, preview: false, bound: 0, issues: [] };
+        }
+    };
+    let queue = guarded();
+    const refresh = (known) => (queue = queue.then(() => guarded(known)));
+    /** Preview is left: at once on the page, then one fill — unless a fill that began after the exit already committed. */
+    const exit = () => {
+        endPreview();
+        drop();
+        const after = generation;
+        return (queue = queue.then(() => (committed >= after && last !== null ? last : guarded())));
+    };
+    const onClick = (event) => {
+        const target = event.target;
+        if (!target?.closest?.(`[${P}end-preview]`))
+            return;
+        event.preventDefault();
+        void exit();
+    };
+    doc.addEventListener("click", onClick);
+    return {
+        ready: queue,
+        get report() {
+            return last;
+        },
+        refresh: () => refresh(),
+        endPreview: exit,
+        stop: () => {
+            stopped = true;
+            stopWatching?.();
+            stopWatching = () => { };
+            clearTimeout(expiry);
+            doc.removeEventListener("click", onClick);
+        },
+        client,
+    };
+}