kopular 0.4.0 → 0.6.1

package/LLM.md

@@ -1,14 +1,17 @@
 # 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 7 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).
+(If), `kopular/http` (Http), `kopular/forms` (FormField, Validators). 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
 
@@ -44,8 +47,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
@@ -125,8 +158,23 @@ 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).
+- **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
 
@@ -173,7 +221,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`):
@@ -191,6 +240,36 @@ 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.
+
 ## 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,20 @@ 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.
+- `src/forms.ks` — `FormField<T>` and `Validators` (see "Forms" below).
+- `bin/kp.mjs` — the `kp new` scaffolding CLI (see "Starting a new project" below); the
+  one hand-written (not compiled from `.ks`) file besides `http_runtime.js`, for the same
+  reason — filesystem scaffolding isn't a Kopular `Component`.
 
-That's the whole framework — six files. Everything else (a real app built on top of it)
+That's the whole framework — seven 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 +126,41 @@ 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.
+
+**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 +251,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,11 +278,77 @@ 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
+this package's browser files and an import map pointing at it (a browser can't resolve a
+bare specifier like `"kopular/component"` the way Node's own module resolution does) — is
+boilerplate every Kopular project needs verbatim. Generate it instead of reconstructing it
+by hand (or from memory, if you're an AI agent):
+
+```bash
+npx kp new my-app
+cd my-app
+npm install
+npm start   # builds, vendors kopular's browser files, and serves at :8080
+```
+
+This scaffolds a real, working `Component` (`src/counter.ks` — the same Counter shown
+above), the ambient DOM/Kopular `extern` bindings it needs (`src/kopular_bindings.ks`),
+and a `README.md` that points an AI agent at this package's own `LLM.md` before it starts
+generating code. `kp` ships from this package (not from `kopscript`'s own `ks` CLI) since
+scaffolding a *Kopular* app is a framework concern, not a language one — `ks` stays a
+pure-language tool with no framework knowledge baked in.
+
 ## Using Kopular from another KopScript project
 
 KopScript's own `using "./path";` only resolves relative paths within a project — it has
 no package-import mechanism yet. Cross-package consumption goes through `extern`
-instead, the same way KopScript already describes any other JS/npm dependency:
+instead, the same way KopScript already describes any other JS/npm dependency
+(`kp new` above generates exactly this, if you'd rather not hand-write it):
 
 ```ks
 extern class Component {
@@ -268,6 +377,11 @@ 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).
+
 ## Getting started (developing Kopular itself)
 
 ```bash

package/bin/kp.mjs

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+// Kopular's own scaffolding CLI — separate from kopscript's `ks` (build/run/
+// watch/check), which stays a pure-language tool with no knowledge of any
+// framework built on top of it. `kp new` generates a *Kopular* app skeleton
+// (a Component, the ambient extern bindings its Render()/Mount() calls
+// need, and the vendor/serve scripts a Kopular app needs to run in a real
+// browser), so it lives here instead — in the package that actually knows
+// what a Kopular app looks like.
+//
+// Hand-written plain JS, not compiled from a .ks source, the same as
+// src/http_runtime.js: filesystem scaffolding isn't a Kopular Component, and
+// KopScript has no object-literal syntax to build the file-content map this
+// needs anyway.
+import { writeFileSync, mkdirSync, existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const kopularPkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf-8"));
+// Read the ranges to generate from Kopular's own package.json rather than
+// hardcoding them a second time here — this file only has to change when the
+// *shape* of a scaffolded project changes, not on every kopular/kopscript release.
+const KOPULAR_RANGE = `^${kopularPkg.version}`;
+const KOPSCRIPT_RANGE = kopularPkg.devDependencies.kopscript;
+
+function packageJsonTemplate(name) {
+  return `{
+  "name": "${name}",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "build": "ks build src/app.ks && npm run vendor",
+    "vendor": "node scripts/vendor-kopular.mjs",
+    "serve": "node scripts/serve.mjs . 8080",
+    "start": "npm run build && npm run serve"
+  },
+  "dependencies": {
+    "kopular": "${KOPULAR_RANGE}"
+  },
+  "devDependencies": {
+    "kopscript": "${KOPSCRIPT_RANGE}"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}
+`;
+}
+
+const INDEX_HTML_TEMPLATE = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Kopular app</title>
+  </head>
+  <body>
+    <!--
+      Compiled output imports Kopular's classes as bare specifiers
+      ("kopular/component", "kopular/router") — real Node module resolution
+      understands that natively via node_modules, but a browser needs an
+      explicit import map, since "kopular/component" isn't a URL on its own.
+      This points at vendor/kopular/ (see scripts/vendor-kopular.mjs), not
+      node_modules/kopular/src/ directly, so the browser never has to be
+      served the whole node_modules tree just to reach two files inside it.
+    -->
+    <script type="importmap">
+      {
+        "imports": {
+          "kopular/component": "/vendor/kopular/component.js",
+          "kopular/router": "/vendor/kopular/router.js"
+        }
+      }
+    </script>
+    <script type="module" src="/src/app.js"></script>
+  </body>
+</html>
+`;
+
+const GITIGNORE_TEMPLATE = `node_modules/
+*.js
+/vendor/
+.DS_Store
+`;
+
+function readmeTemplate(name) {
+  return `# ${name}
+
+A [KopScript](https://www.npmjs.com/package/kopscript) + [Kopular](https://www.npmjs.com/package/kopular) app, scaffolded with \`kp new\`.
+
+## Commands
+
+- \`npm install\`
+- \`npm run build\` — compiles \`src/*.ks\` to JS and vendors Kopular's browser files into \`vendor/\`
+- \`npm run serve\` — serves the app at http://localhost:8080/
+- \`npm start\` — both of the above
+
+## Where to go next
+
+- \`src/counter.ks\` is a real, working Kopular \`Component\` — start there.
+- \`src/kopular_bindings.ks\` declares the ambient DOM and Kopular types this project builds on (see the comments inside it for why these have to be redeclared per-project rather than imported).
+- For routing, dependency injection ("Pure DI" / a composition root), structural directives, or the \`Http\` client, see Kopular's own README and \`node_modules/kopular/LLM.md\`.
+- For the full language reference, see \`node_modules/kopscript/LLM.md\`.
+
+**Working with an AI agent on this project?** Point it at \`node_modules/kopscript/LLM.md\` and \`node_modules/kopular/LLM.md\` first — they're dense, example-verified references written specifically to be loaded as context, not narrative docs.
+`;
+}
+
+const SERVE_MJS_TEMPLATE = `#!/usr/bin/env node
+// Minimal static file server for previewing the compiled app in a real
+// browser. Kept dependency-free on purpose — browsers won't load ES module
+// imports over file://, so anything with \`using\`/\`extern\`-based imports
+// needs to be served over http to actually run.
+import { createServer } from "node:http";
+import { readFile } from "node:fs/promises";
+import { extname, join, resolve } from "node:path";
+
+const root = resolve(process.argv[2] ?? ".");
+const port = Number(process.argv[3] ?? 8080);
+
+const MIME_TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+};
+
+const server = createServer(async (req, res) => {
+  try {
+    let pathname = decodeURIComponent(new URL(req.url, "http://localhost").pathname);
+    if (pathname === "/") pathname = "/index.html";
+    let filePath = join(root, pathname);
+    if (!filePath.startsWith(root)) {
+      res.writeHead(403).end("Forbidden");
+      return;
+    }
+
+    let data;
+    try {
+      data = await readFile(filePath);
+    } catch (err) {
+      // SPA fallback: a path with no file extension is a client-side route
+      // Router would handle once the page loads, not a missing asset — serve
+      // the app shell instead of 404ing. A path that *does* have an
+      // extension (a genuinely missing .js/.css/...) still 404s normally.
+      if (extname(pathname)) throw err;
+      filePath = join(root, "index.html");
+      data = await readFile(filePath);
+    }
+
+    res.writeHead(200, { "Content-Type": MIME_TYPES[extname(filePath)] ?? "application/octet-stream" });
+    res.end(data);
+  } catch {
+    res.writeHead(404).end("Not found");
+  }
+});
+
+server.listen(port, () => {
+  console.log(\`Serving \${root} at http://localhost:\${port}/\`);
+});
+`;
+
+const VENDOR_KOPULAR_MJS_TEMPLATE = `#!/usr/bin/env node
+// Copies the Kopular files the browser actually needs out of node_modules
+// into a small local vendor/ directory — the import map in index.html points
+// here instead of into node_modules directly, since shipping (or even
+// locally serving) the whole node_modules tree just to get a few files out
+// of it is unnecessary.
+//
+// dom.js isn't in the import map itself, but component.js and router.js each
+// import it internally via a relative "./dom.js" — Kopular's own compiled
+// files reference each other as siblings, so all three have to land in the
+// same vendor/kopular/ directory together, not just the two the import map
+// names explicitly.
+import { copyFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const outDir = join(root, "vendor", "kopular");
+mkdirSync(outDir, { recursive: true });
+
+for (const file of ["dom.js", "component.js", "router.js"]) {
+  copyFileSync(join(root, "node_modules", "kopular", "src", file), join(outDir, file));
+}
+
+console.log(\`Vendored kopular/{dom,component,router}.js into \${outDir}\`);
+`;
+
+// Ambient DOM bindings, plus Kopular's own classes redeclared as `extern` —
+// copied verbatim from a real project's working copy. `using` only resolves
+// relative paths within a project (KopScript has no package-import mechanism
+// yet), so it can't reach across the node_modules boundary into Kopular's
+// own .ks sources — every consuming project redeclares this ambient surface
+// once, here.
+const KOPULAR_BINDINGS_KS_TEMPLATE = `// Ambient DOM bindings — describing standing browser globals, not anything
+// Kopular itself exports, so this is just describing the platform.
+extern class Event {
+  Element target { get; }
+  void preventDefault();
+};
+
+extern class Element {
+  string textContent { get; set; }
+  string innerHTML { get; set; }
+  string id { get; set; }
+  string className { get; set; }
+  string href { get; set; }
+  string src { get; set; }
+  string alt { get; set; }
+  void appendChild(Element child);
+  void replaceChild(Element newChild, Element oldChild);
+  void addEventListener(string eventType, (Event) => void handler);
+  void removeEventListener(string eventType, (Event) => void handler);
+  Element querySelector(string selector);
+};
+
+extern class Document {
+  Element createElement(string tagName);
+  Element getElementById(string id);
+  Element body { get; }
+};
+
+extern Document document;
+
+// Kopular's real classes, consumed from the real published "kopular" npm
+// package. \`virtual\` on Render() is what lets a class here \`override\` it.
+extern class Component {
+  constructor();
+  virtual Element Render();
+  void Mount(Element parent);
+  void Update();
+} from "kopular/component";
+
+extern class Router {
+  constructor(Component notFoundPage);
+  void AddRoute(string path, Component page);
+  void Navigate(string path);
+  void Mount(Element parent);
+} from "kopular/router";
+`;
+
+// The same Counter shown in Kopular's own README/LLM.md — real, verified
+// example code, not a placeholder.
+const COUNTER_KS_TEMPLATE = `using "./kopular_bindings";
+
+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;
+    });
+    return button;
+  }
+}
+`;
+
+const APP_KS_TEMPLATE = `using "./kopular_bindings";
+using "./counter";
+
+// The app's root: mounts straight to document.body since there's nothing
+// else in the shell yet. Add a Router and a composition root (see Kopular's
+// README on "Pure DI") once there's more than one page.
+Counter app = new Counter();
+app.Mount(document.body);
+`;
+
+function scaffoldProject(dirPath) {
+  const name = basename(dirPath);
+  if (existsSync(dirPath) && readdirSync(dirPath).length > 0) {
+    console.error(`kp: '${dirPath}' already exists and is not empty`);
+    process.exitCode = 1;
+    return;
+  }
+
+  mkdirSync(join(dirPath, "src"), { recursive: true });
+  mkdirSync(join(dirPath, "scripts"), { recursive: true });
+
+  writeFileSync(join(dirPath, "package.json"), packageJsonTemplate(name), "utf-8");
+  writeFileSync(join(dirPath, "index.html"), INDEX_HTML_TEMPLATE, "utf-8");
+  writeFileSync(join(dirPath, ".gitignore"), GITIGNORE_TEMPLATE, "utf-8");
+  writeFileSync(join(dirPath, "README.md"), readmeTemplate(name), "utf-8");
+  writeFileSync(join(dirPath, "scripts", "serve.mjs"), SERVE_MJS_TEMPLATE, "utf-8");
+  writeFileSync(join(dirPath, "scripts", "vendor-kopular.mjs"), VENDOR_KOPULAR_MJS_TEMPLATE, "utf-8");
+  writeFileSync(join(dirPath, "src", "kopular_bindings.ks"), KOPULAR_BINDINGS_KS_TEMPLATE, "utf-8");
+  writeFileSync(join(dirPath, "src", "counter.ks"), COUNTER_KS_TEMPLATE, "utf-8");
+  writeFileSync(join(dirPath, "src", "app.ks"), APP_KS_TEMPLATE, "utf-8");
+
+  console.log(`Created ${name} in ${dirPath}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  cd ${name}`);
+  console.log("  npm install");
+  console.log("  npm start");
+}
+
+function main() {
+  const [command, dir] = process.argv.slice(2);
+  if (command !== "new" || !dir) {
+    console.error("Usage: kp new <project-directory>");
+    process.exitCode = 1;
+    return;
+  }
+  scaffoldProject(resolve(dir));
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.4.0",
+  "version": "0.6.1",
   "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",
@@ -16,27 +16,32 @@
     "ui"
   ],
   "main": "./src/component.js",
+  "bin": {
+    "kp": "./bin/kp.mjs"
+  },
   "exports": {
     ".": "./src/component.js",
     "./component": "./src/component.js",
     "./router": "./src/router.js",
     "./dom": "./src/dom.js",
     "./directives": "./src/directives.js",
-    "./http": "./src/http.js"
+    "./http": "./src/http.js",
+    "./forms": "./src/forms.js"
   },
   "files": [
     "src",
+    "bin",
     "assets",
     "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"
   },
   "devDependencies": {
-    "kopscript": "^0.3.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;
+  }
+}