kopular 0.15.0 → 0.15.1

package/LLM.md

@@ -22,7 +22,67 @@ there is no `kopular/template` entry point to import.
 ## Consuming Kopular from your own KopScript project
 
 `using` only resolves same-project relative paths — reaching into an npm package (Kopular
-included) always goes through `extern`, re-describing exactly the members you use:
+included) always goes through `extern`, re-describing exactly the members you use.
+
+**`Element`/`Document`/`Event` are NOT part of Kopular's own exports** — they're plain
+ambient browser globals (`extern class Element { ... };`, no `from` clause), genuinely
+present at runtime with no import needed, but Kopular has no re-exportable copy of them
+to reach for: `kopular/dom` is Kopular's own *internal* ambient binding, itself made of
+erased `extern` declarations with nothing real behind them at runtime, so `extern class
+Element { ... } from "kopular/dom";` doesn't work — there's no `Element` symbol actually
+living in that module to bind to. Every consuming project re-declares its own
+Element/Document/Event, same as this one does. **Copy the block below rather than
+hand-rolling a smaller one from scratch and adding members as compile errors demand
+them** — a real, complete first-attempt implementation of a Kopular app hit the exact
+same missing property (`Element.value`) twice from two independently-trimmed subsets,
+because the compile error only ever names the one member actually touched, never warns
+that a *sibling* feature (a template's `placeholder="..."` attribute, a `[(value)]`
+binding's generated `e.target.value` read) will need one you didn't happen to write by
+hand:
+
+```ks
+extern class Event {
+  Element target { get; }
+  void preventDefault();
+};
+
+extern class Element {
+  string textContent { get; set; }
+  string innerHTML { get; set; }
+  string id { get; set; }
+  string className { get; set; }
+  string href { get; set; }
+  string src { get; set; }
+  string alt { get; set; }
+  // Every `[(value)]="Field"` template binding and any handler reading
+  // `e.target.value` needs this — the single most commonly missing member
+  // when a hand-trimmed subset breaks.
+  string value { get; set; }
+  string placeholder { get; set; }
+  void appendChild(Element child);
+  void replaceChild(Element newChild, Element oldChild);
+  void insertBefore(Element newChild, Element? referenceChild);
+  void removeChild(Element child);
+  void setAttribute(string name, string value);
+  void addEventListener(string eventType, (Event) => void handler);
+  void removeEventListener(string eventType, (Event) => void handler);
+  Element querySelector(string selector);
+  Element? closest(string selector);
+};
+
+extern class Document {
+  Element createElement(string tagName);
+  Element getElementById(string id);
+  Element body { get; }
+};
+
+extern Document document;
+```
+
+Trim what you genuinely never use (this is still "describe exactly the members you
+use," not "always paste everything") — but trim it *after* writing the app, not before,
+so the trim is informed by what actually compiled, not a guess at what a template will
+eventually need.
 
 ```ks
 extern class VElement {

package/README.md

@@ -549,6 +549,15 @@ Marking `Render()` `virtual` in the `extern` declaration is what lets a real sub
 for a full working example (components, a service, and routing, all consuming Kopular
 this way).
 
+The snippet above is illustrative, not exhaustive — real code needs a fuller
+`VElement`/`Component`/`Router`, and `Element` itself (used above as `Mount`'s
+parameter type but never shown declared) is a plain ambient browser global your own
+project declares, not something Kopular exports — `LLM.md`'s "Consuming Kopular from
+your own KopScript project" section has the complete, copy-ready block for all of
+these, `Element`/`Document`/`Event` included. `npx kp new` (above) generates this
+boilerplate for a fresh project either way — reach for `LLM.md`'s block when adding to
+an existing one instead.
+
 `extern class` can carry its own `<T>` (kopscript >= 0.5.0), so a generic export like
 `FormField<T>` describes the same way a real generic class does — see `LLM.md`'s
 `FormField<T>`/`Validators` section for the full example.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Kopular: a small component framework for KopScript — components, reactive state, constructor-injected services, routing, real compiled templates, and HTTP, with no DI container",
   "type": "module",
   "license": "MIT",