@heroiclands/package-build 23.13.0 → 24.0.1

package/engine/site-root.mjs

@@ -15,20 +15,20 @@
  * The files that belong to a deployment's **root** rather than to the rendered
  * site.
  *
- * Hugo renders into `<out>/<package>/`, because the deployment carries the
+ * `package-build site build` renders into `<out>/<package>/`, because the deployment carries the
  * `/<package>/` prefix physically and the routing layer is a path-preserving
  * pass-through. The directory that is *uploaded* is its parent, and Cloudflare
  * Pages reads `_headers` and `_redirects` from there and nowhere else — a copy
- * inside the prefix is published as a text file and never applied. Hugo owns
+ * inside the prefix is published as a text file and never applied. The render owns
  * everything under the prefix; this owns what sits beside it.
  *
  * **One file, `_headers`.** The prefix root is the homepage — the site build
- * writes it as the mount's `_index.md` — so nothing redirects, and no
+ * renders it at the package root — so nothing redirects, and no
  * `_redirects` is written. One left beside the site by an earlier build is
  * removed rather than left to send every reader somewhere nothing publishes.
  *
  * **And one directory inside the prefix, `pagefind/`.** Every package site
- * ends the same way — Hugo renders into the output directory, this
+ * ends the same way — the render fills the output directory, this
  * post-processes it there — so the search index is built in this step and
  * every site gets one without each repository adding a dependency and a
  * script. Pagefind indexes the rendered pages and writes `<package>/pagefind/`
@@ -51,7 +51,8 @@
 import fs from "node:fs";
 import path from "node:path";
 import * as pagefind from "pagefind";
-import { gunzipSync } from "node:zlib";
+
+import { feedPaths, reachablePages } from "./site-reach.mjs";
 
 import { formatDiagnostic } from "./diagnostics.mjs";
 
@@ -120,15 +121,19 @@ export function noindexHeaders() {
  * that names their version, so a year's lifetime never serves a stale file.
  *
  * @param {object} [options] - Options.
- * @param {string} [options.pkg] - The content package, which is the prefix.
+ * @param {string} [options.pkg] - The content package, whose site is served at
+ *   `/<pkg>/` unless `base` says otherwise.
+ * @param {string} [options.base] - The path the site is served at, beginning
+ *   and ending with `/`.
  * @param {boolean} [options.fonts] - Whether the site carries the fonts.
  * @returns {string} The file's contents.
  */
-export function headers({ pkg, fonts = false } = {}) {
+export function headers({ pkg, base, fonts = false } = {}) {
     const lines = noindexHeaders();
-    if (fonts && pkg) {
+    const prefix = base ?? (pkg ? `/${pkg}/` : "");
+    if (fonts && prefix) {
         lines.push(
-            `/${pkg}/fonts/heroiclands/*`,
+            `${prefix}fonts/heroiclands/*`,
             "  Cache-Control: public, max-age=31536000, immutable",
             "",
         );
@@ -145,11 +150,40 @@ export function headers({ pkg, fonts = false } = {}) {
  * binary.
  *
  * @callback SiteIndexer
- * @param {{site: string, output: string}} where - The rendered site, and the
- *   directory inside it the index is written to.
+ * @param {{site: string, output: string, base?: string}} where - The rendered
+ *   site, the directory inside it the index is written to, and the path the
+ *   site is served at. With a `base`, only the pages reachable from the
+ *   homepage are indexed.
  * @returns {Promise<{pages: number}>} How many pages were indexed.
  */
 
+/**
+ * The addresses of the pages reachable from a rendered site's homepage.
+ *
+ * @param {string} site - The rendered site's directory, served at `base`.
+ * @param {string} base - The path the site is served at.
+ * @returns {Set<string>} Page addresses, each beginning with `base`.
+ */
+function reachableFromDisk(site, base) {
+    const file = (url) => path.join(site, ...url.slice(base.length).split("/").filter(Boolean));
+    const read = (target) => {
+        try {
+            return fs.readFileSync(target, "utf8");
+        } catch {
+            return undefined;
+        }
+    };
+    return reachablePages({
+        base,
+        html: (url) => read(path.join(file(url), "index.html")),
+        expand: (target) => {
+            if (!target.endsWith(".xml")) return [];
+            const xml = read(file(target));
+            return xml === undefined ? [] : feedPaths(xml);
+        },
+    });
+}
+
 /**
  * Build the search index of a rendered site with Pagefind.
  *
@@ -165,12 +199,17 @@ export function headers({ pkg, fonts = false } = {}) {
  * - The binary missing is reported by the package as an install failure of
  *   its own; it is rethrown naming the platform package to install.
  *
+ * With a `base`, the index covers the pages reachable from the homepage by
+ * the links the rendered HTML carries, and no others: an unlinked page is
+ * served but not searchable. Each reachable page is handed to Pagefind as its
+ * own file, so a page outside the set is never read.
+ *
  * The output directory is emptied first, so an index of an earlier build's
  * pages never survives beside the current one.
  *
  * @type {SiteIndexer}
  */
-export async function indexSite({ site, output }) {
+export async function indexSite({ site, output, base }) {
     if (!fs.statSync(site, { throwIfNoEntry: false })?.isDirectory()) {
         throw new Error(`${site} is not a directory, so there is nothing to index`);
     }
@@ -197,33 +236,40 @@ export async function indexSite({ site, output }) {
     }
     let pages;
     try {
-        const added = await index.addDirectory({ path: site });
-        if (added.errors.length) throw new Error(added.errors.join("; "));
-        pages = added.page_count;
+        if (base) {
+            pages = 0;
+            for (const url of reachableFromDisk(site, base)) {
+                const sourcePath = path.posix.join(
+                    ...url.slice(base.length).split("/"),
+                    "index.html",
+                );
+                const content = fs.readFileSync(path.join(site, sourcePath), "utf8");
+                const added = await index.addHTMLFile({ sourcePath, content });
+                if (added.errors.length) throw new Error(added.errors.join("; "));
+                pages += 1;
+            }
+        } else {
+            const added = await index.addDirectory({ path: site });
+            if (added.errors.length) throw new Error(added.errors.join("; "));
+            pages = added.page_count;
+        }
         if (!pages) {
             throw new Error(`no page under ${site} was indexed — the site holds no HTML`);
         }
-        const written = await index.writeFiles({ outputPath: output });
-        if (written.errors.length) throw new Error(written.errors.join("; "));
+        // The files are taken from the index in memory and written here,
+        // because `writeFiles` can answer while the binary is still flushing
+        // them, which leaves an index that a reader loads half-written.
+        const { files, errors } = await index.getFiles();
+        if (errors.length) throw new Error(errors.join("; "));
+        if (!files.length) throw new Error("the search index holds no files");
+        for (const file of files) {
+            const target = path.join(output, file.path);
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, file.content);
+        }
     } finally {
         await pagefind.close();
     }
-    // Pagefind may finish its API call while fragment writes are still visible
-    // as incomplete gzip streams under heavy parallel load. A successful site
-    // build must hand deployment complete fragments.
-    const fragmentDir = path.join(output, "fragment");
-    const deadline = Date.now() + 5000;
-    for (;;) {
-        try {
-            const fragments = fs.readdirSync(fragmentDir);
-            if (!fragments.length) throw new Error("no search fragments were written");
-            for (const name of fragments) gunzipSync(fs.readFileSync(path.join(fragmentDir, name)));
-            break;
-        } catch (error) {
-            if (Date.now() >= deadline) throw error;
-            await new Promise((resolve) => setTimeout(resolve, 25));
-        }
-    }
     return { pages };
 }
 
@@ -245,7 +291,10 @@ export async function indexSite({ site, output }) {
  *
  * @param {object} options - Options.
  * @param {string} options.pkg - The content package name, which is also the
- *   directory Hugo rendered into.
+ *   directory the site is rendered into unless `base` says otherwise.
+ * @param {string} [options.base] - The path the site is served at, beginning
+ *   and ending with `/`; the site is rendered into that path under `out`, so
+ *   a site served at `/` is rendered at `out` itself.
  * @param {string} options.out - The directory that is deployed.
  * @param {boolean} [options.search] - Whether to build the search index;
  *   `site.search` in the configuration. Default `true`.
@@ -259,18 +308,20 @@ export async function indexSite({ site, output }) {
  *   under the prefix; or, located at the rendered site, when the indexer
  *   fails.
  */
-export async function writeSiteRoot({ pkg, out, search = true, indexer = indexSite }) {
+export async function writeSiteRoot({ pkg, base, out, search = true, indexer = indexSite }) {
     const root = path.resolve(out);
-    const rendered = path.join(root, pkg);
+    const prefix = base ?? `/${pkg}/`;
+    const rendered = path.join(root, ...prefix.split("/").filter(Boolean));
     if (!fs.existsSync(path.join(rendered, "index.html"))) {
         throw new Error(
-            `${out}/${pkg}/ holds no rendered site — build the site before its root files`,
+            `${path.join(out, ...prefix.split("/").filter(Boolean))}/ holds no rendered site — ` +
+                "build the site before its root files",
         );
     }
 
     const file = path.join(root, "_headers");
     const fonts = fs.existsSync(path.join(rendered, "fonts", "heroiclands"));
-    fs.writeFileSync(file, headers({ pkg, fonts }));
+    fs.writeFileSync(file, headers({ pkg, base: prefix, fonts }));
     fs.rmSync(path.join(root, "_redirects"), { force: true });
 
     const dir = path.join(rendered, SEARCH_DIR);
@@ -280,7 +331,7 @@ export async function writeSiteRoot({ pkg, out, search = true, indexer = indexSi
     }
     let pages;
     try {
-        ({ pages } = await indexer({ site: rendered, output: dir }));
+        ({ pages } = await indexer({ site: rendered, output: dir, base: prefix }));
     } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         // A directory, so the locator is the file field alone: there is no

package/engine/site-search.mjs

@@ -0,0 +1,161 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * **What a note's page tells the site's search.** Pagefind reads the filters a
+ * page carries, so a reader can narrow a search to a package, a kind of note
+ * or a part of the world:
+ *
+ * | Filter | Value |
+ * | ------ | ----- |
+ * | `package` | the package that publishes the note |
+ * | `type` | the note's `type` |
+ * | `subtype` | the note's `subType` |
+ * | `culture` | the name of the culture `data.culture` names |
+ * | `continent` | the continent the note lies in |
+ * | `region` | the outermost region beneath that continent |
+ *
+ * A place lies where its `parents` lead; a being where its `homes` are; a
+ * scenario where its `locations` are. A continent is a region whose parent is
+ * the world. A note reached by more than one path carries every continent and
+ * region it reaches, so a being with homes in two regions is found under both.
+ *
+ * The note's name and its aliases are weighted, so a search for a name finds
+ * its note first. A note's tags and its draft state are not filters.
+ *
+ * @module
+ */
+
+import { placeShortcodes } from "./map-places.mjs";
+import { resolveInfoboxRef } from "./site-index.mjs";
+
+/** The filters a note's page carries, in the order a reader is offered them. */
+export const SEARCH_FILTERS = Object.freeze([
+    "package",
+    "type",
+    "subtype",
+    "culture",
+    "continent",
+    "region",
+]);
+
+/**
+ * @param {unknown} value - Anything.
+ * @returns {boolean} Whether it is a mapping a field may be read out of.
+ */
+const isMapping = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * The continents and regions every place lies in.
+ *
+ * @param {Map<string, {shortcode: string, name: string, subType?: string, parents: string[]}>} places -
+ *   Every place, by shortcode, as {@link module:engine/map-places.mapWorld} reads them.
+ * @returns {(shortcodes: Iterable<string>) => {continents: string[], regions: string[]}}
+ *   The names of the continents and the outermost regions the given places lie
+ *   in, each sorted.
+ */
+export function placeGeography(places) {
+    const worlds = new Set(
+        [...places.values()].filter((p) => p.subType === "world").map((p) => p.shortcode),
+    );
+    const isContinent = (place) =>
+        place?.subType === "region" && place.parents.some((parent) => worlds.has(parent));
+    /** @type {Map<string, {continents: Set<string>, regions: Set<string>}>} */
+    const known = new Map();
+
+    const reach = (shortcode, visiting) => {
+        if (known.has(shortcode)) return known.get(shortcode);
+        const found = { continents: new Set(), regions: new Set() };
+        const place = places.get(shortcode);
+        if (!place || visiting.has(shortcode) || worlds.has(shortcode)) return found;
+        visiting.add(shortcode);
+        if (isContinent(place)) found.continents.add(shortcode);
+        for (const parent of place.parents) {
+            if (place.subType === "region" && isContinent(places.get(parent)))
+                found.regions.add(shortcode);
+            const above = reach(parent, visiting);
+            for (const c of above.continents) found.continents.add(c);
+            for (const r of above.regions) found.regions.add(r);
+        }
+        visiting.delete(shortcode);
+        known.set(shortcode, found);
+        return found;
+    };
+
+    const names = (shortcodes) =>
+        [...new Set([...shortcodes].map((sc) => places.get(sc)?.name ?? sc))].sort();
+    return (shortcodes) => {
+        const continents = new Set();
+        const regions = new Set();
+        for (const shortcode of shortcodes) {
+            const found = reach(shortcode, new Set());
+            for (const c of found.continents) continents.add(c);
+            for (const r of found.regions) regions.add(r);
+        }
+        return { continents: names(continents), regions: names(regions) };
+    };
+}
+
+/**
+ * The places a note lies in: itself for a place, its `homes` and its
+ * `locations` otherwise.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @returns {string[]} Shortcodes, lower case.
+ */
+export function notePlaces(fm) {
+    if (fm?.type === "place") return [String(fm.shortcode ?? "").toLowerCase()].filter(Boolean);
+    const data = isMapping(fm?.data) ? fm.data : {};
+    return [...placeShortcodes(data.homes), ...placeShortcodes(data.locations)];
+}
+
+/**
+ * What a note's page tells the search.
+ *
+ * @param {object} fm - The page's frontmatter: the note's, with its `package`.
+ * @param {object} options - What the values resolve against.
+ * @param {(shortcodes: Iterable<string>) => {continents: string[], regions: string[]}} options.geography -
+ *   From {@link placeGeography}.
+ * @param {object} [options.index] - The site's address index, which names the
+ *   culture `data.culture` names.
+ * @returns {{filters: Array<{name: string, values: string[]}>, names: string[]}}
+ *   Each filter with a value, in {@link SEARCH_FILTERS} order, and the names a
+ *   search weights.
+ */
+export function searchMetadata(fm, { geography, index }) {
+    const data = isMapping(fm?.data) ? fm.data : {};
+    const text = (value) => (value === undefined || value === null ? "" : String(value).trim());
+    const culture =
+        data.culture !== undefined && data.culture !== null && data.culture !== "" ?
+            index && resolveInfoboxRef(index, data.culture, { type: "lore" })?.name
+        :   undefined;
+    const { continents, regions } = geography(notePlaces(fm));
+    const values = {
+        package: [text(fm?.package)],
+        type: [text(fm?.type)],
+        subtype: [text(fm?.subType)],
+        culture: [text(culture)],
+        continent: continents,
+        region: regions,
+    };
+    const filters = SEARCH_FILTERS.map((name) => ({
+        name,
+        values: values[name].filter(Boolean),
+    })).filter((filter) => filter.values.length);
+    const name = isMapping(fm?.name) ? fm.name : {};
+    const names = [
+        text(name.full),
+        ...(Array.isArray(name.aliases) ? name.aliases.map(text) : []),
+    ].filter(Boolean);
+    return { filters, names: [...new Set(names)] };
+}

package/engine/site-serve.mjs

@@ -0,0 +1,274 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * **A site served while it is written.** {@link serveSite} builds a package's
+ * site, serves it, and keeps it current: it watches the content tree and the
+ * theme, writes again what a change touches, and tells every open page to
+ * reload.
+ *
+ * | Change | What is written again |
+ * | ------ | --------------------- |
+ * | a note's body or frontmatter | that note's page |
+ * | a note's name, type or shortcode, a new or removed note, a note holding an `sql` table, any other file in the content tree | the whole site |
+ * | the theme's layouts, partials or files | every page, and the theme's files |
+ *
+ * A page that changes because another note changed — a table that lists the
+ * note, a link that carries its name — is written again by the next whole
+ * build. A note in error is written as its page shows it, and the error is
+ * reported; a build whose gates fire writes nothing and leaves the last good
+ * site in place.
+ *
+ * The site is served from the deployed root, so a page is at the address it is
+ * deployed at, its base path included. Every HTML page is sent with a script
+ * that listens on {@link RELOAD_PATH} for the server's `reload` event; the
+ * script is added as the page is sent and is never written to the site. The
+ * search index is built once, after the first build.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+
+import { siteBuildFailed } from "./site-build.mjs";
+import { SITE_THEME_DIR } from "./site-theme.mjs";
+import { SITE_STATIC_DIR, buildPackageSite, writeSite, writeThemeFiles } from "./site-render.mjs";
+import { siteBase } from "../content-config.mjs";
+import { SEARCH_DIR, indexSite } from "./site-root.mjs";
+
+/** The address a served page listens on for the server's reloads. */
+export const RELOAD_PATH = "/__package-build/reload";
+
+/** How long a burst of changes is gathered before it is written, in milliseconds. */
+const SETTLE_MS = 120;
+
+/** What a file is sent as, by its extension. */
+const CONTENT_TYPES = Object.freeze({
+    ".html": "text/html; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".mjs": "text/javascript; charset=utf-8",
+    ".json": "application/json",
+    ".xml": "application/xml",
+    ".txt": "text/plain; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".webp": "image/webp",
+    ".gif": "image/gif",
+    ".woff2": "font/woff2",
+    ".woff": "font/woff",
+    ".wasm": "application/wasm",
+});
+
+/** The script a served page is sent with. */
+const RELOAD_SCRIPT = `<script>new EventSource(${JSON.stringify(RELOAD_PATH)}).addEventListener("reload", () => location.reload());</script>`;
+
+/** Whether a note's text holds a query its build prepares ahead of the render. */
+const holdsQuery = (text) => /```\s*sql\b|\{\{[^}]*\bsql\b/.test(text);
+
+/**
+ * Serve a package's site, and keep it current.
+ *
+ * @param {object} options - The inputs.
+ * @param {object} options.config - The resolved configuration.
+ * @param {string} options.out - The site's directory under the deployed
+ *   root, which the site is written to.
+ * @param {string} [options.root] - The deployed root, which is served. The
+ *   directory above `out` by default; `out` itself for a site served at `/`.
+ * @param {string} [options.host] - The address to listen on.
+ * @param {number} [options.port] - The port; `0` takes any free one.
+ * @param {boolean} [options.search] - Build the search index after the first
+ *   build, where the site has one.
+ * @param {number} [options.year] - The year the footer states.
+ * @param {(event: {kind: string, built?: object, files?: string[], findings?: object[], error?: unknown}) => void} [options.report] -
+ *   Told of each build: `built` for a whole build, `page` for one note's page,
+ *   `theme` for the theme, `failed` with what the build found, `error` with
+ *   what it threw.
+ * @returns {Promise<{url: string, close: () => Promise<void>, settled: () => Promise<void>}>}
+ *   The address of the site's home page, how to stop serving, and a promise
+ *   for the moment every change seen so far has been written.
+ */
+export async function serveSite({
+    config,
+    out,
+    root = path.dirname(out),
+    host = "127.0.0.1",
+    port = 1313,
+    search = true,
+    year,
+    report = () => {},
+}) {
+    /** @type {Set<http.ServerResponse>} */
+    const listeners = new Set();
+    let state = null;
+
+    const reload = () => {
+        for (const res of listeners) res.write("event: reload\ndata: {}\n\n");
+    };
+
+    const buildAll = async () => {
+        const result = await buildPackageSite({ config, out, year });
+        if (!result.written || siteBuildFailed(result.built))
+            report({ kind: "failed", built: result.built });
+        if (!result.written) return false;
+        state = result;
+        report({ kind: "built", built: result.built, findings: result.written.findings });
+        return true;
+    };
+
+    const redrawNotes = (files) => {
+        if (!state) return false;
+        const changed = new Set();
+        for (const file of files) {
+            const text = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+            if (!file.endsWith(".md") || !text || holdsQuery(text)) return false;
+            const entry = state.built.site.renderNote(file);
+            if (!entry) return false;
+            if (entry.findings.length) {
+                report({ kind: "failed", findings: entry.findings });
+                return true;
+            }
+            const page = state.pageOf(entry);
+            state.pages = state.pages.map((old) => (old.url === page.url ? page : old));
+            changed.add(page.url);
+        }
+        const written = writeSite({ site: state.site, pages: state.pages, out, only: changed });
+        report({ kind: "page", files: written.files, findings: written.findings });
+        return true;
+    };
+
+    const redrawTheme = () => {
+        if (!state) return false;
+        writeThemeFiles(out);
+        const written = writeSite({
+            site: state.site,
+            pages: state.pages,
+            out,
+            only: new Set(state.pages.map((page) => page.url)),
+        });
+        report({ kind: "theme", files: written.files, findings: written.findings });
+        return true;
+    };
+
+    const indexForSearch = async () => {
+        if (!search || config.site.search === false || !state) return;
+        await indexSite({ site: out, output: path.join(out, SEARCH_DIR), base: siteBase(config) });
+    };
+
+    await buildAll();
+    await indexForSearch();
+
+    /** @type {{content: Set<string>, theme: boolean}} */
+    let pending = { content: new Set(), theme: false };
+    let timer = null;
+    let work = Promise.resolve();
+    const flush = () => {
+        timer = null;
+        const batch = pending;
+        pending = { content: new Set(), theme: false };
+        work = work.then(async () => {
+            try {
+                let done = true;
+                if (batch.content.size && !redrawNotes([...batch.content])) {
+                    done = await buildAll();
+                    if (done) await indexForSearch();
+                } else if (batch.theme) done = redrawTheme();
+                if (done) reload();
+            } catch (error) {
+                report({ kind: "error", error });
+            }
+        });
+    };
+    const queue = (kind, file) => {
+        if (kind === "theme") pending.theme = true;
+        else pending.content.add(file);
+        if (!timer) timer = setTimeout(flush, SETTLE_MS);
+    };
+
+    const watchers = [
+        fs.watch(config.paths.content, { recursive: true }, (_event, name) => {
+            if (name) queue("content", path.join(config.paths.content, String(name)));
+        }),
+        ...[SITE_THEME_DIR, SITE_STATIC_DIR]
+            .filter((dir) => fs.existsSync(dir))
+            .map((dir) => fs.watch(dir, { recursive: true }, () => queue("theme"))),
+    ];
+
+    const server = http.createServer((req, res) => {
+        const address = decodeURIComponent(
+            new URL(req.url ?? "/", "http://serve.invalid").pathname,
+        );
+        if (address === RELOAD_PATH) {
+            res.writeHead(200, {
+                "content-type": "text/event-stream",
+                "cache-control": "no-cache",
+                connection: "keep-alive",
+            });
+            res.write(": connected\n\n");
+            listeners.add(res);
+            req.on("close", () => listeners.delete(res));
+            return;
+        }
+        let file = path.join(root, address);
+        if (!file.startsWith(root)) {
+            res.writeHead(403).end();
+            return;
+        }
+        if (fs.statSync(file, { throwIfNoEntry: false })?.isDirectory())
+            file = path.join(file, "index.html");
+        let status = 200;
+        if (!fs.existsSync(file)) {
+            status = 404;
+            file = path.join(out, "404.html");
+            if (!fs.existsSync(file)) {
+                res.writeHead(404).end();
+                return;
+            }
+        }
+        const type = CONTENT_TYPES[path.extname(file).toLowerCase()] ?? "application/octet-stream";
+        let body = fs.readFileSync(file);
+        if (type.startsWith("text/html")) {
+            const html = body.toString("utf8");
+            const at = html.lastIndexOf("</body>");
+            body = Buffer.from(
+                at < 0 ? html + RELOAD_SCRIPT : html.slice(0, at) + RELOAD_SCRIPT + html.slice(at),
+            );
+        }
+        res.writeHead(status, { "content-type": type, "cache-control": "no-store" });
+        res.end(body);
+    });
+    await new Promise((resolve) => server.listen(port, host, resolve));
+    const listening = /** @type {import("node:net").AddressInfo} */ (server.address());
+    const base = new URL(config.homepage).pathname;
+
+    return {
+        url: `http://${host}:${listening.port}${base}`,
+        settled: async () => {
+            while (timer || pending.content.size || pending.theme) {
+                await new Promise((resolve) => setTimeout(resolve, SETTLE_MS));
+            }
+            await work;
+        },
+        close: async () => {
+            if (timer) clearTimeout(timer);
+            for (const watcher of watchers) watcher.close();
+            for (const res of listeners) res.end();
+            await work;
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}