ferrovue 0.4.0 → 0.5.0

package/dist/calls.js

@@ -20,7 +20,7 @@ export function call(s, n) {
                     meet(comp, a, b, "`v-model`", n, "equal");
                     return boolOf(stringsEqual(a, b));
                 }
-                return fail(comp, "`v-model` comparison between these types", n);
+                return fail(comp, "FV0413", "`v-model` comparison between these types", n);
             }
             case "_ssrIncludeBooleanAttr": {
                 const a = expr(s, args[0]);
@@ -33,7 +33,7 @@ export function call(s, n) {
                 return boolOf(truthy(a));
             }
             case "_ssrLooseContain":
-                return fail(comp, "`v-model` over an array", n);
+                return fail(comp, "FV0414", "`v-model` over an array", n);
         }
         const own = claim((p) => p.call?.(s, n));
         if (own)
@@ -58,21 +58,21 @@ export function call(s, n) {
                 return a;
             if (a.ty.k === "bool")
                 return { code: `i64::from(${bare(a.code)})`, ty: INT };
-            return fail(comp, "`Number()` takes a string, a number or a boolean that is present", n);
+            return fail(comp, "FV0701", "`Number()` takes a string, a number or a boolean that is present", n);
         }
         if ((callee.name === "parseInt" && (args.length === 1 || args.length === 2)) || (callee.name === "parseFloat" && args.length === 1)) {
             const a = expr(s, args[0]);
             if (a.ty.k !== "str")
-                fail(comp, `\`${callee.name}()\` takes a string`, args[0]);
+                fail(comp, "FV0702", `\`${callee.name}()\` takes a string`, args[0]);
             if (callee.name === "parseFloat")
                 return { code: `fv::js_parse_float(${strArg(a.code)})`, ty: FLOAT };
             const radix = args[1];
             if (radix && !(radix.type === "NumericLiteral" && (radix.value === 10 || radix.value === 16))) {
-                fail(comp, "`parseInt()` takes a radix of 10 or 16, written as a literal", radix);
+                fail(comp, "FV0703", "`parseInt()` takes a radix of 10 or 16, written as a literal", radix);
             }
             return { code: `fv::js_parse_int(${strArg(a.code)}, ${radix ? radix.value : 0})`, ty: FLOAT };
         }
-        return fail(comp, `\`${callee.name}()\` is not available when rendering on the server`, n);
+        return fail(comp, "FV0601", `\`${callee.name}()\` is not available when rendering on the server`, n);
     }
     if (callee.type === "MemberExpression" && !callee.computed) {
         const method = callee.property.name;
@@ -119,7 +119,7 @@ export function call(s, n) {
                         return { code: `${receiver(asF64(x))}.${method}()`, ty: FLOAT };
                 }
             }
-            return fail(comp, `\`Math.${method}()\` is supported on numbers as \`max\`, \`min\`, \`abs\`, \`round\`, \`floor\`, \`ceil\` and \`trunc\``, n);
+            return fail(comp, "FV0704", `\`Math.${method}()\` is supported on numbers as \`max\`, \`min\`, \`abs\`, \`round\`, \`floor\`, \`ceil\` and \`trunc\``, n);
         }
         const target = expr(s, callee.object);
         if (target.ty.k === "str") {
@@ -145,7 +145,7 @@ export function call(s, n) {
         if (isNumber(target.ty) && method === "toFixed" && args.length <= 1) {
             const d = args.length ? args[0] : { type: "NumericLiteral", value: 0 };
             if (d.type !== "NumericLiteral" || !Number.isInteger(d.value) || d.value < 0 || d.value > 100) {
-                fail(comp, "`.toFixed()` takes a literal number of digits, from 0 to 100", n);
+                fail(comp, "FV0705", "`.toFixed()` takes a literal number of digits, from 0 to 100", n);
             }
             return { code: `&*fv::js_to_fixed(${bare(asF64(target))}, ${d.value})`, ty: STR };
         }
@@ -162,8 +162,10 @@ export function call(s, n) {
             const of = target.ty.of;
             if (method === "includes" && args.length === 1) {
                 const v = expr(s, args[0]);
+                if (of.k === "int" && v.ty.k === "float")
+                    return { code: `${atom(target.code)}.iter().any(|v| ${binary("*v as f64", "==", v.code)})`, ty: BOOL };
                 if (!sameTy(v.ty, of))
-                    fail(comp, "`.includes()` looks for a value of the list's own type", args[0]);
+                    fail(comp, "FV0801", "`.includes()` looks for a value of the list's own type", args[0]);
                 if (of.k === "int")
                     return { code: `${atom(target.code)}.contains(&${operand(v.code, UNARY)})`, ty: BOOL };
                 const test = v.code === '""' ? "v.is_empty()" : binary("&**v", "==", v.code);
@@ -172,14 +174,14 @@ export function call(s, n) {
             if (method === "join" && args.length <= 1) {
                 const sep = args.length ? expr(s, args[0]) : { code: '","', ty: STR };
                 if (sep.ty.k !== "str")
-                    fail(comp, "`.join()` takes a string", args[0]);
+                    fail(comp, "FV0802", "`.join()` takes a string", args[0]);
                 const each = of.k === "str" ? `${atom(target.code)}.iter().map(|v| &**v)` : `${atom(target.code)}.iter().map(|v| fv::Js(*v).to_string())`;
                 return { code: `&*${each}.collect::<Vec<_>>().join(${strArg(sep.code)})`, ty: STR, ...loneOf(sep) };
             }
         }
-        return fail(comp, `\`.${method}()\` is not supported`, n);
+        return fail(comp, "FV0602", `\`.${method}()\` is not supported`, n);
     }
-    return fail(comp, "this call is not supported", n);
+    return fail(comp, "FV0603", "this call is not supported", n);
 }
 export function isObjectCall(n, method) {
     return (n?.type === "CallExpression" && n.callee.type === "MemberExpression" && !n.callee.computed &&
@@ -187,7 +189,7 @@ export function isObjectCall(n, method) {
 }
 function json(s, v, n) {
     if (v.lone)
-        fail(s.comp, lonely("`JSON.stringify()`"), n);
+        fail(s.comp, "FV0706", lonely("`JSON.stringify()`"), n);
     const one = (code, ty) => {
         switch (ty.k) {
             case "str":
@@ -199,7 +201,7 @@ function json(s, v, n) {
             case "bool":
                 return `(if ${condition(code)} { "true" } else { "false" }).to_owned()`;
             default:
-                return fail(s.comp, "`JSON.stringify()` of a string, a number, a boolean or a list of those, present", n);
+                return fail(s.comp, "FV0707", "`JSON.stringify()` of a string, a number, a boolean or a list of those, present", n);
         }
     };
     if (v.ty.k === "list") {
@@ -212,7 +214,7 @@ function json(s, v, n) {
 export function helperCall(s, name, args, n) {
     const h = ctx.helpers[name];
     if (args.length !== h.params.length)
-        fail(s.comp, `\`${name}\` takes ${h.params.length} argument(s)`, n);
+        fail(s.comp, "FV1101", `\`${name}\` takes ${h.params.length} argument(s)`, n);
     const code = args.map((a, i) => bare(coerce(s.comp, expr(s, a), h.params[i], a))).join(", ");
     s.helperBytes.n += h.maxLen;
     return { code: `${h.rust}(${code})`, ty: h.ret };

package/dist/children.d.ts

@@ -1,9 +1,16 @@
-import { type Component, type N, type Scope, type Ty, type Val } from "./model.ts";
+import { type Component, type Field, type N, type Scope, type Ty, type Val } from "./model.ts";
 import { Emitter } from "./emitter.ts";
-export declare function renderChild(s: Scope, e: Emitter, n: N): void;
+/** A component the project renders with a Rust function of its own, in place of a compiled one. */
+export interface TwinCall {
+    comp: Component;
+    init(s: Scope, f: Field, node: N | undefined, n: N): string;
+    call(s: Scope, e: Emitter, inits: string[], slots: N, attrs: string): void;
+}
+export declare function renderChild(s: Scope, e: Emitter, n: N, twin?: TwinCall): void;
 export declare function array(key: string): boolean;
 export declare function fieldInit(name: string, value: string): string;
 export declare function takesSlots(c: Component): boolean;
 export declare function extraParams(c: Component): string;
 export declare function callChild(s: Scope, e: Emitter, child: Component, propsCode: string, slots: N, attrs: string | null): void;
+export declare function callWith(s: Scope, e: Emitter, child: Component, m: string, head: string, slotsTy: string, trailing: string, slots: N, vnode?: boolean): void;
 export declare function ownInto(comp: Component, v: Val, want: Ty, node: N): string;

package/dist/children.js

@@ -1,8 +1,8 @@
 import { isSSRSafeAttrName, propsToAttrMap } from "@vue/shared";
-import { camelize, declares, fail, GenError, rustStr, sameTy, snake, takesAttrs } from "./model.js";
+import { camelize, declares, fail, nothing, rustStr, sameTy, snake, takesAttrs } from "./model.js";
 import { ctx } from "./context.js";
 import { markHome } from "./typescript.js";
-import { expr, fieldVal } from "./expr.js";
+import { expr, fieldVal, holdsNothing } from "./expr.js";
 import { asF64 } from "./numbers.js";
 import { atom, bare } from "./parens.js";
 import { Emitter } from "./emitter.js";
@@ -11,7 +11,7 @@ import { passedKey } from "./fallthrough.js";
 import { claim, paramsOf, slotFieldsOf } from "./plugin.js";
 import { statements } from "./template.js";
 import { slotContent, slotFieldBorrows, staticallyFilled } from "./slots.js";
-export function renderChild(s, e, n) {
+export function renderChild(s, e, n, twin) {
     const [target, rawProps, slots, , slotScopeId] = n.arguments;
     let local = null;
     if (target.type === "MemberExpression" && target.object.name === "$setup") {
@@ -19,9 +19,9 @@ export function renderChild(s, e, n) {
     }
     const isSelf = target.type === "Identifier" && target.name === s.selfAlias.name;
     const childName = isSelf ? s.comp.name : local ? s.children.get(local) : undefined;
-    const child = childName ? s.components.get(childName) : undefined;
+    const child = twin?.comp ?? (childName ? s.components.get(childName) : undefined);
     if (!child)
-        fail(s.comp, "a child component must be an imported island", n);
+        fail(s.comp, "FV0501", `a child component must be imported from a \`.vue\` file among the components compiled, in ${ctx.componentsDir.replace(/\/$/, "")}`, n);
     for (const p of ctx.plugins)
         p.child?.(s, child, n);
     const parts = !rawProps || rawProps.type === "NullLiteral" ? [] : mergedParts(rawProps);
@@ -33,30 +33,32 @@ export function renderChild(s, e, n) {
     if (parts.some(passed)) {
         for (const name of s.comp.attrNames) {
             if (declares(child, name)) {
-                fail(s.comp, `\`${name}\`, an attribute ${s.comp.name} may be passed, would reach ${child.name} as its prop \`${camelize(name)}\`, which an attribute has no type for`, n);
+                fail(s.comp, "FV0502", `\`${name}\`, an attribute ${s.comp.name} may be passed, would reach ${child.name} as its prop \`${camelize(name)}\`, which an attribute has no type for`, n);
             }
         }
     }
     const ids = claim((p) => p.childIds?.(s, child, passesAttrs, !!slotScopeId, n)) ?? null;
     if (objects.length === 1 && objects[0].type !== "ObjectExpression") {
+        if (twin)
+            fail(s.comp, "FV1501", `the props of ${child.name}, a Rust twin, are attributes or an object literal`, objects[0]);
         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));
+            callChild(s, e, child, v.code, slots, childAttrsArg(s, child, parts, merges, null, ids, n));
             return;
         }
-        fail(s.comp, `child props must be an object literal, or \`v-bind\` of ${child.name}'s own \`Props\``, n);
+        fail(s.comp, "FV0503", `child props must be an object literal, or \`v-bind\` of ${child.name}'s own \`Props\``, n);
     }
     for (const p of objects) {
         if (p.type !== "ObjectExpression")
-            fail(s.comp, `child props must be an object literal, or \`v-bind\` of ${child.name}'s own \`Props\``, p);
+            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();
     for (const obj of objects) {
         for (const p of obj.properties) {
             if (p.type !== "ObjectProperty" || p.computed)
-                fail(s.comp, "child props hold plain keys", p);
+                fail(s.comp, "FV0504", "child props hold plain keys", p);
             const key = p.key.type === "Identifier" ? p.key.name : String(p.key.value);
             if (!passedKey(child, key))
                 continue;
@@ -66,29 +68,36 @@ export function renderChild(s, e, n) {
                 continue;
             }
             if (array(key))
-                fail(s.comp, `an attribute named \`${key}\`, which JavaScript would put before the others`, p);
+                fail(s.comp, "FV0505", `an attribute named \`${key}\`, which JavaScript would put before the others`, p);
             const name = propsToAttrMap[key] ?? key.toLowerCase();
             if (key !== "class" && key !== "style" && !isSSRSafeAttrName(name))
-                fail(s.comp, `unsafe attribute name \`${name}\``, p);
+                fail(s.comp, "FV0404", `unsafe attribute name \`${name}\``, p);
             fallthrough.add(p);
         }
     }
+    if (twin) {
+        const inits = child.props.fields.map((f) => twin.init(s, f, given.get(f.js), n));
+        twin.call(s, e, inits, slots, childAttrsArg(s, child, parts, merges, fallthrough, ids, n));
+        return;
+    }
     const inits = child.props.fields.map((f) => {
         const node = given.get(f.js);
         if (!node) {
             if (f.ty.k !== "opt")
-                fail(s.comp, `${child.name} requires \`${f.js}\``, n);
+                fail(s.comp, "FV0506", `${child.name} requires \`${f.js}\``, n);
+            if (f.ty.none !== undefined)
+                fail(s.comp, "FV0507", `${child.name} requires \`${f.js}\`, which is \`T | null\`: Vue would hand it \`undefined\`; pass \`null\` for none`, n);
             return `${f.rust}: None`;
         }
         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));
+    callChild(s, e, child, `&super::${child.module}::Props { ${inits.join(", ")} }`, slots, childAttrsArg(s, child, parts, merges, fallthrough, ids, n));
 }
 export function array(key) {
     return /^(0|[1-9]\d*)$/.test(key) && Number(key) < 2 ** 32 - 1;
 }
-function childAttrsArg(s, child, parts, merges, fallthrough, ids) {
+function childAttrsArg(s, child, parts, merges, fallthrough, ids, n) {
     const sources = [];
     for (const p of parts) {
         if (s.fallthrough !== null && ((isAttrs(p) && s.comp.inheritAttrs) || dollarAttrs(s, p))) {
@@ -105,7 +114,7 @@ function childAttrsArg(s, child, parts, merges, fallthrough, ids) {
     }
     if (!takesAttrs(child)) {
         if (sources.length)
-            throw new GenError(`${s.comp.file}: ${child.name} is passed attributes it does not take`);
+            fail(s.comp, "FV0508", `${child.name} is passed attributes it does not take`, n);
         return ids;
     }
     if (!sources.length)
@@ -124,30 +133,33 @@ export function extraParams(c) {
     return (takesSlots(c) ? ", fv_slots: Slots<'_>" : "") + paramsOf(c).map((p) => `, ${p.name}: ${p.ty}`).join("");
 }
 export function callChild(s, e, child, propsCode, slots, attrs) {
+    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";
+    callWith(s, e, child, m, `${m}::${render}(out, ${propsCode}`, `${m}::Slots`, trailing, slots);
+}
+export function callWith(s, e, child, m, head, slotsTy, trailing, slots, vnode = false) {
     const given = new Map();
     if (slots && slots.type !== "NullLiteral") {
         if (slots.type !== "ObjectExpression")
-            fail(s.comp, "slots must be an object literal", slots);
+            fail(s.comp, "FV0901", "slots must be an object literal", slots);
         for (const p of slots.properties) {
             const key = p.key?.type === "Identifier" ? p.key.name : p.key?.value;
             if (key === "_")
                 continue;
             if (p.type !== "ObjectProperty" || p.computed)
-                fail(s.comp, "slots hold plain keys", p);
+                fail(s.comp, "FV0902", "slots hold plain keys", p);
             if (!child.slotNames.includes(key))
-                fail(s.comp, `${child.name} has no slot \`${key}\``, p);
+                fail(s.comp, "FV0903", `${child.name} has no slot \`${key}\``, p);
             given.set(key, p.value);
         }
     }
-    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";
     if (!takesSlots(child)) {
-        e.stmt(`${m}::${render}(out, ${propsCode}${trailing});`);
+        e.stmt(`${head}${trailing});`);
         return;
     }
-    e.open(`${m}::${render}(out, ${propsCode}, ${m}::Slots`);
+    e.open(`${head}, ${slotsTy}`);
     for (const name of child.slotNames) {
         const field = snake(name);
         const value = given.get(name);
@@ -182,7 +194,7 @@ export function callChild(s, e, child, propsCode, slots, attrs) {
             if (param?.type === "ObjectPattern") {
                 for (const p of param.properties) {
                     if (p.type !== "ObjectProperty" || p.computed || p.value.type !== "Identifier") {
-                        fail(s.comp, "slot props are destructured into plain names, without defaults", p);
+                        fail(s.comp, "FV0904", "slot props are destructured into plain names, without defaults", p);
                     }
                     locals.set(p.value.name, fieldVal(s.comp, sp, ty, p.key.name ?? p.key.value, p));
                 }
@@ -191,19 +203,19 @@ export function callChild(s, e, child, propsCode, slots, attrs) {
                 locals.set(param.name, { code: sp, ty });
             }
             else if (!takesNone)
-                fail(s.comp, "slot props are a name or an object pattern", param);
+                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`);
             const opened = e.lines.length - 1;
-            content({ ...s, locals, sid });
+            content({ ...s, locals, sid, vnode });
             unread(opened, sp);
             unread(opened, sid);
             e.close("),");
             continue;
         }
         if (!takesNone)
-            fail(s.comp, `\`<slot${name === "default" ? "" : ` name="${name}"`}>\` in ${child.name} passes no props`, param);
-        const inner = { ...s, sid };
+            fail(s.comp, "FV0906", `\`<slot${name === "default" ? "" : ` name="${name}"`}>\` in ${child.name} passes no props`, param);
+        const inner = { ...s, sid, vnode };
         if (sid !== null) {
             e.open(`${field}: Some(fv::Slot::slotted(&|out: &mut String${sidParam}| -> bool`);
             const opened = e.lines.length - 1;
@@ -227,14 +239,15 @@ export function callChild(s, e, child, propsCode, slots, attrs) {
     e.close(`${trailing});`);
 }
 export function ownInto(comp, v, want, node) {
+    holdsNothing(comp, v, want, node, "the prop");
+    if (want.k === "opt" && nothing(v.ty))
+        return "None";
     if (want.k === "str") {
         if (v.ty.k !== "str")
-            fail(comp, "a string prop needs a string", node);
+            fail(comp, "FV0509", "a string prop needs a string", node);
         return `std::borrow::Cow::Borrowed(${bare(v.code)})`;
     }
     if (want.k === "opt" && want.of.k === "str") {
-        if (v.ty.k === "undef")
-            return "None";
         if (v.ty.k === "str")
             return `Some(std::borrow::Cow::Borrowed(${bare(v.code)}))`;
         if (v.ty.k === "opt" && v.ty.of.k === "str")
@@ -257,7 +270,7 @@ export function ownInto(comp, v, want, node) {
     if (want.k === "opt" && objecty(want.of) && sameTy(v.ty, want.of))
         return `Some(${atom(v.code)}.to_owned())`;
     if (objecty(want) && v.ty.k === want.k && JSON.stringify(v.ty).includes('"struct"')) {
-        fail(comp, `a ${JSON.stringify(v.ty)} where the child takes a ${JSON.stringify(want)}: two components share a type only when both import it from one \`.ts\` file`, node);
+        fail(comp, "FV0510", `a ${JSON.stringify(v.ty)} where the child takes a ${JSON.stringify(want)}: two components share a type only when both import it from one \`.ts\` file`, node);
     }
     if (want.k === "list" && v.ty.k === "list" && v.ty.of.k === "undef")
         return "Vec::new()";
@@ -269,5 +282,5 @@ export function ownInto(comp, v, want, node) {
         if (want.of.k === "int" || want.of.k === "float" || want.of.k === "bool")
             return `${atom(v.code)}.to_vec()`;
     }
-    return fail(comp, `a ${JSON.stringify(v.ty)} into a ${JSON.stringify(want)} prop`, node);
+    return fail(comp, "FV0511", `a ${JSON.stringify(v.ty)} into a ${JSON.stringify(want)} prop`, node);
 }

package/dist/classes.js

@@ -1,5 +1,5 @@
 import { escapeHtml } from "@vue/shared";
-import { fail, rustStr, STR } from "./model.js";
+import { fail, nothing, rustStr, STR } from "./model.js";
 import { expr } from "./expr.js";
 import { cond, known, truthy } from "./narrowing.js";
 import { meet } from "./strings.js";
@@ -25,10 +25,10 @@ export function classItems(s, n) {
                 const keys = [];
                 const entries = n.properties.map((p) => {
                     if (p.type !== "ObjectProperty")
-                        fail(s.comp, "a class object holds `name: condition` pairs", p);
+                        fail(s.comp, "FV1001", "a class object holds `name: condition` pairs", p);
                     const key = p.computed ? expr(s, p.key) : { code: rustStr(p.key.type === "Identifier" ? p.key.name : String(p.key.value)), ty: STR };
                     if (key.ty.k !== "str")
-                        fail(s.comp, "a computed class name is a string", p.key);
+                        fail(s.comp, "FV1002", "a computed class name is a string", p.key);
                     for (const other of keys)
                         meet(s.comp, other, key, "a class object's names", p.key, "equal");
                     keys.push(key);
@@ -38,18 +38,18 @@ export function classItems(s, n) {
             }
             return n.properties.flatMap((p) => {
                 if (p.type !== "ObjectProperty")
-                    fail(s.comp, "a class object holds `name: condition` pairs", p);
+                    fail(s.comp, "FV1001", "a class object holds `name: condition` pairs", p);
                 let name;
                 if (!p.computed) {
                     const key = p.key.type === "Identifier" ? p.key.name : String(p.key.value);
                     if (key !== key.trim() || !key)
-                        fail(s.comp, `class name \`${key}\` has spaces around it`, p);
+                        fail(s.comp, "FV1003", `class name \`${key}\` has spaces around it`, p);
                     name = { lit: key };
                 }
                 else {
                     const k = expr(s, p.key);
                     if (k.ty.k !== "str")
-                        fail(s.comp, "a computed class name is a string", p.key);
+                        fail(s.comp, "FV1002", "a computed class name is a string", p.key);
                     name = { code: `fv::js_trim(${strArg(k.code)})` };
                 }
                 const v = expr(s, p.value);
@@ -77,9 +77,9 @@ export function classItems(s, n) {
         return [{ code: v.code }];
     if (v.ty.k === "opt" && v.ty.of.k === "str")
         return [{ code: `${atom(v.code)}.unwrap_or("")` }];
-    if (v.ty.k === "undef")
+    if (nothing(v.ty))
         return [];
-    return fail(s.comp, "a class is a string, an array, or an object of conditions", n);
+    return fail(s.comp, "FV1004", "a class is a string, an array, or an object of conditions", n);
 }
 function conditional(test, items) {
     if (test === "true" || test === "false")
@@ -123,7 +123,7 @@ export function classPresent(s, n) {
             break;
     }
     const v = expr(s, n);
-    if (v.ty.k === "undef")
+    if (nothing(v.ty))
         return "false";
     if (v.ty.k === "opt")
         return `${atom(v.code)}.is_some()`;
@@ -170,7 +170,7 @@ export function classAttr(s, n, side) {
             return `if ${condition(cond(s, n.test))} { ${classAttr(s, n.consequent, side)} } else { ${classAttr(s, n.alternate, side)} }`;
     }
     const v = expr(s, n);
-    if (v.ty.k === "str" || v.ty.k === "undef" || (v.ty.k === "opt" && v.ty.of.k === "str"))
+    if (v.ty.k === "str" || nothing(v.ty) || (v.ty.k === "opt" && v.ty.of.k === "str"))
         return valueAttr(s, v, n);
-    return fail(s.comp, "a class is a string, an array, or an object of conditions", n);
+    return fail(s.comp, "FV1004", "a class is a string, an array, or an object of conditions", n);
 }

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/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, GenError, generate, loadConfig, VERSION, write } from "./compiler.js";
+import { CONFIG_FILE, generate, loadConfig, VERSION, write } from "./compiler.js";
 import { unifiedDiff } from "./diff.js";
+import { diagnose, formatRefusal, isRefusal } from "./diagnostics.js";
 const root = process.cwd();
 const HELP = `Usage: ferrovue [command] [options]
 
@@ -14,16 +15,23 @@ Commands:
 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
 `;
+let json = false;
+function emit(result) {
+    console.log(JSON.stringify({ diagnostics: [], ...result }));
+}
 function report(e) {
-    if (e instanceof GenError || e instanceof SyntaxError)
-        console.error(`error: ${e.message}`);
-    else
+    if (!isRefusal(e))
         throw e;
+    if (json)
+        emit({ diagnostics: [diagnose(e)] });
+    else
+        console.error(formatRefusal(e));
 }
 function initProject(targetRoot, configPath) {
     const configFile = configPath ? resolve(targetRoot, configPath) : join(targetRoot, CONFIG_FILE);
@@ -77,6 +85,10 @@ function check(config, showDiff = false) {
         }
     });
     const extra = have.filter((name) => !want.has(name));
+    if (json) {
+        emit({ out: config.out, stale: stale.map((name) => `${config.out}/${name}`), notGenerated: extra.map((name) => `${config.out}/${name}`) });
+        return stale.length || extra.length ? 1 : 0;
+    }
     if (stale.length || extra.length) {
         const committed = (name) => {
             try {
@@ -104,6 +116,8 @@ function check(config, showDiff = false) {
 }
 function once(config) {
     const { files, changed, removed } = write(root, config);
+    if (json)
+        return emit({ out: config.out, files, changed, removed });
     const what = changed.length || removed.length ? `${changed.length} changed, ${removed.length} removed` : "nothing changed";
     console.log(`${config.out}: ${files.length} files, ${what}`);
 }
@@ -137,7 +151,7 @@ function watchProject(configPath) {
             clearTimeout(timer);
         timer = setTimeout(run, 50);
     });
-    console.log("watching for changes (Ctrl-C to stop)");
+    (json ? console.error : console.log)("watching for changes (Ctrl-C to stop)");
 }
 try {
     const rawArgs = process.argv.slice(2);
@@ -155,6 +169,14 @@ try {
         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);
         }
@@ -169,6 +191,10 @@ try {
         console.error("error: '--diff' requires '--check'");
         process.exit(1);
     }
+    if ((args.includes("--diff") || args.includes("-d")) && json) {
+        console.error("error: '--diff' writes text, and does not combine with '--format json'");
+        process.exit(1);
+    }
     if (args.includes("--version") || args.includes("-v")) {
         console.log(VERSION);
     }

package/dist/client.d.ts

@@ -1,7 +1,7 @@
 import { type App, type Component, type Plugin } from "vue";
 import type { Pinia } from "pinia";
 import type { Router } from "vue-router";
-/** Give Pinia the state the server rendered with — what `ferrovue::state_script_into` wrote — before
+/** 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;
 export interface MountOptions {
@@ -18,7 +18,7 @@ export interface MountOptions {
      * those given or its props are malformed. 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
+/** A component, or a function that loads one (`() => import("./Counter.vue")`), so that the code
  * of an island not on the page is never fetched. A function is taken for a loader as vue-router
  * takes one for a lazy route: unless it has `props` or `displayName`, which mark a functional
  * component, or `__vccOpts`, a class component. `ferrovue/islands` maps the name of every island
@@ -38,3 +38,36 @@ export interface Islands {
  * 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. */
 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
+ * compile the default slot, so anything may go there: a component library's components, code that
+ * reads `window`. The swap happens only where Vue runs on the page, as in an island. */
+export declare const ClientOnly: Component;
+/** One component the server rendered into a slot of a page's layout, as `ferrovue::Part` records
+ * it: its name (`c`) and the props it was rendered from (`p`). */
+export interface PagePart {
+    c: string;
+    p: Record<string, unknown>;
+}
+/** What `ferrovue::PageRecord` writes: the layout's props, and each slot's parts in order. */
+export interface PageRecord {
+    props: Record<string, unknown>;
+    slots: Record<string, PagePart[]>;
+}
+export interface PageOptions extends Pick<MountOptions, "pinia" | "router" | "plugins"> {
+    /** The element holding the layout's root, or a selector for it: `#app` by default. */
+    container?: Element | string;
+    /** The `id` of the record's script, as given to `PageRecord::script_into`: `__fv_page` by default. */
+    record?: string;
+    /** The document to read the page from. */
+    doc?: Document;
+}
+/** 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;
+/** 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>;