@frontiers-labs/argon 0.4.0

package/dist/lower.js

@@ -0,0 +1,1341 @@
+// Lowering: TypeScript AST → Argon IR.
+//
+// This is the single place that understands the source language. Value
+// expressions (template interpolations, setup statements, helper functions)
+// are lowered into typed IR with inference over the SSR-safe subset. Anything
+// outside the subset becomes an `opaque` node carrying the source text and a
+// ready-made diagnostic; event handlers are opaque by construction.
+import * as ts from "typescript";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { componentSignatures, findComponents } from "./component.js";
+import { processTemplate } from "./template.js";
+import { ArgonCompileError, diagnosticForNode } from "./diagnostics.js";
+import { containsJsx, isJsxRoot, jsxToTemplate, } from "./jsx.js";
+import { BOOLEAN, isMarkup, NUMBER, STRING, UNKNOWN, } from "./ir.js";
+import { ARRAY_METHODS, MATH_FNS, SSR_HINT, STRING_METHODS } from "./ssr-subset.js";
+export { SSR_HINT } from "./ssr-subset.js";
+class LowerError extends Error {
+    diagnostic;
+    constructor(diagnostic) {
+        super(diagnostic.message);
+        this.diagnostic = diagnostic;
+    }
+}
+export function lowerProgram(source, sourceText) {
+    return new Lowerer(source, sourceText).lower();
+}
+class Lowerer {
+    source;
+    sourceText;
+    structs = new Map();
+    tables = new Map();
+    fns = new Map();
+    cssConsts = new Set();
+    opaqueDecls = new Set();
+    decls = [];
+    scopes = [];
+    signatures = new Map();
+    namedImports = new Map();
+    resolvedComponents = new Map();
+    composedImports = new Set();
+    // Composition is a template feature; nested JSX outside component bodies
+    // (module helpers) cannot compose.
+    composing = false;
+    constructor(source, sourceText) {
+        this.source = source;
+        this.sourceText = sourceText;
+    }
+    lower() {
+        const imports = this.readImports();
+        this.signatures = componentSignatures(this.source);
+        const componentNames = new Set(this.signatures.keys());
+        // Pass 1: hoisted facts — interfaces and function signatures.
+        ts.forEachChild(this.source, node => {
+            if (ts.isInterfaceDeclaration(node)) {
+                try {
+                    this.registerStruct(node.name.text, node.members);
+                }
+                catch (error) {
+                    if (!(error instanceof LowerError))
+                        throw error;
+                }
+            }
+            else if (ts.isFunctionDeclaration(node) && node.name && !componentNames.has(node.name.text)) {
+                this.fns.set(node.name.text, this.fnSignature(node));
+            }
+        });
+        // Pass 2: declaration bodies in source order.
+        ts.forEachChild(this.source, node => {
+            if (ts.isFunctionDeclaration(node) && node.name && !componentNames.has(node.name.text)) {
+                this.lowerFn(node);
+            }
+            else if (ts.isVariableStatement(node)) {
+                for (const decl of node.declarationList.declarations)
+                    this.lowerConst(decl);
+            }
+        });
+        // Templates convert last, so composed components resolve against the
+        // full module context (structs, consts, helpers).
+        const components = findComponents(this.source, this.composeResolver);
+        const lowered = components.map(c => this.lowerComponent(c));
+        return {
+            source: this.source,
+            sourceText: this.sourceText,
+            imports,
+            composedImports: [...this.composedImports],
+            structs: this.structs,
+            decls: this.decls,
+            components: lowered,
+        };
+    }
+    readImports() {
+        const imports = [];
+        ts.forEachChild(this.source, node => {
+            if (!ts.isImportDeclaration(node) || !ts.isStringLiteral(node.moduleSpecifier))
+                return;
+            const bindings = node.importClause?.namedBindings;
+            if (bindings && ts.isNamedImports(bindings)) {
+                for (const element of bindings.elements) {
+                    this.namedImports.set(element.name.text, node.moduleSpecifier.text);
+                }
+            }
+            imports.push({
+                module: node.moduleSpecifier.text,
+                isArgon: node.moduleSpecifier.text === "@frontiers-labs/argon",
+                span: { start: node.getStart(this.source), end: node.getEnd() },
+            });
+        });
+        return imports;
+    }
+    // ── Component composition ───────────────────────────────────────────────────
+    composeResolver = (name, node) => {
+        const cached = this.resolvedComponents.get(name);
+        if (cached)
+            return cached;
+        const resolved = this.resolveComponent(name, node);
+        this.resolvedComponents.set(name, resolved);
+        return resolved;
+    };
+    resolveComponent(name, node) {
+        const composeFail = (message, hint) => {
+            throw new ArgonCompileError([diagnosticForNode("ARGON124", "all", message, node, this.source, hint)], this.source);
+        };
+        let sig = this.signatures.get(name);
+        let module;
+        if (!sig) {
+            const spec = this.namedImports.get(name);
+            if (spec === undefined) {
+                composeFail(`Unknown component '<${name}>'.`, "Declare it in this file, or import it from the module that declares it.");
+            }
+            if (!spec.startsWith(".")) {
+                composeFail(`'<${name}>' is imported from '${spec}'; composition needs a relative import pointing at the component's source file.`);
+            }
+            const file = resolveSourceFile(path.resolve(path.dirname(this.source.fileName), spec));
+            if (!file) {
+                composeFail(`Cannot find the source of '<${name}>' (imported from '${spec}').`, "Composition resolves './x.js' to './x.tsx' or './x.ts' relative to this file.");
+            }
+            const childText = fs.readFileSync(file, "utf8");
+            const childSource = ts.createSourceFile(file, childText, ts.ScriptTarget.Latest, true);
+            sig = componentSignatures(childSource).get(name);
+            if (!sig)
+                composeFail(`'${file}' does not declare an Argon component named '${name}'.`);
+            // Rust convention: each compiled file is a sibling module named after
+            // its source file, so cross-file children resolve as super::module::T.
+            module = path.basename(file, path.extname(file)).replace(/-/g, "_");
+            this.composedImports.add(spec);
+        }
+        const sameFile = module === undefined;
+        const props = sig.props.map(p => {
+            let base = UNKNOWN;
+            if (p.typeNode) {
+                try {
+                    base = this.typeOf(p.typeNode, pascal(p.name));
+                }
+                catch (error) {
+                    if (!(error instanceof LowerError))
+                        throw error;
+                    composeFail(`Prop '${p.name}' of '<${name}>' has a type this file cannot encode.`, sameFile ? undefined : "Cross-file composition supports scalar props and arrays of scalars; declare the child in this file to pass interface types.");
+                }
+            }
+            let def;
+            if (p.defaultExpr) {
+                // Cross-file defaults lower from the child's AST, so only literals
+                // are safe; anything richer makes the prop required for the parent.
+                def = sameFile ? this.tryExpr(p.defaultExpr) : literalExpr(p.defaultExpr);
+                if (def && def.type.kind === "unknown")
+                    def = { ...def, type: base };
+                if (def && base.kind === "unknown")
+                    base = def.type;
+            }
+            const optional = p.optional && !p.defaultExpr;
+            return {
+                name: p.name,
+                type: optional ? { kind: "option", inner: base } : base,
+                default: def,
+                optional,
+                required: !optional && def === undefined,
+            };
+        });
+        return { className: sig.className, tagName: sig.tagName, module, props };
+    }
+    tryExpr(node) {
+        try {
+            return this.expr(node);
+        }
+        catch (error) {
+            if (!(error instanceof LowerError))
+                throw error;
+            return undefined;
+        }
+    }
+    // Lower a marker that plays a composition role: a child prop value in
+    // attribute position, or the construction site of the child's shadow DOM.
+    composedExpr(meta, node) {
+        if (meta.kind === "propattr") {
+            const propType = meta.prop.type.kind === "option" ? meta.prop.type.inner : meta.prop.type;
+            let value;
+            try {
+                value = this.value(node, propType);
+            }
+            catch (error) {
+                if (!(error instanceof LowerError))
+                    throw error;
+                value = this.opaqueExpr(node, error.diagnostic);
+            }
+            return { kind: "propattr", value, propType, type: STRING };
+        }
+        const props = meta.component.props.map(p => {
+            const provided = meta.provided.get(p.name);
+            let value;
+            if (provided === true) {
+                value = { kind: "bool", value: true, type: BOOLEAN };
+            }
+            else if (provided) {
+                try {
+                    value = this.value(provided, p.type);
+                }
+                catch (error) {
+                    if (!(error instanceof LowerError))
+                        throw error;
+                    value = this.opaqueExpr(provided, error.diagnostic);
+                }
+            }
+            else {
+                // Validated by the JSX pass: only optional or defaulted props omit.
+                value = p.default;
+            }
+            return { name: p.name, type: p.type, value };
+        });
+        return { kind: "construct", className: meta.component.className, module: meta.component.module, props, type: STRING };
+    }
+    // ── Diagnostics ────────────────────────────────────────────────────────────
+    fail(node, message, hint = SSR_HINT) {
+        throw new LowerError(diagnosticForNode("ARGON199", "ssr", message, node, this.source, hint));
+    }
+    opaqueExpr(node, diagnostic) {
+        return {
+            kind: "opaque",
+            text: node.getText(this.source),
+            freeIds: [...freeIdentifiers(node)],
+            diagnostic,
+            hasJsx: containsJsx(node),
+            type: UNKNOWN,
+        };
+    }
+    // ── Types ────────────────────────────────────────────────────────────────────
+    registerStruct(name, members) {
+        const existing = this.structs.get(name);
+        if (existing)
+            return existing;
+        const struct = { name, fields: [] };
+        this.structs.set(name, struct);
+        try {
+            for (const m of members) {
+                if (!ts.isPropertySignature(m) || !m.type || !ts.isIdentifier(m.name))
+                    continue;
+                const type = this.typeOf(m.type, pascal(m.name.text));
+                struct.fields.push({ name: m.name.text, type: m.questionToken ? { kind: "option", inner: type } : type });
+            }
+        }
+        catch (error) {
+            // A field outside the supported type set: drop the struct, so uses of
+            // it surface as unsupported types instead of crashing the compile.
+            if (!(error instanceof LowerError))
+                throw error;
+            this.structs.delete(name);
+            throw error;
+        }
+        return struct;
+    }
+    typeOf(node, nameHint) {
+        if (node.kind === ts.SyntaxKind.StringKeyword)
+            return STRING;
+        if (node.kind === ts.SyntaxKind.NumberKeyword)
+            return NUMBER;
+        if (node.kind === ts.SyntaxKind.BooleanKeyword)
+            return BOOLEAN;
+        if (ts.isArrayTypeNode(node)) {
+            return { kind: "array", elem: this.typeOf(node.elementType, nameHint) };
+        }
+        if (ts.isTupleTypeNode(node)) {
+            const elems = node.elements.map(e => this.typeOf(e, nameHint));
+            if (elems.length > 0 && elems.every(e => sameType(e, elems[0]))) {
+                return { kind: "fixed", elem: elems[0], size: elems.length };
+            }
+            return { kind: "tuple", elems };
+        }
+        if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName)) {
+            const struct = this.structs.get(node.typeName.text);
+            if (struct)
+                return { kind: "struct", name: struct.name };
+        }
+        if (ts.isTypeLiteralNode(node)) {
+            return { kind: "struct", name: this.registerStruct(nameHint, node.members).name };
+        }
+        this.fail(node, `unsupported Rust SSR type: ${node.getText(this.source)}`);
+    }
+    fieldType(type, name) {
+        if (type.kind !== "struct")
+            return UNKNOWN;
+        return this.structs.get(type.name)?.fields.find(f => f.name === name)?.type ?? UNKNOWN;
+    }
+    // ── Scopes ─────────────────────────────────────────────────────────────────
+    bind(name, binding) {
+        this.scopes[this.scopes.length - 1].bindings.set(name, binding);
+    }
+    resolve(name) {
+        for (let i = this.scopes.length - 1; i >= 0; i--) {
+            const found = this.scopes[i].bindings.get(name);
+            if (found)
+                return found;
+        }
+        return undefined;
+    }
+    scoped(fn) {
+        this.scopes.push({ bindings: new Map(), narrows: new Set() });
+        try {
+            return fn();
+        }
+        finally {
+            this.scopes.pop();
+        }
+    }
+    // ── Flow narrowing ─────────────────────────────────────────────────────────
+    //
+    // Within a branch guarded by a presence test, the tested optional place is
+    // proven present, so reads of it unwrap instead of demanding a fallback.
+    narrowedBy(cond, taken, fn) {
+        const paths = [];
+        collectPresent(cond, taken, paths);
+        if (paths.length === 0)
+            return fn();
+        return this.scoped(() => {
+            const narrows = this.scopes[this.scopes.length - 1].narrows;
+            for (const path of paths)
+                narrows.add(path);
+            return fn();
+        });
+    }
+    isNarrowed(path) {
+        const root = path.split(".")[0];
+        for (let i = this.scopes.length - 1; i >= 0; i--) {
+            if (this.scopes[i].narrows.has(path))
+                return true;
+            // A rebinding of the root (map items, params) shadows outer proofs.
+            if (this.scopes[i].bindings.has(root))
+                return false;
+        }
+        return false;
+    }
+    maybeUnwrap(expr) {
+        if (expr.type.kind !== "option")
+            return expr;
+        const path = placePath(expr);
+        if (path === undefined || !this.isNarrowed(path))
+            return expr;
+        return { kind: "unwrap", object: expr, type: expr.type.inner };
+    }
+    // ── Module declarations ────────────────────────────────────────────────────
+    fnSignature(fn) {
+        try {
+            const params = fn.parameters.map(p => ({
+                name: p.name.text,
+                type: p.type ? this.typeOf(p.type, pascal(p.name.text)) : NUMBER,
+            }));
+            const ret = fn.type ? this.typeOf(fn.type, "Ret") : NUMBER;
+            return { params, ret };
+        }
+        catch {
+            return { params: [], ret: UNKNOWN };
+        }
+    }
+    lowerFn(fn) {
+        const name = fn.name.text;
+        const sig = this.fns.get(name);
+        try {
+            if (!fn.body)
+                this.fail(fn, `function '${name}' has no body`);
+            const body = this.scoped(() => {
+                for (const param of sig.params)
+                    this.bind(param.name, { space: "param", type: param.type });
+                return fn.body.statements.flatMap(s => this.stmt(s, sig.ret));
+            });
+            this.decls.push({
+                kind: "fn",
+                name,
+                params: sig.params,
+                ret: sig.ret,
+                body,
+                span: { start: fn.getStart(this.source), end: fn.getEnd() },
+                hasJsx: containsJsx(fn),
+            });
+        }
+        catch (error) {
+            if (!(error instanceof LowerError))
+                throw error;
+            this.opaqueDecls.add(name);
+            this.decls.push({ kind: "opaque", name, diagnostic: error.diagnostic, hasJsx: containsJsx(fn) });
+        }
+    }
+    lowerConst(decl) {
+        if (!ts.isIdentifier(decl.name) || !decl.initializer)
+            return;
+        const name = decl.name.text;
+        const init = decl.initializer;
+        if (ts.isTaggedTemplateExpression(init) && ts.isIdentifier(init.tag) && init.tag.text === "css") {
+            this.cssConsts.add(name);
+            this.decls.push({ kind: "css", name, text: templateText(init.template) });
+            return;
+        }
+        if (ts.isObjectLiteralExpression(init) && decl.type && isRecordType(decl.type)) {
+            try {
+                const valueType = this.typeOf(decl.type.typeArguments[1], "Value");
+                const entries = [];
+                for (const prop of init.properties) {
+                    if (!ts.isPropertyAssignment(prop))
+                        continue;
+                    const key = ts.isStringLiteral(prop.name) || ts.isIdentifier(prop.name) ? prop.name.text : undefined;
+                    if (key === undefined)
+                        continue;
+                    entries.push({ key, value: this.expr(prop.initializer, valueType) });
+                }
+                this.tables.set(name, valueType);
+                this.decls.push({
+                    kind: "table",
+                    name,
+                    valueType,
+                    entries,
+                    span: { start: decl.getStart(this.source), end: decl.getEnd() },
+                    hasJsx: containsJsx(init),
+                });
+            }
+            catch (error) {
+                if (!(error instanceof LowerError))
+                    throw error;
+                this.opaqueDecls.add(name);
+                this.decls.push({ kind: "opaque", name, diagnostic: error.diagnostic, hasJsx: containsJsx(init) });
+            }
+            return;
+        }
+        this.opaqueDecls.add(name);
+        this.decls.push({
+            kind: "opaque",
+            name,
+            diagnostic: diagnosticForNode("ARGON199", "ssr", `unsupported Rust SSR const: ${name}`, decl, this.source, SSR_HINT),
+            hasJsx: containsJsx(decl),
+        });
+    }
+    // ── Components ─────────────────────────────────────────────────────────────
+    lowerComponent(component) {
+        this.composing = true;
+        try {
+            return this.lowerComponentBody(component);
+        }
+        finally {
+            this.composing = false;
+        }
+    }
+    lowerComponentBody(component) {
+        return this.scoped(() => {
+            const props = component.props.map(p => {
+                let type = UNKNOWN;
+                if (p.typeNode) {
+                    try {
+                        type = this.typeOf(p.typeNode, pascal(p.name));
+                        // `name?:` with a default is always filled; without one the
+                        // value may genuinely be absent.
+                        if (p.optional && !p.defaultExpr)
+                            type = { kind: "option", inner: type };
+                    }
+                    catch (error) {
+                        if (!(error instanceof LowerError))
+                            throw error;
+                    }
+                }
+                let def;
+                if (p.defaultExpr) {
+                    try {
+                        def = this.expr(p.defaultExpr, type);
+                        if (type.kind === "unknown")
+                            type = def.type;
+                    }
+                    catch (error) {
+                        if (!(error instanceof LowerError))
+                            throw error;
+                        def = this.opaqueExpr(p.defaultExpr, error.diagnostic);
+                    }
+                }
+                this.bind(p.name, { space: "prop", type });
+                return { name: p.name, type, default: def };
+            });
+            const states = [];
+            const setup = [];
+            for (const stmt of component.prelude) {
+                for (const lowered of this.setupStmt(stmt, states))
+                    setup.push(lowered);
+            }
+            const refs = setup.flatMap(s => (s.kind === "refdecl" ? [s.name] : []));
+            const processed = processTemplate(component.template);
+            this.checkRefAttrs(processed.nodes, new Set(refs), component);
+            const eventIndices = new Set(processed.bindings.map(b => b.exprIndex));
+            const exprs = processed.expressionNodes.map((node, i) => {
+                if (eventIndices.has(i)) {
+                    return this.opaqueExpr(node, diagnosticForNode("ARGON198", "ssr", "Event handlers are CSR-only and never evaluated during SSR.", node, this.source));
+                }
+                const meta = processed.meta.get(i);
+                if (meta)
+                    return this.composedExpr(meta, node);
+                try {
+                    // Rendered values must be definite; an optional interpolation gets
+                    // the unwrap-first diagnostic.
+                    return this.value(node);
+                }
+                catch (error) {
+                    if (!(error instanceof LowerError))
+                        throw error;
+                    return this.opaqueExpr(node, error.diagnostic);
+                }
+            });
+            const template = {
+                nodes: processed.nodes,
+                events: processed.bindings,
+                textBindings: processed.textBindings,
+                attrBindings: processed.attrBindings,
+                exprs,
+                exprSpans: processed.expressionNodes.map(n => ({ start: n.getStart(this.source), end: n.getEnd() })),
+            };
+            return {
+                className: component.className,
+                tagName: component.tagName,
+                props,
+                states,
+                refs,
+                setup,
+                template,
+                span: {
+                    start: component.func.getStart(component.source),
+                    end: component.func.getEnd(),
+                },
+            };
+        });
+    }
+    // ref={name} attributes must point at a ref() declared in the setup;
+    // a typo would otherwise silently yield a ref that never resolves.
+    checkRefAttrs(nodes, refs, component) {
+        for (const node of nodes) {
+            if (node.type !== "element")
+                continue;
+            const attr = node.attrs.find(a => a.name === "data-argon-ref");
+            if (attr && (attr.value === null || !refs.has(attr.value))) {
+                throw new ArgonCompileError([{
+                        code: "ARGON122",
+                        target: "all",
+                        message: `ref '${attr.value}' is not declared in this component.`,
+                        span: { start: component.func.getStart(component.source), end: component.func.getEnd() },
+                        hint: `Declare it in the component setup: const ${attr.value} = ref();`,
+                    }], this.source);
+            }
+            this.checkRefAttrs(node.children, refs, component);
+        }
+    }
+    // onMount(cb) / effect(cb) — CSR-only lifecycle, component setup only.
+    // Malformed calls fail the whole compile: turned opaque they would pass
+    // through to the JS output, where onMount/effect do not exist at runtime.
+    hookStmt(stmt) {
+        if (!ts.isExpressionStatement(stmt) || !ts.isCallExpression(stmt.expression))
+            return undefined;
+        const call = stmt.expression;
+        if (!ts.isIdentifier(call.expression))
+            return undefined;
+        const name = call.expression.text;
+        if (name !== "onMount" && name !== "effect")
+            return undefined;
+        const cb = call.arguments[0];
+        if (call.arguments.length !== 1 || !cb || (!ts.isArrowFunction(cb) && !ts.isFunctionExpression(cb))) {
+            throw new ArgonCompileError([diagnosticForNode("ARGON123", "all", `${name}() takes a single callback function.`, call, this.source)], this.source);
+        }
+        return {
+            kind: "hook",
+            hook: name === "onMount" ? "mount" : "effect",
+            text: cb.getText(this.source),
+            freeIds: [...freeIdentifiers(cb)],
+            span: { start: call.getStart(this.source), end: call.getEnd() },
+            hasJsx: containsJsx(cb),
+        };
+    }
+    setupStmt(stmt, states) {
+        const hook = this.hookStmt(stmt);
+        if (hook)
+            return [hook];
+        try {
+            const lowered = this.stmt(stmt, UNKNOWN, states);
+            return lowered;
+        }
+        catch (error) {
+            if (!(error instanceof LowerError))
+                throw error;
+            const names = declaredNames(stmt);
+            for (const name of names)
+                this.bind(name, { space: "local", type: UNKNOWN });
+            return [{
+                    kind: "opaque",
+                    text: stmt.getText(this.source),
+                    names,
+                    freeIds: [...freeIdentifiers(stmt)],
+                    diagnostic: error.diagnostic,
+                    hasJsx: containsJsx(stmt),
+                }];
+        }
+    }
+    // ── Statements ─────────────────────────────────────────────────────────────
+    stmt(node, expectedReturn, states) {
+        if (ts.isVariableStatement(node)) {
+            return node.declarationList.declarations.map(d => this.varDecl(d, states));
+        }
+        if (ts.isReturnStatement(node)) {
+            if (!node.expression)
+                this.fail(node, "Rust SSR requires a return value.");
+            return [{ kind: "return", value: this.value(node.expression, expectedReturn) }];
+        }
+        if (ts.isIfStatement(node) || ts.isSwitchStatement(node)) {
+            // `states` is only threaded through component setup; control flow there
+            // would bypass the reactive-binding gating, so it stays in helpers.
+            if (states) {
+                this.fail(node, "if/switch statements are only supported inside helper functions; use a ternary here, or extract a helper.");
+            }
+            return [ts.isIfStatement(node) ? this.ifStmt(node, expectedReturn) : this.switchStmt(node, expectedReturn)];
+        }
+        this.fail(node, `Rust SSR supports const/let setup statements, if/switch, and return; found ${ts.SyntaxKind[node.kind]}.`);
+    }
+    // Lower a statement or block into a scoped list of StmtIR.
+    branch(node, expectedReturn) {
+        return this.scoped(() => {
+            if (ts.isBlock(node))
+                return node.statements.flatMap(s => this.stmt(s, expectedReturn));
+            return this.stmt(node, expectedReturn);
+        });
+    }
+    ifStmt(node, expectedReturn) {
+        const cond = this.value(node.expression);
+        const then = this.narrowedBy(cond, true, () => this.branch(node.thenStatement, expectedReturn));
+        const els = node.elseStatement
+            ? this.narrowedBy(cond, false, () => this.branch(node.elseStatement, expectedReturn))
+            : undefined;
+        return { kind: "if", cond, then, else: els };
+    }
+    // switch (disc) { case k: …; default: … } desugars to an if/else chain over
+    // equality with each case label. Cases do not fall through: each must break
+    // or return, and a trailing break is dropped.
+    switchStmt(node, expectedReturn) {
+        const disc = this.value(node.expression);
+        const clauses = node.caseBlock.clauses;
+        const bodyOf = (stmts) => this.scoped(() => stmts.filter(s => !ts.isBreakStatement(s)).flatMap(s => this.stmt(s, expectedReturn)));
+        // Group consecutive labels that fall through to a shared body (`case a:
+        // case b: return x`), and pull out the default body.
+        const groups = [];
+        let defaultBody;
+        let pending = [];
+        for (const clause of clauses) {
+            if (ts.isDefaultClause(clause)) {
+                defaultBody = bodyOf(clause.statements);
+                continue;
+            }
+            pending.push({ kind: "binary", op: "==", left: disc, right: this.value(clause.expression, disc.type), type: BOOLEAN });
+            const meaningful = clause.statements.filter(s => !ts.isBreakStatement(s));
+            if (meaningful.length > 0) {
+                groups.push({ tests: pending, body: bodyOf(clause.statements) });
+                pending = [];
+            }
+        }
+        if (groups.length === 0 && !defaultBody)
+            this.fail(node, "switch needs at least one case with a body.");
+        // Fold into an if/else chain, ORing each group's labels; default is the tail.
+        let chain = defaultBody;
+        for (let i = groups.length - 1; i >= 0; i--) {
+            const cond = groups[i].tests.reduce((acc, t) => ({ kind: "binary", op: "||", left: acc, right: t, type: BOOLEAN }));
+            chain = [{ kind: "if", cond, then: groups[i].body, else: chain }];
+        }
+        return chain.length === 1 ? chain[0] : { kind: "if", cond: { kind: "bool", value: true, type: BOOLEAN }, then: chain };
+    }
+    varDecl(decl, states) {
+        if (!decl.initializer)
+            this.fail(decl, "Rust SSR declarations need an initializer.");
+        // const el = ref() — CSR-only DOM handle, component setup only.
+        if (states && ts.isIdentifier(decl.name) && isRefCall(decl.initializer)) {
+            return { kind: "refdecl", name: decl.name.text };
+        }
+        // let count = state(initial) — reactive state, component setup only. A
+        // CSR-only initializer (e.g. Date.now()) is not silently emitted as a
+        // verbatim `state(...)` call: it stays reactive state (the client
+        // materializes it at hydration) but carries an SSR diagnostic so Rust
+        // rejects it with an actionable message.
+        const stateInit = states && stateCallArgument(decl.initializer);
+        if (stateInit && ts.isIdentifier(decl.name)) {
+            let initial;
+            try {
+                initial = this.expr(stateInit);
+            }
+            catch (error) {
+                if (!(error instanceof LowerError))
+                    throw error;
+                initial = this.opaqueExpr(stateInit, diagnosticForNode("ARGON126", "ssr", `state() initializer '${stateInit.getText(this.source)}' is CSR-only and cannot be server-rendered.`, stateInit, this.source, "Initialize with a server-renderable placeholder and assign the real value in onMount()."));
+            }
+            states.push({ name: decl.name.text, type: initial.type, initial });
+            this.bind(decl.name.text, { space: "state", type: initial.type });
+            return { kind: "let", names: [decl.name.text], tuple: false, init: initial, type: initial.type, isState: true };
+        }
+        const init = this.expr(decl.initializer);
+        if (ts.isArrayBindingPattern(decl.name)) {
+            const names = decl.name.elements.map(e => ts.isBindingElement(e) && ts.isIdentifier(e.name) ? e.name.text : "_");
+            const elems = tupleElemTypes(init.type, names.length);
+            names.forEach((name, i) => {
+                if (name !== "_")
+                    this.bind(name, { space: "local", type: elems[i] ?? UNKNOWN });
+            });
+            return { kind: "let", names, tuple: true, init, type: init.type, isState: false };
+        }
+        if (!ts.isIdentifier(decl.name)) {
+            this.fail(decl, "Rust SSR does not support this binding pattern.");
+        }
+        this.bind(decl.name.text, { space: "local", type: init.type });
+        return { kind: "let", names: [decl.name.text], tuple: false, init, type: init.type, isState: false };
+    }
+    // ── Expressions ────────────────────────────────────────────────────────────
+    // Lower an expression that must produce a definite value: optionals are
+    // rejected with a targeted fix instead of leaking Option<T> into Rust.
+    value(node, expected = UNKNOWN) {
+        const expr = this.expr(node, expected);
+        if (expr.type.kind === "option") {
+            this.fail(node, "Optional value used where a definite value is required.", "Unwrap it first: apply a fallback with '?? <default>' or test presence with '!== undefined'.");
+        }
+        return expr;
+    }
+    expr(node, expected = UNKNOWN) {
+        // Values stored into an optional slot are lowered against the inner type;
+        // the Rust backend wraps them in Some(...) at the assignment site.
+        if (expected.kind === "option")
+            expected = expected.inner;
+        if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node)) {
+            return this.expr(node.expression, expected);
+        }
+        if (ts.isNumericLiteral(node))
+            return { kind: "num", text: node.text, type: NUMBER };
+        if (ts.isStringLiteral(node))
+            return { kind: "str", value: node.text, type: STRING };
+        if (ts.isNoSubstitutionTemplateLiteral(node))
+            return { kind: "str", value: node.text, type: STRING };
+        if (node.kind === ts.SyntaxKind.TrueKeyword)
+            return { kind: "bool", value: true, type: BOOLEAN };
+        if (node.kind === ts.SyntaxKind.FalseKeyword)
+            return { kind: "bool", value: false, type: BOOLEAN };
+        if (ts.isIdentifier(node))
+            return this.identifier(node);
+        if (ts.isPrefixUnaryExpression(node)) {
+            if (node.operator === ts.SyntaxKind.ExclamationToken) {
+                return { kind: "unary", op: "!", operand: this.value(node.operand), type: BOOLEAN };
+            }
+            if (node.operator === ts.SyntaxKind.MinusToken) {
+                const operand = this.value(node.operand);
+                if (operand.kind === "num")
+                    return { kind: "num", text: `-${operand.text}`, type: NUMBER };
+                return { kind: "unary", op: "-", operand, type: NUMBER };
+            }
+            this.fail(node, `Rust SSR does not support unary '${ts.tokenToString(node.operator)}'.`);
+        }
+        if (ts.isPropertyAccessExpression(node)) {
+            if (node.name.text === "length") {
+                return { kind: "length", object: this.value(node.expression), type: NUMBER };
+            }
+            const object = this.value(node.expression);
+            return this.maybeUnwrap({
+                kind: "member",
+                object,
+                name: node.name.text,
+                type: this.fieldType(object.type, node.name.text),
+            });
+        }
+        if (ts.isElementAccessExpression(node)) {
+            if (ts.isIdentifier(node.expression) && this.tables.has(node.expression.text)) {
+                return {
+                    kind: "lookup",
+                    table: node.expression.text,
+                    key: this.value(node.argumentExpression),
+                    type: this.tables.get(node.expression.text),
+                };
+            }
+            const object = this.value(node.expression);
+            const index = this.value(node.argumentExpression);
+            return { kind: "index", object, index, type: indexedType(object.type, index) };
+        }
+        if (ts.isConditionalExpression(node)) {
+            const cond = this.value(node.condition);
+            const whenTrue = this.narrowedBy(cond, true, () => this.value(node.whenTrue, expected));
+            const whenFalse = this.narrowedBy(cond, false, () => this.value(node.whenFalse, expected));
+            return {
+                kind: "cond",
+                cond,
+                whenTrue,
+                whenFalse,
+                type: whenTrue.type.kind === "unknown" ? whenFalse.type : whenTrue.type,
+            };
+        }
+        if (ts.isBinaryExpression(node))
+            return this.binary(node);
+        if (ts.isTemplateExpression(node))
+            return this.template(node);
+        if (ts.isCallExpression(node))
+            return this.call(node);
+        if (ts.isArrayLiteralExpression(node)) {
+            const elems = node.elements.map(e => this.value(e));
+            const type = expected.kind === "fixed" || expected.kind === "array"
+                ? expected
+                : { kind: "tuple", elems: elems.map(e => e.type) };
+            return { kind: "arr", elems, type };
+        }
+        if (ts.isObjectLiteralExpression(node)) {
+            if (expected.kind !== "struct") {
+                this.fail(node, "untyped Rust SSR object literal", "Annotate the value with an interface type so the compiler can emit a struct.");
+            }
+            const struct = this.structs.get(expected.name);
+            const fields = node.properties.flatMap(prop => {
+                if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) {
+                    this.fail(prop, "Rust SSR does not support this object literal member.");
+                }
+                const fieldType = struct?.fields.find(f => f.name === prop.name.text)?.type ?? UNKNOWN;
+                // Optional fields accept optional values as-is; definite fields must
+                // receive definite values.
+                const value = fieldType.kind === "option"
+                    ? this.expr(prop.initializer, fieldType)
+                    : this.value(prop.initializer, fieldType);
+                return [{ name: prop.name.text, value }];
+            });
+            return { kind: "obj", struct: expected.name, fields, type: expected };
+        }
+        if (isJsxRoot(node))
+            return this.jsxTemplate(node);
+        if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+            this.fail(node, "Function values are CSR-only; Rust SSR cannot evaluate them in template interpolation.");
+        }
+        this.fail(node, `Rust SSR does not support ${ts.SyntaxKind[node.kind]}: ${node.getText(this.source)}`);
+    }
+    identifier(node) {
+        const binding = this.resolve(node.text);
+        if (binding)
+            return this.maybeUnwrap({ kind: "ref", name: node.text, space: binding.space, type: binding.type });
+        if (this.cssConsts.has(node.text))
+            return { kind: "ref", name: node.text, space: "global", type: STRING };
+        this.fail(node, `Rust SSR cannot evaluate '${node.text}' here.`);
+    }
+    // Nested JSX in a value position compiles to a string-producing template.
+    jsxTemplate(node) {
+        const tpl = jsxToTemplate(node, this.source, false, this.composing ? this.composeResolver : undefined);
+        const key = tpl.key ? this.value(tpl.key) : undefined;
+        if (tpl.expressionNodes.length === 0 && !key)
+            return { kind: "str", value: tpl.quasis[0], type: STRING, html: true };
+        return {
+            kind: "template",
+            quasis: tpl.quasis,
+            parts: tpl.expressionNodes.map((n, i) => {
+                const meta = tpl.meta.get(i);
+                return meta ? this.composedExpr(meta, n) : this.value(n);
+            }),
+            key,
+            type: STRING,
+            html: true,
+        };
+    }
+    binary(node) {
+        const ops = {
+            [ts.SyntaxKind.EqualsEqualsEqualsToken]: "==",
+            [ts.SyntaxKind.EqualsEqualsToken]: "==",
+            [ts.SyntaxKind.ExclamationEqualsEqualsToken]: "!=",
+            [ts.SyntaxKind.ExclamationEqualsToken]: "!=",
+            [ts.SyntaxKind.PlusToken]: "+",
+            [ts.SyntaxKind.MinusToken]: "-",
+            [ts.SyntaxKind.AsteriskToken]: "*",
+            [ts.SyntaxKind.SlashToken]: "/",
+            [ts.SyntaxKind.PercentToken]: "%",
+            [ts.SyntaxKind.LessThanToken]: "<",
+            [ts.SyntaxKind.GreaterThanToken]: ">",
+            [ts.SyntaxKind.LessThanEqualsToken]: "<=",
+            [ts.SyntaxKind.GreaterThanEqualsToken]: ">=",
+            [ts.SyntaxKind.AmpersandAmpersandToken]: "&&",
+            [ts.SyntaxKind.BarBarToken]: "||",
+            [ts.SyntaxKind.QuestionQuestionToken]: "??",
+        };
+        // Exponentiation lowers to a scalar Math.pow.
+        if (node.operatorToken.kind === ts.SyntaxKind.AsteriskAsteriskToken) {
+            return { kind: "math", fn: "pow", args: [this.value(node.left, NUMBER), this.value(node.right, NUMBER)], type: NUMBER };
+        }
+        const op = ops[node.operatorToken.kind];
+        if (!op) {
+            this.fail(node.operatorToken, `Rust SSR does not support '${ts.tokenToString(node.operatorToken.kind)}'.`);
+        }
+        // React semantics: `cond && value` renders nothing when falsy, instead of
+        // the string "false". This covers `<jsx/>` and any string-valued right
+        // side; emitting the raw `bool && String` would miscompile in Rust (E0308)
+        // and render "false" (never nothing) on the client. A boolean/numeric
+        // right side stays a real logical-AND.
+        if (op === "&&") {
+            const cond = this.value(node.left);
+            const whenTrue = this.narrowedBy(cond, true, () => isJsxRoot(node.right) ? this.jsxTemplate(node.right) : this.value(node.right));
+            if (whenTrue.type.kind === "string" || whenTrue.type.kind === "unknown") {
+                return {
+                    kind: "cond",
+                    cond,
+                    whenTrue,
+                    // The empty branch matches the right side's markup-ness: a markup
+                    // right side stays wholly markup; a string right side stays text (so
+                    // it is escaped whole, as a scalar value would be).
+                    whenFalse: { kind: "str", value: "", type: STRING, html: isMarkup(whenTrue) },
+                    type: STRING,
+                };
+            }
+            return { kind: "binary", op, left: cond, right: whenTrue, type: binaryType(op, cond, whenTrue) };
+        }
+        // Presence test of an optional: x !== undefined / x === undefined.
+        const isUndef = (n) => ts.isIdentifier(n) && n.text === "undefined";
+        if ((op === "==" || op === "!=") && (isUndef(node.left) || isUndef(node.right))) {
+            const object = this.expr(isUndef(node.left) ? node.right : node.left);
+            return { kind: "exists", object, present: op === "!=", type: BOOLEAN };
+        }
+        // ?? unwraps an optional left side; everything else needs definite values.
+        const left = op === "??" ? this.expr(node.left) : this.value(node.left);
+        // Short-circuit narrowing: the right side of || runs only when the left
+        // is false. (&& is handled above.)
+        const lowerRight = () => this.value(node.right);
+        const right = op === "||" ? this.narrowedBy(left, false, lowerRight) : lowerRight();
+        return { kind: "binary", op, left, right, type: binaryType(op, left, right) };
+    }
+    template(node) {
+        const quasis = [node.head.text];
+        const parts = [];
+        for (const span of node.templateSpans) {
+            parts.push(this.value(span.expression));
+            quasis.push(span.literal.text);
+        }
+        return { kind: "template", quasis, parts, type: STRING };
+    }
+    call(node) {
+        const callee = node.expression;
+        // state(x) outside a declaration evaluates to its initial value.
+        if (ts.isIdentifier(callee) && callee.text === "state") {
+            if (!node.arguments[0])
+                this.fail(node, "state() needs an initial value.");
+            return this.expr(node.arguments[0]);
+        }
+        // unsafeHtml(x): render x as raw markup instead of escaping it.
+        if (ts.isIdentifier(callee) && callee.text === "unsafeHtml") {
+            if (!node.arguments[0])
+                this.fail(node, "unsafeHtml() needs a string argument.");
+            return { kind: "raw", inner: this.value(node.arguments[0], STRING), type: STRING };
+        }
+        if (ts.isIdentifier(callee)) {
+            const sig = this.fns.get(callee.text);
+            if (!sig)
+                this.fail(node, `Rust SSR cannot call '${callee.text}'.`);
+            if (this.opaqueDecls.has(callee.text)) {
+                this.fail(node, `'${callee.text}' uses CSR-only code, so Rust SSR cannot call it.`);
+            }
+            const args = node.arguments.map((a, i) => this.value(a, sig.params[i]?.type ?? UNKNOWN));
+            return { kind: "call", fn: callee.text, args, type: sig.ret };
+        }
+        if (ts.isPropertyAccessExpression(callee)) {
+            const method = callee.name.text;
+            if (ts.isIdentifier(callee.expression) && callee.expression.text === "Math") {
+                // Spread min/max keeps the array-reducing form; everything else is a
+                // scalar Math call over definite numbers.
+                if ((method === "min" || method === "max") && node.arguments[0] && ts.isSpreadElement(node.arguments[0])) {
+                    return { kind: "minmax", op: method, array: this.sequence(node.arguments[0].expression), type: NUMBER };
+                }
+                const spec = MATH_FNS[method];
+                if (!spec)
+                    this.fail(node, `Rust SSR does not support Math.${method}.`);
+                const args = node.arguments.map(a => this.value(a, NUMBER));
+                const ok = spec.arity === "1+" ? args.length >= 1 : spec.arity === "2" ? args.length === 2 : args.length === spec.arity;
+                if (!ok) {
+                    const want = spec.arity === "1+" ? "one or more arguments" : spec.arity === "2" ? "two arguments" : `${spec.arity} argument(s)`;
+                    this.fail(node, `Math.${method} takes ${want}.`);
+                }
+                return { kind: "math", fn: method, args, type: NUMBER };
+            }
+            if (method === "toFixed") {
+                const digits = node.arguments[0];
+                return {
+                    kind: "toFixed",
+                    value: this.value(callee.expression),
+                    digits: digits && ts.isNumericLiteral(digits) ? Number(digits.text) : 0,
+                    type: STRING,
+                };
+            }
+            if (method === "map") {
+                return this.mapCall(node, callee);
+            }
+            if (method === "join") {
+                const sep = node.arguments[0];
+                const array = this.sequence(callee.expression);
+                return {
+                    kind: "join",
+                    array,
+                    sep: sep && ts.isStringLiteral(sep) ? sep.text : ",",
+                    type: STRING,
+                };
+            }
+            // Whitelisted string/array methods, dispatched by receiver type.
+            if (STRING_METHODS[method] || ARRAY_METHODS[method]) {
+                const object = this.sequence(callee.expression);
+                if (object.type.kind === "string" && STRING_METHODS[method]) {
+                    return this.methodCall("strmethod", method, object, node, STRING_METHODS[method]);
+                }
+                if ((object.type.kind === "array" || object.type.kind === "fixed") && ARRAY_METHODS[method]) {
+                    return this.arrMethod(method, object, node);
+                }
+            }
+            this.fail(node, `Rust SSR does not support '.${method}()' calls.`);
+        }
+        this.fail(node, `Rust SSR does not support this call: ${node.getText(this.source)}`);
+    }
+    // Lower a whitelisted method call: validate arity, lower each argument
+    // against its declared kind, and tag the result type.
+    methodCall(kind, method, object, node, spec) {
+        const [min, max] = spec.args;
+        if (node.arguments.length < min || node.arguments.length > max) {
+            const want = min === max ? `${min}` : `${min}–${max}`;
+            this.fail(node, `.${method}() takes ${want} argument(s).`);
+        }
+        const args = node.arguments.map((a, i) => this.value(a, spec.argKinds[i] === "number" ? NUMBER : STRING));
+        const type = spec.result === "boolean" ? BOOLEAN : spec.result === "number" ? NUMBER : STRING;
+        return { kind, method, object, args, type };
+    }
+    // Whitelisted array methods. Predicate methods bind a single element param
+    // and lower the arrow body within its scope.
+    arrMethod(method, object, node) {
+        const elem = elemType(object.type);
+        const spec = ARRAY_METHODS[method];
+        if (spec.kind === "predicate") {
+            const cb = node.arguments[0];
+            if (!cb || !ts.isArrowFunction(cb))
+                this.fail(node, `.${method}() requires an arrow function predicate.`);
+            const { param, body } = this.predicate(cb, elem);
+            const type = method === "filter" ? { kind: "array", elem }
+                : method === "find" ? { kind: "option", inner: elem }
+                    : BOOLEAN;
+            return { kind: "arrmethod", method, object, param, body, args: [], type };
+        }
+        if (spec.kind === "value") {
+            const v = node.arguments[0];
+            if (!v)
+                this.fail(node, `.${method}() needs a value argument.`);
+            const arg = this.value(v, elem);
+            return { kind: "arrmethod", method, object, args: [arg], type: method === "includes" ? BOOLEAN : NUMBER };
+        }
+        // slice
+        const args = node.arguments.map(a => this.value(a, NUMBER));
+        if (args.length < 1 || args.length > 2)
+            this.fail(node, ".slice() takes 1–2 arguments.");
+        return { kind: "arrmethod", method, object, args, type: { kind: "array", elem } };
+    }
+    predicate(cb, elem) {
+        const first = cb.parameters[0];
+        if (!first || !ts.isIdentifier(first.name)) {
+            this.fail(cb, "Predicate callbacks need a single named parameter.");
+        }
+        const param = first.name.text;
+        return this.scoped(() => {
+            this.bind(param, { space: "local", type: elem });
+            let body;
+            if (ts.isBlock(cb.body)) {
+                const ret = cb.body.statements.find(ts.isReturnStatement);
+                if (!ret || !ret.expression)
+                    this.fail(cb, "Predicate callbacks must return a value.");
+                body = this.value(ret.expression);
+            }
+            else {
+                body = this.value(cb.body);
+            }
+            return { param, body };
+        });
+    }
+    // An array literal in a sequence position (map/join/spread) is a fixed
+    // array, not the tuple it would be as a standalone value.
+    sequence(node) {
+        const expr = this.value(node);
+        if (expr.kind === "arr" && expr.type.kind === "tuple" && expr.elems.length > 0) {
+            const elems = expr.type.elems;
+            if (elems.every(e => sameType(e, elems[0]))) {
+                return { ...expr, type: { kind: "fixed", elem: elems[0], size: elems.length } };
+            }
+        }
+        return expr;
+    }
+    mapCall(node, callee) {
+        const array = this.sequence(callee.expression);
+        const cb = node.arguments[0];
+        if (!cb || !ts.isArrowFunction(cb)) {
+            this.fail(node, "Rust SSR map() requires an arrow function callback.");
+        }
+        const elem = elemType(array.type);
+        return this.scoped(() => {
+            let item;
+            const first = cb.parameters[0];
+            if (first && ts.isArrayBindingPattern(first.name)) {
+                const names = first.name.elements.map(e => ts.isBindingElement(e) && ts.isIdentifier(e.name) ? e.name.text : "_");
+                const elems = tupleElemTypes(elem, names.length);
+                names.forEach((name, i) => {
+                    if (name !== "_")
+                        this.bind(name, { space: "local", type: elems[i] ?? UNKNOWN });
+                });
+                item = names;
+            }
+            else if (first && ts.isIdentifier(first.name)) {
+                this.bind(first.name.text, { space: "local", type: elem });
+                item = first.name.text;
+            }
+            else {
+                this.fail(cb, "Rust SSR map() callbacks need a named element parameter.");
+            }
+            let indexVar;
+            const second = cb.parameters[1];
+            if (second && ts.isIdentifier(second.name)) {
+                indexVar = second.name.text;
+                this.bind(indexVar, { space: "local", type: NUMBER });
+            }
+            const stmts = [];
+            let result;
+            if (ts.isBlock(cb.body)) {
+                for (const stmt of cb.body.statements) {
+                    if (ts.isReturnStatement(stmt)) {
+                        if (!stmt.expression)
+                            this.fail(stmt, "Rust SSR map() callbacks must return a value.");
+                        result = this.value(stmt.expression);
+                    }
+                    else {
+                        for (const s of this.stmt(stmt, UNKNOWN))
+                            stmts.push(s);
+                    }
+                }
+                if (!result)
+                    this.fail(cb, "Rust SSR map() callbacks must return a value.");
+            }
+            else {
+                result = this.value(cb.body);
+            }
+            return {
+                kind: "map",
+                array,
+                item,
+                indexVar,
+                body: { stmts, result },
+                type: { kind: "array", elem: result.type },
+            };
+        });
+    }
+}
+// ── Narrowing helpers ────────────────────────────────────────────────────────
+// Paths proven present when `cond` evaluates to `taken`, flowing through
+// `!`, `&&` (taken branch) and `||` (not-taken branch).
+function collectPresent(cond, taken, out) {
+    if (cond.kind === "exists") {
+        if (cond.present === taken && cond.object.type.kind === "option") {
+            const path = placePath(cond.object);
+            if (path !== undefined)
+                out.push(path);
+        }
+    }
+    else if (cond.kind === "unary" && cond.op === "!") {
+        collectPresent(cond.operand, !taken, out);
+    }
+    else if (cond.kind === "binary" && ((cond.op === "&&" && taken) || (cond.op === "||" && !taken))) {
+        collectPresent(cond.left, taken, out);
+        collectPresent(cond.right, taken, out);
+    }
+}
+// Canonical path of a narrowable place: refs and member chains only.
+function placePath(e) {
+    if (e.kind === "ref")
+        return e.name;
+    if (e.kind === "unwrap")
+        return placePath(e.object);
+    if (e.kind === "member") {
+        const base = placePath(e.object);
+        return base === undefined ? undefined : `${base}.${e.name}`;
+    }
+    return undefined;
+}
+// ── Type helpers ─────────────────────────────────────────────────────────────
+function sameType(a, b) {
+    if (a.kind !== b.kind)
+        return false;
+    if (a.kind === "struct" && b.kind === "struct")
+        return a.name === b.name;
+    if ((a.kind === "array" || a.kind === "fixed") && (b.kind === "array" || b.kind === "fixed")) {
+        return a.kind === b.kind && sameType(a.elem, b.elem);
+    }
+    return true;
+}
+function elemType(type) {
+    if (type.kind === "array" || type.kind === "fixed")
+        return type.elem;
+    return UNKNOWN;
+}
+function tupleElemTypes(type, count) {
+    if (type.kind === "tuple")
+        return type.elems;
+    if (type.kind === "fixed" || type.kind === "array")
+        return Array(count).fill(type.elem);
+    return Array(count).fill(UNKNOWN);
+}
+function indexedType(object, index) {
+    if (object.kind === "array" || object.kind === "fixed")
+        return object.elem;
+    if (object.kind === "tuple" && index.kind === "num")
+        return object.elems[Number(index.text)] ?? UNKNOWN;
+    return UNKNOWN;
+}
+function binaryType(op, left, right) {
+    if (op === "==" || op === "!=" || op === "<" || op === ">" || op === "<=" || op === ">=" || op === "&&") {
+        return BOOLEAN;
+    }
+    if (op === "||")
+        return left.type.kind === "boolean" ? BOOLEAN : left.type;
+    // The right side is policed to be definite, so ?? always yields a value.
+    if (op === "??")
+        return left.type.kind === "option" ? right.type : left.type;
+    if (op === "+") {
+        if (left.type.kind === "string" || right.type.kind === "string")
+            return STRING;
+        return NUMBER;
+    }
+    return NUMBER;
+}
+// ── AST helpers ──────────────────────────────────────────────────────────────
+function pascal(name) {
+    return name.charAt(0).toUpperCase() + name.slice(1);
+}
+function resolveSourceFile(base) {
+    const stripped = base.replace(/\.(js|tsx|ts)$/, "");
+    for (const ext of [".tsx", ".ts"]) {
+        if (fs.existsSync(stripped + ext))
+            return stripped + ext;
+    }
+    return undefined;
+}
+// The literal subset safe to lower from another file's AST (cross-file
+// defaults): diagnostics and source text must never reference foreign nodes.
+function literalExpr(node) {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+        return { kind: "str", value: node.text, type: STRING };
+    }
+    if (ts.isNumericLiteral(node))
+        return { kind: "num", text: node.text, type: NUMBER };
+    if (node.kind === ts.SyntaxKind.TrueKeyword)
+        return { kind: "bool", value: true, type: BOOLEAN };
+    if (node.kind === ts.SyntaxKind.FalseKeyword)
+        return { kind: "bool", value: false, type: BOOLEAN };
+    if (ts.isPrefixUnaryExpression(node) &&
+        node.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(node.operand)) {
+        return { kind: "num", text: `-${node.operand.text}`, type: NUMBER };
+    }
+    if (ts.isArrayLiteralExpression(node)) {
+        const elems = [];
+        for (const element of node.elements) {
+            const lowered = literalExpr(element);
+            if (!lowered)
+                return undefined;
+            elems.push(lowered);
+        }
+        return { kind: "arr", elems, type: UNKNOWN };
+    }
+    return undefined;
+}
+function isRefCall(init) {
+    return (ts.isCallExpression(init) &&
+        ts.isIdentifier(init.expression) &&
+        init.expression.text === "ref" &&
+        init.arguments.length === 0);
+}
+function stateCallArgument(init) {
+    if (ts.isCallExpression(init) &&
+        ts.isIdentifier(init.expression) &&
+        init.expression.text === "state" &&
+        init.arguments[0]) {
+        return init.arguments[0];
+    }
+    return undefined;
+}
+function declaredNames(stmt) {
+    const names = [];
+    if (ts.isVariableStatement(stmt)) {
+        for (const decl of stmt.declarationList.declarations) {
+            if (ts.isIdentifier(decl.name))
+                names.push(decl.name.text);
+            else if (ts.isArrayBindingPattern(decl.name)) {
+                for (const el of decl.name.elements) {
+                    if (ts.isBindingElement(el) && ts.isIdentifier(el.name))
+                        names.push(el.name.text);
+                }
+            }
+        }
+    }
+    return names;
+}
+function templateText(tpl) {
+    if (ts.isNoSubstitutionTemplateLiteral(tpl))
+        return tpl.text;
+    let out = tpl.head.text;
+    for (const span of tpl.templateSpans)
+        out += span.literal.text;
+    return out;
+}
+function isRecordType(type) {
+    return (ts.isTypeReferenceNode(type) &&
+        ts.isIdentifier(type.typeName) &&
+        type.typeName.text === "Record" &&
+        type.typeArguments?.length === 2);
+}
+export function freeIdentifiers(node) {
+    const ids = new Set();
+    const visit = (n) => {
+        if (ts.isIdentifier(n)) {
+            if (ts.isPropertyAccessExpression(n.parent) && n.parent.name === n)
+                return;
+            if (ts.isPropertyAssignment(n.parent) && n.parent.name === n)
+                return;
+            if (ts.isBindingElement(n.parent) && n.parent.name === n)
+                return;
+            if (ts.isVariableDeclaration(n.parent) && n.parent.name === n)
+                return;
+            if (ts.isParameter(n.parent) && n.parent.name === n)
+                return;
+            if (ts.isFunctionDeclaration(n.parent) && n.parent.name === n)
+                return;
+            ids.add(n.text);
+        }
+        ts.forEachChild(n, visit);
+    };
+    visit(node);
+    return ids;
+}
+//# sourceMappingURL=lower.js.map