ferrovue 0.4.0 → 0.5.0

package/dist/expr.js

@@ -1,4 +1,4 @@
-import { BOOL, fail, FLOAT, GenError, INT, opt, rustStr, sameTy, snake, STR, UNDEF } from "./model.js";
+import { absence, BOOL, fail, FLOAT, GenError, INT, joinAbsence, nothing, NULL, opt, rustStr, sameTy, snake, STR, UNDEF, withAbsence } from "./model.js";
 import { ctx } from "./context.js";
 import { lookupStruct, markHome } from "./typescript.js";
 import { claim } from "./plugin.js";
@@ -6,8 +6,9 @@ import { atom, bare, binary, enclosed, logical, negate, not, occurrences, strArg
 import { collected } from "./lists.js";
 import { asCow, formatted, isTemporary, loneOf, meet, stringsEqual } from "./strings.js";
 import { arithmetic, asF64, compare, intFromF64, isNumber, negatedOrder, numberVal } from "./numbers.js";
-import { boolOf, choice, known, narrowing, narrowTo, pathOf, presence, truthy } from "./narrowing.js";
+import { boolOf, checkNullTest, choice, known, narrowing, narrowTo, nullTest, pathOf, presence, truthy } from "./narrowing.js";
 import { call, isObjectCall } from "./calls.js";
+import { constOf, constVal } from "./constants.js";
 export function describeTy(ty) {
     switch (ty.k) {
         case "str":
@@ -26,20 +27,26 @@ export function describeTy(ty) {
         case "child":
             return "an object";
         case "opt":
+            if (ty.none === "null")
+                return `${describeTy(ty.of)} or \`null\``;
+            if (ty.none === "either")
+                return `${describeTy(ty.of)}, \`null\` or \`undefined\``;
             return `an optional ${describeTy(ty.of).replace(/^an? /, "")}`;
         case "undef":
             return "`undefined`";
+        case "null":
+            return "`null`";
         default:
             return claim((p) => p.values?.describe?.(ty)) ?? "a value of another kind";
     }
 }
 export function fieldVal(comp, base, ty, js, node) {
     if (ty.k !== "struct")
-        fail(comp, `\`.${js}\` on a value that is not an object`, node);
+        fail(comp, "FV0604", `\`.${js}\` on a value that is not an object`, node);
     const { st, owner } = lookupStruct(comp, ty);
     const found = st?.fields.find((x) => x.js === js);
     if (!found)
-        fail(comp, `\`${ty.name}\` has no field \`${js}\``, node);
+        fail(comp, "FV0605", `\`${ty.name}\` has no field \`${js}\``, node);
     const f = owner === comp ? found : { ...found, ty: markHome(found.ty, owner.name) };
     if (st.slot)
         return { code: `${base}.${f.rust}`, ty: f.ty };
@@ -70,25 +77,49 @@ export function fieldVal(comp, base, ty, js, node) {
             return { code: place, ty: f.ty };
     }
 }
+export function holdsNothing(comp, v, want, node, where) {
+    const has = absence(v.ty);
+    if (has === null)
+        return;
+    const takes = absence(want);
+    if (takes === has || takes === "either")
+        return;
+    const is = has === "either" ? "may be `null` or `undefined`" : has === "null" ? "may be `null`" : "may be `undefined`";
+    const fix = takes === null ? "narrow it with `v-if` first" : takes === "null" ? "write `?? null` after it" : "write `?? undefined` after it";
+    fail(comp, "FV0606", `a value that ${is} where ${where} takes ${describeTy(want)}, which Vue would hand it as it is: ${fix}`, node);
+}
 export function coerce(comp, v, want, node) {
     if (sameTy(v.ty, want))
         return v.code;
-    if (want.k === "opt" && v.ty.k === "undef")
+    holdsNothing(comp, v, want, node, "the function");
+    if (want.k === "opt" && nothing(v.ty))
         return "None";
+    if (want.k === "opt" && v.ty.k === "opt" && sameTy(v.ty.of, want.of))
+        return v.code;
     if (want.k === "opt" && sameTy(v.ty, want.of))
         return `Some(${bare(v.code)})`;
     if (want.k === "float" && v.ty.k === "int")
         return asF64(v);
     if (want.k === "opt" && want.of.k === "float" && v.ty.k === "int")
         return `Some(${asF64(v)})`;
-    return fail(comp, `a ${JSON.stringify(v.ty)} where ${JSON.stringify(want)} is expected`, node);
+    return fail(comp, "FV0607", `a ${JSON.stringify(v.ty)} where ${JSON.stringify(want)} is expected`, node);
 }
 export function childOf(name) {
     const c = ctx.components.get(name);
     if (!c)
-        throw new GenError(`\`Props\` is imported from ${name}.vue, which is not among the components compiled`);
+        throw new GenError("FV0512", `\`Props\` is imported from ${name}.vue, which is not among the components compiled`);
     return c;
 }
+function slotsObject(s, n) {
+    if (n.type === "Identifier")
+        return n.name === "$slots" || (s.slotsBindings.has(n.name) && !s.locals.has(n.name)) ? n.name : null;
+    if (n.type !== "MemberExpression" || n.computed || n.object.type !== "Identifier")
+        return null;
+    const [owner, name] = [n.object.name, n.property.name];
+    if (owner === "_ctx" && name === "$slots")
+        return "$slots";
+    return (owner === "$setup" || owner === "_ctx") && s.slotsBindings.has(name) ? name : null;
+}
 export function expr(s, n) {
     const comp = s.comp;
     const path = pathOf(n);
@@ -97,6 +128,9 @@ export function expr(s, n) {
         if (narrowed)
             return narrowed;
     }
+    const named = constOf(s, n);
+    if (named)
+        return constVal(named.c, { comp, node: n, what: named.what });
     if (n.type === "MemberExpression" && !n.computed && n.property.type === "Identifier" && n.property.name === "length") {
         if (isObjectCall(n.object, "entries") && n.object.arguments.length === 1) {
             const r = expr(s, n.object.arguments[0]);
@@ -129,7 +163,7 @@ export function expr(s, n) {
         }
         if (isNumber(a.ty) && isNumber(b.ty))
             return arithmetic(a, "+", b, a.ty.k === "int" && b.ty.k === "int");
-        return fail(comp, "`+` joins a string to a string or a number, or adds two numbers", n);
+        return fail(comp, "FV0608", "`+` joins a string to a string or a number, or adds two numbers", n);
     }
     if (n.type === "BinaryExpression" && ["-", "*", "%", "/", "<", ">", "<=", ">="].includes(n.operator)) {
         const a = expr(s, n.left);
@@ -145,7 +179,7 @@ export function expr(s, n) {
                 ? "narrow an optional one with `v-if` first"
                 : `the other is ${describeTy(isNumber(a.ty) ? b.ty : a.ty)}`;
             const between = comparison ? "two numbers, or two strings," : "two numbers";
-            return fail(comp, `\`${n.operator}\` is supported between ${between} that are present: ${why}`, n);
+            return fail(comp, "FV0609", `\`${n.operator}\` is supported between ${between} that are present: ${why}`, n);
         }
         if (["<", ">", "<=", ">="].includes(n.operator))
             return compare(a, n.operator, b);
@@ -168,24 +202,26 @@ export function expr(s, n) {
                 return { code: "[]", ty: { k: "list", of: UNDEF } };
             const values = n.elements.map((el) => {
                 if (!el || el.type === "SpreadElement")
-                    fail(comp, "an array literal holds plain values", n);
+                    fail(comp, "FV0610", "an array literal holds plain values", n);
                 return expr(s, el);
             });
             const of = values[0].ty;
             if (!(of.k === "str" || of.k === "int" || of.k === "float" || of.k === "bool") || values.some((v) => !sameTy(v.ty, of))) {
-                fail(comp, "an array literal holds strings, numbers or booleans, all of one type", n);
+                fail(comp, "FV0611", "an array literal holds strings, numbers or booleans, all of one type", n);
             }
             return { code: `[${values.map((v) => bare(v.code)).join(", ")}]`, ty: { k: "list", of }, ...loneOf(...values) };
         }
         case "OptionalMemberExpression": {
             if (n.computed)
-                return fail(comp, "computed member access", n);
+                return fail(comp, "FV0612", "computed member access", n);
             const base = expr(s, n.object);
+            if (nothing(base.ty))
+                return { code: "None", ty: UNDEF };
             if (base.ty.k !== "opt")
                 return fieldVal(comp, base.code, base.ty, n.property.name, n);
             const f = fieldVal(comp, "v", base.ty.of, n.property.name, n);
             if (f.ty.k === "opt")
-                return { code: `${atom(base.code)}.and_then(|v| ${f.code})`, ty: f.ty };
+                return { code: `${atom(base.code)}.and_then(|v| ${f.code})`, ty: opt(f.ty) };
             return { code: `${atom(base.code)}.map(|v| ${f.code})`, ty: opt(f.ty) };
         }
         case "StringLiteral":
@@ -195,7 +231,7 @@ export function expr(s, n) {
         case "BooleanLiteral":
             return { code: String(n.value), ty: BOOL, konst: n.value };
         case "NullLiteral":
-            return fail(comp, "`null`: compare with `undefined`, which is what an absent prop is", n);
+            return { code: "None", ty: NULL };
         case "Identifier": {
             if (n.name === "undefined")
                 return { code: "None", ty: UNDEF };
@@ -203,11 +239,11 @@ export function expr(s, n) {
             if (local)
                 return local;
             if (s.clientOnly.has(n.name)) {
-                return fail(comp, `\`${n.name}\` is set up in a way the server cannot evaluate: ${s.clientOnly.get(n.name)}`, n);
+                return fail(comp, "FV0613", `\`${n.name}\` is set up in a way the server cannot evaluate: ${s.clientOnly.get(n.name)}`, n);
             }
             if (n.name === s.propsIdent)
                 return { code: "props", ty: { k: "struct", name: "Props" } };
-            return fail(comp, `\`${n.name}\` is not available when rendering on the server`, n);
+            return fail(comp, "FV0601", `\`${n.name}\` is not available when rendering on the server`, n);
         }
         case "MemberExpression": {
             if (!n.computed && n.property.name === "value" && n.object.type === "Identifier" && s.refs.has(n.object.name) && !s.locals.has(n.object.name)) {
@@ -223,15 +259,13 @@ export function expr(s, n) {
                     if (own)
                         return own;
                 }
-                return fail(comp, "computed member access", n);
+                return fail(comp, "FV0612", "computed member access", n);
             }
             const prop = n.property.name;
-            const slotsObject = (n.object.type === "Identifier" && n.object.name === "$slots") ||
-                (n.object.type === "MemberExpression" && !n.object.computed && n.object.object.type === "Identifier" &&
-                    n.object.object.name === "_ctx" && n.object.property.name === "$slots");
-            if (slotsObject) {
+            const slots = slotsObject(s, n.object);
+            if (slots !== null) {
                 if (!comp.slotNames.includes(prop))
-                    fail(comp, `\`$slots.${prop}\` names a slot this template does not render`, n);
+                    fail(comp, "FV0907", `\`${slots}.${prop}\` names a slot this template does not render`, n);
                 return { code: `fv_slots.${snake(prop)}.is_some()`, ty: BOOL };
             }
             if (n.object.type === "Identifier") {
@@ -244,18 +278,20 @@ export function expr(s, n) {
                         if (global)
                             return global;
                         if (n.object.name === "_ctx" && prop === "$attrs") {
-                            return fail(comp, "`$attrs` is bound whole, with `v-bind=\"$attrs\"`; a value read from it has no type: declare it as a prop", n);
+                            return fail(comp, "FV0415", "`$attrs` is bound whole, with `v-bind=\"$attrs\"`; a value read from it has no type: declare it as a prop", n);
                         }
                         const v = s.setup.get(prop);
                         if (v)
                             return v;
+                        if (prop === s.propsIdent)
+                            return { code: "props", ty: { k: "struct", name: "Props" } };
                         if (s.clientOnly.has(prop)) {
-                            return fail(comp, `\`${prop}\` is set up in a way the server cannot evaluate: ${s.clientOnly.get(prop)}`, n);
+                            return fail(comp, "FV0613", `\`${prop}\` is set up in a way the server cannot evaluate: ${s.clientOnly.get(prop)}`, n);
                         }
                         if (n.object.name === "_ctx" && comp.props.fields.some((f) => f.js === prop)) {
                             return fieldVal(comp, "props", { k: "struct", name: "Props" }, prop, n);
                         }
-                        return fail(comp, `\`${prop}\` is not available when rendering on the server`, n);
+                        return fail(comp, "FV0601", `\`${prop}\` is not available when rendering on the server`, n);
                     }
                 }
             }
@@ -272,7 +308,7 @@ export function expr(s, n) {
                     const code = narrowing(s, p, (inner) => (right = expr(inner, n.right)).code, () => String(n.operator === "||"));
                     if (right?.ty.k === "bool")
                         return { code, ty: BOOL };
-                    return fail(comp, `\`${n.operator}\` is supported between booleans only`, n);
+                    return fail(comp, "FV0614", `\`${n.operator}\` is supported between booleans only`, n);
                 }
             }
             const a = expr(s, n.left);
@@ -281,12 +317,14 @@ export function expr(s, n) {
                 const own = claim((p) => p.values?.nullish?.(s, a, b, n));
                 if (own)
                     return own;
+                if (nothing(a.ty))
+                    return b;
                 if (a.ty.k !== "opt")
                     return a;
-                if (b.ty.k === "undef")
-                    return a;
+                if (nothing(b.ty))
+                    return { ...a, ty: withAbsence(a.ty.of, absence(b.ty)) };
                 if (b.iter !== undefined)
-                    fail(comp, "`??` falling back to a computed list", n);
+                    fail(comp, "FV0615", "`??` falling back to a computed list", n);
                 if (a.held !== undefined && b.ty.k === "str")
                     return { code: `&*${atom(a.held)}.unwrap_or(${asCow(b)})`, ty: STR, ...loneOf(a, b) };
                 if (a.ty.of.k === "str" && b.ty.k === "str" && isTemporary(b)) {
@@ -294,13 +332,13 @@ export function expr(s, n) {
                 }
                 if (sameTy(a.ty.of, b.ty))
                     return { code: `${atom(a.code)}.unwrap_or(${bare(b.code)})`, ty: b.ty, ...loneOf(a, b) };
-                if (sameTy(a.ty, b.ty))
-                    return { code: `${atom(a.code)}.or(${bare(b.code)})`, ty: a.ty, ...loneOf(a, b) };
+                if (b.ty.k === "opt" && sameTy(a.ty.of, b.ty.of))
+                    return { code: `${atom(a.code)}.or(${bare(b.code)})`, ty: b.ty, ...loneOf(a, b) };
                 if (a.ty.of.k === "float" && b.ty.k === "int")
                     return { code: `${atom(a.code)}.unwrap_or(${bare(asF64(b))})`, ty: FLOAT };
                 if (a.ty.of.k === "int" && b.ty.k === "float")
                     return { code: `${atom(a.code)}.map(|v| v as f64).unwrap_or(${bare(b.code)})`, ty: FLOAT };
-                return fail(comp, "`??` between different types", n);
+                return fail(comp, "FV0616", "`??` between different types", n);
             }
             if (n.operator === "||") {
                 if (a.ty.k === "bool" && b.ty.k === "bool")
@@ -322,11 +360,11 @@ export function expr(s, n) {
                     const otherwise = a.ty.k === "str" ? strArg(b.code) : bare(b.code);
                     return { code: `{ let a = ${bare(a.code)}; if ${truthy({ code: "a", ty: a.ty })} { a } else { ${otherwise} } }`, ty: a.ty, ...loneOf(a, b) };
                 }
-                return fail(comp, "`||` between these types", n);
+                return fail(comp, "FV0617", "`||` between these types", n);
             }
             if (n.operator === "&&" && a.ty.k === "bool" && b.ty.k === "bool")
                 return boolOf(logical(a.code, "&&", b.code));
-            return fail(comp, `\`${n.operator}\` is supported between booleans only`, n);
+            return fail(comp, "FV0614", `\`${n.operator}\` is supported between booleans only`, n);
         }
         case "UnaryExpression":
             if (n.operator === "!") {
@@ -341,13 +379,32 @@ export function expr(s, n) {
                 if (a.ty.k === "float")
                     return { code: negate(a.code), ty: FLOAT };
             }
-            return fail(comp, `unary \`${n.operator}\``, n);
+            return fail(comp, "FV0618", `unary \`${n.operator}\``, n);
         case "BinaryExpression": {
-            if (n.operator !== "===" && n.operator !== "!==")
-                fail(comp, `\`${n.operator}\``, n);
+            const test = nullTest(n);
+            if (n.operator !== "===" && n.operator !== "!==" && !test)
+                fail(comp, "FV0619", `\`${n.operator}\`: \`==\` and \`!=\` compare with \`null\` or \`undefined\` only; use \`===\``, n);
             const whole = claim((p) => p.equality?.(s, n));
             if (whole)
                 return whole;
+            if (test) {
+                const v = expr(s, test.target);
+                const none = absence(v.ty);
+                if (v.ty.k === "opt") {
+                    checkNullTest(s, test, v);
+                    const is = `${atom(v.code)}.is_none()`;
+                    return boolOf(test.is ? is : not(is));
+                }
+                if (none !== null) {
+                    const konst = (!test.strict || none === test.literal) === test.is;
+                    return { code: String(konst), ty: BOOL, konst };
+                }
+                if (!test.strict && claim((p) => p.values?.describe?.(v.ty)) === undefined) {
+                    return { code: String(!test.is), ty: BOOL, konst: !test.is };
+                }
+                if (!test.strict)
+                    fail(comp, "FV0620", `\`${n.operator}\` of ${describeTy(v.ty)}: compare with \`${test.is ? "===" : "!=="} undefined\``, n);
+            }
             const a = expr(s, n.left);
             const b = expr(s, n.right);
             let eq;
@@ -358,11 +415,16 @@ export function expr(s, n) {
             const own = claim((p) => p.values?.equals?.(a, b));
             if (own !== undefined)
                 eq = own;
-            else if (b.ty.k === "undef" && a.ty.k === "opt")
-                eq = `${atom(a.code)}.is_none()`;
-            else if (a.ty.k === "undef" && b.ty.k === "opt")
-                eq = `${atom(b.code)}.is_none()`;
-            else if (a.ty.k === "undef" || b.ty.k === "undef") {
+            else if ((nothing(b.ty) && a.ty.k === "opt") || (nothing(a.ty) && b.ty.k === "opt")) {
+                const [v, literal] = a.ty.k === "opt" ? [a, b] : [b, a];
+                checkNullTest(s, { target: n, literal: literal.ty.k === "null" ? "null" : "undefined", strict: true, is: n.operator === "===" }, v);
+                eq = `${atom(v.code)}.is_none()`;
+            }
+            else if (nothing(a.ty) || nothing(b.ty)) {
+                const other = nothing(a.ty) ? b.ty : a.ty;
+                const opaque = nothing(other) ? undefined : claim((p) => p.values?.describe?.(other));
+                if (opaque !== undefined)
+                    fail(comp, "FV0621", `\`${n.operator}\` between ${opaque} and ${describeTy(nothing(a.ty) ? a.ty : b.ty)}`, n);
                 const same = a.ty.k === b.ty.k;
                 const konst = n.operator === "===" ? same : !same;
                 return { code: String(konst), ty: BOOL, konst };
@@ -383,7 +445,7 @@ export function expr(s, n) {
             else if (b.ty.k === "opt" && sameTy(b.ty.of, a.ty) && scalar(a.ty))
                 eq = binary(`Some(${bare(a.code)})`, "==", b.code);
             else
-                return fail(comp, "`===` between these types", n);
+                return fail(comp, "FV0622", "`===` between these types", n);
             return boolOf(n.operator === "===" ? eq : not(eq));
         }
         case "ConditionalExpression": {
@@ -406,6 +468,8 @@ export function expr(s, n) {
                     return p.option;
                 if (present === name)
                     return `${atom(p.option)}.unwrap_or(${absent})`;
+                if (absent === "None" && present.startsWith("Some(") && enclosed(present.slice(4)))
+                    return `${atom(p.option)}.map(|${name}| ${bare(present.slice(5, -1))})`;
                 if (occurrences(present, name))
                     return `if ${p.pattern(name)} { ${present} } else { ${absent} }`;
                 return choice(p.present, present, absent);
@@ -418,15 +482,18 @@ export function expr(s, n) {
                 const both = `(${choose(collected(a), collected(b))})`;
                 return { code: both, ty: a.ty, iter: `${both}.into_iter()`, ...lone };
             }
-            const optStr = (v) => v.ty.k === "undef" || (v.ty.k === "opt" && v.ty.of.k === "str") || v.ty.k === "str";
+            const optStr = (v) => nothing(v.ty) || (v.ty.k === "opt" && v.ty.of.k === "str") || v.ty.k === "str";
             if (sameTy(a.ty, b.ty) && a.ty.k !== "opt")
                 return { code: choose(a.code, b.code), ty: a.ty, ...lone };
             if (isNumber(a.ty) && isNumber(b.ty))
                 return { code: choose(asF64(a), asF64(b)), ty: FLOAT };
-            if (sameTy(a.ty, b.ty) || a.ty.k === "undef" || b.ty.k === "undef" || (a.ty.k === "opt" && sameTy(a.ty.of, b.ty)) || (b.ty.k === "opt" && sameTy(b.ty.of, a.ty))) {
-                const ty = opt(a.ty.k === "undef" || b.ty.k === "opt" ? b.ty : a.ty);
+            const base = (ty) => (ty.k === "opt" ? ty.of : nothing(ty) ? null : ty);
+            const [baseA, baseB] = [base(a.ty), base(b.ty)];
+            const of = baseA ?? baseB;
+            if (of !== null && (baseA === null || baseB === null || sameTy(baseA, baseB))) {
+                const ty = withAbsence(of, joinAbsence(absence(a.ty), absence(b.ty)));
                 if (optStr(a) && optStr(b) && (isTemporary(a) || isTemporary(b) || a.held !== undefined || b.held !== undefined)) {
-                    const held = (v) => v.held ?? (v.ty.k === "undef" ? "None" : v.ty.k === "opt" ? `${atom(v.code)}.map(std::borrow::Cow::<str>::Borrowed)` : `Some(${asCow(v)})`);
+                    const held = (v) => v.held ?? (nothing(v.ty) ? "None" : v.ty.k === "opt" ? `${atom(v.code)}.map(std::borrow::Cow::<str>::Borrowed)` : `Some(${asCow(v)})`);
                     const both = atom(choose(held(a), held(b)));
                     return { code: `${both}.as_deref()`, ty, held: both, ...lone };
                 }
@@ -434,9 +501,13 @@ export function expr(s, n) {
                     return { code: choose(a.code, b.code), ty: a.ty, ...lone };
                 return { code: choose(coerce(comp, a, ty, n), coerce(comp, b, ty, n)), ty, ...lone };
             }
-            return fail(comp, "the two branches of `?:` differ in type", n);
+            return fail(comp, "FV0623", "the two branches of `?:` differ in type", n);
+        }
+        case "NewExpression": {
+            const made = n.callee.type === "Identifier" ? n.callee.name : n.callee.type === "MemberExpression" && !n.callee.computed ? `${n.callee.object.name ?? "…"}.${n.callee.property.name}` : "…";
+            return fail(comp, "FV0624", `\`new ${made}(…)\` builds an object the server has no twin for: compute the value in Rust and pass it as a prop`, n);
         }
         default:
-            return fail(comp, `\`${n.type}\` is not supported in an island template`, n);
+            return fail(comp, "FV0625", `\`${n.type}\` is not supported in a template`, n);
     }
 }

package/dist/fixture.d.ts

@@ -1,5 +1,6 @@
 import { type App, type Component } from "vue";
-import type { RouteRecordRaw } from "vue-router";
+import { type RouteEntry } from "./routes.ts";
+export { routeRecords, type RouteEntry } from "./routes.ts";
 /** A conformance fixture: the props, and `$slots`, `$route`, `$stores` and `$locale`. */
 export interface Fixture {
     props: Record<string, unknown>;
@@ -11,12 +12,6 @@ export interface Fixture {
 }
 /** A fixture's JSON, split into the props and the rest. */
 export declare function readFixture(json: Record<string, unknown>): Fixture;
-/** A route as a routes file lists it: a path, or a path and a name. */
-export type RouteEntry = string | {
-    path: string;
-    name?: string;
-    children?: RouteEntry[];
-};
 /** The router options ferrovue reproduces, as the project's configuration gives them. */
 export interface RouterOptions {
     base?: string;
@@ -29,11 +24,9 @@ export interface RouterOptions {
         locale: string;
         fallbackLocale?: string | string[];
     };
-    /** Render on the client with `createApp`, rather than hydrate what the server rendered: the scope
+    /** Render on the client from scratch with `createApp`: the scope
      * ids a fresh client render writes, which the server's must equal for scoped styles to apply. */
     client?: boolean;
 }
-/** Route records for vue-router, every route — nested ones too — given the fixture's view. */
-export declare function routeRecords(routes: RouteEntry[], View: Component): RouteRecordRaw[];
 /** An app rendering one fixture of `component`: with a router over `routes` when there are any. */
 export declare function fixtureApp(component: Component, fixture: Fixture, routes: RouteEntry[] | null, options?: RouterOptions): Promise<App>;

package/dist/fixture.js

@@ -1,4 +1,6 @@
 import { createApp, createSSRApp, createStaticVNode, defineComponent, h } from "vue";
+import { routeRecords } from "./routes.js";
+export { routeRecords } from "./routes.js";
 /** A fixture's JSON, split into the props and the rest. */
 export function readFixture(json) {
     const { $slots, $route, $stores, $locale, ...props } = json;
@@ -45,12 +47,6 @@ async function optionalPinia(stores) {
         return null;
     }
 }
-/** Route records for vue-router, every route — nested ones too — given the fixture's view. */
-export function routeRecords(routes, View) {
-    return routes.map((r) => typeof r === "string"
-        ? { path: r, component: View }
-        : { path: r.path, component: View, ...(r.name ? { name: r.name } : {}), ...(r.children ? { children: routeRecords(r.children, View) } : {}) });
-}
 /** An app rendering one fixture of `component`: with a router over `routes` when there are any. */
 export async function fixtureApp(component, fixture, routes, options = {}) {
     const slots = Object.fromEntries(Object.entries(fixture.slots)

package/dist/hydration.d.ts

@@ -0,0 +1,15 @@
+import type { App, Component } from "vue";
+import { type IslandComponent, type PageOptions, type PageRecord } from "./client.ts";
+/** A page as the server wrote it: `html` holds the container and, unless `record` is given, the
+ * record's script. */
+export interface RecordedPage {
+    html: string;
+    record?: PageRecord;
+}
+/** Put a recorded page into the document's body and hydrate it with `mountPage`, throwing on a
+ * node Vue replaced, on any change hydrating made to the markup (a `style` attribute is compared by
+ * the declarations it holds), and on anything Vue warns or logs as an error until the page has
+ * settled. The markup is compared as hydrating leaves it; what changes once the page is mounted,
+ * such as a `<ClientOnly>` showing its content or an async component loading, is the app's to
+ * change. Resolves to the app, mounted and settled. */
+export declare function hydrateRecordedPage(page: RecordedPage, layout: Component, components: Record<string, IslandComponent>, options?: PageOptions): Promise<App>;

package/dist/hydration.js

@@ -0,0 +1,80 @@
+import { mountPage } from "./client.js";
+import { settled } from "./settle.js";
+function recordScript(id, record) {
+    const json = JSON.stringify(record).replace(/[<>&\u2028\u2029]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16).padStart(4, "0")}`);
+    return `<script type="application/json" id="${id}">${json}</script>`;
+}
+function shape(node, scratch) {
+    if (node.nodeType === 3)
+        return node.textContent ?? "";
+    if (node.nodeType === 8)
+        return `<!--${node.textContent ?? ""}-->`;
+    if (node.nodeType !== 1)
+        return "";
+    const el = node;
+    const attrs = el
+        .getAttributeNames()
+        .filter((name) => name !== "style")
+        .toSorted()
+        .map((name) => ` ${name}=${JSON.stringify(el.getAttribute(name))}`);
+    scratch.setAttribute("style", el.getAttribute("style") ?? "");
+    if (scratch.style.cssText)
+        attrs.push(` style=${JSON.stringify(scratch.style.cssText)}`);
+    return `<${el.tagName}${attrs.join("")}>${[...el.childNodes].map((child) => shape(child, scratch)).join("")}</${el.tagName}>`;
+}
+/** Put a recorded page into the document's body and hydrate it with `mountPage`, throwing on a
+ * node Vue replaced, on any change hydrating made to the markup (a `style` attribute is compared by
+ * the declarations it holds), and on anything Vue warns or logs as an error until the page has
+ * settled. The markup is compared as hydrating leaves it; what changes once the page is mounted,
+ * such as a `<ClientOnly>` showing its content or an async component loading, is the app's to
+ * change. Resolves to the app, mounted and settled. */
+export async function hydrateRecordedPage(page, layout, components, options = {}) {
+    const doc = options.doc ?? document;
+    const id = options.record ?? "__fv_page";
+    doc.body.innerHTML = page.html + (page.record ? recordScript(id, page.record) : "");
+    const selector = options.container ?? "#app";
+    const container = typeof selector === "string" ? doc.querySelector(selector) : selector;
+    if (!container)
+        throw new Error(`the recorded page has no ${selector}`);
+    const scratch = doc.createElement("div");
+    const before = container.innerHTML;
+    const shapeBefore = [...container.childNodes].map((child) => shape(child, scratch)).join("");
+    const first = container.firstChild;
+    const problems = [];
+    const shapeOf = () => [...container.childNodes].map((child) => shape(child, scratch)).join("");
+    let hydrated = "";
+    let shapeHydrated = "";
+    const watch = {
+        install(app) {
+            app.config.warnHandler = (message) => void problems.push(`warning: ${message}`);
+            const mount = app.mount.bind(app);
+            app.mount = (...args) => {
+                const root = mount(...args);
+                hydrated = container.innerHTML;
+                shapeHydrated = shapeOf();
+                return root;
+            };
+        },
+    };
+    const { warn, error } = console;
+    console.warn = (...args) => void problems.push(`console.warn: ${args.map(String).join(" ")}`);
+    console.error = (...args) => void problems.push(`console.error: ${args.map(String).join(" ")}`);
+    let app;
+    try {
+        app = await mountPage(layout, components, { ...options, doc, container, plugins: [...(options.plugins ?? []), watch] });
+        await settled(app);
+    }
+    finally {
+        console.warn = warn;
+        console.error = error;
+    }
+    if (container.firstChild !== first)
+        problems.push("Vue replaced the server's first node");
+    if (shapeHydrated !== shapeBefore)
+        problems.push(`hydrating changed the markup:\n  server:   ${before}\n  hydrated: ${hydrated}`);
+    if (problems.length) {
+        app.unmount();
+        throw new Error(`the page did not hydrate exactly:\n${problems.join("\n")}`);
+    }
+    return app;
+}

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-export { hydrateState, mountIslands, type IslandComponent, type Islands, type MountOptions } from "./client.ts";
+export { ClientOnly, hydrateState, mountIslands, type IslandComponent, type Islands, type MountOptions } from "./client.ts";
+export { createPageApp, mountPage, type PageOptions, type PagePart, type PageRecord } from "./client.ts";
 export type { Float, TrustedHtml } from "./types.ts";

package/dist/index.js

@@ -1 +1,2 @@
-export { hydrateState, mountIslands } from "./client.js";
+export { ClientOnly, hydrateState, mountIslands } from "./client.js";
+export { createPageApp, mountPage } from "./client.js";

package/dist/link-router.d.ts

@@ -0,0 +1,24 @@
+import { type RouteLocationNormalized, type Router, type RouterHistory } from "vue-router";
+import { type RouteEntry } from "./routes.ts";
+export type { RouteEntry } from "./routes.ts";
+/** What `linkRouter` hands navigations to, and the router options of `ferrovue.config.json`. */
+export interface LinkRouterOptions {
+    /** The application's own navigation, called with the `href` of every navigation after the first
+     * (the base included, as the link's `href` attribute has it) and the route it resolves to. */
+    navigate: (href: string, to: RouteLocationNormalized) => void;
+    /** The history's base, as `router.base` in `ferrovue.config.json` gives it. */
+    base?: string;
+    /** As `router.linkActiveClass` in `ferrovue.config.json`. */
+    linkActiveClass?: string;
+    /** As `router.linkExactActiveClass` in `ferrovue.config.json`. */
+    linkExactActiveClass?: string;
+    /** The history the router reads its first location from. By default a memory history at the
+     * page's location: the router neither writes to the browser's history nor listens to it. */
+    history?: RouterHistory;
+}
+/** A router for `<RouterLink>` and `useRoute()` alone, for an application whose own navigation
+ * layer leaves the page: built from the routes file the compiler reads, every route rendering
+ * nothing. Its first navigation resolves the page the server rendered; every later one, a link's
+ * click included, is handed to `navigate` and aborted, so the router stays on that page. Build one
+ * for each page the application shows. */
+export declare function linkRouter(routes: RouteEntry[], options: LinkRouterOptions): Router;

package/dist/link-router.js

@@ -0,0 +1,36 @@
+import { createMemoryHistory, createRouter, isNavigationFailure, NavigationFailureType, START_LOCATION } from "vue-router";
+import { routeRecords } from "./routes.js";
+const Empty = { render: () => null };
+function pageHistory(base) {
+    const history = createMemoryHistory(base);
+    const { pathname, search, hash } = window.location;
+    const prefix = history.base;
+    const path = prefix && pathname.toLowerCase().startsWith(prefix.toLowerCase()) ? pathname.slice(prefix.length) || "/" : pathname;
+    history.replace(path + search + hash);
+    return history;
+}
+/** A router for `<RouterLink>` and `useRoute()` alone, for an application whose own navigation
+ * layer leaves the page: built from the routes file the compiler reads, every route rendering
+ * nothing. Its first navigation resolves the page the server rendered; every later one, a link's
+ * click included, is handed to `navigate` and aborted, so the router stays on that page. Build one
+ * for each page the application shows. */
+export function linkRouter(routes, options) {
+    const history = options.history ?? pageHistory(options.base);
+    const router = createRouter({
+        history,
+        routes: routeRecords(routes, Empty),
+        ...(options.linkActiveClass !== undefined ? { linkActiveClass: options.linkActiveClass } : {}),
+        ...(options.linkExactActiveClass !== undefined ? { linkExactActiveClass: options.linkExactActiveClass } : {}),
+    });
+    router.beforeEach((to, from) => {
+        if (from === START_LOCATION)
+            return true;
+        options.navigate(history.createHref(to.fullPath), to);
+        return false;
+    });
+    router.afterEach((to, _from, failure) => {
+        if (isNavigationFailure(failure, NavigationFailureType.duplicated))
+            options.navigate(history.createHref(to.fullPath), to);
+    });
+    return router;
+}