kopular 0.5.0 → 0.8.0

package/LLM.md

@@ -1,17 +1,18 @@
 # Kopular — LLM reference
 
 Complete reference for generating correct Kopular code. This is a spec, not a tutorial —
-see `README.md` for narrative/rationale. Kopular is 6 files total; this covers all of
+see `README.md` for narrative/rationale. Kopular is 8 files total; this covers all of
 them. For the host language, see KopScript's own `LLM.md` in the `Kop` repo (or its
 published `LLM.md` on the `kopscript` npm package) — that reference is a prerequisite,
 not repeated here.
 
 Published as npm `kopular`. Entry points: `kopular` / `kopular/component` (Component),
 `kopular/router` (Router), `kopular/dom` (ambient DOM bindings), `kopular/directives`
-(If), `kopular/http` (Http). Also ships a bin, `kp` — `npx kp new <dir>` scaffolds a new
-project (the `extern` bindings below, plus the vendor/serve scripts needed to run in a
-browser) rather than requiring it be reconstructed by hand; prefer it over hand-writing
-the section below for a new project.
+(If), `kopular/http` (Http), `kopular/forms` (FormField, Validators), `kopular/testing`
+(runKopularApp, runKopularFixture — see below). Also ships a bin, `kp` — `npx kp new
+<dir>` scaffolds a new project (the `extern` bindings below, plus the vendor/serve
+scripts needed to run in a browser) rather than requiring it be reconstructed by hand;
+prefer it over hand-writing the section below for a new project.
 
 ## Consuming Kopular from your own KopScript project
 
@@ -47,8 +48,38 @@ extern class Http {
   static task<Response> Patch(string url, string jsonBody);
   static task<Response> Delete(string url);
 } from "kopular/http";
+
+extern class Validators {
+  static string? Required(string value);
+  static string? MinLength(string value, number min);
+  static string? MaxLength(string value, number max);
+  static string? Email(string value);
+  static string? Min(number value, number min);
+  static string? Max(number value, number max);
+} from "kopular/forms";
+```
+
+**`extern class` has no `<T>` syntax** — `extern class FormField<T> { ... }` is a parse
+error (`ExternClassDecl` has no `typeParam`, unlike a real `ClassDecl`/`InterfaceDecl`).
+Describe one concrete instantiation per `T` you actually need instead, aliasing the same
+real export with `as` (the same trust-based, per-shape approach `Http`'s typed-JSON gap
+above already uses) — e.g. for a `FormField<string>`:
+
+```ks
+extern class StringField {
+  constructor(string initial, (string) => string? validate);
+  state<string> Value;
+  state<string?> Error;
+  state<bool> Touched;
+  void Touch();
+  bool Valid();
+} from "kopular/forms" as "FormField";
 ```
 
+`Value`/`Error`/`Touched` are declared as bare properties (`state<T> Value;`, no
+`{ get; }`) — `extern class` supports a plain field declaration for exactly this case,
+not just get/set accessor pairs.
+
 You also need your own ambient DOM `extern` block (`document`, `Element`, `Event`, ...) —
 Kopular's own copy in `dom.ks` isn't reachable across the package boundary; redeclare the
 handful of members you actually use. See KopularDemo's `src/kopular_bindings.ks` for a
@@ -128,8 +159,38 @@ nav.Navigate("/about");                          // pushState + immediate re-ren
 - `Navigate(path)` calls `history.pushState` then re-renders immediately. A browser
   back/forward triggers re-render via a `popstate` listener registered in the
   constructor — `Navigate()` itself doesn't rely on that event.
-- Needs a server that falls back to the app shell for any unrecognized path (a plain
-  static server has nothing to serve at `/about` on direct load/refresh).
+- **Dynamic route segments**: a pattern segment written `:name` (e.g. `AddRoute("/dogs/:id",
+  ...)`) matches any single non-empty path segment; every other segment must match
+  literally (same segment count required too — `/dogs` does NOT match `/dogs/:id`).
+  The captured value is `Router.Param` — a plain `string` field (**not** `state<T>`; no
+  `Subscribe()` needed — see below), `""` when the matched route has no `:` segment.
+  Just one dynamic segment per route in v1: no `/dogs/:id/toys/:toyId`, no wildcards, no
+  query string parsing.
+- **Why `Param` is a plain field, not `state<T>`**: `Render()` already rebuilds a fresh
+  outlet and re-`Mount()`s the matched page on every `Navigate()`/`popstate`, which
+  re-runs that page's own `Render()` (reading the fresh `Param`) with no extra step.
+  Making it `state<T>` and having a page `Subscribe()` to it — the pattern every *other*
+  piece of state in this framework uses — actually crashes: `Match()` sets it *before*
+  `Render()` finishes swapping the matched page into the outlet, so the very first route
+  that matches a page nothing has `Mount()`ed yet fires that page's subscribed listener
+  while its inherited `Update()` still has no `ParentElement` to `replaceChild` into.
+- **Every deployment target needs its own SPA/history-fallback config — this is
+  unavoidable, not a Kopular gap.** A direct load or refresh at `/about` is a plain HTTP
+  request that reaches your host *before* any JS (Router included) has run, so no
+  client-side router in any language/framework can intercept it; the host itself has to
+  respond with the app shell for any route it doesn't have a literal file for. Configure
+  this on every host you deploy to, not just in local dev:
+  - Local dev (`ks watch` + a static file server): see KopularDemo's `scripts/serve.mjs`
+    — falls back to `index.html` only for an extension-less path, so a genuinely missing
+    `.js`/`.css` still 404s.
+  - Cloudflare Workers (what KopularDemo itself deploys to): `wrangler.jsonc`'s
+    `assets.not_found_handling: "single-page-application"`. Coarser than `serve.mjs` —
+    it falls back for *any* unmatched request, extension or not, so a typo'd asset URL
+    silently serves the app shell instead of 404ing (confirmed via `wrangler dev`; no
+    config short of a custom Worker distinguishes the two cases).
+  - Any other static host (Netlify, Vercel, S3+CloudFront, nginx, ...) has an equivalent
+    "SPA fallback" / "custom 404 → index.html" option — look for that host's own docs on
+    single-page-application routing, the terminology is standard across all of them.
 
 ## `If` (`directives.ks`) — the `*ngIf` equivalent
 
@@ -176,7 +237,8 @@ r.status   // number
 await r.text();   // task<string> — the raw body, nothing more
 ```
 
-**No typed JSON deserialization** — no generics means no safe `Get<T>(url): task<T>`.
+**No typed JSON deserialization** — KopScript's generics are classes/interfaces only (no
+generic functions/methods), so there's no safe `task<T> Get<T>(string url)`.
 Get a typed response by describing its shape as its own `extern class` and parsing with
 a per-shape `extern ... as "JSON.parse"` (unchecked, same trust model as every other
 `extern`):
@@ -194,6 +256,65 @@ hypothetical `Delete`-with-a-body) need one for `{ method, headers, body }`, whi
 KopScript categorically cannot construct — Kopular ships one small hand-written JS
 function (`http_runtime.js`, not compiled from `.ks`) that does, for exactly that reason.
 
+## `FormField<T>` / `Validators` (`forms.ks`)
+
+```ks
+FormField<string> email = new FormField<string>("", (string v) => {
+  string? required = Validators.Required(v);
+  if (required != null) { return required; }
+  return Validators.Email(v);
+});
+
+email.Value.Value = "x";        // state<T> — revalidates automatically on assignment
+email.Error.Value               // string? — current validator's message, or null
+email.Touched.Value             // bool — only true after Touch() (call on blur)
+email.Touch();
+email.Valid();                  // bool — Error.Value == null
+```
+
+`Validators.Required/MinLength/MaxLength/Email` are `(string) => string?`;
+`Validators.Min/Max` are `(number) => string?`. Each returns an error message or `null`.
+
+**No array-of-validators parameter** — KopScript has no array-of-function-values type
+(`((T) => string?)[]` doesn't parse: the parser reads a second `(...)  => ...` immediately
+after the first as a nested function type, not an array element type, and errors expecting
+`=>`). Combine checks as an if-chain in one lambda instead (see the `email` example above)
+— this is the same reason `FormField<T>`'s constructor takes exactly one validator
+function, not a list.
+
+**No DOM binding** — wiring `.Value` to a real `<input>` is a plain `addEventListener`
+call in your own `Render()`, the same as any other event handler; there is no
+`[(ngModel)]`-equivalent.
+
+## `kopular/testing` (`testing.js`, hand-written JS, not compiled from `.ks`)
+
+```ts
+import { runKopularApp } from "kopular/testing";
+
+const { window, cleanup } = await runKopularApp(srcDir, "app.ks", {
+  includeKopularPackage: true,   // app consumes Kopular via `extern`, not relative `using`
+  extraFiles: ["http_runtime.js"], // non-.ks/.html siblings a `using` graph needs at runtime
+  fetchMock: (...args) => Promise.resolve({ ok: true, status: 200, text: () => Promise.resolve("body") }),
+  url: "http://localhost/",
+});
+try {
+  window.document.querySelector(...)
+} finally {
+  cleanup();  // always call, even on a thrown assertion — restores globalThis + deletes the temp dir
+}
+```
+
+Compiles `entryFileName` (plus everything else in `srcDir` it `using`s) via kopscript's
+`compileGraph`, binds jsdom onto `globalThis` (`document`/`Element`/`Event`/`location`/
+`history`/`window`/`fetch`) for the compiled ambient `extern` declarations to find, and
+runs it. `runKopularFixture(source, options)` is the sibling export for an inline fixture
+string instead of a real file (used by Kopular's own test suite; copies Kopular's *own*
+`.ks` sources alongside the fixture, so `using "./component"` resolves — only meaningful
+for testing Kopular itself, not an external consumer, which should use `runKopularApp`
+with `includeKopularPackage: true` instead).
+
+`jsdom` is an optional peer dependency — add it to your own project to use this.
+
 ## Dependency injection — no container, no decorators
 
 There is no injector, no `@Injectable`, no provider tokens. "Injecting" a service is

package/README.md

@@ -26,9 +26,8 @@ Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./
   class.
 - **`Router`**: real URLs (`/about`, not `#/about`) via the History API
   (`pushState`/`popstate`), with route registration as plain method calls, not a config
-  DSL. Needs a server that falls back to the app shell for unrecognized paths — see
-  [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo)'s
-  `scripts/serve.mjs`.
+  DSL. See "Router, and deploying it" below — every deployment target needs its own
+  SPA-fallback config, not just local dev.
 - **Structural directives, no template DSL**: `*ngIf`/`*ngFor`/`*ngSwitch`'s job — build
   a subtree conditionally, repeat one per item, pick one of several cases — done as plain
   function calls (`If(...)`) and existing KopScript expressions (`array.ForEach(...)`,
@@ -36,6 +35,8 @@ Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./
 - **`Http`**: a thin, static wrapper over the real Fetch API (`Http.Get(url)`,
   `Http.Post(url, jsonBody)`, ...) — no HttpClient injection tokens, no RxJS
   observables/operators. See "HTTP" below.
+- **`FormField<T>`**: a single input's value/error/touched state, built on `state<T>` —
+  no two-way-binding magic, no `FormGroup` config object. See "Forms" below.
 
 ## What's here
 
@@ -48,14 +49,22 @@ Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./
 - `src/http.ks` — `Http`, a thin wrapper over `fetch` (see below). `src/http_runtime.js`
   is its one companion file — the single hand-written (not compiled from `.ks`) file in
   Kopular, and why is explained in its own header comment.
-
-That's the whole framework — six files. Everything else (a real app built on top of it)
+- `src/forms.ks` — `FormField<T>` and `Validators` (see "Forms" below).
+- `src/testing.js` — `runKopularApp`/`runKopularFixture` (see "Testing your own app"
+  below); hand-written for the same reason as `http_runtime.js` — filesystem/process
+  orchestration isn't a Kopular `Component`.
+- `bin/kp.mjs` — the `kp new` scaffolding CLI (see "Starting a new project" below); also
+  hand-written, same reason.
+
+That's the whole framework — eight files, plus the scaffolding CLI. Everything else (a
+real app built on top of it)
 lives in a separate consumer repo, [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo).
 
 ## Dependency injection: the composition root pattern
 
 Kopular has no injector because KopScript has nothing for one to hook into — no
-decorators, no reflection, no generics for a type-safe `Resolve<T>()`. Instead, the
+decorators, no reflection, and no *generic functions* (KopScript's generics are
+classes/interfaces only — see the Kop repo) for a type-safe `Resolve<T>()`. Instead, the
 whole app's service/page graph gets built exactly once, by hand, in one place: a plain
 class with no `Component` base and no framework code in it at all, sometimes called an
 **app container** or (in the wider DI literature) a **composition root**. Everything
@@ -119,6 +128,57 @@ See [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/Kopular
 `src/app_container.ks` and `src/routed_app.ks` for the real, working version this
 example is drawn from.
 
+## Router, and deploying it
+
+```ks
+Router nav = new Router(new NotFoundPage());   // fallback page required up front — no null route
+nav.AddRoute("/", new HomePage(nav));           // pages built once, kept alive for Router's lifetime
+nav.AddRoute("/about", new AboutPage(nav));
+nav.Mount(document.body);
+nav.Navigate("/about");                          // pushState + immediate re-render
+```
+
+Real URLs via the History API (`pushState`/`popstate`), not `#/about` hash routing.
+`AddRoute` takes an already-constructed `Component`, not a factory, so a page's own
+`state<T>` survives navigating away and back — see "Dependency injection" above for how
+the whole page graph typically gets built once, in a composition root.
+
+**Dynamic route segments**: a path segment written `:name` (e.g. `/dogs/:id`) matches any
+single non-empty segment, captured into `Router.Param`:
+
+```ks
+nav.AddRoute("/dogs/:id", new DogPage(nav));
+// inside DogPage.Render():
+el.textContent = "Dog #" + this.Nav.Param;
+```
+
+`Param` is a plain `string`, deliberately not `state<T>` — Router's own `Render()`
+already rebuilds a fresh outlet and re-`Mount()`s the matched page on every
+`Navigate()`/`popstate`, which re-runs that page's `Render()` (reading the fresh `Param`)
+with no extra step. No `Subscribe()` needed on it. Deliberately just one dynamic segment
+per route for now — no multiple params (`/dogs/:id/toys/:toyId`), no wildcards, no query
+string parsing — each a real, separate extension, not an oversight.
+
+**Deploying a Router-based app needs SPA/history-fallback configured on whatever you
+deploy to — this is true of every client-side router in every framework, not a Kopular
+gap.** A direct load or a refresh at `/about` is a plain HTTP request that reaches your
+host before any JS has run, so nothing client-side (Router included) can intercept it;
+the host has to serve the app shell itself for any route it has no literal file for.
+KopularDemo hit exactly this in production (worked when navigated to via a link, 404'd on
+refresh) before its Cloudflare Workers config had this set:
+
+```jsonc
+// wrangler.jsonc
+"assets": {
+  "directory": "./public",
+  "not_found_handling": "single-page-application"
+}
+```
+
+Every static host has an equivalent option (Netlify, Vercel, nginx, ...) — search that
+host's docs for "SPA fallback" or "single-page application routing", the terminology is
+standard. For local dev, see KopularDemo's `scripts/serve.mjs`.
+
 ## Structural directives
 
 Angular's `*ngIf`/`*ngFor`/`*ngSwitch` are template syntax that expands, at compile time,
@@ -209,8 +269,9 @@ anywhere, including straight out of a service's own methods.
 
 **No typed JSON deserialization** — `Response.text()` gets you the raw body, nothing
 more. This isn't a corner cut for v1; it's a direct consequence of two things KopScript
-doesn't have: generics (so there's no safe way to write a general `Get<T>(url):
-task<T>`) and object-literal syntax (`{ ... }` as a value — see below). If you want a
+doesn't have: generic *functions/methods* (KopScript's generics are classes/interfaces
+only, so there's no safe way to write a general `task<T> Get<T>(string url)`) and
+object-literal syntax (`{ ... }` as a value — see below). If you want a
 typed response, describe its shape as its own `extern class` and parse it yourself with
 a per-shape `extern ... as "JSON.parse"` declaration — the same trust-based approach
 `extern` already uses for everything else, not a new mechanism:
@@ -235,6 +296,49 @@ real global). It's the one file in this package not compiled from `.ks` — ever
 else avoids the problem by only wrapping JS APIs that take plain positional arguments
 (see `dom.ks`'s `addEventListener(string, handler)`, never an options-object-taking API).
 
+## Forms
+
+```ks
+using "./forms";
+
+FormField<string> email = new FormField<string>("", (string v) => {
+  string? required = Validators.Required(v);
+  if (required != null) { return required; }
+  return Validators.Email(v);
+});
+
+email.Value.Value = "not-an-email";
+print(email.Error.Value);   // "Must be a valid email"
+print(email.Valid());       // false
+
+emailInput.addEventListener("input", (Event e) => {
+  email.Value.Value = emailInput.textContent;   // revalidates automatically
+});
+emailInput.addEventListener("blur", (Event e) => { email.Touch(); });
+```
+
+`FormField<T>` holds one input's value, error, and touched state as three ordinary
+`state<T>` boxes — `.Value` (the input's current value, revalidating on every
+assignment), `.Error` (`string?`, the current validator's message or `null`), and
+`.Touched` (`bool`, set by calling `.Touch()` — typically on blur, so a fresh field with
+an invalid initial value like an empty required field doesn't show an error before the
+user has typed anything). Subscribe to any of the three from your `Component`'s
+constructor exactly like `Counter`'s own `state<number>`, to re-render when they change.
+
+A validator is a plain `(T) => string?` — `null` means valid, the same convention
+KopScript's own nullable types use elsewhere. **There's no array-of-validators
+constructor parameter** — KopScript has no syntax for an array of function values — so
+combining more than one check (as `email` does above) is just an `if`-chain in one
+lambda, not a combinator API. `Validators` ships the handful of checks almost every form
+needs (`Required`, `MinLength`, `MaxLength`, `Email`, `Min`, `Max`), each returning its
+own message; write your own validator function for anything more specific.
+
+**No two-way data binding** — wiring `Value` to a real `<input>` is the
+`addEventListener` call shown above, the same manual pattern `Counter` already uses for
+its click handler. This is deliberate, not a missing feature: a magic `[(ngModel)]`-style
+binding would be exactly the kind of hidden framework behavior Kopular avoids everywhere
+else.
+
 ## Starting a new project: `kp new`
 
 Everything in the next section — the `extern` bindings, plus a `vendor/kopular/` copy of
@@ -291,6 +395,42 @@ Marking `Render()` `virtual` in the `extern` declaration is what lets a real sub
 for a full working example (components, a service, and routing, all consuming Kopular
 this way).
 
+`extern class` has no `<T>` syntax, so a generic export like `FormField<T>` can't be
+described directly this way — see `LLM.md`'s `FormField<T>`/`Validators` section for the
+per-concrete-type workaround (the same trust-based, per-shape approach the "HTTP" section
+above uses for typed JSON).
+
+## Testing your own app: `kopular/testing`
+
+A `Component`/`Router` graph can only be exercised end-to-end by actually compiling its
+`.ks` sources and running the result against a real DOM — there's no way to unit test one
+otherwise. Doing that by hand is a real ~50-line dance (a fresh temp dir per test, since
+Node's ESM module cache means re-importing the same compiled path twice never re-runs an
+ambient extern binding's top-level code — silently binding every later test to the first
+test's jsdom instance — compiling via `kopscript`'s `compileGraph`, binding jsdom onto
+`globalThis` for `document`/`Element`/... to find, then restoring it). Both Kopular's own
+test suite and KopularDemo's used to hand-roll this independently; `kopular/testing` is
+that dance, written once:
+
+```ts
+import { runKopularApp } from "kopular/testing";
+
+const { window, cleanup } = await runKopularApp(join(__dirname, "..", "src"), "app.ks", {
+  includeKopularPackage: true, // your app consumes Kopular via `extern`, not relative `using`
+});
+try {
+  expect(window.document.querySelector("h1")?.textContent).toBe("Hello");
+} finally {
+  cleanup(); // always — even on a thrown assertion — or the next test inherits these globals
+}
+```
+
+`jsdom` is an **optional peer dependency** — installing `kopular` alone doesn't pull it
+in; only a project that actually calls `runKopularApp` needs it added too. See
+`Kopular/test/kopular.test.ts` (`runKopularFixture`, the sibling export used for testing
+Kopular's own source against inline fixtures) and KopularDemo's
+`test/routed_app.test.ts` for two real, different call sites.
+
 ## Getting started (developing Kopular itself)
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.5.0",
+  "version": "0.8.0",
   "description": "Kopular: a small component framework for KopScript — components, reactive state, constructor-injected services, routing, structural directives, and HTTP, with no template DSL and no DI container",
   "type": "module",
   "license": "MIT",
@@ -25,7 +25,9 @@
     "./router": "./src/router.js",
     "./dom": "./src/dom.js",
     "./directives": "./src/directives.js",
-    "./http": "./src/http.js"
+    "./http": "./src/http.js",
+    "./forms": "./src/forms.js",
+    "./testing": "./src/testing.js"
   },
   "files": [
     "src",
@@ -34,13 +36,21 @@
     "LLM.md"
   ],
   "scripts": {
-    "build": "ks build src/router.ks && ks build src/directives.ks && ks build src/http.ks",
+    "build": "ks build src/router.ks && ks build src/directives.ks && ks build src/http.ks && ks build src/forms.ks",
     "prepublishOnly": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest"
   },
+  "peerDependencies": {
+    "jsdom": "^25.0.0"
+  },
+  "peerDependenciesMeta": {
+    "jsdom": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "kopscript": "^0.4.0",
+    "kopscript": "^0.4.1",
     "@types/jsdom": "^30.0.0",
     "@types/node": "^20.14.0",
     "jsdom": "^25.0.1",

package/src/forms.js

@@ -0,0 +1,81 @@
+class __KopState {
+  constructor(value) {
+    this._value = value;
+    this._listeners = [];
+  }
+  get Value() { return this._value; }
+  set Value(v) {
+    this._value = v;
+    for (const listener of this._listeners) listener(v);
+  }
+  Subscribe(listener) {
+    this._listeners.push(listener);
+  }
+}
+
+export class FormField {
+  constructor(initial, validate) {
+    (this.Value = new __KopState(initial));
+    (this.Error = new __KopState(validate(initial)));
+    (this.Touched = new __KopState(false));
+    this.Value.Subscribe((v) => {
+  (this.Error.Value = validate(v));
+});
+  }
+
+  Touch() {
+    (this.Touched.Value = true);
+  }
+
+  Valid() {
+    return (this.Error.Value === null);
+  }
+}
+export class Validators {
+  static Required(value) {
+    if ((value.trim().length === 0)) {
+      return "Required";
+    }
+    return null;
+  }
+
+  static MinLength(value, min) {
+    if ((value.length < min)) {
+      return `Must be at least ${min} characters`;
+    }
+    return null;
+  }
+
+  static MaxLength(value, max) {
+    if ((value.length > max)) {
+      return `Must be at most ${max} characters`;
+    }
+    return null;
+  }
+
+  static Email(value) {
+    return (() => {
+  const __subject0 = value;
+  if (new RegExp("^[^@\\s]+@[^@\\s]+\\.[^@\\s]+$").test(__subject0)) {
+    return null;
+  }
+  else {
+    return "Must be a valid email";
+  }
+})();
+  }
+
+  static Min(value, min) {
+    if ((value < min)) {
+      return `Must be at least ${min}`;
+    }
+    return null;
+  }
+
+  static Max(value, max) {
+    if ((value > max)) {
+      return `Must be at most ${max}`;
+    }
+    return null;
+  }
+}

package/src/forms.ks

@@ -0,0 +1,77 @@
+// FormField<T>: a single form input's value, validation state, and touched
+// flag, built on the same state<T> reactivity Component already uses — no
+// new reactive primitive, and deliberately no DOM binding of its own
+// (wiring Value to a real <input> is one addEventListener call in your own
+// Render(), the same as Counter's own click handler — see Kopular's README).
+//
+// A validator is a plain (T) => string? function: null means valid, the
+// same "null means nothing to report" convention KopScript's nullable
+// types already use elsewhere. There's no array of validators — KopScript
+// has no syntax for an array of function values — so combining more than
+// one check is just an if-chain in one lambda:
+//
+//   FormField<string> name = new FormField<string>("", (string v) => {
+//     string? required = Validators.Required(v);
+//     if (required != null) { return required; }
+//     return Validators.MaxLength(v, 40);
+//   });
+class FormField<T> {
+  public state<T> Value;
+  public state<string?> Error;
+  public state<bool> Touched;
+
+  constructor(T initial, (T) => string? validate) {
+    this.Value = state(initial);
+    this.Error = state(validate(initial));
+    this.Touched = state(false);
+    this.Value.Subscribe((T v) => { this.Error.Value = validate(v); });
+  }
+
+  // Call on blur — separate from Error so a fresh, untouched field with an
+  // invalid initial value (e.g. Required on an empty string) doesn't show
+  // an error message before the user has had a chance to type anything.
+  public void Touch() {
+    this.Touched.Value = true;
+  }
+
+  public bool Valid() {
+    return this.Error.Value == null;
+  }
+}
+
+// A small set of common checks, each returning an error message or null —
+// not a validation framework, just the handful of checks almost every form
+// needs, so most fields don't have to hand-write string-length arithmetic.
+class Validators {
+  public static string? Required(string value) {
+    if (value.Trim().Length == 0) { return "Required"; }
+    return null;
+  }
+
+  public static string? MinLength(string value, number min) {
+    if (value.Length < min) { return $"Must be at least {min} characters"; }
+    return null;
+  }
+
+  public static string? MaxLength(string value, number max) {
+    if (value.Length > max) { return $"Must be at most {max} characters"; }
+    return null;
+  }
+
+  public static string? Email(string value) {
+    return match value {
+      r"^[^@\s]+@[^@\s]+\.[^@\s]+$" => null,
+      _ => "Must be a valid email"
+    };
+  }
+
+  public static string? Min(number value, number min) {
+    if (value < min) { return $"Must be at least {min}"; }
+    return null;
+  }
+
+  public static string? Max(number value, number max) {
+    if (value > max) { return $"Must be at most {max}"; }
+    return null;
+  }
+}

package/src/router.js

@@ -7,6 +7,7 @@ export class Router extends Component {
     (this.Paths = []);
     (this.Pages = []);
     (this.NotFoundPage = notFoundPage);
+    (this.Param = "");
     window.addEventListener("popstate", (e) => (this.Update()));
   }
 
@@ -21,12 +22,31 @@ export class Router extends Component {
   }
 
   Match(path) {
+    let pathSegments = path.split("/");
     let found = this.NotFoundPage;
+    let param = "";
     for (let i = 0; (i < this.Paths.length); (i = (i + 1))) {
-      if ((this.Paths[i] === path)) {
+      let patternSegments = this.Paths[i].split("/");
+      if ((patternSegments.length !== pathSegments.length)) {
+        continue;
+      }
+      let matched = true;
+      let capturedParam = "";
+      for (let j = 0; (j < patternSegments.length); (j = (j + 1))) {
+        if (patternSegments[j].startsWith(":")) {
+          (capturedParam = pathSegments[j]);
+        } else if ((patternSegments[j] !== pathSegments[j])) {
+          (matched = false);
+          break;
+        }
+      }
+      if (matched) {
         (found = this.Pages[i]);
+        (param = capturedParam);
+        break;
       }
     }
+    (this.Param = param);
     return found;
   }
 

package/src/router.ks

@@ -28,10 +28,25 @@ class Router : Component {
   private Component[] Pages;
   private Component NotFoundPage;
 
+  // The current route's dynamic segment (e.g. "42" for a "/dogs/:id" route
+  // matching "/dogs/42"), or "" if the matched route has none.
+  //
+  // A plain field, deliberately **not** state<T> — Render() below always
+  // rebuilds a fresh outlet and re-Mount()s the matched page into it on
+  // every Navigate()/popstate, which already re-runs that page's own
+  // Render() (reading the fresh Param) with no extra step. Subscribing to
+  // it, the way a page reacts to its *own* state<T>, would fire during
+  // Match() itself — before Render() has finished swapping the matched page
+  // in — which crashes the very first time a route no page has been
+  // Mount()ed into yet matches, since a not-yet-mounted Component's
+  // inherited Update() has no ParentElement to replaceChild into.
+  public string Param;
+
   constructor(Component notFoundPage) : base() {
     this.Paths = [];
     this.Pages = [];
     this.NotFoundPage = notFoundPage;
+    this.Param = "";
     // 'popstate' only fires on browser back/forward (or history.go/back/
     // forward) — never on pushState itself, unlike hashchange firing
     // whenever location.hash is set. Navigate() below calls Update()
@@ -40,6 +55,11 @@ class Router : Component {
     window.addEventListener("popstate", (Event e) => this.Update());
   }
 
+  // A path segment written ":name" (e.g. "dogs/:id") matches any single
+  // non-empty segment; every other segment must match literally. Comparing
+  // segment-by-segment (rather than the whole string at once) is what makes
+  // a static route's own matching still exactly as strict as a plain `==`
+  // was before — same segment count, same literal text throughout.
   public void AddRoute(string path, Component page) {
     this.Paths = this.Paths.Push(path);
     this.Pages = this.Pages.Push(page);
@@ -51,12 +71,31 @@ class Router : Component {
   }
 
   private Component Match(string path) {
+    string[] pathSegments = path.Split("/");
     Component found = this.NotFoundPage;
+    string param = "";
     for (number i = 0; i < this.Paths.Length; i = i + 1) {
-      if (this.Paths[i] == path) {
+      string[] patternSegments = this.Paths[i].Split("/");
+      if (patternSegments.Length != pathSegments.Length) { continue; }
+
+      bool matched = true;
+      string capturedParam = "";
+      for (number j = 0; j < patternSegments.Length; j = j + 1) {
+        if (patternSegments[j].StartsWith(":")) {
+          capturedParam = pathSegments[j];
+        } else if (patternSegments[j] != pathSegments[j]) {
+          matched = false;
+          break;
+        }
+      }
+
+      if (matched) {
         found = this.Pages[i];
+        param = capturedParam;
+        break;
       }
     }
+    this.Param = param;
     return found;
   }
 

package/src/testing.js

@@ -0,0 +1,166 @@
+// A real Kopular app can only be exercised end-to-end by actually compiling
+// its .ks sources and running the result in a DOM — there's no way to unit
+// test a Component/Router graph without one. Every test suite that's tried
+// this so far (Kopular's own, and KopularDemo's) ended up hand-rolling the
+// same ~50-line dance: a fresh temp dir per test (Node's ESM module cache
+// means re-importing the same compiled path twice never re-runs an ambient
+// extern binding's top-level code — silently binding every test after the
+// first to the first test's jsdom instance), compiling via kopscript's
+// compileGraph, binding jsdom onto globalThis for the ambient `document`/
+// `Element`/... extern declarations to find, then restoring/cleaning up.
+// This is that dance, written once.
+//
+// Hand-written plain JS, not compiled from a .ks source, the same as
+// http_runtime.js and bin/kp.mjs: filesystem/process orchestration isn't a
+// Kopular Component.
+//
+// `jsdom` is a peer dependency (optional) — only installed by a consumer
+// who actually calls this, not a weight every `kopular` install pays.
+import { JSDOM } from "jsdom";
+import { compileGraph } from "kopscript";
+import { cpSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const GLOBAL_KEYS = ["document", "Element", "Event", "location", "history", "window", "fetch"];
+const OWN_SRC_DIR = dirname(fileURLToPath(import.meta.url));
+
+// Copies every .ks/.html file from `srcDir` into `dir`, plus any filename
+// listed in `extraFiles` (e.g. http_runtime.js — a hand-written sibling a
+// compiled `using` graph needs at runtime, which the compiler wouldn't know
+// to copy on its own).
+function copySources(srcDir, dir, extraFiles) {
+  for (const name of readdirSync(srcDir)) {
+    if (name.endsWith(".ks") || name.endsWith(".html") || extraFiles.includes(name)) {
+      cpSync(join(srcDir, name), join(dir, name));
+    }
+  }
+}
+
+// kopscript's compiled output is genuine ESM (`export class ...`), which
+// Node only interprets correctly given a ".mjs" extension or an ancestor
+// package.json declaring "type": "module" — a bare os.tmpdir() has neither,
+// so the dynamic `import()` below would otherwise fail with "Cannot use
+// import statement outside a module" the moment anything outside this
+// file's own module graph (a real npm package, not code vitest/vite-node
+// itself transforms) tries to load it.
+function mkTempDir() {
+  const dir = mkdtempSync(join(tmpdir(), "kopular-testing-"));
+  writeFileSync(join(dir, "package.json"), JSON.stringify({ type: "module" }), "utf-8");
+  return dir;
+}
+
+// Copies this real, installed `kopular` package into the temp dir's own
+// node_modules — for an entry that consumes Kopular the way a separate
+// project does, through `extern ... from "kopular/..."` bare specifiers,
+// not via relative `using`. Resolved off this very file's own location, so
+// it's always the real package as installed in the *caller's*
+// node_modules, not a guess at a path.
+function copyKopularPackage(dir) {
+  mkdirSync(join(dir, "node_modules"), { recursive: true });
+  cpSync(join(OWN_SRC_DIR, ".."), join(dir, "node_modules", "kopular"), { recursive: true });
+}
+
+// Shared by both exports below: compiles `entryFileName` (already written
+// into `dir`, alongside everything it `using`s) and runs it against a fresh
+// jsdom instance.
+async function compileAndRun(dir, entryFileName, options) {
+  const entry = join(dir, entryFileName);
+  const result = compileGraph(entry);
+  if (!result.success) {
+    rmSync(dir, { recursive: true, force: true });
+    const messages = [...result.modules.values()]
+      .filter((m) => m.diagnostics.hasErrors)
+      .map((m) => m.diagnostics.format(m.source, m.absPath))
+      .join("\n\n");
+    throw new Error(messages || "Compilation failed");
+  }
+  for (const [absPath, js] of result.outputs) {
+    writeFileSync(absPath.replace(/\.ks$/, ".js"), js, "utf-8");
+  }
+
+  const dom = new JSDOM("<!doctype html><html><body></body></html>", { url: options.url ?? "http://localhost/" });
+  const g = globalThis;
+  const previous = {};
+  for (const key of GLOBAL_KEYS) previous[key] = g[key];
+  g.document = dom.window.document;
+  g.Element = dom.window.Element;
+  g.Event = dom.window.Event;
+  g.location = dom.window.location;
+  g.history = dom.window.history;
+  g.window = dom.window;
+  if (options.fetchMock) g.fetch = options.fetchMock;
+
+  let cleanedUp = false;
+  const cleanup = () => {
+    if (cleanedUp) return;
+    cleanedUp = true;
+    for (const key of GLOBAL_KEYS) g[key] = previous[key];
+    rmSync(dir, { recursive: true, force: true });
+  };
+
+  try {
+    await import(entry.replace(/\.ks$/, ".js"));
+  } catch (err) {
+    cleanup();
+    throw err;
+  }
+
+  return { window: dom.window, cleanup };
+}
+
+/**
+ * Compiles a real KopScript app — `entryFileName` plus everything else in
+ * `srcDir` it `using`s — and runs it against a fresh jsdom instance. For a
+ * real project's own src/ directory, the way KopularDemo's test suite (or
+ * any app consuming `kopular/...` via `extern`) would use it.
+ *
+ * @param {string} srcDir - directory containing the entry file and
+ *   everything it `using`s.
+ * @param {string} entryFileName - the entry .ks file's name within srcDir.
+ * @param {object} [options]
+ * @param {boolean} [options.includeKopularPackage] - copy the real
+ *   installed `kopular` package into a temp node_modules/, for an entry
+ *   that consumes Kopular via `extern ... from "kopular/..."` rather than
+ *   relative `using`. Default false.
+ * @param {string[]} [options.extraFiles] - extra filenames (not .ks/.html)
+ *   to copy from srcDir, e.g. ["http_runtime.js"].
+ * @param {(...args: unknown[]) => unknown} [options.fetchMock] - replaces
+ *   the global `fetch` for the duration of the run, for testing `Http`.
+ * @param {string} [options.url] - the jsdom document's URL. Default
+ *   "http://localhost/".
+ * @returns {Promise<{ window: import("jsdom").DOMWindow, cleanup: () => void }>}
+ *   `cleanup()` restores globals and deletes the temp dir — call it in an
+ *   `afterEach`/`finally`, always, even on a thrown error, or the next test
+ *   silently inherits this one's globals.
+ */
+export async function runKopularApp(srcDir, entryFileName, options = {}) {
+  const dir = mkTempDir();
+  copySources(srcDir, dir, options.extraFiles ?? []);
+  if (options.includeKopularPackage) copyKopularPackage(dir);
+  return compileAndRun(dir, entryFileName, options);
+}
+
+/**
+ * Like `runKopularApp`, but for a fixture written inline as a string rather
+ * than a real file on disk — for testing Kopular's *own* source files
+ * (`using "./component"`, `using "./router"`, ...) against a tiny
+ * throwaway component, the way Kopular's own test suite does. Copies
+ * Kopular's own .ks sources (resolved from this very file's own directory)
+ * alongside the fixture, so a relative `using "./dom"` in `source` resolves
+ * correctly — this only makes sense for testing Kopular itself, not for an
+ * external consumer (which would `extern ... from "kopular/..."` instead;
+ * see `runKopularApp` for that case).
+ *
+ * @param {string} source - the entry file's full KopScript source.
+ * @param {object} [options] - same as `runKopularApp`, plus:
+ * @param {string} [options.entryFileName] - default "main.ks".
+ */
+export async function runKopularFixture(source, options = {}) {
+  const dir = mkTempDir();
+  copySources(OWN_SRC_DIR, dir, options.extraFiles ?? ["http_runtime.js"]);
+  const entryFileName = options.entryFileName ?? "main.ks";
+  writeFileSync(join(dir, entryFileName), source, "utf-8");
+  return compileAndRun(dir, entryFileName, options);
+}