kopular 0.14.1 → 0.15.1

package/LLM.md

@@ -22,7 +22,67 @@ there is no `kopular/template` entry point to import.
 ## Consuming Kopular from your own KopScript project
 
 `using` only resolves same-project relative paths — reaching into an npm package (Kopular
-included) always goes through `extern`, re-describing exactly the members you use:
+included) always goes through `extern`, re-describing exactly the members you use.
+
+**`Element`/`Document`/`Event` are NOT part of Kopular's own exports** — they're plain
+ambient browser globals (`extern class Element { ... };`, no `from` clause), genuinely
+present at runtime with no import needed, but Kopular has no re-exportable copy of them
+to reach for: `kopular/dom` is Kopular's own *internal* ambient binding, itself made of
+erased `extern` declarations with nothing real behind them at runtime, so `extern class
+Element { ... } from "kopular/dom";` doesn't work — there's no `Element` symbol actually
+living in that module to bind to. Every consuming project re-declares its own
+Element/Document/Event, same as this one does. **Copy the block below rather than
+hand-rolling a smaller one from scratch and adding members as compile errors demand
+them** — a real, complete first-attempt implementation of a Kopular app hit the exact
+same missing property (`Element.value`) twice from two independently-trimmed subsets,
+because the compile error only ever names the one member actually touched, never warns
+that a *sibling* feature (a template's `placeholder="..."` attribute, a `[(value)]`
+binding's generated `e.target.value` read) will need one you didn't happen to write by
+hand:
+
+```ks
+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; }
+  // Every `[(value)]="Field"` template binding and any handler reading
+  // `e.target.value` needs this — the single most commonly missing member
+  // when a hand-trimmed subset breaks.
+  string value { get; set; }
+  string placeholder { get; set; }
+  void appendChild(Element child);
+  void replaceChild(Element newChild, Element oldChild);
+  void insertBefore(Element newChild, Element? referenceChild);
+  void removeChild(Element child);
+  void setAttribute(string name, string value);
+  void addEventListener(string eventType, (Event) => void handler);
+  void removeEventListener(string eventType, (Event) => void handler);
+  Element querySelector(string selector);
+  Element? closest(string selector);
+};
+
+extern class Document {
+  Element createElement(string tagName);
+  Element getElementById(string id);
+  Element body { get; }
+};
+
+extern Document document;
+```
+
+Trim what you genuinely never use (this is still "describe exactly the members you
+use," not "always paste everything") — but trim it *after* writing the app, not before,
+so the trim is informed by what actually compiled, not a guess at what a template will
+eventually need.
 
 ```ks
 extern class VElement {
@@ -221,10 +281,12 @@ class Counter : Component {
   no manual `Subscribe` in the constructor for that field. State reached indirectly
   (through a method, or `this.SomeService.Count`) still needs a manual `Subscribe`, same
   as a hand-written `Render()` always has.
+- **Two-way binding**: `[(value)]="Field"` desugars to `[value]="Field"` +
+  `(input)="Field = e.target.value"` — `value` only, and `Field` must be a bare name or
+  `this.Field` (see KopScript's own LLM.md `KS5017`/`KS5018` for the two rejected cases).
 - One top-level element per template (hard error otherwise); no mixing text and element
   children under one element (`VElement` has no text-node sibling concept, only
-  `.TextContent`); no two-way binding, no pipes, at most one structural directive per
-  element.
+  `.TextContent`); no pipes, at most one structural directive per element.
 - This is entirely a KopScript compiler feature (parsed/desugared before type-checking
   runs) — Kopular's own framework code (`component.ks`, `dom.ks`) is unmodified and
   unaware templates exist; a template-generated `Render()` is indistinguishable from a
@@ -423,10 +485,12 @@ CombineValidators2((string v) => Validators.Required(v), (string v) => Validator
 Fixed-arity (2, 3 — add more the same way if a form ever needs to chain further), not a
 general `Validators.All(...)`, for the same array-of-function-values reason above.
 
-**No DOM binding** — wiring `.Value` to a real `<input>` is a plain `VElement.OnInput`
-assignment in your own `Render()` reading `e.target.value` (the same as any other event
+**No DOM binding in a hand-written `Render()`** — wiring `.Value` to a real `<input>` is a
+plain `VElement.OnInput` assignment reading `e.target.value` (the same as any other event
 handler; `VElement.Value` itself is one-way, host-to-DOM only), and reading it back out
-via `.Touch()` on `OnBlur`; there is no `[(ngModel)]`-equivalent.
+via `.Touch()` on `OnBlur`. A **template** has real `[(value)]="Field"` sugar for the
+value-binding half (see "Templates" above); `Touch()` on blur still needs its own explicit
+`(blur)="Field.Touch()"` either way — `[(value)]` only ever wires `value`/`input`.
 
 ## `kopular/testing` (`testing.js`, hand-written JS, not compiled from `.ks`)
 
@@ -528,10 +592,12 @@ class CounterService {
   independent mechanisms, not the same thing wired two ways** — a template never needs
   `directives.ks`'s `If()` imported or called; `*if`/`*for` compile to real `if`/`for`
   directly. Don't mix a template with a hand-written-`Render()` helper call.
-- **No two-way binding, anywhere.** Wiring a template's `[value]` or a hand-written
-  `.Value` to a real `<input>` back and forth always needs an explicit `OnInput`
-  assignment reading `e.target.value` — there's no `[(ngModel)]`-equivalent to reach for
-  in either authoring style.
+- **`[(value)]` two-way binding is template-only, and `value`-only.** A hand-written
+  `Render()` still always needs an explicit `OnInput` assignment reading
+  `e.target.value` — there's no equivalent shorthand there, since it already has direct
+  field access. `[(id)]`/`[(className)]` don't exist either, even in a template — the
+  sugar only wires `value`/`input`, the one pairing with a real "user just changed this"
+  event.
 - **A `VElement` event binding only accepts `click`/`input`/`blur`/`change`** — both in a
   template's `(event)="..."` and a hand-written `OnClick`/`OnInput`/`OnBlur`/`OnChange`
   assignment. There's no generic `addEventListener` on `VElement` (event handlers are part
@@ -549,7 +615,9 @@ class CounterService {
 DI container/injector · decorators (`@Injectable`, `@Component`, ...) · a runtime
 template engine or interpreted expression language — templates compile to the same
 imperative `Render()` code as the hand-written form, checked at compile time, not
-interpreted at runtime (see "Templates" above) · two-way binding (`[(ngModel)]`) ·
+interpreted at runtime (see "Templates" above) · two-way binding in a hand-written
+`Render()`, or on anything but `value` even in a template (`[(value)]="Field"` exists —
+see "Templates" above — but it's `value`-only, and templates-only) ·
 reconciliation across a nested-Component boundary (see "Common mistakes" above — real
 vdom diffing exists *within* one Component's own subtree, via `Update()`/`vdom.ks`) ·
 a generic/arbitrary `VElement` event binding — only `click`/`input`/`blur`/`change` ·

package/README.md

@@ -477,13 +477,16 @@ to live as a free function instead. `Validators` ships the handful of checks alm
 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 `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.
+**No two-way data binding in a hand-written `Render()`** — 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: hand-written code already has direct field/handler
+access, so there's nothing for a magic binding to save you from writing. A **template**
+gets real sugar for exactly this — `[(value)]="Field"` desugars to `[value]="Field"` +
+`(input)="Field = e.target.value"` (see KopScript's own "Templates" docs) — since a
+markup file has no equivalent direct access to fall back on.
 
 ## Starting a new project: `kp new`
 
@@ -546,6 +549,15 @@ 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).
 
+The snippet above is illustrative, not exhaustive — real code needs a fuller
+`VElement`/`Component`/`Router`, and `Element` itself (used above as `Mount`'s
+parameter type but never shown declared) is a plain ambient browser global your own
+project declares, not something Kopular exports — `LLM.md`'s "Consuming Kopular from
+your own KopScript project" section has the complete, copy-ready block for all of
+these, `Element`/`Document`/`Event` included. `npx kp new` (above) generates this
+boilerplate for a fresh project either way — reach for `LLM.md`'s block when adding to
+an existing one instead.
+
 `extern class` can carry its own `<T>` (kopscript >= 0.5.0), so a generic export like
 `FormField<T>` describes the same way a real generic class does — see `LLM.md`'s
 `FormField<T>`/`Validators` section for the full example.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.14.1",
+  "version": "0.15.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",

package/src/component.js

@@ -1,5 +1,5 @@
 import { Event, Element, Document, Location, History, Window, document, location, history, window } from "./dom.js";
-import { VElement } from "./velement.js";
+import { VElement, NoOpEventHandler } from "./velement.js";
 import { Materialize, Patch, PatchChildren } from "./vdom.js";
 
 export class Component {

package/src/directives.js

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

package/src/router.js

@@ -1,6 +1,6 @@
 import { Event, Element, Document, Location, History, Window, document, location, history, window } from "./dom.js";
 import { Component } from "./component.js";
-import { VElement } from "./velement.js";
+import { VElement, NoOpEventHandler } from "./velement.js";
 
 export class Router extends Component {
   constructor(notFoundPage) {

package/src/vdom.js

@@ -1,5 +1,5 @@
 import { Event, Element, Document, Location, History, Window, document, location, history, window } from "./dom.js";
-import { VElement } from "./velement.js";
+import { VElement, NoOpEventHandler } from "./velement.js";
 
 export function Materialize(tree) {
   let el = document.createElement(tree.Tag);
@@ -18,10 +18,18 @@ export function Materialize(tree) {
   for (let i = 0; (i < tree.ExtraNames.length); i = (i + 1)) {
     el.setAttribute(tree.ExtraNames[i], tree.ExtraValues[i]);
   }
-  el.addEventListener("click", tree.OnClick);
-  el.addEventListener("input", tree.OnInput);
-  el.addEventListener("blur", tree.OnBlur);
-  el.addEventListener("change", tree.OnChange);
+  if ((tree.OnClick !== NoOpEventHandler)) {
+    el.addEventListener("click", tree.OnClick);
+  }
+  if ((tree.OnInput !== NoOpEventHandler)) {
+    el.addEventListener("input", tree.OnInput);
+  }
+  if ((tree.OnBlur !== NoOpEventHandler)) {
+    el.addEventListener("blur", tree.OnBlur);
+  }
+  if ((tree.OnChange !== NoOpEventHandler)) {
+    el.addEventListener("change", tree.OnChange);
+  }
   tree.RealNode = el;
   return el;
 }
@@ -54,17 +62,33 @@ export function Patch(parent, old, updated) {
           realNode.id = updated.Id;
         }
         realNode.value = updated.Value;
-        for (let i = 0; (i < updated.ExtraNames.length); i = (i + 1)) {
-          realNode.setAttribute(updated.ExtraNames[i], updated.ExtraValues[i]);
+        if ((updated.ExtraNames.length === oldTree.ExtraNames.length)) {
+          for (let i = 0; (i < updated.ExtraNames.length); i = (i + 1)) {
+            if (((updated.ExtraNames[i] !== oldTree.ExtraNames[i]) || (updated.ExtraValues[i] !== oldTree.ExtraValues[i]))) {
+              realNode.setAttribute(updated.ExtraNames[i], updated.ExtraValues[i]);
+            }
+          }
+        } else {
+          for (let i = 0; (i < updated.ExtraNames.length); i = (i + 1)) {
+            realNode.setAttribute(updated.ExtraNames[i], updated.ExtraValues[i]);
+          }
+        }
+        if ((updated.OnClick !== oldTree.OnClick)) {
+          realNode.removeEventListener("click", oldTree.OnClick);
+          realNode.addEventListener("click", updated.OnClick);
+        }
+        if ((updated.OnInput !== oldTree.OnInput)) {
+          realNode.removeEventListener("input", oldTree.OnInput);
+          realNode.addEventListener("input", updated.OnInput);
+        }
+        if ((updated.OnBlur !== oldTree.OnBlur)) {
+          realNode.removeEventListener("blur", oldTree.OnBlur);
+          realNode.addEventListener("blur", updated.OnBlur);
+        }
+        if ((updated.OnChange !== oldTree.OnChange)) {
+          realNode.removeEventListener("change", oldTree.OnChange);
+          realNode.addEventListener("change", updated.OnChange);
         }
-        realNode.removeEventListener("click", oldTree.OnClick);
-        realNode.addEventListener("click", updated.OnClick);
-        realNode.removeEventListener("input", oldTree.OnInput);
-        realNode.addEventListener("input", updated.OnInput);
-        realNode.removeEventListener("blur", oldTree.OnBlur);
-        realNode.addEventListener("blur", updated.OnBlur);
-        realNode.removeEventListener("change", oldTree.OnChange);
-        realNode.addEventListener("change", updated.OnChange);
         return realNode;
       }
     } else {
@@ -79,14 +103,8 @@ export function Patch(parent, old, updated) {
   }
 }
 export function PatchChildren(parent, oldChildren, newChildren) {
-  let oldConsumed = [];
-  for (let i = 0; (i < oldChildren.length); i = (i + 1)) {
-    oldConsumed = [...oldConsumed, false];
-  }
-  let matchedOldIndex = [];
-  for (let i = 0; (i < newChildren.length); i = (i + 1)) {
-    matchedOldIndex = [...matchedOldIndex, -1];
-  }
+  let oldConsumed = oldChildren.map((c) => (false));
+  let matchedOldIndex = newChildren.map((c) => (-1));
   for (let i = 0; (i < newChildren.length); i = (i + 1)) {
     if ((newChildren[i].Id.length === 0)) {
       continue;
@@ -113,13 +131,22 @@ export function PatchChildren(parent, oldChildren, newChildren) {
       nextOld = (nextOld + 1);
     }
   }
+  let needsReorder = (oldChildren.length !== newChildren.length);
+  for (let i = 0; (i < newChildren.length); i = (i + 1)) {
+    if ((matchedOldIndex[i] !== i)) {
+      needsReorder = true;
+      break;
+    }
+  }
   for (let i = 0; (i < newChildren.length); i = (i + 1)) {
     let matchedOld = null;
     if ((matchedOldIndex[i] >= 0)) {
       matchedOld = oldChildren[matchedOldIndex[i]];
     }
     let childNode = Patch(parent, matchedOld, newChildren[i]);
-    parent.appendChild(childNode);
+    if (needsReorder) {
+      parent.appendChild(childNode);
+    }
   }
   for (let j = 0; (j < oldChildren.length); j = (j + 1)) {
     if (oldConsumed[j]) {

package/src/vdom.js.map

@@ -1 +1 @@
-{"version":3,"file":"vdom.js","sources":["vdom.ks"],"sourcesContent":["using \"./dom\";\nusing \"./velement\";\n\n// The diff/patch engine behind real vdom diffing: Component.Update() (see\n// component.ks) calls Patch() with the PREVIOUS render's VElement tree\n// (which carries each node's real, live DOM counterpart via its own\n// RealNode field) and the NEW tree Render() just produced, and gets back\n// real DOM mutated/reused in place wherever possible instead of a full\n// subtree rebuild.\n//\n// Deliberately never reads the live DOM back to rediscover structure (no\n// \"get current children\"/\"get current tag\" API exists, or is needed) —\n// the retained *previous* VElement tree already records everything Patch()\n// needs to know about what's currently there. This is what makes the whole\n// approach work without a generic children/attributes read-back API that\n// KopScript's narrow, curated DOM binding doesn't have.\n\n// Builds a brand-new, fully real DOM subtree from a VElement tree with no\n// diffing at all — first mount, or whenever Patch() decides a subtree must\n// be replaced outright (no previous node to reuse, or the tag changed).\n// Mutates `tree.RealNode` (and recursively every descendant's) as a side\n// effect, so the tree this was called on becomes the new \"previous tree\"\n// the next Patch() call diffs against.\nElement Materialize(VElement tree) {\n  Element el = document.createElement(tree.Tag);\n\n  if (tree.RawHtml.Length > 0) {\n    el.innerHTML = tree.RawHtml;\n  } else if (tree.Children.Length > 0) {\n    foreach (VElement child in tree.Children) {\n      el.appendChild(Materialize(child));\n    }\n  } else {\n    el.textContent = tree.TextContent;\n  }\n\n  el.className = tree.ClassName;\n  el.id = tree.Id;\n  el.value = tree.Value;\n\n  for (number i = 0; i < tree.ExtraNames.Length; i = i + 1) {\n    el.setAttribute(tree.ExtraNames[i], tree.ExtraValues[i]);\n  }\n\n  el.addEventListener(\"click\", tree.OnClick);\n  el.addEventListener(\"input\", tree.OnInput);\n  el.addEventListener(\"blur\", tree.OnBlur);\n  el.addEventListener(\"change\", tree.OnChange);\n\n  tree.RealNode = el;\n  return el;\n}\n\n// Diffs `updated` against `old` (the previous render's tree for this exact\n// position, or null if there is none — first mount) and returns the real\n// DOM node now representing `updated`, reusing `old`'s real node in place\n// whenever the tag matches. `parent` is only used to attach/replace at the\n// top of whatever subtree Patch() is called on — child-level attach/replace\n// happens inside PatchChildren.\n//\n// Deliberately all positive-branch `if (x != null) { ... } else { ... }`,\n// never an early-return guard clause — KopScript's nullable narrowing is\n// scope-based, not reachability-based, so `if (x == null) { return; }\n// use(x);` would NOT narrow `x` afterward (see KopScript's own LLM.md \"Common\n// mistakes\"). Every nullable member-access path (`oldTree.RealNode`,\n// never narrows directly either) is read into a local first for the same\n// reason.\nElement Patch(Element parent, VElement? old, VElement updated) {\n  if (old != null) {\n    VElement oldTree = old;\n    Element? maybeOldNode = oldTree.RealNode;\n    if (maybeOldNode != null) {\n      Element realNode = maybeOldNode;\n      if (oldTree.Tag != updated.Tag) {\n        Element created = Materialize(updated);\n        parent.replaceChild(created, realNode);\n        return created;\n      } else {\n        updated.RealNode = realNode;\n\n        if (updated.RawHtml.Length > 0 || oldTree.RawHtml.Length > 0) {\n          if (updated.RawHtml != oldTree.RawHtml) {\n            realNode.innerHTML = updated.RawHtml;\n          }\n        } else {\n          if (updated.TextContent != oldTree.TextContent) {\n            realNode.textContent = updated.TextContent;\n          }\n          PatchChildren(realNode, oldTree.Children, updated.Children);\n        }\n\n        if (updated.ClassName != oldTree.ClassName) {\n          realNode.className = updated.ClassName;\n        }\n        if (updated.Id != oldTree.Id) {\n          realNode.id = updated.Id;\n        }\n        // Always assigned, never conditionally on updated.Value != oldTree.Value\n        // — unlike TextContent/ClassName/Id, an <input>/<select>'s live value\n        // can diverge from the last-recorded VElement.Value purely through\n        // user interaction (typing, picking an option) with no Update() ever\n        // running in between (a real, deliberate pattern — see KopularDemo's\n        // dogs_page.ks, which never Update()s on input/change). The recorded\n        // oldTree.Value only reflects the tree as of the last actual render,\n        // so comparing against it can't tell \"genuinely unchanged\" apart from\n        // \"changed live in the DOM since then, framework never told\" — the\n        // same reason a real \"controlled input\" (React's own term for this)\n        // always writes value on every render rather than diffing it.\n        realNode.value = updated.Value;\n\n        for (number i = 0; i < updated.ExtraNames.Length; i = i + 1) {\n          realNode.setAttribute(updated.ExtraNames[i], updated.ExtraValues[i]);\n        }\n\n        // Always swap all four listeners — cheap, and sidesteps needing to\n        // compare function identity (every Render() call creates fresh\n        // closures, so \"did the handler actually change\" isn't answerable\n        // any other way).\n        realNode.removeEventListener(\"click\", oldTree.OnClick);\n        realNode.addEventListener(\"click\", updated.OnClick);\n        realNode.removeEventListener(\"input\", oldTree.OnInput);\n        realNode.addEventListener(\"input\", updated.OnInput);\n        realNode.removeEventListener(\"blur\", oldTree.OnBlur);\n        realNode.addEventListener(\"blur\", updated.OnBlur);\n        realNode.removeEventListener(\"change\", oldTree.OnChange);\n        realNode.addEventListener(\"change\", updated.OnChange);\n\n        return realNode;\n      }\n    } else {\n      // Shouldn't happen in practice (every previously-rendered tree has a\n      // real node by the time a second render diffs against it) — treated\n      // as \"nothing to reuse\" rather than a crash, same defensive spirit\n      // as Component's own IsMounted guard.\n      Element created = Materialize(updated);\n      parent.appendChild(created);\n      return created;\n    }\n  } else {\n    Element created = Materialize(updated);\n    parent.appendChild(created);\n    return created;\n  }\n}\n\n// Keyed reconciliation: each VElement's own Id is its key when non-empty —\n// a real, existing DOM convention, needing no new API or syntax. A new\n// child whose Id matches an old child's Id is patched against that old\n// child (reusing its real node) regardless of position; a new child with\n// no Id, or an Id not present among the old children, falls back to\n// pairing positionally against whatever old children are still unconsumed,\n// in order. DOCUMENTED, REAL LIMITATION: without stable Ids, a reordered\n// list still produces the correct final output, but a given item's real\n// DOM node (and anything stateful attached to it, like focus) isn't\n// guaranteed to follow its data across the reorder — give list items a\n// stable Id for that guarantee.\nvoid PatchChildren(Element parent, VElement[] oldChildren, VElement[] newChildren) {\n  bool[] oldConsumed = [];\n  for (number i = 0; i < oldChildren.Length; i = i + 1) {\n    oldConsumed = oldConsumed.Push(false);\n  }\n\n  number[] matchedOldIndex = [];\n  for (number i = 0; i < newChildren.Length; i = i + 1) {\n    matchedOldIndex = matchedOldIndex.Push(-1);\n  }\n\n  // Pass 1: keyed matches, by Id.\n  for (number i = 0; i < newChildren.Length; i = i + 1) {\n    if (newChildren[i].Id.Length == 0) { continue; }\n    for (number j = 0; j < oldChildren.Length; j = j + 1) {\n      if (!oldConsumed[j] && oldChildren[j].Id == newChildren[i].Id) {\n        matchedOldIndex[i] = j;\n        oldConsumed[j] = true;\n        break;\n      }\n    }\n  }\n\n  // Pass 2: positional fallback for everything Pass 1 didn't match —\n  // pair each remaining new child against the next still-unconsumed old\n  // child, in order.\n  number nextOld = 0;\n  for (number i = 0; i < newChildren.Length; i = i + 1) {\n    if (matchedOldIndex[i] >= 0) { continue; }\n    while (nextOld < oldChildren.Length && oldConsumed[nextOld]) {\n      nextOld = nextOld + 1;\n    }\n    if (nextOld < oldChildren.Length) {\n      matchedOldIndex[i] = nextOld;\n      oldConsumed[nextOld] = true;\n      nextOld = nextOld + 1;\n    }\n  }\n\n  // Pass 3: patch/create each new child in order, then move it into its\n  // correct final position — appendChild on a node already attached\n  // elsewhere in the DOM MOVES it (real DOM semantics), so processing new\n  // children in their final desired order and always appending naturally\n  // builds up the correct sequence, no separate insertBefore/reference-\n  // node bookkeeping needed. Safe because VElement.Children is always the\n  // COMPLETE list of a node's children — nothing else ever shares `parent`.\n  for (number i = 0; i < newChildren.Length; i = i + 1) {\n    VElement? matchedOld = null;\n    if (matchedOldIndex[i] >= 0) {\n      matchedOld = oldChildren[matchedOldIndex[i]];\n    }\n    Element childNode = Patch(parent, matchedOld, newChildren[i]);\n    parent.appendChild(childNode);\n  }\n\n  // Pass 4: remove whatever old children never got reused.\n  for (number j = 0; j < oldChildren.Length; j = j + 1) {\n    if (oldConsumed[j]) { continue; }\n    Element? maybeOldNode = oldChildren[j].RealNode;\n    if (maybeOldNode != null) {\n      Element oldNode = maybeOldNode;\n      parent.removeChild(oldNode);\n    }\n  }\n}\n"],"names":[],"mappings":";;;AAuBA;EACE;EAEA;IACe;;IAEb;MACgB;;;IAGD;;EAGJ;EACP;EACG;EAET;IACiB;;EAGE;EACA;EACA;EACA;EAEL;EACd;;AAiBF;EACE;IACE;IACA;IACA;MACE;MACA;QACE;QACmB;QACnB;;QAEiB;QAEjB;UACE;YACqB;;;UAGrB;YACuB;;UAEV;;QAGf;UACqB;;QAErB;UACc;;QAaC;QAEf;UACuB;;QAOK;QACH;QACG;QACH;QACG;QACH;QACG;QACH;QAEzB;;;MAOF;MACkB;MAClB;;;IAGF;IACkB;IAClB;;;AAeJ;EACE;EACA;IACc;;EAGd;EACA;IACkB;;EAIlB;IACE;MAAqC;;IACrC;MACE;QACqB;QACJ;QACf;;;;EAQN;EACA;IACE;MAA+B;;IAC/B;MACU;;IAEV;MACqB;MACE;MACb;;;EAWZ;IACE;IACA;MACa;;IAEb;IACkB;;EAIpB;IACE;MAAsB;;IACtB;IACA;MACE;MACkB"}
+{"version":3,"file":"vdom.js","sources":["vdom.ks"],"sourcesContent":["using \"./dom\";\nusing \"./velement\";\n\n// The diff/patch engine behind real vdom diffing: Component.Update() (see\n// component.ks) calls Patch() with the PREVIOUS render's VElement tree\n// (which carries each node's real, live DOM counterpart via its own\n// RealNode field) and the NEW tree Render() just produced, and gets back\n// real DOM mutated/reused in place wherever possible instead of a full\n// subtree rebuild.\n//\n// Deliberately never reads the live DOM back to rediscover structure (no\n// \"get current children\"/\"get current tag\" API exists, or is needed) —\n// the retained *previous* VElement tree already records everything Patch()\n// needs to know about what's currently there. This is what makes the whole\n// approach work without a generic children/attributes read-back API that\n// KopScript's narrow, curated DOM binding doesn't have.\n\n// Builds a brand-new, fully real DOM subtree from a VElement tree with no\n// diffing at all — first mount, or whenever Patch() decides a subtree must\n// be replaced outright (no previous node to reuse, or the tag changed).\n// Mutates `tree.RealNode` (and recursively every descendant's) as a side\n// effect, so the tree this was called on becomes the new \"previous tree\"\n// the next Patch() call diffs against.\nElement Materialize(VElement tree) {\n  Element el = document.createElement(tree.Tag);\n\n  if (tree.RawHtml.Length > 0) {\n    el.innerHTML = tree.RawHtml;\n  } else if (tree.Children.Length > 0) {\n    foreach (VElement child in tree.Children) {\n      el.appendChild(Materialize(child));\n    }\n  } else {\n    el.textContent = tree.TextContent;\n  }\n\n  el.className = tree.ClassName;\n  el.id = tree.Id;\n  el.value = tree.Value;\n\n  for (number i = 0; i < tree.ExtraNames.Length; i = i + 1) {\n    el.setAttribute(tree.ExtraNames[i], tree.ExtraValues[i]);\n  }\n\n  // Skip attaching VElement's own shared no-op (see velement.ks) — it does\n  // nothing when invoked, so registering it costs real work (a listener\n  // list entry, held onto for nothing) for zero benefit. A real handler\n  // (never equal to the shared no-op) always gets attached as before.\n  if (tree.OnClick != NoOpEventHandler) { el.addEventListener(\"click\", tree.OnClick); }\n  if (tree.OnInput != NoOpEventHandler) { el.addEventListener(\"input\", tree.OnInput); }\n  if (tree.OnBlur != NoOpEventHandler) { el.addEventListener(\"blur\", tree.OnBlur); }\n  if (tree.OnChange != NoOpEventHandler) { el.addEventListener(\"change\", tree.OnChange); }\n\n  tree.RealNode = el;\n  return el;\n}\n\n// Diffs `updated` against `old` (the previous render's tree for this exact\n// position, or null if there is none — first mount) and returns the real\n// DOM node now representing `updated`, reusing `old`'s real node in place\n// whenever the tag matches. `parent` is only used to attach/replace at the\n// top of whatever subtree Patch() is called on — child-level attach/replace\n// happens inside PatchChildren.\n//\n// Deliberately all positive-branch `if (x != null) { ... } else { ... }`,\n// never an early-return guard clause — KopScript's nullable narrowing is\n// scope-based, not reachability-based, so `if (x == null) { return; }\n// use(x);` would NOT narrow `x` afterward (see KopScript's own LLM.md \"Common\n// mistakes\"). Every nullable member-access path (`oldTree.RealNode`,\n// never narrows directly either) is read into a local first for the same\n// reason.\nElement Patch(Element parent, VElement? old, VElement updated) {\n  if (old != null) {\n    VElement oldTree = old;\n    Element? maybeOldNode = oldTree.RealNode;\n    if (maybeOldNode != null) {\n      Element realNode = maybeOldNode;\n      if (oldTree.Tag != updated.Tag) {\n        Element created = Materialize(updated);\n        parent.replaceChild(created, realNode);\n        return created;\n      } else {\n        updated.RealNode = realNode;\n\n        if (updated.RawHtml.Length > 0 || oldTree.RawHtml.Length > 0) {\n          if (updated.RawHtml != oldTree.RawHtml) {\n            realNode.innerHTML = updated.RawHtml;\n          }\n        } else {\n          if (updated.TextContent != oldTree.TextContent) {\n            realNode.textContent = updated.TextContent;\n          }\n          PatchChildren(realNode, oldTree.Children, updated.Children);\n        }\n\n        if (updated.ClassName != oldTree.ClassName) {\n          realNode.className = updated.ClassName;\n        }\n        if (updated.Id != oldTree.Id) {\n          realNode.id = updated.Id;\n        }\n        // Always assigned, never conditionally on updated.Value != oldTree.Value\n        // — unlike TextContent/ClassName/Id, an <input>/<select>'s live value\n        // can diverge from the last-recorded VElement.Value purely through\n        // user interaction (typing, picking an option) with no Update() ever\n        // running in between (a real, deliberate pattern — see KopularDemo's\n        // dogs_page.ks, which never Update()s on input/change). The recorded\n        // oldTree.Value only reflects the tree as of the last actual render,\n        // so comparing against it can't tell \"genuinely unchanged\" apart from\n        // \"changed live in the DOM since then, framework never told\" — the\n        // same reason a real \"controlled input\" (React's own term for this)\n        // always writes value on every render rather than diffing it.\n        realNode.value = updated.Value;\n\n        // Same-length is the overwhelmingly common case (the same Render()\n        // code path calls SetAttr the same number of times, in the same\n        // order, on every call) — compare aligned by index and only touch\n        // the real DOM for an entry that actually changed, rather than\n        // reapplying every extra attribute on every patch regardless. A\n        // length mismatch (the rarer case: a SetAttr call was added,\n        // removed, or made conditional between renders) falls back to\n        // reapplying everything, since index-aligned comparison isn't\n        // meaningful once the two arrays don't correspond entry-for-entry.\n        if (updated.ExtraNames.Length == oldTree.ExtraNames.Length) {\n          for (number i = 0; i < updated.ExtraNames.Length; i = i + 1) {\n            if (updated.ExtraNames[i] != oldTree.ExtraNames[i] || updated.ExtraValues[i] != oldTree.ExtraValues[i]) {\n              realNode.setAttribute(updated.ExtraNames[i], updated.ExtraValues[i]);\n            }\n          }\n        } else {\n          for (number i = 0; i < updated.ExtraNames.Length; i = i + 1) {\n            realNode.setAttribute(updated.ExtraNames[i], updated.ExtraValues[i]);\n          }\n        }\n\n        // Swap a listener only when the handler reference actually changed.\n        // A node that never sets a real OnClick/OnInput/OnBlur/OnChange\n        // keeps VElement's own shared NoOpEventHandler reference on both\n        // sides (see velement.ks) — comparing by `!=` costs nothing and\n        // skips two real DOM API calls per event per node for the (common)\n        // case of \"this node has no handler of this kind either time,\"\n        // which matters a lot on a list with hundreds/thousands of rows\n        // most of which set at most one or two of the four. A node WITH a\n        // real handler still gets a fresh closure every render (it\n        // captures per-render values, like a loop's own item), so it still\n        // swaps every time — correctly, since the old closure really is\n        // stale.\n        if (updated.OnClick != oldTree.OnClick) {\n          realNode.removeEventListener(\"click\", oldTree.OnClick);\n          realNode.addEventListener(\"click\", updated.OnClick);\n        }\n        if (updated.OnInput != oldTree.OnInput) {\n          realNode.removeEventListener(\"input\", oldTree.OnInput);\n          realNode.addEventListener(\"input\", updated.OnInput);\n        }\n        if (updated.OnBlur != oldTree.OnBlur) {\n          realNode.removeEventListener(\"blur\", oldTree.OnBlur);\n          realNode.addEventListener(\"blur\", updated.OnBlur);\n        }\n        if (updated.OnChange != oldTree.OnChange) {\n          realNode.removeEventListener(\"change\", oldTree.OnChange);\n          realNode.addEventListener(\"change\", updated.OnChange);\n        }\n\n        return realNode;\n      }\n    } else {\n      // Shouldn't happen in practice (every previously-rendered tree has a\n      // real node by the time a second render diffs against it) — treated\n      // as \"nothing to reuse\" rather than a crash, same defensive spirit\n      // as Component's own IsMounted guard.\n      Element created = Materialize(updated);\n      parent.appendChild(created);\n      return created;\n    }\n  } else {\n    Element created = Materialize(updated);\n    parent.appendChild(created);\n    return created;\n  }\n}\n\n// Keyed reconciliation: each VElement's own Id is its key when non-empty —\n// a real, existing DOM convention, needing no new API or syntax. A new\n// child whose Id matches an old child's Id is patched against that old\n// child (reusing its real node) regardless of position; a new child with\n// no Id, or an Id not present among the old children, falls back to\n// pairing positionally against whatever old children are still unconsumed,\n// in order. DOCUMENTED, REAL LIMITATION: without stable Ids, a reordered\n// list still produces the correct final output, but a given item's real\n// DOM node (and anything stateful attached to it, like focus) isn't\n// guaranteed to follow its data across the reorder — give list items a\n// stable Id for that guarantee.\nvoid PatchChildren(Element parent, VElement[] oldChildren, VElement[] newChildren) {\n  // Map, not a Push loop — Push is deliberately non-mutating (a real\n  // spread-copy every call, see KopScript's own README), so building an\n  // n-length array by Push-ing once per element in a loop is an\n  // accidental O(n^2) on every single PatchChildren call, however small\n  // the actual diff. Map is a real, single O(n) pass straight to\n  // Array.prototype.map.\n  bool[] oldConsumed = oldChildren.Map((VElement c) => false);\n  number[] matchedOldIndex = newChildren.Map((VElement c) => -1);\n\n  // Pass 1: keyed matches, by Id.\n  for (number i = 0; i < newChildren.Length; i = i + 1) {\n    if (newChildren[i].Id.Length == 0) { continue; }\n    for (number j = 0; j < oldChildren.Length; j = j + 1) {\n      if (!oldConsumed[j] && oldChildren[j].Id == newChildren[i].Id) {\n        matchedOldIndex[i] = j;\n        oldConsumed[j] = true;\n        break;\n      }\n    }\n  }\n\n  // Pass 2: positional fallback for everything Pass 1 didn't match —\n  // pair each remaining new child against the next still-unconsumed old\n  // child, in order.\n  number nextOld = 0;\n  for (number i = 0; i < newChildren.Length; i = i + 1) {\n    if (matchedOldIndex[i] >= 0) { continue; }\n    while (nextOld < oldChildren.Length && oldConsumed[nextOld]) {\n      nextOld = nextOld + 1;\n    }\n    if (nextOld < oldChildren.Length) {\n      matchedOldIndex[i] = nextOld;\n      oldConsumed[nextOld] = true;\n      nextOld = nextOld + 1;\n    }\n  }\n\n  // Whether anything is actually moving at all — same length, and every\n  // new position matched the *same* old position. The extremely common\n  // case for a list that's only had some of its rows' own content change\n  // (e.g. \"update every 10th row\"), where reconciliation still has real\n  // work to do (see Pass 1/2 above and Patch() itself) but nothing needs\n  // to physically move in the DOM at all.\n  bool needsReorder = oldChildren.Length != newChildren.Length;\n  for (number i = 0; i < newChildren.Length; i = i + 1) {\n    if (matchedOldIndex[i] != i) {\n      needsReorder = true;\n      break;\n    }\n  }\n\n  // Pass 3: patch/create each new child in order, then — only if the list\n  // actually needs reordering — move it into its correct final position.\n  // appendChild on a node already attached elsewhere in the DOM MOVES it\n  // (real DOM semantics), so processing new children in their final\n  // desired order and always appending naturally builds up the correct\n  // sequence, no separate insertBefore/reference-node bookkeeping needed.\n  // Safe because VElement.Children is always the COMPLETE list of a\n  // node's children — nothing else ever shares `parent`. Skipping the\n  // move entirely when `needsReorder` is false avoids a real DOM API call\n  // per child for the common no-reorder case — Patch() itself already\n  // updates or replaces a reused/changed node exactly in place either way.\n  for (number i = 0; i < newChildren.Length; i = i + 1) {\n    VElement? matchedOld = null;\n    if (matchedOldIndex[i] >= 0) {\n      matchedOld = oldChildren[matchedOldIndex[i]];\n    }\n    Element childNode = Patch(parent, matchedOld, newChildren[i]);\n    if (needsReorder) {\n      parent.appendChild(childNode);\n    }\n  }\n\n  // Pass 4: remove whatever old children never got reused.\n  for (number j = 0; j < oldChildren.Length; j = j + 1) {\n    if (oldConsumed[j]) { continue; }\n    Element? maybeOldNode = oldChildren[j].RealNode;\n    if (maybeOldNode != null) {\n      Element oldNode = maybeOldNode;\n      parent.removeChild(oldNode);\n    }\n  }\n}\n"],"names":[],"mappings":";;;AAuBA;EACE;EAEA;IACe;;IAEb;MACgB;;;IAGD;;EAGJ;EACP;EACG;EAET;IACiB;;EAOjB;IAA2D;;EAC3D;IAA2D;;EAC3D;IAA0D;;EAC1D;IAA4D;;EAE9C;EACd;;AAiBF;EACE;IACE;IACA;IACA;MACE;MACA;QACE;QACmB;QACnB;;QAEiB;QAEjB;UACE;YACqB;;;UAGrB;YACuB;;UAEV;;QAGf;UACqB;;QAErB;UACc;;QAaC;QAWf;UACE;YACE;cACuB;;;;UAIzB;YACuB;;;QAgBzB;UAC8B;UACH;;QAE3B;UAC8B;UACH;;QAE3B;UAC8B;UACH;;QAE3B;UAC8B;UACH;;QAG3B;;;MAOF;MACkB;MAClB;;;IAGF;IACkB;IAClB;;;AAeJ;EAOE;EACA;EAGA;IACE;MAAqC;;IACrC;MACE;QACqB;QACJ;QACf;;;;EAQN;EACA;IACE;MAA+B;;IAC/B;MACU;;IAEV;MACqB;MACE;MACb;;;EAUZ;EACA;IACE;MACe;MACb;;;EAeJ;IACE;IACA;MACa;;IAEb;IACA;MACoB;;;EAKtB;IACE;MAAsB;;IACtB;IACA;MACE;MACkB"}

package/src/vdom.ks

@@ -42,10 +42,14 @@ Element Materialize(VElement tree) {
     el.setAttribute(tree.ExtraNames[i], tree.ExtraValues[i]);
   }
 
-  el.addEventListener("click", tree.OnClick);
-  el.addEventListener("input", tree.OnInput);
-  el.addEventListener("blur", tree.OnBlur);
-  el.addEventListener("change", tree.OnChange);
+  // Skip attaching VElement's own shared no-op (see velement.ks) — it does
+  // nothing when invoked, so registering it costs real work (a listener
+  // list entry, held onto for nothing) for zero benefit. A real handler
+  // (never equal to the shared no-op) always gets attached as before.
+  if (tree.OnClick != NoOpEventHandler) { el.addEventListener("click", tree.OnClick); }
+  if (tree.OnInput != NoOpEventHandler) { el.addEventListener("input", tree.OnInput); }
+  if (tree.OnBlur != NoOpEventHandler) { el.addEventListener("blur", tree.OnBlur); }
+  if (tree.OnChange != NoOpEventHandler) { el.addEventListener("change", tree.OnChange); }
 
   tree.RealNode = el;
   return el;
@@ -108,22 +112,55 @@ Element Patch(Element parent, VElement? old, VElement updated) {
         // always writes value on every render rather than diffing it.
         realNode.value = updated.Value;
 
-        for (number i = 0; i < updated.ExtraNames.Length; i = i + 1) {
-          realNode.setAttribute(updated.ExtraNames[i], updated.ExtraValues[i]);
+        // Same-length is the overwhelmingly common case (the same Render()
+        // code path calls SetAttr the same number of times, in the same
+        // order, on every call) — compare aligned by index and only touch
+        // the real DOM for an entry that actually changed, rather than
+        // reapplying every extra attribute on every patch regardless. A
+        // length mismatch (the rarer case: a SetAttr call was added,
+        // removed, or made conditional between renders) falls back to
+        // reapplying everything, since index-aligned comparison isn't
+        // meaningful once the two arrays don't correspond entry-for-entry.
+        if (updated.ExtraNames.Length == oldTree.ExtraNames.Length) {
+          for (number i = 0; i < updated.ExtraNames.Length; i = i + 1) {
+            if (updated.ExtraNames[i] != oldTree.ExtraNames[i] || updated.ExtraValues[i] != oldTree.ExtraValues[i]) {
+              realNode.setAttribute(updated.ExtraNames[i], updated.ExtraValues[i]);
+            }
+          }
+        } else {
+          for (number i = 0; i < updated.ExtraNames.Length; i = i + 1) {
+            realNode.setAttribute(updated.ExtraNames[i], updated.ExtraValues[i]);
+          }
         }
 
-        // Always swap all four listeners — cheap, and sidesteps needing to
-        // compare function identity (every Render() call creates fresh
-        // closures, so "did the handler actually change" isn't answerable
-        // any other way).
-        realNode.removeEventListener("click", oldTree.OnClick);
-        realNode.addEventListener("click", updated.OnClick);
-        realNode.removeEventListener("input", oldTree.OnInput);
-        realNode.addEventListener("input", updated.OnInput);
-        realNode.removeEventListener("blur", oldTree.OnBlur);
-        realNode.addEventListener("blur", updated.OnBlur);
-        realNode.removeEventListener("change", oldTree.OnChange);
-        realNode.addEventListener("change", updated.OnChange);
+        // Swap a listener only when the handler reference actually changed.
+        // A node that never sets a real OnClick/OnInput/OnBlur/OnChange
+        // keeps VElement's own shared NoOpEventHandler reference on both
+        // sides (see velement.ks) — comparing by `!=` costs nothing and
+        // skips two real DOM API calls per event per node for the (common)
+        // case of "this node has no handler of this kind either time,"
+        // which matters a lot on a list with hundreds/thousands of rows
+        // most of which set at most one or two of the four. A node WITH a
+        // real handler still gets a fresh closure every render (it
+        // captures per-render values, like a loop's own item), so it still
+        // swaps every time — correctly, since the old closure really is
+        // stale.
+        if (updated.OnClick != oldTree.OnClick) {
+          realNode.removeEventListener("click", oldTree.OnClick);
+          realNode.addEventListener("click", updated.OnClick);
+        }
+        if (updated.OnInput != oldTree.OnInput) {
+          realNode.removeEventListener("input", oldTree.OnInput);
+          realNode.addEventListener("input", updated.OnInput);
+        }
+        if (updated.OnBlur != oldTree.OnBlur) {
+          realNode.removeEventListener("blur", oldTree.OnBlur);
+          realNode.addEventListener("blur", updated.OnBlur);
+        }
+        if (updated.OnChange != oldTree.OnChange) {
+          realNode.removeEventListener("change", oldTree.OnChange);
+          realNode.addEventListener("change", updated.OnChange);
+        }
 
         return realNode;
       }
@@ -155,15 +192,14 @@ Element Patch(Element parent, VElement? old, VElement updated) {
 // guaranteed to follow its data across the reorder — give list items a
 // stable Id for that guarantee.
 void PatchChildren(Element parent, VElement[] oldChildren, VElement[] newChildren) {
-  bool[] oldConsumed = [];
-  for (number i = 0; i < oldChildren.Length; i = i + 1) {
-    oldConsumed = oldConsumed.Push(false);
-  }
-
-  number[] matchedOldIndex = [];
-  for (number i = 0; i < newChildren.Length; i = i + 1) {
-    matchedOldIndex = matchedOldIndex.Push(-1);
-  }
+  // Map, not a Push loop — Push is deliberately non-mutating (a real
+  // spread-copy every call, see KopScript's own README), so building an
+  // n-length array by Push-ing once per element in a loop is an
+  // accidental O(n^2) on every single PatchChildren call, however small
+  // the actual diff. Map is a real, single O(n) pass straight to
+  // Array.prototype.map.
+  bool[] oldConsumed = oldChildren.Map((VElement c) => false);
+  number[] matchedOldIndex = newChildren.Map((VElement c) => -1);
 
   // Pass 1: keyed matches, by Id.
   for (number i = 0; i < newChildren.Length; i = i + 1) {
@@ -193,20 +229,40 @@ void PatchChildren(Element parent, VElement[] oldChildren, VElement[] newChildre
     }
   }
 
-  // Pass 3: patch/create each new child in order, then move it into its
-  // correct final position — appendChild on a node already attached
-  // elsewhere in the DOM MOVES it (real DOM semantics), so processing new
-  // children in their final desired order and always appending naturally
-  // builds up the correct sequence, no separate insertBefore/reference-
-  // node bookkeeping needed. Safe because VElement.Children is always the
-  // COMPLETE list of a node's children — nothing else ever shares `parent`.
+  // Whether anything is actually moving at all — same length, and every
+  // new position matched the *same* old position. The extremely common
+  // case for a list that's only had some of its rows' own content change
+  // (e.g. "update every 10th row"), where reconciliation still has real
+  // work to do (see Pass 1/2 above and Patch() itself) but nothing needs
+  // to physically move in the DOM at all.
+  bool needsReorder = oldChildren.Length != newChildren.Length;
+  for (number i = 0; i < newChildren.Length; i = i + 1) {
+    if (matchedOldIndex[i] != i) {
+      needsReorder = true;
+      break;
+    }
+  }
+
+  // Pass 3: patch/create each new child in order, then — only if the list
+  // actually needs reordering — move it into its correct final position.
+  // appendChild on a node already attached elsewhere in the DOM MOVES it
+  // (real DOM semantics), so processing new children in their final
+  // desired order and always appending naturally builds up the correct
+  // sequence, no separate insertBefore/reference-node bookkeeping needed.
+  // Safe because VElement.Children is always the COMPLETE list of a
+  // node's children — nothing else ever shares `parent`. Skipping the
+  // move entirely when `needsReorder` is false avoids a real DOM API call
+  // per child for the common no-reorder case — Patch() itself already
+  // updates or replaces a reused/changed node exactly in place either way.
   for (number i = 0; i < newChildren.Length; i = i + 1) {
     VElement? matchedOld = null;
     if (matchedOldIndex[i] >= 0) {
       matchedOld = oldChildren[matchedOldIndex[i]];
     }
     Element childNode = Patch(parent, matchedOld, newChildren[i]);
-    parent.appendChild(childNode);
+    if (needsReorder) {
+      parent.appendChild(childNode);
+    }
   }
 
   // Pass 4: remove whatever old children never got reused.

package/src/velement.js

@@ -1,5 +1,7 @@
 import { Event, Element, Document, Location, History, Window, document, location, history, window } from "./dom.js";
 
+export function NoOpEventHandler(e) {
+}
 export class VElement {
   constructor(tag) {
     this.Tag = tag;
@@ -9,14 +11,10 @@ export class VElement {
     this.Value = "";
     this.Children = [];
     this.RawHtml = "";
-    this.OnClick = (e) => {
-};
-    this.OnInput = (e) => {
-};
-    this.OnBlur = (e) => {
-};
-    this.OnChange = (e) => {
-};
+    this.OnClick = NoOpEventHandler;
+    this.OnInput = NoOpEventHandler;
+    this.OnBlur = NoOpEventHandler;
+    this.OnChange = NoOpEventHandler;
     this.ExtraNames = [];
     this.ExtraValues = [];
     this.RealNode = null;

package/src/velement.js.map

@@ -1 +1 @@
-{"version":3,"file":"velement.js","sources":["velement.ks"],"sourcesContent":["using \"./dom\";\n\n// A lightweight, framework-owned description of one DOM element — Render()\n// builds a tree of these instead of real DOM nodes, so Update() can DIFF\n// the new tree against the previous one and patch only what changed,\n// instead of discarding and rebuilding the whole real DOM subtree every\n// time (see src/vdom.ks for the diff/patch engine, src/component.ks for\n// where Render()'s return type changed from Element to VElement).\n//\n// Fixed, named fields — not a generic prop bag — because KopScript has no\n// object-literal syntax to build one with. Fixed, named event slots — not\n// an array of handlers — because KopScript has no array-of-function-values\n// type either. Both are real language constraints, not an oversight; see\n// SetAttr below for the escape hatch covering everything not common enough\n// to deserve its own named field.\nclass VElement {\n  public string Tag;\n  // Mutually exclusive with Children and RawHtml — set at most one of the\n  // three. TextContent/Children mirrors the same \"no mixed text/element\n  // content\" rule KopScript's own templates already enforce.\n  public string TextContent;\n  public string ClassName;\n  public string Id;\n  // The one property patched via direct assignment, never setAttribute —\n  // see Element.value's own comment in dom.ks for why (the \"default value\n  // attribute\" vs \"current live value property\" DOM footgun — the exact\n  // property behind the original typing bug this whole effort traces to).\n  public string Value;\n  public VElement[] Children;\n  // An opaque, undiffed leaf — set instead of TextContent/Children for the\n  // existing raw-HTML-then-wire-handlers pattern (header.ks/nav.ks). The\n  // patch engine treats two VElements with different RawHtml as a single\n  // innerHTML assignment, never recursing inside it — the same \"opaque\n  // blob\" treatment `raw string` already gets everywhere else.\n  public string RawHtml;\n\n  // Each defaults to a real no-op, never null — KopScript has no nullable\n  // *function* type to fall back on for \"no handler set\" (see Router.Guard\n  // for the same default-real-function pattern already established).\n  public (Event) => void OnClick;\n  public (Event) => void OnInput;\n  public (Event) => void OnBlur;\n  public (Event) => void OnChange;\n\n  // A real HTML attribute not common enough for its own named field (href,\n  // src, alt, placeholder, ...) — parallel arrays, since KopScript has no\n  // Dictionary type. Never Value (see its own field comment above). Public,\n  // read directly by the patch engine (src/vdom.ks) rather than through\n  // accessor methods — plain data, same style as this codebase's other\n  // plain classes (Note, Dog, ...).\n  public string[] ExtraNames;\n  public string[] ExtraValues;\n\n  // Set only once this VElement has been materialized into (or reused as)\n  // a real DOM node — null on a freshly-built tree from a not-yet-patched\n  // Render() call. The patch engine reads the *previous* render's tree's\n  // RealNode to know what to reuse/patch; it never reads the live DOM back\n  // to rediscover this (see vdom.ks's own header comment for why).\n  public Element? RealNode;\n\n  constructor(string tag) {\n    this.Tag = tag;\n    this.TextContent = \"\";\n    this.ClassName = \"\";\n    this.Id = \"\";\n    this.Value = \"\";\n    this.Children = [];\n    this.RawHtml = \"\";\n    this.OnClick = (Event e) => {};\n    this.OnInput = (Event e) => {};\n    this.OnBlur = (Event e) => {};\n    this.OnChange = (Event e) => {};\n    this.ExtraNames = [];\n    this.ExtraValues = [];\n    this.RealNode = null;\n  }\n\n  public static VElement Create(string tag) {\n    return new VElement(tag);\n  }\n\n  public void AppendChild(VElement child) {\n    this.Children = this.Children.Push(child);\n  }\n\n  // Last call for a given name wins if SetAttr is called more than once\n  // with the same name on one VElement — the patch engine applies\n  // ExtraNames/ExtraValues in order, so a later entry's setAttribute call\n  // simply overwrites an earlier one for the same name, no special\n  // dedup/replace logic needed here.\n  public void SetAttr(string name, string value) {\n    this.ExtraNames = this.ExtraNames.Push(name);\n    this.ExtraValues = this.ExtraValues.Push(value);\n  }\n}\n"],"names":[],"mappings":";;AAeA;EA6CE;IACW;IACQ;IACF;IACP;IACG;IACG;IACD;IACA;;IACA;;IACD;;IACE;;IACE;IACC;IACH;;;EAGF;IACZ;;;EAGK;IACS;;;EAQT;IACW;IACC"}
+{"version":3,"file":"velement.js","sources":["velement.ks"],"sourcesContent":["using \"./dom\";\n\n// A lightweight, framework-owned description of one DOM element — Render()\n// builds a tree of these instead of real DOM nodes, so Update() can DIFF\n// the new tree against the previous one and patch only what changed,\n// instead of discarding and rebuilding the whole real DOM subtree every\n// time (see src/vdom.ks for the diff/patch engine, src/component.ks for\n// where Render()'s return type changed from Element to VElement).\n//\n// A single shared no-op, not a fresh closure per VElement — every instance\n// that never sets a real handler gets this exact same function reference,\n// so Patch() (vdom.ks) can tell \"no handler either time\" apart from \"a\n// handler changed\" with a plain `!=` reference check instead of always\n// removing/re-adding all four DOM listeners on every patch regardless of\n// whether anything about them actually changed. A fresh `(Event e) => {}`\n// closure per instance would defeat this — two \"empty\" handlers would\n// never compare equal, even when nothing meaningful differs.\nvoid NoOpEventHandler(Event e) {\n}\n\n// Fixed, named fields — not a generic prop bag — because KopScript has no\n// object-literal syntax to build one with. Fixed, named event slots — not\n// an array of handlers — because KopScript has no array-of-function-values\n// type either. Both are real language constraints, not an oversight; see\n// SetAttr below for the escape hatch covering everything not common enough\n// to deserve its own named field.\nclass VElement {\n  public string Tag;\n  // Mutually exclusive with Children and RawHtml — set at most one of the\n  // three. TextContent/Children mirrors the same \"no mixed text/element\n  // content\" rule KopScript's own templates already enforce.\n  public string TextContent;\n  public string ClassName;\n  public string Id;\n  // The one property patched via direct assignment, never setAttribute —\n  // see Element.value's own comment in dom.ks for why (the \"default value\n  // attribute\" vs \"current live value property\" DOM footgun — the exact\n  // property behind the original typing bug this whole effort traces to).\n  public string Value;\n  public VElement[] Children;\n  // An opaque, undiffed leaf — set instead of TextContent/Children for the\n  // existing raw-HTML-then-wire-handlers pattern (header.ks/nav.ks). The\n  // patch engine treats two VElements with different RawHtml as a single\n  // innerHTML assignment, never recursing inside it — the same \"opaque\n  // blob\" treatment `raw string` already gets everywhere else.\n  public string RawHtml;\n\n  // Each defaults to a real no-op, never null — KopScript has no nullable\n  // *function* type to fall back on for \"no handler set\" (see Router.Guard\n  // for the same default-real-function pattern already established).\n  public (Event) => void OnClick;\n  public (Event) => void OnInput;\n  public (Event) => void OnBlur;\n  public (Event) => void OnChange;\n\n  // A real HTML attribute not common enough for its own named field (href,\n  // src, alt, placeholder, ...) — parallel arrays, since KopScript has no\n  // Dictionary type. Never Value (see its own field comment above). Public,\n  // read directly by the patch engine (src/vdom.ks) rather than through\n  // accessor methods — plain data, same style as this codebase's other\n  // plain classes (Note, Dog, ...).\n  public string[] ExtraNames;\n  public string[] ExtraValues;\n\n  // Set only once this VElement has been materialized into (or reused as)\n  // a real DOM node — null on a freshly-built tree from a not-yet-patched\n  // Render() call. The patch engine reads the *previous* render's tree's\n  // RealNode to know what to reuse/patch; it never reads the live DOM back\n  // to rediscover this (see vdom.ks's own header comment for why).\n  public Element? RealNode;\n\n  constructor(string tag) {\n    this.Tag = tag;\n    this.TextContent = \"\";\n    this.ClassName = \"\";\n    this.Id = \"\";\n    this.Value = \"\";\n    this.Children = [];\n    this.RawHtml = \"\";\n    this.OnClick = NoOpEventHandler;\n    this.OnInput = NoOpEventHandler;\n    this.OnBlur = NoOpEventHandler;\n    this.OnChange = NoOpEventHandler;\n    this.ExtraNames = [];\n    this.ExtraValues = [];\n    this.RealNode = null;\n  }\n\n  public static VElement Create(string tag) {\n    return new VElement(tag);\n  }\n\n  public void AppendChild(VElement child) {\n    this.Children = this.Children.Push(child);\n  }\n\n  // Last call for a given name wins if SetAttr is called more than once\n  // with the same name on one VElement — the patch engine applies\n  // ExtraNames/ExtraValues in order, so a later entry's setAttribute call\n  // simply overwrites an earlier one for the same name, no special\n  // dedup/replace logic needed here.\n  public void SetAttr(string name, string value) {\n    this.ExtraNames = this.ExtraNames.Push(name);\n    this.ExtraValues = this.ExtraValues.Push(value);\n  }\n}\n"],"names":[],"mappings":";;AAiBA;;AASA;EA6CE;IACW;IACQ;IACF;IACP;IACG;IACG;IACD;IACA;IACA;IACD;IACE;IACE;IACC;IACH;;;EAGF;IACZ;;;EAGK;IACS;;;EAQT;IACW;IACC"}

package/src/velement.ks

@@ -7,6 +7,17 @@ using "./dom";
 // time (see src/vdom.ks for the diff/patch engine, src/component.ks for
 // where Render()'s return type changed from Element to VElement).
 //
+// A single shared no-op, not a fresh closure per VElement — every instance
+// that never sets a real handler gets this exact same function reference,
+// so Patch() (vdom.ks) can tell "no handler either time" apart from "a
+// handler changed" with a plain `!=` reference check instead of always
+// removing/re-adding all four DOM listeners on every patch regardless of
+// whether anything about them actually changed. A fresh `(Event e) => {}`
+// closure per instance would defeat this — two "empty" handlers would
+// never compare equal, even when nothing meaningful differs.
+void NoOpEventHandler(Event e) {
+}
+
 // Fixed, named fields — not a generic prop bag — because KopScript has no
 // object-literal syntax to build one with. Fixed, named event slots — not
 // an array of handlers — because KopScript has no array-of-function-values
@@ -66,10 +77,10 @@ class VElement {
     this.Value = "";
     this.Children = [];
     this.RawHtml = "";
-    this.OnClick = (Event e) => {};
-    this.OnInput = (Event e) => {};
-    this.OnBlur = (Event e) => {};
-    this.OnChange = (Event e) => {};
+    this.OnClick = NoOpEventHandler;
+    this.OnInput = NoOpEventHandler;
+    this.OnBlur = NoOpEventHandler;
+    this.OnChange = NoOpEventHandler;
     this.ExtraNames = [];
     this.ExtraValues = [];
     this.RealNode = null;