kopular 0.20.0 → 0.21.0

package/LLM.md

@@ -417,14 +417,35 @@ nav.Navigate("/about");                          // pushState + immediate re-ren
   `"/search?sort=name"` -> `Query("sort") == "name"`. Values are **not percent-decoded** —
   no `decodeURIComponent` binding exists yet, a deliberate v1 cut; `%20`/`+` arrive
   exactly as written in the URL, not converted to a space.
-- **Why `Param` is a plain field, not `state<T>`**: `Router`'s own `AfterRender` already
-  re-`Mount()`s the matched page into its outlet on every `Navigate()`/`popstate`, which
+- **Why `Param` is a plain field, not `state<T>`**: `Router`'s own `Render()` already
+  re-embeds the matched page (via `VElement.Mount`) on every `Navigate()`/`popstate`, which
   re-runs that page's own `Render()` (reading the fresh `Param`) with no extra step.
   Making it `state<T>` and having a page `Subscribe()` to it — the pattern every *other*
   piece of state in this framework uses — actually crashes: `Match()` sets it *before*
-  `AfterRender` finishes mounting the matched page into the outlet, so the very first
-  route that matches a page nothing has `Mount()`ed yet fires that page's subscribed
-  listener while its inherited `Update()` still has no `ParentElement` to patch into.
+  the matched page is ever mounted into the outlet, so the very first route that matches a
+  page nothing has `Mount()`ed yet fires that page's subscribed listener while its
+  inherited `Update()` still has no `ParentElement` to patch into.
+- **Lazy routes (real code-splitting) — `AddLazyRoute(path, loader)`**: like `AddRoute`,
+  but `loader` is a `() => task<Component>` instead of an already-built page — its JS chunk
+  is only ever fetched the first time the route actually matches, not eagerly with
+  everything else at startup. `loader` is a real dynamic `import()`, reached via a
+  hand-written loader shim and a relative `extern` (see `kopscript`'s own "extern" docs —
+  `kopscript@0.23.0` fixed a real bug in this exact path):
+  ```js
+  // dogs_page_loader.js
+  export async function LoadDogsPage() {
+    const { DogsPage } = await import("./dogs_page.js");
+    return new DogsPage();
+  }
+  ```
+  ```ks
+  extern task<Component> LoadDogsPage() from "./dogs_page_loader";
+  nav.AddLazyRoute("/dogs", LoadDogsPage);
+  ```
+  The outlet shows a plain loading placeholder (override `BuildLoadingPlaceholder()`) while
+  the fetch is in flight; the loaded page is cached after the first fetch, same as an eager
+  page — navigating away and back reuses it, no re-fetch. Mixes freely with `AddRoute` in
+  the same `Router`.
 - **Navigation guards**: `SetGuard(redirectPath, (string) => bool guard)` — `guard` is
   called with the target path before every navigation (including a direct load/refresh);
   returning `false` redirects to `redirectPath` (via `pushState`, so the URL updates too —

package/README.md

@@ -294,6 +294,37 @@ too (via `pushState`), so refreshing a blocked path lands on the redirect again
 back on the page the guard just rejected — pick a `redirectPath` the guard itself always
 allows, or it loops.
 
+**Lazy routes (real code-splitting)**: `AddRoute` takes an already-built page — its whole
+JS chunk loads eagerly, with everything else, at startup. `AddLazyRoute` takes a *loader*
+instead, so that chunk is only ever fetched the first time its route actually matches:
+
+```ks
+nav.AddLazyRoute("/dogs", LoadDogsPage);
+```
+
+`LoadDogsPage` is a `() => task<Component>` — a real dynamic `import()`, since KopScript's
+own syntax has no expression for one. Write a tiny hand-written loader (not compiled from
+`.ks`) and reach it via a relative `extern` (see KopScript's own `README.md`/`LLM.md`
+"extern" section for the full mechanics — this needed a real compiler fix,
+`kopscript@0.23.0`, to work reliably):
+
+```js
+// dogs_page_loader.js — hand-written
+export async function LoadDogsPage() {
+  const { DogsPage } = await import("./dogs_page.js");
+  return new DogsPage();
+}
+```
+```ks
+extern task<Component> LoadDogsPage() from "./dogs_page_loader";
+```
+
+The outlet shows a plain loading placeholder (override `BuildLoadingPlaceholder()` to
+customize it) while the fetch is in flight, then the real page once it resolves — and,
+like an eager page, it's only ever fetched once: navigating away and back reuses the same
+already-loaded instance, keeping whatever state it built up. A lazy and an eager route mix
+freely in the same `Router`; nothing about `AddRoute`'s own existing signature changes.
+
 **Deploying a Router-based app needs SPA/history-fallback configured on whatever you
 deploy to — this is true of every client-side router in every framework, not a Kopular
 gap.** A direct load or a refresh at `/about` is a plain HTTP request that reaches your

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "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",
@@ -62,7 +62,7 @@
     "@types/jsdom": "^30.0.0",
     "@types/node": "^20.14.0",
     "jsdom": "^25.0.1",
-    "kopscript": "^0.22.0",
+    "kopscript": "^0.23.0",
     "typescript": "^5.5.0",
     "vitest": "^4.1.11"
   },

package/src/router.js

@@ -2,12 +2,47 @@ import { Event, Element, Document, Location, History, Window, document, location
 import { Component } from "./component.js";
 import { VElement, NoOpEventHandler } from "./velement.js";
 
+export class EagerPage {
+  constructor(page) {
+    this.ThePage = page;
+  }
+
+  Peek() {
+    return this.ThePage;
+  }
+
+  async Resolve() {
+    return this.ThePage;
+  }
+}
+export class LazyPage {
+  constructor(loader) {
+    this.Loader = loader;
+    this.CachedValue = null;
+  }
+
+  Peek() {
+    return this.CachedValue;
+  }
+
+  async Resolve() {
+    let maybeCached = this.CachedValue;
+    if ((maybeCached !== null)) {
+      let cached = maybeCached;
+      return cached;
+    }
+    let loaded = await this.Loader();
+    this.CachedValue = loaded;
+    return loaded;
+  }
+}
 export class Router extends Component {
   constructor(notFoundPage) {
     super();
     this.Paths = [];
     this.Pages = [];
-    this.NotFoundPage = notFoundPage;
+    this.NotFoundProvider = new EagerPage(notFoundPage);
+    this.LoadingProvider = null;
     this.Param = "";
     this.ParamNames = [];
     this.ParamValues = [];
@@ -20,7 +55,12 @@ export class Router extends Component {
 
   AddRoute(path, page) {
     this.Paths = [...this.Paths, path];
-    this.Pages = [...this.Pages, page];
+    this.Pages = [...this.Pages, new EagerPage(page)];
+  }
+
+  AddLazyRoute(path, loader) {
+    this.Paths = [...this.Paths, path];
+    this.Pages = [...this.Pages, new LazyPage(loader)];
   }
 
   SetGuard(redirectPath, guard) {
@@ -81,7 +121,7 @@ export class Router extends Component {
     this.ParseQuery(effectivePath);
     let pathAndQuery = effectivePath.split("?");
     let pathSegments = pathAndQuery[0].split("/");
-    let found = this.NotFoundPage;
+    let found = this.NotFoundProvider;
     let foundNames = [];
     let foundValues = [];
     for (let i = 0; (i < this.Paths.length); i = (i + 1)) {
@@ -134,12 +174,43 @@ export class Router extends Component {
 
   Render() {
     let path = (location.pathname + location.search);
-    let page = this.Match(path);
+    let provider = this.Match(path);
     let outlet = VElement.Create("div");
     outlet.ClassName = "router-outlet";
-    outlet.AppendChild(VElement.Mount(page));
+    let maybeResolved = provider.Peek();
+    if ((maybeResolved !== null)) {
+      let resolved = maybeResolved;
+      outlet.AppendChild(VElement.Mount(resolved));
+    } else {
+      let alreadyLoadingThisProvider = false;
+      let maybeLoadingProvider = this.LoadingProvider;
+      if ((maybeLoadingProvider !== null)) {
+        let loadingProvider = maybeLoadingProvider;
+        if ((loadingProvider === provider)) {
+          alreadyLoadingThisProvider = true;
+        }
+      }
+      if (!alreadyLoadingThisProvider) {
+        this.LoadingProvider = provider;
+        this.LoadThenUpdate(provider);
+      }
+      outlet.AppendChild(this.BuildLoadingPlaceholder());
+    }
     return outlet;
   }
+
+  async LoadThenUpdate(provider) {
+    await provider.Resolve();
+    this.LoadingProvider = null;
+    this.Update();
+  }
+
+  BuildLoadingPlaceholder() {
+    let div = VElement.Create("div");
+    div.ClassName = "router-loading";
+    div.TextContent = "Loading...";
+    return div;
+  }
 }
 
 //# sourceMappingURL=router.js.map

package/src/router.js.map

@@ -1 +1 @@
-{"version":3,"file":"router.js","sources":["router.ks"],"sourcesContent":["using \"./dom\";\nusing \"./component\";\nusing \"./velement\";\n\n// History-API routing (real paths — `/about`, not `#/about`) via\n// `history.pushState`/the browser's native `popstate` event. This needs a\n// server that falls back to the app shell for any path it doesn't\n// recognize as a real file (see KopularDemo's scripts/serve.mjs) — a plain\n// static file server has nothing to serve at `/about` on a direct\n// visit/refresh otherwise, unlike hash-based routing, which never leaves\n// the one HTML file the server actually has. Route registration is\n// imperative (`AddRoute` calls), not a config object — one thing to learn,\n// not a routing DSL.\n//\n// Routes are registered as already-constructed Component instances, not\n// factories — `Component[]`, not `(() => Component)[]` (KopScript's type\n// grammar has no way to write \"array of function type\" in v1, since a\n// parenthesized function type isn't a general grouping construct). This\n// turns out to be a genuine feature, not just a workaround: each page\n// Component is built once and kept alive for the Router's own lifetime, so\n// a page's own state<T> fields survive navigating away and back — no state\n// gets reset just because a route wasn't showing for a while.\n//\n// No nullable types in v1 means \"no route matched\" can't be represented as\n// null — a `NotFoundPage` is required up front instead, the same way a\n// `match` expression requires its own `_` wildcard arm.\nclass Router : Component {\n  private string[] Paths;\n  private Component[] Pages;\n  private Component NotFoundPage;\n\n  // The FIRST captured dynamic segment's value (e.g. \"42\" for a\n  // \"/dogs/:id\" route matching \"/dogs/42\"), or \"\" if the matched route has\n  // none — kept exactly as-is (a plain string, not the general Params()\n  // lookup below) so every existing single-dynamic-segment consumer keeps\n  // working unchanged. For a route with more than one captured segment,\n  // use Params(name) instead; this still holds the first one either way.\n  //\n  // A plain field, deliberately **not** state<T> — Render() below always\n  // rebuilds a fresh outlet and re-Mount()s the matched page into it on\n  // every Navigate()/popstate, which already re-runs that page's own\n  // Render() (reading the fresh Param) with no extra step. Subscribing to\n  // it, the way a page reacts to its *own* state<T>, would fire during\n  // Match() itself — before Render() has finished swapping the matched page\n  // in — which crashes the very first time a route no page has been\n  // Mount()ed into yet matches, since a not-yet-mounted Component's\n  // inherited Update() has no ParentElement to replaceChild into.\n  public string Param;\n\n  // Every named dynamic segment captured by whatever route just matched\n  // (\":id\"/\":toyId\" for \"/dogs/:id/toys/:toyId\"), plus the pseudo-name \"*\"\n  // for a trailing wildcard segment's captured remainder — see Params()\n  // below. Parallel arrays (ParamNames[i] <-> ParamValues[i]), the same\n  // convention Paths/Pages above already use — not a Dictionary type,\n  // since KopScript has none.\n  private string[] ParamNames;\n  private string[] ParamValues;\n\n  // The current URL's query string, parsed once per navigation/popstate —\n  // see Query() below. Never part of route *matching* itself in v1: every\n  // route sees whatever query string is actually in the URL, matched or\n  // not. Values are NOT percent-decoded (a deliberate v1 cut — no\n  // decodeURIComponent binding exists yet); a value containing `%20` or\n  // `+` for a space arrives exactly as written in the URL.\n  private string[] QueryKeys;\n  private string[] QueryValues;\n\n  // Checked before every navigation, including a direct load/refresh — not\n  // just Navigate()/popstate. Deliberately one guard for the whole Router,\n  // not per-route: the guard function itself decides which paths it cares\n  // about (typically `path.StartsWith(\"/admin\")`-style checks), the same\n  // \"no config object, just a function\" style Http/DI already use, rather\n  // than a parallel array of per-route guards (which also can't be written\n  // as a type anyway — see AddRoute's own comment on array-of-function\n  // types). Defaults to always-allow, not null — a nullable function TYPE\n  // has the same \"can't parenthesize for a postfix `?`\" problem as an\n  // array of one, so \"no guard configured\" is a real function that always\n  // returns true, not a null check.\n  private (string) => bool Guard;\n  private string RedirectPath;\n\n  constructor(Component notFoundPage) : base() {\n    this.Paths = [];\n    this.Pages = [];\n    this.NotFoundPage = notFoundPage;\n    this.Param = \"\";\n    this.ParamNames = [];\n    this.ParamValues = [];\n    this.QueryKeys = [];\n    this.QueryValues = [];\n    this.Guard = (string path) => true;\n    this.RedirectPath = \"\";\n    // 'popstate' only fires on browser back/forward (or history.go/back/\n    // forward) — never on pushState itself, unlike hashchange firing\n    // whenever location.hash is set. Navigate() below calls Update()\n    // directly for that reason; this listener only covers the back/forward\n    // case, where the URL changes without any of our own code running.\n    window.addEventListener(\"popstate\", (Event e) => this.Update());\n  }\n\n  // A path segment written \":name\" (e.g. \"dogs/:id\") matches any single\n  // non-empty segment; every other segment must match literally, except a\n  // trailing \"*\" segment (e.g. \"files/*\"), which matches one or more\n  // remaining segments as a single captured group (see Params(\"*\")).\n  // Comparing segment-by-segment (rather than the whole string at once) is\n  // what makes a static route's own matching still exactly as strict as a\n  // plain `==` was before — same segment count, same literal text\n  // throughout (a trailing \"*\" route aside, which only ever needs *at\n  // least* as many path segments as its static prefix).\n  public void AddRoute(string path, Component page) {\n    this.Paths = this.Paths.Push(path);\n    this.Pages = this.Pages.Push(page);\n  }\n\n  // `guard` is called with the path being navigated to; returning false\n  // redirects to `redirectPath` instead (updating the URL via pushState, so\n  // a refresh on the blocked path lands on the redirect too, not back on\n  // the page the guard just rejected). `redirectPath` itself is never\n  // guard-checked — pick one the guard always allows, or it'll loop.\n  public void SetGuard(string redirectPath, (string) => bool guard) {\n    this.RedirectPath = redirectPath;\n    this.Guard = guard;\n  }\n\n  public void Navigate(string path) {\n    history.pushState(\"\", \"\", path);\n    this.Update();\n  }\n\n  // The captured value for a named dynamic segment (e.g. \"toyId\" for\n  // \":toyId\" in \"/dogs/:id/toys/:toyId\") or \"*\" for a trailing wildcard\n  // segment's matched remainder — \"\" if `name` wasn't captured by whatever\n  // route just matched, the same \"empty string, not null\" convention\n  // `Param` itself already uses.\n  public string Params(string name) {\n    for (number i = 0; i < this.ParamNames.Length; i = i + 1) {\n      if (this.ParamNames[i] == name) {\n        return this.ParamValues[i];\n      }\n    }\n    return \"\";\n  }\n\n  // The current URL's query-string value for `key` (e.g. \"name\" for\n  // \"?sort=name\") — \"\" if `key` isn't present. See QueryKeys/QueryValues'\n  // own comment for the percent-decoding cut.\n  public string Query(string key) {\n    for (number i = 0; i < this.QueryKeys.Length; i = i + 1) {\n      if (this.QueryKeys[i] == key) {\n        return this.QueryValues[i];\n      }\n    }\n    return \"\";\n  }\n\n  // KopScript strings have no index-based substring/slice method (only\n  // arrays do — see Array.Slice), so splitting on the literal separator and\n  // taking the piece after it is the idiomatic way to strip a known\n  // single-character prefix here, both for \"?\" (query string) and \":\"\n  // (a pattern segment's own leading marker, used below in Match).\n  private void ParseQuery(string pathWithQuery) {\n    this.QueryKeys = [];\n    this.QueryValues = [];\n    string[] afterMark = pathWithQuery.Split(\"?\");\n    if (afterMark.Length < 2) { return; }\n    string rawQuery = afterMark[1];\n    if (rawQuery.Length == 0) { return; }\n    string[] pairs = rawQuery.Split(\"&\");\n    foreach (string pair in pairs) {\n      string[] kv = pair.Split(\"=\");\n      if (kv.Length == 2) {\n        this.QueryKeys = this.QueryKeys.Push(kv[0]);\n        this.QueryValues = this.QueryValues.Push(kv[1]);\n      }\n    }\n  }\n\n  private Component Match(string fullPath) {\n    string effectivePath = fullPath;\n    if (!this.Guard(fullPath)) {\n      history.pushState(\"\", \"\", this.RedirectPath);\n      effectivePath = this.RedirectPath;\n    }\n\n    this.ParseQuery(effectivePath);\n    string[] pathAndQuery = effectivePath.Split(\"?\");\n    string[] pathSegments = pathAndQuery[0].Split(\"/\");\n\n    Component found = this.NotFoundPage;\n    string[] foundNames = [];\n    string[] foundValues = [];\n\n    for (number i = 0; i < this.Paths.Length; i = i + 1) {\n      string[] patternSegments = this.Paths[i].Split(\"/\");\n      bool hasWildcard = patternSegments.Length > 0 && patternSegments[patternSegments.Length - 1] == \"*\";\n\n      number staticCount = patternSegments.Length;\n      if (hasWildcard) {\n        staticCount = patternSegments.Length - 1;\n      }\n\n      if (hasWildcard) {\n        if (pathSegments.Length < staticCount) { continue; }\n      } else {\n        if (patternSegments.Length != pathSegments.Length) { continue; }\n      }\n\n      bool matched = true;\n      string[] names = [];\n      string[] values = [];\n      for (number j = 0; j < staticCount; j = j + 1) {\n        if (patternSegments[j].StartsWith(\":\")) {\n          names = names.Push(patternSegments[j].Split(\":\")[1]);\n          values = values.Push(pathSegments[j]);\n        } else if (patternSegments[j] != pathSegments[j]) {\n          matched = false;\n          break;\n        }\n      }\n\n      if (matched && hasWildcard) {\n        names = names.Push(\"*\");\n        values = values.Push(pathSegments.Slice(staticCount, pathSegments.Length).Join(\"/\"));\n      }\n\n      if (matched) {\n        found = this.Pages[i];\n        foundNames = names;\n        foundValues = values;\n        break;\n      }\n    }\n\n    this.ParamNames = foundNames;\n    this.ParamValues = foundValues;\n    this.Param = \"\";\n    if (foundValues.Length > 0) {\n      this.Param = foundValues[0];\n    }\n    return found;\n  }\n\n  // The outlet itself is a plain, unchanging `<div>` — its tag/className\n  // never change between navigations, so Component's own diffing (see\n  // vdom.ks) reuses the exact same real outlet element across every\n  // navigation, rather than rebuilding it. What goes *inside* it (the\n  // matched page) is embedded via VElement.Mount — a single child, so it\n  // needs no .Id (there's never more than one to key against; positional\n  // matching is unambiguous). Navigating to a DIFFERENT page than last\n  // time is a different Mountable instance in the slot, so Patch() tears\n  // the old one down (Teardown() — its OnUnmount fires, IsMounted resets)\n  // and mounts the new one fresh — matching this class's original\n  // behavior exactly (every navigation always freshly Mount()s the\n  // matched page; a page's own re-renders, once mounted, still go through\n  // the normal diffed Update() path when its own state changes). The one\n  // real change from before: a page navigated AWAY from now actually gets\n  // torn down (OnUnmount fires) instead of being silently abandoned with\n  // its DOM ripped out from under it and IsMounted left permanently true.\n  public override VElement Render() {\n    string path = location.pathname + location.search;\n    Component page = this.Match(path);\n\n    VElement outlet = VElement.Create(\"div\");\n    outlet.ClassName = \"router-outlet\";\n    outlet.AppendChild(VElement.Mount(page));\n    return outlet;\n  }\n}\n"],"names":[],"mappings":";;;;AA0BA;EAuDE;;IACa;IACA;IACO;IACP;IACK;IACC;IACF;IACE;IACN;IACO;IAMK;;;EAYlB;IACM;IACA;;;EAQN;IACa;IACP;;;EAGN;IACY;IACN;;;EAQN;IACL;MACE;QACE;;;IAGJ;;;EAMK;IACL;MACE;QACE;;;IAGJ;;;EAQM;IACS;IACE;IACjB;IACA;MAA4B;;IAC5B;IACA;MAA4B;;IAC5B;IACA;MACE;MACA;QACiB;QACE;;;;;EAKf;IACN;IACA;MACmB;MACH;;IAGD;IACf;IACA;IAEA;IACA;IACA;IAEA;MACE;MACA;MAEA;MACA;QACc;;MAGd;QACE;UAAyC;;;QAEzC;UAAqD;;;MAGvD;MACA;MACA;MACA;QACE;UACQ;UACC;;UAEC;UACR;;;MAIJ;QACQ;QACC;;MAGT;QACQ;QACK;QACC;QACZ;;;IAIY;IACC;IACN;IACX;MACa;;IAEb;;;EAmBc;IACd;IACA;IAEA;IACiB;IACC;IAClB"}
+{"version":3,"file":"router.js","sources":["router.ks"],"sourcesContent":["using \"./dom\";\nusing \"./component\";\nusing \"./velement\";\n\n// History-API routing (real paths — `/about`, not `#/about`) via\n// `history.pushState`/the browser's native `popstate` event. This needs a\n// server that falls back to the app shell for any path it doesn't\n// recognize as a real file (see KopularDemo's scripts/serve.mjs) — a plain\n// static file server has nothing to serve at `/about` on a direct\n// visit/refresh otherwise, unlike hash-based routing, which never leaves\n// the one HTML file the server actually has. Route registration is\n// imperative (`AddRoute` calls), not a config object — one thing to learn,\n// not a routing DSL.\n//\n// AddRoute registers an already-constructed Component; AddLazyRoute\n// registers a loader instead, for real code-splitting (see PageProvider/\n// LazyPage below) — but neither is stored as a raw function value in an\n// array (`Component[]`/`(() => Component)[]`): KopScript's type grammar\n// has no way to write \"array of function type\" in v1 (a parenthesized\n// function type isn't a general grouping construct), so both cases are\n// wrapped in a PageProvider instance instead, and it's `PageProvider[]`\n// that's actually stored. Either way, once a page is built (eagerly at\n// registration, or on first navigation for a lazy one) it's kept alive\n// for the Router's own lifetime, so its own state<T> fields survive\n// navigating away and back — no state gets reset just because a route\n// wasn't showing for a while.\n//\n// No nullable types in v1 means \"no route matched\" can't be represented as\n// null — a `NotFoundPage` is required up front instead, the same way a\n// `match` expression requires its own `_` wildcard arm.\n// A registered route's page, either already built (EagerPage — every\n// route registered via the original AddRoute) or not fetched yet\n// (LazyPage — AddLazyRoute, real code-splitting: the page's own JS chunk\n// is only ever requested the first time its route actually matches, not\n// eagerly with everything else at startup). Router itself only ever\n// touches a route through this interface, never caring which case it is.\ninterface PageProvider {\n  // Synchronous: the resolved Component if one is already available (an\n  // EagerPage always has one; a LazyPage does once its own Resolve() has\n  // completed at least once), or null if not yet loaded. Router's own\n  // Render() calls this on every render to decide whether to mount the\n  // real page or show a loading placeholder — never triggers a fetch by\n  // itself.\n  Component? Peek();\n\n  // Produces the resolved Component, fetching it if this is the first\n  // call (a LazyPage calls its own loader exactly once, ever, caching the\n  // result — every later call, on this or a repeat navigation, returns\n  // the SAME cached instance, preserving the same \"a page stays alive and\n  // keeps its own state across navigations\" guarantee eager pages already\n  // have). An EagerPage already has its Component, so this just returns\n  // it immediately.\n  task<Component> Resolve();\n}\n\nclass EagerPage : PageProvider {\n  private Component ThePage;\n  constructor(Component page) { this.ThePage = page; }\n  public Component? Peek() { return this.ThePage; }\n  public async task<Component> Resolve() { return this.ThePage; }\n}\n\nclass LazyPage : PageProvider {\n  private () => task<Component> Loader;\n  private Component? CachedValue;\n\n  constructor(() => task<Component> loader) {\n    this.Loader = loader;\n    this.CachedValue = null;\n  }\n\n  public Component? Peek() {\n    return this.CachedValue;\n  }\n\n  public async task<Component> Resolve() {\n    Component? maybeCached = this.CachedValue;\n    if (maybeCached != null) {\n      Component cached = maybeCached;\n      return cached;\n    }\n    Component loaded = await this.Loader();\n    this.CachedValue = loaded;\n    return loaded;\n  }\n}\n\nclass Router : Component {\n  private string[] Paths;\n  private PageProvider[] Pages;\n  private PageProvider NotFoundProvider;\n  // Tracks whichever PageProvider is currently being Resolve()d, if any —\n  // compared by reference identity so navigating to a SECOND lazy route\n  // while a FIRST one is still loading starts loading the second instead\n  // of getting stuck waiting on a load nothing will ever re-render for\n  // (Peek() will never return non-null for the route actually showing).\n  // Reset to null once that specific load finishes.\n  private PageProvider? LoadingProvider;\n\n  // The FIRST captured dynamic segment's value (e.g. \"42\" for a\n  // \"/dogs/:id\" route matching \"/dogs/42\"), or \"\" if the matched route has\n  // none — kept exactly as-is (a plain string, not the general Params()\n  // lookup below) so every existing single-dynamic-segment consumer keeps\n  // working unchanged. For a route with more than one captured segment,\n  // use Params(name) instead; this still holds the first one either way.\n  //\n  // A plain field, deliberately **not** state<T> — Render() below always\n  // rebuilds a fresh outlet and re-Mount()s the matched page into it on\n  // every Navigate()/popstate, which already re-runs that page's own\n  // Render() (reading the fresh Param) with no extra step. Subscribing to\n  // it, the way a page reacts to its *own* state<T>, would fire during\n  // Match() itself — before Render() has finished swapping the matched page\n  // in — which crashes the very first time a route no page has been\n  // Mount()ed into yet matches, since a not-yet-mounted Component's\n  // inherited Update() has no ParentElement to replaceChild into.\n  public string Param;\n\n  // Every named dynamic segment captured by whatever route just matched\n  // (\":id\"/\":toyId\" for \"/dogs/:id/toys/:toyId\"), plus the pseudo-name \"*\"\n  // for a trailing wildcard segment's captured remainder — see Params()\n  // below. Parallel arrays (ParamNames[i] <-> ParamValues[i]), the same\n  // convention Paths/Pages above already use — not a Dictionary type,\n  // since KopScript has none.\n  private string[] ParamNames;\n  private string[] ParamValues;\n\n  // The current URL's query string, parsed once per navigation/popstate —\n  // see Query() below. Never part of route *matching* itself in v1: every\n  // route sees whatever query string is actually in the URL, matched or\n  // not. Values are NOT percent-decoded (a deliberate v1 cut — no\n  // decodeURIComponent binding exists yet); a value containing `%20` or\n  // `+` for a space arrives exactly as written in the URL.\n  private string[] QueryKeys;\n  private string[] QueryValues;\n\n  // Checked before every navigation, including a direct load/refresh — not\n  // just Navigate()/popstate. Deliberately one guard for the whole Router,\n  // not per-route: the guard function itself decides which paths it cares\n  // about (typically `path.StartsWith(\"/admin\")`-style checks), the same\n  // \"no config object, just a function\" style Http/DI already use, rather\n  // than a parallel array of per-route guards (which also can't be written\n  // as a type anyway — see AddRoute's own comment on array-of-function\n  // types). Defaults to always-allow, not null — a nullable function TYPE\n  // has the same \"can't parenthesize for a postfix `?`\" problem as an\n  // array of one, so \"no guard configured\" is a real function that always\n  // returns true, not a null check.\n  private (string) => bool Guard;\n  private string RedirectPath;\n\n  constructor(Component notFoundPage) : base() {\n    this.Paths = [];\n    this.Pages = [];\n    this.NotFoundProvider = new EagerPage(notFoundPage);\n    this.LoadingProvider = null;\n    this.Param = \"\";\n    this.ParamNames = [];\n    this.ParamValues = [];\n    this.QueryKeys = [];\n    this.QueryValues = [];\n    this.Guard = (string path) => true;\n    this.RedirectPath = \"\";\n    // 'popstate' only fires on browser back/forward (or history.go/back/\n    // forward) — never on pushState itself, unlike hashchange firing\n    // whenever location.hash is set. Navigate() below calls Update()\n    // directly for that reason; this listener only covers the back/forward\n    // case, where the URL changes without any of our own code running.\n    window.addEventListener(\"popstate\", (Event e) => this.Update());\n  }\n\n  // A path segment written \":name\" (e.g. \"dogs/:id\") matches any single\n  // non-empty segment; every other segment must match literally, except a\n  // trailing \"*\" segment (e.g. \"files/*\"), which matches one or more\n  // remaining segments as a single captured group (see Params(\"*\")).\n  // Comparing segment-by-segment (rather than the whole string at once) is\n  // what makes a static route's own matching still exactly as strict as a\n  // plain `==` was before — same segment count, same literal text\n  // throughout (a trailing \"*\" route aside, which only ever needs *at\n  // least* as many path segments as its static prefix).\n  public void AddRoute(string path, Component page) {\n    this.Paths = this.Paths.Push(path);\n    this.Pages = this.Pages.Push(new EagerPage(page));\n  }\n\n  // Real code-splitting: `loader` is a hand-written JS shim's dynamic\n  // `import()`, reached via `extern task<Component> Load...() from\n  // \"./loader\";` (see kopscript's own LLM.md/README.md \"extern\" section)\n  // — its target module is only ever fetched the first time this route\n  // actually matches, not eagerly with every other page at startup. The\n  // loaded page still stays alive across navigations exactly like an\n  // eager one does (LazyPage caches it after the first Resolve()); only\n  // the FIRST time this route is visited pays the fetch cost.\n  public void AddLazyRoute(string path, () => task<Component> loader) {\n    this.Paths = this.Paths.Push(path);\n    this.Pages = this.Pages.Push(new LazyPage(loader));\n  }\n\n  // `guard` is called with the path being navigated to; returning false\n  // redirects to `redirectPath` instead (updating the URL via pushState, so\n  // a refresh on the blocked path lands on the redirect too, not back on\n  // the page the guard just rejected). `redirectPath` itself is never\n  // guard-checked — pick one the guard always allows, or it'll loop.\n  public void SetGuard(string redirectPath, (string) => bool guard) {\n    this.RedirectPath = redirectPath;\n    this.Guard = guard;\n  }\n\n  public void Navigate(string path) {\n    history.pushState(\"\", \"\", path);\n    this.Update();\n  }\n\n  // The captured value for a named dynamic segment (e.g. \"toyId\" for\n  // \":toyId\" in \"/dogs/:id/toys/:toyId\") or \"*\" for a trailing wildcard\n  // segment's matched remainder — \"\" if `name` wasn't captured by whatever\n  // route just matched, the same \"empty string, not null\" convention\n  // `Param` itself already uses.\n  public string Params(string name) {\n    for (number i = 0; i < this.ParamNames.Length; i = i + 1) {\n      if (this.ParamNames[i] == name) {\n        return this.ParamValues[i];\n      }\n    }\n    return \"\";\n  }\n\n  // The current URL's query-string value for `key` (e.g. \"name\" for\n  // \"?sort=name\") — \"\" if `key` isn't present. See QueryKeys/QueryValues'\n  // own comment for the percent-decoding cut.\n  public string Query(string key) {\n    for (number i = 0; i < this.QueryKeys.Length; i = i + 1) {\n      if (this.QueryKeys[i] == key) {\n        return this.QueryValues[i];\n      }\n    }\n    return \"\";\n  }\n\n  // KopScript strings have no index-based substring/slice method (only\n  // arrays do — see Array.Slice), so splitting on the literal separator and\n  // taking the piece after it is the idiomatic way to strip a known\n  // single-character prefix here, both for \"?\" (query string) and \":\"\n  // (a pattern segment's own leading marker, used below in Match).\n  private void ParseQuery(string pathWithQuery) {\n    this.QueryKeys = [];\n    this.QueryValues = [];\n    string[] afterMark = pathWithQuery.Split(\"?\");\n    if (afterMark.Length < 2) { return; }\n    string rawQuery = afterMark[1];\n    if (rawQuery.Length == 0) { return; }\n    string[] pairs = rawQuery.Split(\"&\");\n    foreach (string pair in pairs) {\n      string[] kv = pair.Split(\"=\");\n      if (kv.Length == 2) {\n        this.QueryKeys = this.QueryKeys.Push(kv[0]);\n        this.QueryValues = this.QueryValues.Push(kv[1]);\n      }\n    }\n  }\n\n  private PageProvider Match(string fullPath) {\n    string effectivePath = fullPath;\n    if (!this.Guard(fullPath)) {\n      history.pushState(\"\", \"\", this.RedirectPath);\n      effectivePath = this.RedirectPath;\n    }\n\n    this.ParseQuery(effectivePath);\n    string[] pathAndQuery = effectivePath.Split(\"?\");\n    string[] pathSegments = pathAndQuery[0].Split(\"/\");\n\n    PageProvider found = this.NotFoundProvider;\n    string[] foundNames = [];\n    string[] foundValues = [];\n\n    for (number i = 0; i < this.Paths.Length; i = i + 1) {\n      string[] patternSegments = this.Paths[i].Split(\"/\");\n      bool hasWildcard = patternSegments.Length > 0 && patternSegments[patternSegments.Length - 1] == \"*\";\n\n      number staticCount = patternSegments.Length;\n      if (hasWildcard) {\n        staticCount = patternSegments.Length - 1;\n      }\n\n      if (hasWildcard) {\n        if (pathSegments.Length < staticCount) { continue; }\n      } else {\n        if (patternSegments.Length != pathSegments.Length) { continue; }\n      }\n\n      bool matched = true;\n      string[] names = [];\n      string[] values = [];\n      for (number j = 0; j < staticCount; j = j + 1) {\n        if (patternSegments[j].StartsWith(\":\")) {\n          names = names.Push(patternSegments[j].Split(\":\")[1]);\n          values = values.Push(pathSegments[j]);\n        } else if (patternSegments[j] != pathSegments[j]) {\n          matched = false;\n          break;\n        }\n      }\n\n      if (matched && hasWildcard) {\n        names = names.Push(\"*\");\n        values = values.Push(pathSegments.Slice(staticCount, pathSegments.Length).Join(\"/\"));\n      }\n\n      if (matched) {\n        found = this.Pages[i];\n        foundNames = names;\n        foundValues = values;\n        break;\n      }\n    }\n\n    this.ParamNames = foundNames;\n    this.ParamValues = foundValues;\n    this.Param = \"\";\n    if (foundValues.Length > 0) {\n      this.Param = foundValues[0];\n    }\n    return found;\n  }\n\n  // The outlet itself is a plain, unchanging `<div>` — its tag/className\n  // never change between navigations, so Component's own diffing (see\n  // vdom.ks) reuses the exact same real outlet element across every\n  // navigation, rather than rebuilding it. What goes *inside* it (the\n  // matched page) is embedded via VElement.Mount — a single child, so it\n  // needs no .Id (there's never more than one to key against; positional\n  // matching is unambiguous). Navigating to a DIFFERENT page than last\n  // time is a different Mountable instance in the slot, so Patch() tears\n  // the old one down (Teardown() — its OnUnmount fires, IsMounted resets)\n  // and mounts the new one fresh — matching this class's original\n  // behavior exactly (every navigation always freshly Mount()s the\n  // matched page; a page's own re-renders, once mounted, still go through\n  // the normal diffed Update() path when its own state changes). The one\n  // real change from before: a page navigated AWAY from now actually gets\n  // torn down (OnUnmount fires) instead of being silently abandoned with\n  // its DOM ripped out from under it and IsMounted left permanently true.\n  public override VElement Render() {\n    string path = location.pathname + location.search;\n    PageProvider provider = this.Match(path);\n\n    VElement outlet = VElement.Create(\"div\");\n    outlet.ClassName = \"router-outlet\";\n\n    Component? maybeResolved = provider.Peek();\n    if (maybeResolved != null) {\n      Component resolved = maybeResolved;\n      outlet.AppendChild(VElement.Mount(resolved));\n    } else {\n      bool alreadyLoadingThisProvider = false;\n      PageProvider? maybeLoadingProvider = this.LoadingProvider;\n      if (maybeLoadingProvider != null) {\n        PageProvider loadingProvider = maybeLoadingProvider;\n        if (loadingProvider == provider) {\n          alreadyLoadingThisProvider = true;\n        }\n      }\n      if (!alreadyLoadingThisProvider) {\n        this.LoadingProvider = provider;\n        this.LoadThenUpdate(provider);\n      }\n      outlet.AppendChild(this.BuildLoadingPlaceholder());\n    }\n    return outlet;\n  }\n\n  // Fire-and-forget from Render()'s own point of view — there's no way to\n  // construct a task value outside an async function body to await it\n  // there instead (see kopscript's own LLM.md \"Async\" docs), the same\n  // reason Component's own OnUnmount-cascading Teardown() isn't awaited\n  // by its own caller either. Calls this.Update() once the fetch actually\n  // lands, so Render() runs again and this time provider.Peek() returns\n  // the now-cached page instead of null.\n  private async task LoadThenUpdate(PageProvider provider) {\n    await provider.Resolve();\n    this.LoadingProvider = null;\n    this.Update();\n  }\n\n  // Shown in the outlet while a lazily-loaded route's own page is still\n  // being fetched (AddLazyRoute) — never shown for an eager route, which\n  // always has a Component to Peek() immediately. Override to customize;\n  // default is a plain, unstyled placeholder so a real app always sees\n  // SOMETHING rather than a silently blank outlet while a chunk loads.\n  protected virtual VElement BuildLoadingPlaceholder() {\n    VElement div = VElement.Create(\"div\");\n    div.ClassName = \"router-loading\";\n    div.TextContent = \"Loading...\";\n    return div;\n  }\n}\n"],"names":[],"mappings":";;;;AAuDA;EAEE;IAA2C;;;EACpC;IAAoB;;;EACd;IAA4B;;;AAG3C;EAIE;IACc;IACK;;;EAGZ;IACL;;;EAGW;IACX;IACA;MACE;MACA;;IAEF;IACiB;IACjB;;;AAIJ;EA8DE;;IACa;IACA;IACW;IACD;IACV;IACK;IACC;IACF;IACE;IACN;IACO;IAMK;;;EAYlB;IACM;IACA;;;EAWN;IACM;IACA;;;EAQN;IACa;IACP;;;EAGN;IACY;IACN;;;EAQN;IACL;MACE;QACE;;;IAGJ;;;EAMK;IACL;MACE;QACE;;;IAGJ;;;EAQM;IACS;IACE;IACjB;IACA;MAA4B;;IAC5B;IACA;MAA4B;;IAC5B;IACA;MACE;MACA;QACiB;QACE;;;;;EAKf;IACN;IACA;MACmB;MACH;;IAGD;IACf;IACA;IAEA;IACA;IACA;IAEA;MACE;MACA;MAEA;MACA;QACc;;MAGd;QACE;UAAyC;;;QAEzC;UAAqD;;;MAGvD;MACA;MACA;MACA;QACE;UACQ;UACC;;UAEC;UACR;;;MAIJ;QACQ;QACC;;MAGT;QACQ;QACK;QACC;QACZ;;;IAIY;IACC;IACN;IACX;MACa;;IAEb;;;EAmBc;IACd;IACA;IAEA;IACiB;IAEjB;IACA;MACE;MACkB;;MAElB;MACA;MACA;QACE;QACA;UAC6B;;;MAG/B;QACuB;QACF;;MAEH;;IAEpB;;;EAUY;IACZ;IACqB;IACV;;;EAQK;IAChB;IACc;IACE;IAChB"}

package/src/router.ks

@@ -12,22 +12,90 @@ using "./velement";
 // imperative (`AddRoute` calls), not a config object — one thing to learn,
 // not a routing DSL.
 //
-// Routes are registered as already-constructed Component instances, not
-// factories — `Component[]`, not `(() => Component)[]` (KopScript's type
-// grammar has no way to write "array of function type" in v1, since a
-// parenthesized function type isn't a general grouping construct). This
-// turns out to be a genuine feature, not just a workaround: each page
-// Component is built once and kept alive for the Router's own lifetime, so
-// a page's own state<T> fields survive navigating away and back — no state
-// gets reset just because a route wasn't showing for a while.
+// AddRoute registers an already-constructed Component; AddLazyRoute
+// registers a loader instead, for real code-splitting (see PageProvider/
+// LazyPage below) — but neither is stored as a raw function value in an
+// array (`Component[]`/`(() => Component)[]`): KopScript's type grammar
+// has no way to write "array of function type" in v1 (a parenthesized
+// function type isn't a general grouping construct), so both cases are
+// wrapped in a PageProvider instance instead, and it's `PageProvider[]`
+// that's actually stored. Either way, once a page is built (eagerly at
+// registration, or on first navigation for a lazy one) it's kept alive
+// for the Router's own lifetime, so its own state<T> fields survive
+// navigating away and back — no state gets reset just because a route
+// wasn't showing for a while.
 //
 // No nullable types in v1 means "no route matched" can't be represented as
 // null — a `NotFoundPage` is required up front instead, the same way a
 // `match` expression requires its own `_` wildcard arm.
+// A registered route's page, either already built (EagerPage — every
+// route registered via the original AddRoute) or not fetched yet
+// (LazyPage — AddLazyRoute, real code-splitting: the page's own JS chunk
+// is only ever requested the first time its route actually matches, not
+// eagerly with everything else at startup). Router itself only ever
+// touches a route through this interface, never caring which case it is.
+interface PageProvider {
+  // Synchronous: the resolved Component if one is already available (an
+  // EagerPage always has one; a LazyPage does once its own Resolve() has
+  // completed at least once), or null if not yet loaded. Router's own
+  // Render() calls this on every render to decide whether to mount the
+  // real page or show a loading placeholder — never triggers a fetch by
+  // itself.
+  Component? Peek();
+
+  // Produces the resolved Component, fetching it if this is the first
+  // call (a LazyPage calls its own loader exactly once, ever, caching the
+  // result — every later call, on this or a repeat navigation, returns
+  // the SAME cached instance, preserving the same "a page stays alive and
+  // keeps its own state across navigations" guarantee eager pages already
+  // have). An EagerPage already has its Component, so this just returns
+  // it immediately.
+  task<Component> Resolve();
+}
+
+class EagerPage : PageProvider {
+  private Component ThePage;
+  constructor(Component page) { this.ThePage = page; }
+  public Component? Peek() { return this.ThePage; }
+  public async task<Component> Resolve() { return this.ThePage; }
+}
+
+class LazyPage : PageProvider {
+  private () => task<Component> Loader;
+  private Component? CachedValue;
+
+  constructor(() => task<Component> loader) {
+    this.Loader = loader;
+    this.CachedValue = null;
+  }
+
+  public Component? Peek() {
+    return this.CachedValue;
+  }
+
+  public async task<Component> Resolve() {
+    Component? maybeCached = this.CachedValue;
+    if (maybeCached != null) {
+      Component cached = maybeCached;
+      return cached;
+    }
+    Component loaded = await this.Loader();
+    this.CachedValue = loaded;
+    return loaded;
+  }
+}
+
 class Router : Component {
   private string[] Paths;
-  private Component[] Pages;
-  private Component NotFoundPage;
+  private PageProvider[] Pages;
+  private PageProvider NotFoundProvider;
+  // Tracks whichever PageProvider is currently being Resolve()d, if any —
+  // compared by reference identity so navigating to a SECOND lazy route
+  // while a FIRST one is still loading starts loading the second instead
+  // of getting stuck waiting on a load nothing will ever re-render for
+  // (Peek() will never return non-null for the route actually showing).
+  // Reset to null once that specific load finishes.
+  private PageProvider? LoadingProvider;
 
   // The FIRST captured dynamic segment's value (e.g. "42" for a
   // "/dogs/:id" route matching "/dogs/42"), or "" if the matched route has
@@ -82,7 +150,8 @@ class Router : Component {
   constructor(Component notFoundPage) : base() {
     this.Paths = [];
     this.Pages = [];
-    this.NotFoundPage = notFoundPage;
+    this.NotFoundProvider = new EagerPage(notFoundPage);
+    this.LoadingProvider = null;
     this.Param = "";
     this.ParamNames = [];
     this.ParamValues = [];
@@ -109,7 +178,20 @@ class Router : Component {
   // least* as many path segments as its static prefix).
   public void AddRoute(string path, Component page) {
     this.Paths = this.Paths.Push(path);
-    this.Pages = this.Pages.Push(page);
+    this.Pages = this.Pages.Push(new EagerPage(page));
+  }
+
+  // Real code-splitting: `loader` is a hand-written JS shim's dynamic
+  // `import()`, reached via `extern task<Component> Load...() from
+  // "./loader";` (see kopscript's own LLM.md/README.md "extern" section)
+  // — its target module is only ever fetched the first time this route
+  // actually matches, not eagerly with every other page at startup. The
+  // loaded page still stays alive across navigations exactly like an
+  // eager one does (LazyPage caches it after the first Resolve()); only
+  // the FIRST time this route is visited pays the fetch cost.
+  public void AddLazyRoute(string path, () => task<Component> loader) {
+    this.Paths = this.Paths.Push(path);
+    this.Pages = this.Pages.Push(new LazyPage(loader));
   }
 
   // `guard` is called with the path being navigated to; returning false
@@ -175,7 +257,7 @@ class Router : Component {
     }
   }
 
-  private Component Match(string fullPath) {
+  private PageProvider Match(string fullPath) {
     string effectivePath = fullPath;
     if (!this.Guard(fullPath)) {
       history.pushState("", "", this.RedirectPath);
@@ -186,7 +268,7 @@ class Router : Component {
     string[] pathAndQuery = effectivePath.Split("?");
     string[] pathSegments = pathAndQuery[0].Split("/");
 
-    Component found = this.NotFoundPage;
+    PageProvider found = this.NotFoundProvider;
     string[] foundNames = [];
     string[] foundValues = [];
 
@@ -258,11 +340,55 @@ class Router : Component {
   // its DOM ripped out from under it and IsMounted left permanently true.
   public override VElement Render() {
     string path = location.pathname + location.search;
-    Component page = this.Match(path);
+    PageProvider provider = this.Match(path);
 
     VElement outlet = VElement.Create("div");
     outlet.ClassName = "router-outlet";
-    outlet.AppendChild(VElement.Mount(page));
+
+    Component? maybeResolved = provider.Peek();
+    if (maybeResolved != null) {
+      Component resolved = maybeResolved;
+      outlet.AppendChild(VElement.Mount(resolved));
+    } else {
+      bool alreadyLoadingThisProvider = false;
+      PageProvider? maybeLoadingProvider = this.LoadingProvider;
+      if (maybeLoadingProvider != null) {
+        PageProvider loadingProvider = maybeLoadingProvider;
+        if (loadingProvider == provider) {
+          alreadyLoadingThisProvider = true;
+        }
+      }
+      if (!alreadyLoadingThisProvider) {
+        this.LoadingProvider = provider;
+        this.LoadThenUpdate(provider);
+      }
+      outlet.AppendChild(this.BuildLoadingPlaceholder());
+    }
     return outlet;
   }
+
+  // Fire-and-forget from Render()'s own point of view — there's no way to
+  // construct a task value outside an async function body to await it
+  // there instead (see kopscript's own LLM.md "Async" docs), the same
+  // reason Component's own OnUnmount-cascading Teardown() isn't awaited
+  // by its own caller either. Calls this.Update() once the fetch actually
+  // lands, so Render() runs again and this time provider.Peek() returns
+  // the now-cached page instead of null.
+  private async task LoadThenUpdate(PageProvider provider) {
+    await provider.Resolve();
+    this.LoadingProvider = null;
+    this.Update();
+  }
+
+  // Shown in the outlet while a lazily-loaded route's own page is still
+  // being fetched (AddLazyRoute) — never shown for an eager route, which
+  // always has a Component to Peek() immediately. Override to customize;
+  // default is a plain, unstyled placeholder so a real app always sees
+  // SOMETHING rather than a silently blank outlet while a chunk loads.
+  protected virtual VElement BuildLoadingPlaceholder() {
+    VElement div = VElement.Create("div");
+    div.ClassName = "router-loading";
+    div.TextContent = "Loading...";
+    return div;
+  }
 }

package/src/vdom.js

@@ -196,13 +196,13 @@ export function UnmountPrevious(parent, old, oldMounted) {
   if ((oldMounted !== null)) {
     let m = oldMounted;
     m.Teardown();
-    if ((old !== null)) {
-      let oldTree = old;
-      let maybeOldNode = oldTree.RealNode;
-      if ((maybeOldNode !== null)) {
-        let oldNode = maybeOldNode;
-        parent.removeChild(oldNode);
-      }
+  }
+  if ((old !== null)) {
+    let oldTree = old;
+    let maybeOldNode = oldTree.RealNode;
+    if ((maybeOldNode !== null)) {
+      let oldNode = maybeOldNode;
+      parent.removeChild(oldNode);
     }
   }
 }

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// A component-like thing Batching (below) can flush once every DOM-event-\n// triggered Update() call inside one batch has registered itself. Declared\n// HERE, not in component.ks, specifically so THIS file's own Materialize/\n// Patch — which need to start/stop a batch around every real event\n// dispatch — never have to `using \"./component\"`: component.ks already\n// `using`s this file for Materialize/Patch themselves, and KopScript\n// rejects a circular `using` outright. Component (component.ks) is the\n// one real implementer, via `class Component : Flushable`.\ninterface Flushable {\n  void FlushUpdate();\n}\n\n// Coalesces every Update() call made while a real DOM event handler\n// Kopular itself attached (see Materialize/Patch below, both of which wrap\n// each listener in Batching.Run before attaching it) into one flush per\n// affected component, applied once that handler returns — not one flush\n// per state<T> write inside it. See Component.Update()'s own comment\n// (component.ks) for the full rationale; this is just the mechanism.\n//\n// Deliberately class-level, shared across every batch/component rather\n// than per-instance — a single click can trigger Update() on more than one\n// component (e.g. a shared service's state<T> notifying two sibling\n// pages), and all of them need to flush together, once, when that one\n// handler finishes.\nclass Batching {\n  private static number Depth = 0;\n  private static Flushable[] Pending = [];\n\n  public static bool IsActive() {\n    return Batching.Depth > 0;\n  }\n\n  public static void Defer(Flushable f) {\n    if (!Batching.Pending.Includes(f)) {\n      Batching.Pending = Batching.Pending.Push(f);\n    }\n  }\n\n  // `try`/`finally`, not a bare sequence: a handler that throws must still\n  // decrement Depth and flush whatever already-triggered renders are\n  // pending, or one uncaught exception would wedge every future click/\n  // input on the page into \"always batching, never rendering.\" The\n  // exception itself still propagates unchanged — this never catches it,\n  // only guarantees the cleanup runs.\n  public static void Run(() => void action) {\n    Batching.Depth = Batching.Depth + 1;\n    try {\n      action();\n    } finally {\n      Batching.Depth = Batching.Depth - 1;\n      if (Batching.Depth == 0) {\n        Flushable[] toFlush = Batching.Pending;\n        Batching.Pending = [];\n        foreach (Flushable f in toFlush) {\n          f.FlushUpdate();\n        }\n      }\n    }\n  }\n}\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. Takes `parent` — every call site\n// already knows it (either Patch's own `parent` parameter, or the real\n// element a recursive child call is about to be appendChild'd into) —\n// solely to hand to a Mounted slot's own MountAsChild, which needs to\n// remember its real parent for THAT component's own future self-triggered\n// re-renders; an ordinary (non-Mounted) VElement never uses it.\nElement Materialize(VElement tree, Element parent) {\n  Mountable? maybeMounted = tree.Mounted;\n  if (maybeMounted != null) {\n    Mountable m = maybeMounted;\n    Element mountedRoot = m.MountAsChild(parent);\n    tree.RealNode = mountedRoot;\n    return mountedRoot;\n  }\n\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, el));\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  // wrapped in Batching.Run so every Update() it triggers coalesces with\n  // any others from the same dispatch (see Component.Update()'s own\n  // comment). The wrapper itself, not tree.OnClick, is what actually gets\n  // registered — recorded on tree.AttachedOnClick (velement.ks) so a later\n  // Patch() can remove this exact reference, not the handler value itself.\n  if (tree.OnClick != NoOpEventHandler) {\n    (Event) => void wrapped = (Event e) => Batching.Run(() => tree.OnClick(e));\n    tree.AttachedOnClick = wrapped;\n    el.addEventListener(\"click\", wrapped);\n  }\n  if (tree.OnInput != NoOpEventHandler) {\n    (Event) => void wrapped = (Event e) => Batching.Run(() => tree.OnInput(e));\n    tree.AttachedOnInput = wrapped;\n    el.addEventListener(\"input\", wrapped);\n  }\n  if (tree.OnBlur != NoOpEventHandler) {\n    (Event) => void wrapped = (Event e) => Batching.Run(() => tree.OnBlur(e));\n    tree.AttachedOnBlur = wrapped;\n    el.addEventListener(\"blur\", wrapped);\n  }\n  if (tree.OnChange != NoOpEventHandler) {\n    (Event) => void wrapped = (Event e) => Batching.Run(() => tree.OnChange(e));\n    tree.AttachedOnChange = wrapped;\n    el.addEventListener(\"change\", wrapped);\n  }\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  Mountable? newMounted = updated.Mounted;\n  Mountable? oldMounted = null;\n  if (old != null) {\n    VElement oldTreeForMount = old;\n    oldMounted = oldTreeForMount.Mounted;\n  }\n\n  // A live child slot (VElement.Mounted — see velement.ks) is handled\n  // entirely separately from the ordinary Tag-based logic below: it's not\n  // Kopular's own DOM element to create/reuse at all, and its \"same node\n  // or replace\" decision is instance identity (== on the Mountable itself,\n  // real reference equality — interfaces erase to the underlying object),\n  // not Tag equality.\n  if (newMounted != null) {\n    Mountable nm = newMounted;\n    if (oldMounted != null) {\n      Mountable om = oldMounted;\n      if (om == nm) {\n        // Same instance still in this slot: patch it in place, don't touch\n        // the DOM position at all (its own real node, reused or not, is\n        // already exactly where it needs to be).\n        Element reused = nm.PatchAsChild();\n        updated.RealNode = reused;\n        return reused;\n      }\n    }\n    // First time this slot has anything mounted, or a DIFFERENT instance\n    // took over the slot: release whatever was here, then mount fresh.\n    UnmountPrevious(parent, old, oldMounted);\n    Element created = nm.MountAsChild(parent);\n    parent.appendChild(created);\n    updated.RealNode = created;\n    return created;\n  }\n\n  if (oldMounted != null) {\n    // Slot reverted from a live component back to plain content: release\n    // the old one, then fall through to an ordinary fresh materialize.\n    UnmountPrevious(parent, old, oldMounted);\n    Element created = Materialize(updated, parent);\n    parent.appendChild(created);\n    return created;\n  }\n\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, parent);\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        //\n        // The actually-attached listener is always a Batching.Run wrapper\n        // (see Materialize above), never `oldTree.OnClick`/`updated.OnClick`\n        // themselves — removeEventListener only works when passed the exact\n        // reference addEventListener received, so removal always goes\n        // through `oldTree.AttachedOnClick` (the wrapper Materialize/a\n        // previous Patch actually registered), and a real swap builds a\n        // fresh wrapper the same way Materialize does. When nothing swaps,\n        // `updated.AttachedOnClick` still needs to carry `oldTree`'s\n        // forward — `updated` is a brand-new VElement whose own\n        // AttachedOnClick starts back at the shared no-op (velement.ks's\n        // constructor), and it becomes the retained \"old tree\" the very\n        // next Patch() call diffs against.\n        if (updated.OnClick != oldTree.OnClick) {\n          realNode.removeEventListener(\"click\", oldTree.AttachedOnClick);\n          (Event) => void wrappedClick = (Event e) => Batching.Run(() => updated.OnClick(e));\n          updated.AttachedOnClick = wrappedClick;\n          realNode.addEventListener(\"click\", wrappedClick);\n        } else {\n          updated.AttachedOnClick = oldTree.AttachedOnClick;\n        }\n        if (updated.OnInput != oldTree.OnInput) {\n          realNode.removeEventListener(\"input\", oldTree.AttachedOnInput);\n          (Event) => void wrappedInput = (Event e) => Batching.Run(() => updated.OnInput(e));\n          updated.AttachedOnInput = wrappedInput;\n          realNode.addEventListener(\"input\", wrappedInput);\n        } else {\n          updated.AttachedOnInput = oldTree.AttachedOnInput;\n        }\n        if (updated.OnBlur != oldTree.OnBlur) {\n          realNode.removeEventListener(\"blur\", oldTree.AttachedOnBlur);\n          (Event) => void wrappedBlur = (Event e) => Batching.Run(() => updated.OnBlur(e));\n          updated.AttachedOnBlur = wrappedBlur;\n          realNode.addEventListener(\"blur\", wrappedBlur);\n        } else {\n          updated.AttachedOnBlur = oldTree.AttachedOnBlur;\n        }\n        if (updated.OnChange != oldTree.OnChange) {\n          realNode.removeEventListener(\"change\", oldTree.AttachedOnChange);\n          (Event) => void wrappedChange = (Event e) => Batching.Run(() => updated.OnChange(e));\n          updated.AttachedOnChange = wrappedChange;\n          realNode.addEventListener(\"change\", wrappedChange);\n        } else {\n          updated.AttachedOnChange = oldTree.AttachedOnChange;\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, parent);\n      parent.appendChild(created);\n      return created;\n    }\n  } else {\n    Element created = Materialize(updated, parent);\n    parent.appendChild(created);\n    return created;\n  }\n}\n\n// Releases whatever was previously mounted in a slot (calling its\n// Teardown, which — for a Component — cascades into anything IT mounted\n// too, however many levels deep, before its own app-facing OnUnmount runs)\n// and removes its real node from the DOM, before a different Mountable (or\n// plain content) takes over that slot. A no-op when there was nothing\n// mounted here before — the common \"first render of this slot\" case.\nvoid UnmountPrevious(Element parent, VElement? old, Mountable? oldMounted) {\n  if (oldMounted != null) {\n    Mountable m = oldMounted;\n    m.Teardown();\n    if (old != null) {\n      VElement oldTree = old;\n      Element? maybeOldNode = oldTree.RealNode;\n      if (maybeOldNode != null) {\n        Element oldNode = maybeOldNode;\n        parent.removeChild(oldNode);\n      }\n    }\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 — releasing\n  // anything Mounted first (see velement.ks) so a child genuinely dropped\n  // from a list (not replaced in the same slot by a different one, which\n  // Patch() itself already handles via UnmountPrevious — removed outright)\n  // still gets torn down. This is the one place THAT case is reachable\n  // from, since Patch() only ever sees one slot at a time, never a slot\n  // disappearing entirely.\n  for (number j = 0; j < oldChildren.Length; j = j + 1) {\n    if (oldConsumed[j]) { continue; }\n    Mountable? maybeOldMounted = oldChildren[j].Mounted;\n    if (maybeOldMounted != null) {\n      Mountable m = maybeOldMounted;\n      m.Teardown();\n    }\n    Element? maybeOldNode = oldChildren[j].RealNode;\n    if (maybeOldNode != null) {\n      Element oldNode = maybeOldNode;\n      parent.removeChild(oldNode);\n    }\n  }\n}\n\n// Recursively finds and tears down every Mounted node within `tree` (tree\n// itself included) — used by Component's own Teardown (see component.ks)\n// so removing ONE component transitively releases everything IT rendered,\n// however many Mounted levels deep, not only the outermost one. A pure\n// data walk over the retained VElement tree; never touches the real DOM\n// itself (the caller already owns removing whatever real node is actually\n// attached).\nvoid UnmountTree(VElement tree) {\n  Mountable? maybeMounted = tree.Mounted;\n  if (maybeMounted != null) {\n    Mountable m = maybeMounted;\n    m.Teardown();\n  }\n  foreach (VElement child in tree.Children) {\n    UnmountTree(child);\n  }\n}\n"],"names":[],"mappings":";;;AAyCA;EACiB;;EACA;;EAED;IACZ;;;EAGY;IACZ;MACmB;;;;EAUP;IACG;IACf;MACQ;;MAES;MACf;QACE;QACiB;QACjB;UACe;;;;;;AAkBvB;EACE;EACA;IACE;IACA;IACc;IACd;;EAGF;EAEA;IACe;;IAEb;MACgB;;;IAGD;;EAGJ;EACP;EACG;EAET;IACiB;;EAYjB;IACE;IACqB;IACF;;EAErB;IACE;IACqB;IACF;;EAErB;IACE;IACoB;IACD;;EAErB;IACE;IACsB;IACH;;EAGP;EACd;;AAiBF;EACE;EACA;EACA;IACE;IACW;;EASb;IACE;IACA;MACE;MACA;QAIE;QACiB;QACjB;;;IAKW;IACf;IACkB;IACD;IACjB;;EAGF;IAGiB;IACf;IACkB;IAClB;;EAGF;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;;;QA6BzB;UAC8B;UAC5B;UACwB;UACC;;UAED;;QAE1B;UAC8B;UAC5B;UACwB;UACC;;UAED;;QAE1B;UAC8B;UAC5B;UACuB;UACE;;UAEF;;QAEzB;UAC8B;UAC5B;UACyB;UACA;;UAEA;;QAG3B;;;MAOF;MACkB;MAClB;;;IAGF;IACkB;IAClB;;;AAUJ;EACE;IACE;IACU;IACV;MACE;MACA;MACA;QACE;QACkB;;;;;AAiB1B;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;;;EAWtB;IACE;MAAsB;;IACtB;IACA;MACE;MACU;;IAEZ;IACA;MACE;MACkB;;;;AAYxB;EACE;EACA;IACE;IACU;;EAEZ;IACa"}
+{"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// A component-like thing Batching (below) can flush once every DOM-event-\n// triggered Update() call inside one batch has registered itself. Declared\n// HERE, not in component.ks, specifically so THIS file's own Materialize/\n// Patch — which need to start/stop a batch around every real event\n// dispatch — never have to `using \"./component\"`: component.ks already\n// `using`s this file for Materialize/Patch themselves, and KopScript\n// rejects a circular `using` outright. Component (component.ks) is the\n// one real implementer, via `class Component : Flushable`.\ninterface Flushable {\n  void FlushUpdate();\n}\n\n// Coalesces every Update() call made while a real DOM event handler\n// Kopular itself attached (see Materialize/Patch below, both of which wrap\n// each listener in Batching.Run before attaching it) into one flush per\n// affected component, applied once that handler returns — not one flush\n// per state<T> write inside it. See Component.Update()'s own comment\n// (component.ks) for the full rationale; this is just the mechanism.\n//\n// Deliberately class-level, shared across every batch/component rather\n// than per-instance — a single click can trigger Update() on more than one\n// component (e.g. a shared service's state<T> notifying two sibling\n// pages), and all of them need to flush together, once, when that one\n// handler finishes.\nclass Batching {\n  private static number Depth = 0;\n  private static Flushable[] Pending = [];\n\n  public static bool IsActive() {\n    return Batching.Depth > 0;\n  }\n\n  public static void Defer(Flushable f) {\n    if (!Batching.Pending.Includes(f)) {\n      Batching.Pending = Batching.Pending.Push(f);\n    }\n  }\n\n  // `try`/`finally`, not a bare sequence: a handler that throws must still\n  // decrement Depth and flush whatever already-triggered renders are\n  // pending, or one uncaught exception would wedge every future click/\n  // input on the page into \"always batching, never rendering.\" The\n  // exception itself still propagates unchanged — this never catches it,\n  // only guarantees the cleanup runs.\n  public static void Run(() => void action) {\n    Batching.Depth = Batching.Depth + 1;\n    try {\n      action();\n    } finally {\n      Batching.Depth = Batching.Depth - 1;\n      if (Batching.Depth == 0) {\n        Flushable[] toFlush = Batching.Pending;\n        Batching.Pending = [];\n        foreach (Flushable f in toFlush) {\n          f.FlushUpdate();\n        }\n      }\n    }\n  }\n}\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. Takes `parent` — every call site\n// already knows it (either Patch's own `parent` parameter, or the real\n// element a recursive child call is about to be appendChild'd into) —\n// solely to hand to a Mounted slot's own MountAsChild, which needs to\n// remember its real parent for THAT component's own future self-triggered\n// re-renders; an ordinary (non-Mounted) VElement never uses it.\nElement Materialize(VElement tree, Element parent) {\n  Mountable? maybeMounted = tree.Mounted;\n  if (maybeMounted != null) {\n    Mountable m = maybeMounted;\n    Element mountedRoot = m.MountAsChild(parent);\n    tree.RealNode = mountedRoot;\n    return mountedRoot;\n  }\n\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, el));\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  // wrapped in Batching.Run so every Update() it triggers coalesces with\n  // any others from the same dispatch (see Component.Update()'s own\n  // comment). The wrapper itself, not tree.OnClick, is what actually gets\n  // registered — recorded on tree.AttachedOnClick (velement.ks) so a later\n  // Patch() can remove this exact reference, not the handler value itself.\n  if (tree.OnClick != NoOpEventHandler) {\n    (Event) => void wrapped = (Event e) => Batching.Run(() => tree.OnClick(e));\n    tree.AttachedOnClick = wrapped;\n    el.addEventListener(\"click\", wrapped);\n  }\n  if (tree.OnInput != NoOpEventHandler) {\n    (Event) => void wrapped = (Event e) => Batching.Run(() => tree.OnInput(e));\n    tree.AttachedOnInput = wrapped;\n    el.addEventListener(\"input\", wrapped);\n  }\n  if (tree.OnBlur != NoOpEventHandler) {\n    (Event) => void wrapped = (Event e) => Batching.Run(() => tree.OnBlur(e));\n    tree.AttachedOnBlur = wrapped;\n    el.addEventListener(\"blur\", wrapped);\n  }\n  if (tree.OnChange != NoOpEventHandler) {\n    (Event) => void wrapped = (Event e) => Batching.Run(() => tree.OnChange(e));\n    tree.AttachedOnChange = wrapped;\n    el.addEventListener(\"change\", wrapped);\n  }\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  Mountable? newMounted = updated.Mounted;\n  Mountable? oldMounted = null;\n  if (old != null) {\n    VElement oldTreeForMount = old;\n    oldMounted = oldTreeForMount.Mounted;\n  }\n\n  // A live child slot (VElement.Mounted — see velement.ks) is handled\n  // entirely separately from the ordinary Tag-based logic below: it's not\n  // Kopular's own DOM element to create/reuse at all, and its \"same node\n  // or replace\" decision is instance identity (== on the Mountable itself,\n  // real reference equality — interfaces erase to the underlying object),\n  // not Tag equality.\n  if (newMounted != null) {\n    Mountable nm = newMounted;\n    if (oldMounted != null) {\n      Mountable om = oldMounted;\n      if (om == nm) {\n        // Same instance still in this slot: patch it in place, don't touch\n        // the DOM position at all (its own real node, reused or not, is\n        // already exactly where it needs to be).\n        Element reused = nm.PatchAsChild();\n        updated.RealNode = reused;\n        return reused;\n      }\n    }\n    // First time this slot has anything mounted, or a DIFFERENT instance\n    // took over the slot: release whatever was here, then mount fresh.\n    UnmountPrevious(parent, old, oldMounted);\n    Element created = nm.MountAsChild(parent);\n    parent.appendChild(created);\n    updated.RealNode = created;\n    return created;\n  }\n\n  if (oldMounted != null) {\n    // Slot reverted from a live component back to plain content: release\n    // the old one, then fall through to an ordinary fresh materialize.\n    UnmountPrevious(parent, old, oldMounted);\n    Element created = Materialize(updated, parent);\n    parent.appendChild(created);\n    return created;\n  }\n\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, parent);\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        //\n        // The actually-attached listener is always a Batching.Run wrapper\n        // (see Materialize above), never `oldTree.OnClick`/`updated.OnClick`\n        // themselves — removeEventListener only works when passed the exact\n        // reference addEventListener received, so removal always goes\n        // through `oldTree.AttachedOnClick` (the wrapper Materialize/a\n        // previous Patch actually registered), and a real swap builds a\n        // fresh wrapper the same way Materialize does. When nothing swaps,\n        // `updated.AttachedOnClick` still needs to carry `oldTree`'s\n        // forward — `updated` is a brand-new VElement whose own\n        // AttachedOnClick starts back at the shared no-op (velement.ks's\n        // constructor), and it becomes the retained \"old tree\" the very\n        // next Patch() call diffs against.\n        if (updated.OnClick != oldTree.OnClick) {\n          realNode.removeEventListener(\"click\", oldTree.AttachedOnClick);\n          (Event) => void wrappedClick = (Event e) => Batching.Run(() => updated.OnClick(e));\n          updated.AttachedOnClick = wrappedClick;\n          realNode.addEventListener(\"click\", wrappedClick);\n        } else {\n          updated.AttachedOnClick = oldTree.AttachedOnClick;\n        }\n        if (updated.OnInput != oldTree.OnInput) {\n          realNode.removeEventListener(\"input\", oldTree.AttachedOnInput);\n          (Event) => void wrappedInput = (Event e) => Batching.Run(() => updated.OnInput(e));\n          updated.AttachedOnInput = wrappedInput;\n          realNode.addEventListener(\"input\", wrappedInput);\n        } else {\n          updated.AttachedOnInput = oldTree.AttachedOnInput;\n        }\n        if (updated.OnBlur != oldTree.OnBlur) {\n          realNode.removeEventListener(\"blur\", oldTree.AttachedOnBlur);\n          (Event) => void wrappedBlur = (Event e) => Batching.Run(() => updated.OnBlur(e));\n          updated.AttachedOnBlur = wrappedBlur;\n          realNode.addEventListener(\"blur\", wrappedBlur);\n        } else {\n          updated.AttachedOnBlur = oldTree.AttachedOnBlur;\n        }\n        if (updated.OnChange != oldTree.OnChange) {\n          realNode.removeEventListener(\"change\", oldTree.AttachedOnChange);\n          (Event) => void wrappedChange = (Event e) => Batching.Run(() => updated.OnChange(e));\n          updated.AttachedOnChange = wrappedChange;\n          realNode.addEventListener(\"change\", wrappedChange);\n        } else {\n          updated.AttachedOnChange = oldTree.AttachedOnChange;\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, parent);\n      parent.appendChild(created);\n      return created;\n    }\n  } else {\n    Element created = Materialize(updated, parent);\n    parent.appendChild(created);\n    return created;\n  }\n}\n\n// Releases whatever was previously mounted in a slot (calling its\n// Teardown, which — for a Component — cascades into anything IT mounted\n// too, however many levels deep, before its own app-facing OnUnmount runs)\n// and removes its real node from the DOM, before a different Mountable (or\n// plain content) takes over that slot. A no-op when there was nothing\n// mounted here before — the common \"first render of this slot\" case.\nvoid UnmountPrevious(Element parent, VElement? old, Mountable? oldMounted) {\n  // Teardown() only applies when there really was a Mounted instance here\n  // before (nothing to tear down for plain content) — but the real node\n  // itself needs removing whenever `old` had one, Mounted or not: a plain\n  // VElement's slot turning into a Mounted one is exactly as much a\n  // wholesale replacement as the reverse direction (handled by falling\n  // through to Materialize below in Patch), and both need the OLD node\n  // gone before the NEW one is appended, not left behind as a stray\n  // sibling.\n  if (oldMounted != null) {\n    Mountable m = oldMounted;\n    m.Teardown();\n  }\n  if (old != null) {\n    VElement oldTree = old;\n    Element? maybeOldNode = oldTree.RealNode;\n    if (maybeOldNode != null) {\n      Element oldNode = maybeOldNode;\n      parent.removeChild(oldNode);\n    }\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 — releasing\n  // anything Mounted first (see velement.ks) so a child genuinely dropped\n  // from a list (not replaced in the same slot by a different one, which\n  // Patch() itself already handles via UnmountPrevious — removed outright)\n  // still gets torn down. This is the one place THAT case is reachable\n  // from, since Patch() only ever sees one slot at a time, never a slot\n  // disappearing entirely.\n  for (number j = 0; j < oldChildren.Length; j = j + 1) {\n    if (oldConsumed[j]) { continue; }\n    Mountable? maybeOldMounted = oldChildren[j].Mounted;\n    if (maybeOldMounted != null) {\n      Mountable m = maybeOldMounted;\n      m.Teardown();\n    }\n    Element? maybeOldNode = oldChildren[j].RealNode;\n    if (maybeOldNode != null) {\n      Element oldNode = maybeOldNode;\n      parent.removeChild(oldNode);\n    }\n  }\n}\n\n// Recursively finds and tears down every Mounted node within `tree` (tree\n// itself included) — used by Component's own Teardown (see component.ks)\n// so removing ONE component transitively releases everything IT rendered,\n// however many Mounted levels deep, not only the outermost one. A pure\n// data walk over the retained VElement tree; never touches the real DOM\n// itself (the caller already owns removing whatever real node is actually\n// attached).\nvoid UnmountTree(VElement tree) {\n  Mountable? maybeMounted = tree.Mounted;\n  if (maybeMounted != null) {\n    Mountable m = maybeMounted;\n    m.Teardown();\n  }\n  foreach (VElement child in tree.Children) {\n    UnmountTree(child);\n  }\n}\n"],"names":[],"mappings":";;;AAyCA;EACiB;;EACA;;EAED;IACZ;;;EAGY;IACZ;MACmB;;;;EAUP;IACG;IACf;MACQ;;MAES;MACf;QACE;QACiB;QACjB;UACe;;;;;;AAkBvB;EACE;EACA;IACE;IACA;IACc;IACd;;EAGF;EAEA;IACe;;IAEb;MACgB;;;IAGD;;EAGJ;EACP;EACG;EAET;IACiB;;EAYjB;IACE;IACqB;IACF;;EAErB;IACE;IACqB;IACF;;EAErB;IACE;IACoB;IACD;;EAErB;IACE;IACsB;IACH;;EAGP;EACd;;AAiBF;EACE;EACA;EACA;IACE;IACW;;EASb;IACE;IACA;MACE;MACA;QAIE;QACiB;QACjB;;;IAKW;IACf;IACkB;IACD;IACjB;;EAGF;IAGiB;IACf;IACkB;IAClB;;EAGF;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;;;QA6BzB;UAC8B;UAC5B;UACwB;UACC;;UAED;;QAE1B;UAC8B;UAC5B;UACwB;UACC;;UAED;;QAE1B;UAC8B;UAC5B;UACuB;UACE;;UAEF;;QAEzB;UAC8B;UAC5B;UACyB;UACA;;UAEA;;QAG3B;;;MAOF;MACkB;MAClB;;;IAGF;IACkB;IAClB;;;AAUJ;EASE;IACE;IACU;;EAEZ;IACE;IACA;IACA;MACE;MACkB;;;;AAgBxB;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;;;EAWtB;IACE;MAAsB;;IACtB;IACA;MACE;MACU;;IAEZ;IACA;MACE;MACkB;;;;AAYxB;EACE;EACA;IACE;IACU;;EAEZ;IACa"}

package/src/vdom.ks

@@ -355,16 +355,24 @@ Element Patch(Element parent, VElement? old, VElement updated) {
 // plain content) takes over that slot. A no-op when there was nothing
 // mounted here before — the common "first render of this slot" case.
 void UnmountPrevious(Element parent, VElement? old, Mountable? oldMounted) {
+  // Teardown() only applies when there really was a Mounted instance here
+  // before (nothing to tear down for plain content) — but the real node
+  // itself needs removing whenever `old` had one, Mounted or not: a plain
+  // VElement's slot turning into a Mounted one is exactly as much a
+  // wholesale replacement as the reverse direction (handled by falling
+  // through to Materialize below in Patch), and both need the OLD node
+  // gone before the NEW one is appended, not left behind as a stray
+  // sibling.
   if (oldMounted != null) {
     Mountable m = oldMounted;
     m.Teardown();
-    if (old != null) {
-      VElement oldTree = old;
-      Element? maybeOldNode = oldTree.RealNode;
-      if (maybeOldNode != null) {
-        Element oldNode = maybeOldNode;
-        parent.removeChild(oldNode);
-      }
+  }
+  if (old != null) {
+    VElement oldTree = old;
+    Element? maybeOldNode = oldTree.RealNode;
+    if (maybeOldNode != null) {
+      Element oldNode = maybeOldNode;
+      parent.removeChild(oldNode);
     }
   }
 }