gofront 1.3.11 → 1.3.12

package/README.md

@@ -109,8 +109,9 @@ Walks the typed AST and emits clean, readable JavaScript. No intermediate repres
 — the codegen writes directly to an output buffer with indentation tracking.
 
 Runtime helpers (`__len`, `__append`, `__s`, `__sprintf`, `__equal`, `__cmul`, `__cdiv`,
-`__error`, `__errorIs`, `__timeFmt`, `__timeParse`, `__pathClean`) are tree-shaken: only
-emitted when actually used. Optional inline source maps are supported via VLQ-encoded mappings.
+`__error`, `__errorIs`, `__timeFmt`, `__timeParse`, `__pathClean`, `__sortSlice`,
+`__sclone`, `__ifv`, `__ifp`) are tree-shaken: only emitted when actually used. Optional
+inline source maps are supported via VLQ-encoded mappings.
 
 ---
 
@@ -191,10 +192,11 @@ The type checker enforces correctness; JavaScript doesn't need to know.
 
 ---
 
-## Examples — Todo App
+## Examples
 
-There are four example apps — all implement the same todo app to show different aspects
-of GoFront.
+There are five example apps. Four implement the same todo app to show different aspects
+of GoFront; the fifth is a WebGL2 3D showcase demonstrating typed graphics APIs and
+zero-allocation rendering.
 
 ### Simple (vanilla DOM)
 
@@ -224,6 +226,10 @@ signals-based reactive framework. Demonstrates how GoFront integrates with exter
 libraries via `.d.ts` type declarations — the entire reactive API surface is typed via a
 hand-written `browser.d.ts` shim and exercised from GoFront source.
 
+> **Note:** Microtastic is now archived. This example is kept as a reference for
+> `.d.ts` interop with third-party signal libraries. For new projects, use the native
+> `.templ` or `gom` approaches shown below.
+
 ```
 example/reactive/
   src/
@@ -368,6 +374,21 @@ attributes, `@Component()` calls inside templates, `if / else if / else` chains,
 `switch` blocks, `for range` loops, and `@templ.Raw()` for trusted HTML injection —
 all inside template bodies.
 
+### WebGL2 (3D showcase)
+
+A 3D rotating colored cube rendered with WebGL2 shaders. Demonstrates GoFront's static
+WebGL2 typings, `Float32Array` / `Uint16Array` slice mapping, zero-allocation `for range`
+loops, and continuous `requestAnimationFrame` rendering — all with zero per-frame heap
+allocations.
+
+```
+example/webgl/
+  src/
+    main.go       ← shaders, mat4 math, vertex/index buffers, render loop
+  app.js          ← generated output
+  index.html      ← canvas element
+```
+
 ### Build and run
 
 ```sh
@@ -375,6 +396,7 @@ npm run build:simple      # → example/simple/app.js
 npm run build:reactive    # → example/reactive/app.js
 npm run build:gom         # → example/gom/app.js
 npm run build:templ       # → example/templ/app.js
+npm run build:webgl       # → example/webgl/app.js
 # open the respective index.html in a browser
 ```
 
@@ -383,23 +405,33 @@ npm run build:templ       # → example/templ/app.js
 ## CLI
 
 ```
-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 e.g. "15ms")
-gofront <input> --check                    type-check only
-gofront check <dir>/...                    type-check every package under <dir> (Go-style `./...`)
-gofront test <dir>/... [--dom]             run tests for every package under <dir>
-gofront <input> --watch                    watch for changes and recompile
-gofront <input> -o out.js --serve          watch + serve with live reload (default port 3000)
-gofront <input> -o out.js --serve --port 8080  use a custom port
-gofront <input> --source-map               append inline source map (single file or directory; multi-file packages emit per-file mappings)
-gofront <input> --minify                   minify output (built-in minifier)
-gofront <input> --minify --mangle          minify and rename local identifiers
-gofront <file.go> --ast                    dump AST (debug)
-gofront <file.go> --tokens                 dump tokens (debug)
-gofront init [dir]                         scaffold a new project
-gofront --version / -v                     print version
-gofront --help / -h                        print this help
+gofront dev [dir]                            watch + compile + asset sync + live reload (default port 3000)
+gofront dev [dir] --port 8080                use a custom port
+gofront build [dir]                          clean + compile + minify + vendor → production output
+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 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 `./...`)
+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 --copy-assets      compile + copy static assets
+gofront <input> --check                      type-check only (single file / directory)
+gofront <input> --watch                      watch for changes and recompile
+gofront <input> -o out.js --serve            watch + serve with live reload (legacy; prefer gofront dev)
+gofront <input> --source-map                 append inline source map
+gofront <input> --minify                     minify output (built-in minifier)
+gofront <input> --minify --mangle            minify and rename local identifiers
+gofront <file.go> --ast                      dump AST (debug)
+gofront <file.go> --tokens                   dump tokens (debug)
+gofront init [dir]                           scaffold a new project
+gofront --version / -v                       print version
+gofront --help / -h                          print this help
 ```
 ### Project configuration
 
@@ -574,6 +606,7 @@ signatures into GoFront's internal type representation.
 | `os` | `Exit`, `Args`, `Getenv` |
 | `io` | `Writer`, `Reader`, `ReadWriter`, `Closer` interface types; `ReadAll`, `EOF`, `Discard`, `WriteString` |
 | `gom` | Browser-native declarative DOM component library. **Types**: `Node` (interface), `NodeFunc`, `Group`. **Core**: `El(tag, children...)`, `Text(s)`, `Mount(sel, node)`, `MountTo(sel, node)`. **Attributes**: `Attr`, `Class`, `Href`, `Type`, `Src`, `Placeholder`, `DataAttr`, `Style`, `For`, `Name`, `Value`, `Target`, `Rel`, `Alt`, `Title`, `Draggable`, `Role`, `AriaLabel`, `StyleAttr`; boolean: `Disabled`, `Checked`, `Selected`, `Readonly`. **Logic**: `If(cond, node)`, `Map(slice, fn)`. **Elements**: full HTML element set (`Div`, `Span`, `Button`, `Input`, `Ul`, `Li`, `Table`, `Form`, `Img`, `A`, `H1`–`H6`, …) |
+| `testing` | **`testing.T`**: `Error`, `Errorf`, `Fatal`, `Fatalf`, `Fail`, `Failed`, `FailNow`, `Log`, `Logf`, `Skip`, `Skipf`, `Skipped`, `Helper`, `Run`, `Name`. **Package functions**: `Short()`, `Verbose()`. Tests are `func TestXxx(t *testing.T)` in `*_test.go` files, excluded from normal compilation and run via `gofront test`. |
 
 ### Packages & imports
 
@@ -604,7 +637,7 @@ These features are intentional additions for the JavaScript platform:
 | Feature | Purpose |
 |---|---|
 | `async func` / `await` | First-class async syntax for frontend work. |
-| Browser globals (`document`, `console`, etc.) | Predeclared as `any` for practical DOM access. |
+| Browser globals (`document`, `console`, etc.) | Predeclared as `any` for practical DOM access. `WebGL2RenderingContext`, `WebGLRenderingContext`, `GPUDevice`, `GPUAdapter`, `GPUQueue`, `ArrayBuffer`, `DataView`, and TypedArrays have full static typings with method-level checking. |
 | `.d.ts` type imports (`import "js:./types.d.ts"`) | Type-safe interop with JavaScript libraries. |
 | npm package resolution | Import types from `node_modules/` and `@types/` automatically. |
 
@@ -646,28 +679,33 @@ you know exactly what to expect.
 
 See [`docs/roadmap.md`](docs/roadmap.md) for the full roadmap and release history.
 Design documents for planned features are organised by release under `docs/v*/`
-(e.g. [`docs/v0.0.8/`](docs/v0.0.8/), [`docs/v0.0.9/`](docs/v0.0.9/)).
+(e.g. [`docs/v0.0.8/`](docs/v0.0.8/), [`docs/v1.2.0/`](docs/v1.2.0/), [`docs/v1.3.0/`](docs/v1.3.0/)).
 
 ---
 
 ## Tests
 
 ```sh
-npm run test:unit   # unit tests only (~1100 tests, no browser required)
-npm run test:e2e    # E2E tests (Playwright, headless Chromium)
-npm run test:all    # both
+npm run test:unit          # unit tests only (~1400 tests, no browser required)
+npm run test:perf          # zero-allocation benchmark (100k ray-triangle intersections, 0 bytes/frame)
+npm run test:examples      # GoFront-native unit tests across all example apps
+npm run test:examples:dom  # same, with JSDOM for DOM/gom/templ component testing
+npm run test:e2e           # E2E tests (Playwright, headless Chromium)
+npm run test:all           # all of the above
 ```
 
-**Unit tests** (~1118) cover language features, type errors, edge cases, DOM (jsdom),
+**Unit tests** (~1,396) cover language features, type errors, edge cases, DOM (jsdom),
 external `.d.ts`, npm resolver, multi-file compilation, embedded structs, string
 formatting, map iteration order, integer overflow semantics, unused variable detection,
 unused import detection, semantic difference verification, stdlib shim packages, generics,
-and `.templ` file compilation (element rendering, interpolation, boolean attrs, component
-calls, `if/else/else-if` chains, `for range`, `switch/case/default`, `@templ.Raw()` raw
-HTML injection, mixed `.go`+`.templ` packages).
+the `testing` framework itself, and `.templ` file compilation (element rendering,
+interpolation, boolean attrs, component calls, `if/else/else-if` chains, `for range`,
+`switch/case/default`, `@templ.Raw()` raw HTML injection, SVG namespace handling, mixed
+`.go`+`.templ` packages).
 
-**E2E tests** (~104, Playwright) run all four example apps in a real browser and verify
+**E2E tests** (~104, Playwright) run all five example apps in a real browser and verify
 CRUD, filtering, priority mode, persistence (reload), drag-and-drop reordering, and sync
 status. Per-app suites check app-specific behaviour: scoped styles, stats bar, loading
-placeholder, `gom.If` conditional rendering, and templ-specific features (`if/else`
-priority hint, `for` loop rendering, conditional bool attributes).
+placeholder, `gom.If` conditional rendering, templ-specific features (`if/else`
+priority hint, `for` loop rendering, conditional bool attributes), and the WebGL2 cube
+rendering.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "gofront",
-	"version": "1.3.11",
+	"version": "1.3.12",
 	"author": "Luuk van Venrooij",
 	"license": "MIT",
 	"repository": {

package/src/codegen/index.js

@@ -208,8 +208,22 @@ export class CodeGen {
 		this._emitVarConstDecls(program);
 		const initNames = this._emitFuncDecls(program);
 		this._callInitAndMain(initNames, program, isTest);
-		this._prependHelpers(isTest);
-		while (this.out[0] === "") this.out.shift();
+		const prependedLines = this._prependHelpers(isTest);
+		return this._finalizeOutput(prependedLines);
+	}
+
+	_finalizeOutput(prependedLines) {
+		let shiftedLines = 0;
+		while (this.out[0] === "") {
+			this.out.shift();
+			shiftedLines++;
+		}
+		const netShift = prependedLines - shiftedLines;
+		if (netShift !== 0) {
+			for (const m of this._srcMappings) {
+				m.genLine = Math.max(0, m.genLine + netShift);
+			}
+		}
 		return this.out.join("\n");
 	}
 
@@ -385,7 +399,13 @@ export class CodeGen {
 			[needsTesting, HELPER_TESTING],
 		];
 		const helpers = HELPER_MAP.filter(([flag]) => flag).map(([, h]) => h);
-		if (helpers.length > 0) this.out.unshift(...helpers, "");
+		if (helpers.length > 0) {
+			const helperLines = helpers.flatMap((h) => h.split("\n"));
+			helperLines.push("");
+			this.out.unshift(...helperLines);
+			return helperLines.length;
+		}
+		return 0;
 	}
 
 	// Generate a single bundle from multiple programs (same-package multi-file).
@@ -400,6 +420,10 @@ export class CodeGen {
 		return this.generate(merged, options);
 	}
 
+	getMappings() {
+		return this._srcMappings;
+	}
+
 	// Returns a source map JSON string for the last generate() call.
 	// sources: string[] of source filenames (relative to the output file).
 	// sourcesContent: string[] of original file contents (embedded for DevTools breakpoints).
@@ -581,9 +605,11 @@ export class CodeGen {
 	}
 
 	genMethod(decl, recvField = null) {
+		const prevFileIdx = this._currentSrcFileIdx;
+		if (decl._srcFileIdx != null) this._currentSrcFileIdx = decl._srcFileIdx;
 		const params = decl.params.map((p) => p.name).join(", ");
 		const asyncPrefix = decl.async ? "async " : "";
-		this.line(`${asyncPrefix}${decl.name}(${params}) {`);
+		this.line(`${asyncPrefix}${decl.name}(${params}) {`, decl._line ?? null);
 		const prevBoxed = this._boxedVars;
 		this._boxedVars = new Set();
 		this._scanAddressTaken(decl.body);
@@ -605,6 +631,7 @@ export class CodeGen {
 		this._unwrappedRecv = prevUnwrapped;
 		this._boxedVars = prevBoxed;
 		this.line("}");
+		this._currentSrcFileIdx = prevFileIdx;
 	}
 
 	// Value receivers are copies in Go; only materialize the copy when the body mutates it.
@@ -648,10 +675,7 @@ export class CodeGen {
 			.join(", ");
 		const asyncPrefix = decl.async ? "async " : "";
 		const srcLine = decl._line ?? null;
-		this.line(
-			`${asyncPrefix}function ${name}(${params}) {`,
-			srcLine ? srcLine - 1 : null,
-		);
+		this.line(`${asyncPrefix}function ${name}(${params}) {`, srcLine);
 		const prevBoxed = this._boxedVars;
 		this._boxedVars = new Set();
 		this._scanAddressTaken(decl.body);

package/src/codegen/source-map.js

@@ -25,7 +25,10 @@ export function buildSourceMap(sources, mappings, sourcesContent) {
 	let prevSrcLine = 0;
 	let prevSrcFile = 0;
 	const maxGen = mappings.reduce((m, e) => Math.max(m, e.genLine), -1);
-	const byLine = new Map(mappings.map((e) => [e.genLine, e]));
+	const byLine = new Map();
+	for (const m of mappings) {
+		if (!byLine.has(m.genLine)) byLine.set(m.genLine, m);
+	}
 	for (let g = 0; g <= maxGen; g++) {
 		const entry = byLine.get(g);
 		if (entry) {
@@ -47,7 +50,7 @@ export function buildSourceMap(sources, mappings, sourcesContent) {
 	}
 	const map = {
 		version: 3,
-		sources,
+		sources: sources.map((s) => s.replace(/\\/g, "/")),
 		names: [],
 		mappings: lines.join(";"),
 	};

package/src/codegen/statements.js

@@ -96,7 +96,11 @@ export const statementGenMethods = {
 		}
 		// Record source mapping: first output line this statement produced
 		if (srcLine != null && this.out.length > _line0) {
-			this._srcMappings.push({ genLine: _line0, srcLine: srcLine - 1 });
+			this._srcMappings.push({
+				genLine: _line0,
+				srcLine: srcLine - 1,
+				srcFileIdx: this._currentSrcFileIdx,
+			});
 		}
 	},
 

package/src/codegen/stdlib/gom.js

@@ -146,9 +146,9 @@ export const gomMethods = {
 			case "Style":
 				return `((s)=>({Mount(p){const e=document.createElement("style");e.textContent=s;p.appendChild(e);}})) (${args[0]})`;
 			case "Mount":
-				return `((sel,n)=>{const e=document.querySelector(sel);e.innerHTML="";n.Mount(e)})(${args[0]},${args[1]})`;
+				return `((sel,n,r)=>{const e=document.querySelector(sel);e.innerHTML="";n.Mount(e,r)})(${args[0]},${args[1]},${args[2] ?? "undefined"})`;
 			case "MountTo":
-				return `((sel,n)=>{const e=document.querySelector(sel);n.Mount(e)})(${args[0]},${args[1]})`;
+				return `((sel,n,r)=>{const e=document.querySelector(sel);n.Mount(e,r)})(${args[0]},${args[1]},${args[2] ?? "undefined"})`;
 		}
 		return undefined;
 	},

package/src/codegen/templ.js

@@ -17,7 +17,7 @@ export const templGenMethods = {
 			.join(", ");
 		this.line(`function ${decl.name}(${params}) {`);
 		this.indented(() => {
-			this.line(`return {Mount(___p) {`);
+			this.line(`return {Mount(___p, ___refs) {`);
 			this.indented(() => {
 				this._genTemplNodes(decl.body, "___p");
 			});
@@ -85,7 +85,7 @@ export const templGenMethods = {
 			return this.line(`${p}.insertAdjacentHTML("beforeend", ${argJs});`);
 		}
 		return this.line(
-			`(${this._genTemplTokenCallExpr(node.tokens)}).Mount(${p});`,
+			`(${this._genTemplTokenCallExpr(node.tokens)}).Mount(${p}, ___refs);`,
 		);
 	},
 
@@ -119,7 +119,10 @@ export const templGenMethods = {
 			isSvg
 				? `${el}.setAttribute("class", ${js});`
 				: `${el}.className = ${js};`;
-		if (attr.kind === "static") {
+		if (attr.kind === "ref") {
+			// ref="key" — capture element into the refs map at mount time
+			this.line(`if(___refs)___refs[${JSON.stringify(attr.value)}]=${el};`);
+		} else if (attr.kind === "static") {
 			if (name === "class") {
 				this.line(setClass(JSON.stringify(attr.value)));
 			} else {

package/src/compiler.js

@@ -20,6 +20,7 @@
 import { readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { CodeGen } from "./codegen/index.js";
+import { buildSourceMap } from "./codegen/source-map.js";
 import { log } from "./colors.js";
 import { parseDts } from "./dts-parser.js";
 import { Lexer } from "./lexer.js";
@@ -74,6 +75,87 @@ export function gwFilesIn(dir, { includeTests = false } = {}) {
 		.map((f) => join(dir, f));
 }
 
+function normalizeChunk(c) {
+	if (typeof c === "string") {
+		return { js: c, sourceFiles: [], sourcesContent: [], mappings: [] };
+	}
+	return c;
+}
+
+function appendChunkMappings(dest, mappings, localToUnifiedIdx, lineOffset) {
+	if (!mappings) return;
+	for (const m of mappings) {
+		dest.push({
+			genLine: m.genLine + lineOffset,
+			srcLine: m.srcLine,
+			srcFileIdx: localToUnifiedIdx[m.srcFileIdx ?? 0] ?? 0,
+		});
+	}
+}
+
+function mergeCompilationChunks(chunks) {
+	const activeChunks = chunks
+		.filter(Boolean)
+		.map(normalizeChunk)
+		.filter((c) => c.js.length > 0);
+
+	if (activeChunks.length === 0) {
+		return { js: "", sourceFiles: [], sourcesContent: [], mappings: [] };
+	}
+
+	const unifiedSources = [];
+	const unifiedSourcesContent = [];
+	const fileIdxMap = new Map();
+
+	function getOrAddFile(filePath, content) {
+		const key = resolve(filePath);
+		let idx = fileIdxMap.get(key);
+		if (idx === undefined) {
+			idx = unifiedSources.length;
+			fileIdxMap.set(key, idx);
+			unifiedSources.push(key);
+			unifiedSourcesContent.push(content);
+		}
+		return idx;
+	}
+
+	const combinedJsParts = [];
+	const mergedMappings = [];
+	let currentLineOffset = 0;
+
+	for (const chunk of activeChunks) {
+		combinedJsParts.push(chunk.js);
+		const localToUnifiedIdx = (chunk.sourceFiles ?? []).map((file, i) =>
+			getOrAddFile(file, chunk.sourcesContent?.[i] ?? ""),
+		);
+		appendChunkMappings(
+			mergedMappings,
+			chunk.mappings,
+			localToUnifiedIdx,
+			currentLineOffset,
+		);
+		currentLineOffset += chunk.js.split("\n").length;
+	}
+
+	return {
+		js: combinedJsParts.join("\n"),
+		sourceFiles: unifiedSources,
+		sourcesContent: unifiedSourcesContent,
+		mappings: mergedMappings,
+	};
+}
+
+function attachSourceMap(merged, outputDir) {
+	const relativeSources = merged.sourceFiles.map((f) => relative(outputDir, f));
+	const mapJson = buildSourceMap(
+		relativeSources,
+		merged.mappings,
+		merged.sourcesContent,
+	);
+	const b64 = Buffer.from(mapJson).toString("base64");
+	merged.js += `\n//# sourceMappingURL=data:application/json;base64,${b64}`;
+}
+
 // ── Import resolution ─────────────────────────────────────────
 //
 // Shared by compileFiles (multi-file) and the single-file path in index.js.
@@ -87,6 +169,7 @@ export function resolveImports(
 	bundledPackages,
 	preambles,
 	bundledDirs = new Set(),
+	options = {},
 ) {
 	const fromDir = dirname(resolve(fromFile));
 	const allImports = programs.flatMap((p) => p.imports);
@@ -137,8 +220,12 @@ export function resolveImports(
 				const depKey = resolve(depDir);
 				const alreadyBundled = bundledDirs.has(depKey);
 				bundledDirs.add(depKey);
-				const dep = compileDir(depDir, { bundledDirs });
-				if (!alreadyBundled) preambles.push(dep.js);
+				const dep = compileDir(depDir, {
+					...options,
+					bundledDirs,
+					isDependency: true,
+				});
+				if (!alreadyBundled) preambles.push(dep);
 				if (alias === "_") continue;
 				if (alias === ".") {
 					checker.addDefinitions(dep.exportedTypes, dep.exportedSymbols);
@@ -181,6 +268,10 @@ export function compileSingleFile(inputPath, options = {}) {
 	ast._source = source;
 	if (dumpAst) return { ast };
 
+	const outputDir =
+		options.outputDir ??
+		(outputFile ? dirname(resolve(outputFile)) : resolve("."));
+
 	const checker = new TypeChecker();
 	const jsImports = new Map();
 	const bundledPackages = new Set();
@@ -193,6 +284,8 @@ export function compileSingleFile(inputPath, options = {}) {
 		jsImports,
 		bundledPackages,
 		preambles,
+		options.bundledDirs ?? new Set(),
+		{ ...options, outputDir },
 	);
 
 	const errors = checker.check(ast);
@@ -202,18 +295,22 @@ export function compileSingleFile(inputPath, options = {}) {
 	}
 
 	const cg = new CodeGen(checker, jsImports, bundledPackages);
-	let js = cg.generate(ast);
-
-	if (sourceMap) {
-		const outputDir = outputFile ? dirname(resolve(outputFile)) : resolve(".");
-		const srcPath = relative(outputDir, inputPath);
-		const map = cg.getSourceMap(srcPath, [source]);
-		const b64 = Buffer.from(map).toString("base64");
-		js += `\n//# sourceMappingURL=data:application/json;base64,${b64}`;
+	const mainJs = cg.generate(ast);
+
+	const mainChunk = {
+		js: mainJs,
+		sourceFiles: [resolve(inputPath)],
+		sourcesContent: [source],
+		mappings: cg.getMappings(),
+	};
+
+	const merged = mergeCompilationChunks([...preambles, mainChunk]);
+
+	if (sourceMap && !options.isDependency) {
+		attachSourceMap(merged, outputDir);
 	}
 
-	const output = preambles.length > 0 ? `${preambles.join("\n")}\n${js}` : js;
-	return { js: output };
+	return { js: merged.js };
 }
 
 export function compileDir(dir, options = {}) {
@@ -230,6 +327,9 @@ export function compilePackageTests(dir, options = {}) {
 
 export function compileFiles(files, options = {}) {
 	const fromDir = options.fromDir ?? dirname(resolve(files[0]));
+	const outputDir =
+		options.outputDir ??
+		(options.outputFile ? dirname(resolve(options.outputFile)) : fromDir);
 
 	// ── 1. Parse ─────────────────────────────────────────────────
 	const parseErrors = [];
@@ -257,7 +357,7 @@ export function compileFiles(files, options = {}) {
 	const checker = new TypeChecker();
 	const jsImports = new Map(); // npm imports → exported names (for ESM emit)
 	const bundledPackages = new Set(); // package names whose code is inlined
-	const preambles = []; // JS code from compiled sub-packages
+	const preambles = []; // JS code / chunks from compiled sub-packages
 
 	const dummyFromFile = join(fromDir, "_dummy.go");
 	resolveImports(
@@ -268,6 +368,7 @@ export function compileFiles(files, options = {}) {
 		bundledPackages,
 		preambles,
 		options.bundledDirs ?? new Set(),
+		{ ...options, outputDir },
 	);
 
 	// ── 3. Type-check ─────────────────────────────────────────────
@@ -284,22 +385,27 @@ export function compileFiles(files, options = {}) {
 		isTest: options.isTest ?? false,
 	});
 
-	let js = preambles.length > 0 ? `${preambles.join("\n")}\n${mainJs}` : mainJs;
+	const mainChunk = {
+		js: mainJs,
+		sourceFiles: files.map((f) => resolve(f)),
+		sourcesContent: files.map((f) => readFileSync(f, "utf8")),
+		mappings: codegen.getMappings(),
+	};
+
+	const merged = mergeCompilationChunks([...preambles, mainChunk]);
 
-	if (options.sourceMap) {
-		const outputDir = options.outputDir ?? fromDir;
-		const sourceFiles = files.map((f) => relative(outputDir, f));
-		const sourcesContent = files.map((f) => readFileSync(f, "utf8"));
-		const map = codegen.getSourceMap(sourceFiles, sourcesContent);
-		const b64 = Buffer.from(map).toString("base64");
-		js += `\n//# sourceMappingURL=data:application/json;base64,${b64}`;
+	if (options.sourceMap && !options.isDependency) {
+		attachSourceMap(merged, outputDir);
 	}
 
 	return {
 		pkgName,
-		js,
+		js: merged.js,
 		programs,
 		exportedSymbols: checker.getExportedSymbols(),
 		exportedTypes: checker.getExportedTypes(),
+		sourceFiles: merged.sourceFiles,
+		sourcesContent: merged.sourcesContent,
+		mappings: merged.mappings,
 	};
 }

package/src/templ-lexer.js

@@ -368,9 +368,14 @@ export class TemplLexer {
 				const exprTokens = this._readGoExprInBraces();
 				attrs.push({ kind: "expr", name: attrName, tokens: exprTokens });
 			} else if (this.peek() === '"') {
-				// Static string attribute
+				// Static string attribute (or ref capture)
 				const value = this._readQuotedString();
-				attrs.push({ kind: "static", name: attrName, value });
+				if (attrName === "ref") {
+					// ref="fieldName" — element reference capture, not a DOM attribute
+					attrs.push({ kind: "ref", value });
+				} else {
+					attrs.push({ kind: "static", name: attrName, value });
+				}
 			} else {
 				// Unquoted attribute value
 				let val = "";

package/src/typechecker/stdlib/extended.js

@@ -53,8 +53,18 @@ export function setupExtendedGlobals(globals, types) {
 		DataAttr: { kind: "func", params: [STRING, STRING], returns: [GOM_NODE_T] },
 		If: { kind: "func", params: [BOOL, GOM_NODE_T], returns: [GOM_NODE_T] },
 		Map: { kind: "func", params: [ANY, ANY], returns: [GOM_NODE_T] },
-		Mount: { kind: "func", params: [STRING, GOM_NODE_T], returns: [VOID] },
-		MountTo: { kind: "func", params: [STRING, GOM_NODE_T], returns: [VOID] },
+		Mount: {
+			kind: "func",
+			params: [STRING, GOM_NODE_T, ANY],
+			variadic: true,
+			returns: [VOID],
+		},
+		MountTo: {
+			kind: "func",
+			params: [STRING, GOM_NODE_T, ANY],
+			variadic: true,
+			returns: [VOID],
+		},
 	};
 	for (const name of [
 		"Div",