kopscript 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Koppin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,588 @@
+# KopScript
+
+KopScript is a small, strongly-typed, object-oriented programming language that transpiles to
+readable JavaScript. It's a hobby/learning project: a from-scratch lexer, parser, type
+checker, and code generator, written in TypeScript — leaning deliberately toward C#
+paradigms (type-first declarations, interfaces, explicit virtual/override dispatch,
+auto-properties, enums) rather than TypeScript ones.
+
+Because KopScript compiles to plain JavaScript and runs on Node, it runs identically on Windows,
+macOS, and Linux — there's no native toolchain to maintain.
+
+## Highlights
+
+- **Object-oriented, C#-flavored**: type-first declarations (`string Name;`, not `name: string`),
+  classes with auto-properties, single inheritance plus interfaces via `class Dog : Animal, IPet`,
+  explicit `virtual`/`override` dispatch (methods are sealed unless marked `virtual`), and a full
+  `public`/`protected`/`private` access model enforced at compile time.
+- **Strongly typed**: every declaration is explicitly typed and checked at compile time.
+- **Built-in string pattern matching**: a `match` expression over strings supporting literal,
+  wildcard, and regex patterns — no `if`/`else` chains required.
+- **Real multi-file programs**: `using "./shapes";` compiles a whole dependency graph
+  together, checking `public`/`private` visibility across files and emitting genuine ES
+  `import`/`export` statements — so a compiled KopScript module is also a normal JS module that
+  a plain Node/TS project can `import` directly.
+- **First-class functions and real closures**: lambdas (`(number x) => x * 2`), function
+  types (`(number, number) => number`), and calling any function-valued expression — not
+  just named functions — compiling straight to native JS arrow functions, so closures work
+  exactly like they do in JS.
+- **JS/npm interop**: `extern` declarations describe the shape of an existing JS function,
+  class, or global value — ambient (`Math`, `document`, no import) or imported from a
+  module specifier — so KopScript code can call real JS APIs, including a `virtual`
+  method on an `extern class` that a real KopScript class can `override`, which is what
+  lets a class subclass something from another package/repo entirely.
+- **`async`/`await`**: `task<T>` (a promise of a `T`) compiles to a real JS `Promise`,
+  `async`/`await` to the real thing, and `try`/`catch`/`finally`/`throw` give a rejected
+  task something to catch.
+- **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.
+- **A companion framework, [Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular)**:
+  components, constructor-injected services (no DI container), and hash-based routing (no
+  config DSL) — built entirely on the features above, in a separate repo consumed as a
+  real package. [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo)
+  is a real app built on both.
+
+## Getting started
+
+```bash
+npm install
+npm run ks -- run examples/animals.ks
+npm run ks -- run examples/classify.ks
+npm run ks -- run examples/features.ks
+npm run ks -- run examples/shapes.ks
+npm run ks -- run examples/modules/main.ks
+npm run ks -- run examples/closures.ks
+npm run ks -- run examples/async.ks
+npm run ks -- run examples/arrays.ks
+```
+
+These are all plain console scripts, runnable with Node directly. A browser-facing
+KopScript project (DOM `extern` bindings, `ks watch` + a static file server for a live
+reload-free dev loop) is a different setup — see
+[Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular) and
+[KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo) for a
+real example of that workflow.
+
+Or build to a `.js` file without running it:
+
+```bash
+npm run ks -- build examples/animals.ks
+```
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+## Language tour
+
+### Variables
+
+Declarations are type-first, C# style — the type comes before the name, with no `let`:
+
+```ks
+number x = 5;
+const string name = "Joe";
+```
+
+### Functions
+
+Free functions are also type-first, with the return type before the name (no `function`
+keyword — the same shape as a class method, just outside a class):
+
+```ks
+number Add(number a, number b) {
+  return a + b;
+}
+
+void Announce(string message) {
+  print(message);
+}
+```
+
+### Functions as values, and closures
+
+A function type is written `(ParamType, ...) => ReturnType`. Lambdas always have explicit
+parameter types (no inference in v1) and never write their own return type — it's checked
+against whatever function type the lambda is used where, which KopScript always knows concretely
+since every declaration is explicitly typed:
+
+```ks
+number Apply((number) => number f, number x) {
+  return f(x);
+}
+
+number Square(number x) { return x * x; }
+
+print(Apply((number x) => x * 2, 5)); // 10 — an inline lambda
+print(Apply(Square, 4));               // 16 — a named function used as a value
+```
+
+A lambda body can be an expression (`(number x) => x * 2`) or a block
+(`(number x) => { return x * 2; }`). Lambdas are real closures — they capture their
+enclosing scope by reference, compiling directly to JS arrow functions, so mutating a
+captured variable from inside a lambda is visible to the code that captured it:
+
+```ks
+number counter = 0;
+() => number next = () => { counter = counter + 1; return counter; };
+print(next()); // 1
+print(next()); // 2
+```
+
+Calling any expression whose type is a function type works — a variable, a field, a call
+that returns a function, not just a named function or method.
+
+### Classes, auto-properties, and inheritance
+
+```ks
+class Animal {
+  public string Name { get; set; }
+  constructor(string name) { this.Name = name; }
+  public virtual string Speak() { return this.Name + " makes a sound"; }
+}
+
+class Dog : Animal {
+  public override string Speak() { return this.Name + " barks"; }
+}
+```
+
+- `public string Name { get; set; }` is a read-write auto-property; `public string Name { get; }`
+  is get-only — it can only be assigned within its own class's constructor (like a C#
+  read-only auto-property), and is rejected anywhere else, including other methods of the
+  same class.
+- `public` / `protected` / `private` are enforced at compile time: `private` members are
+  only reachable from within the declaring class (any instance, not just `this`);
+  `protected` members are reachable from the declaring class and its subclasses; `public`
+  is unrestricted. Fields default to `public` if no modifier is written.
+- Methods are sealed by default, like C#. A subclass may only redefine a method that the
+  base class marked `virtual`, and must mark its own version `override`; the compiler
+  rejects a redefinition that omits `override`, an `override` with no matching `virtual`
+  base method, or a signature mismatch between the two.
+- `static` fields and methods belong to the class itself, accessed as `ClassName.Member`
+  (never through an instance or `this`) and shared across every instance. A static field
+  requires an inline initializer, since there's no constructor to assign it in:
+  `private static number Count = 0;`. `static` cannot be combined with `virtual`/`override`,
+  and static auto-properties aren't supported in v1 — use a static field instead.
+- A subclass that doesn't declare its own constructor inherits the superclass's (the same
+  way JavaScript's `extends` works). Declaring a constructor in a subclass that extends
+  another class is not supported in v1.
+
+### Interfaces
+
+`class Foo : Base, IBar, IBaz` mixes at most one base class with any number of interfaces
+in a single colon-separated list — the compiler figures out which name is which. A class
+implementing an interface must provide every method the interface declares, with a
+matching signature. Interfaces can themselves extend other interfaces
+(`interface INamedShape : IShape { ... }`), which pulls in the parent's method
+requirements too; implementing classes must satisfy the whole chain. Interfaces only
+declare method signatures in v1 — no properties.
+
+```ks
+interface ISpeaker {
+  string Speak();
+}
+
+class Dog : ISpeaker {
+  public string Speak() { return "Woof"; }
+}
+
+void Announce(ISpeaker s) {
+  print(s.Speak());
+}
+```
+
+### Enums
+
+```ks
+enum Color { Red, Green, Blue }
+
+Color c = Color.Green;
+if (c == Color.Green) { print("It's green"); }
+```
+
+Members are numbered from `0` in declaration order, compiling to a frozen JS object.
+
+### Modules
+
+`using "./shapes";` brings every `public` top-level declaration from that file (resolved
+relative to the current file, no `.ks` extension) into unqualified scope — there's no
+namespace prefix and no picking individual names, the same way a C# `using` directive
+brings a whole namespace into scope. `using` directives must be a contiguous block at the
+very top of the file.
+
+```ks
+// shapes.ks
+interface IShape {
+  number Area();
+}
+
+class Circle : IShape {
+  public number Radius;
+  constructor(number radius) { this.Radius = radius; }
+  public number Area() { return this.Radius * this.Radius * 3; }
+}
+```
+
+```ks
+// main.ks
+using "./shapes";
+
+Circle c = new Circle(2);
+print(c.Area());
+```
+
+Every top-level class, interface, enum, and function is `public` (exported, visible to
+files that `using` this one) by default — mark it `private` to keep it file-scoped:
+
+```ks
+private number Helper() { return 42; } // not visible outside this file
+class Public { }                        // visible by default
+```
+
+Top-level `let`/`const` variables are never exportable — only types and functions cross
+file boundaries. There's also a structural rule worth knowing: if a class or interface is
+exported, everything in its public surface must be exported too (an exported class's base
+class and implemented interfaces, an exported interface's base interfaces) — the compiler
+rejects `public class Derived : Base` if `Base` isn't also `public`, since otherwise a
+file importing `Derived` would have no way to make sense of its own base type.
+
+`ks build`/`ks run` compile the entry file plus everything it transitively `using`s,
+each to its own `.js` file with real ES `import`/`export` statements — so `node
+main.js` (or a plain JS/TS project importing the compiled output directly) just works,
+with Node's own module resolution doing the wiring.
+
+### Interop with JS/npm (`extern`)
+
+`extern` declarations describe the shape of something that already exists in JS, without
+providing a KopScript implementation — KopScript trusts the declared types (same trust model as a
+TypeScript `.d.ts` file). There are three forms, and each can be either **ambient** (no
+`from` — an already-existing global like `Math` or `document`, nothing to import) or
+**imported** (`from "<module>"` — a named export from an npm/Node module):
+
+```ks
+extern string ReadFileSync(string path) from "node:fs" as "readFileSync"; // function
+extern Document document;                                                 // value (ambient)
+
+extern class Element {          // class — a type shape, describing an existing class
+  constructor();
+  string textContent { get; set; }
+  void addEventListener(string eventType, (Event) => void handler);
+  static number InstanceCount { get; }
+} from "some-dom-lib";
+```
+
+`as "<jsName>"` maps a KopScript-facing name to the real JS-side identifier (defaults to the
+declared name if omitted) — needed constantly in practice, since JS naming (`camelCase`,
+`readFileSync`) rarely matches KopScript's (`PascalCase`, `ReadFileSync`). Extern **class
+members** have no separate rename mechanism, though — write them with the exact real JS
+name (`addEventListener`, not `AddEventListener`), since that's what actually exists at
+runtime. Calling an extern method or accessing an extern property compiles exactly like
+any other member access — no special codegen, since it isn't reimplementing the class,
+just describing one that's already there.
+
+A real, working example: [Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular)'s
+`dom.ks` declares ambient bindings for `document`/`Element`/`Event`/`window`/`location`,
+which its `Component`/`Router` are built on — and
+[KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo)
+consumes `Component`/`Router` themselves via `extern class ... from "kopular/...";`,
+proving `extern` works as a real cross-*package* boundary, not just for describing DOM
+globals within a single project.
+
+Now that KopScript has `async`/`await` and `task<T>` (see below), a Promise-based JS API is
+describable too — `extern task<string> Fetch(...) from "..." as "fetch";` is legitimate,
+and `await`ing it works exactly like awaiting any other KopScript task. What's still not cleanly
+describable is old-style Node **callback-based** async that doesn't return a Promise at all
+(`fs.readFile(path, callback)` with an error-first callback) — nothing in KopScript understands
+that specific convention, even though the callback parameter itself is describable as an
+ordinary function type.
+
+### async/await, task&lt;T&gt;, and try/catch
+
+`task` (a promise of nothing) and `task<T>` (a promise of a `T`) are the one hardcoded
+parametrized type in v1 — not general generics, just enough to give `async`/`await` a
+return type. `async` requires (and is required by) a `task`/`task<T>` return type; `return`
+statements inside an async body are checked against the unwrapped result type, exactly
+like real C#/JS async functions — you write `return 5;`, not `return SomeTaskOf(5);`:
+
+```ks
+async task<number> Double(number x) {
+  return x * 2;
+}
+
+async task<number> Chain(number x) {
+  number a = await Double(x);
+  number b = await Double(a);
+  return b;
+}
+```
+
+Both compile directly to their real JS equivalents (`async function`, `await`), so an
+`async` KopScript function returns a genuine `Promise` and composes with plain JS/TS code
+without any wrapping. `await` also works at the top level of a file, matching real
+top-level await in an ES module.
+
+Exception handling exists specifically so a rejected task has something to catch:
+
+```ks
+try {
+  number result = await MightFail(x);
+  print(result);
+} catch (string message) {
+  print("caught: " + message);
+} finally {
+  print("done");
+}
+```
+
+`throw` accepts any type — there's no base exception/error type to require conformance
+to, matching JS's own looseness — and a `catch (Type name)` parameter's type is trusted,
+not verified (the same trust model as `extern`: KopScript has no way to know what a given `throw`
+site might actually produce). At least one of `catch`/`finally` is required; a bare `try {}`
+alone is rejected. `examples/async.ks` and `test/codegen.test.ts` exercise a full chain of
+async calls, a caught error, and a `finally` that runs on both the success and failure path.
+
+Known v1 limitations: no async lambdas (`await` is never valid inside a lambda body, even
+inside an async function — only free functions and methods can be `async`), and no way to
+construct a `task` value directly outside of an `async` function body.
+
+### Reactive state: state&lt;T&gt;
+
+`state<T>` is the other hardcoded parametrized type in v1, alongside `task<T>` — a reactive
+box holding a `T`. Construct one with `state(initial)` (no explicit type argument; `T` is
+inferred from `initial`), read/write it through `.Value`, and register a listener with
+`.Subscribe((T) => void)` that fires every time `.Value` is assigned:
+
+```ks
+state<number> count = state(0);
+count.Subscribe((number v) => print("now " + v));
+count.Value = count.Value + 1; // prints "now 1"
+```
+
+This exists to give Kopular components a way to re-render on state change without pulling in
+anything like RxJS — no Observables, no operators, no manual unsubscribe bookkeeping. A
+component subscribes once, in its constructor, to call its own `Update()`:
+
+```ks
+class Counter : Component {
+  private state<number> Count;
+
+  constructor() : base() {
+    this.Count = state(0);
+    this.Count.Subscribe((number v) => this.Update());
+  }
+
+  public override Element Render() {
+    Element button = document.createElement("button");
+    button.textContent = "Count: " + this.Count.Value;
+    button.addEventListener("click", (Event e) => {
+      this.Count.Value = this.Count.Value + 1; // Update() fires automatically
+    });
+    return button;
+  }
+}
+```
+
+Compare this to the pre-`state<T>` version of the same component, which had to call
+`this.Update();` by hand inside every single event handler that touched state — one
+`Subscribe` call at construction now does that job everywhere.
+[Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular)'s `Component`
+is built around exactly this pattern, and its own README covers the rest of the
+"Angular's separation, none of the bloat" story — constructor-injected services instead
+of a DI container, and hash-based routing instead of a config DSL — both built entirely
+on ordinary KopScript, no further compiler features required beyond `state<T>` and the
+`extern`/`virtual` support above.
+
+### String interpolation
+
+```ks
+string name = "Joe";
+string msg = $"Hello, {name}!";
+```
+
+### Pattern matching over strings
+
+The headline feature: a `match` expression with literal, comma-separated, and regex patterns.
+A `match` must end with a `_` wildcard arm.
+
+```ks
+string Classify(string input) {
+  return match input {
+    "cat", "dog" => "animal",
+    r"^[0-9]+$" => "number",
+    _ => "unknown"
+  };
+}
+```
+
+### String stdlib
+
+KopScript's `string` type exposes PascalCase members that map directly onto
+`String.prototype`:
+
+| KopScript                    | JavaScript                |
+| ----------------------- | -------------------------- |
+| `s.Contains(x)`        | `s.includes(x)`           |
+| `s.StartsWith(x)`      | `s.startsWith(x)`         |
+| `s.EndsWith(x)`        | `s.endsWith(x)`           |
+| `s.Replace(a, b)`      | `s.replaceAll(a, b)`      |
+| `s.Split(x)`           | `s.split(x)`              |
+| `s.Trim()`             | `s.trim()`                |
+| `s.ToUpper()`          | `s.toUpperCase()`         |
+| `s.ToLower()`          | `s.toLowerCase()`         |
+| `s.Length`             | `s.length`                |
+
+### Array stdlib
+
+Arrays expose `.Length`, plus `Map`/`Filter`/`ForEach`/`Push`, using lambdas or any other
+function-valued expression (a named function, a variable holding one, ...):
+
+```ks
+number[] xs = [1, 2, 3, 4];
+string[] labels = xs.Map((number x) => "n" + x);      // ["n1", "n2", "n3", "n4"]
+number[] evens = xs.Filter((number x) => x % 2 == 0);  // [2, 4]
+xs.ForEach((number x) => print(x));
+number[] grown = xs.Push(5);                           // [1, 2, 3, 4, 5]; xs itself is untouched
+```
+
+`Map`/`Filter`/`ForEach` compile straight to their real `Array.prototype` equivalents.
+`Push` is the one departure from JS: it's **non-mutating** (returns a new array; `xs`
+itself is unchanged), unlike JS's own `Array.prototype.push` — chosen for consistency with
+`Map`/`Filter` (already non-mutating) and because nothing else in KopScript's type system models
+aliasing/mutable-reference semantics, so a silently-mutating `Push` would be a surprising
+outlier. It compiles to a plain spread (`[...xs, 5]`), not a `.push()` call.
+
+`Map`'s result type is the one genuinely polymorphic piece of the whole language — the
+result element type is whatever the callback actually returns, not a fixed signature.
+A plain function reference (`xs.Map(SomeFunction)`) already carries a fully-known type, so
+that case is exact; an inline expression-bodied lambda (`xs.Map((number x) => ...)`) has
+its return type inferred from the body. A block-bodied lambda passed to `Map` is a known
+v1 gap — its result type can't be inferred that way yet.
+
+### Control flow
+
+```ks
+if (x > 0) {
+  print("positive");
+} else {
+  print("non-positive");
+}
+
+while (x < 10) {
+  x = x + 1;
+}
+
+for (number i = 0; i < 10; i = i + 1) {
+  print(i);
+}
+
+foreach (number item in items) {
+  print(item);
+}
+```
+
+`foreach` requires an explicit element type (there's no `var`/type inference in v1).
+`break` and `continue` work inside `while`, `for`, and `foreach` loops.
+
+### Types (v1 scope)
+
+`number`, `string`, `bool`, `void`, `T[]` (arrays), class types, interface types, enum
+types, and function types (`(T, ...) => R`). No generics or nullable types yet — a
+possible future extension.
+
+### Built-ins
+
+`print(...)` compiles to `console.log(...)`.
+
+## Architecture
+
+```
+src/
+  lexer.ts       tokenizer: source -> Token[]
+  tokens.ts      token kind enum + Token type
+  ast.ts         AST node type definitions
+  parser.ts      recursive-descent parser: Token[] -> AST (Program)
+  diagnostics.ts error/warning collection with line/col + source snippets
+  types.ts       type system: Type representations + compatibility rules
+  checker.ts     semantic analysis: scopes, symbol table, type checking over the AST
+  codegen.ts     AST -> JavaScript source string (readable ES2020 output)
+  modules.ts     multi-file orchestration: resolves the `using` graph, checks
+                 modules in dependency order, drives codegen across all of them
+  cli.ts         `ks build <file>` / `ks run <file>` entry point
+examples/        sample .ks programs (examples/modules/ is a multi-file one)
+test/            vitest unit and end-to-end tests
+```
+
+Pipeline, per file: source -> lexer -> parser (AST) -> checker (validates the AST,
+collects diagnostics) -> codegen (emits JS). `modules.ts` sits above this: it parses the
+entry file and everything it transitively `using`s, topologically sorts them
+(dependencies first), and checks each one with its direct dependencies' exports seeded in
+— so a class from another file resolves exactly like a local one once the checker starts.
+Codegen then runs per file, turning each `using` into a real `import` statement and each
+exported top-level declaration into a real `export`. The CLI aborts before writing
+anything if *any* file in the graph has errors, and otherwise writes one `.js` file next
+to each `.ks` source and (for `run`) executes the entry file's output with `node`.
+
+Interfaces and the virtual/override discipline are purely compile-time: JS methods are
+always dynamically dispatched, so codegen doesn't need to do anything special for either
+one — the checker just validates the contract before code is ever emitted. Enums compile
+to a small frozen object (`Object.freeze({ Red: 0, Green: 1, ... })`); interfaces have no
+runtime representation at all and are dropped from the emitted JS entirely.
+
+## CLI
+
+```
+ks build <file.ks>   # type-check and emit <file>.js next to the source
+ks run <file.ks>     # build, then execute the emitted JS with node
+ks watch <file.ks>   # build, then rebuild on every change to any file in the graph
+```
+
+During development, use `npm run ks -- <build|run|watch> <file.ks>` (backed by `tsx`),
+or run `npm run build` to compile the TypeScript compiler itself to `dist/` and 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
+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
+that to the page. See [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo)
+for this workflow in practice.
+
+## Editor support
+
+`editors/vscode/` is a local-install-only VS Code extension providing `.ks` syntax
+highlighting (a TextMate grammar — comments, all three string forms including highlighted
+interpolation expressions, keywords, types, function calls) and bracket/comment
+configuration. No language server, no Marketplace listing — see `editors/vscode/README.md`
+for installing it locally (`Developer: Install Extension from Location...`, or symlink it
+into your extensions folder).
+
+## Status
+
+This is a v1 / hobby-project scope. Not yet supported: generics, nullable types, static
+auto-properties, interface properties (methods only), and nested functions/classes.
+Generics and nullable types in particular are a substantially bigger undertaking than
+everything else here — they touch the type system's core (type parameters, variance,
+constraint checking) rather than being additive features, so they're deliberately left
+for a dedicated future pass rather than bolted on.
+
+`async`/`await`, `task<T>`, and `try`/`catch`/`finally`/`throw` are now in place (see the
+language tour above) — the ceiling that's left is what's *inside* those: no async lambdas,
+and no way to build a `task` value by hand outside an `async` function body.
+
+### Toward a frontend framework: Kopular
+
+The language shape — modules, closures, DOM interop, `state<T>`, and `extern`/`virtual`
+subclassing across a package boundary — exists to support real UI components, not just
+scripts. That framework itself, [Kopular](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular),
+lives in its own repo now rather than in `examples/` here, consumed as a real package
+(currently via a `file:` dependency, pending an npm publish of both). A real app built on
+both lives in [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo) —
+components, `state<T>`-driven reactivity, a constructor-injected service, and
+hash-based routing between two pages, verified against a real DOM via jsdom and in an
+actual browser.

package/bin/ks.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+// Runs the compiled CLI directly — a published/installed package has no
+// `src/` or `tsx` (a devDependency of this repo, not shipped), only
+// `dist/`. Local development uses `npm run ks`, which still runs `tsx`
+// against `src/cli.ts` directly for a fast edit-run loop.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliEntry = join(__dirname, "..", "dist", "cli.js");
+
+const result = spawnSync(process.execPath, [cliEntry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+
+process.exit(result.status ?? 0);

package/dist/ast.js

@@ -0,0 +1,2 @@
+// ---------- Type annotations (syntactic, as written in source) ----------
+export {};