kopscript 0.5.1 → 0.7.1

package/LLM.md

@@ -421,9 +421,50 @@ exactly the members used, from that package's real module specifier. See Kopular
 raw string HeroHtml from "./hero.html";   // reads the file at compile time, type is always string
 ```
 
+General-purpose only — for a component's actual markup, use `template from` below instead.
+
+## Templates — `template from` (markup files)
+
+```ks
+class Counter : Component {
+  public state<number> Count;
+  constructor() : base() { this.Count = state(0); }
+  public void Increment() { this.Count.Value = this.Count.Value + 1; }
+  template from "./counter.html";   // replaces a hand-written Render() entirely
+}
+```
+
+```html
+<!-- counter.html -->
+<button (click)="Increment()">Count: {{ Count.Value }}</button>
+```
+
+- One `template` per class; a class with both `template` and a hand-written `Render()` is a
+  compile error.
+- Desugars, between parsing and checking, into the exact same `MethodDecl` AST a
+  hand-written `Render()` would produce — no runtime template engine, no virtual DOM.
+  `{{ }}`/binding contents are real KopScript, parsed and type-checked normally.
+- Bindings: `{{ expr }}` (text interpolation, → `InterpolatedStringLiteral`), `(event)="stmt"`
+  (→ `addEventListener`), `[prop]="expr"` (→ plain assignment, checked like any member
+  assignment), static `attr="..."` (`class` aliases to `className`).
+- Structural directives: `*if="expr"` (→ real `if`), `*for="Type varName of expr"` (→ real
+  `for..in`; the element type is explicit — no inference, same stance as Generics).
+  At most one structural directive per element.
+- **Auto-subscribe**: a `state<T>` field declared directly on the class and referenced
+  directly in the template gets `Subscribe((v) => this.Update())` wired automatically — no
+  manual `Subscribe` needed for that field. State reached indirectly (through a method call,
+  or `this.SomeService.Count`) still needs a manual `Subscribe`, unchanged from before.
+- Exactly one top-level element per template (no auto-wrap — hard error). No mixing text and
+  element children under one element. No two-way binding, no pipes, no stacked directives.
+- `ks watch` tracks the referenced `.html` file as well as `.ks` dependencies.
+- Layering note: `template from` is kopscript grammar, but what it desugars *to*
+  (`document.createElement`/`.appendChild`/`.textContent`/`.addEventListener`) assumes
+  Kopular's `dom.ks` DOM surface specifically — a deliberate, documented coupling, not a
+  generic pluggable target.
+
 ## Keywords (reserved, lowercase, exact match)
 
-`using extern raw from as const class interface enum constructor public private
+`using extern raw template from as const class interface enum constructor public private
 protected static virtual override get set return if else while for foreach in break
 continue match this base new void true false null task state async await try catch
 finally throw`
@@ -438,7 +479,9 @@ Locals/params: **camelCase**. This is convention, not enforced by the compiler.
 
 ## Does not exist (don't reach for these)
 
-Generics · `any`/`unknown` annotations ·
+Generics beyond a single unconstrained type parameter (no `Map<K, V>`, no `T : IFoo`
+constraints, no generic functions, no generic inheritance, no variance — see Generics
+above for what *is* supported) · `any`/`unknown` annotations ·
 a `let`/`var` keyword (locals are just `Type name = value;`) · decorators/annotations ·
 reflection · type inference on declarations · ternary expression · union/tuple types ·
 **object-literal syntax** (`{ key: value }` as a value — this doesn't exist *anywhere* in

package/README.md

@@ -50,6 +50,10 @@ LLM's context, as opposed to this README's narrative explanation.
 - **Reactive state without RxJS**: `state<T>` is a small reactive box (`.Value` get/set,
   `.Subscribe((T) => void)`) for holding state and reacting to it changing — no
   Observables, no operators, no manual unsubscribe bookkeeping.
+- **Real markup templates**: `template from "./x.html";` compiles a separate, almost-pure-HTML
+  file — interpolation, event/property bindings, `*if`/`*for` — down to the exact same
+  AST a hand-written `Render()` would produce, with auto-`Subscribe` wiring for state
+  referenced directly in the markup. See [Templates](#templates).
 - **A companion framework, [Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular)**:
   components, constructor-injected services via a composition root (no DI container), and
   real-URL routing (no config DSL) — built entirely on the features above, in a separate
@@ -387,10 +391,11 @@ void Main() {
 ```
 
 Unlike `extern`, there's no real JS export being described here — the compiler fabricates
-the value itself — so there's no `as "jsName"` clause. This exists so a component's static
-markup can live in a real `.html` file instead of a giant `.innerHTML = "..."` string
-literal, the same way Angular's `templateUrl` works — resolved once at build time, not
-fetched at runtime, so `Component.Render()` stays synchronous either way.
+the value itself — so there's no `as "jsName"` clause. This is a general-purpose,
+compile-time-only file embedding primitive — useful for anything that wants a file's
+exact contents as a string constant with no runtime file access. (If what you actually
+want is markup that becomes real DOM construction code, not just a string — see
+[Templates](#templates) below, which is the more specific answer for that case.)
 
 ### async/await, task&lt;T&gt;, and try/catch
 
@@ -488,6 +493,82 @@ of a DI container, and hash-based routing instead of a config DSL — both built
 on ordinary KopScript, no further compiler features required beyond `state<T>` and the
 `extern`/`virtual` support above.
 
+Hand-writing `Render()` like this, statement by statement, is still fully supported — but
+a Kopular component today more commonly expresses it as a **template** instead. See
+[Templates](#templates) below for the markup-based alternative to this same method, and
+for how `Count.Subscribe(...)` above can often be skipped entirely.
+
+### Templates
+
+`template from "<path>";` inside a class body replaces a hand-written `Render()` with a
+real, separate markup file — almost pure HTML, with data bindings and a small set of
+structural directives standing in for the imperative DOM code above:
+
+```ks
+class Counter : Component {
+  public state<number> Count;
+  constructor() : base() { this.Count = state(0); }
+  public void Increment() { this.Count.Value = this.Count.Value + 1; }
+  template from "./counter.html";
+}
+```
+
+```html
+<!-- counter.html -->
+<button (click)="Increment()">Count: {{ Count.Value }}</button>
+```
+
+This compiles to exactly the `Render()` method you'd otherwise write by hand — the
+template compiler is a pass that runs between parsing and type-checking, turning the
+markup into ordinary `MethodDecl`/statement/expression AST nodes and splicing the result
+into the class before checking ever runs. There's no separate runtime template engine, no
+virtual DOM diffing, and no interpreted expression language: `{{ Count.Value }}` and
+`(click)="Increment()"` contain real KopScript, parsed and type-checked exactly like
+anything else in the file, with errors reported at their real position in the `.html`
+file, not the `.ks` file.
+
+A class may have a `template` or a hand-written `Render()`, never both — that's a compile
+error. `ks watch` also tracks the referenced `.html` file, so editing markup alone
+triggers a rebuild.
+
+Supported bindings and directives:
+
+| Syntax                      | Desugars to                                              |
+| --------------------------- | --------------------------------------------------------- |
+| `{{ expr }}` (in text)       | `el.textContent = $"...{expr}...";` (an `InterpolatedStringLiteral`, same as `$"..."`) |
+| `(event)="stmt"`             | `el.addEventListener("event", (Event e) => { stmt });`   |
+| `[prop]="expr"`              | `el.prop = expr;` — a plain assignment, checked like any other |
+| `class="..."` (static)       | `el.className = "...";` (aliased, since `class` is a KopScript keyword) |
+| `*if="expr"`                 | a real `if (expr) { ... }` around the element's creation |
+| `*for="Type var of expr"`    | a real `for (Type var in expr) { ... }` — the element type is explicit, matching KopScript's no-inference stance elsewhere (Generics, Nullable types) |
+
+**Auto-subscribe**: a `state<T>` field declared directly on the component and referenced
+directly in its template (like `Count` above) gets its `Subscribe((v) => this.Update())`
+wired up automatically — no manual `Subscribe` call needed in the constructor. This is a
+syntactic check against the class's own declared fields, not a type-checker query, so it
+only covers *direct* field access; state reached indirectly — through a method call, or
+through `this.SomeService.Count` — still needs a manual `Subscribe`, same as before
+templates existed.
+
+v1 cuts, same discipline as generics and nullable types: exactly one top-level element per
+template (no auto-wrapping — a clear error instead); no mixing text and element children
+under one element (Kopular's DOM surface has no text-node type, only `.textContent`); no
+two-way binding, no pipes, no stacking two structural directives on one element.
+
+**A deliberate layering note**: the `template from` syntax lives in kopscript's own
+grammar (Kopular can't extend a language it doesn't own), but what it desugars *to* —
+`document.createElement`, `.appendChild`, `.textContent`, `.addEventListener` — assumes
+exactly the DOM surface [Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular)'s
+`dom.ks` declares. That's a real coupling from the compiler to one specific consumer,
+accepted deliberately rather than building a generic pluggable desugaring-target system
+for a hypothetical second framework that doesn't exist today. If one ever does, that's the
+point to generalize this.
+
+`raw string <Name> from "./x.html";` (above) still exists as a general-purpose
+compile-time file embedding feature — but for the specific "component markup in its own
+file" use case, `template from` is the real answer; `raw` no longer needs to stand in for
+it.
+
 ### String interpolation
 
 ```ks
@@ -692,8 +773,9 @@ use `node dist/cli.js` directly.
 
 `watch` rebuilds on a save to *any* `.ks` file it reached while compiling — the entry and
 everything it (transitively, non-transitively per-file) `using`s — not just the entry
-file, and re-establishes its watch list after every rebuild since the dependency set
-itself can change (a `using` added or removed). This is the piece that makes a
+file, plus any `.html` file referenced via `template from "...";` in one of those classes,
+and re-establishes its watch list after every rebuild since the dependency set
+itself can change (a `using` added or removed, or a `template` declaration's path). This is the piece that makes a
 browser-facing dev loop bearable: run `ks watch` in one terminal, a static file server in
 another, and refreshing the browser after a save is the only manual step left — there's
 no watch-triggered auto-refresh, since KopScript has no dev-server integration to push
@@ -732,6 +814,6 @@ lives in its own repo, published to npm as `kopular` and consumed like any other
 (no local checkout or `file:` dependency needed). A real app built on both lives in
 [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo) — several
 routed pages, `state<T>`-driven reactivity, constructor-injected services via a
-composition root (no DI container), structural-directive equivalents for `*ngIf`/`*ngFor`/
-`*ngSwitch`, and real-URL (History API) routing — verified against a real DOM via jsdom
-and in an actual browser.
+composition root (no DI container), real-URL (History API) routing, and Angular-style
+markup templates (see [Templates](#templates) above) with `*if`/`*for` structural
+directives — verified against a real DOM via jsdom and in an actual browser.

package/dist/cli.js

@@ -39,6 +39,14 @@ function printHumanDiagnostics(result) {
 // .js file next to each .ks source. With `jsonMode`, nothing but a single
 // JSON object goes to stdout (no "Wrote ..." line, no human diagnostics) —
 // see `printJson` for the shape.
+//
+// A module's watch list is its own path plus any `template from "...";`
+// file(s) it references — those aren't part of `result.order` (they export
+// nothing a `using` could pull in), but editing one needs to trigger a
+// rebuild exactly the way editing a `using`'d file already does.
+function allWatchFiles(result) {
+    return result.order.flatMap((absPath) => [absPath, ...(result.modules.get(absPath)?.extraWatchFiles ?? [])]);
+}
 function build(filePath, jsonMode = false) {
     const result = compileGraph(filePath);
     if (result.entryMissing) {
@@ -55,14 +63,14 @@ function build(filePath, jsonMode = false) {
         else
             printHumanDiagnostics(result);
         process.exitCode = 1;
-        return { outPath: null, watchFiles: result.order };
+        return { outPath: null, watchFiles: allWatchFiles(result) };
     }
     for (const absPath of result.order) {
         writeFileSync(outputPathFor(absPath), result.outputs.get(absPath), "utf-8");
     }
     if (jsonMode)
         printJson(result, result.order.map(outputPathFor));
-    return { outPath: outputPathFor(filePath), watchFiles: result.order };
+    return { outPath: outputPathFor(filePath), watchFiles: allWatchFiles(result) };
 }
 // Type-checks the graph without writing any output — for CI or an editor/
 // agent that wants pass/fail plus diagnostics without touching the

package/dist/lexer.js

@@ -3,6 +3,7 @@ const KEYWORDS = {
     using: TokenKind.Using,
     extern: TokenKind.Extern,
     raw: TokenKind.Raw,
+    template: TokenKind.Template,
     from: TokenKind.From,
     as: TokenKind.As,
     const: TokenKind.Const,

package/dist/modules.js

@@ -5,6 +5,93 @@ import { Parser } from "./parser.js";
 import { Checker, emptyModuleExports } from "./checker.js";
 import { CodeGenerator } from "./codegen.js";
 import { DiagnosticBag } from "./diagnostics.js";
+import { TemplateParser } from "./template_parser.js";
+import { TemplateCompiler } from "./template_compiler.js";
+// Expands every `template from "./x.html";` declaration in `program` into a
+// real, synthetic `Render()` MethodDecl, spliced into that class's own
+// `methods` — before any type-checking happens, so checker.ts/codegen.ts
+// need no knowledge that a template was ever involved (see
+// template_compiler.ts's own header for the full design rationale). Returns
+// the resolved template paths found, for `extraWatchFiles`.
+//
+// Runs entirely on parse-time information: the enclosing ClassDecl's own
+// already-parsed fields (for auto-subscribe field detection) and
+// kopscript's own expression/type parser (for binding expressions) — no
+// dependency on type-checking having run first.
+function expandTemplates(program, absPath, diagnostics, fileOverrides) {
+    const watchFiles = [];
+    for (const stmt of program.statements) {
+        if (stmt.kind !== "ClassDecl" || !stmt.template)
+            continue;
+        const templateRef = stmt.template;
+        if (stmt.methods.some((m) => m.name === "Render" && !m.isStatic)) {
+            diagnostics.error(`Class '${stmt.name}' has both a 'template' declaration and a hand-written 'Render()' method — remove one`, templateRef.line, templateRef.col);
+            continue;
+        }
+        const templatePath = resolve(dirname(absPath), templateRef.path);
+        watchFiles.push(templatePath);
+        const exists = fileOverrides?.has(templatePath) || existsSync(templatePath);
+        if (!exists) {
+            diagnostics.error(`Cannot find template file '${templateRef.path}' (looked for '${displayPath(templatePath)}')`, templateRef.line, templateRef.col);
+            continue;
+        }
+        const templateSource = fileOverrides?.get(templatePath) ?? readFileSync(templatePath, "utf-8");
+        const templateDiagnostics = new DiagnosticBag();
+        const root = new TemplateParser(templateSource, templateDiagnostics).parseDocument();
+        for (const d of templateDiagnostics.diagnostics) {
+            diagnostics.error(`[${templateRef.path}:${d.line}:${d.col}] ${d.message}`, templateRef.line, templateRef.col);
+        }
+        if (!root)
+            continue;
+        const stateFieldNames = new Set(stmt.fields.filter((f) => f.type.kind === "StateType").map((f) => f.name));
+        const memberNames = new Set([...stmt.fields.map((f) => f.name), ...stmt.properties.map((p) => p.name), ...stmt.methods.map((m) => m.name)]);
+        const compileDiagnostics = new DiagnosticBag();
+        const { renderMethod, autoSubscribeFields } = new TemplateCompiler(memberNames, stateFieldNames, compileDiagnostics).compile(root, templateRef);
+        for (const d of compileDiagnostics.diagnostics) {
+            diagnostics.error(`[${templateRef.path}:${d.line}:${d.col}] ${d.message}`, templateRef.line, templateRef.col);
+        }
+        stmt.methods.push(renderMethod);
+        if (autoSubscribeFields.length > 0) {
+            if (!stmt.constructor) {
+                diagnostics.error(`Class '${stmt.name}' has a template referencing state<T> field(s) (${autoSubscribeFields.join(", ")}) but no constructor to subscribe from`, templateRef.line, templateRef.col);
+                continue;
+            }
+            for (const fieldName of autoSubscribeFields) {
+                const field = stmt.fields.find((f) => f.name === fieldName);
+                const valueType = field.type.valueType;
+                const subscribeCall = {
+                    kind: "ExpressionStatement",
+                    expression: {
+                        kind: "CallExpr",
+                        callee: { kind: "MemberExpr", object: { kind: "MemberExpr", object: { kind: "ThisExpr", line: 0, col: 0 }, property: fieldName, line: 0, col: 0 }, property: "Subscribe", line: 0, col: 0 },
+                        args: [
+                            {
+                                kind: "LambdaExpr",
+                                params: [{ name: "__v", type: valueType }],
+                                body: {
+                                    kind: "Block",
+                                    statements: [
+                                        { kind: "ExpressionStatement", expression: { kind: "CallExpr", callee: { kind: "MemberExpr", object: { kind: "ThisExpr", line: 0, col: 0 }, property: "Update", line: 0, col: 0 }, args: [], line: 0, col: 0 }, line: 0, col: 0 },
+                                    ],
+                                    line: 0,
+                                    col: 0,
+                                },
+                                line: 0,
+                                col: 0,
+                            },
+                        ],
+                        line: 0,
+                        col: 0,
+                    },
+                    line: 0,
+                    col: 0,
+                };
+                stmt.constructor.body.statements.push(subscribeCall);
+            }
+        }
+    }
+    return watchFiles;
+}
 function displayPath(absPath) {
     return relative(process.cwd(), absPath);
 }
@@ -15,21 +102,28 @@ function displayPath(absPath) {
 // cyclic dependency is reported on the referencing `using` statement and
 // simply isn't added to that file's dependency list, so the rest of the
 // graph can still be explored and reported on in one pass.
-export function loadModuleGraph(entryAbsPath) {
+// `fileOverrides` (absPath -> source) lets a caller substitute content that
+// hasn't been saved to disk yet — an editor's live buffer, most likely —
+// for any file in the graph, falling back to the real file for everything
+// else. Without this, editor tooling can only ever see what's on disk,
+// which is stale the moment a file has unsaved edits.
+export function loadModuleGraph(entryAbsPath, fileOverrides) {
     const modules = new Map();
     const order = [];
     const stack = [];
-    if (!existsSync(entryAbsPath)) {
+    const exists = (absPath) => fileOverrides?.has(absPath) || existsSync(absPath);
+    if (!exists(entryAbsPath)) {
         return { modules, order, entryMissing: true };
     }
     function visit(absPath) {
         if (modules.has(absPath))
             return;
-        const source = readFileSync(absPath, "utf-8");
+        const source = fileOverrides?.get(absPath) ?? readFileSync(absPath, "utf-8");
         const diagnostics = new DiagnosticBag();
         const tokens = new Lexer(source, diagnostics).tokenize();
         const program = new Parser(tokens, diagnostics).parseProgram();
-        const record = { absPath, source, program, diagnostics, dependencies: [], hoverEntries: [] };
+        const extraWatchFiles = expandTemplates(program, absPath, diagnostics, fileOverrides);
+        const record = { absPath, source, tokens, program, diagnostics, dependencies: [], hoverEntries: [], extraWatchFiles };
         modules.set(absPath, record);
         stack.push(absPath);
         for (const u of program.usings) {
@@ -38,7 +132,7 @@ export function loadModuleGraph(entryAbsPath) {
                 continue;
             }
             const depPath = resolve(dirname(absPath), u.path) + ".ks";
-            if (!existsSync(depPath)) {
+            if (!exists(depPath)) {
                 diagnostics.error(`Cannot find module '${u.path}' (looked for '${displayPath(depPath)}')`, u.line, u.col);
                 continue;
             }
@@ -60,8 +154,8 @@ export function loadModuleGraph(entryAbsPath) {
 // with its direct dependencies' merged exports), and — only if the entire
 // graph is error-free — generates one JS file's contents per module, with
 // real ES `import`/`export` statements wiring them together.
-export function compileGraph(entryAbsPath) {
-    const { modules, order, entryMissing } = loadModuleGraph(entryAbsPath);
+export function compileGraph(entryAbsPath, fileOverrides) {
+    const { modules, order, entryMissing } = loadModuleGraph(entryAbsPath, fileOverrides);
     if (entryMissing) {
         return { success: false, entryMissing: true, modules, order, outputs: new Map() };
     }
@@ -106,7 +200,18 @@ export function compileGraph(entryAbsPath) {
                 merged.enums.set(name, info);
         }
         const checker = new Checker(mod.program, mod.diagnostics, merged, absPath);
-        checker.check();
+        try {
+            checker.check();
+        }
+        catch {
+            // A malformed-enough program (most likely: mid-edit in an editor,
+            // where the rest of the graph is still worth reporting on) can trip
+            // an assertion deep in the checker — whatever hover entries/exports
+            // it recorded before that are still worth keeping, and this module is
+            // conservatively treated as erroring so codegen never runs on a
+            // half-checked result.
+            hasErrors = true;
+        }
         mod.hoverEntries = checker.hoverEntries;
         if (mod.diagnostics.hasErrors)
             hasErrors = true;

package/dist/parser.js

@@ -26,6 +26,49 @@ export class Parser {
         }
         return { kind: "Program", usings, statements };
     }
+    // Parses a single, complete expression from `tokens` and nothing else —
+    // for embedding a real KopScript expression inside something that isn't
+    // itself a .ks file (a template binding's attribute value, `(click)=
+    // "Increment()"` or `{{ Count.Value }}` — see template_compiler.ts).
+    // Errors (including "didn't consume everything") report through the same
+    // `diagnostics` bag this Parser was constructed with, so a caller that
+    // re-maps positions back into the original file gets ordinary Diagnostics
+    // to work with, not a separate error channel. A genuinely malformed
+    // fragment (e.g. an unclosed paren) throws internally the same way any
+    // other parse failure does (see `parseStatement`'s own try/catch) — this
+    // catches that the same way, returning an inert placeholder expression
+    // (a `null` literal) rather than propagating the exception; the real
+    // diagnostic was already recorded before the throw either way.
+    parseStandaloneExpression() {
+        try {
+            const expr = this.parseExpression();
+            if (!this.check(TokenKind.EOF)) {
+                const t = this.peek();
+                this.diagnostics.error(`Unexpected token '${t.lexeme}' after expression`, t.line, t.col);
+            }
+            return expr;
+        }
+        catch {
+            const t = this.peek();
+            return { kind: "NullLiteral", line: t.line, col: t.col };
+        }
+    }
+    // Same idea as `parseStandaloneExpression`, for a type reference — used
+    // for `*for="Item item of Items"`'s explicit element type.
+    parseStandaloneType() {
+        try {
+            const type = this.parseType();
+            if (!this.check(TokenKind.EOF)) {
+                const t = this.peek();
+                this.diagnostics.error(`Unexpected token '${t.lexeme}' after type`, t.line, t.col);
+            }
+            return type;
+        }
+        catch {
+            const t = this.peek();
+            return { kind: "NamedType", name: "void", typeArgs: null, line: t.line, col: t.col };
+        }
+    }
     parseUsing() {
         const start = this.advance(); // 'using'
         const pathTok = this.consume(TokenKind.String, "Expected a module path string after 'using'");
@@ -225,7 +268,19 @@ export class Parser {
         const properties = [];
         const methods = [];
         let ctor = null;
+        let template = null;
         while (!this.check(TokenKind.RBrace) && !this.check(TokenKind.EOF)) {
+            if (this.check(TokenKind.Template)) {
+                const templateStart = this.advance();
+                if (template) {
+                    this.diagnostics.error(`Class '${name}' already has a 'template' declaration`, templateStart.line, templateStart.col);
+                }
+                this.consume(TokenKind.From, "Expected 'from \"<path>\"' after 'template'");
+                const pathTok = this.consume(TokenKind.String, "Expected a file path string after 'from'");
+                this.consume(TokenKind.Semicolon, "Expected ';' after 'template' declaration");
+                template = { path: pathTok.lexeme, line: templateStart.line, col: templateStart.col };
+                continue;
+            }
             let visibility = "public";
             if (this.check(TokenKind.Public) || this.check(TokenKind.Private) || this.check(TokenKind.Protected)) {
                 const v = this.advance().kind;
@@ -357,7 +412,7 @@ export class Parser {
             }
         }
         this.consume(TokenKind.RBrace, "Expected '}' after class body");
-        return { kind: "ClassDecl", isExported, name, typeParam, baseList, fields, properties, constructor: ctor, methods, line: start.line, col: start.col };
+        return { kind: "ClassDecl", isExported, name, typeParam, baseList, fields, properties, constructor: ctor, methods, template, line: start.line, col: start.col };
     }
     parseInterfaceDecl(isExported) {
         const start = this.advance(); // 'interface'

package/dist/template_compiler.js

@@ -0,0 +1,276 @@
+const ELEMENT_TYPE = { kind: "NamedType", name: "Element", typeArgs: null, line: 0, col: 0 };
+const VOID_TYPE = { kind: "NamedType", name: "void", typeArgs: null, line: 0, col: 0 };
+const EVENT_TYPE = { kind: "NamedType", name: "Event", typeArgs: null, line: 0, col: 0 };
+function ident(name, at) {
+    return { kind: "Identifier", name, line: at.line, col: at.col };
+}
+function stringLiteral(value, at) {
+    return { kind: "StringLiteral", value, line: at.line, col: at.col };
+}
+function member(object, property, at) {
+    return { kind: "MemberExpr", object, property, line: at.line, col: at.col };
+}
+function call(callee, args, at) {
+    return { kind: "CallExpr", callee, args, line: at.line, col: at.col };
+}
+function exprStatement(expression, at) {
+    return { kind: "ExpressionStatement", expression, line: at.line, col: at.col };
+}
+function assign(target, value, at) {
+    return exprStatement({ kind: "AssignExpr", target, value, line: at.line, col: at.col }, at);
+}
+function varDecl(name, init, at) {
+    return { kind: "VarDecl", isConst: false, name, nameLine: at.line, nameCol: at.col, type: ELEMENT_TYPE, init, line: at.line, col: at.col };
+}
+function block(statements, at) {
+    return { kind: "Block", statements, line: at.line, col: at.col };
+}
+// Visits every sub-expression reachable from `expr` — used only to find
+// direct references to a state<T> field (see `TemplateCompiler.trackState`)
+// while walking a binding's already-parsed expression; not a general
+// checker replacement.
+function walkExpr(expr, visit) {
+    visit(expr);
+    switch (expr.kind) {
+        case "UnaryExpr":
+            walkExpr(expr.operand, visit);
+            return;
+        case "BinaryExpr":
+        case "LogicalExpr":
+            walkExpr(expr.left, visit);
+            walkExpr(expr.right, visit);
+            return;
+        case "AssignExpr":
+            walkExpr(expr.target, visit);
+            walkExpr(expr.value, visit);
+            return;
+        case "CallExpr":
+            walkExpr(expr.callee, visit);
+            expr.args.forEach((a) => walkExpr(a, visit));
+            return;
+        case "NewExpr":
+            expr.args.forEach((a) => walkExpr(a, visit));
+            return;
+        case "MemberExpr":
+            walkExpr(expr.object, visit);
+            return;
+        case "IndexExpr":
+            walkExpr(expr.object, visit);
+            walkExpr(expr.index, visit);
+            return;
+        case "InterpolatedStringLiteral":
+            for (const part of expr.parts)
+                if (part.kind === "Expr")
+                    walkExpr(part.expression, visit);
+            return;
+        case "ArrayLiteral":
+            expr.elements.forEach((e) => walkExpr(e, visit));
+            return;
+        case "AwaitExpr":
+            walkExpr(expr.operand, visit);
+            return;
+        case "StateExpr":
+            walkExpr(expr.initializer, visit);
+            return;
+        case "MatchExpr":
+            walkExpr(expr.subject, visit);
+            for (const arm of expr.arms)
+                walkExpr(arm.result, visit);
+            return;
+        default:
+            return; // literals, Identifier, ThisExpr, LambdaExpr (deliberately not descending into a lambda body — see module header)
+    }
+}
+// KopScript has no implicit `this` anywhere else in the language — every
+// real example in this codebase writes `this.Foo()`, never a bare `Foo()`
+// meaning the same thing. Template bindings are a deliberate, documented
+// exception: `{{ Count.Value }}`/`(click)="Increment()"` read a bare
+// `Count`/`Increment` the way Angular's own templates do, with `this.`
+// implied. This rebuilds `expr`, rewriting a bare `Identifier` into
+// `this.<name>` exactly when `name` is one of the enclosing class's own
+// directly-declared members (`memberNames`) and isn't shadowed by a
+// closer-in-scope local (`localScope` — a `*for` loop variable, most
+// likely) — anything else (a real global like `print`, a loop variable)
+// resolves exactly as bare KopScript already would.
+//
+// Known limitation: `memberNames` only ever contains the class's *own*
+// declared members, not anything inherited from a base class — this runs
+// at parse time, before the checker has resolved cross-file inheritance,
+// so an inherited member needs an explicit `this.` in a template binding
+// to be found. Most template-relevant state (a component's own counters,
+// handler methods) is declared directly on the component itself in
+// practice; this is a real, accepted v1 gap, not an oversight.
+function qualifyThis(expr, memberNames, localScope) {
+    const q = (e) => qualifyThis(e, memberNames, localScope);
+    switch (expr.kind) {
+        case "Identifier":
+            if (localScope.has(expr.name))
+                return expr;
+            if (memberNames.has(expr.name))
+                return member({ kind: "ThisExpr", line: expr.line, col: expr.col }, expr.name, expr);
+            return expr;
+        case "UnaryExpr":
+            return { ...expr, operand: q(expr.operand) };
+        case "BinaryExpr":
+        case "LogicalExpr":
+            return { ...expr, left: q(expr.left), right: q(expr.right) };
+        case "AssignExpr":
+            return { ...expr, target: q(expr.target), value: q(expr.value) };
+        case "CallExpr":
+            return { ...expr, callee: q(expr.callee), args: expr.args.map(q) };
+        case "NewExpr":
+            return { ...expr, args: expr.args.map(q) };
+        case "MemberExpr":
+            return { ...expr, object: q(expr.object) };
+        case "IndexExpr":
+            return { ...expr, object: q(expr.object), index: q(expr.index) };
+        case "InterpolatedStringLiteral":
+            return { ...expr, parts: expr.parts.map((p) => (p.kind === "Expr" ? { kind: "Expr", expression: q(p.expression) } : p)) };
+        case "ArrayLiteral":
+            return { ...expr, elements: expr.elements.map(q) };
+        case "AwaitExpr":
+            return { ...expr, operand: q(expr.operand) };
+        case "StateExpr":
+            return { ...expr, initializer: q(expr.initializer) };
+        case "MatchExpr":
+            return { ...expr, subject: q(expr.subject), arms: expr.arms.map((arm) => ({ ...arm, result: q(arm.result) })) };
+        default:
+            return expr; // literals, ThisExpr, LambdaExpr — see walkExpr's own comment
+    }
+}
+const NO_LOCALS = new Set();
+export class TemplateCompiler {
+    // `memberNames`: every field/property/method declared directly on the
+    // enclosing class — what a bare identifier in a binding is allowed to
+    // implicitly mean `this.<name>` for (see `qualifyThis`'s own header).
+    // `stateFieldNames`: the subset of those that are `state<T>` — tracked
+    // separately for auto-subscribe, since not every member qualifies.
+    constructor(memberNames, stateFieldNames, diagnostics) {
+        this.memberNames = memberNames;
+        this.stateFieldNames = stateFieldNames;
+        this.diagnostics = diagnostics;
+        this.varCounter = 0;
+        this.autoSubscribeFields = new Set();
+    }
+    freshVar() {
+        return `__el${this.varCounter++}`;
+    }
+    // Qualifies bare member references with `this.`, then records any
+    // directly-referenced `state<T>` field for auto-subscribe — run once per
+    // binding expression, at the point each is pulled out of the template.
+    resolve(expr, localScope) {
+        const qualified = qualifyThis(expr, this.memberNames, localScope);
+        walkExpr(qualified, (e) => {
+            if (e.kind === "MemberExpr" && e.object.kind === "ThisExpr" && this.stateFieldNames.has(e.property)) {
+                this.autoSubscribeFields.add(e.property);
+            }
+        });
+        return qualified;
+    }
+    compile(root, templateDeclAt) {
+        const { varName, statements } = this.buildElement(root, NO_LOCALS);
+        statements.push({ kind: "ReturnStatement", value: ident(varName, templateDeclAt), line: templateDeclAt.line, col: templateDeclAt.col });
+        const renderMethod = {
+            kind: "MethodDecl",
+            visibility: "public",
+            isStatic: false,
+            isAsync: false,
+            isVirtual: false,
+            isOverride: true,
+            name: "Render",
+            nameLine: templateDeclAt.line,
+            nameCol: templateDeclAt.col,
+            params: [],
+            returnType: ELEMENT_TYPE,
+            body: block(statements, templateDeclAt),
+            line: templateDeclAt.line,
+            col: templateDeclAt.col,
+        };
+        return { renderMethod, autoSubscribeFields: [...this.autoSubscribeFields] };
+    }
+    // Builds `node` (ignoring any *if/*for on it — see buildAppendStatements,
+    // which strips those before delegating here) and returns the local
+    // variable name holding the finished Element, plus the statements that
+    // build it. Doesn't append it anywhere; the caller decides that (the
+    // root just returns it, a non-root child appends it to its parent).
+    // `localScope`: names that resolve as plain locals rather than `this.`
+    // members within this subtree — a `*for` loop variable, most likely.
+    buildElement(node, localScope) {
+        const at = node;
+        const varName = this.freshVar();
+        const statements = [];
+        const self = ident(varName, at);
+        statements.push(varDecl(varName, call(member(ident("document", at), "createElement", at), [stringLiteral(node.tag, at)], at), at));
+        for (const attr of node.staticAttrs)
+            statements.push(assign(member(self, attr.name, attr), stringLiteral(attr.value, attr), attr));
+        for (const bind of node.propBindings) {
+            const value = this.resolve(bind.value, localScope);
+            statements.push(assign(member(self, bind.name, bind), value, bind));
+        }
+        for (const bind of node.eventBindings) {
+            const handler = this.resolve(bind.handler, localScope);
+            const handlerParam = { name: "e", type: EVENT_TYPE };
+            const lambda = {
+                kind: "LambdaExpr",
+                params: [{ name: handlerParam.name, type: handlerParam.type }],
+                body: block([exprStatement(handler, bind)], bind),
+                line: bind.line,
+                col: bind.col,
+            };
+            statements.push(exprStatement(call(member(self, "addEventListener", bind), [stringLiteral(bind.name, bind), lambda], bind), bind));
+        }
+        const elementChildren = node.children.filter((c) => c.kind === "element");
+        const textChildren = node.children.filter((c) => c.kind === "text");
+        if (textChildren.length > 0 && elementChildren.length > 0) {
+            this.diagnostics.error(`<${node.tag}> cannot mix text and element children — Kopular's DOM bindings have no text-node API, so text can only be a whole element's content`, node.line, node.col);
+        }
+        else if (textChildren.length > 0) {
+            const parts = textChildren.flatMap((t) => t.parts).map((p) => (p.kind === "Expr" ? { kind: "Expr", expression: this.resolve(p.expression, localScope) } : p));
+            const interpolated = { kind: "InterpolatedStringLiteral", parts, line: at.line, col: at.col };
+            statements.push(assign(member(self, "textContent", at), interpolated, at));
+        }
+        else {
+            for (const child of elementChildren)
+                statements.push(...this.buildAppendStatements(child, varName, localScope));
+        }
+        return { varName, statements };
+    }
+    buildAppendStatements(node, parentVar, localScope) {
+        if (node.forBinding && node.ifCondition) {
+            // Already reported by the parser (only one structural directive per
+            // element) — avoid also emitting a confusing double-wrapped loop/if.
+            node = { ...node, ifCondition: null };
+        }
+        if (node.forBinding) {
+            const forBind = node.forBinding;
+            // The iterable is evaluated in the *enclosing* scope — the loop
+            // variable it's about to introduce isn't in scope for it yet.
+            const iterable = this.resolve(forBind.iterable, localScope);
+            const innerScope = new Set([...localScope, forBind.varName]);
+            const { varName: elVar, statements: buildStatements } = this.buildElement({ ...node, forBinding: null }, innerScope);
+            const body = block([...buildStatements, this.appendChild(parentVar, elVar, node)], node);
+            const forIn = {
+                kind: "ForInStatement",
+                varType: forBind.varType,
+                varName: forBind.varName,
+                iterable,
+                body,
+                line: forBind.line,
+                col: forBind.col,
+            };
+            return [forIn];
+        }
+        if (node.ifCondition) {
+            const condition = this.resolve(node.ifCondition, localScope);
+            const { varName: elVar, statements: buildStatements } = this.buildElement({ ...node, ifCondition: null }, localScope);
+            const thenBranch = block([...buildStatements, this.appendChild(parentVar, elVar, node)], node);
+            const ifStmt = { kind: "IfStatement", condition, thenBranch, elseBranch: null, line: node.line, col: node.col };
+            return [ifStmt];
+        }
+        const { varName: elVar, statements } = this.buildElement(node, localScope);
+        return [...statements, this.appendChild(parentVar, elVar, node)];
+    }
+    appendChild(parentVar, childVar, at) {
+        return exprStatement(call(member(ident(parentVar, at), "appendChild", at), [ident(childVar, at)], at), at);
+    }
+}

package/dist/template_lexer.js

@@ -0,0 +1,162 @@
+export var TemplateTokenKind;
+(function (TemplateTokenKind) {
+    TemplateTokenKind["TagOpen"] = "TagOpen";
+    TemplateTokenKind["TagSelfClose"] = "TagSelfClose";
+    TemplateTokenKind["TagOpenEnd"] = "TagOpenEnd";
+    TemplateTokenKind["TagClose"] = "TagClose";
+    TemplateTokenKind["AttrName"] = "AttrName";
+    TemplateTokenKind["Equals"] = "Equals";
+    TemplateTokenKind["AttrValue"] = "AttrValue";
+    TemplateTokenKind["Text"] = "Text";
+    TemplateTokenKind["EOF"] = "EOF";
+})(TemplateTokenKind || (TemplateTokenKind = {}));
+export class TemplateLexer {
+    constructor(source, diagnostics) {
+        this.source = source;
+        this.diagnostics = diagnostics;
+        this.pos = 0;
+        this.line = 1;
+        this.col = 1;
+        // Set while scanning inside a tag (between '<name' and the closing '>'
+        // or '/>') — text-vs-markup scanning rules differ there (attribute
+        // syntax vs. raw text content).
+        this.inTag = false;
+    }
+    tokenize() {
+        const tokens = [];
+        while (true) {
+            const token = this.inTag ? this.nextTagToken() : this.nextContentToken();
+            tokens.push(token);
+            if (token.kind === TemplateTokenKind.EOF)
+                break;
+        }
+        return tokens;
+    }
+    isAtEnd() {
+        return this.pos >= this.source.length;
+    }
+    peek(offset = 0) {
+        return this.source[this.pos + offset] ?? "";
+    }
+    advance() {
+        const c = this.source[this.pos++];
+        if (c === "\n") {
+            this.line++;
+            this.col = 1;
+        }
+        else {
+            this.col++;
+        }
+        return c;
+    }
+    make(kind, lexeme, line, col) {
+        return { kind, lexeme, line, col };
+    }
+    skipComment() {
+        // Already past '<!--' when called.
+        while (!this.isAtEnd() && !(this.peek() === "-" && this.peek(1) === "-" && this.peek(2) === ">"))
+            this.advance();
+        if (!this.isAtEnd()) {
+            this.advance();
+            this.advance();
+            this.advance(); // '-->'
+        }
+    }
+    // Outside a tag: either a '<...' (comment, closing tag, or opening tag)
+    // or a run of plain text up to the next '<'.
+    nextContentToken() {
+        if (this.isAtEnd())
+            return this.make(TemplateTokenKind.EOF, "", this.line, this.col);
+        if (this.peek() === "<") {
+            if (this.peek(1) === "!" && this.peek(2) === "-" && this.peek(3) === "-") {
+                this.advance();
+                this.advance();
+                this.advance();
+                this.advance(); // '<!--'
+                this.skipComment();
+                return this.nextContentToken(); // comments produce no token at all
+            }
+            if (this.peek(1) === "/") {
+                const line = this.line;
+                const col = this.col;
+                this.advance();
+                this.advance(); // '</'
+                const name = this.readName();
+                this.skipInlineWhitespace();
+                if (this.peek() === ">")
+                    this.advance();
+                return this.make(TemplateTokenKind.TagClose, name, line, col);
+            }
+            const line = this.line;
+            const col = this.col;
+            this.advance(); // '<'
+            const name = this.readName();
+            this.inTag = true;
+            return this.make(TemplateTokenKind.TagOpen, name, line, col);
+        }
+        const line = this.line;
+        const col = this.col;
+        let text = "";
+        while (!this.isAtEnd() && this.peek() !== "<")
+            text += this.advance();
+        return this.make(TemplateTokenKind.Text, text, line, col);
+    }
+    // Inside a tag, after the tag name: attribute names/values, '=', and the
+    // '>' or '/>' that ends it.
+    nextTagToken() {
+        this.skipInlineWhitespace();
+        if (this.isAtEnd())
+            return this.make(TemplateTokenKind.EOF, "", this.line, this.col);
+        const line = this.line;
+        const col = this.col;
+        if (this.peek() === "/" && this.peek(1) === ">") {
+            this.advance();
+            this.advance();
+            this.inTag = false;
+            return this.make(TemplateTokenKind.TagSelfClose, "/>", line, col);
+        }
+        if (this.peek() === ">") {
+            this.advance();
+            this.inTag = false;
+            return this.make(TemplateTokenKind.TagOpenEnd, ">", line, col);
+        }
+        if (this.peek() === "=") {
+            this.advance();
+            return this.make(TemplateTokenKind.Equals, "=", line, col);
+        }
+        if (this.peek() === '"') {
+            this.advance();
+            let value = "";
+            while (!this.isAtEnd() && this.peek() !== '"')
+                value += this.advance();
+            if (this.isAtEnd()) {
+                this.diagnostics.error("Unterminated attribute value", line, col);
+            }
+            else {
+                this.advance(); // closing '"'
+            }
+            return this.make(TemplateTokenKind.AttrValue, value, line, col);
+        }
+        // An attribute name: `(click)`, `[className]`, `*if`, `*for`, or a
+        // plain `id` — every character up to whitespace/'='/'>'/'/'.
+        let name = "";
+        while (!this.isAtEnd() && !/[\s=>/]/.test(this.peek()))
+            name += this.advance();
+        if (name.length === 0) {
+            this.diagnostics.error(`Unexpected character '${this.peek()}' in tag`, line, col);
+            this.advance(); // avoid an infinite loop on a genuinely unexpected character
+            return this.nextTagToken();
+        }
+        return this.make(TemplateTokenKind.AttrName, name, line, col);
+    }
+    skipInlineWhitespace() {
+        while (!this.isAtEnd() && /\s/.test(this.peek()))
+            this.advance();
+    }
+    readName() {
+        let name = "";
+        while (!this.isAtEnd() && /[A-Za-z0-9-]/.test(this.peek()))
+            name += this.advance();
+        return name;
+    }
+}

package/dist/template_parser.js

@@ -0,0 +1,249 @@
+// Builds a template's element/text tree from TemplateLexer's token stream,
+// parsing every binding's value (event/property bindings, *if/*for,
+// {{ }} interpolation) as a real KopScript expression via kopscript's own
+// Lexer/Parser — reusing parseStandaloneExpression/parseStandaloneType
+// (see parser.ts) rather than inventing a second expression language.
+//
+// A fragment parsed out of an attribute value or a {{ }} span starts its
+// own line/col numbering at (1, 1); `remapPosition` translates a position
+// found while parsing one back into real coordinates in the .html file, so
+// a mistake inside a binding ("Cuont.Value") reports at the right place in
+// the template, not "line 1, column 6" every time.
+import { TokenKind } from "./tokens.js";
+import { Lexer } from "./lexer.js";
+import { Parser } from "./parser.js";
+import { DiagnosticBag } from "./diagnostics.js";
+import { TemplateLexer, TemplateTokenKind } from "./template_lexer.js";
+const PROPERTY_ALIASES = { class: "className" };
+function remapPosition(fragmentLine, fragmentCol, localLine, localCol) {
+    if (localLine === 1)
+        return { line: fragmentLine, col: fragmentCol + localCol - 1 };
+    return { line: fragmentLine + localLine - 1, col: localCol };
+}
+export class TemplateParser {
+    constructor(source, diagnostics) {
+        this.diagnostics = diagnostics;
+        this.pos = 0;
+        this.tokens = new TemplateLexer(source, diagnostics).tokenize();
+    }
+    peek() {
+        return this.tokens[this.pos];
+    }
+    advance() {
+        return this.tokens[this.pos++];
+    }
+    check(kind) {
+        return this.peek().kind === kind;
+    }
+    // Parses a fragment of real KopScript source (an attribute value, or the
+    // text inside {{ }}) as a standalone expression, remapping any
+    // diagnostics it produces back into the template file's own coordinates.
+    parseEmbeddedExpression(source, fragmentLine, fragmentCol) {
+        const localDiagnostics = new DiagnosticBag();
+        const tokens = new Lexer(source, localDiagnostics).tokenize();
+        const expr = new Parser(tokens, localDiagnostics).parseStandaloneExpression();
+        for (const d of localDiagnostics.diagnostics) {
+            const { line, col } = remapPosition(fragmentLine, fragmentCol, d.line, d.col);
+            this.diagnostics.error(d.message, line, col);
+        }
+        return expr;
+    }
+    // "Item item of Items" — an explicit element type (matching KopScript's
+    // own no-inference philosophy), a variable name, the contextual "of"
+    // separator (a plain identifier, not a reserved keyword), then the
+    // iterable expression.
+    parseForBinding(source, fragmentLine, fragmentCol) {
+        const localDiagnostics = new DiagnosticBag();
+        const tokens = new Lexer(source, localDiagnostics).tokenize();
+        const ofIndex = tokens.findIndex((t) => t.kind === TokenKind.Identifier && t.lexeme === "of");
+        if (ofIndex < 1 || tokens[ofIndex - 1].kind !== TokenKind.Identifier) {
+            this.diagnostics.error(`Expected '*for="Type varName of iterable"', got '${source}'`, fragmentLine, fragmentCol);
+            return null;
+        }
+        const varNameToken = tokens[ofIndex - 1];
+        const typeTokens = [...tokens.slice(0, ofIndex - 1), tokens[tokens.length - 1]]; // real tokens + the shared EOF
+        const iterableTokens = tokens.slice(ofIndex + 1);
+        const varType = new Parser(typeTokens, localDiagnostics).parseStandaloneType();
+        const iterable = new Parser(iterableTokens, localDiagnostics).parseStandaloneExpression();
+        for (const d of localDiagnostics.diagnostics) {
+            const { line, col } = remapPosition(fragmentLine, fragmentCol, d.line, d.col);
+            this.diagnostics.error(d.message, line, col);
+        }
+        return { varType, varName: varNameToken.lexeme, iterable, line: fragmentLine, col: fragmentCol };
+    }
+    // Splits raw text into alternating literal/`{{ expr }}` parts, matching
+    // AST.InterpolatedPart — the exact shape `$"...{expr}..."` already
+    // produces, so a text node desugars straight into an InterpolatedStringLiteral
+    // with zero new codegen (see template_compiler.ts).
+    parseTextParts(text, startLine, startCol) {
+        const parts = [];
+        let i = 0;
+        let line = startLine;
+        let col = startCol;
+        let literal = "";
+        const advancePos = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === "\n") {
+                    line++;
+                    col = 1;
+                }
+                else {
+                    col++;
+                }
+            }
+        };
+        while (i < text.length) {
+            if (text[i] === "{" && text[i + 1] === "{") {
+                if (literal) {
+                    parts.push({ kind: "Text", text: literal });
+                    literal = "";
+                }
+                const exprStartOffset = i + 2;
+                const end = text.indexOf("}}", exprStartOffset);
+                const exprLine = line;
+                const exprCol = col;
+                advancePos(text.slice(i, exprStartOffset));
+                if (end === -1) {
+                    this.diagnostics.error("Unterminated '{{' interpolation", exprLine, exprCol);
+                    break;
+                }
+                const exprSource = text.slice(exprStartOffset, end);
+                const expr = this.parseEmbeddedExpression(exprSource, exprLine, exprCol);
+                parts.push({ kind: "Expr", expression: expr });
+                advancePos(text.slice(exprStartOffset, end + 2));
+                i = end + 2;
+                continue;
+            }
+            literal += text[i];
+            advancePos(text[i]);
+            i++;
+        }
+        if (literal)
+            parts.push({ kind: "Text", text: literal });
+        return parts;
+    }
+    // Parses the whole template, enforcing the single-root-element rule
+    // (Component.Render() returns exactly one Element — no silent
+    // auto-wrapping if the author writes multiple top-level tags).
+    parseDocument() {
+        const roots = [];
+        while (!this.check(TemplateTokenKind.EOF)) {
+            if (this.check(TemplateTokenKind.Text) && this.peek().lexeme.trim() === "") {
+                this.advance(); // insignificant top-level whitespace
+                continue;
+            }
+            const node = this.parseNode();
+            if (node)
+                roots.push(node);
+        }
+        const elementRoots = roots.filter((r) => r.kind === "element");
+        if (elementRoots.length !== 1) {
+            const at = roots[0] ?? { line: 1, col: 1 };
+            this.diagnostics.error(`A template must have exactly one top-level element, found ${elementRoots.length}`, at.line, at.col);
+            return null;
+        }
+        return elementRoots[0];
+    }
+    parseNode() {
+        if (this.check(TemplateTokenKind.Text)) {
+            const t = this.advance();
+            return { kind: "text", parts: this.parseTextParts(t.lexeme, t.line, t.col), line: t.line, col: t.col };
+        }
+        if (this.check(TemplateTokenKind.TagOpen)) {
+            return this.parseElement();
+        }
+        const t = this.advance();
+        this.diagnostics.error(`Unexpected token in template ('${t.lexeme}')`, t.line, t.col);
+        return null;
+    }
+    parseElement() {
+        const tagTok = this.advance(); // TagOpen
+        const tag = tagTok.lexeme;
+        const staticAttrs = [];
+        const propBindings = [];
+        const eventBindings = [];
+        let ifCondition = null;
+        let forBinding = null;
+        while (this.check(TemplateTokenKind.AttrName)) {
+            const nameTok = this.advance();
+            this.consumeEquals(nameTok);
+            const valueTok = this.consumeAttrValue(nameTok);
+            if (!valueTok)
+                continue;
+            const name = nameTok.lexeme;
+            if (name.startsWith("(") && name.endsWith(")")) {
+                const eventName = name.slice(1, -1);
+                const handler = this.parseEmbeddedExpression(valueTok.lexeme, valueTok.line, valueTok.col);
+                eventBindings.push({ name: eventName, handler, line: nameTok.line, col: nameTok.col });
+            }
+            else if (name.startsWith("[") && name.endsWith("]")) {
+                const propName = name.slice(1, -1);
+                const value = this.parseEmbeddedExpression(valueTok.lexeme, valueTok.line, valueTok.col);
+                propBindings.push({ name: PROPERTY_ALIASES[propName] ?? propName, value, line: nameTok.line, col: nameTok.col });
+            }
+            else if (name === "*if") {
+                if (ifCondition || forBinding) {
+                    this.diagnostics.error(`Only one structural directive ('*if'/'*for') is allowed per element`, nameTok.line, nameTok.col);
+                }
+                else {
+                    ifCondition = this.parseEmbeddedExpression(valueTok.lexeme, valueTok.line, valueTok.col);
+                }
+            }
+            else if (name === "*for") {
+                if (ifCondition || forBinding) {
+                    this.diagnostics.error(`Only one structural directive ('*if'/'*for') is allowed per element`, nameTok.line, nameTok.col);
+                }
+                else {
+                    forBinding = this.parseForBinding(valueTok.lexeme, valueTok.line, valueTok.col);
+                }
+            }
+            else {
+                staticAttrs.push({ name: PROPERTY_ALIASES[name] ?? name, value: valueTok.lexeme, line: nameTok.line, col: nameTok.col });
+            }
+        }
+        const children = [];
+        if (this.check(TemplateTokenKind.TagSelfClose)) {
+            this.advance();
+        }
+        else {
+            this.consume(TemplateTokenKind.TagOpenEnd, tagTok, `Expected '>' or '/>' to close '<${tag}'`);
+            while (!this.check(TemplateTokenKind.TagClose) && !this.check(TemplateTokenKind.EOF)) {
+                if (this.check(TemplateTokenKind.Text) && this.peek().lexeme.trim() === "") {
+                    this.advance(); // insignificant whitespace between child elements
+                    continue;
+                }
+                const child = this.parseNode();
+                if (child)
+                    children.push(child);
+            }
+            if (this.check(TemplateTokenKind.TagClose)) {
+                const closeTok = this.advance();
+                if (closeTok.lexeme !== tag) {
+                    this.diagnostics.error(`Mismatched closing tag: expected '</${tag}>', got '</${closeTok.lexeme}>'`, closeTok.line, closeTok.col);
+                }
+            }
+            else {
+                this.diagnostics.error(`Expected closing tag '</${tag}>'`, tagTok.line, tagTok.col);
+            }
+        }
+        return { kind: "element", tag, staticAttrs, propBindings, eventBindings, ifCondition, forBinding, children, line: tagTok.line, col: tagTok.col };
+    }
+    consumeEquals(attrNameTok) {
+        this.consume(TemplateTokenKind.Equals, attrNameTok, `Expected '=' after attribute '${attrNameTok.lexeme}'`);
+    }
+    consumeAttrValue(attrNameTok) {
+        if (!this.check(TemplateTokenKind.AttrValue)) {
+            this.diagnostics.error(`Expected a quoted value after '${attrNameTok.lexeme}='`, attrNameTok.line, attrNameTok.col);
+            return null;
+        }
+        return this.advance();
+    }
+    consume(kind, at, message) {
+        if (this.check(kind)) {
+            this.advance();
+        }
+        else {
+            this.diagnostics.error(message, at.line, at.col);
+        }
+    }
+}

package/dist/tokens.js

@@ -13,6 +13,7 @@ export var TokenKind;
     TokenKind["Using"] = "Using";
     TokenKind["Extern"] = "Extern";
     TokenKind["Raw"] = "Raw";
+    TokenKind["Template"] = "Template";
     TokenKind["From"] = "From";
     TokenKind["As"] = "As";
     TokenKind["Const"] = "Const";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopscript",
-  "version": "0.5.1",
+  "version": "0.7.1",
   "description": "KopScript: a small OOP, strongly-typed language that transpiles to JavaScript, with generics and nullable types",
   "type": "module",
   "license": "MIT",
@@ -9,12 +9,17 @@
     "type": "git",
     "url": "https://dev.azure.com/koppinator/Koppindependence/_git/Kop"
   },
+  "homepage": "https://kopular.dev",
   "keywords": [
     "language",
     "compiler",
     "transpiler",
     "typescript",
-    "javascript"
+    "javascript",
+    "ai",
+    "llm",
+    "codegen",
+    "agent"
   ],
   "main": "./dist/modules.js",
   "files": [
@@ -37,7 +42,7 @@
     "@types/node": "^20.14.0",
     "tsx": "^4.16.0",
     "typescript": "^5.5.0",
-    "vitest": "^2.0.0"
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=18"