ferrovue 0.1.0 → 0.2.0

package/dist/component.d.ts

@@ -0,0 +1,6 @@
+import { type Component, type N } from "./model.ts";
+export declare function readComponent(file: string, root: string): {
+    comp: Component;
+    ast: N[];
+    ssr: string;
+};

package/dist/component.js

@@ -0,0 +1,251 @@
+/* One `.vue` file read: its props, models, imported types, and Vue's SSR compilation of its template. */
+import { compileScript, compileTemplate, parse as parseSfc } from "@vue/compiler-sfc";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { SourceMapConsumer } from "source-map-js";
+import { basename, relative, resolve, sep } from "node:path";
+import { fail, opt, snake, tagAst } from "./model.js";
+import { ctx } from "./context.js";
+import { typesImports, declareTypes, defaultValue, definePropsType, readTypeFile, resolveImport, runtimeDefaults, structOf, tyOfTs } from "./typescript.js";
+/** A Vue compiler error's position as a node \`fail\` can point at: its line and 1-based column,
+ * offset by where the template starts when the error is in the template's content. */
+function vueErrorNode(err, within) {
+    const loc = err.loc;
+    if (!loc)
+        return undefined;
+    const { line, column } = loc.start;
+    const at = !within ? { line, column: column - 1 } : line === 1 ? { line: within.line, column: within.column - 1 + column - 1 } : { line: within.line + line - 1, column: column - 1 };
+    return { type: "VueError", loc: { start: at }, __fv: "source" };
+}
+/** `getHash` in `@vitejs/plugin-vue`: the first 8 hex digits of the SHA-256 of the file's path from
+ * Vite's root, with `/` between its parts, followed in `"filepath-source"` mode by its source. */
+function scopeHash(file, source) {
+    const path = relative(ctx.viteRoot, resolve(file)).split(sep).join("/");
+    return createHash("sha256")
+        .update(ctx.scopeId === "filepath" ? path : path + source)
+        .digest("hex")
+        .slice(0, 8);
+}
+/** `inheritAttrs` as `defineOptions({ inheritAttrs })` or a plain `<script>`'s `export default`
+ * sets it: a literal, since it decides what reaches the root. */
+function inheritAttrs(comp, statements) {
+    let found = true;
+    for (const st of statements) {
+        const call = st.type === "ExpressionStatement" ? st.expression : null;
+        const options = call?.type === "CallExpression" && call.callee.type === "Identifier" && call.callee.name === "defineOptions"
+            ? call.arguments[0]
+            : st.type === "ExportDefaultDeclaration"
+                ? st.declaration
+                : null;
+        if (options?.type !== "ObjectExpression")
+            continue;
+        for (const p of options.properties) {
+            if (p.type !== "ObjectProperty" || p.computed || (p.key.name ?? p.key.value) !== "inheritAttrs")
+                continue;
+            if (p.value.type !== "BooleanLiteral")
+                fail(comp, "`inheritAttrs` is `true` or `false`", p.value);
+            found = p.value.value;
+        }
+    }
+    return found;
+}
+export function readComponent(file, root) {
+    const name = basename(file, ".vue");
+    const source = readFileSync(file, "utf8");
+    const { descriptor, errors } = parseSfc(source, { filename: file });
+    const rel = relative(root, file);
+    const comp = {
+        name,
+        module: snake(name),
+        file: rel,
+        props: { name: "Props", fields: [] },
+        structs: new Map(),
+        trustedName: null,
+        floatName: null,
+        childProps: new Map(),
+        imports: new Set(),
+        slotNames: [],
+        routerView: false,
+        routerLink: false,
+        readsRoute: false,
+        usesRoute: false,
+        readsStores: false,
+        usesStores: false,
+        readsI18n: false,
+        usesI18n: false,
+        readsTeleports: false,
+        usesTeleports: false,
+        models: new Map(),
+        aliases: new Map(),
+        importedTypes: new Map(),
+        slotShapes: new Map(),
+        scopeId: null,
+        slotted: false,
+        inheritAttrs: true,
+        inherits: false,
+        passesSlotIds: false,
+    };
+    comp.source = source;
+    if (errors.length)
+        fail(comp, String(errors[0]), vueErrorNode(errors[0]));
+    if (!descriptor.scriptSetup || !descriptor.template) {
+        fail(comp, "an island needs `<script setup lang=\"ts\">` and a `<template>`");
+    }
+    // A global `<style>` block changes no markup. A scoped one adds `data-v-…` attributes, whose id is
+    // computed here as the bundler computes it. A CSS module renames classes, and `v-bind()` in CSS
+    // writes variables onto the root, neither of which the server reproduces.
+    for (const st of descriptor.styles) {
+        if (st.module)
+            fail(comp, "`<style module>` renames classes in the bundler; use a global or scoped `<style>`, or a stylesheet");
+    }
+    if (descriptor.cssVars.length)
+        fail(comp, "`v-bind()` in `<style>` sets variables the server does not render; bind `:style` instead");
+    if (descriptor.styles.some((st) => st.scoped))
+        comp.scopeId = `data-v-${scopeHash(file, source)}`;
+    comp.slotted = descriptor.slotted;
+    const script = compileScript(descriptor, { id: name });
+    const ast = script.scriptSetupAst ?? [];
+    tagAst(ast, "source");
+    // A plain `<script>` beside the setup one may declare the types the setup block uses.
+    const plainAst = script.scriptAst ?? [];
+    tagAst(plainAst, "source");
+    for (const s of [...plainAst, ...ast]) {
+        if (s.type !== "ImportDeclaration" || !s.source.value.endsWith(".vue"))
+            continue;
+        const from = basename(s.source.value, ".vue");
+        if (s.specifiers.some((sp) => sp.type === "ImportDefaultSpecifier"))
+            comp.imports.add(from);
+        for (const sp of s.specifiers) {
+            if (sp.type === "ImportSpecifier" && (sp.imported.name ?? sp.imported.value) === "Props") {
+                comp.childProps.set(sp.local.name, from);
+            }
+        }
+    }
+    typesImports(comp, [...plainAst, ...ast]);
+    comp.inheritAttrs = inheritAttrs(comp, [...plainAst, ...ast]);
+    // Types imported from elsewhere: a store's file, a shared `.ts` file, or another component.
+    for (const st of [...plainAst, ...ast]) {
+        if (st.type !== "ImportDeclaration")
+            continue;
+        const from = st.source.value;
+        for (const sp of st.specifiers) {
+            if (sp.type !== "ImportSpecifier")
+                continue;
+            const typeName = sp.imported.name ?? sp.imported.value;
+            if (from.endsWith(".vue")) {
+                if (typeName !== "Props")
+                    comp.importedTypes.set(sp.local.name, { k: "struct", name: typeName, home: basename(from, ".vue") });
+                continue;
+            }
+            const isType = st.importKind === "type" || sp.importKind === "type";
+            const typeFile = resolveImport(comp.file, from);
+            if (!typeFile)
+                continue;
+            const module = typeFile.replace(/\.ts$/, "");
+            if ([...ctx.stores.values()].some((x) => x.module === module)) {
+                if (ctx.storeStructs.has(typeName))
+                    comp.importedTypes.set(sp.local.name, { k: "struct", name: typeName, store: true });
+                continue;
+            }
+            if (ctx.helperModule !== null && from === ctx.helperModule && !isType)
+                continue;
+            readTypeFile(typeFile);
+            if (ctx.typeStructs.has(typeName))
+                comp.importedTypes.set(sp.local.name, { k: "struct", name: typeName, home: "types" });
+            else if (ctx.typeAliases.has(typeName))
+                comp.aliases.set(sp.local.name, ctx.typeAliases.get(typeName));
+        }
+    }
+    // Interfaces in two passes: every name first, so one may name another declared after it, or
+    // itself — a tree node's children are tree nodes.
+    const decls = declareTypes(comp, [...plainAst, ...ast], comp.structs, comp.aliases);
+    for (const d of decls)
+        comp.structs.set(d.name, structOf(comp, d.name, d.members, comp.structs));
+    let propsTy = null;
+    for (const s of ast) {
+        const call = s.type === "ExpressionStatement" ? s.expression : s.type === "VariableDeclaration" ? s.declarations[0]?.init : null;
+        const inner = call?.type === "CallExpression" && call.callee.type === "Identifier" && call.callee.name === "withDefaults" ? call.arguments[0] : call;
+        if (inner?.type === "CallExpression" && inner.callee.type === "Identifier" && inner.callee.name === "defineProps" && !inner.typeParameters) {
+            fail(comp, "props are declared with a type, `defineProps<{ ... }>()`: a runtime declaration has no Rust type", inner);
+        }
+        const found = definePropsType(call);
+        if (found)
+            propsTy = found;
+    }
+    // A component without `defineProps` takes no props.
+    if (!propsTy) {
+        // nothing to read
+    }
+    else if (propsTy.type === "TSTypeLiteral") {
+        comp.props = structOf(comp, "Props", propsTy.members, comp.structs);
+    }
+    else if (propsTy.type === "TSTypeReference" && comp.structs.has(propsTy.typeName.name)) {
+        comp.props = { name: "Props", fields: comp.structs.get(propsTy.typeName.name).fields };
+    }
+    else {
+        fail(comp, "`defineProps` takes a type literal or an interface declared in the same block", propsTy);
+    }
+    // `defineModel`: a prop of its own (`modelValue` unless named), which the binding reads.
+    for (const st of ast) {
+        if (st.type !== "VariableDeclaration")
+            continue;
+        for (const d of st.declarations) {
+            const call = d.init;
+            if (call?.type !== "CallExpression" || call.callee.type !== "Identifier" || call.callee.name !== "defineModel")
+                continue;
+            const t = call.typeParameters?.params?.[0];
+            if (!t)
+                fail(comp, "`defineModel` needs its type: `defineModel<string>()`", call);
+            const named = call.arguments[0]?.type === "StringLiteral" ? call.arguments[0].value : "modelValue";
+            const options = call.arguments.find((a) => a.type === "ObjectExpression");
+            const required = options?.properties.some((p) => p.type === "ObjectProperty" && (p.key.name ?? p.key.value) === "required" && p.value.type === "BooleanLiteral" && p.value.value);
+            const base = tyOfTs(comp, t, comp.structs);
+            comp.props.fields.push({ js: named, rust: snake(named), ty: required ? base : opt(base) });
+            comp.models.set(d.id.name, named);
+        }
+    }
+    // What Vue uses for an absent optional prop: the default `compileScript` resolved — from
+    // `withDefaults`, a destructured default, or `defineModel`'s options — or `false` for a boolean.
+    const defaults = runtimeDefaults(comp, script.content);
+    for (const f of comp.props.fields) {
+        if (f.ty.k !== "opt")
+            continue;
+        const node = defaults.get(f.js);
+        if (node)
+            f.dflt = defaultValue(comp, f, node);
+        else if (f.ty.of.k === "bool")
+            f.dflt = "false";
+    }
+    const compiled = compileTemplate({
+        source: descriptor.template.content,
+        filename: file,
+        // As `@vitejs/plugin-vue` compiles it: the scope id written onto every element, and passed to
+        // slot content only with `:slotted()` styles.
+        id: comp.scopeId ?? name,
+        scoped: comp.scopeId !== null,
+        slotted: comp.slotted,
+        ssr: true,
+        ssrCssVars: [],
+        compilerOptions: { bindingMetadata: script.bindings, sourceMap: true },
+    });
+    const start = descriptor.template.loc.start;
+    comp.templateStart = { line: start.line, column: start.column };
+    if (compiled.map)
+        comp.templateMap = new SourceMapConsumer(compiled.map);
+    // A template error's position is within the template's content.
+    if (compiled.errors.length)
+        fail(comp, String(compiled.errors[0]), vueErrorNode(compiled.errors[0], comp.templateStart));
+    for (const m of compiled.code.matchAll(/_ssrRenderSlot\(_ctx\.\$slots, "([^"]+)"/g)) {
+        if (!comp.slotNames.includes(m[1]))
+            comp.slotNames.push(m[1]);
+    }
+    // Resolved by name, as globally registered components are, or imported from `vue-router`.
+    const imported = (exported) => [...plainAst, ...ast].some((st) => st.type === "ImportDeclaration" && st.source.value === "vue-router" &&
+        st.specifiers.some((sp) => sp.type === "ImportSpecifier" && (sp.imported.name ?? sp.imported.value) === exported));
+    comp.routerLink = compiled.code.includes('_resolveComponent("RouterLink")') || imported("RouterLink");
+    comp.routerView = compiled.code.includes('_resolveComponent("RouterView")') || imported("RouterView");
+    comp.readsRoute = compiled.code.includes("_ctx.$route");
+    comp.readsI18n = compiled.code.includes("_ctx.$t(");
+    comp.readsTeleports = compiled.code.includes("_ssrRenderTeleport(");
+    return { comp, ast, ssr: compiled.code };
+}

package/dist/context.d.ts

@@ -0,0 +1,151 @@
+import type { I18nSetup } from "./i18n.ts";
+import { type Component, type N, type Struct, type Ty } from "./model.ts";
+/** A type a helper takes or returns, as the configuration spells it. */
+export type TypeName = "string" | "string?" | "int" | "int?" | "float" | "float?" | "bool";
+/** A function a template may call, and the Rust function that is its twin. */
+export interface HelperSpec {
+    /** The Rust path the generated code calls, e.g. `crate::helpers::format_count`. */
+    rust: string;
+    params: TypeName[];
+    returns: TypeName;
+    /** The longest string it returns, which is what a call adds to the buffer reservation. */
+    maxLen?: number;
+}
+/** What `ferrovue.config.json` holds. Paths are relative to the project root. */
+export interface Config {
+    /** The directory of `.vue` files to compile. */
+    components: string;
+    /** The directory the Rust modules are written to. Everything in it is replaced. */
+    out: string;
+    /** The module components import their helpers from, and the Rust twin of each export. */
+    helpers?: {
+        module: string;
+        functions: Record<string, HelperSpec>;
+    };
+    /** The Rust type a `TrustedHtml` prop is, which must implement `ferrovue::TrustedHtml`, e.g.
+     * `crate::sanitize::SafeHtml`. A type that borrows names the props' lifetime, `'a`:
+     * `crate::render::Trusted<'a>`. Without it, a component cannot use `v-html` at all. */
+    trustedHtml?: string;
+    /** A JSON file listing the app's routes as vue-router paths (`/users/:id`), which `<RouterLink>`
+     * resolves against. Without it, a component cannot use `<RouterLink>`. */
+    routes?: string;
+    /** The router, in full: its routes file, the history's base, and the class names
+     * `createRouter` gives active links. `routes` alone is shorthand for `{ routes }`. */
+    router?: {
+        routes: string;
+        base?: string;
+        linkActiveClass?: string;
+        linkExactActiveClass?: string;
+    };
+    /** The directory of Pinia stores (`.ts` files), whose state a component may read while it renders
+     * on the server. */
+    stores?: string;
+    /** Custom directives that render nothing on the server — no `getSSRProps` — by name, without
+     * `v-`: `["focus", "click-outside"]`. Any other custom directive is refused, since the server
+     * cannot know what its `getSSRProps` would add. */
+    clientDirectives?: string[];
+    /** vue-i18n: the directory of locale files (\`en.json\`, \`nl.json\`), the locale a page renders in
+     * when it names none, and the locales a missing message falls back to. */
+    i18n?: {
+        messages: string;
+        locale?: string;
+        fallbackLocale?: string | string[];
+    };
+    /** How a `<style scoped>` component's `data-v-` id is computed, which must be how
+     * `@vitejs/plugin-vue` computes it for the client: from the file's path (`"filepath"`, the
+     * plugin's choice in development, and with `features.componentIdGenerator: "filepath"`), or its
+     * path and source (`"filepath-source"`, the plugin's choice for a production build). */
+    scopeId?: ScopeIdMode;
+    /** Vite's root, from which a scope id hashes a component's path: the project root by default. */
+    viteRoot?: string;
+}
+export type ScopeIdMode = "filepath" | "filepath-source";
+export declare const CONFIG_FILE = "ferrovue.config.json";
+/** Read the project's configuration. */
+export declare function loadConfig(root: string): Config;
+export declare function tyOfName(name: TypeName): Ty;
+/** A route as the routes file lists it: a vue-router path, and the name it may have. */
+export interface RouteDef {
+    /** The path as written: relative to the parent's unless it starts with \`/\`. */
+    path: string;
+    name?: string;
+    /** The routes nested in it. */
+    children?: RouteDef[];
+    /** The path with its ancestors', as vue-router normalises it. */
+    fullPath: string;
+}
+/** Every route, nested ones included, parents first. */
+export declare function allRoutes(routes: RouteDef[]): RouteDef[];
+/** A getter: the parameter naming the state (an option store's), and the expression it returns.
+ * \`setup\` marks a setup store's \`computed\`, which reads the state's refs and the other getters by
+ * name, through \`.value\`. */
+export interface StoreGetter {
+    param: string | null;
+    body: N;
+    file: string;
+    setup?: true;
+}
+/** A Pinia option store: `export const usePrefs = defineStore("prefs", { state: (): PrefsState => ... })`. */
+export interface Store {
+    /** `usePrefs` */
+    hook: string;
+    /** `prefs`: its key in `pinia.state.value`. */
+    id: string;
+    /** `prefs`: its field in the generated `Stores`. */
+    field: string;
+    /** `PrefsState`: the interface its state is. */
+    state: string;
+    /** The file, without its extension, as an import names it once resolved. */
+    module: string;
+    /** Its getters: name → the parameter that names the state, and the expression returned. */
+    getters: Map<string, StoreGetter>;
+}
+/** Where `TrustedHtml` comes from. Only that import names the type `v-html` will write raw. */
+export declare const TYPES_MODULE = "ferrovue/types";
+/** What the configuration being compiled says, and what has been read so far: set up by
+ * `generate()` at the start of each run, which is synchronous, so one run never sees another's. */
+export declare const ctx: {
+    /** The helpers of the configuration being compiled: name → Rust twin, typed. */
+    helpers: Record<string, {
+        rust: string;
+        params: Ty[];
+        ret: Ty;
+        maxLen: number;
+    }>;
+    helperModule: string | null;
+    trustedHtml: string | null;
+    /** Custom directives declared to render nothing on the server. */
+    clientDirectives: Set<string>;
+    /** The configured routes, when there are any. */
+    routes: RouteDef[] | null;
+    /** The history's base, and the class names active links take, from the configured router. */
+    routerBase: string;
+    linkActive: string;
+    linkExactActive: string;
+    /** The configured stores, by hook name, and every interface their files declare. */
+    stores: Map<string, Store>;
+    storeStructs: Map<string, Struct>;
+    /** The store file each of those interfaces is declared in. */
+    storeFiles: Map<string, string>;
+    /** The project root, for resolving a component's imports. */
+    rootDir: string;
+    /** Interfaces and object types declared in shared `.ts` files that components import, and type
+     * aliases there; the file each comes from. They are written once, to `types.rs`. */
+    typeStructs: Map<string, Struct>;
+    typeAliases: Map<string, any>;
+    typeFiles: Map<string, string>;
+    /** The shared files read so far. */
+    typeRead: Set<string>;
+    /** Every component being compiled, by name, for a type that names another one's props. */
+    components: Map<string, Component>;
+    /** Numbers the bindings narrowing introduces, restarted per component so that a file's text
+     * depends on its own source alone. */
+    narrowCount: number;
+    /** The directory the components being compiled come from, for the generated headers. */
+    componentsDir: string;
+    /** The configured locales and their messages, when there are any. */
+    i18n: I18nSetup | null;
+    /** How scope ids are computed, and the directory a component's path is hashed from. */
+    scopeId: ScopeIdMode;
+    viteRoot: string;
+};

package/dist/context.js

@@ -0,0 +1,84 @@
+/* The project's configuration, and the state one `generate()` run builds up. */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { BOOL, FLOAT, GenError, INT, opt, STR } from "./model.js";
+export const CONFIG_FILE = "ferrovue.config.json";
+/** Read the project's configuration. */
+export function loadConfig(root) {
+    const raw = JSON.parse(readFileSync(join(root, CONFIG_FILE), "utf8"));
+    if (typeof raw.components !== "string" || typeof raw.out !== "string") {
+        throw new GenError(`${CONFIG_FILE} needs \`components\` and \`out\` directories`);
+    }
+    if (raw.scopeId !== undefined && raw.scopeId !== "filepath" && raw.scopeId !== "filepath-source") {
+        throw new GenError(`\`scopeId\` in ${CONFIG_FILE} is "filepath" or "filepath-source", as \`@vitejs/plugin-vue\` computes it`);
+    }
+    return raw;
+}
+export function tyOfName(name) {
+    switch (name) {
+        case "string":
+            return STR;
+        case "string?":
+            return opt(STR);
+        case "int":
+            return INT;
+        case "int?":
+            return opt(INT);
+        case "float":
+            return FLOAT;
+        case "float?":
+            return opt(FLOAT);
+        case "bool":
+            return BOOL;
+        default:
+            throw new GenError(`unknown helper type \`${String(name)}\``);
+    }
+}
+/** Every route, nested ones included, parents first. */
+export function allRoutes(routes) {
+    return routes.flatMap((r) => [r, ...allRoutes(r.children ?? [])]);
+}
+/** Where `TrustedHtml` comes from. Only that import names the type `v-html` will write raw. */
+export const TYPES_MODULE = "ferrovue/types";
+/** What the configuration being compiled says, and what has been read so far: set up by
+ * `generate()` at the start of each run, which is synchronous, so one run never sees another's. */
+export const ctx = {
+    /** The helpers of the configuration being compiled: name → Rust twin, typed. */
+    helpers: {},
+    helperModule: null,
+    trustedHtml: null,
+    /** Custom directives declared to render nothing on the server. */
+    clientDirectives: new Set(),
+    /** The configured routes, when there are any. */
+    routes: null,
+    /** The history's base, and the class names active links take, from the configured router. */
+    routerBase: "",
+    linkActive: "router-link-active",
+    linkExactActive: "router-link-exact-active",
+    /** The configured stores, by hook name, and every interface their files declare. */
+    stores: new Map(),
+    storeStructs: new Map(),
+    /** The store file each of those interfaces is declared in. */
+    storeFiles: new Map(),
+    /** The project root, for resolving a component's imports. */
+    rootDir: "",
+    /** Interfaces and object types declared in shared `.ts` files that components import, and type
+     * aliases there; the file each comes from. They are written once, to `types.rs`. */
+    typeStructs: new Map(),
+    typeAliases: new Map(),
+    typeFiles: new Map(),
+    /** The shared files read so far. */
+    typeRead: new Set(),
+    /** Every component being compiled, by name, for a type that names another one's props. */
+    components: new Map(),
+    /** Numbers the bindings narrowing introduces, restarted per component so that a file's text
+     * depends on its own source alone. */
+    narrowCount: 0,
+    /** The directory the components being compiled come from, for the generated headers. */
+    componentsDir: "",
+    /** The configured locales and their messages, when there are any. */
+    i18n: null,
+    /** How scope ids are computed, and the directory a component's path is hashed from. */
+    scopeId: "filepath-source",
+    viteRoot: "",
+};

package/dist/emitter.d.ts

@@ -0,0 +1,23 @@
+/** Statements, with adjacent literal pushes merged into one `push_str`. */
+export declare class Emitter {
+    lines: string[];
+    /** Bytes of markup written once per render, part of what `render` reserves up front: the literal
+     * markup, and what the numbers written at run time are expected to take. */
+    literalBytes: number;
+    /** Rust expressions for the rest of the reservation: a loop's markup once per item. */
+    perItem: string[];
+    private pending;
+    private depth;
+    lit(s: string): void;
+    /** `bytes` more expected of a value written at run time. */
+    expect(bytes: number): void;
+    stmt(code: string): void;
+    open(code: string): void;
+    close(tail?: string): void;
+    /** Whether the lines from \`from\` on read \`name\`. Literals are skipped, so markup that happens to
+     * spell the name does not count, and so are fields of that name. */
+    reads(name: string, from: number): boolean;
+    /** Replace \`from\` with \`to\` in line \`index\`: an unused binding renamed to \`_\`. */
+    replace(index: number, from: string, to: string): void;
+    flush(): void;
+}

package/dist/emitter.js

@@ -0,0 +1,58 @@
+/* The Rust statements a render is written as. */
+import { rustChar, rustStr } from "./model.js";
+import { occurrences } from "./parens.js";
+/** Statements, with adjacent literal pushes merged into one `push_str`. */
+export class Emitter {
+    lines = [];
+    /** Bytes of markup written once per render, part of what `render` reserves up front: the literal
+     * markup, and what the numbers written at run time are expected to take. */
+    literalBytes = 0;
+    /** Rust expressions for the rest of the reservation: a loop's markup once per item. */
+    perItem = [];
+    pending = "";
+    depth = 1;
+    lit(s) {
+        this.pending += s;
+        this.literalBytes += Buffer.byteLength(s);
+    }
+    /** `bytes` more expected of a value written at run time. */
+    expect(bytes) {
+        this.literalBytes += bytes;
+    }
+    stmt(code) {
+        this.flush();
+        this.lines.push("    ".repeat(this.depth) + code);
+    }
+    open(code) {
+        this.stmt(code ? code + " {" : "{");
+        this.depth++;
+    }
+    close(tail = "") {
+        this.flush();
+        this.depth--;
+        this.lines.push("    ".repeat(this.depth) + "}" + tail);
+        // `} else {` closes one block and opens the next.
+        if (tail.endsWith("{"))
+            this.depth++;
+    }
+    /** Whether the lines from \`from\` on read \`name\`. Literals are skipped, so markup that happens to
+     * spell the name does not count, and so are fields of that name. */
+    reads(name, from) {
+        this.flush();
+        return occurrences(this.lines.slice(from).join("\n"), name) > 0;
+    }
+    /** Replace \`from\` with \`to\` in line \`index\`: an unused binding renamed to \`_\`. */
+    replace(index, from, to) {
+        // A function, so a `$&` or `$'` in the generated text is not read as a replacement pattern.
+        this.lines[index] = this.lines[index].replace(from, () => to);
+    }
+    flush() {
+        if (!this.pending)
+            return;
+        const text = this.pending;
+        this.pending = "";
+        // One character is pushed as a `char`.
+        const push = /^.$/su.test(text) ? `out.push(${rustChar(text)});` : `out.push_str(${rustStr(text)});`;
+        this.lines.push("    ".repeat(this.depth) + push);
+    }
+}

package/dist/expr.d.ts

@@ -0,0 +1,76 @@
+import { type Component, type N, type Scope, type Ty, type Val } from "./model.ts";
+/** The refusal for a string that may hold half of a surrogate pair, used where that half matters. */
+export declare function lonely(what: string): string;
+/** Two strings meeting, where a half of a surrogate pair — which ferrovue holds as U+FFFD — would
+ * change the result:
+ * - `equal`: two halves may differ, and a half never equals a literal U+FFFD;
+ * - `order`: a half orders as a surrogate, below U+E000, where U+FFFD orders above — the same only
+ *   against a literal of characters below U+D800, which both order after;
+ * - `search`: a half searched for (`b`) matches half of a whole pair in `a`;
+ * - `join`: two halves side by side join into one character.
+ * A string holding U+FFFD in the data still equals, or is found in, a half: README, "Strings". */
+export declare function meet(comp: Component, a: Val, b: Val, what: string, n: N, how: "equal" | "order" | "search" | "join"): void;
+/** Whether a string expression borrows from a temporary it builds — \`&*format!(…)\`, a call that
+ * returns a \`String\` — rather than from the props or the state. Such a borrow ends with the block
+ * it is in, so a branch of \`?:\` or \`||\` must hand back the string itself. */
+export declare function isTemporary(v: Val): boolean;
+/** A string as a \`Cow\`: borrowed when it lives on, owned when it is a temporary. The \`Cow\` is
+ * itself a temporary of the whole statement, so the \`&str\` taken from it lives to its end. A
+ * \`String\` built for the purpose is moved into it, and one that is already a \`Cow\` — a branch
+ * of \`?:\` or \`||\` — is taken as it is. */
+export declare function asCow(v: Val): string;
+/** Whether built code is a `Cow<str>` already: a runtime routine that borrows when it can
+ * (`js_slice`, `js_replace`, `js_pad_start`, …), or a fallback taken from one (`.unwrap_or(Cow…)`). */
+export declare function yieldsCow(code: string): boolean;
+/** Whether a value is a JavaScript number: an integer or a fraction. */
+export declare function isNumber(ty: Ty): boolean;
+/** A number as an `f64`, as JavaScript holds every number. */
+export declare function asF64(v: Val): string;
+/** A type as an error names it. */
+export declare function describeTy(ty: Ty): string;
+export declare function fieldVal(comp: Component, base: string, ty: Ty, js: string, node: N): Val;
+/** A value's truthiness when it is known at generation time: a boolean constant, a string literal,
+ * a number JavaScript computed. */
+export declare function known(v: Val): boolean | undefined;
+export declare function truthy(v: Val): string;
+/** A value passed where `want` is expected: a present value into an optional slot is wrapped. */
+export declare function coerce(comp: Component, v: Val, want: Ty, node: N): string;
+/** The JavaScript path an expression names — `$props.user`, `item.author.name` — or `null` when it
+ * is not a plain chain of names. */
+export declare function pathOf(n: N): string | null;
+/** A test that an optional value is present, as TypeScript narrows on it: `x`, `x !== undefined`,
+ * and, `negated`, `!x` and `x === undefined`, after which the value is present in the other branch. */
+export interface Presence {
+    path: string;
+    /** The value bound where it is present, and its type there. */
+    pattern: (name: string) => string;
+    /** The `Option` the pattern matches: the value, or for a truthiness test only its truthy values. */
+    option: string;
+    /** The test alone, for a branch that never reads the value. */
+    present: string;
+    of: Ty;
+    negated: boolean;
+    /** Tested by truthiness, so the test itself is a boolean only when it is negated. */
+    truthy: boolean;
+}
+export declare function presence(s: Scope, n: N): Presence | null;
+/** The scope with `p`'s value present, bound as `name`. */
+export declare function narrowTo(s: Scope, p: Presence, name: string): Scope;
+export declare function cond(s: Scope, n: N): string;
+export declare function childOf(name: string): Component;
+/** The reader's route, which the component then takes. */
+export declare function theRoute(s: Scope, n: N): Val;
+/** A field of the route: what `useRoute()` gives that the server knows as vue-router does. */
+export declare function routeField(s: Scope, base: Val, prop: string, n: N): Val;
+/** A Pinia getter read from a store's state, `prefs.doubled`: its expression, translated with the
+ * state it takes bound to that state. `null` when `name` is not a getter of that store. */
+export declare function storeGetter(s: Scope, base: Val, name: string, node: N): Val | null;
+/** A Rust string literal's text. */
+export declare function unquote(literal: string): string;
+export declare function expr(s: Scope, n: N): Val;
+/** A boolean computed at run time, or known now when it folded to a constant. */
+export declare function boolOf(code: string): Val;
+export declare function call(s: Scope, n: N): Val;
+/** Whether `n` is `Object.<method>(…)`. */
+export declare function isObjectCall(n: N, method: string): boolean;
+export declare function helperCall(s: Scope, name: string, args: N[], n: N): Val;