@jalvin/compiler 2.0.41 → 2.0.43

package/dist/codegen.js

@@ -1,9 +1,9 @@
 "use strict";
 // ─────────────────────────────────────────────────────────────────────────────
-// Jalvin Code Generator — AST → TypeScript
+// Jalvin Code Generator — AST → TypeScript/TSX
 //
 // Design principles:
-//   • component declarations  → Functional components (standard TS)
+//   • component declarations  → React functional components (TSX)
 //   • data class              → class with auto-generated copy(), equals(), toString()
 //   • sealed class            → TypeScript discriminated union + base class
 //   • extension functions     → module-level functions with receiver as first param,
@@ -89,6 +89,7 @@ class Writer {
     setSourceLine(line) { this.currentLine = line + 1; }
 }
 exports.DEFAULT_CODEGEN_OPTIONS = {
+    jsx: false,
     module: "esm",
     emitTypes: false,
     runtimeImport: "@jalvin/runtime",
@@ -98,10 +99,8 @@ class CodeGenerator {
     opts;
     hasComponents = false;
     runtimeSymbolsNeeded = new Set();
-    /** Names of true Jalvin components — used to detect functional calls */
-    userComponentNames = new Set();
-    /** Names of all potential components (including UI primitives) — used to detect props-object calls */
-    allComponentLikeNames = new Set();
+    /** Names of component functions — used to detect component calls and emit them as JSX */
+    componentNames = new Set();
     /**
      * Param names for components resolved from imported local .jalvin files.
      * Maps component name → ordered list of param names.
@@ -109,8 +108,6 @@ class CodeGenerator {
     componentParamNames = new Map();
     /** True when the program contains `import @jalvin/ui.*` — used to detect UI primitive calls */
     hasUiStarImport = false;
-    /** Names of symbols explicitly imported from @jalvin/ui */
-    uiNamedImports = new Set();
     /** Operator overload resolutions from the type checker */
     operatorOverloadMap = new Map();
     /** Type map from the type checker */
@@ -134,7 +131,6 @@ class CodeGenerator {
      * Maps module specifier (e.g. "src/views") → sorted list of exported names.
      */
     localStarExports = new Map();
-    isInClass = false;
     constructor(opts = {}) {
         this.opts = { ...exports.DEFAULT_CODEGEN_OPTIONS, ...opts };
     }
@@ -145,40 +141,34 @@ class CodeGenerator {
             this.typeMap = typeMap;
         // Pre-scan for components (local declarations OR @jalvin/ui imports)
         this.hasComponents = program.declarations.some((d) => d.kind === "ComponentDecl" ||
-            (d.kind === "ClassDecl" && d.body?.members.some((m) => m.kind === "ComponentDecl"))) || program.imports.some((imp) => imp.path[0] === "@jalvin" && imp.path[1] === "ui")
-            || this.containsJsx(program);
+            (d.kind === "ClassDecl" && d.body?.members.some((m) => m.kind === "ComponentDecl"))) || program.imports.some((imp) => imp.path[0] === "@jalvin" && imp.path[1] === "ui");
         // Collect component names for component call detection
-        this.userComponentNames = new Set();
-        this.allComponentLikeNames = new Set();
+        this.componentNames = new Set();
         this.componentParamNames = new Map();
         for (const decl of program.declarations) {
             if (decl.kind === "ComponentDecl") {
-                this.userComponentNames.add(decl.name);
-                this.allComponentLikeNames.add(decl.name);
+                this.componentNames.add(decl.name);
                 this.componentParamNames.set(decl.name, decl.params.map((p) => p.name));
             }
             if (decl.kind === "ClassDecl" && decl.body) {
                 for (const m of decl.body.members) {
                     if (m.kind === "ComponentDecl") {
-                        this.userComponentNames.add(m.name);
-                        this.allComponentLikeNames.add(m.name);
+                        this.componentNames.add(m.name);
                         this.componentParamNames.set(m.name, m.params.map((p) => p.name));
                     }
                 }
             }
         }
         this.hasUiStarImport = false;
-        this.uiNamedImports = new Set();
         for (const imp of program.imports) {
-            if (imp.path[0] === "@jalvin" && imp.path[1] === "ui") {
-                if (imp.star) {
-                    this.hasUiStarImport = true;
-                }
-                else {
-                    const name = imp.path[imp.path.length - 1];
-                    this.uiNamedImports.add(name);
-                    this.allComponentLikeNames.add(name);
-                }
+            // Named imports from @jalvin/ui are treated as potential component functions.
+            // Hooks (e.g. useIsHovered) are filtered out at call-site by the type-based guard below.
+            if (imp.path[0] === "@jalvin" && imp.path[1] === "ui" && !imp.star) {
+                this.componentNames.add(imp.path[imp.path.length - 1]);
+            }
+            // Star import from @jalvin/ui — UI primitives won't be in componentNames
+            if (imp.path[0] === "@jalvin" && imp.path[1] === "ui" && imp.star) {
+                this.hasUiStarImport = true;
             }
         }
         // Resolve component fun symbols from locally imported .jalvin files
@@ -212,42 +202,14 @@ class CodeGenerator {
         return {
             code,
             lineMap: this.w.lineMap,
-            hasComponents: this.hasComponents,
-        };
-    }
-    /** Walk AST to see if it contains any JsxElement nodes */
-    containsJsx(program) {
-        let found = false;
-        const walk = (val) => {
-            if (found || !val || typeof val !== "object")
-                return;
-            if (Array.isArray(val)) {
-                for (const item of val)
-                    walk(item);
-                return;
-            }
-            const obj = val;
-            if (obj["kind"] === "JsxElement") {
-                found = true;
-                return;
-            }
-            for (const propVal of Object.values(obj)) {
-                walk(propVal);
-            }
+            isJsx: this.hasComponents,
         };
-        for (const decl of program.declarations)
-            walk(decl);
-        return found;
     }
     // ── Preamble & imports ─────────────────────────────────────────────────────
     buildPreamble() {
         const lines = [];
-        lines.push("// ─────────────────────────────────────────────────────────────────────────────");
-        lines.push("// JALVIN COMPILER V5 - PURE VANILLA - NO REACT ALLOWED");
-        lines.push(`// BUILD ID: ${Date.now()}`);
-        lines.push("// ─────────────────────────────────────────────────────────────────────────────");
         if (this.hasComponents) {
-            this.runtimeSymbolsNeeded.add("jalvinCreateElement");
+            lines.push('import React from "react";');
         }
         // Emit compiler-injected runtime symbols, but only those NOT already covered
         // by a star-import's named-import expansion (to avoid duplicate imports).
@@ -264,6 +226,19 @@ class CodeGenerator {
         const sourceRoot = this.opts.sourceRoot ?? process.cwd();
         // Re-emit user imports as ES imports
         for (const imp of program.imports) {
+            // Build module specifier.
+            //
+            // Scoped packages (@org/pkg.Symbol): symbol is an export from the package,
+            // strip the last segment.
+            //   import @jalvin/ui.Column       → import { Column } from "@jalvin/ui"
+            //   import @jalvin/runtime.*       → import * as runtime from "@jalvin/runtime"
+            //
+            // Local imports (a.b.C): check whether the preceding segments already
+            // resolve to a file on disk.
+            //   import src.models.Rotation     → src/models/Rotation.ts does NOT exist
+            //                                    → import { Rotation } from "src/models/Rotation"
+            //   import src.models.css.Css      → src/models/css.ts DOES exist
+            //                                    → import { Css } from "src/models/css"
             const isScoped = imp.path[0].startsWith("@");
             let moduleSpecifier;
             if (imp.star) {
@@ -278,28 +253,35 @@ class CodeGenerator {
                 moduleSpecifier = moduleParts[0] + "/" + moduleParts.slice(1).join("/");
             }
             else {
-                // Non-scoped import: prefer local-file convention
+                // Non-scoped import: prefer local-file convention unless this looks like
+                // an installed npm package path (e.g. cubing/twisty.TwistyPlayer).
                 const precedingParts = imp.path.slice(0, -1);
                 const precedingRelPath = precedingParts.join("/");
                 const fileExts = [".ts", ".tsx", ".jalvin"];
                 const precedingIsFile = precedingParts.length > 0 && fileExts.some((ext) => fs.existsSync(nodePath.join(sourceRoot, precedingRelPath + ext)));
                 const looksLikeNpmPackage = this.isLikelyNodeModuleImport(imp.path, sourceRoot);
                 moduleSpecifier = precedingIsFile
-                    ? precedingRelPath
+                    ? precedingRelPath // src.models.css.Css → "src/models/css"
                     : looksLikeNpmPackage
-                        ? precedingRelPath
-                        : imp.path.join("/");
+                        ? precedingRelPath // cubing.twisty.TwistyPlayer → "cubing/twisty"
+                        : imp.path.join("/"); // src.models.Rotation → "src/models/Rotation"
             }
             if (imp.star && isScoped && this.externalStarCandidates.size > 0) {
+                // Named-import expansion of a scoped star import.
+                // Emit explicit named imports for each external symbol used in the file so
+                // that symbols like `ViewModel`, `mutableStateOf` are directly in scope.
                 const symbols = [...this.externalStarCandidates].sort();
                 this.w.writeIndentedLine(`import { ${symbols.join(", ")} } from "${moduleSpecifier}";`);
                 this.handledStarImportModules.add(moduleSpecifier);
             }
             else if (imp.star && !isScoped && this.localStarExports.has(moduleSpecifier)) {
+                // Local wildcard import: import src.module.* — expand to named imports
+                // so all exported symbols are directly in scope (no namespace qualifier needed).
                 const symbols = this.localStarExports.get(moduleSpecifier).slice().sort();
                 this.w.writeIndentedLine(`import { ${symbols.join(", ")} } from "${moduleSpecifier}";`);
             }
             else if (imp.star) {
+                // Fallback: namespace import (multiple scoped star imports or no candidates).
                 this.w.writeIndentedLine(`import * as ${imp.path[imp.path.length - 1]} from "${moduleSpecifier}";`);
             }
             else if (imp.alias) {
@@ -313,6 +295,11 @@ class CodeGenerator {
         if (program.imports.length > 0)
             this.w.writeLine();
     }
+    /**
+     * Heuristic for non-scoped imports: if the first path segment resolves to an
+     * installed package in node_modules, treat the import as npm/ESM and strip
+     * the trailing symbol name from the module specifier.
+     */
     isLikelyNodeModuleImport(pathParts, sourceRoot) {
         if (pathParts.length < 2)
             return false;
@@ -330,12 +317,14 @@ class CodeGenerator {
         return false;
     }
     // ── Top-level declarations ─────────────────────────────────────────────────
+    /** Emit a @deprecated JSDoc block if the declaration has @Nuked. */
     emitAnnotations(mods) {
         for (const ann of mods.annotations) {
             if (ann.name === "Nuked") {
                 const reason = ann.args ? ` ${ann.args.replace(/^["']|["']$/g, "")}` : "";
                 this.w.writeIndentedLine(`/** @deprecated${reason} */`);
             }
+            // Other annotations are silently ignored for now (pass-through model)
         }
     }
     emitTopLevelDecl(decl) {
@@ -390,6 +379,7 @@ class CodeGenerator {
             ? `: ${this.emitTypeRef(decl.returnType)}`
             : "";
         if (!decl.body) {
+            // Abstract / interface method
             this.w.writeIndentedLine(`${vis}${asyncKw}${decl.name}${typeParams}(${params})${retType};`);
             return;
         }
@@ -406,6 +396,7 @@ class CodeGenerator {
             this.w.writeIndentedLine(`}`);
         }
         else {
+            // Expression body
             if (memberOf) {
                 this.w.writeIndentedLine(`${vis}${asyncKw}${decl.name}${typeParams}(${params})${retType} {`);
             }
@@ -446,19 +437,21 @@ class CodeGenerator {
             this.w.writeIndentedLine(`}`);
         }
     }
-    // ── component declarations → Functional components ────────────────────
+    // ── component declarations → React function components ────────────────────
     emitComponentDecl(decl) {
         this.emitAnnotations(decl.modifiers);
         this.hasComponents = true;
-        const vis = this.isInClass ? this.visibilityPrefix(decl.modifiers) : this.exportPrefix(decl.modifiers);
-        const hasChildren = decl.params.some((p) => p.name === "children");
+        const vis = this.exportPrefix(decl.modifiers);
+        // "children" is passed as the second positional argument by emitComponentCall,
+        // so it must NOT be destructured from the props object.
         const propsParams = decl.params.filter((p) => p.name !== "children");
+        const hasChildren = decl.params.some((p) => p.name === "children");
         // Props interface
-        if (!this.isInClass && propsParams.length > 0) {
+        if (decl.params.length > 0) {
             this.w.writeIndentedLine(`interface ${decl.name}Props {`);
             this.w.pushIndent();
-            for (const p of propsParams) {
-                const optional = p.defaultValue ? "?" : "";
+            for (const p of decl.params) {
+                const optional = p.defaultValue || p.name === "children" ? "?" : "";
                 const typeStr = this.opts.emitTypes ? this.emitTypeRef(p.type) : "any";
                 this.w.writeIndentedLine(`readonly ${p.name}${optional}: ${typeStr};`);
             }
@@ -466,32 +459,21 @@ class CodeGenerator {
             this.w.writeIndentedLine(`}`);
             this.w.writeLine();
         }
-        const propsType = this.isInClass
-            ? `{ ${propsParams.map(p => {
-                const optional = p.defaultValue ? "?" : "";
-                const typeStr = this.opts.emitTypes ? this.emitTypeRef(p.type) : "any";
-                return `readonly ${p.name}${optional}: ${typeStr}`;
-            }).join("; ")} }`
-            : `${decl.name}Props`;
-        let signature = "";
-        if (propsParams.length > 0) {
-            signature = `{ ${propsParams.map((p) => p.name + (p.defaultValue ? ` = ${this.emitExpr(p.defaultValue)}` : "")).join(", ")} }: ${propsType}`;
-        }
-        else if (hasChildren) {
-            signature = "{}";
-        }
-        if (hasChildren) {
-            signature += signature ? ", children?: any" : "children?: any";
-        }
-        const sig = this.isInClass
-            ? `${decl.name}(${signature})`
-            : `function ${decl.name}(${signature})`;
-        this.w.writeIndentedLine(`${vis}${sig} {`);
+        const propsDestructure = decl.params.length > 0
+            ? `{ ${decl.params.map((p) => p.name + (p.defaultValue ? ` = ${this.emitExpr(p.defaultValue)}` : "")).join(", ")} }: ${decl.name}Props`
+            : "";
+        this.w.writeIndentedLine(`${vis}function ${decl.name}(${propsDestructure}) {`);
         this.w.pushIndent();
         this.emitComponentBlock(decl.body);
         this.w.popIndent();
         this.w.writeIndentedLine(`}`);
     }
+    /**
+     * Emit the body of a `component fun` block.
+     * The last statement is emitted in tail position — if it is an expression,
+     * an if/else chain, or a when block, the innermost UI call is implicitly
+     * returned (implicit return of the last expression).
+     */
     emitComponentBlock(block) {
         const stmts = block.statements;
         for (let i = 0; i < stmts.length; i++) {
@@ -504,8 +486,10 @@ class CodeGenerator {
             }
         }
     }
+    /** Emit a statement in tail position, adding implicit return where applicable. */
     emitTailStmt(stmt) {
         if (stmt.kind === "ExprStmt") {
+            // Implicit return: last expression in a component block
             this.w.writeIndentedLine(`return ${this.emitExpr(stmt.expr)};`);
         }
         else if (stmt.kind === "IfStmt") {
@@ -518,6 +502,7 @@ class CodeGenerator {
             this.emitStmt(stmt);
         }
     }
+    /** Emit a block in tail position, treating its last statement as a tail expression. */
     emitTailBlock(block) {
         const stmts = block.statements;
         for (let i = 0; i < stmts.length; i++) {
@@ -530,6 +515,7 @@ class CodeGenerator {
             }
         }
     }
+    /** Like emitIfStmt but with tail-return applied recursively to each branch body. */
     emitIfStmtWithTailReturn(stmt) {
         this.w.writeIndentedLine(`if (${this.emitExpr(stmt.condition)}) {`);
         this.w.pushIndent();
@@ -552,6 +538,7 @@ class CodeGenerator {
             this.w.writeIndentedLine(`}`);
         }
     }
+    /** Like emitWhenStmt but with tail-return applied recursively to each branch body. */
     emitWhenStmtWithTailReturn(stmt) {
         const subjectVar = stmt.subject ? "__when_subject__" : null;
         if (stmt.subject) {
@@ -588,12 +575,15 @@ class CodeGenerator {
         const superTypes = this.emitSuperTypesStr(decl.superTypes);
         this.w.writeIndentedLine(`${vis}${abstract}class ${decl.name}${typeParams}${superTypes} {`);
         this.w.pushIndent();
+        // The first supertype's delegateArgs become the `super(args)` call inside the constructor.
         const superDelegateArgs = decl.superTypes[0]?.delegateArgs ?? null;
         if (decl.primaryConstructor) {
             const initBlocks = decl.body?.members.filter((m) => m.kind === "InitBlock") ?? [];
             this.emitPrimaryConstructorProps(decl.primaryConstructor.params, initBlocks, superDelegateArgs);
         }
         else if (superDelegateArgs !== null) {
+            // No primary constructor but the supertype has explicit delegation args —
+            // emit a minimal constructor that forwards them to super().
             const superArgsStr = superDelegateArgs.map((a) => this.emitExpr(a.value)).join(", ");
             this.w.writeIndentedLine(`constructor() {`);
             this.w.pushIndent();
@@ -616,20 +606,24 @@ class CodeGenerator {
         const props = decl.primaryConstructor.params;
         this.w.writeIndentedLine(`${vis}class ${decl.name}${typeParams}${superTypes} {`);
         this.w.pushIndent();
+        // Discriminant for sealed class sub-types
         if (kindName) {
             this.w.writeIndentedLine(`readonly __kind = "${kindName}" as const;`);
         }
+        // Constructor params → readonly properties
         for (const p of props) {
             const t = this.opts.emitTypes ? `: ${this.emitTypeRef(p.type)}` : "";
             this.w.writeIndentedLine(`readonly ${p.name}${t};`);
         }
         this.w.writeLine();
+        // Constructor
         const ctorParams = props.map((p) => {
             const t = this.opts.emitTypes ? `: ${this.emitTypeRef(p.type)}` : "";
             return `${p.name}${t}`;
         }).join(", ");
         this.w.writeIndentedLine(`constructor(${ctorParams}) {`);
         this.w.pushIndent();
+        // Emit super() with actual delegation args (or empty call if delegateArgs is []).
         const dataSuperDelegateArgs = decl.superTypes[0]?.delegateArgs ?? null;
         if (dataSuperDelegateArgs !== null) {
             const superArgsStr = dataSuperDelegateArgs.map((a) => this.emitExpr(a.value)).join(", ");
@@ -641,6 +635,7 @@ class CodeGenerator {
         this.w.popIndent();
         this.w.writeIndentedLine(`}`);
         this.w.writeLine();
+        // copy()
         const copyParams = props.map((p) => {
             const t = this.opts.emitTypes ? `: ${this.emitTypeRef(p.type)}` : "";
             return `${p.name}${t} = this.${p.name}`;
@@ -652,6 +647,7 @@ class CodeGenerator {
         this.w.popIndent();
         this.w.writeIndentedLine(`}`);
         this.w.writeLine();
+        // equals()
         this.runtimeSymbolsNeeded.add("jalvinEquals");
         const eqChecks = props.map((p) => `jalvinEquals(this.${p.name}, other.${p.name})`).join(" && ") || "true";
         this.w.writeIndentedLine(`equals(other: unknown): boolean {`);
@@ -661,6 +657,7 @@ class CodeGenerator {
         this.w.popIndent();
         this.w.writeIndentedLine(`}`);
         this.w.writeLine();
+        // toString()
         const toStringParts = props.map((p) => `${p.name}=\${this.${p.name}}`).join(", ");
         this.w.writeIndentedLine(`toString(): string {`);
         this.w.pushIndent();
@@ -668,6 +665,7 @@ class CodeGenerator {
         this.w.popIndent();
         this.w.writeIndentedLine(`}`);
         this.w.writeLine();
+        // hashCode() — djb2
         this.w.writeIndentedLine(`hashCode(): number {`);
         this.w.pushIndent();
         this.w.writeIndentedLine(`let h = 17;`);
@@ -703,6 +701,7 @@ class CodeGenerator {
                 }
             }
         }
+        // Emit the abstract base class (only non-subtype members in the body)
         this.w.writeIndentedLine(`${vis}abstract class ${decl.name}${typeParams} {`);
         this.w.pushIndent();
         this.w.writeIndentedLine(`abstract readonly __kind: string;`);
@@ -715,6 +714,7 @@ class CodeGenerator {
         this.w.writeLine();
         if (subDecls.length === 0)
             return;
+        // Emit non-object sub-declarations at module level (before namespace)
         for (const sub of subDecls) {
             if (sub.kind === "DataClassDecl") {
                 this.emitDataClassDecl(sub, sub.name);
@@ -725,10 +725,12 @@ class CodeGenerator {
                 this.w.writeLine();
             }
         }
+        // Emit namespace merging so SealedClass.SubType is accessible
         this.w.writeIndentedLine(`${vis}namespace ${decl.name} {`);
         this.w.pushIndent();
         for (const sub of subDecls) {
             if (sub.kind === "ObjectDecl") {
+                // Singleton object — emit inline in namespace with __kind discriminant
                 const superStr = sub.superTypes.length > 0
                     ? this.emitSuperTypesStr(sub.superTypes)
                     : ` extends ${decl.name}`;
@@ -744,6 +746,7 @@ class CodeGenerator {
                 this.w.writeIndentedLine(`export const ${sub.name} = new (class${superStr} { ${membersStr} })();`);
             }
             else {
+                // DataClassDecl / ClassDecl — already emitted at module level, re-export
                 this.w.writeIndentedLine(`export { ${sub.name} };`);
             }
         }
@@ -754,8 +757,12 @@ class CodeGenerator {
     emitEnumClassDecl(decl) {
         const vis = this.exportPrefix(decl.modifiers);
         const typeParams = this.emitTypeParamsStr(decl.typeParams);
+        // Emit the enum as a TypeScript class with static singleton instances.
+        // This preserves the `EnumClass.ENTRY` access pattern and allows
+        // methods/properties to be attached to entries.
         this.w.writeIndentedLine(`${vis}class ${decl.name}${typeParams} {`);
         this.w.pushIndent();
+        // Private constructor so entries are the only instances
         if (decl.primaryConstructor && decl.primaryConstructor.params.length > 0) {
             const ctorParams = decl.primaryConstructor.params
                 .map((p) => {
@@ -770,6 +777,7 @@ class CodeGenerator {
             this.w.writeIndentedLine(`private constructor(readonly name: string, readonly ordinal: number) {}`);
         }
         this.w.writeLine();
+        // Static entry instances
         for (let i = 0; i < decl.entries.length; i++) {
             const entry = decl.entries[i];
             const args = entry.args.length > 0
@@ -779,6 +787,7 @@ class CodeGenerator {
         }
         if (decl.entries.length > 0) {
             this.w.writeLine();
+            // values() helper
             const entryList = decl.entries.map((e) => `${decl.name}.${e.name}`).join(", ");
             this.w.writeIndentedLine(`static values(): ${decl.name}[] { return [${entryList}]; }`);
             this.w.writeIndentedLine(`static valueOf(name: string): ${decl.name} {`);
@@ -796,12 +805,14 @@ class CodeGenerator {
         this.w.popIndent();
         this.w.writeIndentedLine(`}`);
     }
+    // ── destructuring declaration — val (a, b) = expr ─────────────────────────
     emitDestructuringDecl(decl, _memberOf) {
         const kw = decl.mutable ? "let" : "const";
         const names = decl.names.map((n) => n ?? "_").join(", ");
         const init = this.emitExpr(decl.initializer);
         this.w.writeIndentedLine(`${kw} [${names}] = ${init};`);
     }
+    // ── interface ──────────────────────────────────────────────────────────────
     emitInterfaceDecl(decl) {
         this.emitAnnotations(decl.modifiers);
         const vis = this.exportPrefix(decl.modifiers);
@@ -819,9 +830,12 @@ class CodeGenerator {
         this.w.popIndent();
         this.w.writeIndentedLine(`}`);
     }
+    // ── object declaration → singleton ────────────────────────────────────────
     emitObjectDecl(decl) {
-        if (!decl.name)
+        if (!decl.name) {
+            // Anonymous object — emitted inline
             return;
+        }
         this.emitAnnotations(decl.modifiers);
         const vis = this.exportPrefix(decl.modifiers);
         const superTypes = this.emitSuperTypesStr(decl.superTypes);
@@ -831,11 +845,16 @@ class CodeGenerator {
         this.w.popIndent();
         this.w.writeIndentedLine(`})();`);
     }
+    // ── type alias ─────────────────────────────────────────────────────────────
     emitTypeAliasDecl(decl) {
         const vis = this.exportPrefix(decl.modifiers);
         const typeParams = this.emitTypeParamsStr(decl.typeParams);
         this.w.writeIndentedLine(`${vis}type ${decl.name}${typeParams} = ${this.emitTypeRef(decl.type)};`);
     }
+    // ── extension functions ────────────────────────────────────────────────────
+    // Emitted as standalone free functions with receiver as explicit first param.
+    // For class types, also patched onto the prototype for dot-call syntax.
+    // For primitive types, call sites are rewritten via `primitiveExtensions`.
     emitExtensionFunDecl(decl) {
         const isSuspend = AST.isSuspend(decl.modifiers);
         const asyncKw = isSuspend ? "async " : "";
@@ -846,6 +865,9 @@ class CodeGenerator {
             ? `: ${this.emitTypeRef(decl.returnType)}`
             : "";
         const fnName = `__ext_${receiverType.replace(/[^a-zA-Z0-9_]/g, "_")}_${decl.name}`;
+        // Emit as a free function: receiver is the first explicit parameter `$receiver`.
+        // Inside the function body, `this` is rebound to `$receiver` so Jalvin's
+        // `this.prop` references work correctly.
         this.w.writeIndentedLine(`${asyncKw}function ${fnName}${typeParams}($receiver: ${receiverType}${params ? ", " + params : ""})${retType} {`);
         this.w.pushIndent();
         if (decl.body.kind === "Block") {
@@ -864,12 +886,14 @@ class CodeGenerator {
         const simpleReceiverName = this.receiverClassName(decl.receiver);
         if (simpleReceiverName) {
             if (PRIMITIVE_TYPES.has(simpleReceiverName)) {
+                // Register for call-site rewriting — cannot patch primitive prototypes
                 if (!this.primitiveExtensions.has(simpleReceiverName)) {
                     this.primitiveExtensions.set(simpleReceiverName, new Map());
                 }
                 this.primitiveExtensions.get(simpleReceiverName).set(decl.name, fnName);
             }
             else {
+                // Class types — prototype monkey-patch for dot-call syntax
                 this.w.writeIndentedLine(`// Extension: ${receiverType}.${decl.name}`);
                 this.w.writeIndentedLine(`(${simpleReceiverName}.prototype as any).${decl.name} = function(this: ${receiverType}, ...args: unknown[]) { return (${fnName} as Function)(this, ...args); };`);
             }
@@ -882,6 +906,11 @@ class CodeGenerator {
             return ref.base.name[ref.base.name.length - 1] ?? null;
         return null;
     }
+    /**
+     * Maps a JType to the primitive receiver type name used as a key
+     * in `primitiveExtensions` (e.g. JType `{ tag: "string" }` → `"String"`).
+     * Returns null for non-primitive / unknown types.
+     */
     jTypeToReceiverName(type) {
         const tagToReceiverName = {
             string: "String",
@@ -901,16 +930,19 @@ class CodeGenerator {
             m.name === "invoke" &&
             m.modifiers.modifiers.includes("operator"));
     }
+    // ── property declaration ───────────────────────────────────────────────────
     emitPropertyDecl(decl, member, isLocal = false) {
         this.emitAnnotations(decl.modifiers);
         const vis = member ? this.visibilityPrefix(decl.modifiers) : isLocal ? "" : this.exportPrefix(decl.modifiers);
         const isConst = decl.modifiers.modifiers.includes("const");
         const isLateinit = decl.modifiers.modifiers.includes("lateinit");
+        // `const val` → `const` at module level; inside classes treated as `static readonly`
         const kw = member
             ? (decl.mutable ? "" : "readonly ")
             : (isConst ? "const " : decl.mutable ? "let " : "const ");
         const type = decl.type && this.opts.emitTypes ? `: ${this.emitTypeRef(decl.type)}` : "";
         if (decl.delegate) {
+            // Delegated property — wrap in a getter/setter pair using the delegate
             this.runtimeSymbolsNeeded.add("delegate");
             const delegateExpr = this.emitExpr(decl.delegate);
             if (member) {
@@ -920,22 +952,28 @@ class CodeGenerator {
                 }
             }
             else {
+                // Non-member delegate: resolve via delegate().getValue() so the identifier
+                // holds the delegated value, not the raw delegate wrapper object.
                 this.w.writeIndentedLine(`${kw}${decl.name}${type} = delegate(${delegateExpr}, "${decl.name}", null).getValue();`);
             }
             return;
         }
-        const init = decl.initializer ? ` = ${this.emitExpr(decl.initializer)}` : "";
+        const init = decl.initializer ? ` = ${this.emitExpr(decl.initializer)}` : (isLateinit ? "" : "");
         if (member && !decl.getter) {
+            // Skip backing field when a getter is defined — TypeScript forbids both
+            // `readonly name: T` and `get name()` with the same name in a class.
             const modStr = isConst ? "static readonly " : decl.mutable ? "" : "readonly ";
             this.w.writeIndentedLine(`${vis}${modStr}${decl.name}${type}${init};`);
         }
         else if (!member) {
             this.w.writeIndentedLine(`${vis}${kw}${decl.name}${type}${init};`);
         }
-        if (decl.getter)
+        if (decl.getter) {
             this.emitPropertyAccessor("get", decl.name, decl.getter, member, type);
-        if (decl.setter)
+        }
+        if (decl.setter) {
             this.emitPropertyAccessor("set", decl.name, decl.setter, member, type);
+        }
     }
     emitPropertyAccessor(kind, name, acc, member, type) {
         const vis = this.visibilityPrefix(acc.modifiers);
@@ -955,19 +993,14 @@ class CodeGenerator {
         this.w.popIndent();
         this.w.writeIndentedLine(`}`);
     }
+    // ── class body ─────────────────────────────────────────────────────────────
     emitClassBody(body) {
-        const old = this.isInClass;
-        this.isInClass = true;
-        try {
-            for (const member of body.members) {
-                if (member.kind === "InitBlock")
-                    continue;
-                this.emitClassMember(member);
-                this.w.writeLine();
-            }
-        }
-        finally {
-            this.isInClass = old;
+        for (const member of body.members) {
+            // InitBlocks are emitted inside the constructor by emitPrimaryConstructorProps
+            if (member.kind === "InitBlock")
+                continue;
+            this.emitClassMember(member);
+            this.w.writeLine();
         }
     }
     emitClassMember(member) {
@@ -999,6 +1032,7 @@ class CodeGenerator {
             case "CompanionObject":
                 this.emitCompanionObject(member);
                 break;
+            case "InitBlock": /* handled in constructor */ break;
             case "SecondaryConstructor":
                 this.emitSecondaryConstructor(member);
                 break;
@@ -1015,13 +1049,16 @@ class CodeGenerator {
                 this.w.writeIndentedLine(`${ro}${p.name}${type};`);
             }
         }
+        // Constructor
         const ctorParams = params.map((p) => {
+            const ro = p.propertyKind === "val" ? "readonly " : p.propertyKind === "var" ? "" : "";
             const type = this.opts.emitTypes ? `: ${this.emitTypeRef(p.type)}` : "";
             const def = p.defaultValue ? ` = ${this.emitExpr(p.defaultValue)}` : "";
             return `${p.name}${type}${def}`;
         });
         this.w.writeIndentedLine(`constructor(${ctorParams.join(", ")}) {`);
         this.w.pushIndent();
+        // super() call must be the first statement if there is a supertype.
         if (superDelegateArgs !== null && superDelegateArgs !== undefined) {
             const superArgsStr = superDelegateArgs.map((a) => this.emitExpr(a.value)).join(", ");
             this.w.writeIndentedLine(`super(${superArgsStr});`);
@@ -1031,13 +1068,17 @@ class CodeGenerator {
                 this.w.writeIndentedLine(`this.${p.name} = ${p.name};`);
             }
         }
-        for (const ib of (initBlocks ?? []))
+        // Emit init{} blocks inside the constructor, in declaration order
+        for (const ib of (initBlocks ?? [])) {
             this.emitBlock(ib.body);
+        }
         this.w.popIndent();
         this.w.writeIndentedLine(`}`);
         this.w.writeLine();
     }
     emitCompanionObject(co) {
+        // Emit companion object members as `static` members of the outer class so that
+        // `MyClass.factoryMethod()` works directly (standard semantics).
         for (const member of co.body.members) {
             if (member.kind === "FunDecl") {
                 const vis = this.visibilityPrefix(member.modifiers);
@@ -1082,9 +1123,11 @@ class CodeGenerator {
         this.w.popIndent();
         this.w.writeIndentedLine(`}`);
     }
+    // ── Statements ─────────────────────────────────────────────────────────────
     emitBlock(block) {
-        for (const stmt of block.statements)
+        for (const stmt of block.statements) {
             this.emitStmt(stmt);
+        }
     }
     emitStmt(stmt) {
         switch (stmt.kind) {
@@ -1173,6 +1216,8 @@ class CodeGenerator {
         }
     }
     emitWhenStmt(stmt) {
+        // when(subject) { is Foo -> ... else -> ... }
+        // Compiles to a series of if/else-if chains
         const subjectVar = stmt.subject ? "__when_subject__" : null;
         if (stmt.subject) {
             const binding = stmt.subject.binding ?? subjectVar;
@@ -1189,10 +1234,12 @@ class CodeGenerator {
             }
             first = false;
             this.w.pushIndent();
-            if (branch.body.kind === "Block")
+            if (branch.body.kind === "Block") {
                 this.emitBlock(branch.body);
-            else
+            }
+            else {
                 this.w.writeIndentedLine(`${this.emitExpr(branch.body)};`);
+            }
             this.w.popIndent();
         }
         this.w.writeIndentedLine(`}`);
@@ -1200,6 +1247,8 @@ class CodeGenerator {
     emitWhenCondition(cond, subject) {
         switch (cond.kind) {
             case "WhenIsCondition": {
+                // Qualified name (e.g. UiState.Loading) → use __kind discriminant
+                // Single name (e.g. BibiError) → use instanceof
                 const isQualified = cond.type.kind === "SimpleTypeRef" && cond.type.name.length > 1;
                 const check = isQualified
                     ? `(${subject} as any).__kind === "${cond.type.kind === "SimpleTypeRef" ? cond.type.name[cond.type.name.length - 1] : ""}"`
@@ -1229,6 +1278,7 @@ class CodeGenerator {
         }
         else {
             const { key, value } = stmt.binding;
+            // Use .entries() for JS Map (Map<K,V>), Object.entries() for plain objects
             const iterableType = this.typeMap.get(stmt.iterable);
             const isMap = iterableType?.tag === "class" && iterableType.name === "Map";
             const entries = isMap ? `${iter}.entries()` : `Object.entries(${iter})`;
@@ -1247,6 +1297,9 @@ class CodeGenerator {
         for (const c of stmt.catches) {
             this.w.writeIndentedLine(`} catch (${c.name}: unknown) {`);
             this.w.pushIndent();
+            // Narrow type — always emit the guard so catch clauses are type-safe
+            // regardless of the emitTypes option (which controls explicit type annotations,
+            // not runtime type checks).
             this.w.writeIndentedLine(`if (!(${c.name} instanceof ${this.emitTypeRef(c.type)})) throw ${c.name};`);
             this.emitBlock(c.body);
             this.w.popIndent();
@@ -1259,6 +1312,7 @@ class CodeGenerator {
         }
         this.w.writeIndentedLine(`}`);
     }
+    // ── Expressions ────────────────────────────────────────────────────────────
     emitExpr(expr) {
         switch (expr.kind) {
             case "IntLiteralExpr": return String(expr.value);
@@ -1268,12 +1322,17 @@ class CodeGenerator {
             case "BooleanLiteralExpr": return String(expr.value);
             case "NullLiteralExpr": return "null";
             case "StringLiteralExpr":
-                return expr.raw ? `\`${expr.value}\`` : JSON.stringify(expr.value);
+                return expr.raw
+                    ? `\`${expr.value}\``
+                    : JSON.stringify(expr.value);
             case "StringTemplateExpr":
                 return this.emitStringTemplate(expr);
             case "NameExpr":
-                if (expr.name === "Int" || expr.name === "Long")
+                // Ensure Int/Long companion objects are imported from the runtime
+                if (expr.name === "Int" || expr.name === "Long") {
                     this.runtimeSymbolsNeeded.add(expr.name);
+                }
+                // Unit singleton emits as undefined (void semantics)
                 if (expr.name === "Unit")
                     return "undefined";
                 return expr.name;
@@ -1289,23 +1348,34 @@ class CodeGenerator {
                 if (opMethod) {
                     const l = this.emitExpr(expr.left);
                     const r = this.emitExpr(expr.right);
-                    if (opMethod === "compareTo")
-                        return `(${l}.compareTo(${r}) ${expr.op} 0)`;
-                    if (opMethod === "contains")
+                    // `compareTo` overloads: wrap result in a comparison against 0
+                    if (opMethod === "compareTo") {
+                        const cmpOp = expr.op;
+                        return `(${l}.compareTo(${r}) ${cmpOp} 0)`;
+                    }
+                    // `contains` overloads: `element in collection` → `collection.contains(element)`
+                    if (opMethod === "contains") {
                         return `${r}.contains(${l})`;
-                    if (opMethod === "!contains")
+                    }
+                    if (opMethod === "!contains") {
                         return `!${r}.contains(${l})`;
+                    }
+                    // Generic operator overload: emit as method call `left.method(right)`
                     return `${l}.${opMethod}(${r})`;
                 }
+                // `==` → structural equality, `!=` → negation
                 if (expr.op === "==" || expr.op === "!=") {
                     this.runtimeSymbolsNeeded.add("jalvinEquals");
                     const eq = `jalvinEquals(${this.emitExpr(expr.left)}, ${this.emitExpr(expr.right)})`;
                     return expr.op === "==" ? eq : `!${eq}`;
                 }
-                if (expr.op === "in")
+                // `in` / `!in` without a user-defined operator: use JS `in` / array includes
+                if (expr.op === "in") {
                     return `${this.emitExpr(expr.right)}.includes?.(${this.emitExpr(expr.left)}) ?? (${this.emitExpr(expr.left)} in ${this.emitExpr(expr.right)})`;
-                if (expr.op === "!in")
+                }
+                if (expr.op === "!in") {
                     return `!(${this.emitExpr(expr.right)}.includes?.(${this.emitExpr(expr.left)}) ?? (${this.emitExpr(expr.left)} in ${this.emitExpr(expr.right)}))`;
+                }
                 return `(${this.emitExpr(expr.left)} ${this.binaryOpStr(expr.op)} ${this.emitExpr(expr.right)})`;
             }
             case "AssignExpr":
@@ -1316,81 +1386,124 @@ class CodeGenerator {
                 return expr.prefix
                     ? `${expr.op}${this.emitExpr(expr.target)}`
                     : `${this.emitExpr(expr.target)}${expr.op}`;
-            case "MemberExpr": return `${this.emitExpr(expr.target)}.${expr.member}`;
-            case "SafeMemberExpr": return `${this.emitExpr(expr.target)}?.${expr.member}`;
-            case "IndexExpr": return `${this.emitExpr(expr.target)}[${this.emitExpr(expr.index)}]`;
+            case "MemberExpr":
+                return `${this.emitExpr(expr.target)}.${expr.member}`;
+            case "SafeMemberExpr":
+                return `${this.emitExpr(expr.target)}?.${expr.member}`;
+            case "IndexExpr":
+                return `${this.emitExpr(expr.target)}[${this.emitExpr(expr.index)}]`;
             case "NotNullExpr":
+                // Runtime check
                 this.runtimeSymbolsNeeded.add("notNull");
                 return `notNull(${this.emitExpr(expr.expr)})`;
             case "SafeCallExpr": {
+                // x?.() — safe invocation of a nullable function value
                 const callee = this.emitExpr(expr.callee);
-                const restArgs = expr.args.map((a) => a.spread ? `...${this.emitExpr(a.value)}` : this.emitExpr(a.value));
+                const restArgs = [];
+                for (const a of expr.args) {
+                    restArgs.push(a.spread ? `...${this.emitExpr(a.value)}` : this.emitExpr(a.value));
+                }
                 if (expr.trailingLambda)
                     restArgs.push(this.emitLambdaExpr(expr.trailingLambda));
                 return `${callee}?.(${restArgs.join(", ")})`;
             }
-            case "ElvisExpr": return `(${this.emitExpr(expr.left)} ?? ${this.emitExpr(expr.right)})`;
-            case "CallExpr": return this.emitCallExpr(expr);
-            case "LambdaExpr": return this.emitLambdaExpr(expr);
-            case "IfExpr": return this.emitIfExpr(expr);
-            case "WhenExpr": return this.emitWhenExpr(expr);
-            case "TryCatchExpr": return this.emitTryCatchExpr(expr);
-            case "TypeCheckExpr": return `${expr.negated ? "!(" : ""}${this.emitExpr(expr.expr)} instanceof ${this.emitTypeRef(expr.type)}${expr.negated ? ")" : ""}`;
-            case "TypeCastExpr": return `(${this.emitExpr(expr.expr)} as unknown as ${this.emitTypeRef(expr.type)})`;
-            case "SafeCastExpr":
+            case "ElvisExpr": {
+                // left ?? right  (null coalescing)
+                return `(${this.emitExpr(expr.left)} ?? ${this.emitExpr(expr.right)})`;
+            }
+            case "CallExpr":
+                return this.emitCallExpr(expr);
+            case "LambdaExpr":
+                return this.emitLambdaExpr(expr);
+            case "IfExpr":
+                return this.emitIfExpr(expr);
+            case "WhenExpr":
+                return this.emitWhenExpr(expr);
+            case "TryCatchExpr":
+                return this.emitTryCatchExpr(expr);
+            case "TypeCheckExpr":
+                return `${expr.negated ? "!(" : ""}${this.emitExpr(expr.expr)} instanceof ${this.emitTypeRef(expr.type)}${expr.negated ? ")" : ""}`;
+            case "TypeCastExpr":
+                // Unsafe cast — emit as `(expr as Type)` which is stripped at runtime
+                return `(${this.emitExpr(expr.expr)} as unknown as ${this.emitTypeRef(expr.type)})`;
+            case "SafeCastExpr": {
                 this.runtimeSymbolsNeeded.add("safeCast");
                 return `safeCast(${this.emitExpr(expr.expr)}, ${this.emitTypeRef(expr.type)})`;
-            case "RangeExpr":
+            }
+            case "RangeExpr": {
                 this.runtimeSymbolsNeeded.add("range");
                 return `range(${this.emitExpr(expr.from)}, ${this.emitExpr(expr.to)}, ${expr.inclusive})`;
+            }
             case "LaunchExpr": {
+                // fire-and-forget → void IIFE
                 const stmts = this.captureBlock(expr.body);
                 return `(async () => { ${stmts} })()`;
             }
             case "AsyncExpr": {
+                // returns Promise<T>
                 const stmts = this.captureBlock(expr.body);
                 return `(async () => { ${stmts} })()`;
             }
-            case "CollectionLiteralExpr": return this.emitCollectionLiteral(expr);
-            case "ObjectExpr": return this.emitObjectExpr(expr);
+            case "CollectionLiteralExpr":
+                return this.emitCollectionLiteral(expr);
+            case "ObjectExpr":
+                return this.emitObjectExpr(expr);
             case "ReturnExpr": {
                 const val = expr.value ? ` ${this.emitExpr(expr.value)}` : "";
                 return `((() => { return${val}; })())`;
             }
             case "BreakExpr": return "undefined /* break */";
             case "ContinueExpr": return "undefined /* continue */";
-            case "JsxElement": return this.emitJsxElement(expr);
-            default: return "undefined";
+            case "JsxElement":
+                return this.emitJsxElement(expr);
+            default:
+                return "undefined";
         }
     }
+    // ── JSX ──────────────────────────────────────────────────────────────────
     emitJsxElement(expr) {
-        this.runtimeSymbolsNeeded.add("jalvinCreateElement");
         const attrsStr = expr.attrs.length > 0
-            ? "{ " + expr.attrs.map((a) => this.emitJsxAttr(a)).join(", ") + " }"
-            : "{}";
-        const childrenArr = expr.children.length > 0
-            ? "[" + expr.children.map((c) => this.emitJsxChild(c)).join(", ") + "]"
-            : "[]";
-        return `jalvinCreateElement(${JSON.stringify(expr.tag)}, ${attrsStr}, ${childrenArr})`;
+            ? " " + expr.attrs.map((a) => this.emitJsxAttr(a)).join(" ")
+            : "";
+        if (expr.children.length === 0) {
+            return `<${expr.tag}${attrsStr} />`;
+        }
+        const children = expr.children.map((c) => this.emitJsxChild(c)).join("");
+        return `<${expr.tag}${attrsStr}>${children}</${expr.tag}>`;
     }
     emitJsxAttr(attr) {
-        const name = attr.name === "class" ? "className" : attr.name === "for" ? "htmlFor" : attr.name;
-        const val = attr.value === null ? "true" : typeof attr.value === "string" ? JSON.stringify(attr.value) : this.emitExpr(attr.value);
-        return `${name}: ${val}`;
+        // Map HTML attribute names to React prop names
+        const name = attr.name === "class" ? "className"
+            : attr.name === "for" ? "htmlFor"
+                : attr.name;
+        if (attr.value === null)
+            return name;
+        if (typeof attr.value === "string")
+            return `${name}="${attr.value}"`;
+        return `${name}={${this.emitExpr(attr.value)}}`;
     }
     emitJsxChild(child) {
         switch (child.kind) {
             case "JsxElement": return this.emitJsxElement(child);
-            case "JsxExprChild": return this.emitExpr(child.expr);
-            case "JsxTextChild": return `document.createTextNode(${JSON.stringify(child.text)})`;
+            case "JsxExprChild": return `{${this.emitExpr(child.expr)}}`;
+            case "JsxTextChild": return child.text;
         }
     }
     emitStringTemplate(expr) {
-        const inner = expr.parts.map((p) => p.kind === "LiteralPart" ? p.value.replace(/`/g, "\\`").replace(/\\/g, "\\\\") : `\${${this.emitExpr(p.expr)}}`).join("");
+        const inner = expr.parts.map((p) => {
+            if (p.kind === "LiteralPart") {
+                return p.value.replace(/`/g, "\\`").replace(/\\/g, "\\\\");
+            }
+            return `\${${this.emitExpr(p.expr)}}`;
+        }).join("");
         return `\`${inner}\``;
     }
     emitCallExpr(expr) {
-        if (expr.callee.kind === "MemberExpr" && (expr.callee.member === "downTo" || expr.callee.member === "until" || expr.callee.member === "step")) {
+        // Rewrite infix numeric extension calls that JS numbers don't natively have:
+        //   `a.downTo(b)` → `downTo(a, b)`   `a.until(b)` → `range(a, b, false)`
+        //   `range.step(n)` → `step(range, n)`
+        if (expr.callee.kind === "MemberExpr" &&
+            (expr.callee.member === "downTo" || expr.callee.member === "until" || expr.callee.member === "step")) {
             const obj = this.emitExpr(expr.callee.target);
             const arg = expr.args.length > 0 ? this.emitExpr(expr.args[0].value) : "0";
             if (expr.callee.member === "downTo") {
@@ -1406,39 +1519,51 @@ class CodeGenerator {
                 return `step(${obj}, ${arg})`;
             }
         }
+        // Rewrite calls on primitive-receiver extension functions.
+        // `str.truncate(30)` where `String.truncate` is a user extension → `__ext_string_truncate(str, 30)`
         if (expr.callee.kind === "MemberExpr") {
             const scopeMember = expr.callee.member;
-            const receiver = this.emitExpr(expr.callee.target);
-            const lambda = expr.trailingLambda ?? (expr.args.length === 1 && expr.args[0].value.kind === "LambdaExpr" ? expr.args[0].value : null);
-            if (lambda) {
-                if (scopeMember === "let") {
-                    this.runtimeSymbolsNeeded.add("let_");
-                    return `let_(${receiver}, ${this.emitLambdaExpr(lambda)})`;
-                }
-                if (scopeMember === "also") {
-                    this.runtimeSymbolsNeeded.add("also");
-                    return `also(${receiver}, ${this.emitLambdaExpr(lambda)})`;
-                }
-                if (scopeMember === "apply") {
-                    this.runtimeSymbolsNeeded.add("apply");
-                    const body = this.captureBlockStatements(lambda.body);
-                    return `apply(${receiver}, function(this: any) { ${body} })`;
-                }
-                if (scopeMember === "run") {
-                    this.runtimeSymbolsNeeded.add("run_");
-                    const body = this.captureBlockStatements(lambda.body);
-                    return `run_(${receiver}, function(this: any) { ${body} })`;
-                }
-                if (scopeMember === "takeIf") {
-                    this.runtimeSymbolsNeeded.add("takeIf");
-                    return `takeIf(${receiver}, ${this.emitLambdaExpr(lambda)})`;
-                }
-                if (scopeMember === "takeUnless") {
-                    this.runtimeSymbolsNeeded.add("takeUnless");
-                    return `takeUnless(${receiver}, ${this.emitLambdaExpr(lambda)})`;
+            // Scope function call rewriting: `x.let { ... }` → `let_(x, ...)`
+            // `x.apply { ... }` → `apply(x, function(this:any) { ... })`
+            if (scopeMember === "let" || scopeMember === "also" || scopeMember === "apply" || scopeMember === "run" || scopeMember === "takeIf" || scopeMember === "takeUnless") {
+                const receiver = this.emitExpr(expr.callee.target);
+                const lambda = expr.trailingLambda ??
+                    (expr.args.length === 1 && expr.args[0].value.kind === "LambdaExpr"
+                        ? expr.args[0].value
+                        : null);
+                if (lambda) {
+                    if (scopeMember === "let") {
+                        this.runtimeSymbolsNeeded.add("let_");
+                        return `let_(${receiver}, ${this.emitLambdaExpr(lambda)})`;
+                    }
+                    if (scopeMember === "also") {
+                        this.runtimeSymbolsNeeded.add("also");
+                        return `also(${receiver}, ${this.emitLambdaExpr(lambda)})`;
+                    }
+                    if (scopeMember === "apply") {
+                        this.runtimeSymbolsNeeded.add("apply");
+                        const body = this.captureBlockStatements(lambda.body);
+                        return `apply(${receiver}, function(this: any) { ${body} })`;
+                    }
+                    if (scopeMember === "run") {
+                        this.runtimeSymbolsNeeded.add("run_");
+                        const body = this.captureBlockStatements(lambda.body);
+                        return `run_(${receiver}, function(this: any) { ${body} })`;
+                    }
+                    if (scopeMember === "takeIf") {
+                        this.runtimeSymbolsNeeded.add("takeIf");
+                        return `takeIf(${receiver}, ${this.emitLambdaExpr(lambda)})`;
+                    }
+                    if (scopeMember === "takeUnless") {
+                        this.runtimeSymbolsNeeded.add("takeUnless");
+                        return `takeUnless(${receiver}, ${this.emitLambdaExpr(lambda)})`;
+                    }
                 }
             }
+            // `with(x) { ... }` is a free function handled via seedBuiltins; but rewrite if emitted as member
         }
+        // Rewrite calls on primitive-receiver extension functions.
+        // `str.truncate(30)` where `String.truncate` is a user extension → `__ext_string_truncate(str, 30)`
         if (expr.callee.kind === "MemberExpr") {
             const receiverType = this.typeMap.get(expr.callee.target);
             const memberName = expr.callee.member;
@@ -1458,69 +1583,105 @@ class CodeGenerator {
             }
         }
         const callee = this.emitExpr(expr.callee);
-        const typeArgs = expr.typeArgs.length > 0 ? `<${expr.typeArgs.map((t) => t.star ? "*" : this.emitTypeRef(t.type)).join(", ")}>` : "";
-        if (expr.callee.kind === "NameExpr" && expr.callee.name === "with" && (expr.trailingLambda || (expr.args.length === 2 && expr.args[1].value.kind === "LambdaExpr"))) {
+        const typeArgs = expr.typeArgs.length > 0
+            ? `<${expr.typeArgs.map((t) => t.star ? "*" : this.emitTypeRef(t.type)).join(", ")}>`
+            : "";
+        // Rewrite top-level `with(obj) { ... }` → `with_(obj, function(this: any) { ... })`
+        if (expr.callee.kind === "NameExpr" && expr.callee.name === "with" &&
+            (expr.trailingLambda || (expr.args.length === 2 && expr.args[1].value.kind === "LambdaExpr"))) {
             const obj = expr.args.length > 0 ? this.emitExpr(expr.args[0].value) : "undefined";
-            const lambda = expr.trailingLambda ?? expr.args[1].value;
+            const lambda = expr.trailingLambda ??
+                expr.args[1].value;
             this.runtimeSymbolsNeeded.add("with_");
             const body = this.captureBlockStatements(lambda.body);
             return `with_(${obj}, function(this: any) { ${body} })`;
         }
-        if (expr.callee.kind === "NameExpr" && expr.callee.name === "run" && expr.args.length === 0 && expr.trailingLambda) {
+        // Rewrite top-level `run { ... }` (no receiver) — just call the lambda
+        if (expr.callee.kind === "NameExpr" && expr.callee.name === "run" &&
+            expr.args.length === 0 && expr.trailingLambda) {
             return `(${this.emitLambdaExpr(expr.trailingLambda)})()`;
         }
+        // Handle named arguments by reordering them to match positional parameters
         const calleeType = this.typeMap.get(expr.callee);
+        // Component call: Column(modifier = ...) { ... } → Column({ modifier: ... }, [children])
+        // Also catches star-imported @jalvin/ui primitives (Row, Button, etc.) whose type is T_UNKNOWN
+        //
+        // Skip the component path when the typechecker resolved a func type with explicit paramNames.
+        // That indicates a regular function (fun) or a built-in hook — both use positional calling.
+        // component fun declarations intentionally omit paramNames from their func type.
         const isKnownPositionalFunc = calleeType?.tag === "func" && calleeType.paramNames !== undefined;
-        let isComponentLike = false;
-        if (expr.callee.kind === "NameExpr") {
-            isComponentLike = this.allComponentLikeNames.has(expr.callee.name) || (this.hasUiStarImport && (!calleeType || calleeType.tag === "unknown") && /^[A-Z]/.test(expr.callee.name));
-        }
-        else if (expr.callee.kind === "MemberExpr" || expr.callee.kind === "SafeMemberExpr") {
-            isComponentLike = this.allComponentLikeNames.has(expr.callee.member);
-        }
-        if (!isKnownPositionalFunc && isComponentLike)
+        if (!isKnownPositionalFunc && expr.callee.kind === "NameExpr" && (this.componentNames.has(expr.callee.name) ||
+            (this.hasUiStarImport && (!calleeType || calleeType.tag === "unknown") && /^[A-Z]/.test(expr.callee.name)))) {
             return this.emitComponentCall(expr);
+        }
         let finalArgs = [];
         if (calleeType && calleeType.tag === "func" && calleeType.paramNames) {
             const paramNames = calleeType.paramNames;
             const argsByName = new Map();
             const positionalArgs = [];
             for (const arg of expr.args) {
-                if (arg.name)
+                if (arg.name) {
                     argsByName.set(arg.name, arg.spread ? `...${this.emitExpr(arg.value)}` : this.emitExpr(arg.value));
-                else
+                }
+                else {
                     positionalArgs.push(arg.spread ? `...${this.emitExpr(arg.value)}` : this.emitExpr(arg.value));
+                }
             }
+            // Reconstruct args based on paramNames
             for (let i = 0; i < paramNames.length; i++) {
                 const name = paramNames[i];
-                if (argsByName.has(name))
+                if (argsByName.has(name)) {
                     finalArgs.push(argsByName.get(name));
-                else if (i < positionalArgs.length)
+                }
+                else if (i < positionalArgs.length) {
                     finalArgs.push(positionalArgs[i]);
-                else
+                }
+                else {
+                    // Missing argument - JS default value logic will handle it if we pass undefined
                     finalArgs.push("undefined");
+                }
             }
-            if (positionalArgs.length > paramNames.length)
+            // Handle trailing positional args if any
+            if (positionalArgs.length > paramNames.length) {
                 finalArgs.push(...positionalArgs.slice(paramNames.length));
+            }
         }
         else {
-            finalArgs = expr.args.map((a) => a.spread ? `...${this.emitExpr(a.value)}` : this.emitExpr(a.value));
+            // Fallback for types we don't know param names for (like constructors or any)
+            finalArgs = expr.args.map((a) => {
+                return a.spread ? `...${this.emitExpr(a.value)}` : this.emitExpr(a.value);
+            });
         }
-        if (expr.trailingLambda)
+        if (expr.trailingLambda) {
             finalArgs.push(this.emitLambdaExpr(expr.trailingLambda));
-        if (calleeType && calleeType.tag === "class" && calleeType.decl && this.classHasInvokeOperator(calleeType.decl)) {
+        }
+        // If the callee is a class instance (not a constructor / function), emit `.invoke(args)`
+        if (calleeType &&
+            calleeType.tag === "class" &&
+            calleeType.decl &&
+            this.classHasInvokeOperator(calleeType.decl)) {
             return `${callee}.invoke(${finalArgs.join(", ")})`;
         }
-        if (this.isConstructorCall(expr.callee))
+        // Constructor calls: class names start with uppercase by convention
+        if (this.isConstructorCall(expr.callee)) {
             return `new ${callee}${typeArgs}(${finalArgs.join(", ")})`;
+        }
         return `${callee}${typeArgs}(${finalArgs.join(", ")})`;
     }
+    /**
+     * For each non-scoped local import (e.g. `import src.views.MoveCounterView.MoveCounter`),
+     * attempt to load and parse the corresponding .jalvin source file. If the named symbol is
+     * a `component fun`, register it in `componentNames` and record its param names so that
+     * call sites can emit the correct props-object invocation.
+     */
     resolveLocalComponentImports(program, sourceRoot) {
         this.localStarExports.clear();
         for (const imp of program.imports) {
+            // Skip scoped packages (@org/pkg)
             if (imp.path[0]?.startsWith("@"))
                 continue;
             if (imp.star) {
+                // Local wildcard import: import src.module.* — load all exports from src/module.jalvin
                 if (imp.path.length < 1)
                     continue;
                 const candidatePath = nodePath.join(sourceRoot, imp.path.join("/") + ".jalvin");
@@ -1543,27 +1704,21 @@ class CodeGenerator {
                             continue;
                         exportedNames.push(name);
                         if (d.kind === "ComponentDecl") {
-                            this.userComponentNames.add(name);
-                            this.allComponentLikeNames.add(name);
+                            this.componentNames.add(name);
                             this.componentParamNames.set(name, d.params.map((p) => p.name));
                             this.hasComponents = true;
                         }
-                        if (d.kind === "ClassDecl" && d.body) {
-                            for (const m of d.body.members) {
-                                if (m.kind === "ComponentDecl") {
-                                    this.allComponentLikeNames.add(m.name);
-                                    this.componentParamNames.set(m.name, m.params.map((p) => p.name));
-                                    this.hasComponents = true;
-                                }
-                            }
-                        }
                     }
-                    if (exportedNames.length > 0)
+                    if (exportedNames.length > 0) {
                         this.localStarExports.set(moduleSpecifier, exportedNames);
+                    }
+                }
+                catch {
+                    // Silently skip if the file cannot be read or parsed
                 }
-                catch { }
                 continue;
             }
+            // Named import: last path segment is the symbol, preceding segments form the file path
             if (imp.path.length < 2)
                 continue;
             const rawSymbolName = imp.path[imp.path.length - 1];
@@ -1581,237 +1736,574 @@ class CodeGenerator {
                 const ast = (0, parser_js_1.parse)(tokens, candidatePath, diag, source);
                 if (diag.hasErrors)
                     continue;
-                const decl = ast.declarations.find((d) => ((d.kind === "ComponentDecl" || d.kind === "ClassDecl") && d.name === rawSymbolName));
-                if (decl?.kind === "ComponentDecl") {
-                    this.userComponentNames.add(symbolName);
-                    this.allComponentLikeNames.add(symbolName);
-                    this.componentParamNames.set(symbolName, decl.params.map((p) => p.name));
+                // Look for a top-level ComponentDecl matching the imported symbol name
+                const compDecl = ast.declarations.find((d) => d.kind === "ComponentDecl" && d.name === rawSymbolName);
+                if (compDecl) {
+                    this.componentNames.add(symbolName);
+                    this.componentParamNames.set(symbolName, compDecl.params.map((p) => p.name));
                     this.hasComponents = true;
                 }
-                else if (decl?.kind === "ClassDecl" && decl.body) {
-                    for (const m of decl.body.members) {
-                        if (m.kind === "ComponentDecl") {
-                            this.userComponentNames.add(m.name);
-                            this.allComponentLikeNames.add(m.name);
-                            this.componentParamNames.set(m.name, m.params.map((p) => p.name));
-                            this.hasComponents = true;
-                        }
-                    }
-                }
             }
-            catch { }
+            catch {
+                // Silently skip if the file cannot be read or parsed
+            }
         }
     }
+    /** Returns true if a call expression's callee looks like a class constructor.
+     *  In Jalvin, class names always start with an uppercase letter. */
     isConstructorCall(calleeExpr) {
         if (calleeExpr.kind === "NameExpr") {
-            if (this.allComponentLikeNames.has(calleeExpr.name))
+            // Names in componentNames are factory functions (UI primitives, components), not constructors
+            if (this.componentNames.has(calleeExpr.name))
                 return false;
+            // Class names start with uppercase; function names start with lowercase
             return /^[A-Z]/.test(calleeExpr.name);
         }
         if (calleeExpr.kind === "MemberExpr") {
-            if (this.allComponentLikeNames.has(calleeExpr.member))
-                return false;
+            // e.g. UiState.Success(data), Discount.Percentage(0.1)
             return /^[A-Z]/.test(calleeExpr.member);
         }
         return false;
     }
+    // ── Component call → props object ──────────────────────────────────────
+    /** Emit `Column(modifier = ...) { ... }` as `React.createElement(Column, { modifier: ... }, [children])` */
     emitComponentCall(expr) {
-        const callee = this.emitExpr(expr.callee);
-        const tagName = expr.callee.kind === "NameExpr" ? expr.callee.name : expr.callee.member;
+        const tag = expr.callee.name;
         const calleeType = this.typeMap.get(expr.callee);
-        const paramNames = (calleeType?.tag === "func" ? calleeType.paramNames : undefined) ?? (tagName ? this.componentParamNames.get(tagName) : undefined);
+        // Param names from type checker (for same-file components) or resolved from imported files
+        const paramNames = (calleeType?.tag === "func" ? calleeType.paramNames : undefined) ??
+            this.componentParamNames.get(tag);
+        // Build props object from named/positional args
         const props = [];
         for (let i = 0; i < expr.args.length; i++) {
             const arg = expr.args[i];
-            const propName = arg.name ?? paramNames?.[i] ?? (arg.value.kind === "NameExpr" ? arg.value.name : undefined);
+            // Prop name: explicit named arg > known param name > NameExpr variable name (shorthand)
+            const propName = arg.name ??
+                paramNames?.[i] ??
+                (arg.value.kind === "NameExpr" ? arg.value.name : undefined);
             if (!propName)
                 continue;
             const val = this.emitExpr(arg.value);
+            // Use JS shorthand `{ key }` when key and value are the same identifier
             props.push(propName === val ? propName : `${propName}: ${val}`);
         }
         const propsStr = props.length > 0 ? `{ ${props.join(", ")} }` : "{}";
         if (expr.trailingLambda) {
             const children = this.emitLambdaBodyAsDomChildren(expr.trailingLambda);
-            return `${callee}(${propsStr}, [${children}])`;
+            return `React.createElement(${tag}, ${propsStr}, [${children}])`;
         }
-        return `${callee}(${propsStr})`;
+        return `React.createElement(${tag}, ${propsStr})`;
     }
+    /** Collect each expression statement in a trailing-lambda body as DOM children.
+     *  For-loop statements are emitted as spread IIFEs so their dynamic output is preserved. */
     emitLambdaBodyAsDomChildren(lambda) {
         const parts = [];
         for (const stmt of lambda.body) {
             if (stmt.kind === "ExprStmt") {
                 parts.push(this.emitExpr(stmt.expr));
             }
-            else if (stmt.kind === "IfStmt") {
-                const s = stmt;
-                const cond = this.emitExpr(s.condition);
-                const thenExprs = s.then.statements.filter((st) => st.kind === "ExprStmt").map((st) => this.emitExpr(st.expr));
-                const elseExprs = s.else && s.else.kind === "Block" ? s.else.statements.filter((st) => st.kind === "ExprStmt").map((st) => this.emitExpr(st.expr)) : [];
-                const thenStr = thenExprs.length > 0 ? `...(${cond} ? [${thenExprs.join(", ")}] : [])` : "";
-                const elseStr = elseExprs.length > 0 ? `...(!(${cond}) ? [${elseExprs.join(", ")}] : [])` : "";
-                if (thenStr)
-                    parts.push(thenStr);
-                if (elseStr)
-                    parts.push(elseStr);
-            }
             else if (stmt.kind === "ForStmt") {
                 const s = stmt;
                 const iter = this.emitExpr(s.iterable);
-                let bindingStr = typeof s.binding === "string" ? `const ${s.binding}` : s.binding.kind === "TupleDestructure" ? `const [${s.binding.names.map((n) => n ?? "_").join(", ")}]` : `const [${s.binding.key}, ${s.binding.value}]`;
-                const innerExprs = s.body.statements.filter((inner) => inner.kind === "ExprStmt").map((inner) => this.emitExpr(inner.expr));
+                let bindingStr;
+                if (typeof s.binding === "string") {
+                    bindingStr = `const ${s.binding}`;
+                }
+                else if (s.binding.kind === "TupleDestructure") {
+                    const names = s.binding.names.map((n) => n ?? "_").join(", ");
+                    bindingStr = `const [${names}]`;
+                }
+                else {
+                    bindingStr = `const [${s.binding.key}, ${s.binding.value}]`;
+                }
+                const innerExprs = s.body.statements
+                    .filter((inner) => inner.kind === "ExprStmt")
+                    .map((inner) => this.emitExpr(inner.expr));
                 if (innerExprs.length > 0) {
                     const pushes = innerExprs.map((e) => `__c.push(${e});`).join(" ");
                     parts.push(`...(() => { const __c: any[] = []; for (${bindingStr} of ${iter}) { ${pushes} } return __c; })()`);
                 }
             }
+            // Other statement kinds (if, while, etc.) are not renderable as UI children inline
         }
         return parts.join(", ");
     }
     emitLambdaExpr(expr) {
-        const params = expr.params.length === 0 ? "it" : expr.params.map((p) => p.name ?? "_").join(", ");
-        if (expr.body.length === 1 && expr.body[0].kind === "ExprStmt")
-            return `(${params}) => ${this.emitExpr(expr.body[0].expr)}`;
-        return `(${params}) => { ${expr.body.map((s) => this.captureStmt(s)).join(" ")} }`;
+        // If no explicit params, emit `it` as the single implicit parameter
+        // (Convention for single-argument lambdas)
+        const params = expr.params.length === 0
+            ? "it"
+            : expr.params.map((p) => p.name ?? "_").join(", ");
+        const body = expr.body;
+        if (body.length === 1 && body[0].kind === "ExprStmt") {
+            return `(${params}) => ${this.emitExpr(body[0].expr)}`;
+        }
+        return `(${params}) => { ${body.map((s) => this.captureStmt(s)).join(" ")} }`;
     }
     emitIfExpr(expr) {
         const cond = this.emitExpr(expr.condition);
-        const thenStr = expr.then.kind === "Block" ? `(() => { ${this.captureBlockStatements(expr.then.statements)} })()` : this.emitExpr(expr.then);
-        const elseStr = expr.else.kind === "Block" ? `(() => { ${this.captureBlockStatements(expr.else.statements)} })()` : expr.else.kind === "IfExpr" ? this.emitIfExpr(expr.else) : this.emitExpr(expr.else);
+        const thenStr = expr.then.kind === "Block"
+            ? `(() => { ${this.captureBlockStatements(expr.then.statements)} })()`
+            : this.emitExpr(expr.then);
+        const elseExpr = expr.else;
+        const elseStr = elseExpr.kind === "Block"
+            ? `(() => { ${this.captureBlockStatements(elseExpr.statements)} })()`
+            : elseExpr.kind === "IfExpr"
+                ? this.emitIfExpr(elseExpr)
+                : this.emitExpr(elseExpr);
         return `(${cond} ? ${thenStr} : ${elseStr})`;
     }
     emitWhenExpr(expr) {
+        // Compile as an IIFE with if/else chain
         const parts = [];
         const subject = expr.subject ? `const __s = ${this.emitExpr(expr.subject.expr)};` : "";
         const subjectRef = expr.subject ? (expr.subject.binding ?? "__s") : "";
         for (const branch of expr.branches) {
-            const body = branch.body.kind === "Block" ? this.captureBlock(branch.body) : `return ${this.emitExpr(branch.body)};`;
-            if (branch.isElse)
+            if (branch.isElse) {
+                const body = branch.body.kind === "Block"
+                    ? this.captureBlock(branch.body)
+                    : `return ${this.emitExpr(branch.body)};`;
                 parts.push(`{ ${body} }`);
-            else
-                parts.push(`if (${branch.conditions.map((c) => this.emitWhenCondition(c, subjectRef)).join(" || ")}) { ${body} }`);
+            }
+            else {
+                const cond = branch.conditions.map((c) => this.emitWhenCondition(c, subjectRef)).join(" || ");
+                const body = branch.body.kind === "Block"
+                    ? this.captureBlock(branch.body)
+                    : `return ${this.emitExpr(branch.body)};`;
+                parts.push(`if (${cond}) { ${body} }`);
+            }
         }
         return `(() => { ${subject} ${parts.join(" else ")} })()`;
     }
     emitTryCatchExpr(expr) {
         const body = this.captureBlock(expr.body);
-        const catches = expr.catches.map((c) => `catch (${c.name}) { ${this.captureBlock(c.body)} }`).join(" ");
+        const catches = expr.catches.map((c) => {
+            const cb = this.captureBlock(c.body);
+            return `catch (${c.name}) { ${cb} }`;
+        }).join(" ");
         const fin = expr.finally ? `finally { ${this.captureBlock(expr.finally)} }` : "";
         return `(() => { try { ${body} } ${catches} ${fin} })()`;
     }
     emitCollectionLiteral(expr) {
-        if (expr.collectionKind === "map")
-            return `new Map([${expr.elements.map((e) => ("kind" in e && e.kind === "MapEntry") ? `[${this.emitExpr(e.key)}, ${this.emitExpr(e.value)}]` : "null").join(", ")}])`;
-        if (expr.collectionKind === "set")
-            return `new Set([${expr.elements.map((e) => this.emitExpr(e)).join(", ")}])`;
-        return `[${expr.elements.map((e) => this.emitExpr(e)).join(", ")}]`;
+        if (expr.collectionKind === "map") {
+            const entries = expr.elements.map((e) => {
+                if ("kind" in e && e.kind === "MapEntry") {
+                    return `[${this.emitExpr(e.key)}, ${this.emitExpr(e.value)}]`;
+                }
+                return "null";
+            });
+            return `new Map([${entries.join(", ")}])`;
+        }
+        if (expr.collectionKind === "set") {
+            const items = expr.elements.map((e) => this.emitExpr(e));
+            return `new Set([${items.join(", ")}])`;
+        }
+        const items = expr.elements.map((e) => this.emitExpr(e));
+        return `[${items.join(", ")}]`;
     }
     emitObjectExpr(expr) {
         const superType = expr.superTypes[0];
         const ext = superType ? ` extends ${this.emitTypeRef(superType.type)}` : "";
-        return `(new (class${ext} { ${expr.body.members.map((m) => this.captureClassMember(m)).join(" ")} })())`;
-    }
-    captureBlock(block) { return block.statements.map((s) => this.captureStmt(s)).join(" "); }
-    captureBlockStatements(stmts) { return stmts.map((s) => this.captureStmt(s)).join(" "); }
-    captureStmt(stmt) { const saved = this.w; const tmp = new Writer(); this.w = tmp; this.emitStmt(stmt); this.w = saved; return tmp.output.trim(); }
-    captureClassMember(member) { const saved = this.w; const tmp = new Writer(); this.w = tmp; this.emitClassMember(member); this.w = saved; return tmp.output.trim(); }
+        const members = expr.body.members.map((m) => this.captureClassMember(m)).join(" ");
+        return `(new (class${ext} { ${members} })())`;
+    }
+    // ── capture helpers (emit to temp string) ─────────────────────────────────
+    captureBlock(block) {
+        return block.statements.map((s) => this.captureStmt(s)).join(" ");
+    }
+    captureBlockStatements(stmts) {
+        return stmts.map((s) => this.captureStmt(s)).join(" ");
+    }
+    captureStmt(stmt) {
+        const saved = this.w;
+        const tmp = new Writer();
+        this.w = tmp;
+        this.emitStmt(stmt);
+        this.w = saved;
+        return tmp.output.trim();
+    }
+    captureClassMember(member) {
+        const saved = this.w;
+        const tmp = new Writer();
+        this.w = tmp;
+        this.emitClassMember(member);
+        this.w = saved;
+        return tmp.output.trim();
+    }
+    // ── Type reference emission ────────────────────────────────────────────────
     emitTypeRef(ref) {
         switch (ref.kind) {
-            case "SimpleTypeRef": return PRIMITIVE_TYPE_MAP[ref.name.join(".")] ?? ref.name.join(".");
-            case "NullableTypeRef": return `${this.emitTypeRef(ref.base)} | null | undefined`;
-            case "GenericTypeRef": return `${GENERIC_TYPE_MAP[ref.base.name.join(".")] ?? ref.base.name.join(".")}<${ref.args.map((a) => a.star ? "any" : a.type ? this.emitTypeRef(a.type) : "unknown").join(", ")}>`;
-            case "FunctionTypeRef": return `(${ref.params.map((p, i) => `p${i}: ${this.emitTypeRef(p)}`).join(", ")}) => ${this.emitTypeRef(ref.returnType)}`;
-            case "StarProjection": return "any";
-        }
-    }
-    emitTypeParamsStr(params) { return params.length === 0 ? "" : `<${params.map((p) => `${p.name}${p.upperBound ? ` extends ${this.emitTypeRef(p.upperBound)}` : ""}`).join(", ")}>`; }
-    emitParamsStr(params) { return params.map((p) => `${p.vararg ? "..." : ""}${p.name}${this.opts.emitTypes ? `: ${this.emitTypeRef(p.type)}${p.vararg ? "[]" : ""}` : ""}${p.defaultValue ? ` = ${this.emitExpr(p.defaultValue)}` : ""}`).join(", "); }
-    emitSuperTypesStr(superTypes) { return superTypes.length === 0 ? "" : superTypes.map((s, i) => i === 0 ? ` extends ${this.emitTypeRef(s.type)}` : ` implements ${this.emitTypeRef(s.type)}`).join(""); }
-    exportPrefix(mods) { return (mods.visibility === "private" || mods.visibility === "internal") ? "" : "export "; }
-    visibilityPrefix(mods) { switch (mods.visibility) {
-        case "private": return "private ";
-        case "protected": return "protected ";
-        case "internal": return "/* internal */ ";
-        default: return "";
-    } }
-    unaryOpStr(op) { return op === "not" ? "!" : op; }
-    binaryOpStr(op) { switch (op) {
-        case "and": return "&&";
-        case "or": return "||";
-        case "xor": return "^";
-        case "shl": return "<<";
-        case "shr": return ">>";
-        case "ushr": return ">>>";
-        case "===": return "===";
-        case "!==": return "!==";
-        default: return op;
-    } }
+            case "SimpleTypeRef": {
+                const name = ref.name.join(".");
+                return PRIMITIVE_TYPE_MAP[name] ?? name;
+            }
+            case "NullableTypeRef":
+                return `${this.emitTypeRef(ref.base)} | null | undefined`;
+            case "GenericTypeRef": {
+                const base = ref.base.name.join(".");
+                const mapped = GENERIC_TYPE_MAP[base] ?? base;
+                const args = ref.args.map((a) => a.star ? "any" : a.type ? this.emitTypeRef(a.type) : "unknown");
+                return `${mapped}<${args.join(", ")}>`;
+            }
+            case "FunctionTypeRef": {
+                const params = ref.params.map((p, i) => `p${i}: ${this.emitTypeRef(p)}`).join(", ");
+                const ret = this.emitTypeRef(ref.returnType);
+                return `(${params}) => ${ret}`;
+            }
+            case "StarProjection":
+                return "any";
+        }
+    }
+    // ── Utility helpers ────────────────────────────────────────────────────────
+    emitTypeParamsStr(params) {
+        if (params.length === 0)
+            return "";
+        const ps = params.map((p) => {
+            const bound = p.upperBound ? ` extends ${this.emitTypeRef(p.upperBound)}` : "";
+            return `${p.name}${bound}`;
+        });
+        return `<${ps.join(", ")}>`;
+    }
+    emitParamsStr(params) {
+        return params.map((p) => {
+            const spread = p.vararg ? "..." : "";
+            // vararg params are rest params in TS: `...name: T[]`
+            const type = this.opts.emitTypes
+                ? `: ${this.emitTypeRef(p.type)}${p.vararg ? "[]" : ""}`
+                : "";
+            const def = p.defaultValue ? ` = ${this.emitExpr(p.defaultValue)}` : "";
+            return `${spread}${p.name}${type}${def}`;
+        }).join(", ");
+    }
+    emitComponentPropsStr(params) {
+        if (params.length === 0)
+            return "";
+        return params.map((p) => {
+            const type = this.opts.emitTypes ? `: ${this.emitTypeRef(p.type)}` : "";
+            return `${p.name}${type}`;
+        }).join(", ");
+    }
+    emitSuperTypesStr(superTypes) {
+        if (superTypes.length === 0)
+            return "";
+        const parts = [];
+        let first = true;
+        for (const s of superTypes) {
+            // TypeScript does NOT allow constructor arguments in the `extends` clause.
+            // Delegation args are passed via `super(args)` inside the constructor.
+            if (first) {
+                parts.push(` extends ${this.emitTypeRef(s.type)}`);
+                first = false;
+            }
+            else {
+                parts.push(` implements ${this.emitTypeRef(s.type)}`);
+            }
+        }
+        return parts.join("");
+    }
+    exportPrefix(mods) {
+        if (mods.visibility === "private" || mods.visibility === "internal")
+            return "";
+        return "export ";
+    }
+    visibilityPrefix(mods) {
+        switch (mods.visibility) {
+            case "private": return "private ";
+            case "protected": return "protected ";
+            case "internal": return "/* internal */ ";
+            default: return "";
+        }
+    }
+    unaryOpStr(op) {
+        if (op === "not")
+            return "!";
+        return op;
+    }
+    binaryOpStr(op) {
+        switch (op) {
+            case "and": return "&&";
+            case "or": return "||";
+            case "xor": return "^";
+            case "shl": return "<<";
+            case "shr": return ">>";
+            case "ushr": return ">>>";
+            // === / !== are JS reference equality (Jalvin's triple-equals)
+            case "===": return "===";
+            case "!==": return "!==";
+            case "..": return "/* .. */ +"; // handled by range()
+            case "..<": return "/* ..< */ +";
+            default: return op;
+        }
+    }
+    // ── AST name walkers (for wildcard import resolution) ─────────────────────
+    /**
+     * Walk the entire program AST and collect all identifier names that are
+     * REFERENCED (i.e., used) in the code: NameExpr values and the first name
+     * component of SimpleTypeRef / GenericTypeRef nodes.
+     *
+     * Jalvin primitive type names (String, Boolean, …) that map to TS primitives
+     * are excluded from TypeRef collection since they never need an import.
+     */
     gatherReferencedNames(program) {
         const names = new Set();
         const visited = new WeakSet();
         const walk = (val) => {
-            if (!val || typeof val !== "object" || visited.has(val))
+            if (!val || typeof val !== "object")
                 return;
-            visited.add(val);
             if (Array.isArray(val)) {
-                val.forEach(walk);
+                for (const item of val)
+                    walk(item);
                 return;
             }
             const obj = val;
-            if (obj.kind === "NameExpr") {
-                if (typeof obj.name === "string")
-                    names.add(obj.name);
+            if (visited.has(obj))
                 return;
-            }
-            if (obj.kind === "SimpleTypeRef") {
-                if (obj.name?.[0] && !(obj.name[0] in PRIMITIVE_TYPE_MAP))
-                    names.add(obj.name[0]);
+            visited.add(obj);
+            const kind = obj["kind"];
+            if (kind === "NameExpr") {
+                const name = obj["name"];
+                if (typeof name === "string")
+                    names.add(name);
+                return; // leaf node
+            }
+            if (kind === "SimpleTypeRef") {
+                const nameArr = obj["name"];
+                if (Array.isArray(nameArr) && nameArr.length > 0) {
+                    const first = nameArr[0];
+                    // Skip Jalvin primitive type names — they're erased to TS primitives.
+                    if (!(first in PRIMITIVE_TYPE_MAP))
+                        names.add(first);
+                }
                 return;
             }
-            if (obj.kind === "GenericTypeRef") {
-                if (obj.base?.name?.[0] && !(obj.base.name[0] in PRIMITIVE_TYPE_MAP))
-                    names.add(obj.base.name[0]);
+            if (kind === "GenericTypeRef") {
+                const base = obj["base"];
+                const nameArr = base?.["name"];
+                if (Array.isArray(nameArr) && nameArr.length > 0) {
+                    const first = nameArr[0];
+                    if (!(first in PRIMITIVE_TYPE_MAP))
+                        names.add(first);
+                }
+                // Fall through to recurse into type arguments
+            }
+            for (const propVal of Object.values(obj)) {
+                walk(propVal);
             }
-            Object.values(obj).forEach(walk);
         };
-        program.declarations.forEach(walk);
+        for (const decl of program.declarations)
+            walk(decl);
         return names;
     }
+    /**
+     * Walk the entire program AST and collect all names that are LOCALLY DEFINED:
+     * top-level declaration names, non-star import aliases, function/lambda
+     * parameters, local val/var bindings, for-loop variables, catch-clause names,
+     * when-subject bindings, and type parameter names.
+     */
     gatherAllLocalBindings(program) {
         const names = new Set();
         const visited = new WeakSet();
-        program.declarations.forEach((d) => { if (d.name)
-            names.add(d.name); });
-        program.imports.forEach((i) => { if (!i.star)
-            names.add(i.alias ?? i.path[i.path.length - 1]); });
+        // Top-level declaration names
+        for (const decl of program.declarations) {
+            const d = decl;
+            if (typeof d.name === "string" && d.name)
+                names.add(d.name);
+        }
+        // Non-star import aliases
+        for (const imp of program.imports) {
+            if (!imp.star) {
+                const name = imp.alias ?? imp.path[imp.path.length - 1];
+                if (name)
+                    names.add(name);
+            }
+        }
         const walk = (val) => {
-            if (!val || typeof val !== "object" || visited.has(val))
+            if (!val || typeof val !== "object")
                 return;
-            visited.add(val);
             if (Array.isArray(val)) {
-                val.forEach(walk);
+                for (const item of val)
+                    walk(item);
                 return;
             }
             const obj = val;
-            if (["PropertyDecl", "DestructuringDecl", "FunDecl", "ExtensionFunDecl", "ComponentDecl", "ClassDecl", "DataClassDecl", "SealedClassDecl", "EnumClassDecl", "InterfaceDecl", "ObjectDecl", "TypeAliasDecl", "LambdaExpr"].includes(obj.kind) && obj.name)
-                names.add(obj.name);
-            if (obj.typeParams)
-                obj.typeParams.forEach((tp) => names.add(tp.name));
-            if (obj.params)
-                obj.params.forEach((p) => names.add(p.name));
-            if (obj.kind === "ForStmt" && typeof obj.binding === "string")
-                names.add(obj.binding);
-            if (obj.kind === "TryCatchStmt" && obj.catches)
-                obj.catches.forEach((c) => names.add(c.name));
-            Object.values(obj).forEach(walk);
+            if (visited.has(obj))
+                return;
+            visited.add(obj);
+            const kind = obj["kind"];
+            // Collect bound names at their declaration sites
+            if (kind === "PropertyDecl" || kind === "DestructuringDecl") {
+                if (typeof obj["name"] === "string")
+                    names.add(obj["name"]);
+                const nms = obj["names"];
+                if (Array.isArray(nms)) {
+                    for (const n of nms) {
+                        if (typeof n === "string")
+                            names.add(n);
+                    }
+                }
+            }
+            if (kind === "FunDecl" || kind === "ExtensionFunDecl" ||
+                kind === "ComponentDecl" || kind === "ClassDecl" ||
+                kind === "DataClassDecl" || kind === "SealedClassDecl" ||
+                kind === "EnumClassDecl" || kind === "InterfaceDecl" ||
+                kind === "ObjectDecl" || kind === "TypeAliasDecl") {
+                if (typeof obj["name"] === "string" && obj["name"])
+                    names.add(obj["name"]);
+                // Type parameters
+                const typeParams = obj["typeParams"];
+                if (Array.isArray(typeParams)) {
+                    for (const tp of typeParams) {
+                        if (tp.name)
+                            names.add(tp.name);
+                    }
+                }
+                // Function/method parameters
+                const params = obj["params"];
+                if (Array.isArray(params)) {
+                    for (const p of params) {
+                        if (p.name)
+                            names.add(p.name);
+                    }
+                }
+            }
+            if (kind === "LambdaExpr") {
+                const params = obj["params"];
+                if (Array.isArray(params)) {
+                    for (const p of params) {
+                        if (p.name)
+                            names.add(p.name);
+                    }
+                }
+            }
+            if (kind === "ForStmt") {
+                const binding = obj["binding"];
+                if (typeof binding === "string") {
+                    names.add(binding);
+                }
+                else if (binding && typeof binding === "object") {
+                    const b = binding;
+                    // TupleDestructure or MapDestructure
+                    if (Array.isArray(b["names"])) {
+                        for (const n of b["names"]) {
+                            if (typeof n === "string")
+                                names.add(n);
+                        }
+                    }
+                    if (typeof b["key"] === "string")
+                        names.add(b["key"]);
+                    if (typeof b["value"] === "string")
+                        names.add(b["value"]);
+                }
+            }
+            if (kind === "TryCatchStmt") {
+                const catches = obj["catches"];
+                if (Array.isArray(catches)) {
+                    for (const c of catches) {
+                        if (c.name)
+                            names.add(c.name);
+                    }
+                }
+            }
+            if (kind === "WhenStmt" || kind === "WhenExpr") {
+                const subject = obj["subject"];
+                if (typeof subject?.["binding"] === "string")
+                    names.add(subject["binding"]);
+            }
+            if (kind === "SecondaryConstructor") {
+                const params = obj["params"];
+                if (Array.isArray(params)) {
+                    for (const p of params) {
+                        if (p.name)
+                            names.add(p.name);
+                    }
+                }
+            }
+            for (const propVal of Object.values(obj)) {
+                walk(propVal);
+            }
         };
-        program.declarations.forEach(walk);
+        for (const decl of program.declarations)
+            walk(decl);
         return names;
     }
 }
 exports.CodeGenerator = CodeGenerator;
-const PRIMITIVE_TYPE_MAP = { Int: "number", Long: "bigint", Float: "number", Double: "number", Boolean: "boolean", String: "string", Char: "string", Byte: "number", Short: "number", Unit: "void", Any: "unknown", Nothing: "never" };
-const GENERIC_TYPE_MAP = { List: "ReadonlyArray", MutableList: "Array", Set: "ReadonlySet", MutableSet: "Set", Map: "ReadonlyMap", MutableMap: "Map", Array: "Array", Deferred: "Promise", StateFlow: "StateFlow", MutableStateFlow: "MutableStateFlow", Flow: "AsyncIterable" };
+// ---------------------------------------------------------------------------
+// Type name mappings (Jalvin → TypeScript)
+// ---------------------------------------------------------------------------
+const PRIMITIVE_TYPE_MAP = {
+    Int: "number",
+    Long: "bigint",
+    Float: "number",
+    Double: "number",
+    Boolean: "boolean",
+    String: "string",
+    Char: "string",
+    Byte: "number",
+    Short: "number",
+    Unit: "void",
+    Any: "unknown",
+    Nothing: "never",
+};
+const GENERIC_TYPE_MAP = {
+    List: "ReadonlyArray",
+    MutableList: "Array",
+    Set: "ReadonlySet",
+    MutableSet: "Set",
+    Map: "ReadonlyMap",
+    MutableMap: "Map",
+    Array: "Array",
+    Pair: "[", // handled specially
+    Triple: "[",
+    Deferred: "Promise",
+    StateFlow: "StateFlow",
+    MutableStateFlow: "MutableStateFlow",
+    Flow: "AsyncIterable",
+};
 const PRIMITIVE_TYPES = new Set(Object.keys(PRIMITIVE_TYPE_MAP));
-const JS_GLOBAL_NAMES = new Set(["Array", "Map", "Set", "Object", "String", "Number", "Boolean", "Promise", "Error", "console", "Math", "Date", "JSON", "setTimeout", "setInterval", "fetch", "document", "window", "undefined", "null", "NaN", "Infinity", "it", "this", "super", "any", "unknown", "never", "void"]);
-function generate(program, opts, operatorOverloads, typeMap) { return new CodeGenerator(opts).generate(program, operatorOverloads, typeMap); }
+// ---------------------------------------------------------------------------
+// Well-known JavaScript / TypeScript global names that must never be emitted
+// as named imports from a wildcard-imported package.
+// ---------------------------------------------------------------------------
+const JS_GLOBAL_NAMES = new Set([
+    // JS built-in constructors and objects
+    "Array", "Map", "Set", "Object", "String", "Number", "Boolean",
+    "Promise", "Error", "TypeError", "RangeError", "SyntaxError", "URIError",
+    "EvalError", "ReferenceError",
+    "console", "Math", "Date", "JSON", "RegExp", "Symbol", "BigInt",
+    "Proxy", "Reflect", "globalThis", "Atomics", "SharedArrayBuffer",
+    "ArrayBuffer", "DataView", "Int8Array", "Uint8Array", "Uint8ClampedArray",
+    "Int16Array", "Uint16Array", "Int32Array", "Uint32Array",
+    "Float32Array", "Float64Array", "BigInt64Array", "BigUint64Array",
+    // Global functions
+    "isNaN", "isFinite", "parseInt", "parseFloat", "eval",
+    "encodeURI", "decodeURI", "encodeURIComponent", "decodeURIComponent",
+    // Browser/Node globals
+    "setTimeout", "clearTimeout", "setInterval", "clearInterval",
+    "queueMicrotask", "requestAnimationFrame", "cancelAnimationFrame",
+    "fetch", "URL", "URLSearchParams", "AbortController", "AbortSignal",
+    "EventTarget", "Event", "CustomEvent", "FormData", "Headers",
+    "Request", "Response", "Blob", "File", "FileReader",
+    "Worker", "SharedWorker", "WebSocket",
+    "ReadableStream", "WritableStream", "TransformStream",
+    "document", "window", "navigator", "location", "history", "screen",
+    "performance", "crypto", "indexedDB", "localStorage", "sessionStorage",
+    "confirm", "alert", "prompt",
+    "process", "Buffer", "global", "require", "module", "exports", "__dirname", "__filename",
+    // Special identifiers
+    "undefined", "null", "NaN", "Infinity",
+    "it", "this", "super", "arguments", "new", "class", "function",
+    // TypeScript primitive type names
+    "any", "unknown", "never", "void", "string", "number", "boolean", "bigint",
+    "object", "symbol",
+    // Jalvin type names that map to TS primitives (never need import)
+    "String", "Boolean", "Any", "Nothing", "Unit", "Char", "Byte", "Short",
+    "Float", "Double",
+]);
+// ---------------------------------------------------------------------------
+// Public helper
+// ---------------------------------------------------------------------------
+function generate(program, opts, operatorOverloads, typeMap) {
+    return new CodeGenerator(opts).generate(program, operatorOverloads, typeMap);
+}
 //# sourceMappingURL=codegen.js.map