gofront 1.3.11 → 1.4.0

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/
@@ -277,6 +283,12 @@ example/templ/
 `.templ` syntax at a glance:
 
 ```go
+css cardStyle() {
+    background: #ffffff;
+    border-radius: 8px;
+    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+}
+
 templ TodoItem(t Todo) {
     <li class={ todoItemClass(t) } draggable="true" data-id={ t.id }>
         <input type="checkbox" checked?={ t.done }/>
@@ -288,7 +300,7 @@ templ TodoItem(t Todo) {
 }
 
 templ AppView() {
-    <div class="card">
+    <div class={ cardStyle() }>
         @Header(highCount(), syncMsg, syncCls)
         @TodoList(visibleTodos())
     </div>
@@ -296,6 +308,7 @@ templ AppView() {
 ```
 
 Key syntax features:
+- `css Name() { ... }` — scoped CSS declarations (templ.guide spec); compiles to a deterministic scoped class name (`gfc_<name>_<hash>`) and injects styles automatically into `<head>`
 - `{ expr }` — interpolate any Go expression (strings auto-cast, others use `String()`)
 - `attr={ expr }` — dynamic attribute value (expression)
 - `attr?={ expr }` — boolean attribute (present/absent based on truthiness)
@@ -363,11 +376,26 @@ parity with the other examples (priority mode, validation, localStorage persiste
 sync status, drag-and-drop reordering).
 
 The templ example additionally demonstrates: **`.templ` file compilation**, template
-components with parameters, `{ expr }` interpolation, `attr?={}` conditional boolean
-attributes, `@Component()` calls inside templates, `if / else if / else` chains,
+components with parameters, scoped `css` declarations (`css Name() { ... }`), `{ expr }` interpolation,
+`attr?={}` conditional boolean 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 +403,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 +412,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 +613,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
 
@@ -587,7 +627,7 @@ signatures into GoFront's internal type representation.
 | Unused import detection | ✓ |
 | External `.d.ts` types | ✓ |
 | npm package type resolution | ✓ |
-| `.templ` files in packages | ✓ — mix `.go` and `.templ` files freely; templ components visible across the whole package |
+| `.templ` files in packages | ✓ — mix `.go` and `.templ` files freely; templ components and `css` declarations visible across the whole package |
 
 ---
 
@@ -604,7 +644,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 +686,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,400+) 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, scoped `css` declarations with class hashing,
+`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** (~105, 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 (scoped `css` injection,
+`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.4.0",
 	"author": "Luuk van Venrooij",
 	"license": "MIT",
 	"repository": {

package/src/codegen/index.js

@@ -27,6 +27,7 @@ import {
 	HELPER_ERROR,
 	HELPER_ERROR_IS,
 	HELPER_IFACE_BOX,
+	HELPER_INJECT_STYLES,
 	HELPER_LEN,
 	HELPER_PATH_CLEAN,
 	HELPER_S,
@@ -97,6 +98,7 @@ export class CodeGen {
 		this.structNames = new Set();
 		this.structFields = new Map();
 		this.namedWrapperNames = new Set();
+		this.collectedCss = [];
 		this.jsImports = jsImports;
 		this.bundledPackages = bundledPackages;
 		this.namedReturnVars = null; // names of current function's named return vars
@@ -191,6 +193,10 @@ export class CodeGen {
 	}
 
 	_callInitAndMain(initNames, program, isTest = false) {
+		if (this.collectedCss.length > 0) {
+			const uniqueCss = [...new Set(this.collectedCss)];
+			this.line(`__injectStyles(${JSON.stringify(uniqueCss.join("\n\n"))});`);
+		}
 		for (const name of initNames) this.line(`${name}();`);
 		if (
 			!isTest &&
@@ -201,6 +207,14 @@ export class CodeGen {
 
 	generate(program, options = {}) {
 		const isTest = options.isTest ?? false;
+		// Ensure _pkgName is set on all decls (generateAll sets it for
+		// multi-file; for single-file compiles we derive it from the AST).
+		const pkgName = program.pkg?.name;
+		if (pkgName) {
+			for (const d of program.decls) {
+				if (!d._pkgName) d._pkgName = pkgName;
+			}
+		}
 		this._renameReservedIdents(program.decls);
 		const methods = this._collectDecls(program);
 		this._emitJsImports();
@@ -208,12 +222,26 @@ 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");
 	}
 
-	// Emits FuncDecl and TemplDecl nodes; returns renamed init function names.
+	// Emits FuncDecl, TemplDecl, and CssDecl nodes; returns renamed init function names.
 	_emitFuncDecls(program) {
 		let initCount = 0;
 		const initNames = [];
@@ -233,6 +261,10 @@ export class CodeGen {
 				this._currentSrcFileIdx = d._srcFileIdx ?? 0;
 				this.genTemplDecl(d);
 				this.blank();
+			} else if (d.kind === "CssDecl") {
+				this._currentSrcFileIdx = d._srcFileIdx ?? 0;
+				this.genCssDecl(d);
+				this.blank();
 			}
 		}
 		return initNames;
@@ -292,6 +324,7 @@ export class CodeGen {
 		MethodDecl: "_renameMethodDeclNode",
 		FuncLit: "_renameSignature",
 		TemplDecl: "_renameSignature",
+		CssDecl: "_renameSignature",
 		VarDecl: "_renameDeclSpecs",
 		ConstDecl: "_renameDeclSpecs",
 		TypeSwitchStmt: "_renameTypeSwitchNode",
@@ -367,6 +400,7 @@ export class CodeGen {
 	_prependHelpers(isTest = false) {
 		const needsTesting = isTest || this._usesTesting;
 		const HELPER_MAP = [
+			[this.collectedCss.length > 0, HELPER_INJECT_STYLES],
 			[this._usesLen, HELPER_LEN],
 			[this._usesAppend, HELPER_APPEND],
 			[this._usesSliceGuard, HELPER_S],
@@ -385,7 +419,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).
@@ -394,12 +434,21 @@ export class CodeGen {
 		for (let i = 0; i < programs.length; i++) {
 			for (const decl of programs[i].decls) {
 				decl._srcFileIdx = i;
+				decl._pkgName = programs[i].pkg?.name;
 			}
 		}
 		const merged = { decls: programs.flatMap((p) => p.decls) };
 		return this.generate(merged, options);
 	}
 
+	getCss() {
+		return [...new Set(this.collectedCss)].join("\n\n");
+	}
+
+	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 +630,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 +656,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 +700,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/runtime.js

@@ -312,3 +312,14 @@ var __GoFront_T = __GoFront_T || class {
   }
 };
 var __testing_T = __GoFront_T;`;
+
+export const HELPER_INJECT_STYLES = `var __injectStyles = __injectStyles || function(css) {
+  if (typeof document === "undefined" || !document || !document.head || !css) return;
+  let s = document.getElementById("gofront-styles");
+  if (!s) {
+    s = document.createElement("style");
+    s.id = "gofront-styles";
+    document.head.appendChild(s);
+  }
+  s.textContent += "\\n" + css;
+};`;

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");
 			});
@@ -26,6 +26,35 @@ export const templGenMethods = {
 		this.line("}");
 	},
 
+	genCssDecl(decl) {
+		if (decl.params && decl.params.length > 0) {
+			throw new Error(
+				`css ${decl.name}: parameterized css declarations are not yet supported`,
+			);
+		}
+		const className = this.getCssClassName(decl);
+		const scopedCss = `.${className} {\n${decl.cssText.trim()}\n}`;
+		this.collectedCss.push(scopedCss);
+
+		this.line(`function ${decl.name}() {`);
+		this.indented(() => {
+			this.line(`return ${JSON.stringify(className)};`);
+		});
+		this.line("}");
+	},
+
+	getCssClassName(decl) {
+		if (decl._className) return decl._className;
+		let h = 2166136261 >>> 0;
+		const str = `${decl._pkgName || ""}_${decl.name}_${decl.cssText}`;
+		for (let i = 0; i < str.length; i++) {
+			h = Math.imul(h ^ str.charCodeAt(i), 16777619) >>> 0;
+		}
+		const hash = (h >>> 0).toString(36);
+		decl._className = `gfc_${decl.name}_${hash}`;
+		return decl._className;
+	},
+
 	// Emit mount statements for an array of TemplNodes into parent variable `p`.
 	_genTemplNodes(nodes, p) {
 		if (!nodes || nodes.length === 0) return;
@@ -85,7 +114,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 +148,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, css: cg.getCss() };
 }
 
 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,33 @@ 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);
 	}
 
+	const mainCss = codegen.getCss();
+	const allCss = [...preambles.map((p) => p.css).filter(Boolean), mainCss]
+		.filter(Boolean)
+		.join("\n\n");
+
 	return {
 		pkgName,
-		js,
+		js: merged.js,
+		css: allCss,
 		programs,
 		exportedSymbols: checker.getExportedSymbols(),
 		exportedTypes: checker.getExportedTypes(),
+		sourceFiles: merged.sourceFiles,
+		sourcesContent: merged.sourcesContent,
+		mappings: merged.mappings,
 	};
 }

package/src/resolver.js

@@ -65,7 +65,9 @@ export function resolveGwDir(importPath, fromFile) {
 	const fromDir = dirname(resolve(fromFile));
 	const dir = resolve(fromDir, importPath);
 	if (!existsSync(dir)) return null;
-	const gwFiles = readdirSync(dir).filter((f) => f.endsWith(".go"));
+	const gwFiles = readdirSync(dir).filter(
+		(f) => f.endsWith(".go") || f.endsWith(".templ"),
+	);
 	return gwFiles.length > 0 ? dir : null;
 }
 

package/src/templ-lexer.js

@@ -35,6 +35,8 @@ export const TT = {
 	TEMPL_CASE: "TEMPL_CASE", // case expr:
 	TEMPL_DEFAULT: "TEMPL_DEFAULT", // default:
 	TEMPL_END: "TEMPL_END", // closing } of if/for/switch/templ body
+	CSS_KW: "css",
+	CSS_BODY: "CSS_BODY",
 };
 
 // Describes a parsed HTML attribute
@@ -123,6 +125,13 @@ export class TemplLexer {
 				continue;
 			}
 
+			// Detect `css` keyword at identifier boundaries
+			if (this._matchKeyword("css")) {
+				this.tokens.push(new Token(TT.CSS_KW, "css", this.line, this.col));
+				this._lexCssDecl();
+				continue;
+			}
+
 			// Everything else: scan to end of top-level declaration using the
 			// raw Go lexer, accumulating tokens until the next `templ` keyword
 			// or EOF.
@@ -135,7 +144,7 @@ export class TemplLexer {
 
 	// ── Go chunk lexing ──────────────────────────────────────────
 
-	// Scan ahead to find the next `templ ` keyword at top level (not inside
+	// Scan ahead to find the next `templ ` or `css ` keyword at top level (not inside
 	// braces/parens/strings/comments). Collect all source text up to that
 	// point, lex it as normal Go, and append the tokens.
 	_lexGoChunk() {
@@ -143,8 +152,12 @@ export class TemplLexer {
 		let depth = 0; // brace depth
 
 		while (!this.eof()) {
-			// Check for `templ` keyword at top level (depth === 0)
-			if (depth === 0 && this._peekKeyword("templ")) break;
+			// Check for `templ` or `css` keyword at top level (depth === 0)
+			if (
+				depth === 0 &&
+				(this._peekKeyword("templ") || this._peekKeyword("css"))
+			)
+				break;
 
 			const ch = this.peek();
 
@@ -222,6 +235,97 @@ export class TemplLexer {
 		this._lexHtmlBody(1);
 	}
 
+	// ── CSS declaration lexing ───────────────────────────────────
+
+	_lexCssDecl() {
+		this.skipWhitespace();
+
+		// Name (identifier)
+		const nameStart = this.pos;
+		while (!this.eof() && /\w/.test(this.peek())) this.advance();
+		const name = this.src.slice(nameStart, this.pos);
+		if (!name) this.err("expected name after 'css'");
+		this.tokens.push(new Token(T.IDENT, name, this.line, this.col));
+
+		this.skipWhitespace();
+
+		// Parameter list (balanced parens)
+		if (this.peek() !== "(") this.err("expected '(' after css name");
+		const paramStart = this.pos;
+		this._skipBalanced("(", ")");
+		const paramSrc = this.src.slice(paramStart, this.pos);
+		for (const t of this._goTokens(paramSrc)) this.tokens.push(t);
+
+		this.skipWhitespace();
+
+		// Opening { of body
+		if (this.peek() !== "{") this.err("expected '{' after css params");
+		this.advance(); // consume {
+		this.tokens.push(new Token(T.LBRACE, "{", this.line, this.col));
+
+		this._lexCssBody();
+	}
+
+	_skipCssString(quote) {
+		this.advance(); // consume opening quote
+		while (!this.eof()) {
+			const ch = this.peek();
+			if (ch === "\\") {
+				this.advance();
+				if (!this.eof()) this.advance();
+				continue;
+			}
+			if (ch === quote) {
+				this.advance();
+				return;
+			}
+			if (ch === "\n") {
+				this.err("unterminated string in css block");
+			}
+			this.advance();
+		}
+		this.err("unterminated string in css block");
+	}
+
+	_lexCssBody() {
+		const start = this.pos;
+		let depth = 1;
+		while (!this.eof()) {
+			const ch = this.peek();
+			// Skip CSS comments /* ... */
+			if (ch === "/" && this.peek(1) === "*") {
+				this.advance();
+				this.advance();
+				this.skipBlockComment();
+				continue;
+			}
+			// Skip strings
+			if (ch === '"' || ch === "'") {
+				this._skipCssString(ch);
+				continue;
+			}
+			if (ch === "{") {
+				depth++;
+				this.advance();
+			} else if (ch === "}") {
+				depth--;
+				if (depth === 0) {
+					const cssText = this.src.slice(start, this.pos);
+					this.tokens.push(
+						new Token(TT.CSS_BODY, cssText, this.line, this.col),
+					);
+					this.advance(); // consume closing }
+					this.tokens.push(new Token(T.RBRACE, "}", this.line, this.col));
+					return;
+				}
+				this.advance();
+			} else {
+				this.advance();
+			}
+		}
+		this.err("unclosed css block");
+	}
+
 	// Lex the HTML body of a templ declaration.
 	// depth: current brace depth (starts at 1 for the opening { of templ)
 	_lexHtmlBody(depth) {
@@ -368,9 +472,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/templ-parser.js

@@ -42,9 +42,38 @@ export class TemplParser extends Parser {
 
 	parseTopDecl() {
 		if (this.check(TT.TEMPL_KW)) return this.parseTemplDecl();
+		if (this.check(TT.CSS_KW)) return this.parseCssDecl();
 		return super.parseTopDecl();
 	}
 
+	// ── CssDecl ───────────────────────────────────────────────────
+
+	parseCssDecl() {
+		const _line = this.peek().line;
+		this.advance(); // consume CSS_KW
+
+		const name = this.expect(T.IDENT).value;
+
+		// Parse parameter list (standard Go params: LPAREN...RPAREN)
+		const params = this.parseParamList();
+
+		// Optional semicolon between ) and {
+		this.semi();
+
+		// Consume opening {
+		this.expect(T.LBRACE);
+
+		// Consume CSS_BODY
+		const bodyToken = this.expect(TT.CSS_BODY);
+		const cssText = bodyToken.value;
+
+		// Consume closing }
+		this.expect(T.RBRACE);
+		this.semi();
+
+		return { kind: "CssDecl", name, params, cssText, _line };
+	}
+
 	// ── TemplDecl ─────────────────────────────────────────────────
 
 	parseTemplDecl() {

package/src/typechecker/index.js

@@ -241,6 +241,7 @@ export class TypeChecker {
 				if (d.kind === "FuncDecl" || d.kind === "MethodDecl")
 					this.collectFunc(d);
 				else if (d.kind === "TemplDecl") this._collectTemplDecl(d);
+				else if (d.kind === "CssDecl") this._collectCssDecl(d);
 			}
 		}
 	}
@@ -267,7 +268,11 @@ export class TypeChecker {
 		for (const p of programs) {
 			this._setCurrentFile(p);
 			for (const d of p.decls) {
-				if (d.kind === "FuncDecl" || d.kind === "MethodDecl") {
+				if (
+					d.kind === "FuncDecl" ||
+					d.kind === "MethodDecl" ||
+					d.kind === "TemplDecl"
+				) {
 					this.checkTopDecl(d, this.globals);
 				}
 			}
@@ -457,11 +462,71 @@ export class TypeChecker {
 				this.checkConstDecl(decl, scope);
 				break;
 			case "TypeDecl":
+			case "CssDecl":
+				break;
 			case "TemplDecl":
-				break; // already collected / no body to check
+				this._markTemplNodesUsed(decl.body);
+				break;
+		}
+	}
+
+	_markTokensUsed(tokens) {
+		if (!tokens) return;
+		for (const t of tokens) {
+			if (t.type === "IDENT" || t.type?.name === "IDENT") {
+				this.globals.lookup(t.value);
+			}
+		}
+	}
+
+	_markTemplNodesUsed(nodes) {
+		if (!nodes) return;
+		for (const n of nodes) {
+			if (n.kind === "TemplElement") {
+				for (const a of n.attrs || []) {
+					if (a.tokens) this._markTokensUsed(a.tokens);
+				}
+				this._markTemplNodesUsed(n.children);
+			} else if (n.kind === "TemplExpr" || n.kind === "TemplComponent") {
+				this._markTokensUsed(n.tokens);
+			} else if (n.kind === "TemplIf") {
+				this._markTokensUsed(n.condTokens);
+				this._markTemplNodesUsed(n.then);
+				this._markTemplNodesUsed(n.else_);
+			} else if (n.kind === "TemplFor") {
+				this._markTokensUsed(n.stmtTokens);
+				this._markTemplNodesUsed(n.body);
+			} else if (n.kind === "TemplSwitch") {
+				this._markTokensUsed(n.exprTokens);
+				for (const c of n.cases || []) {
+					this._markTokensUsed(c.caseTokens);
+					this._markTemplNodesUsed(c.body);
+				}
+			}
 		}
 	}
 
+	_collectCssDecl(decl) {
+		const paramTypes = (decl.params || []).map((p) =>
+			this.resolveTypeNode(p.type, this.globals),
+		);
+		const stringType = this.types.get("string") ?? {
+			kind: "basic",
+			name: "string",
+		};
+		const funcType = {
+			kind: "func",
+			params: paramTypes,
+			returns: [stringType],
+			variadic: false,
+			async: false,
+		};
+		if (this.globals.symbols.has(decl.name) && decl.name !== "init") {
+			this.err(`${decl.name} redeclared in this block`, decl);
+		}
+		this.globals.define(decl.name, funcType);
+	}
+
 	_collectTemplDecl(decl) {
 		const paramTypes = decl.params.map((p) =>
 			this.resolveTypeNode(p.type, this.globals),

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",