gofront 1.4.0 → 1.5.1

package/README.md

@@ -4,8 +4,8 @@ Go for the backend: simple, type-safe, no nonsense. JavaScript for the frontend:
 everywhere, no setup. The problem is JavaScript's loose typing — and TypeScript never
 quite felt like home either.
 
-So I built GoFront. Go syntax and type safety, compiling to plain ES modules. One language
-front and back, no runtime, no framework, no tsconfig.json.
+So I built GoFront. Go syntax and type safety, compiling to plain ES modules and
+WebAssembly (WasmGC). One language front and back, no runtime, no framework, no tsconfig.json.
 
 With built-in support for declarative DOM rendering via the [`gom`](https://www.gomponents.com) standard library, JSX-like [`.templ`](https://templ.guide/) files, and seamless integration with external JavaScript libraries through TypeScript definition files (`.d.ts`), GoFront is designed specifically as a frontend development target. Build complex, reactive user interfaces entirely in Go.
 
@@ -54,15 +54,16 @@ Requires Node.js 20+.
 
 ## How it works
 
-GoFront is a four-stage compiler written in pure Node.js (no dependencies). Every stage
-operates on the same AST (abstract syntax tree), running in a single pass per stage:
+GoFront is a five-stage compiler written in pure Node.js (no dependencies). Every stage
+operates on the AST (abstract syntax tree):
 
 ```
 source text (.go files)
   → Lexer          tokenize + Go-style semicolon insertion
   → Parser         recursive-descent → AST
   → Type Checker   annotate AST with types + collect errors
-  → Code Gen       AST → JavaScript string
+  → Lowering       ownership/clone elision, escape analysis, capture analysis
+  → Code Gen       AST → JavaScript ES module or WebAssembly GC module (.wasm)
 
 source text (.templ files)
   → TemplLexer     dual-mode: Go mode for declarations, HTML mode inside templ bodies
@@ -103,7 +104,7 @@ Types are plain JS objects (`{ kind: "basic", name: "int" }`, `{ kind: "slice",
 elem: ... }`, etc.). The special `any` type acts as a recovery/escape hatch — any
 operation on it is silently permitted, preventing cascading errors.
 
-### 4. Code Generator (`src/codegen/`)
+### 4. Code Generator (`src/backend/js/`)
 
 Walks the typed AST and emits clean, readable JavaScript. No intermediate representation
 — the codegen writes directly to an output buffer with indentation tracking.
@@ -113,6 +114,66 @@ Runtime helpers (`__len`, `__append`, `__s`, `__sprintf`, `__equal`, `__cmul`, `
 `__sclone`, `__ifv`, `__ifp`) are tree-shaken: only emitted when actually used. Optional
 inline source maps are supported via VLQ-encoded mappings.
 
+### 5. Lowering & WASM backend (`src/lower/`, `src/backend/wasm/`) — experimental
+
+`src/lower/` runs analyses shared by both backends (ownership/clone elision, address-taken
+boxing, range shape, named returns/`defer`, embedded-method stubs, closure captures, pointer
+escape) and stores the results in side tables keyed by AST node.
+
+A package that starts with `//gofront:target wasm` (before the `package` clause) is compiled
+by `src/backend/wasm/` to a WebAssembly GC module instead of JavaScript.
+`//gofront:target both` marks a package that must compile under either backend: it may only
+import other `both` packages, may not use `gom`, may not mutate package-level variables, and
+its JS output uses strict Go numeric semantics (sized-integer wrapping, `float32` rounding,
+integer divide-by-zero panics). Running WASM output requires a WasmGC-capable runtime
+(Node ≥ 22 or a current Chrome/Firefox/Safari).
+
+**Hybrid builds.** Every `wasm`/`both` package a build reaches is linked into a single
+`app.wasm`, written next to `app.js` by `gofront build`, `gofront dev` and `-o`. The JS
+bundle contains a generated facade in place of the wasm packages: exported functions,
+methods, literal constants and structs are callable from JS code as if they were compiled
+to JS. Primitives convert directly, strings and `any` pass through, `both` struct values
+are copied into their JS class, `wasm` structs become opaque handle classes with stable
+identity, slices/arrays are copied element-wise (TypedArrays accepted) and func values are
+wrapped in both directions. Maps, `error`, non-empty interfaces and pointers to non-structs
+are not yet supported at the boundary and are rejected at compile time. The loader fetches
+`app.wasm` relative to the page (override with `globalThis.__GOFRONT_WASM_URL`, or
+pre-supply bytes via `globalThis.__GOFRONT_WASM_BYTES`). `--emit-wat` additionally writes
+a textual `app.wat`.
+
+```
+                     GoFront Source Code
+     ┌───────────────────────┬───────────────────────┐
+     │  //gofront:target js  │ //gofront:target wasm │
+     │  UI, DOM, WebGL, Game │ Collision, Raycasting │
+     └───────────┬───────────┴───────────┬───────────┘
+                 │                       │
+                 │   GoFront Compiler    │
+                 ▼                       ▼
+           ┌───────────┐           ┌───────────┐
+           │  app.js   │ ◄───────► │ app.wasm  │
+           └─────┬─────┘  Boundary └─────┬─────┘
+                 │         Facade        │
+                 ▼                       ▼
+            DOM & Browser          Tight Loops & Math
+          Dynamic & Ergonomic      Predictable & Fast
+```
+
+`gofront test` runs the tests of a `wasm` package inside the linked module (`*testing.T`
+stays a JS object) and runs the tests of a `both` package twice — once per backend,
+reported as `pkg [js]` and `pkg [wasm]` — so both must agree.
+
+**Performance.** Splitting an app into high-level JavaScript orchestration and low-level WebAssembly compute delivers the best of both worlds. On a real-world Möller–Trumbore raycast benchmark (131,072 triangles, 100,000 rays; `npm run bench:raycast`):
+
+| Target | Throughput | Allocation | Engine Stability |
+| :--- | :--- | :--- | :--- |
+| **Pure JS** | `26,720 rays/s` ▰▰▰▰▰▰▰▰▱▱ | `6.20 B / ray` | Subject to periodic V8 young-gen GC pauses |
+| **Hybrid WASM** | `31,293 rays/s` ▰▰▰▰▰▰▰▰▰▰ | `0.86 B / ray` | **Near-zero alloc (7.2× less)**, smooth 60 FPS |
+
+- **+17.1% higher throughput:** Direct WasmGC typed arrays, local-cached scratch globals, and hardware-trapped nil dereferences outperform JIT compiled JS.
+- **86% memory churn reduction:** Dropping allocations from 6.2 B/ray to 0.86 B/ray prevents garbage collection pauses from causing micro-stutter in 60 FPS loops.
+- **Minimal boundary overhead:** The boundary trampoline consumes only ~0.5% of total runtime, ensuring batch computations cross between JS and WASM with virtually zero penalty.
+
 ---
 
 ## Go → JavaScript mapping
@@ -412,13 +473,14 @@ npm run build:webgl       # → example/webgl/app.js
 ## CLI
 
 ```
-gofront dev [dir]                            watch + compile + asset sync + live reload (default port 3000)
+gofront dev [dir]                            watch + compile + asset sync + live reload (hybrid projects emit app.wasm; default port 3000)
 gofront dev [dir] --port 8080                use a custom port
-gofront build [dir]                          clean + compile + minify + vendor → production output
+gofront build [dir]                          clean + compile + minify + vendor → production output (hybrid projects emit app.wasm)
 gofront build [dir] --pwa                    also generate offline service worker (sw.js) + precache manifest
 gofront build [dir] --source-map             include inline source maps in the release bundle
 gofront build [dir] --no-minify              skip minification
 gofront build [dir] --no-mangle              minify but keep original identifiers
+gofront build [dir] --emit-wat               also write app.wat next to app.wasm (hybrid projects)
 gofront prep [dir] [--minify]                run asset copying + vendor bundling only (alias: gofront vendor)
 gofront check <dir>                          type-check a single package
 gofront check <dir>/...                      type-check every package under <dir> (Go-style `./...`)
@@ -426,7 +488,8 @@ gofront test <dir> [--dom]                   run tests for a single package
 gofront test <dir>/... [--dom] [-v] [-run <regex>]  run tests recursively
 gofront <file.go>                            compile single file → stdout
 gofront <dir>                                compile all *.go in directory → stdout
-gofront <input> -o out.js                    write output to file (prints elapsed compile time)
+gofront <input> -o out.js                    write output to file (prints elapsed compile time; hybrid projects also write app.wasm)
+gofront <input> -o out.js --emit-wat         also write app.wat
 gofront <input> -o out.js --copy-assets      compile + copy static assets
 gofront <input> --check                      type-check only (single file / directory)
 gofront <input> --watch                      watch for changes and recompile

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gofront",
-	"version": "1.4.0",
+	"version": "1.5.1",
 	"author": "Luuk van Venrooij",
 	"license": "MIT",
 	"repository": {
@@ -41,6 +41,7 @@
 		"test:all": "npm run test:unit && npm run test:perf && npm run test:examples && npm run test:examples:dom && npm run test:e2e",
 		"test:unit": "node test/unit/run.js",
 		"test:perf": "node test/e2e/perf/zero-alloc.js",
+		"bench:raycast": "node --expose-gc test/e2e/perf/raycast-bench.js",
 		"test:examples": "node src/index.js test example/simple/src && node src/index.js test example/simple/src/utils && node src/index.js test example/reactive/src && node src/index.js test example/reactive/src/utils && node src/index.js test example/gom/src && node src/index.js test example/gom/src/utils && node src/index.js test example/templ/src && node src/index.js test example/templ/src/utils",
 		"test:examples:dom": "node src/index.js test --dom example/simple/src && node src/index.js test --dom example/gom/src && node src/index.js test --dom example/templ/src",
 		"test:coverage": "c8 --include='src/**' --reporter=text --reporter=lcov node test/unit/run.js",

package/src/{codegen → backend/js}/expressions.js

@@ -1,12 +1,78 @@
+import {
+	closureMutates,
+	fnMutates,
+	nodeMutatesVar,
+	nodeWritesVar,
+	rootIdentName,
+} from "../../lower/index.js";
 import {
 	ERROR,
 	isComplex,
 	isTypedArraySlice,
 	typedArrayConstructorForElem,
-} from "../typechecker/types.js";
+} from "../../typechecker/types.js";
 
 /** @typedef {import('./index.js').CodeGen} CodeGen */
 
+export const STRICT_NUMERIC_TYPES = new Set([
+	"float32",
+	"int8",
+	"int16",
+	"int32",
+	"rune",
+	"uint8",
+	"byte",
+	"uint16",
+	"uint32",
+]);
+
+export const STRICT_OPS = new Set([
+	"+",
+	"-",
+	"*",
+	"/",
+	"%",
+	"&",
+	"|",
+	"^",
+	"&^",
+	"<<",
+	">>",
+]);
+
+// Splits a generated JS lvalue at its outermost trailing access:
+// `a.b[i]` → { obj: "a.b", key: "i" }, `a.b.c` → { obj: "a.b", prop: "c" }.
+function splitLastAccess(js) {
+	if (js.endsWith("]")) {
+		let depth = 0;
+		let quote = null;
+		for (let i = js.length - 1; i >= 0; i--) {
+			const ch = js[i];
+			if (quote) {
+				if (ch === quote && js[i - 1] !== "\\") quote = null;
+				continue;
+			}
+			if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+			else if (ch === "]" || ch === ")") depth++;
+			else if (ch === "[" || ch === "(") {
+				depth--;
+				if (depth === 0 && ch === "[" && i > 0)
+					return { obj: js.slice(0, i), key: js.slice(i + 1, -1) };
+			}
+		}
+		return null;
+	}
+	const m = /^(.*[^.])\.([A-Za-z_$][\w$]*)$/s.exec(js);
+	if (!m) return null;
+	// Only split when the dot is at nesting depth 0, e.g. not inside `f(a.b)`.
+	let depth = 0;
+	for (const ch of m[1]) {
+		if (ch === "(" || ch === "[") depth++;
+		else if (ch === ")" || ch === "]") depth--;
+	}
+	return depth === 0 ? { obj: m[1], prop: m[2] } : null;
+}
+
 // Namespace constants: pkg.Field → JS literal
 const NS_CONSTANTS = {
 	math: {
@@ -144,7 +210,7 @@ const TYPEOF_NUMBER_NAMES = new Set([...INT_TYPE_NAMES, "float32", "float64"]);
 const BUILTIN_GEN = {
 	append: (s, e) => s.genAppend(e),
 	len: (s, e) => s._genBuiltinLen(e),
-	cap: (s, e) => `${s.genExpr(e.args[0])}.length`,
+	cap: (s, e) => `(${s.genExpr(e.args[0])}?.length ?? 0)`,
 	make: (s, e) => s.genMake(e),
 	delete: (s, e) => {
 		const [m, k] = e.args.map((a) => s.genExpr(a));
@@ -335,60 +401,21 @@ export const expressionGenMethods = {
 	},
 
 	_rootIdentName(e) {
-		while (e) {
-			if (e.kind === "Ident") return e.name;
-			if (e.kind === "SelectorExpr" || e.kind === "IndexExpr") e = e.expr;
-			else if (e.kind === "UnaryExpr" && e.op === "*") e = e.operand;
-			else return null;
-		}
-		return null;
+		return rootIdentName(e);
 	},
 
 	// True when `node` itself (not its children) writes to variable `name`.
 	_nodeWritesVar(node, name) {
-		const root = (e) => this._rootIdentName(e) === name;
-		switch (node.kind) {
-			case "AssignStmt":
-				return node.lhs.some(root);
-			case "DefineStmt":
-				return node.lhs.some((e) => e._redecl && e.name === name);
-			case "IncDecStmt":
-				return root(node.expr);
-			case "SelectorExpr":
-				return Boolean(
-					node._isMethodValue && node._type?._ptrRecv && root(node.expr),
-				);
-			default:
-				return false;
-		}
+		return nodeWritesVar(node, name);
 	},
 
 	// True when `node` may modify (or take the address of) the value held by variable `name`.
 	_nodeMutatesVar(node, name, addrOnly = false) {
-		if (!node || typeof node !== "object") return false;
-		if (Array.isArray(node))
-			return node.some((n) => this._nodeMutatesVar(n, name, addrOnly));
-		if (
-			node.kind === "UnaryExpr" &&
-			node.op === "&" &&
-			this._rootIdentName(node.operand) === name
-		)
-			return true;
-		if (!addrOnly && this._nodeWritesVar(node, name)) return true;
-		for (const key of Object.keys(node)) {
-			if (key.startsWith("_")) continue;
-			if (this._nodeMutatesVar(node[key], name, addrOnly)) return true;
-		}
-		return false;
+		return nodeMutatesVar(node, name, addrOnly);
 	},
 
 	_fnMutates(name, addrOnly = false) {
-		const ctx = this._fnCtx;
-		if (!ctx) return true;
-		const key = `${addrOnly ? "&" : ""}${name}`;
-		if (!ctx.mut.has(key))
-			ctx.mut.set(key, this._nodeMutatesVar(ctx.body, name, addrOnly));
-		return ctx.mut.get(key);
+		return fnMutates(this._fnCtx?.body, name, addrOnly, this._fnCtx?.mut);
 	},
 
 	_withFnCtx(body, fn) {
@@ -447,21 +474,7 @@ export const expressionGenMethods = {
 	},
 
 	_closureMutates(name) {
-		const ctx = this._fnCtx;
-		const key = `λ${name}`;
-		if (!ctx.mut.has(key)) {
-			const walk = (node) => {
-				if (!node || typeof node !== "object") return false;
-				if (Array.isArray(node)) return node.some(walk);
-				if (node.kind === "FuncLit")
-					return this._nodeMutatesVar(node.body, name);
-				return Object.keys(node).some(
-					(k) => !k.startsWith("_") && walk(node[k]),
-				);
-			};
-			ctx.mut.set(key, walk(ctx.body));
-		}
-		return ctx.mut.get(key);
+		return closureMutates(this._fnCtx?.body, name, this._fnCtx?.mut);
 	},
 
 	_genUnaryExpr(expr) {
@@ -1253,6 +1266,12 @@ export const expressionGenMethods = {
 			return expr.op === "==" ? cmp : `!${cmp}`;
 		}
 
+		if (this.strict && this._needsStrictOp(expr.op, expr._type)) {
+			const l = this.genExpr(expr.left);
+			const r = this.genExpr(expr.right);
+			return this._genStrictBinary(expr.op, l, r, expr._type);
+		}
+
 		const jsOp = this._emittedBinaryOp(expr) ?? "/";
 		const operand = (child, isRight) =>
 			wrapForJsOp(
@@ -1422,4 +1441,142 @@ export const expressionGenMethods = {
 				return inner;
 		}
 	},
+
+	_typeName(t) {
+		if (!t) return null;
+		if (t.kind === "untyped") return t.base;
+		if (t.kind === "named") return this._typeName(t.underlying);
+		if (t.kind === "basic") return t.name;
+		return null;
+	},
+
+	_isStrictAtomicOp(_op, typeName) {
+		return STRICT_NUMERIC_TYPES.has(typeName);
+	},
+
+	_needsStrictOp(op, type) {
+		if (!STRICT_OPS.has(op)) return false;
+		if (this._isStrictAtomicOp(op, this._typeName(type))) return true;
+		return this.isIntType(type) && (op === "/" || op === "%");
+	},
+
+	// Emits `lhs = strict(lhs op rhs)` for any lvalue shape; returns false when not applicable.
+	// Indexed / nested targets are split into object + key temps so sub-expressions run once.
+	_genStrictCompound(lhsNode, op, rhsJs, srcLine = null, lhsJs = null) {
+		const type = lhsNode._type;
+		if (!this._needsStrictOp(op, type)) return false;
+		if (lhsNode.kind === "IndexExpr" && lhsNode.expr?._type?.kind === "map")
+			return false;
+		const l = lhsJs ?? this._genAssignLhsExpr(lhsNode);
+		if (/^[A-Za-z_$][\w$]*(\.[A-Za-z_$][\w$]*)*$/.test(l)) {
+			this.line(
+				`${l} = ${this._genStrictBinary(op, l, rhsJs, type)};`,
+				srcLine,
+			);
+			return true;
+		}
+		const split = splitLastAccess(l);
+		if (!split) return false;
+		this._tmpCounter = (this._tmpCounter ?? 0) + 1;
+		const o = `__o${this._tmpCounter}`;
+		if (split.key != null) {
+			const k = `__k${this._tmpCounter}`;
+			const target = `${o}[${k}]`;
+			this.line(
+				`{ const ${o} = ${split.obj}, ${k} = ${split.key}; ${target} = ${this._genStrictBinary(op, target, rhsJs, type)}; }`,
+				srcLine,
+			);
+		} else {
+			const target = `${o}.${split.prop}`;
+			this.line(
+				`{ const ${o} = ${split.obj}; ${target} = ${this._genStrictBinary(op, target, rhsJs, type)}; }`,
+				srcLine,
+			);
+		}
+		return true;
+	},
+
+	_genStrictBinary(op, l, r, type) {
+		const tName = this._typeName(type);
+		if (tName === "float32") {
+			return `Math.fround(${l} ${op} ${r})`;
+		}
+		if (tName === "int32" || tName === "rune") {
+			if (op === "*") return `Math.imul(${l}, ${r})`;
+			if (op === "/")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : (Math.trunc((${l}) / (${r})) | 0))`;
+			if (op === "%")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : (((${l}) % (${r})) | 0))`;
+			if (op === "<<" || op === ">>") {
+				return `((${r}) >= 32 ? (${op === ">>" ? `((${l}) < 0 ? -1 : 0)` : "0"}) : ((${l}) ${op} (${r}))) | 0`;
+			}
+			if (op === "&^") return `((${l}) & ~(${r})) | 0`;
+			return `((${l} ${op} ${r}) | 0)`;
+		}
+		if (tName === "uint32") {
+			if (op === "/")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : (Math.trunc((${l}) / (${r})) >>> 0))`;
+			if (op === "%")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : (((${l}) % (${r})) >>> 0))`;
+			if (op === "<<" || op === ">>") {
+				const jsOp = op === ">>" ? ">>>" : "<<";
+				return `((${r}) >= 32 ? 0 : ((${l}) ${jsOp} (${r}))) >>> 0`;
+			}
+			if (op === "&^") return `((${l}) & ~(${r})) >>> 0`;
+			return `((${l} ${op} ${r}) >>> 0)`;
+		}
+		if (tName === "int8") {
+			if (op === "/")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : ((Math.trunc((${l}) / (${r})) << 24) >> 24))`;
+			if (op === "%")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : (((((${l}) % (${r})) << 24) >> 24)))`;
+			if (op === "<<" || op === ">>") {
+				return `((${r}) >= 8 ? (${op === ">>" ? `((${l}) < 0 ? -1 : 0)` : "0"}) : (((${l}) ${op} (${r})) << 24 >> 24))`;
+			}
+			if (op === "&^") return `((((${l}) & ~(${r})) << 24) >> 24)`;
+			return `((((${l} ${op} ${r})) << 24) >> 24)`;
+		}
+		if (tName === "int16") {
+			if (op === "/")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : ((Math.trunc((${l}) / (${r})) << 16) >> 16))`;
+			if (op === "%")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : (((((${l}) % (${r})) << 16) >> 16)))`;
+			if (op === "<<" || op === ">>") {
+				return `((${r}) >= 16 ? (${op === ">>" ? `((${l}) < 0 ? -1 : 0)` : "0"}) : (((${l}) ${op} (${r})) << 16 >> 16))`;
+			}
+			if (op === "&^") return `((((${l}) & ~(${r})) << 16) >> 16)`;
+			return `((((${l} ${op} ${r})) << 16) >> 16)`;
+		}
+		if (tName === "uint8" || tName === "byte") {
+			if (op === "/")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : (Math.trunc((${l}) / (${r})) & 0xFF))`;
+			if (op === "%")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : (((${l}) % (${r})) & 0xFF))`;
+			if (op === "<<" || op === ">>") {
+				const jsOp = op === ">>" ? ">>>" : "<<";
+				return `((${r}) >= 8 ? 0 : (((${l}) ${jsOp} (${r})) & 0xFF))`;
+			}
+			if (op === "&^") return `(((${l}) & ~(${r})) & 0xFF)`;
+			return `((${l} ${op} ${r}) & 0xFF)`;
+		}
+		if (tName === "uint16") {
+			if (op === "/")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : (Math.trunc((${l}) / (${r})) & 0xFFFF))`;
+			if (op === "%")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : (((${l}) % (${r})) & 0xFFFF))`;
+			if (op === "<<" || op === ">>") {
+				const jsOp = op === ">>" ? ">>>" : "<<";
+				return `((${r}) >= 16 ? 0 : (((${l}) ${jsOp} (${r})) & 0xFFFF))`;
+			}
+			if (op === "&^") return `(((${l}) & ~(${r})) & 0xFFFF)`;
+			return `((${l} ${op} ${r}) & 0xFFFF)`;
+		}
+		if (this.isIntType(type)) {
+			if (op === "/")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : Math.trunc((${l}) / (${r})))`;
+			if (op === "%")
+				return `((${r}) === 0 ? (() => { throw new Error("runtime error: integer divide by zero"); })() : ((${l}) % (${r})))`;
+		}
+		return `${l} ${op} ${r}`;
+	},
 };

package/src/{codegen → backend/js}/index.js

@@ -1,6 +1,6 @@
 // Code generator: walks the typed AST and emits clean JavaScript.
 //
-// Split into sub-modules under codegen/:
+// Split into sub-modules under backend/js/:
 //   source-map.js    — VLQ encoder and source map builder
 //   statements.js    — genBlock, genStmt, genFor, genSwitch, etc.
 //   expressions.js   — genExpr, genCall, genCompositeLit, helpers
@@ -17,7 +17,12 @@
 //   - make(map[K]V)    → {}
 //   - for range        → for...of with .entries()
 
-import { isComplex, isNumeric } from "../typechecker/types.js";
+import {
+	computeEmbeddedStubs,
+	isReferenceType,
+	scanAddressTaken,
+} from "../../lower/index.js";
+import { isComplex, isNumeric } from "../../typechecker/types.js";
 import { expressionGenMethods } from "./expressions.js";
 import {
 	HELPER_APPEND,
@@ -43,6 +48,8 @@ import { statementGenMethods } from "./statements.js";
 import { stdlibGenMethods } from "./stdlib/index.js";
 import { templGenMethods } from "./templ.js";
 
+export { buildSourceMap };
+
 // Valid Go identifiers that cannot be used as JS bindings; emitted with a `$` suffix.
 const JS_RESERVED = new Set([
 	"arguments",
@@ -91,8 +98,11 @@ export class CodeGen {
 		checker = null,
 		jsImports = new Map(),
 		bundledPackages = new Set(),
+		options = {},
 	) {
 		this.checker = checker;
+		this.target = options.target ?? "js";
+		this.strict = Boolean(options.strict || this.target === "both");
 		this.out = [];
 		this.indent = 0;
 		this.structNames = new Set();
@@ -621,12 +631,13 @@ export class CodeGen {
 	}
 
 	_genEmbeddedMethodStubs(name, methodDecls) {
-		if (!this.checker) return;
-		const resolvedType = this.checker.types.get(name)?.underlying;
-		if (resolvedType?.kind !== "struct" || !resolvedType._embeds) return;
-		const declared = new Set(methodDecls.map((m) => m.name));
-		for (const embed of resolvedType._embeds)
-			this._genSingleEmbedStubs(embed, declared);
+		const stubs = computeEmbeddedStubs(name, methodDecls, this.checker);
+		for (const stub of stubs) {
+			this.blank();
+			this.line(
+				`${stub.methodName}(...__a) { return ${stub.embedName}.prototype.${stub.methodName}.call(this, ...__a); }`,
+			);
+		}
 	}
 
 	genMethod(decl, recvField = null) {
@@ -767,36 +778,11 @@ export class CodeGen {
 
 	// Scan AST node for _addressTaken idents on scalars and populate _boxedVars.
 	_scanAddressTaken(node) {
-		if (!node || typeof node !== "object") return;
-		if (Array.isArray(node)) {
-			for (const child of node) this._scanAddressTaken(child);
-			return;
-		}
-		// &x — the operand ident will have _addressTaken set by typechecker
-		if (node.kind === "Ident" && node._addressTaken) {
-			// Check if the type is a scalar (needs boxing) vs reference type (no boxing)
-			const t = node._type;
-			if (t && !this._isReferenceType(t)) {
-				this._boxedVars.add(node.name);
-			}
-		}
-		// Recurse into FuncLit too — closures may take address of outer vars
-		for (const key of Object.keys(node)) {
-			if (key.startsWith("_")) continue;
-			this._scanAddressTaken(node[key]);
-		}
+		scanAddressTaken(node, this._boxedVars);
 	}
 
 	_isReferenceType(t) {
-		if (!t) return false;
-		const base = t.kind === "named" ? t.underlying : t;
-		return (
-			base?.kind === "struct" ||
-			base?.kind === "slice" ||
-			base?.kind === "map" ||
-			base?.kind === "func" ||
-			base?.kind === "interface"
-		);
+		return isReferenceType(t);
 	}
 
 	// ── Variable / const declarations ────────────────────────────