kopular 0.13.0 → 0.14.1

package/README.md

@@ -2,7 +2,7 @@
 
 # Kopular
 
-Kopular is a small component framework for [KopScript](https://dev.azure.com/koppinator/Koppindependence/_git/Kop),
+Kopular is a small component framework for [KopScript](https://dev.azure.com/koppinator/Koppindependence/_git/KopScript),
 built to give Angular's separation of concerns — components own UI, services own logic,
 a router owns navigation — without Angular's steepest learning-curve pieces: no RxJS, no
 dependency-injection container, and templates that are real, compiled, type-checked
@@ -13,12 +13,14 @@ Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./
 
 ## Highlights
 
-- **`Component`**: a base class with `virtual Render()` (builds a fresh DOM subtree from
-  current state) and `Update()` (swaps the old subtree for the new one). No diffing either
-  way — `Render()` is provided as a real, separate markup file compiled by KopScript's
-  `template from` (see "Templates" below), or written by hand as plain imperative DOM
-  code against plain DOM bindings, the way you'd write careful vanilla-JS UI code — your
-  choice, and both compile to the exact same thing. An optional `virtual
+- **`Component`, with real vdom diffing**: a base class with `virtual Render()` (describes
+  the current state as a `VElement` tree — a lightweight description of a DOM element, not
+  a real one) and `Update()` (diffs the new tree against the previous one and patches only
+  what changed, reusing a real DOM node wherever its tag stays the same — not a full
+  subtree rebuild). `Render()` is provided as a real, separate markup file compiled by
+  KopScript's `template from` (see "Templates" below), or written by hand building a
+  `VElement` tree against `kopular/velement`, the way you'd write careful vanilla-JS UI
+  code — your choice, and both compile to the exact same thing. An optional `virtual
   RenderError(message)` renders a fallback instead of a hard crash if `Render()` throws —
   purely additive; not overriding it keeps today's exact (uncaught) behavior.
 - **Templates, compiled and type-checked, not interpreted**: markup lives in its own
@@ -28,7 +30,7 @@ Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./
   automatic `Subscribe`/`Update()` wiring for `state<T>` fields referenced directly in the
   markup. See "Templates" below.
 - **Reactive state, no RxJS**: components hold `state<number>`/`state<string>`/... (a
-  KopScript language feature — see the [Kop](https://dev.azure.com/koppinator/Koppindependence/_git/Kop)
+  KopScript language feature — see the [KopScript](https://dev.azure.com/koppinator/Koppindependence/_git/KopScript)
   repo) and subscribe once, in their constructor, to call `Update()` on change. No
   Observables, no operators, no manual unsubscribe bookkeeping.
 - **Services, no DI container**: "injecting" a service is just passing it as a
@@ -55,6 +57,10 @@ Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./
 
 - `src/dom.ks` — ambient DOM bindings (`document`, `Element`, `Event`, `window`,
   `location`) that `component.ks`/`router.ks`/`directives.ks` are built on.
+- `src/velement.ks` — `VElement`, the lightweight description of a DOM element `Render()`
+  returns.
+- `src/vdom.ks` — the diff/patch engine (`Materialize`/`Patch`/`PatchChildren`) behind real
+  vdom diffing — see "Component" above.
 - `src/component.ks` — the `Component` base class.
 - `src/router.ks` — the `Router`.
 - `src/directives.ks` — `If()`, the structural-directive equivalents' one genuinely new
@@ -69,7 +75,7 @@ Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./
 - `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
+That's the whole framework — ten 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).
 
@@ -77,12 +83,12 @@ lives in a separate consumer repo, [KopularDemo](https://dev.azure.com/koppinato
 
 A component's `Render()` can be a real markup file instead of hand-written imperative DOM
 code — `template from "./x.html";` in the class body, a KopScript language feature (see
-[Kop](https://dev.azure.com/koppinator/Koppindependence/_git/Kop)'s own README/LLM.md for
+[KopScript](https://dev.azure.com/koppinator/Koppindependence/_git/KopScript)'s own README/LLM.md for
 the full syntax reference). Kopular itself needed **zero framework code changes** for
 this — the compiler desugars a template straight into calls against the same
-`document.createElement`/`.appendChild`/`.textContent`/`.addEventListener` surface
-`dom.ks` already declares, so a template-generated `Render()` is indistinguishable from
-one you'd write by hand:
+`VElement.Create`/`.AppendChild`/`.TextContent`/named event fields `velement.ks` already
+declares, so a template-generated `Render()` is indistinguishable from one you'd write by
+hand:
 
 ```ks
 // counter.ks
@@ -112,12 +118,12 @@ class Counter : Component {
     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) => {
+  public override VElement Render() {
+    VElement button = VElement.Create("button");
+    button.TextContent = "Count: " + this.Count.Value;
+    button.OnClick = (Event e) => {
       this.Count.Value = this.Count.Value + 1;
-    });
+    };
     return button;
   }
 }
@@ -137,7 +143,7 @@ still has one manual `Subscribe`. `*if`/`*for` in a template are covered under
 
 Kopular has no injector because KopScript has nothing for one to hook into — no
 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
+classes/interfaces only — see the KopScript 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
@@ -172,10 +178,17 @@ class RoutedApp : Component {
     this.Nav = services.Nav;
   }
 
-  public override Element Render() {
-    Element container = document.createElement("div");
-    this.Nav.Mount(container);
-    return container;
+  public override VElement Render() {
+    return VElement.Create("div");
+  }
+
+  // Mounting the Router — a live, nested Component — isn't something a
+  // VElement tree can express as data (see "Component" above). AfterRender
+  // is called with the real DOM node Render()'s tree just became, once
+  // Mount()/Update() has actually materialized/patched it — here, that's
+  // the container itself.
+  protected override void AfterRender(Element root) {
+    this.Nav.Mount(root);
   }
 }
 
@@ -223,13 +236,13 @@ single non-empty segment. With just one per route, its value is captured into
 ```ks
 nav.AddRoute("/dogs/:id", new DogPage(nav));
 // inside DogPage.Render():
-el.textContent = "Dog #" + this.Nav.Param;
+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.
+`Param` is a plain `string`, deliberately not `state<T>` — Router's own `AfterRender`
+already re-`Mount()`s the matched page into its outlet on every `Navigate()`/`popstate`,
+which re-runs that page's `Render()` (reading the fresh `Param`) with no extra step. No
+`Subscribe()` needed on it.
 
 **More than one dynamic segment**, and a trailing **wildcard** segment, both work too —
 read each by name via `Router.Params(name)` instead (`Param` above still holds the
@@ -238,7 +251,7 @@ read each by name via `Router.Params(name)` instead (`Param` above still holds t
 ```ks
 nav.AddRoute("/dogs/:id/toys/:toyId", new ToyPage(nav));
 // inside ToyPage.Render():
-el.textContent = "Dog " + this.Nav.Params("id") + " / Toy " + this.Nav.Params("toyId");
+el.TextContent = "Dog " + this.Nav.Params("id") + " / Toy " + this.Nav.Params("toyId");
 
 nav.AddRoute("/files/*", new FilesPage(nav));
 // "/files/2026/reports/q1.pdf" -> Params("*") == "2026/reports/q1.pdf"
@@ -317,7 +330,7 @@ template's `*if`/`*for` need no further explanation, they're covered under "Temp
 to get a conditional value out of it. `If()` is that helper — nothing more than:
 
 ```ks
-Element If(bool condition, () => Element whenTrue, () => Element whenFalse) {
+VElement If(bool condition, () => VElement whenTrue, () => VElement whenFalse) {
   if (condition) {
     return whenTrue();
   }
@@ -328,26 +341,26 @@ Element If(bool condition, () => Element whenTrue, () => Element whenFalse) {
 Both branches are required (same reasoning `Router` uses for requiring a `NotFoundPage`
 up front — see `router.ks`): v1 has no nullable types, so "render nothing" has no value
 to hand back. Only the branch actually taken runs — the other lambda is never called, so
-an explicit empty branch (`() => document.createElement("span")`) costs nothing when
-there's genuinely nothing to show.
+an explicit empty branch (`() => VElement.Create("span")`) costs nothing when there's
+genuinely nothing to show.
 
 All three read the same way, right inside a hand-written `Render()` — no directive
 registration, nothing to import beyond the function itself:
 
 ```ks
-public override Element Render() {
-  Element root = document.createElement("div");
+public override VElement Render() {
+  VElement root = VElement.Create("div");
 
   // *ngIf
-  root.appendChild(If(this.User.IsLoggedIn, () => this.BuildProfile(), () => this.BuildLoginButton()));
+  root.AppendChild(If(this.User.IsLoggedIn, () => this.BuildProfile(), () => this.BuildLoginButton()));
 
   // *ngFor
-  Element list = document.createElement("ul");
-  this.Items.ForEach((Item item) => { list.appendChild(this.BuildItemRow(item)); });
-  root.appendChild(list);
+  VElement list = VElement.Create("ul");
+  this.Items.ForEach((Item item) => { list.AppendChild(this.BuildItemRow(item)); });
+  root.AppendChild(list);
 
   // *ngSwitch
-  root.appendChild(match this.Status {
+  root.AppendChild(match this.Status {
     "loading" => this.BuildSpinner(),
     "error" => this.BuildError(),
     _ => this.BuildContent()
@@ -357,12 +370,12 @@ public override Element Render() {
 }
 ```
 
-Why not a general reuse-existing-DOM-nodes diffing layer, the way `*ngFor trackBy`
-avoids rebuilding unchanged rows? That needs comparing old and new *data* items by a
-caller-supplied key, generic over the item type — and KopScript has no generics (no
-`class Foo<T>`, no `T Resolve<T>()`). A one-off keyed-diff helper could be hand-written
-per list, but that's real vdom-diffing work — already called out as out of scope in
-"Status" below, and not something these three lines take on.
+Give each `Item`'s `VElement` a stable `.Id` (e.g. the item's own id) to make `*ngFor
+trackBy`-style row reuse automatic — `Update()`'s diff engine matches children by `Id`
+across a re-render, reusing a matched child's real DOM node (and anything stateful
+attached to it, like focus) rather than rebuilding it, the same way `*ngFor`'s own
+`trackBy` avoids rebuilding unchanged rows. Without a stable `Id`, a list still renders
+correctly on reorder, but a given item's real node isn't guaranteed to follow its data.
 
 ## HTTP
 
@@ -430,10 +443,11 @@ 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(); });
+// inside a hand-written Render(), building emailInput as a VElement:
+emailInput.OnInput = (Event e) => {
+  email.Value.Value = e.target.value;   // revalidates automatically
+};
+emailInput.OnBlur = (Event e) => { email.Touch(); };
 ```
 
 `FormField<T>` holds one input's value, error, and touched state as three ordinary
@@ -458,16 +472,18 @@ FormField<string> email = new FormField<string>("",
 
 Free functions, not `Validators` methods, and fixed-arity (2 and 3) rather than a general
 `Validators.All(...)` — a class's own static method can't introduce a new type parameter
-beyond the class's own (see "Generics" in `Kop`'s own docs), so a *generic* combinator has
+beyond the class's own (see "Generics" in `KopScript`'s own docs), so a *generic* combinator has
 to live as a free function instead. `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.
+**No two-way data binding** — wiring `Value` to a real `<input>` is the `OnInput`
+assignment shown above, the same manual pattern `Counter` already uses for its click
+handler (`VElement.Value` itself is one-way, host-to-DOM only — reading the *current* DOM
+value back out is always the real event's `e.target.value`, not something Kopular
+mirrors into `Value` for you). 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`
 
@@ -499,9 +515,14 @@ 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 VElement {
+  static VElement Create(string tag);
+  string TextContent { get; set; }
+} from "kopular/velement";
+
 extern class Component {
   constructor();
-  virtual Element Render();
+  virtual VElement Render();
   void Mount(Element parent);
 } from "kopular/component";
 
@@ -512,9 +533,9 @@ extern class Router {
 } from "kopular/router";
 
 class MyWidget : Component {
-  public override Element Render() {
-    Element el = document.createElement("div");
-    el.textContent = "Hello from MyWidget";
+  public override VElement Render() {
+    VElement el = VElement.Create("div");
+    el.TextContent = "Hello from MyWidget";
     return el;
   }
 }
@@ -568,16 +589,22 @@ npm run build # compiles src/*.ks -> src/*.js (compiled output is gitignored)
 npm test      # runs test/kopular.test.ts against a real DOM via jsdom
 ```
 
-`kopscript` is a real published dependency (`^0.1.0`) — this repo doesn't need Kop
+`kopscript` is a real published dependency (`^0.1.0`) — this repo doesn't need KopScript
 checked out as a sibling directory or anything else local to build or test.
 
 ## Status
 
-v1 / hobby-project scope, same as KopScript itself. Known limitation: `Component` only
-handles a single component's own re-render cycle — if a *parent* re-renders while it has
-mounted children, those children aren't automatically re-mounted into the parent's new
-tree (real reconciliation, the way React/Vue handle this, is real vdom-diffing work well
-beyond v1). Compose independent components into stable slots (see `Router`'s own pattern
-of keeping page instances alive rather than rebuilding them) to avoid the issue.
-`Update()` called before `Mount()` is a safe no-op — see `LLM.md`'s `Component` section
-for exactly when that happens (sibling pages sharing one injected service's `state<T>`).
+v1 / hobby-project scope, same as KopScript itself. `Update()` now diffs and patches
+real DOM (see "Component" above) rather than replacing a whole subtree on every
+re-render — but reconciliation is still per-`Component`, not across nested ones: if a
+*parent* Component's own `Render()` output changes shape around a slot where a *nested*
+Component was imperatively `Mount()`ed (via `AfterRender` — see `Router`'s own pattern),
+that nested Component isn't automatically re-`Mount()`ed or torn down as part of the
+parent's diff, since a live mounted child isn't something a `VElement` tree can express
+as data. Composing independent components into a stable, unchanging slot — the way every
+real use of `AfterRender` in this codebase already does, `Router`'s own outlet included —
+avoids the issue entirely. A list child without a stable `VElement.Id` similarly still
+renders correctly across a reorder, but isn't guaranteed to keep the same real DOM node
+(see "Structural directives" above). `Update()` called before `Mount()` is a safe no-op
+— see `LLM.md`'s `Component` section for exactly when that happens (sibling pages
+sharing one injected service's `state<T>`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Kopular: a small component framework for KopScript — components, reactive state, constructor-injected services, routing, real compiled templates, and HTTP, with no DI container",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,7 @@
     "./component": "./src/component.js",
     "./router": "./src/router.js",
     "./dom": "./src/dom.js",
+    "./velement": "./src/velement.js",
     "./directives": "./src/directives.js",
     "./http": "./src/http.js",
     "./forms": "./src/forms.js",

package/src/component.js

@@ -1,4 +1,6 @@
 import { Event, Element, Document, Location, History, Window, document, location, history, window } from "./dom.js";
+import { VElement } from "./velement.js";
+import { Materialize, Patch, PatchChildren } from "./vdom.js";
 
 export class Component {
   constructor() {
@@ -6,7 +8,7 @@ export class Component {
   }
 
   Render() {
-    return document.createElement("div");
+    return VElement.Create("div");
   }
 
   RenderError(message) {
@@ -21,20 +23,26 @@ export class Component {
     }
   }
 
+  AfterRender(root) {
+  }
+
   Mount(parent) {
     this.ParentElement = parent;
-    this.Root = this.SafeRender();
-    parent.appendChild(this.Root);
+    this.Tree = this.SafeRender();
+    let root = Materialize(this.Tree);
+    parent.appendChild(root);
     this.IsMounted = true;
+    this.AfterRender(root);
   }
 
   Update() {
     if (!this.IsMounted) {
       return;
     }
-    let newRoot = this.SafeRender();
-    this.ParentElement.replaceChild(newRoot, this.Root);
-    this.Root = newRoot;
+    let newTree = this.SafeRender();
+    let root = Patch(this.ParentElement, this.Tree, newTree);
+    this.Tree = newTree;
+    this.AfterRender(root);
   }
 }
 

package/src/component.js.map

@@ -1 +1 @@
-{"version":3,"file":"component.js","sources":["component.ks"],"sourcesContent":["using \"./dom\";\n\n// A minimal component base: subclasses override Render() to imperatively\n// build a fresh DOM tree from current state, and call the inherited\n// Update() whenever that state changes to swap the old tree for a new one.\n// There is deliberately no template language or diffing here — Render()\n// rebuilds its whole subtree every time, the simplest thing that works.\n//\n// Known limitation: if a *parent* component's own Render() re-runs (i.e.\n// something calls Update() on the parent) while it has mounted children,\n// those children are not automatically re-mounted into the parent's new\n// tree — this base class only handles a single component's own re-render\n// cycle, not parent/child reconciliation across one. Composing independent\n// components (each mounted into its own stable slot, as in app.kop) avoids\n// the issue entirely.\nclass Component {\n  protected Element Root;\n  private Element ParentElement;\n  // Set true only once Mount() actually runs. A page Component is commonly\n  // constructed eagerly (e.g. Router.AddRoute takes an already-built\n  // instance — see Router's own header comment) long before it's ever\n  // Mount()ed, and two sibling pages sharing one injected service's\n  // state<T> (Pure DI — both Subscribe() the same field) both get notified\n  // on any change regardless of which one is actually the currently-routed,\n  // mounted page. Update() guards on this so that notification is a safe\n  // no-op for the unmounted one, instead of a crash (see Update() below).\n  private bool IsMounted;\n\n  constructor() {\n    this.IsMounted = false;\n  }\n\n  public virtual Element Render() {\n    return document.createElement(\"div\");\n  }\n\n  // Overridden to render a fallback UI when Render() throws — a page bug,\n  // an unhandled rejected Http call, anything — instead of leaving\n  // Mount()/Update() to propagate the exception uncaught, which would\n  // otherwise crash whatever triggered the render (a click handler, a\n  // Router navigation) with nothing shown to the user at all. Default just\n  // re-throws, so anything that doesn't override this keeps today's exact\n  // behavior — this is purely additive, opt-in error recovery, not a\n  // behavior change for existing components.\n  protected virtual Element RenderError(string message) {\n    throw message;\n  }\n\n  private Element SafeRender() {\n    try {\n      return this.Render();\n    } catch (string message) {\n      return this.RenderError(message);\n    }\n  }\n\n  public void Mount(Element parent) {\n    this.ParentElement = parent;\n    this.Root = this.SafeRender();\n    parent.appendChild(this.Root);\n    this.IsMounted = true;\n  }\n\n  // A no-op, not an error, when called before Mount() — see the class-level\n  // comment on IsMounted for exactly when this happens for real (a\n  // shared-service state change reaching a sibling page that isn't the one\n  // currently routed/mounted). Nothing is lost: SafeRender() would only be\n  // thrown away unread since there's no live DOM parent to put it in, and\n  // Mount() itself always calls SafeRender() fresh whenever this component\n  // does become the routed page, picking up whatever the current state is\n  // at that point.\n  protected void Update() {\n    if (!this.IsMounted) {\n      return;\n    }\n    Element newRoot = this.SafeRender();\n    this.ParentElement.replaceChild(newRoot, this.Root);\n    this.Root = newRoot;\n  }\n}\n"],"names":[],"mappings":";;AAeA;EAaE;IACiB;;;EAGF;IACb;;;EAWgB;IAChB;;;EAGM;IACN;MACE;;MAEA;;;;EAIG;IACc;IACT;IACQ;IACH;;;EAWP;IACR;MACE;;IAEF;IAC+B;IACrB"}
+{"version":3,"file":"component.js","sources":["component.ks"],"sourcesContent":["using \"./dom\";\nusing \"./velement\";\nusing \"./vdom\";\n\n// A minimal component base: subclasses override Render() to build a\n// VElement tree describing the current state, and call the inherited\n// Update() whenever that state changes to re-render. Update() DIFFS the\n// new VElement tree against the previous one (see vdom.ks's Patch) and\n// patches only what changed, reusing real DOM nodes wherever their tag\n// stays the same — replacing a whole subtree is now the exception (a\n// changed tag, or no previous tree at all), not the default on every\n// re-render the way it used to be.\n//\n// Known limitation: if a *parent* component's own Render() re-runs (i.e.\n// something calls Update() on the parent) while it has mounted children,\n// those children are not automatically re-mounted into the parent's new\n// tree — this base class only handles a single component's own re-render\n// cycle, not parent/child reconciliation across one. Composing independent\n// components (each mounted into its own stable slot, as in app.kop) avoids\n// the issue entirely.\nclass Component {\n  protected VElement Tree;\n  private Element ParentElement;\n  // Set true only once Mount() actually runs. A page Component is commonly\n  // constructed eagerly (e.g. Router.AddRoute takes an already-built\n  // instance — see Router's own header comment) long before it's ever\n  // Mount()ed, and two sibling pages sharing one injected service's\n  // state<T> (Pure DI — both Subscribe() the same field) both get notified\n  // on any change regardless of which one is actually the currently-routed,\n  // mounted page. Update() guards on this so that notification is a safe\n  // no-op for the unmounted one, instead of a crash (see Update() below).\n  private bool IsMounted;\n\n  constructor() {\n    this.IsMounted = false;\n  }\n\n  public virtual VElement Render() {\n    return VElement.Create(\"div\");\n  }\n\n  // Overridden to render a fallback UI when Render() throws — a page bug,\n  // an unhandled rejected Http call, anything — instead of leaving\n  // Mount()/Update() to propagate the exception uncaught, which would\n  // otherwise crash whatever triggered the render (a click handler, a\n  // Router navigation) with nothing shown to the user at all. Default just\n  // re-throws, so anything that doesn't override this keeps today's exact\n  // behavior — this is purely additive, opt-in error recovery, not a\n  // behavior change for existing components.\n  protected virtual VElement RenderError(string message) {\n    throw message;\n  }\n\n  private VElement SafeRender() {\n    try {\n      return this.Render();\n    } catch (string message) {\n      return this.RenderError(message);\n    }\n  }\n\n  // Called after Mount()/Update() has materialized/patched this\n  // component's own VElement tree into `root` — a hook for a component\n  // that needs to do additional, imperative work against its OWN\n  // now-real root element once it exists. Default is a no-op, so every\n  // component that doesn't need this is unaffected. Router is the one\n  // real user of this today: mounting/re-mounting its matched child PAGE\n  // into the outlet div its own Render() just describes, since a nested\n  // Component's own mount lifecycle isn't something a VElement tree can\n  // express as data (see the class comment above on parent/child\n  // reconciliation being a known, deliberately out-of-scope limitation —\n  // this hook is the documented way around it, not a fix to it).\n  protected virtual void AfterRender(Element root) {\n  }\n\n  public void Mount(Element parent) {\n    this.ParentElement = parent;\n    this.Tree = this.SafeRender();\n    Element root = Materialize(this.Tree);\n    parent.appendChild(root);\n    this.IsMounted = true;\n    this.AfterRender(root);\n  }\n\n  // A no-op, not an error, when called before Mount() — see the class-level\n  // comment on IsMounted for exactly when this happens for real (a\n  // shared-service state change reaching a sibling page that isn't the one\n  // currently routed/mounted). Nothing is lost: SafeRender() would only be\n  // thrown away unread since there's no live DOM parent to put it in, and\n  // Mount() itself always calls SafeRender() fresh whenever this component\n  // does become the routed page, picking up whatever the current state is\n  // at that point.\n  protected void Update() {\n    if (!this.IsMounted) {\n      return;\n    }\n    VElement newTree = this.SafeRender();\n    Element root = Patch(this.ParentElement, this.Tree, newTree);\n    this.Tree = newTree;\n    this.AfterRender(root);\n  }\n}\n"],"names":[],"mappings":";;;;AAoBA;EAaE;IACiB;;;EAGF;IACb;;;EAWgB;IAChB;;;EAGM;IACN;MACE;;MAEA;;;;EAec;;;EAGX;IACc;IACT;IACV;IACkB;IACH;IACC;;;EAWR;IACR;MACE;;IAEF;IACA;IACU;IACM"}

package/src/component.ks

@@ -1,10 +1,15 @@
 using "./dom";
+using "./velement";
+using "./vdom";
 
-// A minimal component base: subclasses override Render() to imperatively
-// build a fresh DOM tree from current state, and call the inherited
-// Update() whenever that state changes to swap the old tree for a new one.
-// There is deliberately no template language or diffing here — Render()
-// rebuilds its whole subtree every time, the simplest thing that works.
+// A minimal component base: subclasses override Render() to build a
+// VElement tree describing the current state, and call the inherited
+// Update() whenever that state changes to re-render. Update() DIFFS the
+// new VElement tree against the previous one (see vdom.ks's Patch) and
+// patches only what changed, reusing real DOM nodes wherever their tag
+// stays the same — replacing a whole subtree is now the exception (a
+// changed tag, or no previous tree at all), not the default on every
+// re-render the way it used to be.
 //
 // Known limitation: if a *parent* component's own Render() re-runs (i.e.
 // something calls Update() on the parent) while it has mounted children,
@@ -14,7 +19,7 @@ using "./dom";
 // components (each mounted into its own stable slot, as in app.kop) avoids
 // the issue entirely.
 class Component {
-  protected Element Root;
+  protected VElement Tree;
   private Element ParentElement;
   // Set true only once Mount() actually runs. A page Component is commonly
   // constructed eagerly (e.g. Router.AddRoute takes an already-built
@@ -30,8 +35,8 @@ class Component {
     this.IsMounted = false;
   }
 
-  public virtual Element Render() {
-    return document.createElement("div");
+  public virtual VElement Render() {
+    return VElement.Create("div");
   }
 
   // Overridden to render a fallback UI when Render() throws — a page bug,
@@ -42,11 +47,11 @@ class Component {
   // re-throws, so anything that doesn't override this keeps today's exact
   // behavior — this is purely additive, opt-in error recovery, not a
   // behavior change for existing components.
-  protected virtual Element RenderError(string message) {
+  protected virtual VElement RenderError(string message) {
     throw message;
   }
 
-  private Element SafeRender() {
+  private VElement SafeRender() {
     try {
       return this.Render();
     } catch (string message) {
@@ -54,11 +59,27 @@ class Component {
     }
   }
 
+  // Called after Mount()/Update() has materialized/patched this
+  // component's own VElement tree into `root` — a hook for a component
+  // that needs to do additional, imperative work against its OWN
+  // now-real root element once it exists. Default is a no-op, so every
+  // component that doesn't need this is unaffected. Router is the one
+  // real user of this today: mounting/re-mounting its matched child PAGE
+  // into the outlet div its own Render() just describes, since a nested
+  // Component's own mount lifecycle isn't something a VElement tree can
+  // express as data (see the class comment above on parent/child
+  // reconciliation being a known, deliberately out-of-scope limitation —
+  // this hook is the documented way around it, not a fix to it).
+  protected virtual void AfterRender(Element root) {
+  }
+
   public void Mount(Element parent) {
     this.ParentElement = parent;
-    this.Root = this.SafeRender();
-    parent.appendChild(this.Root);
+    this.Tree = this.SafeRender();
+    Element root = Materialize(this.Tree);
+    parent.appendChild(root);
     this.IsMounted = true;
+    this.AfterRender(root);
   }
 
   // A no-op, not an error, when called before Mount() — see the class-level
@@ -73,8 +94,9 @@ class Component {
     if (!this.IsMounted) {
       return;
     }
-    Element newRoot = this.SafeRender();
-    this.ParentElement.replaceChild(newRoot, this.Root);
-    this.Root = newRoot;
+    VElement newTree = this.SafeRender();
+    Element root = Patch(this.ParentElement, this.Tree, newTree);
+    this.Tree = newTree;
+    this.AfterRender(root);
   }
 }

package/src/directives.js

@@ -1,4 +1,5 @@
 import { Event, Element, Document, Location, History, Window, document, location, history, window } from "./dom.js";
+import { VElement } from "./velement.js";
 
 export function If(condition, whenTrue, whenFalse) {
   if (condition) {

package/src/directives.js.map

@@ -1 +1 @@
-{"version":3,"file":"directives.js","sources":["directives.ks"],"sourcesContent":["using \"./dom\";\n\n// Kopular's structural-directive equivalents — see the README's\n// \"Structural directives\" section for the full *ngIf/*ngFor/*ngSwitch\n// mapping. There's no template language here (Kopular doesn't have one, by\n// design — see component.ks), so these are just plain functions: call them\n// like any other expression from inside Render(), the same way you'd call\n// document.createElement.\n//\n// *ngFor and *ngSwitch need nothing new — `array.ForEach(...)` and\n// KopScript's own `match` expression already cover them (and `match` is\n// exhaustiveness-checked, which *ngSwitch isn't). `If` below is the one\n// piece the language doesn't already give you as an expression: `if` is a\n// statement in KopScript, so without this you'd need a throwaway mutable\n// local to get a conditional value.\n\n// The *ngIf equivalent — conditionally build one of two subtrees, as an\n// expression. Both branches are required: v1 has no nullable types, so\n// \"render nothing\" has no value to return — the same reasoning Router uses\n// for requiring a NotFoundPage up front (see router.ks) rather than letting\n// \"no match\" be null. Only the branch actually taken runs; the other\n// lambda is never called, so an explicit empty branch (e.g.\n// `() => document.createElement(\"span\")`) costs nothing when there's\n// genuinely nothing to show.\nElement If(bool condition, () => Element whenTrue, () => Element whenFalse) {\n  if (condition) {\n    return whenTrue();\n  }\n  return whenFalse();\n}\n"],"names":[],"mappings":";;AAwBA;EACE;IACE;;EAEF"}
+{"version":3,"file":"directives.js","sources":["directives.ks"],"sourcesContent":["using \"./dom\";\nusing \"./velement\";\n\n// Kopular's structural-directive equivalents — see the README's\n// \"Structural directives\" section for the full *ngIf/*ngFor/*ngSwitch\n// mapping. There's no template language here (Kopular doesn't have one, by\n// design — see component.ks), so these are just plain functions: call them\n// like any other expression from inside Render(), the same way you'd call\n// VElement.Create.\n//\n// *ngFor and *ngSwitch need nothing new — `array.ForEach(...)` and\n// KopScript's own `match` expression already cover them (and `match` is\n// exhaustiveness-checked, which *ngSwitch isn't). `If` below is the one\n// piece the language doesn't already give you as an expression: `if` is a\n// statement in KopScript, so without this you'd need a throwaway mutable\n// local to get a conditional value.\n\n// The *ngIf equivalent — conditionally build one of two subtrees, as an\n// expression. Both branches are required: v1 has no nullable types, so\n// \"render nothing\" has no value to return — the same reasoning Router uses\n// for requiring a NotFoundPage up front (see router.ks) rather than letting\n// \"no match\" be null. Only the branch actually taken runs; the other\n// lambda is never called, so an explicit empty branch (e.g.\n// `() => VElement.Create(\"span\")`) costs nothing when there's genuinely\n// nothing to show.\nVElement If(bool condition, () => VElement whenTrue, () => VElement whenFalse) {\n  if (condition) {\n    return whenTrue();\n  }\n  return whenFalse();\n}\n"],"names":[],"mappings":";;;AAyBA;EACE;IACE;;EAEF"}

package/src/directives.ks

@@ -1,11 +1,12 @@
 using "./dom";
+using "./velement";
 
 // Kopular's structural-directive equivalents — see the README's
 // "Structural directives" section for the full *ngIf/*ngFor/*ngSwitch
 // mapping. There's no template language here (Kopular doesn't have one, by
 // design — see component.ks), so these are just plain functions: call them
 // like any other expression from inside Render(), the same way you'd call
-// document.createElement.
+// VElement.Create.
 //
 // *ngFor and *ngSwitch need nothing new — `array.ForEach(...)` and
 // KopScript's own `match` expression already cover them (and `match` is
@@ -20,9 +21,9 @@ using "./dom";
 // for requiring a NotFoundPage up front (see router.ks) rather than letting
 // "no match" be null. Only the branch actually taken runs; the other
 // lambda is never called, so an explicit empty branch (e.g.
-// `() => document.createElement("span")`) costs nothing when there's
-// genuinely nothing to show.
-Element If(bool condition, () => Element whenTrue, () => Element whenFalse) {
+// `() => VElement.Create("span")`) costs nothing when there's genuinely
+// nothing to show.
+VElement If(bool condition, () => VElement whenTrue, () => VElement whenFalse) {
   if (condition) {
     return whenTrue();
   }

package/src/dom.js.map

@@ -1 +1 @@
-{"version":3,"file":"dom.js","sources":["dom.ks"],"sourcesContent":["// Minimal browser DOM bindings. All ambient (no `from` clause) — document,\n// Element, and Event genuinely exist as globals in a browser, no import\n// needed. Member names use the real JS casing exactly (camelCase), since\n// extern declarations describe an existing external contract rather than\n// idiomatic Kop code — there's no per-member rename mechanism. `extern\n// class` declarations end in `;`, like the other two extern forms.\n\nextern class Event {\n  Element target { get; }\n  void preventDefault();\n};\n\nextern class Element {\n  string textContent { get; set; }\n  string id { get; set; }\n  string className { get; set; }\n  void appendChild(Element child);\n  void replaceChild(Element newChild, Element oldChild);\n  void addEventListener(string eventType, (Event) => void handler);\n  void removeEventListener(string eventType, (Event) => void handler);\n};\n\nextern class Document {\n  Element createElement(string tagName);\n  Element getElementById(string id);\n  Element body { get; }\n};\n\nextern class Location {\n  string pathname { get; }\n  // The real query string including its leading \"?\" (e.g. \"?sort=name\"),\n  // or \"\" if the current URL has none — see Router.ParseQuery/Query.\n  string search { get; }\n};\n\nextern class History {\n  // Param named `historyState`, not `state` — `state` is a KopScript\n  // keyword (state<T>), not a valid parameter name.\n  void pushState(string historyState, string title, string url);\n};\n\nextern class Window {\n  void addEventListener(string eventType, (Event) => void handler);\n};\n\nextern Document document;\nextern Location location;\nextern History history;\nextern Window window;\n"],"names":[],"mappings":"AAOA;AAKA;AAUA;AAMA;AAOA;AAMA;AAIA;AACA;AACA;AACA"}
+{"version":3,"file":"dom.js","sources":["dom.ks"],"sourcesContent":["// Minimal browser DOM bindings. All ambient (no `from` clause) — document,\n// Element, and Event genuinely exist as globals in a browser, no import\n// needed. Member names use the real JS casing exactly (camelCase), since\n// extern declarations describe an existing external contract rather than\n// idiomatic KopScript code — there's no per-member rename mechanism. `extern\n// class` declarations end in `;`, like the other two extern forms.\n\nextern class Event {\n  Element target { get; }\n  void preventDefault();\n};\n\nextern class Element {\n  string textContent { get; set; }\n  string id { get; set; }\n  string className { get; set; }\n  // The one property the vdom patch engine (src/vdom.ks) always sets via\n  // direct property assignment, never setAttribute — setAttribute(\"value\",\n  // x) sets the DEFAULT value attribute, not the current live one, a real\n  // DOM footgun (and the exact property behind the original typing bug\n  // this whole diffing effort traces back to).\n  string value { get; set; }\n  // Only ever assigned by the vdom patch engine for a VElement.RawHtml leaf\n  // — never diffed into, an opaque blob the same way `raw string` is.\n  string innerHTML { get; set; }\n  void appendChild(Element child);\n  void replaceChild(Element newChild, Element oldChild);\n  // `referenceChild` is nullable — real DOM insertBefore(node, null) means\n  // \"append at the end,\" used by the patch engine's child-reordering step.\n  void insertBefore(Element newChild, Element? referenceChild);\n  void removeChild(Element child);\n  // The generic escape hatch VElement.SetAttr's ExtraNames/ExtraValues\n  // patch through — real HTML attributes only (href, src, alt,\n  // placeholder, ...), never `value` (see above).\n  void setAttribute(string name, string value);\n  void addEventListener(string eventType, (Event) => void handler);\n  void removeEventListener(string eventType, (Event) => void handler);\n};\n\nextern class Document {\n  Element createElement(string tagName);\n  Element getElementById(string id);\n  Element body { get; }\n};\n\nextern class Location {\n  string pathname { get; }\n  // The real query string including its leading \"?\" (e.g. \"?sort=name\"),\n  // or \"\" if the current URL has none — see Router.ParseQuery/Query.\n  string search { get; }\n};\n\nextern class History {\n  // Param named `historyState`, not `state` — `state` is a KopScript\n  // keyword (state<T>), not a valid parameter name.\n  void pushState(string historyState, string title, string url);\n};\n\nextern class Window {\n  void addEventListener(string eventType, (Event) => void handler);\n};\n\nextern Document document;\nextern Location location;\nextern History history;\nextern Window window;\n"],"names":[],"mappings":"AAOA;AAKA;AA2BA;AAMA;AAOA;AAMA;AAIA;AACA;AACA;AACA"}

package/src/dom.ks

@@ -2,7 +2,7 @@
 // Element, and Event genuinely exist as globals in a browser, no import
 // needed. Member names use the real JS casing exactly (camelCase), since
 // extern declarations describe an existing external contract rather than
-// idiomatic Kop code — there's no per-member rename mechanism. `extern
+// idiomatic KopScript code — there's no per-member rename mechanism. `extern
 // class` declarations end in `;`, like the other two extern forms.
 
 extern class Event {
@@ -14,8 +14,25 @@ extern class Element {
   string textContent { get; set; }
   string id { get; set; }
   string className { get; set; }
+  // The one property the vdom patch engine (src/vdom.ks) always sets via
+  // direct property assignment, never setAttribute — setAttribute("value",
+  // x) sets the DEFAULT value attribute, not the current live one, a real
+  // DOM footgun (and the exact property behind the original typing bug
+  // this whole diffing effort traces back to).
+  string value { get; set; }
+  // Only ever assigned by the vdom patch engine for a VElement.RawHtml leaf
+  // — never diffed into, an opaque blob the same way `raw string` is.
+  string innerHTML { get; set; }
   void appendChild(Element child);
   void replaceChild(Element newChild, Element oldChild);
+  // `referenceChild` is nullable — real DOM insertBefore(node, null) means
+  // "append at the end," used by the patch engine's child-reordering step.
+  void insertBefore(Element newChild, Element? referenceChild);
+  void removeChild(Element child);
+  // The generic escape hatch VElement.SetAttr's ExtraNames/ExtraValues
+  // patch through — real HTML attributes only (href, src, alt,
+  // placeholder, ...), never `value` (see above).
+  void setAttribute(string name, string value);
   void addEventListener(string eventType, (Event) => void handler);
   void removeEventListener(string eventType, (Event) => void handler);
 };