ferrovue 0.5.0 → 0.6.0

package/dist/children.js

@@ -8,9 +8,10 @@ import { atom, bare } from "./parens.js";
 import { Emitter } from "./emitter.js";
 import { attrOf, dollarAttrs, IGNORED_PROPS, isAttrs, mergedParts } from "./attrs.js";
 import { passedKey } from "./fallthrough.js";
-import { claim, paramsOf, slotFieldsOf } from "./plugin.js";
+import { claim, paramsOf, slotContextOf, slotFieldsOf } from "./plugin.js";
 import { statements } from "./template.js";
 import { slotContent, slotFieldBorrows, staticallyFilled } from "./slots.js";
+import { slotAsVnodes } from "./dynamic.js";
 export function renderChild(s, e, n, twin) {
     const [target, rawProps, slots, , slotScopeId] = n.arguments;
     let local = null;
@@ -22,6 +23,7 @@ export function renderChild(s, e, n, twin) {
     const child = twin?.comp ?? (childName ? s.components.get(childName) : undefined);
     if (!child)
         fail(s.comp, "FV0501", `a child component must be imported from a \`.vue\` file among the components compiled, in ${ctx.componentsDir.replace(/\/$/, "")}`, n);
+    const later = !twin && local !== null && s.loadedLater.has(local);
     for (const p of ctx.plugins)
         p.child?.(s, child, n);
     const parts = !rawProps || rawProps.type === "NullLiteral" ? [] : mergedParts(rawProps);
@@ -44,7 +46,7 @@ export function renderChild(s, e, n, twin) {
         const v = expr(s, objects[0]);
         const own = child.name === s.comp.name && v.ty.k === "struct" && v.ty.name === "Props";
         if (own || (v.ty.k === "child" && v.ty.name === child.name)) {
-            callChild(s, e, child, v.code, slots, childAttrsArg(s, child, parts, merges, null, ids, n));
+            callChild(s, e, child, v.code, slots, childAttrsArg(s, child, parts, merges, null, ids, n), later);
             return;
         }
         fail(s.comp, "FV0503", `child props must be an object literal, or \`v-bind\` of ${child.name}'s own \`Props\``, n);
@@ -54,7 +56,8 @@ export function renderChild(s, e, n, twin) {
             fail(s.comp, "FV0503", `child props must be an object literal, or \`v-bind\` of ${child.name}'s own \`Props\``, p);
     }
     const given = new Map();
-    const fallthrough = new Set();
+    const fallthrough = new Map();
+    const loaded = !merges && local !== null && s.loadedLater.has(local);
     for (const obj of objects) {
         for (const p of obj.properties) {
             if (p.type !== "ObjectProperty" || p.computed)
@@ -72,7 +75,7 @@ export function renderChild(s, e, n, twin) {
             const name = propsToAttrMap[key] ?? key.toLowerCase();
             if (key !== "class" && key !== "style" && !isSSRSafeAttrName(name))
                 fail(s.comp, "FV0404", `unsafe attribute name \`${name}\``, p);
-            fallthrough.add(p);
+            fallthrough.set(p, loaded && key === "class" ? loadedClass(s, p.value) : p.value);
         }
     }
     if (twin) {
@@ -92,11 +95,38 @@ export function renderChild(s, e, n, twin) {
         const v = expr(s, node);
         return fieldInit(f.rust, ownInto(s.comp, { ...v, ty: markHome(v.ty, s.comp.name) }, markHome(f.ty, child.name), node));
     });
-    callChild(s, e, child, `&super::${child.module}::Props { ${inits.join(", ")} }`, slots, childAttrsArg(s, child, parts, merges, fallthrough, ids, n));
+    callChild(s, e, child, `&super::${child.module}::Props { ${inits.join(", ")} }`, slots, childAttrsArg(s, child, parts, merges, fallthrough, ids, n), later);
 }
 export function array(key) {
     return /^(0|[1-9]\d*)$/.test(key) && Number(key) < 2 ** 32 - 1;
 }
+/** A string `:class` given to a component `defineAsyncComponent` loads, in props no `mergeProps`
+ * normalised: Vue's wrapper hands on the class once as written and once trimmed, so a class with
+ * whitespace around it is written twice. */
+const lengthOf = (n) => ({ type: "MemberExpression", object: n, property: { type: "Identifier", name: "length" }, computed: false });
+function holdsClassLiteral(n) {
+    if (n.type === "ObjectExpression" || n.type === "ArrayExpression")
+        return true;
+    if (n.type === "ConditionalExpression")
+        return holdsClassLiteral(n.consequent) || holdsClassLiteral(n.alternate);
+    if (n.type === "LogicalExpression")
+        return holdsClassLiteral(n.left) || holdsClassLiteral(n.right);
+    return false;
+}
+function loadedClass(s, value) {
+    if (value.type === "ConditionalExpression" && (holdsClassLiteral(value.consequent) || holdsClassLiteral(value.alternate))) {
+        return { ...value, consequent: loadedClass(s, value.consequent), alternate: loadedClass(s, value.alternate) };
+    }
+    if (holdsClassLiteral(value) || expr(s, value).ty.k !== "str")
+        return value;
+    const trimmed = { type: "CallExpression", callee: { type: "MemberExpression", object: value, property: { type: "Identifier", name: "trim" }, computed: false }, arguments: [] };
+    return {
+        type: "ConditionalExpression",
+        test: { type: "BinaryExpression", operator: "===", left: lengthOf(trimmed), right: lengthOf(value) },
+        consequent: value,
+        alternate: { type: "ArrayExpression", elements: [trimmed, value] },
+    };
+}
 function childAttrsArg(s, child, parts, merges, fallthrough, ids, n) {
     const sources = [];
     for (const p of parts) {
@@ -106,7 +136,7 @@ function childAttrsArg(s, child, parts, merges, fallthrough, ids, n) {
         else if (p.type === "ObjectExpression" && fallthrough !== null) {
             const entries = p.properties.filter((q) => fallthrough.has(q)).map((q) => {
                 const key = q.key.type === "Identifier" ? q.key.name : String(q.key.value);
-                return `(${rustStr(key)}, ${attrOf(s, key, q.value, "vnode")})`;
+                return `(${rustStr(key)}, ${attrOf(s, key, fallthrough.get(q), "vnode")})`;
             });
             if (entries.length)
                 sources.push(`&[${entries.join(", ")}]`);
@@ -129,15 +159,23 @@ export function fieldInit(name, value) {
 export function takesSlots(c) {
     return c.slotNames.length > 0 || slotFieldsOf(c).length > 0;
 }
-export function extraParams(c) {
-    return (takesSlots(c) ? ", fv_slots: Slots<'_>" : "") + paramsOf(c).map((p) => `, ${p.name}: ${p.ty}`).join("");
+export function extraParams(c, unread = () => false) {
+    return (takesSlots(c) ? ", fv_slots: Slots<'_>" : "") + paramsOf(c).map((p) => `, ${unread(p.name) ? "_" : ""}${p.name}: ${p.ty}`).join("");
 }
-export function callChild(s, e, child, propsCode, slots, attrs) {
+export function callChild(s, e, child, propsCode, slots, attrs, later = false) {
     const m = `super::${child.module}`;
     const scoped = child.inherits || takesAttrs(child);
     const trailing = paramsOf(child).map((p) => `, ${p.name}`).join("") + (scoped ? `, ${attrs ?? (takesAttrs(child) ? "&fv::Attrs::NONE" : '""')}` : "");
     const render = scoped ? "render_scoped" : "render";
+    const around = later ? ctx.plugins.flatMap((p) => p.loadedLater?.(child) ?? []) : [];
+    if (around.length) {
+        e.open("");
+        for (const line of around)
+            e.stmt(line);
+    }
     callWith(s, e, child, m, `${m}::${render}(out, ${propsCode}`, `${m}::Slots`, trailing, slots);
+    if (around.length)
+        e.close();
 }
 export function callWith(s, e, child, m, head, slotsTy, trailing, slots, vnode = false) {
     const given = new Map();
@@ -160,6 +198,9 @@ export function callWith(s, e, child, m, head, slotsTy, trailing, slots, vnode =
         return;
     }
     e.open(`${head}, ${slotsTy}`);
+    const context = slotContextOf(child);
+    const contextParams = context.map((p) => `, ${p.name}: ${p.ty}`).join("");
+    const opaque = vnode ? child.name : s.opaque;
     for (const name of child.slotNames) {
         const field = snake(name);
         const value = given.get(name);
@@ -168,6 +209,7 @@ export function callWith(s, e, child, m, head, slotsTy, trailing, slots, vnode =
             continue;
         }
         const { body, param } = slotContent(s, value);
+        const asVnodes = vnode || s.vnode || slotAsVnodes(child, name);
         const shape = child.slotShapes.get(name);
         const takesNone = param?.type === "Identifier" && param.name === "_";
         const sid = child.passesSlotIds ? `fv_sid${++ctx.narrowCount}` : null;
@@ -205,18 +247,29 @@ export function callWith(s, e, child, m, head, slotsTy, trailing, slots, vnode =
             else if (!takesNone)
                 fail(s.comp, "FV0905", "slot props are a name or an object pattern", param);
             const life = shape.fields.some((f) => slotFieldBorrows(f.ty)) ? "<'_>" : "";
-            e.open(`${field}: Some(&|out: &mut String, ${sp}: &${m}::${shape.name}${life}${sidParam}| -> bool`);
+            e.open(`${field}: Some(&|out: &mut String, ${sp}: &${m}::${shape.name}${life}${sidParam}${contextParams}| -> bool`);
             const opened = e.lines.length - 1;
-            content({ ...s, locals, sid, vnode });
+            content({ ...s, locals, sid, vnode: asVnodes, opaque });
             unread(opened, sp);
             unread(opened, sid);
+            for (const p of context)
+                unread(opened, p.name);
             e.close("),");
             continue;
         }
         if (!takesNone)
             fail(s.comp, "FV0906", `\`<slot${name === "default" ? "" : ` name="${name}"`}>\` in ${child.name} passes no props`, param);
-        const inner = { ...s, sid, vnode };
-        if (sid !== null) {
+        const inner = { ...s, sid, vnode: asVnodes, opaque };
+        if (context.length) {
+            e.open(`${field}: Some(&|out: &mut String${sidParam}${contextParams}| -> bool`);
+            const opened = e.lines.length - 1;
+            content(inner);
+            unread(opened, sid);
+            for (const p of context)
+                unread(opened, p.name);
+            e.close("),");
+        }
+        else if (sid !== null) {
             e.open(`${field}: Some(fv::Slot::slotted(&|out: &mut String${sidParam}| -> bool`);
             const opened = e.lines.length - 1;
             content(inner);

package/dist/classes.d.ts

@@ -7,6 +7,10 @@ export type ClassItem = {
 };
 export declare function classItems(s: Scope, n: N): ClassItem[];
 export declare function renderClass(s: Scope, e: Emitter, n: N, after?: boolean): void;
+/** The class list of an element in content Vue renders from virtual nodes, in the order Vue's
+ * client compiler merges a static `class` written before `:class`: the static names first, at the
+ * place of the static `class`. */
+export declare function vnodeClass(s: Scope, n: N): N;
 export declare function classPresent(s: Scope, n: N): string;
 export declare function maybeEqual(s: Scope, n: N): boolean;
 export declare function literalClass(n: N): string | null;

package/dist/classes.js

@@ -1,5 +1,5 @@
 import { escapeHtml } from "@vue/shared";
-import { fail, nothing, rustStr, STR } from "./model.js";
+import { directiveOwner, fail, nothing, rustStr, STR } from "./model.js";
 import { expr } from "./expr.js";
 import { cond, known, truthy } from "./narrowing.js";
 import { meet } from "./strings.js";
@@ -102,6 +102,28 @@ export function renderClass(s, e, n, after = false) {
         e.stmt(`fv::class_into(out, ${wrote}, &[${rest.join(", ")}]);`);
     }
 }
+const UNWRITTEN = new Set(["on", "if", "else-if", "else", "for", "slot", "once", "memo", "cloak", "pre"]);
+/** The class list of an element in content Vue renders from virtual nodes, in the order Vue's
+ * client compiler merges a static `class` written before `:class`: the static names first, at the
+ * place of the static `class`. */
+export function vnodeClass(s, n) {
+    const last = n.type === "ArrayExpression" ? n.elements.at(-1) : null;
+    if (n.fvMerged || last?.type !== "StringLiteral" || n.elements.length < 2)
+        return n;
+    const el = directiveOwner(s.comp, n.elements[0]);
+    if (!el)
+        return n;
+    const own = el.props.findIndex((p) => p.type === 6 && p.name === "class");
+    const bound = el.props.findIndex((p) => p.type === 7 && p.name === "bind" && p.arg?.content === "class");
+    if (own < 0 || bound < own)
+        return n;
+    const between = el.props.slice(own + 1, bound).find((p) => p.type === 6 || !UNWRITTEN.has(p.name));
+    if (between) {
+        const at = { type: "VueTemplate", loc: { start: { line: between.loc.start.line, column: between.loc.start.column - 1 } }, __fv: "source" };
+        fail(s.comp, "FV1013", "in content Vue renders from virtual nodes, a `class` written before `:class` is written where the `class` stands, and Vue's server compiler moves it to where `:class` stands; write the two next to each other, or `:class` first", at);
+    }
+    return { ...n, elements: [last, ...n.elements.slice(0, -1)] };
+}
 export function classPresent(s, n) {
     if (n.fvMerged)
         return n.elements.reduce((acc, el) => logical(acc, "||", classPresent(s, el)), "false");

package/dist/client.d.ts

@@ -15,7 +15,8 @@ export interface MountOptions {
     /** Where to look for islands: the whole document by default. */
     root?: ParentNode;
     /** Told about an island left as the server rendered it, because its component is not among
-     * those given or its props are malformed. Warns on the console by default. */
+     * those given, did not load or its props are malformed, and about one hydrated at once because
+     * its `data-hydrate` is not one this version knows. Warns on the console by default. */
     onError?: (element: Element, problem: string) => void;
 }
 /** A component, or a function that loads one (`() => import("./Counter.vue")`), so that the code
@@ -28,15 +29,19 @@ export type IslandComponent = Component | (() => Promise<Component | {
 }>);
 /** The islands mounted. */
 export interface Islands {
-    /** One app per island, in document order. */
+    /** One app per island hydrated so far: those hydrated at once in document order, then each
+     * island with a `data-hydrate` as it hydrates. */
     apps: App[];
-    /** Unmount every island, as a page leaving would. */
+    /** Unmount every island and stop waiting to hydrate the others, as a page leaving would. */
     unmount(): void;
 }
 /** Hydrate every island on the page: each `<div data-island="Name" data-props="…">` that
  * `Html::island` wrote becomes an app of the component of that name, given the props the server
  * rendered it with, mounted where it is. A loader is called only for an island the page holds, all
- * of them at once, and the islands mount in document order once every one has loaded. */
+ * of them at once, and the islands mount in document order once every one has loaded. An island
+ * with a `data-hydrate` (`Html::hydrate`) waits instead: once it is visible (or within a root margin
+ * of the viewport), the browser is idle,
+ * it is interacted with or a media query matches, its component is loaded and it hydrates. */
 export declare function mountIslands(components: Record<string, IslandComponent>, options?: MountOptions): Promise<Islands>;
 /** Content only the browser renders. The server writes the `#fallback` slot, or nothing; the
  * browser hydrates that fallback, then swaps in the default slot once mounted. ferrovue does not

package/dist/client.js

@@ -1,4 +1,4 @@
-import { createSSRApp, createTextVNode, defineComponent, h, onMounted, ref } from "vue";
+import { createSSRApp, createTextVNode, defineComponent, h, hydrateOnIdle, hydrateOnMediaQuery, hydrateOnVisible, onMounted, ref, } from "vue";
 const BARE = /"(?:[^"\\]|\\.)*"|-?Infinity|NaN/g;
 const NON_FINITE = { NaN: Number.NaN, Infinity: Number.POSITIVE_INFINITY, "-Infinity": Number.NEGATIVE_INFINITY };
 function parseJson(text) {
@@ -18,35 +18,79 @@ export function hydrateState(pinia, id = "__pinia", doc = document) {
     if (text)
         pinia.state.value = parseJson(text);
 }
+const INTERACTIONS = ["pointerenter", "click", "focus"];
+const strategy = (wait) => (el, hydrate) => wait(() => void hydrate(), (each) => void each(el)) ?? (() => { });
+const idle = (el, hydrate) => {
+    if (typeof requestIdleCallback === "function")
+        return strategy(hydrateOnIdle())(el, hydrate);
+    const timer = setTimeout(() => void hydrate(), 200);
+    return () => clearTimeout(timer);
+};
+const interaction = (names) => (el, hydrate) => {
+    const events = names.length ? names : INTERACTIONS;
+    const early = [];
+    const stop = () => {
+        for (const name of events)
+            el.removeEventListener(name, listen, true);
+    };
+    const replay = () => {
+        stop();
+        for (const e of early.splice(0)) {
+            if (e.target instanceof Node && e.target.isConnected)
+                e.target.dispatchEvent(new e.constructor(e.type, e));
+        }
+    };
+    function listen(e) {
+        if (early.push(e) === 1)
+            void hydrate().then((mounted) => (mounted ? replay() : stop()));
+    }
+    for (const name of events)
+        el.addEventListener(name, listen, true);
+    return stop;
+};
+function trigger(when) {
+    const colon = when.indexOf(":");
+    const [kind, arg] = colon < 0 ? [when, undefined] : [when.slice(0, colon), when.slice(colon + 1)];
+    if (kind === "visible")
+        return strategy(hydrateOnVisible(arg ? { rootMargin: arg } : undefined));
+    if (kind === "idle" && arg === undefined)
+        return idle;
+    if (kind === "interaction")
+        return interaction((arg ?? "").split(/\s+/).filter(Boolean));
+    if (kind === "media" && arg !== undefined)
+        return strategy(hydrateOnMediaQuery(arg || "all"));
+    return undefined;
+}
 /** Hydrate every island on the page: each `<div data-island="Name" data-props="…">` that
  * `Html::island` wrote becomes an app of the component of that name, given the props the server
  * rendered it with, mounted where it is. A loader is called only for an island the page holds, all
- * of them at once, and the islands mount in document order once every one has loaded. */
+ * of them at once, and the islands mount in document order once every one has loaded. An island
+ * with a `data-hydrate` (`Html::hydrate`) waits instead: once it is visible (or within a root margin
+ * of the viewport), the browser is idle,
+ * it is interacted with or a media query matches, its component is loaded and it hydrates. */
 export async function mountIslands(components, options = {}) {
     const root = options.root ?? document;
     const report = options.onError ?? ((el, problem) => console.warn(`[ferrovue] island left unhydrated: ${problem}`, el));
     const elements = Array.from(root.querySelectorAll("[data-island]"));
     const loading = new Map();
-    for (const el of elements) {
-        const name = el.dataset.island ?? "";
-        if (Object.hasOwn(components, name) && !loading.has(name))
-            loading.set(name, load(components[name]));
-    }
-    const [loaded] = await Promise.all([
-        Promise.all([...loading].map(async ([name, pending]) => [name, await pending])).then((pairs) => new Map(pairs)),
-        options.router?.isReady(),
-    ]);
+    const loadIsland = (name) => {
+        let pending = loading.get(name);
+        if (!pending)
+            loading.set(name, (pending = load(components[name])));
+        return pending;
+    };
+    const ready = options.router?.isReady();
     const apps = [];
-    for (const el of elements) {
-        const name = el.dataset.island ?? "";
-        const component = loaded.get(name);
+    const waiting = [];
+    let stopped = false;
+    const mount = (el, name, component) => {
         if (!component) {
             report(el, `no component called ${JSON.stringify(name)} was given (\`ferrovue/islands\` holds every component that has an \`island()\`)`);
-            continue;
+            return;
         }
         if (component instanceof Error) {
             report(el, `${name} did not load: ${component.message}`);
-            continue;
+            return;
         }
         let props;
         try {
@@ -54,7 +98,7 @@ export async function mountIslands(components, options = {}) {
         }
         catch {
             report(el, `the props of ${name} are not JSON`);
-            continue;
+            return;
         }
         const app = createSSRApp(component, props);
         if (options.pinia)
@@ -65,10 +109,55 @@ export async function mountIslands(components, options = {}) {
             app.use(plugin);
         app.mount(el);
         apps.push(app);
+    };
+    const now = [];
+    for (const el of elements) {
+        const name = el.dataset.island ?? "";
+        const given = Object.hasOwn(components, name);
+        const when = el.dataset.hydrate;
+        const wait = given && when !== undefined ? trigger(when) : undefined;
+        if (!wait) {
+            if (given && when !== undefined)
+                report(el, `${name} has data-hydrate=${JSON.stringify(when)}, which this version of ferrovue does not know, so it hydrated at once`);
+            if (given)
+                void loadIsland(name);
+            now.push(el);
+            continue;
+        }
+        let started = false;
+        try {
+            waiting.push(wait(el, async () => {
+                if (started || stopped)
+                    return false;
+                started = true;
+                const [component] = await Promise.all([loadIsland(name), ready]);
+                if (stopped)
+                    return false;
+                mount(el, name, component);
+                return true;
+            }));
+        }
+        catch (e) {
+            report(el, `${name} has data-hydrate=${JSON.stringify(when)}, which the browser rejects (${e instanceof Error ? e.message : String(e)}), so it hydrated at once`);
+            void loadIsland(name);
+            now.push(el);
+        }
+    }
+    const names = new Set(now.map((el) => el.dataset.island ?? "").filter((name) => Object.hasOwn(components, name)));
+    const [loaded] = await Promise.all([
+        Promise.all([...names].map(async (name) => [name, await loadIsland(name)])).then((pairs) => new Map(pairs)),
+        ready,
+    ]);
+    for (const el of now) {
+        const name = el.dataset.island ?? "";
+        mount(el, name, loaded.get(name));
     }
     return {
         apps,
         unmount() {
+            stopped = true;
+            for (const stop of waiting.splice(0))
+                stop();
             for (const app of apps.splice(0))
                 app.unmount();
         },

package/dist/compiler.d.ts

@@ -18,6 +18,6 @@ export interface Written {
  * so a Rust build that watches them rebuilds no more than it must, and removing what no component
  * produces any more. */
 export declare function write(root: string, config?: Config): Written;
-export { CONFIG_FILE, loadConfig, TYPES_MODULE, type Config, type HelperSpec, type TwinSpec, type TypeName } from "./context.ts";
+export { CONFIG_FILE, loadConfig, TYPES_MODULE, type Config, type HelperSpec, type RoutesSource, type TwinSpec, type TypeName } from "./context.ts";
 export { GenError } from "./model.ts";
 export declare const VERSION: string;

package/dist/compiler.js

@@ -1,9 +1,11 @@
 import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { basename, join, relative } from "node:path";
 import { ctx, loadConfig, tyOfName } from "./context.js";
+import { failIn, snake } from "./model.js";
 import { importsOf, readComponent } from "./component.js";
 import { scopeFor } from "./script.js";
 import { attrsFlow } from "./fallthrough.js";
+import { prepareDynamic } from "./dynamic.js";
 import { componentSource, isIsland, modSource } from "./rust.js";
 import { renderParams } from "./plugin.js";
 import { PLUGINS } from "./plugins/index.js";
@@ -15,6 +17,7 @@ export function generate(root, config = loadConfig(root)) {
     ctx.builders = config.builders ?? true;
     ctx.clientDirectives = new Set(config.clientDirectives ?? []);
     ctx.rootDir = root;
+    ctx.vnodeTag = null;
     ctx.typeStructs = new Map();
     ctx.typeAliases = new Map();
     ctx.typeFiles = new Map();
@@ -32,16 +35,34 @@ export function generate(root, config = loadConfig(root)) {
         { rust: h.rust, params: h.params.map(tyOfName), ret: tyOfName(h.returns), maxLen: h.maxLen ?? 0 },
     ]));
     const dir = join(root, config.components);
-    const files = readdirSync(dir)
-        .filter((f) => f.endsWith(".vue"))
-        .toSorted()
-        .map((f) => join(dir, f));
-    const children = new Set(files.flatMap((f) => importsOf(readFileSync(f, "utf8")).filter((c) => c !== basename(f, ".vue"))));
-    const read = files.map((f) => readComponent(f, root, children.has(basename(f, ".vue"))));
+    const files = [
+        ...readdirSync(dir)
+            .filter((f) => f.endsWith(".vue"))
+            .toSorted()
+            .map((f) => ({ file: join(dir, f), name: basename(f, ".vue") })),
+        ...PLUGINS.flatMap((p) => p.components?.() ?? []).map((c) => ({ file: join(root, c.file), name: c.name })),
+    ];
+    const modulesOf = new Map();
+    for (const f of files) {
+        const rel = relative(root, f.file);
+        if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(f.name)) {
+            failIn(rel, "FV0007", `the component is called \`${f.name}\` after its file, which is not a Rust name: name the file in PascalCase, letters and digits (\`UserCard.vue\`)`);
+        }
+        const file = moduleFile(snake(f.name));
+        if (file === "mod.rs")
+            failIn(rel, "FV0007", `the component's module would be \`mod.rs\`, which holds the generated modules: rename the file`);
+        const taken = modulesOf.get(file);
+        if (taken)
+            failIn(rel, "FV0007", `the component's module would be \`${file}\`, as ${taken}'s is: rename one of them`);
+        modulesOf.set(file, rel);
+    }
+    const children = new Set(files.flatMap((f) => importsOf(readFileSync(f.file, "utf8")).filter((c) => c !== f.name)));
+    const read = files.map((f) => readComponent(f.file, root, children.has(f.name), f.name));
     const components = new Map(read.map((r) => [r.comp.name, r.comp]));
     ctx.components = components;
     const scopes = read.map((r) => scopeFor(r.comp, r.ast, components).scope);
-    const all = read.map((r, i) => ({ comp: r.comp, ssr: r.ssr, children: scopes[i].children, attrsBindings: scopes[i].attrsBindings }));
+    const analysed = prepareDynamic(read.map((r, i) => ({ ...r, scope: scopes[i] })));
+    const all = read.map((r, i) => ({ comp: r.comp, ssr: analysed[i], children: scopes[i].children, attrsBindings: scopes[i].attrsBindings }));
     for (const p of PLUGINS)
         p.analyse?.(all);
     attrsFlow(all);
@@ -75,14 +96,21 @@ export function generate(root, config = loadConfig(root)) {
     read.forEach(place);
     for (const r of ordered) {
         ctx.narrowCount = 0;
-        out.set(`${r.comp.module}.rs`, componentSource(r.comp, r.ast, r.ssr, components));
+        out.set(moduleFile(r.comp.module), componentSource(r.comp, r.ast, r.ssr, components));
     }
     const modules = PLUGINS.flatMap((p) => p.modules?.() ?? []);
     out.set("mod.rs", modSource(read.map((r) => r.comp), modules.map(([file]) => file)));
-    for (const [file, text] of modules)
+    for (const [file, text] of modules) {
+        const taken = modulesOf.get(file);
+        if (taken)
+            failIn(taken, "FV0007", `the component's module would be \`${file}\`, which ferrovue writes for the project's ${file.replace(/\.rs$/, "").replaceAll("_", " ")}: rename the file`);
         out.set(file, text);
+    }
     return out;
 }
+function moduleFile(module) {
+    return `${module.replace(/^r#/, "")}.rs`;
+}
 /** Write what \`generate\` produces to the configured directory: only the files whose text changed,
  * so a Rust build that watches them rebuilds no more than it must, and removing what no component
  * produces any more. */

package/dist/component.d.ts

@@ -1,7 +1,7 @@
 import { type Component, type N } from "./model.ts";
 /** The `.vue` files a component imports, by name. */
 export declare function importsOf(source: string): string[];
-export declare function readComponent(file: string, root: string, isChild: boolean): {
+export declare function readComponent(file: string, root: string, isChild: boolean, name?: string): {
     comp: Component;
     ast: N[];
     ssr: string;

package/dist/component.js

@@ -114,15 +114,14 @@ function scriptOf(comp, descriptor) {
         throw new GenError("FV0001", e.message, { file: comp.file, ...where }, e.message.split("\n")[0]);
     }
 }
-export function readComponent(file, root, isChild) {
-    const name = basename(file, ".vue");
+export function readComponent(file, root, isChild, name = basename(file, ".vue")) {
     const source = readFileSync(file, "utf8");
     const { descriptor, errors } = parseSfc(source, { filename: file });
     const rel = relative(root, file);
     const comp = blankComponent(name, snake(name), rel);
     comp.source = source;
     if (errors.length)
-        fail(comp, "FV0002", String(errors[0]), vueErrorNode(errors[0]));
+        fail(comp, "FV0002", String(errors[0]).replaceAll(file, rel), vueErrorNode(errors[0]) ?? sourceAt(source, 0));
     if (descriptor.script && !descriptor.scriptSetup) {
         const needs = isChild ? "a child component must have" : "an island needs";
         fail(comp, "FV0003", `${needs} \`<script setup lang="ts">\`, or no script at all: a \`<script>\` without \`setup\` (the Options API, \`defineComponent\`) is not translated`, blockAt(source, descriptor.script));

package/dist/conformance.d.ts

@@ -0,0 +1,64 @@
+import type { App, Component } from "vue";
+import { type Config } from "./compiler.ts";
+import { type RouteEntry, type RouterOptions } from "./fixture.ts";
+/** What `conformanceSuite` checks: the project, its components and its fixtures. `pinia`,
+ * `vueRouter` and `vueI18n` are the application's own modules (`pinia: await import("pinia")`),
+ * which the fixtures install so that its stores and composables find them. */
+export interface ConformanceOptions extends Pick<RouterOptions, "pinia" | "vueRouter" | "vueI18n"> {
+    /** The project's `ferrovue.config.json`. */
+    config: string;
+    /** Every component in the configured `components` directory, by file name or by the path
+     * `import.meta.glob` gives it: `import.meta.glob("../components/*.vue", { eager: true })`; and
+     * with a folder of pages, every page, by the path `import.meta.glob("../pages/**\/*.vue")` gives
+     * it or by its component name (`BooksId`). */
+    components: Record<string, Component | {
+        default: Component;
+    }>;
+    /** The fixtures, one directory per component holding `<case>.json` and `<case>.html`:
+     * `fixtures` beside the configuration when not given. */
+    fixtures?: string;
+    /** Write each fixture's `.html` from Vue's render instead of comparing it: when
+     * `FERROVUE_FIXTURES_WRITE=1` is set, if not given. */
+    record?: boolean;
+}
+interface TestApi {
+    describe(name: string, body: () => void): void;
+    it(name: string, body: () => Promise<void> | void): void;
+}
+export declare const TELEPORTS = "<!--fv-teleports-->";
+export declare const HEAD = "<!--fv-head-->";
+/** What unhead's server renderer wrote for a recorded render's head, as `renderSSRHead` gives it. */
+export interface RecordedHead {
+    headTags: string;
+    bodyTags: string;
+    bodyTagsOpen: string;
+    htmlAttrs: string;
+    bodyAttrs: string;
+}
+/** The head a recorded render wrote after its body, if it wrote one. */
+export declare function recordedHead(html: string): RecordedHead | null;
+/** Render a fixture's app as the conformance suite records it: Vue's HTML, then what was teleported
+ * and what `useHead` asked for, each after its marker. */
+export declare function renderFixture(app: App): Promise<string>;
+/** Put a recorded render's head into the document, as a page would write it: its tags in `<head>`,
+ * and its attributes on `<html>` and `<body>`. */
+export declare function placeHead(head: RecordedHead | null, doc?: Document): void;
+/** A recorded render as a page body to hydrate: the main HTML in `<div id="root">`, what was
+ * teleported in each target, and the tags the head puts at the start and end of `<body>`. */
+export declare function hydrationBody(html: string): string;
+/** Where two renders first differ, with the text around it in each. */
+export declare function firstDifference(recorded: string, rendered: string): string;
+/** The routes and the router and vue-i18n options a project's fixtures render with, from its configuration. */
+export declare function fixtureOptions(root: string, config: Config): {
+    routes: RouteEntry[] | null;
+    options: RouterOptions;
+};
+/** Register the conformance suite with the given `describe` and `it`. */
+export declare function registerConformance(api: TestApi, options: ConformanceOptions): void;
+/** Register vitest tests holding a project's components to Vue, as ferrovue's own suite does:
+ * every component has fixtures and every fixture a component, the generated Rust is what the
+ * generator writes now, Vue renders each fixture to its recorded `.html` (or records it, with
+ * `FERROVUE_FIXTURES_WRITE=1`), and each recorded `.html` hydrates with no warning and the server's
+ * nodes kept. Await it at the top of a test file run in a DOM environment such as happy-dom. */
+export declare function conformanceSuite(options: ConformanceOptions): Promise<void>;
+export {};