ferrovue 0.6.0 → 0.7.1

package/dist/cli.js

@@ -1,30 +1,28 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readFileSync, readdirSync, watch, writeFileSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
-import { CONFIG_FILE, generate, loadConfig, VERSION, write } from "./compiler.js";
+import { dirname, join, resolve } from "node:path";
+import { relativePath } from "./paths.js";
+import { CONFIG_FILE, generate, isGenerated, loadConfig, VERSION, write } from "./compiler.js";
+import { helpText, parseArgs } from "./args.js";
 import { unifiedDiff } from "./diff.js";
-import { diagnose, formatRefusal, isRefusal } from "./diagnostics.js";
+import { diagnose, formatRefusal, formatWarning, isRefusal } from "./diagnostics.js";
+import { affects, inputsOf } from "./inputs.js";
 const root = process.cwd();
-const HELP = `Usage: ferrovue [command] [options]
-
-Compile Vue components to Rust render functions, run from the project root.
-
-Commands:
-  init                     scaffold starter ferrovue.config.json and components
-
-Options:
-      --check              check that generated files match committed files without writing
-  -d, --diff               show unified diff of changes when checking (use with --check)
-      --format <format>    how to write errors and results: human (default) or json
-      --watch              watch components, stores, routes and config for changes and regenerate
-  -c, --config <path>      path to configuration file (default: ferrovue.config.json)
-  -v, --version            print the version and exit
-  -h, --help               print this help and exit
-`;
+const SCHEMA_URL = `https://cdn.jsdelivr.net/npm/ferrovue@${VERSION}/schema.json`;
 let json = false;
+let warnings = [];
+function warn(warning) {
+    if (json)
+        warnings.push(diagnose(warning, "warning"));
+    else
+        console.error(formatWarning(warning));
+}
 function emit(result) {
-    console.log(JSON.stringify({ diagnostics: [], ...result }));
+    const { diagnostics = [], ...rest } = result;
+    console.log(JSON.stringify({ diagnostics: [...warnings, ...diagnostics], ...rest }));
+    warnings = [];
 }
+const load = (configPath) => loadConfig(root, configPath, warn);
 function report(e) {
     if (!isRefusal(e))
         throw e;
@@ -36,18 +34,19 @@ function report(e) {
 function initProject(targetRoot, configPath) {
     const configFile = configPath ? resolve(targetRoot, configPath) : join(targetRoot, CONFIG_FILE);
     if (existsSync(configFile)) {
-        console.error(`error: configuration file already exists: ${relative(targetRoot, configFile) || CONFIG_FILE}`);
+        console.error(`error: configuration file already exists: ${relativePath(targetRoot, configFile) || CONFIG_FILE}`);
         return 1;
     }
     const defaultComponents = "components";
     const defaultOut = "src/generated";
     mkdirSync(dirname(configFile), { recursive: true });
     const config = {
+        $schema: SCHEMA_URL,
         components: defaultComponents,
         out: defaultOut,
     };
     writeFileSync(configFile, JSON.stringify(config, null, 2) + "\n");
-    console.log(`created ${relative(targetRoot, configFile) || CONFIG_FILE}`);
+    console.log(`created ${relativePath(targetRoot, configFile) || CONFIG_FILE}`);
     const compDir = join(targetRoot, defaultComponents);
     mkdirSync(compDir, { recursive: true });
     const helloVue = join(compDir, "Hello.vue");
@@ -60,7 +59,7 @@ defineProps<{ name: string }>();
   <p>Hello, {{ name }}!</p>
 </template>
 `);
-        console.log(`created ${join(defaultComponents, "Hello.vue")}`);
+        console.log(`created ${defaultComponents}/Hello.vue`);
     }
     const outDir = join(targetRoot, defaultOut);
     mkdirSync(outDir, { recursive: true });
@@ -104,7 +103,8 @@ function check(config, showDiff = false) {
                 console.error(unifiedDiff(`${config.out}/${name}`, committed(name), want.get(name)));
         }
         for (const name of extra) {
-            console.error(`not generated: ${config.out}/${name}`);
+            const foreign = isGenerated(join(dir, name)) ? "" : ` (not written by ferrovue, so \`ferrovue\` leaves it: move it out of ${config.out})`;
+            console.error(`not generated: ${config.out}/${name}${foreign}`);
             if (showDiff)
                 console.error(unifiedDiff(`${config.out}/${name}`, committed(name), ""));
         }
@@ -122,97 +122,96 @@ function once(config) {
     console.log(`${config.out}: ${files.length} files, ${what}`);
 }
 function watchProject(configPath) {
+    let inputs;
     const run = () => {
+        let config = null;
         try {
-            once(loadConfig(root, configPath));
+            config = load(configPath);
+            once(config);
         }
         catch (e) {
-            report(e);
+            // A refusal is reported as one; anything else (a folder renamed away, a file read as it is
+            // written) is shown too, and the watch carries on for the change that puts it right.
+            if (isRefusal(e))
+                report(e);
+            else
+                console.error(`error: ${e instanceof Error ? e.message : String(e)}`);
         }
-    };
-    run();
-    const ignored = (file) => {
-        let out = "";
-        try {
-            out = loadConfig(root, configPath).out;
-        }
-        catch {
+        finally {
+            inputs = inputsOf(root, configPath ?? CONFIG_FILE, config);
         }
-        const parts = file.split(sep);
-        return (parts.some((p) => p === "node_modules" || p === "target" || p === ".git" || p === "dist") ||
-            (out !== "" && (file === out || file.startsWith(out + sep))) ||
-            !/\.(vue|ts|json)$/.test(file));
     };
+    run();
     let timer = null;
-    watch(root, { recursive: true }, (_event, name) => {
-        if (!name || ignored(relative(root, join(root, name))))
+    // One recursive watch of the root, filtered to the inputs: watching each input directory instead
+    // would miss one created later, and the type files may be anywhere.
+    const watcher = watch(root, { recursive: true }, (_event, name) => {
+        if (!name || !affects(inputs, join(root, name)))
             return;
         if (timer)
             clearTimeout(timer);
         timer = setTimeout(run, 50);
     });
+    watcher.on("error", (e) => {
+        console.error(`error: stopped watching: ${e.message}`);
+        process.exitCode = 1;
+    });
     (json ? console.error : console.log)("watching for changes (Ctrl-C to stop)");
 }
 try {
-    const rawArgs = process.argv.slice(2);
-    let configPath;
-    const args = [];
-    for (let i = 0; i < rawArgs.length; i++) {
-        const arg = rawArgs[i];
-        if (arg === "-c" || arg === "--config") {
-            if (i + 1 >= rawArgs.length || rawArgs[i + 1].startsWith("-")) {
-                console.error(`error: option '${arg}' requires an argument`);
-                process.exit(1);
-            }
-            configPath = rawArgs[++i];
-        }
-        else if (arg.startsWith("--config=")) {
-            configPath = arg.slice("--config=".length);
-        }
-        else if (arg === "--format" || arg.startsWith("--format=")) {
-            const format = arg === "--format" ? rawArgs[++i] : arg.slice("--format=".length);
-            if (format !== "human" && format !== "json") {
-                console.error(`error: '--format' is 'human' or 'json'`);
-                process.exit(1);
-            }
-            json = format === "json";
-        }
-        else {
-            args.push(arg);
-        }
+    const parsed = parseArgs(process.argv.slice(2));
+    if ("error" in parsed) {
+        console.error(`error: ${parsed.error}`);
+        process.exit(1);
     }
-    const known = new Set(["init", "--check", "--diff", "-d", "--watch", "-v", "--version", "-h", "--help"]);
-    const unknown = args.find((a) => !known.has(a));
-    if (unknown !== undefined) {
-        console.error(`error: unknown option or command '${unknown}'\n\nRun \`ferrovue --help\` for usage.`);
+    const { command, options, spelt } = parsed;
+    const configPath = options.get("--config");
+    const format = options.get("--format");
+    if (format !== undefined && format !== "human" && format !== "json") {
+        console.error(`error: '--format' is 'human' or 'json'`);
         process.exit(1);
     }
-    if ((args.includes("--diff") || args.includes("-d")) && !args.includes("--check")) {
+    json = format === "json";
+    for (const w of parsed.warnings)
+        warn(w);
+    const conflict = (a, b) => {
+        console.error(`error: '${a}' does not combine with '${b}'`);
+        return process.exit(1);
+    };
+    if (command === "init") {
+        const other = ["--check", "--watch", "--diff"].find((o) => options.has(o));
+        if (other !== undefined)
+            conflict("init", spelt.get(other));
+        if (json)
+            conflict("init", "--format json");
+    }
+    if (options.has("--check") && options.has("--watch"))
+        conflict("--check", "--watch");
+    if (options.has("--diff") && !options.has("--check")) {
         console.error("error: '--diff' requires '--check'");
         process.exit(1);
     }
-    if ((args.includes("--diff") || args.includes("-d")) && json) {
+    if (options.has("--diff") && json) {
         console.error("error: '--diff' writes text, and does not combine with '--format json'");
         process.exit(1);
     }
-    if (args.includes("--version") || args.includes("-v")) {
+    if (options.has("--version")) {
         console.log(VERSION);
     }
-    else if (args.includes("--help") || args.includes("-h")) {
-        console.log(HELP.trimEnd());
+    else if (options.has("--help")) {
+        console.log(helpText());
     }
-    else if (args.includes("init")) {
+    else if (command === "init") {
         process.exitCode = initProject(root, configPath);
     }
-    else if (args.includes("--watch")) {
+    else if (options.has("--watch")) {
         watchProject(configPath);
     }
-    else if (args.includes("--check")) {
-        const showDiff = args.includes("--diff") || args.includes("-d");
-        process.exitCode = check(loadConfig(root, configPath), showDiff);
+    else if (options.has("--check")) {
+        process.exitCode = check(load(configPath), options.has("--diff"));
     }
     else {
-        once(loadConfig(root, configPath));
+        once(load(configPath));
     }
 }
 catch (e) {

package/dist/client-render.d.ts

@@ -0,0 +1,27 @@
+import { type App, type Plugin } from "vue";
+/** The DOM inside `container` as a client render is compared with the server's markup: comments
+ * left out, adjacent text joined and empty text dropped, a `class` attribute by the classes it
+ * holds, a `style` attribute by the declarations it holds (custom properties, which Vue's client
+ * sets for `v-bind()` in `<style>` after the others, by name in any order), and the state of a form control (an
+ * `<input>`'s `value` and `checked`, a `<textarea>`'s `value`, an `<option>`'s `selected`) by its
+ * property, which Vue's client sets where the server writes the attribute. */
+export declare function renderedShape(container: Element): string;
+/** `renderedShape` of markup as the browser parsed it, untouched since: an `<option>`'s state is
+ * the selection the HTML parser gives it, from the `selected` attributes (the last one in a single
+ * `<select>`, or its first enabled option without one), which happy-dom's property misreports. */
+export declare function parsedShape(container: Element): string;
+/** A plugin that takes what the app is mounted on, and its `renderedShape` as `mount` returns,
+ * before any update an `onMounted` hook scheduled has run. */
+export declare function shapeAtMount(): {
+    plugin: Plugin;
+    container: () => Element | undefined;
+    shape: () => string | undefined;
+};
+/** Set the custom properties `v-bind()` in `<style>` gives each component's root elements, as Vue's
+ * client sets them once mounted, where Vue's build does not set them itself (its Node build) and a
+ * component tells them through `getCssVars`, as `attachSsrRender` makes it. */
+export declare function applyCssVars(app: App): void;
+/** Where `app`, mounted on `container`, showed something other than `expected` (a
+ * `renderedShape`): as mounting left it (`atMount`), and, where that differs while async
+ * components are loading, once they have loaded. `null` where it agrees at either point. */
+export declare function renderDifference(app: App, container: Element, atMount: string, expected: string): Promise<string | null>;

package/dist/client-render.js

@@ -0,0 +1,171 @@
+import { normalizeCssVarValue } from "@vue/shared";
+import { Fragment, Static } from "vue";
+import { settled, stillLoading } from "./settle.js";
+const escapeText = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+const STATE_ATTRS = { INPUT: ["value", "checked"], TEXTAREA: ["value"], OPTION: ["selected"] };
+function selectOf(option) {
+    const parent = option.parentElement;
+    const select = parent?.tagName === "OPTGROUP" ? parent.parentElement : parent;
+    return select?.tagName === "SELECT" ? select : null;
+}
+function optionsOf(select) {
+    return [...select.children].flatMap((child) => (child.tagName === "OPTION" ? [child] : child.tagName === "OPTGROUP" ? [...child.children].filter((c) => c.tagName === "OPTION") : []));
+}
+function parsedSelected(option) {
+    const select = selectOf(option);
+    if (!select || select.hasAttribute("multiple") || Number(select.getAttribute("size")) > 1)
+        return option.hasAttribute("selected");
+    const options = optionsOf(select);
+    const disabled = (o) => o.hasAttribute("disabled") || (o.parentElement?.tagName === "OPTGROUP" && o.parentElement.hasAttribute("disabled"));
+    const chosen = options.findLast((o) => o.hasAttribute("selected")) ?? options.find((o) => !disabled(o));
+    return option === chosen;
+}
+function stateOf(el, name, parsed) {
+    if (parsed && el.tagName === "OPTION")
+        return parsedSelected(el);
+    return el[name];
+}
+function element(el, scratch, parsed) {
+    const state = STATE_ATTRS[el.tagName] ?? [];
+    const attrs = el
+        .getAttributeNames()
+        .filter((name) => name !== "style" && name !== "class" && !state.includes(name))
+        .toSorted()
+        .map((name) => ` ${name}=${JSON.stringify(el.getAttribute(name))}`);
+    const classes = [...new Set((el.getAttribute("class") ?? "").split(/[\t\n\f\r ]+/).filter(Boolean))].toSorted();
+    if (classes.length)
+        attrs.push(` class=${JSON.stringify(classes.join(" "))}`);
+    const style = styleShape(el.getAttribute("style") ?? "", scratch);
+    if (style)
+        attrs.push(` style=${JSON.stringify(style)}`);
+    for (const name of state)
+        attrs.push(` .${name}=${JSON.stringify(stateOf(el, name, parsed))}`);
+    const children = el.tagName === "TEXTAREA" ? "" : nodes(el.childNodes, scratch, parsed);
+    return `<${el.localName}${attrs.join("")}>${children}</${el.localName}>`;
+}
+function styleShape(text, scratch) {
+    scratch.setAttribute("style", text);
+    const { style } = scratch;
+    const own = [];
+    const custom = [];
+    for (let i = 0; i < style.length; i++) {
+        const name = style.item(i);
+        const declared = `${name.replace(/\\(.)/g, "$1")}: ${style.getPropertyValue(name).trim()}${style.getPropertyPriority(name) ? " !important" : ""};`;
+        (name.startsWith("--") ? custom : own).push(declared);
+    }
+    return [...own, ...custom.toSorted()].join(" ");
+}
+function nodes(list, scratch, parsed) {
+    let out = "";
+    let text = "";
+    for (const node of list) {
+        if (node.nodeType === 3) {
+            text += node.textContent ?? "";
+            continue;
+        }
+        if (node.nodeType !== 1)
+            continue;
+        out += escapeText(text) + element(node, scratch, parsed);
+        text = "";
+    }
+    return out + escapeText(text);
+}
+/** The DOM inside `container` as a client render is compared with the server's markup: comments
+ * left out, adjacent text joined and empty text dropped, a `class` attribute by the classes it
+ * holds, a `style` attribute by the declarations it holds (custom properties, which Vue's client
+ * sets for `v-bind()` in `<style>` after the others, by name in any order), and the state of a form control (an
+ * `<input>`'s `value` and `checked`, a `<textarea>`'s `value`, an `<option>`'s `selected`) by its
+ * property, which Vue's client sets where the server writes the attribute. */
+export function renderedShape(container) {
+    return nodes(container.childNodes, container.ownerDocument.createElement("div"), false);
+}
+/** `renderedShape` of markup as the browser parsed it, untouched since: an `<option>`'s state is
+ * the selection the HTML parser gives it, from the `selected` attributes (the last one in a single
+ * `<select>`, or its first enabled option without one), which happy-dom's property misreports. */
+export function parsedShape(container) {
+    return nodes(container.childNodes, container.ownerDocument.createElement("div"), true);
+}
+/** A plugin that takes what the app is mounted on, and its `renderedShape` as `mount` returns,
+ * before any update an `onMounted` hook scheduled has run. */
+export function shapeAtMount() {
+    let container;
+    let shape;
+    const plugin = {
+        install(app) {
+            const mount = app.mount.bind(app);
+            app.mount = (...args) => {
+                const root = mount(...args);
+                const [target] = args;
+                container = (typeof target === "string" ? document.querySelector(target) : target);
+                shape = renderedShape(container);
+                return root;
+            };
+        },
+    };
+    return { plugin, container: () => container, shape: () => shape };
+}
+function setVarsOnNode(node, vars) {
+    if (node.nodeType !== 1)
+        return;
+    for (const key in vars)
+        node.style.setProperty(`--${key}`, normalizeCssVarValue(vars[key]));
+}
+function setVarsOnVNode(vnode, vars) {
+    let at = vnode && vnode.shapeFlag & 128 ? (vnode.suspense?.activeBranch ?? null) : vnode;
+    while (at?.component)
+        at = at.component.subTree;
+    if (!at)
+        return;
+    if (at.shapeFlag & 1 && at.el)
+        setVarsOnNode(at.el, vars);
+    else if (at.type === Fragment && Array.isArray(at.children))
+        for (const c of at.children)
+            setVarsOnVNode(c, vars);
+    else if (at.type === Static) {
+        for (let el = at.el; el; el = el.nextSibling) {
+            setVarsOnNode(el, vars);
+            if (el === at.anchor)
+                break;
+        }
+    }
+}
+function eachInstance(vnode, visit) {
+    if (!vnode)
+        return;
+    if (vnode.component) {
+        visit(vnode.component);
+        eachInstance(vnode.component.subTree, visit);
+    }
+    if (vnode.shapeFlag & 128)
+        eachInstance(vnode.suspense?.activeBranch ?? null, visit);
+    if (Array.isArray(vnode.children))
+        for (const c of vnode.children)
+            if (c && typeof c === "object")
+                eachInstance(c, visit);
+}
+/** Set the custom properties `v-bind()` in `<style>` gives each component's root elements, as Vue's
+ * client sets them once mounted, where Vue's build does not set them itself (its Node build) and a
+ * component tells them through `getCssVars`, as `attachSsrRender` makes it. */
+export function applyCssVars(app) {
+    const root = app._instance;
+    if (!root)
+        return;
+    const visit = (instance) => {
+        if (instance.getCssVars)
+            setVarsOnVNode(instance.subTree, instance.getCssVars());
+    };
+    visit(root);
+    eachInstance(root.subTree, visit);
+}
+/** Where `app`, mounted on `container`, showed something other than `expected` (a
+ * `renderedShape`): as mounting left it (`atMount`), and, where that differs while async
+ * components are loading, once they have loaded. `null` where it agrees at either point. */
+export async function renderDifference(app, container, atMount, expected) {
+    let shown = atMount;
+    if (shown !== expected && stillLoading(app)) {
+        await settled(app);
+        applyCssVars(app);
+        shown = renderedShape(container);
+    }
+    return shown === expected ? null : `the client renders it differently:\n  server: ${expected}\n  client: ${shown}`;
+}

package/dist/client.d.ts

@@ -1,9 +1,39 @@
 import { type App, type Component, type Plugin } from "vue";
 import type { Pinia } from "pinia";
 import type { Router } from "vue-router";
+/** The state of a page already read: the text of its state's script, as `readPage` gives it. */
+export interface StateText {
+    text: string | undefined;
+}
 /** Give Pinia the state the server rendered with (what `ferrovue::state_script_into` wrote) before
- * the app mounts, so every store starts from it and the hydrated markup agrees with the server's. */
-export declare function hydrateState(pinia: Pinia, id?: string, doc?: Document): void;
+ * the app mounts, so every store starts from it and the markup agrees with the server's. The state
+ * is read from the script with the `id` given (`__pinia` by default) in `doc`, or given as
+ * `{ text }`: the `state` of a fetched page that `readPage` read. Either way the numbers JSON
+ * cannot carry (`NaN`, `Infinity`) are read back. Pinia is left alone when there is no state. */
+export declare function hydrateState(pinia: Pinia, from?: string | StateText, doc?: Document): void;
+/** The `id`s of the scripts `readPage` reads. */
+export interface ReadPageOptions {
+    /** The `id` of the record's script, as given to `PageRecord::script_into`: `__fv_page` by default. */
+    record?: string;
+    /** The `id` of the state's script, as given to `ferrovue::state_script_into`: `__pinia` by default. */
+    state?: string;
+}
+/** A page read out of the HTML of its document. */
+export interface ReadPage {
+    /** The record `ferrovue::PageRecord` wrote, with the numbers JSON cannot carry read back. */
+    record: PageRecord;
+    /** The text of the state's script, for `hydrateState(pinia, { text: state })`: `undefined` when
+     * the page carries no state. */
+    state: string | undefined;
+}
+/** Read the record and the state of a page out of the HTML of its document, as a navigation that
+ * fetches the next page receives it. It needs no `DOMParser`, so it also runs in a worker and on a
+ * server. Each script is the one the browser's `getElementById` would find in the parsed document:
+ * the first `<script>` with that `id` outside a `<template>`, an `<svg>` and a `<math>`, with
+ * comments, attribute values and the text of `<script>`, `<style>`, `<textarea>`, `<title>` and the
+ * other raw-text elements passed over as the HTML parser passes over them. Throws when the page
+ * carries no record. */
+export declare function readPage(html: string, options?: ReadPageOptions): ReadPage;
 export interface MountOptions {
     /** One Pinia for every island, so they share stores. Call `hydrateState` on it first. */
     pinia?: Pinia;
@@ -52,11 +82,13 @@ export declare const ClientOnly: Component;
  * it: its name (`c`) and the props it was rendered from (`p`). */
 export interface PagePart {
     c: string;
-    p: Record<string, unknown>;
+    /** `null` where serde_json refused the props, which the part then renders without. */
+    p: Record<string, unknown> | null;
 }
 /** What `ferrovue::PageRecord` writes: the layout's props, and each slot's parts in order. */
 export interface PageRecord {
-    props: Record<string, unknown>;
+    /** `null` where serde_json refused the props, which the layout then renders without. */
+    props: Record<string, unknown> | null;
     slots: Record<string, PagePart[]>;
 }
 export interface PageOptions extends Pick<MountOptions, "pinia" | "router" | "plugins"> {
@@ -67,12 +99,39 @@ export interface PageOptions extends Pick<MountOptions, "pinia" | "router" | "pl
     /** The document to read the page from. */
     doc?: Document;
 }
+export interface PageAppOptions extends Pick<MountOptions, "pinia" | "router" | "plugins"> {
+    /** `false` for an app that renders the page from its record into an empty container, as
+     * `renderPage` does, in place of hydrating the server's markup. */
+    hydrate?: boolean;
+}
 /** The app of a page: its root renders `layout` with the record's props, and each slot as the
  * components the record names, in order, as a plain array, which hydrates the markup the server
- * wrote with no fragment of its own. `components` must hold every component the record names. */
-export declare function createPageApp(layout: Component, record: PageRecord, components: Record<string, Component>, options?: PageOptions): App;
+ * wrote with no fragment of its own. With `hydrate: false` the same tree is rendered from scratch,
+ * so the first page and every page shown after it are one shape of app. `components` must hold
+ * every component the record names. */
+export declare function createPageApp(layout: Component, record: PageRecord, components: Record<string, Component>, options?: PageAppOptions): App;
 /** Hydrate a page `ferrovue::Page` rendered: read its record, load the components it names (and
  * no others), wait for the router, and mount the layout on the container. Rejects, leaving the page
  * as the server rendered it, when the container or the record is missing or a component is not
  * given or does not load. */
 export declare function mountPage(layout: IslandComponent, components: Record<string, IslandComponent>, options?: PageOptions): Promise<App>;
+export interface RenderPageOptions extends Pick<MountOptions, "pinia" | "router" | "plugins"> {
+    /** The element holding the page shown now, or a selector for it: `#app` by default. */
+    container?: Element | string;
+    /** What shows the page now: the app `mountPage` or `renderPage` returned, or the islands
+     * `mountIslands` mounted. It is unmounted once the next page is mounted. */
+    previous?: {
+        unmount(): void;
+    } | undefined;
+    /** The document the container is in. */
+    doc?: Document;
+}
+/** Show the next page of a navigation from its record, as `readPage` read it out of the fetched
+ * document: load the components it names (and no others), render the app `createPageApp` builds
+ * with `hydrate: false` into a copy of the container with no children, wait for the router, put the
+ * copy in the container's place, mount, and then unmount `previous`. The next app is mounted
+ * before the previous one is unmounted, so a router both use stays started. `router` must be at the
+ * next page's location: `linkRouter` with the `location` the navigation goes to. Rejects, leaving
+ * the page shown as it is, when the container is missing or a component is not given or does not
+ * load. */
+export declare function renderPage(layout: IslandComponent, components: Record<string, IslandComponent>, record: PageRecord, options?: RenderPageOptions): Promise<App>;