kopular 0.10.0 → 0.11.0

package/LLM.md

@@ -12,7 +12,9 @@ Published as npm `kopular`. Entry points: `kopular` / `kopular/component` (Compo
 (runKopularApp, runKopularFixture — see below). Also ships a bin, `kp` — `npx kp new
 <dir>` scaffolds a new project (the `extern` bindings below, plus the vendor/serve
 scripts needed to run in a browser) rather than requiring it be reconstructed by hand;
-prefer it over hand-writing the section below for a new project.
+prefer it over hand-writing the section below for a new project. Templates (`template
+from "./x.html";`, see below) are a KopScript language feature, not a Kopular export —
+there is no `kopular/template` entry point to import.
 
 ## Consuming Kopular from your own KopScript project
 
@@ -112,8 +114,10 @@ w.Bump();                // re-render
 ```
 
 - `Render()`: `virtual`, override it to build a fresh DOM subtree from current state.
-  Called by both `Mount()` and `Update()`. **No template language, no diffing** — every
-  call rebuilds the whole subtree from scratch.
+  Called by both `Mount()` and `Update()`. **No diffing either way** — every call
+  rebuilds the whole subtree from scratch. Provide it as a real markup file via
+  KopScript's `template from "./x.html";` (see "Templates" below) instead of hand-writing
+  it — both produce the exact same method; Kopular needed no code changes to support this.
 - `Mount(parent)`: calls `Render()` once, appends the result to `parent`, remembers both
   for `Update()` to use later.
 - `Update()` (protected — called from within the component, not externally): calls
@@ -141,6 +145,38 @@ w.Bump();                // re-render
   into the component) renders normally again — there's no separate "broken" state to
   reset, `SafeRender()` just tries `Render()` again like any other `Update()`.
 
+## Templates — `template from` (see KopScript's own `LLM.md` for the full syntax)
+
+```ks
+class Counter : Component {
+  public state<number> Count;
+  constructor() : base() { this.Count = state(0); }
+  public void Increment() { this.Count.Value = this.Count.Value + 1; }
+  template from "./counter.html";   // replaces Render() entirely — cannot coexist with a hand-written one
+}
+```
+```html
+<!-- counter.html -->
+<button (click)="Increment()">Count: {{ Count.Value }}</button>
+```
+
+- `{{ expr }}` interpolation, `(event)="stmt"`, `[prop]="expr"`, `*if="expr"`,
+  `*for="Type varName of expr"` — all real KopScript, checked at compile time, desugared
+  to the exact same `document.createElement`/`.appendChild`/`.textContent`/
+  `.addEventListener` calls a hand-written `Render()` would use.
+- A `state<T>` field declared directly on the class and referenced directly in the
+  template (`Count` above) gets `Subscribe((v) => this.Update())` wired automatically —
+  no manual `Subscribe` in the constructor for that field. State reached indirectly
+  (through a method, or `this.SomeService.Count`) still needs a manual `Subscribe`, same
+  as a hand-written `Render()` always has.
+- One top-level element per template (hard error otherwise); no mixing text and element
+  children under one element (no text-node type in `dom.ks`, only `.textContent`); no
+  two-way binding, no pipes, at most one structural directive per element.
+- This is entirely a KopScript compiler feature (parsed/desugared before type-checking
+  runs) — Kopular's own framework code (`component.ks`, `dom.ks`) is unmodified and
+  unaware templates exist; a template-generated `Render()` is indistinguishable from a
+  hand-written one to every other part of the framework.
+
 ## `Router` (`router.ks`)
 
 Real URLs via the History API (`pushState`/`popstate`), not hash routing.
@@ -217,7 +253,12 @@ nav.Navigate("/about");                          // pushState + immediate re-ren
     "SPA fallback" / "custom 404 → index.html" option — look for that host's own docs on
     single-page-application routing, the terminology is standard across all of them.
 
-## `If` (`directives.ks`) — the `*ngIf` equivalent
+## `If` (`directives.ks`) — the `*ngIf` equivalent for a hand-written `Render()`
+
+In a **template**, `*if="expr"`/`*for="Type v of expr"` are the direct equivalents (real
+`if`/`for` under the hood — see "Templates" above), no helper needed. This section is for
+a **hand-written** `Render()`, where `if` being a statement (not an expression) means a
+conditional value needs a helper to get one out of it:
 
 ```ks
 Element If(bool condition, () => Element whenTrue, () => Element whenFalse)
@@ -229,7 +270,7 @@ root.appendChild(If(this.IsLoggedIn, () => this.BuildProfile(), () => this.Build
 
 Both branches always required (no null "nothing" value); only the branch actually taken
 is called — the other lambda never runs. `*ngFor` and `*ngSwitch` need no Kopular helper
-at all:
+at all in hand-written `Render()` either:
 
 ```ks
 // *ngFor — plain array method
@@ -386,8 +427,10 @@ class CounterService {
 
 ## Does not exist
 
-DI container/injector · decorators (`@Injectable`, `@Component`, ...) · a template
-language/DSL — everything is imperative `Render()` code against plain DOM bindings ·
+DI container/injector · decorators (`@Injectable`, `@Component`, ...) · a runtime
+template engine or interpreted expression language — templates compile to the same
+imperative `Render()` code as the hand-written form, checked at compile time, not
+interpreted at runtime (see "Templates" above) · two-way binding (`[(ngModel)]`) ·
 vdom diffing / reconciliation beyond a single component's own re-render · pipes ·
 animations · forms/validation module · typed/generic HTTP responses (`Http` returns raw
 text — see above) · a CLI/scaffolding tool (`ng generate`-equivalent) · SSR.

package/README.md

@@ -5,7 +5,8 @@
 Kopular is a small component framework for [KopScript](https://dev.azure.com/koppinator/Koppindependence/_git/Kop),
 built to give Angular's separation of concerns — components own UI, services own logic,
 a router owns navigation — without Angular's steepest learning-curve pieces: no RxJS, no
-dependency-injection container, no template DSL.
+dependency-injection container, and templates that are real, compiled, type-checked
+KopScript rather than a separate interpreted template language.
 
 Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./LLM.md)**
 — a dense, complete reference designed to be loaded straight into an LLM's context.
@@ -13,11 +14,19 @@ Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./
 ## Highlights
 
 - **`Component`**: a base class with `virtual Render()` (builds a fresh DOM subtree from
-  current state) and `Update()` (swaps the old subtree for the new one). No template
-  language, no diffing — components build/update the DOM imperatively against plain DOM
-  bindings, the way you'd write careful vanilla-JS UI code. An optional `virtual
+  current state) and `Update()` (swaps the old subtree for the new one). No diffing either
+  way — `Render()` is provided as a real, separate markup file compiled by KopScript's
+  `template from` (see "Templates" below), or written by hand as plain imperative DOM
+  code against plain DOM bindings, the way you'd write careful vanilla-JS UI code — your
+  choice, and both compile to the exact same thing. An optional `virtual
   RenderError(message)` renders a fallback instead of a hard crash if `Render()` throws —
   purely additive; not overriding it keeps today's exact (uncaught) behavior.
+- **Templates, compiled and type-checked, not interpreted**: markup lives in its own
+  `.html` file — interpolation (`{{ }}`), event/property bindings (`(click)="..."`,
+  `[prop]="..."`), and `*if`/`*for` structural directives — desugared by the KopScript
+  compiler into the exact same code a hand-written `Render()` would produce, with
+  automatic `Subscribe`/`Update()` wiring for `state<T>` fields referenced directly in the
+  markup. See "Templates" below.
 - **Reactive state, no RxJS**: components hold `state<number>`/`state<string>`/... (a
   KopScript language feature — see the [Kop](https://dev.azure.com/koppinator/Koppindependence/_git/Kop)
   repo) and subscribe once, in their constructor, to call `Update()` on change. No
@@ -30,10 +39,12 @@ Generating Kopular code with an AI coding assistant? Point it at **[`LLM.md`](./
   (`pushState`/`popstate`), with route registration as plain method calls, not a config
   DSL. See "Router, and deploying it" below — every deployment target needs its own
   SPA-fallback config, not just local dev.
-- **Structural directives, no template DSL**: `*ngIf`/`*ngFor`/`*ngSwitch`'s job — build
-  a subtree conditionally, repeat one per item, pick one of several cases — done as plain
-  function calls (`If(...)`) and existing KopScript expressions (`array.ForEach(...)`,
-  `match`), not special template syntax. See "Structural directives" below.
+- **Structural directives**: `*ngIf`/`*ngFor`/`*ngSwitch`'s job — build a subtree
+  conditionally, repeat one per item, pick one of several cases. In a template, that's
+  `*if`/`*for` (real `if`/`for` under the hood — see "Templates"); in a hand-written
+  `Render()`, the same job is a plain function call (`If(...)`) or existing KopScript
+  expression (`array.ForEach(...)`, `match`) — no special syntax needed there either way.
+  See "Structural directives" below.
 - **`Http`**: a thin, static wrapper over the real Fetch API (`Http.Get(url)`,
   `Http.Post(url, jsonBody)`, ...) — no HttpClient injection tokens, no RxJS
   observables/operators. See "HTTP" below.
@@ -62,6 +73,66 @@ That's the whole framework — eight files, plus the scaffolding CLI. Everything
 real app built on top of it)
 lives in a separate consumer repo, [KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo).
 
+## Templates
+
+A component's `Render()` can be a real markup file instead of hand-written imperative DOM
+code — `template from "./x.html";` in the class body, a KopScript language feature (see
+[Kop](https://dev.azure.com/koppinator/Koppindependence/_git/Kop)'s own README/LLM.md for
+the full syntax reference). Kopular itself needed **zero framework code changes** for
+this — the compiler desugars a template straight into calls against the same
+`document.createElement`/`.appendChild`/`.textContent`/`.addEventListener` surface
+`dom.ks` already declares, so a template-generated `Render()` is indistinguishable from
+one you'd write by hand:
+
+```ks
+// counter.ks
+class Counter : Component {
+  public state<number> Count;
+  constructor() : base() { this.Count = state(0); }
+  public void Increment() { this.Count.Value = this.Count.Value + 1; }
+  template from "./counter.html";
+}
+```
+
+```html
+<!-- counter.html -->
+<button (click)="Increment()">Count: {{ Count.Value }}</button>
+```
+
+Note there's no `this.Count.Subscribe(...)` anywhere — a `state<T>` field referenced
+directly in the template (`Count.Value` above) gets it wired automatically. The exact
+same component, hand-written, needs that `Subscribe` call itself:
+
+```ks
+class Counter : Component {
+  private state<number> Count;
+
+  constructor() : base() {
+    this.Count = state(0);
+    this.Count.Subscribe((number v) => this.Update());
+  }
+
+  public override Element Render() {
+    Element button = document.createElement("button");
+    button.textContent = "Count: " + this.Count.Value;
+    button.addEventListener("click", (Event e) => {
+      this.Count.Value = this.Count.Value + 1;
+    });
+    return button;
+  }
+}
+```
+
+Both produce the same `Render()`, and can be mixed freely across a codebase — nothing
+about `Component`, `Update()`, or any other Kopular API differs between them. The manual
+`Subscribe` call is still exactly what you need the moment state is reached *indirectly*
+— through a method call, or through an injected service's own state
+(`this.Service.Count`, say) — which is why the real, production `Counter` on the
+[KopularDemo](https://dev.azure.com/koppinator/Koppindependence/_git/KopularDemo) site
+(it injects a `CounterService` rather than holding `Count` itself) uses a template but
+still has one manual `Subscribe`. `*if`/`*for` in a template are covered under
+"Structural directives" below, alongside their hand-written-`Render()` equivalents.
+
 ## Dependency injection: the composition root pattern
 
 Kopular has no injector because KopScript has nothing for one to hook into — no
@@ -202,20 +273,23 @@ standard. For local dev, see KopularDemo's `scripts/serve.mjs`.
 ## Structural directives
 
 Angular's `*ngIf`/`*ngFor`/`*ngSwitch` are template syntax that expands, at compile time,
-into imperative view-container calls. Kopular has no template compiler to expand
-anything into (`Render()` is already imperative — see `component.ks`), so there's no
-special syntax here either: each one maps onto a plain expression, and two of the three
-need nothing new at all.
-
-| Angular          | Kopular                                    | New code? |
-| ----------------- | ------------------------------------------- | :-------: |
-| `*ngFor`          | `array.ForEach((item) => ...)`              | none — already a KopScript array method |
-| `*ngSwitch`       | `match value { ... }`                       | none — already a KopScript expression, and exhaustiveness-checked (`*ngSwitch` isn't) |
-| `*ngIf` / `*ngIf-else` | `If(condition, () => ..., () => ...)`  | `directives.ks` |
-
-`*ngIf` is the one case that needs something new: `if` is a *statement* in KopScript, so
-without a helper you'd need a throwaway mutable local just to get a conditional value out
-of it. `If()` is that helper — nothing more than:
+into imperative view-container calls. In a Kopular **template**, `*if`/`*for` are exactly
+that — real KopScript `if`/`for` statements underneath (see "Templates" above), compiled
+by KopScript itself, not interpreted by Kopular at runtime. In a **hand-written**
+`Render()`, there's no separate directive syntax to reach for: each job maps onto a plain
+expression, and two of the three need nothing new at all.
+
+| Angular          | Kopular template | Kopular hand-written `Render()`             | New code? |
+| ----------------- | ---------------- | -------------------------------------------- | :-------: |
+| `*ngFor`          | `*for="Type v of expr"` | `array.ForEach((item) => ...)`         | none — already a KopScript array method |
+| `*ngSwitch`       | *(not supported — use `*if`, or switch in the backing class)* | `match value { ... }` | none — already a KopScript expression, and exhaustiveness-checked (`*ngSwitch` isn't) |
+| `*ngIf` / `*ngIf-else` | `*if="expr"` | `If(condition, () => ..., () => ...)`  | `directives.ks` (hand-written form only — a template's `*if` needs no helper, it's a real `if`) |
+
+The rest of this section is about the **hand-written `Render()`** column above — a
+template's `*if`/`*for` need no further explanation, they're covered under "Templates".
+`*ngIf` is the one case in hand-written `Render()` that needs something new: `if` is a
+*statement* in KopScript, so without a helper you'd need a throwaway mutable local just
+to get a conditional value out of it. `If()` is that helper — nothing more than:
 
 ```ks
 Element If(bool condition, () => Element whenTrue, () => Element whenFalse) {
@@ -232,7 +306,7 @@ to hand back. Only the branch actually taken runs — the other lambda is never
 an explicit empty branch (`() => document.createElement("span")`) costs nothing when
 there's genuinely nothing to show.
 
-All three read the same way, right inside `Render()` — no template file, no directive
+All three read the same way, right inside a hand-written `Render()` — no directive
 registration, nothing to import beyond the function itself:
 
 ```ks

package/bin/kp.mjs

@@ -97,7 +97,7 @@ A [KopScript](https://www.npmjs.com/package/kopscript) + [Kopular](https://www.n
 
 ## Where to go next
 
-- \`src/counter.ks\` is a real, working Kopular \`Component\` — start there.
+- \`src/counter.ks\` + \`src/counter.html\` is a real, working Kopular \`Component\` — start there. Its markup lives in \`counter.html\` (interpolation, \`(click)="..."\`) via KopScript's \`template from\`; \`counter.ks\` holds only state and logic. See \`node_modules/kopscript/LLM.md\`'s "Templates" section for the full binding/directive syntax, and Kopular's own README/LLM.md for the hand-written-\`Render()\` alternative.
 - \`src/kopular_bindings.ks\` declares the ambient DOM and Kopular types this project builds on (see the comments inside it for why these have to be redeclared per-project rather than imported).
 - For routing, dependency injection ("Pure DI" / a composition root), structural directives, or the \`Http\` client, see Kopular's own README and \`node_modules/kopular/LLM.md\`.
 - For the full language reference, see \`node_modules/kopscript/LLM.md\`.
@@ -242,28 +242,31 @@ extern class Router {
 `;
 
 // The same Counter shown in Kopular's own README/LLM.md — real, verified
-// example code, not a placeholder.
+// example code, not a placeholder. Uses a template (see counter.html below)
+// rather than a hand-written Render(), since that's the more common style
+// today; Kopular's/KopScript's own docs show the equivalent hand-written
+// form too, for the case a component needs one (e.g. Subscribe-ing to state
+// reached indirectly, through an injected service).
 const COUNTER_KS_TEMPLATE = `using "./kopular_bindings";
 
 class Counter : Component {
-  private state<number> Count;
+  public state<number> Count;
 
   constructor() : base() {
     this.Count = state(0);
-    this.Count.Subscribe((number v) => this.Update());
   }
 
-  public override Element Render() {
-    Element button = document.createElement("button");
-    button.textContent = "Count: " + this.Count.Value;
-    button.addEventListener("click", (Event e) => {
-      this.Count.Value = this.Count.Value + 1;
-    });
-    return button;
+  public void Increment() {
+    this.Count.Value = this.Count.Value + 1;
   }
+
+  template from "./counter.html";
 }
 `;
 
+const COUNTER_HTML_TEMPLATE = `<button (click)="Increment()">Count: {{ Count.Value }}</button>
+`;
+
 const APP_KS_TEMPLATE = `using "./kopular_bindings";
 using "./counter";
 
@@ -293,6 +296,7 @@ function scaffoldProject(dirPath) {
   writeFileSync(join(dirPath, "scripts", "vendor-kopular.mjs"), VENDOR_KOPULAR_MJS_TEMPLATE, "utf-8");
   writeFileSync(join(dirPath, "src", "kopular_bindings.ks"), KOPULAR_BINDINGS_KS_TEMPLATE, "utf-8");
   writeFileSync(join(dirPath, "src", "counter.ks"), COUNTER_KS_TEMPLATE, "utf-8");
+  writeFileSync(join(dirPath, "src", "counter.html"), COUNTER_HTML_TEMPLATE, "utf-8");
   writeFileSync(join(dirPath, "src", "app.ks"), APP_KS_TEMPLATE, "utf-8");
 
   console.log(`Created ${name} in ${dirPath}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kopular",
-  "version": "0.10.0",
-  "description": "Kopular: a small component framework for KopScript — components, reactive state, constructor-injected services, routing, structural directives, and HTTP, with no template DSL and no DI container",
+  "version": "0.11.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",
   "author": "Joe Koppin <koppinjo@gmail.com>",
@@ -38,6 +38,7 @@
   "scripts": {
     "build": "ks build src/router.ks && ks build src/directives.ks && ks build src/http.ks && ks build src/forms.ks",
     "prepublishOnly": "npm run build",
+    "pretest": "npm run build",
     "test": "vitest run",
     "test:watch": "vitest"
   },
@@ -50,7 +51,7 @@
     }
   },
   "devDependencies": {
-    "kopscript": "^0.5.0",
+    "kopscript": "^0.7.0",
     "@types/jsdom": "^30.0.0",
     "@types/node": "^20.14.0",
     "jsdom": "^25.0.1",

package/src/component.js

@@ -18,14 +18,14 @@ export class Component {
   }
 
   Mount(parent) {
-    (this.ParentElement = parent);
-    (this.Root = this.SafeRender());
+    this.ParentElement = parent;
+    this.Root = this.SafeRender();
     parent.appendChild(this.Root);
   }
 
   Update() {
     let newRoot = this.SafeRender();
     this.ParentElement.replaceChild(newRoot, this.Root);
-    (this.Root = newRoot);
+    this.Root = newRoot;
   }
 }

package/src/forms.js

@@ -15,16 +15,16 @@ class __KopState {
 
 export class FormField {
   constructor(initial, validate) {
-    (this.Value = new __KopState(initial));
-    (this.Error = new __KopState(validate(initial)));
-    (this.Touched = new __KopState(false));
+    this.Value = new __KopState(initial);
+    this.Error = new __KopState(validate(initial));
+    this.Touched = new __KopState(false);
     this.Value.Subscribe((v) => {
-  (this.Error.Value = validate(v));
+  this.Error.Value = validate(v);
 });
   }
 
   Touch() {
-    (this.Touched.Value = true);
+    this.Touched.Value = true;
   }
 
   Valid() {

package/src/router.js

@@ -4,23 +4,23 @@ import { Component } from "./component.js";
 export class Router extends Component {
   constructor(notFoundPage) {
     super();
-    (this.Paths = []);
-    (this.Pages = []);
-    (this.NotFoundPage = notFoundPage);
-    (this.Param = "");
-    (this.Guard = (path) => (true));
-    (this.RedirectPath = "");
+    this.Paths = [];
+    this.Pages = [];
+    this.NotFoundPage = notFoundPage;
+    this.Param = "";
+    this.Guard = (path) => (true);
+    this.RedirectPath = "";
     window.addEventListener("popstate", (e) => (this.Update()));
   }
 
   AddRoute(path, page) {
-    (this.Paths = [...this.Paths, path]);
-    (this.Pages = [...this.Pages, page]);
+    this.Paths = [...this.Paths, path];
+    this.Pages = [...this.Pages, page];
   }
 
   SetGuard(redirectPath, guard) {
-    (this.RedirectPath = redirectPath);
-    (this.Guard = guard);
+    this.RedirectPath = redirectPath;
+    this.Guard = guard;
   }
 
   Navigate(path) {
@@ -32,39 +32,39 @@ export class Router extends Component {
     let effectivePath = path;
     if (!this.Guard(path)) {
       history.pushState("", "", this.RedirectPath);
-      (effectivePath = this.RedirectPath);
+      effectivePath = this.RedirectPath;
     }
     let pathSegments = effectivePath.split("/");
     let found = this.NotFoundPage;
     let param = "";
-    for (let i = 0; (i < this.Paths.length); (i = (i + 1))) {
+    for (let i = 0; (i < this.Paths.length); i = (i + 1)) {
       let patternSegments = this.Paths[i].split("/");
       if ((patternSegments.length !== pathSegments.length)) {
         continue;
       }
       let matched = true;
       let capturedParam = "";
-      for (let j = 0; (j < patternSegments.length); (j = (j + 1))) {
+      for (let j = 0; (j < patternSegments.length); j = (j + 1)) {
         if (patternSegments[j].startsWith(":")) {
-          (capturedParam = pathSegments[j]);
+          capturedParam = pathSegments[j];
         } else if ((patternSegments[j] !== pathSegments[j])) {
-          (matched = false);
+          matched = false;
           break;
         }
       }
       if (matched) {
-        (found = this.Pages[i]);
-        (param = capturedParam);
+        found = this.Pages[i];
+        param = capturedParam;
         break;
       }
     }
-    (this.Param = param);
+    this.Param = param;
     return found;
   }
 
   Render() {
     let outlet = document.createElement("div");
-    (outlet.className = "router-outlet");
+    outlet.className = "router-outlet";
     let path = location.pathname;
     let page = this.Match(path);
     page.Mount(outlet);

package/src/testing.js

@@ -18,13 +18,26 @@
 // who actually calls this, not a weight every `kopular` install pays.
 import { JSDOM } from "jsdom";
 import { compileGraph } from "kopscript";
-import { cpSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const GLOBAL_KEYS = ["document", "Element", "Event", "location", "history", "window", "fetch"];
 const OWN_SRC_DIR = dirname(fileURLToPath(import.meta.url));
+// A hidden folder at this package's own root — for an external consumer,
+// that's inside their node_modules/kopular/, i.e. still within their
+// project tree. Deliberately NOT os.tmpdir(): Vitest/Vite's own module
+// resolution (used to dynamically `import()` the compiled fixture below)
+// restricts filesystem access to the project's workspace root by default,
+// and the OS temp directory sits outside that boundary entirely — on top
+// of macOS's os.tmpdir() itself being a symlink (/var/folders/... ->
+// /private/var/folders/...), a second, independent reason the same
+// resolution can fail. This bit a real CI run with "Failed to load url
+// kopular/component ... Does the file exist?" — a resolution failure, not
+// a transform error — while passing intermittently elsewhere, which is
+// exactly the signature of a filesystem-access-boundary problem rather
+// than anything wrong with the copied files themselves.
+const TEMP_ROOT = join(OWN_SRC_DIR, "..", ".kopular-testing-tmp");
 
 // Copies every .ks/.html file from `srcDir` into `dir`, plus any filename
 // listed in `extraFiles` (e.g. http_runtime.js — a hand-written sibling a
@@ -40,13 +53,14 @@ function copySources(srcDir, dir, extraFiles) {
 
 // kopscript's compiled output is genuine ESM (`export class ...`), which
 // Node only interprets correctly given a ".mjs" extension or an ancestor
-// package.json declaring "type": "module" — a bare os.tmpdir() has neither,
+// package.json declaring "type": "module" — a fresh directory has neither,
 // so the dynamic `import()` below would otherwise fail with "Cannot use
 // import statement outside a module" the moment anything outside this
 // file's own module graph (a real npm package, not code vitest/vite-node
 // itself transforms) tries to load it.
 function mkTempDir() {
-  const dir = mkdtempSync(join(tmpdir(), "kopular-testing-"));
+  mkdirSync(TEMP_ROOT, { recursive: true });
+  const dir = mkdtempSync(join(TEMP_ROOT, "run-"));
   writeFileSync(join(dir, "package.json"), JSON.stringify({ type: "module" }), "utf-8");
   return dir;
 }
@@ -57,9 +71,26 @@ function mkTempDir() {
 // not via relative `using`. Resolved off this very file's own location, so
 // it's always the real package as installed in the *caller's*
 // node_modules, not a guess at a path.
+//
+// Copies only package.json plus its own "files" allowlist (src, bin,
+// assets, LLM.md) — i.e. exactly what a real `npm install` would put there
+// — not the whole package root. Copying the root wholesale would also drag
+// along Kopular's *own* node_modules/.git/test, producing a nested
+// node_modules/kopular/node_modules/... no real consumer's install ever
+// has; that mismatch is what caused this to resolve fine in some
+// environments and fail with "Does the file exist?" in CI, since a
+// bundler's dependency resolution isn't obligated to behave the same in
+// the presence of a duplicate, unexpected nested node_modules.
 function copyKopularPackage(dir) {
-  mkdirSync(join(dir, "node_modules"), { recursive: true });
-  cpSync(join(OWN_SRC_DIR, ".."), join(dir, "node_modules", "kopular"), { recursive: true });
+  const kopularRoot = join(OWN_SRC_DIR, "..");
+  const pkg = JSON.parse(readFileSync(join(kopularRoot, "package.json"), "utf-8"));
+  const destRoot = join(dir, "node_modules", "kopular");
+  mkdirSync(destRoot, { recursive: true });
+  cpSync(join(kopularRoot, "package.json"), join(destRoot, "package.json"));
+  for (const entry of pkg.files ?? []) {
+    const src = join(kopularRoot, entry);
+    if (existsSync(src)) cpSync(src, join(destRoot, entry), { recursive: true });
+  }
 }
 
 // Shared by both exports below: compiles `entryFileName` (already written