@nativele/ts-dom 0.4.0 → 0.5.0

package/dist/index.d.mts

@@ -176,7 +176,15 @@ export declare function event<T = void>(opts?: {
 type DetailOf<D> = D extends EventDecl<infer T> ? T : never;
 type EmitArgs<D> = [DetailOf<D>] extends [void] ? [detail?: undefined] : [detail: DetailOf<D>];
 /** The data passed to render(): state, props and derived values merged. */
-type View<D, R> = Readonly<D> & Readonly<R>;
+/**
+ * Read-only all the way down: arrays, objects, Maps and Sets inside it cannot be changed through it.
+ * State, props and derived values are typed this way, so changing an object in place instead of passing a new one is a tsc error.
+ */
+type DeepReadonly<T> = T extends ((...args: never[]) => unknown) ? T : T extends Node | Date | RegExp | Promise<unknown> ? T : T extends ReadonlyMap<infer K, infer V> ? ReadonlyMap<K, DeepReadonly<V>> : T extends ReadonlySet<infer V> ? ReadonlySet<DeepReadonly<V>> : T extends readonly unknown[] ? { readonly [K in keyof T]: DeepReadonly<T[K]>; } : T extends object ? IsPlainObject<T> extends true ? { readonly [K in keyof T]: DeepReadonly<T[K]>; } : T : T;
+type IsPlainObject<T> = { [K in keyof T]: T[K]; } extends T ? true : false;
+/** Props as the element exposes them: the parent assigns them, but cannot change the objects inside through them. */
+type PropAccessors<P> = { -readonly [K in keyof P]: DeepReadonly<P[K]>; };
+type View<D, R> = DeepReadonly<D> & DeepReadonly<R>;
 interface DataOptions<St extends object, P extends object, R, E extends Record<string, EventDecl<unknown>>> extends ComponentOptions {
   /** Data owned by the component and changed only through set(). Fields named like a {{ hole }} or data-if in the HTML bind automatically. */
   state?: St;
@@ -190,7 +198,7 @@ interface DataOptions<St extends object, P extends object, R, E extends Record<s
    * Derived values: computed from state and props, usable directly by {{ holes }}, data-if and render().
    * Recomputed after every data change (there is no dependency tracking).
    */
-  derive?: { [K in keyof R]: (s: Readonly<St & P>) => R[K]; };
+  derive?: { [K in keyof R]: (s: DeepReadonly<St & P>) => R[K]; };
   /** The events this component emits. */
   emits?: E;
 }
@@ -210,15 +218,25 @@ type Problems<S extends Schema, St, P, R, E> = ([keyof St | keyof P | keyof R] e
 });
 type IsClean<T> = unknown extends T ? true : false;
 type Lists<S extends Schema> = { [K in keyof S["lists"]]: List<S["lists"][K]>; };
-/** The second argument received by a data-on-* handler method. */
-interface EventHit<Item = unknown> {
+/**
+ * The second argument received by a data-on-* handler method.
+ * In a handler for events inside list items, name the item type and its key field, e.g. `hit: EventHit<Todo, "id">`: `hit.item` is then a `Todo` and `hit.key` a `Todo["id"]`.
+ */
+type EventHit<Item = unknown, KeyField extends keyof Item = never> = [KeyField] extends [never] ? {
   /** The element that carries the data-on-* attribute */
   readonly el: Element;
   /** When the event happened inside a list item: the key of that item */
   readonly key?: PropertyKey;
-  /** When the event happened inside a list item: the data last passed to update() for that item. Annotate the handler, e.g. `hit: EventHit<Todo>`, to type it. */
+  /** When the event happened inside a list item: the data of that item. Annotate the handler, e.g. `hit: EventHit<Todo, "id">`, to type it. */
   readonly item?: Item;
-}
+} : {
+  /** The element that carries the data-on-* attribute */
+  readonly el: Element;
+  /** The key of the list item the event happened in */
+  readonly key: Item[KeyField];
+  /** The data of the list item the event happened in */
+  readonly item: Item;
+};
 interface ComponentInstance<S extends Schema> extends HTMLElement {
   /** Type inference only (define() uses it to check that data-on-* methods exist); does not exist at runtime. */
   readonly "~events"?: S["events"];
@@ -246,21 +264,21 @@ interface ComponentInstance<S extends Schema> extends HTMLElement {
 /** Members added when the `state` / `props` / `derive` / `emits` options are used. */
 interface StatefulInstance<S extends Schema, St extends object, P extends object, R, E extends Record<string, EventDecl<unknown>>> extends ComponentInstance<S> {
   /** The component's own data (read-only). Use set() to change it. */
-  readonly state: Readonly<St>;
+  readonly state: DeepReadonly<St>;
   /** Data provided by the parent (read-only). Do not assign it inside the component; use emit() to notify the parent. */
-  readonly props: Readonly<P>;
+  readonly props: DeepReadonly<P>;
   /**
    * The only way to change state: shallow-merges the patch, and does nothing when no field actually changed.
    * When something changed it synchronously updates the same-named {{ holes }} and data-if, then calls render(). It cannot change props.
    */
-  set(patch: Partial<St> | ((s: Readonly<St>) => Partial<St>)): void;
+  set(patch: Partial<DeepReadonly<St>> | ((s: DeepReadonly<St>) => Partial<DeepReadonly<St>>)): void;
   /** Coalesce several set() calls and prop changes: the view is updated and render() is called once, after fn returns. */
   batch(fn: () => void): void;
   /**
    * Override it to handle updates that automatic binding cannot do (lists, attributes, focus, ...).
-   * `view` is state, props and derived values merged; `changed` holds the fields that changed (all of them on the first render).
+   * `view` is state, props and derived values merged; `changed` holds the names of the state fields, props and derived values that changed (all of them on the first render).
    */
-  render(view: View<St & P, R>, changed: ReadonlySet<keyof St | keyof P>): void;
+  render(view: View<St & P, R>, changed: ReadonlySet<keyof St | keyof P | keyof R>): void;
   /** Emit an event declared in `emits` (it does not bubble by default and only reaches this element itself). */
   emit<K extends keyof E & string>(name: K, ...detail: EmitArgs<E[K]>): void;
   /** Type inference only (EmitEvent uses it to get the detail type of an event); does not exist at runtime. */
@@ -284,7 +302,7 @@ export declare function Component<S extends Schema>(tpl: Template<S>, opts?: Com
  * `reservedPropNames` (a prop shares a name with HTMLElement or a ts-dom member), `nativeEventNames` (emits shares a name with a native event).
  * (The check lives in the return type, not in the parameter: in the parameter it prevents TypeScript from inferring the type of derive.)
  */
-export declare function Component<S extends Schema, St extends object = Record<never, never>, P extends object = Record<never, never>, R = Record<never, never>, E extends Record<string, EventDecl<unknown>> = Record<never, never>>(tpl: Template<S>, opts: DataOptions<St, P, R, E>): IsClean<Problems<S, St, P, R, E>> extends true ? new () => StatefulInstance<S, St, P, R, E> & P : Problems<S, St, P, R, E>;
+export declare function Component<S extends Schema, St extends object = Record<never, never>, P extends object = Record<never, never>, R = Record<never, never>, E extends Record<string, EventDecl<unknown>> = Record<never, never>>(tpl: Template<S>, opts: DataOptions<St, P, R, E>): IsClean<Problems<S, St, P, R, E>> extends true ? new () => StatefulInstance<S, St, P, R, E> & PropAccessors<P> : Problems<S, St, P, R, E>;
 type CheckHandlers<I> = I extends {
   readonly "~events"?: infer E;
 } ? [Exclude<NonNullable<E>, keyof I>] extends [never] ? unknown : {
@@ -295,4 +313,4 @@ type CheckHandlers<I> = I extends {
  * component as a public method, otherwise tsc reports an error that lists the missing names (`missingHandlers`).
  */
 export declare function define<C extends abstract new (...args: never[]) => HTMLElement>(name: string, ctor: C & CheckHandlers<InstanceType<C>>): void;
-export type { ComponentInstance, ComponentOptions, DataOptions, El, EmitEvent, EventDecl, EventHit, ItemContext, ListItem, ListSchema, ReadableStore, ReplaceOptions, Schema, StatefulInstance, Store, Template, TemplateInstance, TextOf, TextValue, Update, View };
+export type { ComponentInstance, ComponentOptions, DataOptions, DeepReadonly, El, EmitEvent, EventDecl, EventHit, ItemContext, ListItem, ListSchema, PropAccessors, ReadableStore, ReplaceOptions, Schema, StatefulInstance, Store, Template, TemplateInstance, TextOf, TextValue, Update, View };

package/dist/index.mjs

@@ -228,7 +228,7 @@ var List = class {
 		if (!this.binding) throw new Error("[list-not-bound] this list has no data-key and data-prop, so its items cannot be assigned. Fix: add them to the <template data-each>, e.g. data-key=\"id\" data-prop=\"item\", or call replace().");
 		if (!Array.isArray(items)) throw new Error(`[invalid-items] items must be an array of objects, but got ${items === null ? "null" : typeof items}. Fix: assign an array, for example items = view.todos ?? [].`);
 		if (items.length) this.#checkProp();
-		this.replace(items, this.#keyOf, this.#assign, { skipUnchanged: true });
+		this.#reconcile(items, this.#keyOf, this.#assign, true, true);
 	}
 	#checkProp() {
 		const prop = this.binding?.prop;
@@ -263,7 +263,7 @@ var List = class {
 		return this.#items.get(key);
 	}
 	#create(key) {
-		const el = this.proto.cloneNode(true);
+		const el = this.binding ? document.importNode(this.proto, true) : this.proto.cloneNode(true);
 		const holder = document.createDocumentFragment();
 		holder.append(el);
 		const conds = mountConds(holder);
@@ -324,6 +324,10 @@ var List = class {
 	}
 	/** Keyed reconciliation: remove extra items, create missing ones, reorder, and call update() for every item. */
 	replace(items, key, update, opts = {}) {
+		this.#reconcile(items, key, update, opts.skipUnchanged === true, false);
+	}
+	/** `updateFirst`: a new item is updated before it is inserted, so an item component is connected with its prop already set. */
+	#reconcile(items, key, update, skipUnchanged, updateFirst) {
 		const next = /* @__PURE__ */ new Set();
 		for (const it of items) {
 			const k = key(it);
@@ -340,13 +344,14 @@ var List = class {
 			if (!entry) {
 				entry = this.#create(k);
 				this.#items.set(k, entry);
+				if (updateFirst) this.#run(entry, k, it, update);
 			}
 			if (entry.el.nextSibling !== after || entry.el.parentNode !== parent) {
 				if (entry.el.parentNode === parent && parent?.moveBefore) parent.moveBefore(entry.el, after);
 				else parent?.insertBefore(entry.el, after);
 			}
 			after = entry.el;
-			this.#run(entry, k, it, update, opts.skipUnchanged);
+			this.#run(entry, k, it, update, skipUnchanged);
 		}
 	}
 };
@@ -657,7 +662,10 @@ function Component(tpl, opts = {}) {
 			for (const [name, fn] of Object.entries(opts.derive ?? {})) {
 				const v = fn(to);
 				derived[name] = v;
-				if (!from || !Object.is(this.#derived[name], v)) bindName(name, v);
+				if (!from || !Object.is(this.#derived[name], v)) {
+					bindName(name, v);
+					keys.push(name);
+				}
 			}
 			this.#derived = derived;
 			this.render({

package/dist/{lint-CqWk4U5P.mjs → lint-5vo_ifIc.mjs}

@@ -1,4 +1,4 @@
-import { a as analyze, d as listHtml, f as scanDefines } from "./a11y-Bn9pDvWV.mjs";
+import { a as analyze, f as listHtml, h as scanDefines } from "./a11y-wWL9rie7.mjs";
 import { readFileSync } from "node:fs";
 import { basename, dirname, relative } from "node:path";
 // src/lib/lint.ts
@@ -43,7 +43,8 @@ function componentClasses(code, htmlSpec) {
 		const bodyEnd = matchClose(code, bodyStart, "{", "}");
 		if (bodyEnd > 0) out.push({
 			call: code.slice(call, callEnd + 1),
-			body: code.slice(bodyStart, bodyEnd + 1)
+			body: code.slice(bodyStart, bodyEnd + 1),
+			end: bodyEnd
 		});
 	}
 	return out;
@@ -144,7 +145,8 @@ const DATA_FLOW_RULES = {
 	"custom-event-on-native": "a custom event belongs on the child component tag that emits it, not on a native element",
 	"unknown-prop": "the attribute is not a declared prop of the child component",
 	"invalid-prop-value": "the attribute value cannot be converted to the prop's type",
-	"unknown-event": "the child component does not emit this event"
+	"unknown-event": "the child component does not emit this event",
+	"unguarded-input-value": "render() writes a form control's value without comparing it first, which moves the caret while the user types"
 };
 /** Common native events. A data-on-* on a native element whose event is not listed here is treated as a custom event. */
 const NATIVE_EVENTS = new Set(`click dblclick auxclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave contextmenu wheel keydown keyup keypress input beforeinput change submit reset invalid select focus blur focusin focusout scroll resize load unload error abort toggle cancel close drag dragstart dragend dragenter dragleave dragover drop copy cut paste compositionstart compositionupdate compositionend touchstart touchmove touchend touchcancel pointerdown pointerup pointermove pointerover pointerout pointerenter pointerleave pointercancel gotpointercapture lostpointercapture animationstart animationend animationiteration transitionstart transitionend transitionrun transitioncancel play pause ended playing timeupdate volumechange seeking seeked loadeddata loadedmetadata canplay waiting slotchange fullscreenchange online offline hashchange popstate storage message`.split(/\s+/));
@@ -307,6 +309,20 @@ function dataFlow(html, classes, ignore = [], contracts = /* @__PURE__ */ new Ma
 		const tag = /El<"([^"]+)">/.exec(type)?.[1];
 		if (tag?.includes("-")) customRefs.set(name, tag);
 	}
+	const formControls = new Set([...a.scope.refs].filter(([, type]) => /El<"(input|textarea|select)">/.test(type)).map(([name]) => name));
+	for (const { body } of classes) {
+		const render = methodBody(body, "render");
+		if (!render || !formControls.size) continue;
+		const lines = render.split("\n");
+		lines.forEach((line, i) => {
+			for (const m of line.matchAll(/\brefs\.(\w+)\.value\s*=(?!=)/g)) {
+				const ref = m[1];
+				if (!formControls.has(ref)) continue;
+				if ([line, lines[i - 1] ?? ""].some((l) => new RegExp(`refs\\.${esc(ref)}\\.value\\s*!==?`).test(l))) continue;
+				report("unguarded-input-value", `render() assigns this.refs.${ref}.value without comparing it first. Writing a form control's value while the user types moves the caret to the end. Fix: if (this.refs.${ref}.value !== next) this.refs.${ref}.value = next;`, `ref:${ref}`);
+			}
+		});
+	}
 	for (const { call, body } of classes) {
 		const props = optionKeys(call, "props");
 		for (const k of props) if (new RegExp(`\\bthis\\.${esc(k)}\\s*(?:[-+*/%]?=(?!=)|\\+\\+|--)`).test(body)) report("props-mutation", `The prop "${k}" is controlled by the parent component; do not assign this.${k} inside the component. Fix: emit an event so the parent changes it, or keep the value in state instead.`);

package/dist/oxlint-plugin.d.mts

@@ -4,6 +4,13 @@ interface ImportNode {
     value: string;
   };
 }
+interface Fixer {
+  insertTextBeforeRange(range: [number, number], text: string): unknown;
+}
+interface Suggestion {
+  desc: string;
+  fix(fixer: Fixer): unknown;
+}
 interface Context {
   options?: [{
     ignore?: string[];
@@ -15,6 +22,7 @@ interface Context {
   report(d: {
     message: string;
     node: unknown;
+    suggest?: Suggestion[];
   }): void;
 }
 declare const _default: {
@@ -22,7 +30,7 @@ declare const _default: {
     name: string;
   };
   rules: {
-    /** The HTML declares markup that this file never uses. Always on when enabled; reported as errors. */
+    /** The HTML declares markup that this file never uses. Reported as errors. */
     "unused-markup": {
       meta: {
         type: "suggestion";
@@ -41,6 +49,7 @@ declare const _default: {
           };
           additionalProperties: boolean;
         }[];
+        hasSuggestions: boolean;
       };
       create(context: Context): {
         ImportDeclaration(node: ImportNode): void;
@@ -65,6 +74,7 @@ declare const _default: {
           };
           additionalProperties: boolean;
         }[];
+        hasSuggestions: boolean;
       };
       create(context: Context): {
         ImportDeclaration(node: ImportNode): void;
@@ -89,6 +99,7 @@ declare const _default: {
           };
           additionalProperties: boolean;
         }[];
+        hasSuggestions: boolean;
       };
       create(context: Context): {
         ImportDeclaration(node: ImportNode): void;

package/dist/oxlint-plugin.mjs

@@ -1,5 +1,5 @@
-import { n as checkA11y } from "./a11y-Bn9pDvWV.mjs";
-import { a as dataFlow, i as contractsFor, l as templateCode, r as componentClasses, u as unusedMarkup } from "./lint-CqWk4U5P.mjs";
+import { n as checkA11y, t as A11Y_RULES } from "./a11y-wWL9rie7.mjs";
+import { a as dataFlow, i as contractsFor, l as templateCode, n as UNUSED_MARKUP_RULES, r as componentClasses, t as DATA_FLOW_RULES, u as unusedMarkup } from "./lint-5vo_ifIc.mjs";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 // src/lib/oxlint-plugin.ts
@@ -14,46 +14,86 @@ const ignoreSchema = [{
 /** Child component contracts, scanned once per process from the working directory. */
 let contracts = null;
 const getContracts = () => contracts ??= contractsFor([process.cwd()]);
+const cache = /* @__PURE__ */ new Map();
+function groupDiagnostics(group, html, code, spec, filename) {
+	const key = `${group}\0${filename}\0${spec}`;
+	const hit = cache.get(key);
+	if (hit && hit.code === code && hit.html === html) return hit.diags;
+	const diags = group === "unused-markup" ? unusedMarkup(html, templateCode(code, spec)) : group === "a11y" ? checkA11y(html) : dataFlow(html, componentClasses(code, spec), [], getContracts());
+	cache.set(key, {
+		code,
+		html,
+		diags
+	});
+	return diags;
+}
+function readTemplate(filename, spec) {
+	try {
+		return readFileSync(resolve(dirname(filename), spec.slice(0, -3)), "utf8");
+	} catch {
+		return null;
+	}
+}
+/** A missing handler can be added to the class that uses the template: offered as a suggestion, since the method body is the developer's to write. */
+function suggestionsFor(d, code, spec) {
+	if (d.rule !== "missing-handler") return void 0;
+	const name = /="([^"]+)"/.exec(d.message)?.[1];
+	const target = componentClasses(code, spec)[0];
+	if (!name || !target) return void 0;
+	return [{
+		desc: `Add a method ${name}() to the component class`,
+		fix: (fixer) => fixer.insertTextBeforeRange([target.end, target.end], `\n  ${name}(_e: Event): void {}\n`)
+	}];
+}
 /**
-* Build an oxlint rule that runs `check` on every `import x from "./name.html.js"` and reports the findings
+* Build an oxlint rule that checks every `import x from "./name.html.js"` and reports the findings
 * on the import line (an oxlint plugin can only report inside the file being linted).
 * The message starts with the HTML location, the rule id and what to do: `./x.html.js:3:5 [unused-ref] ...`.
+* `only` limits the rule to one rule id of the group; without it the rule reports the whole group, minus `ignore`.
 */
-function templateRule(description, check) {
+function templateRule(group, description, only) {
 	return {
 		meta: {
 			type: "suggestion",
 			docs: { description },
-			schema: ignoreSchema
+			schema: only ? [] : ignoreSchema,
+			hasSuggestions: true
 		},
 		create(context) {
 			return { ImportDeclaration(node) {
 				const spec = node.source.value;
 				if (!spec.endsWith(".html.js")) return;
-				let html;
-				try {
-					html = readFileSync(resolve(dirname(context.filename), spec.slice(0, -3)), "utf8");
-				} catch {
-					return;
+				const html = readTemplate(context.filename, spec);
+				if (html === null) return;
+				const code = context.sourceCode.text;
+				const ignore = context.options?.[0]?.ignore ?? [];
+				for (const d of groupDiagnostics(group, html, code, spec, context.filename)) {
+					if (only ? d.rule !== only : ignore.includes(d.rule)) continue;
+					const suggest = suggestionsFor(d, code, spec);
+					context.report({
+						message: `${spec}:${d.line}:${d.col} [${d.rule}] ${d.message}`,
+						node,
+						...suggest ? { suggest } : {}
+					});
 				}
-				for (const d of check(html, context, spec)) context.report({
-					message: `${spec}:${d.line}:${d.col} [${d.rule}] ${d.message}`,
-					node
-				});
 			} };
 		}
 	};
 }
-const ignored = (c) => c.options?.[0]?.ignore ?? [];
+const perRule = (group, rules) => Object.fromEntries(Object.entries(rules).map(([id, description]) => [id, templateRule(group, description, id)]));
+const { "no-importer": _noImporter, ...unusedMarkupRules } = UNUSED_MARKUP_RULES;
 var oxlint_plugin_default = {
 	meta: { name: "ts-dom" },
 	rules: {
-		/** The HTML declares markup that this file never uses. Always on when enabled; reported as errors. */
-		"unused-markup": templateRule("Markup declared in the HTML (data-ref, data-if, data-each, {{ }}, data-on-*) must be used by the component class", (html, c, spec) => unusedMarkup(html, templateCode(c.sourceCode.text, spec)).filter((d) => !ignored(c).includes(d.rule))),
+		/** The HTML declares markup that this file never uses. Reported as errors. */
+		"unused-markup": templateRule("unused-markup", "Markup declared in the HTML (data-ref, data-if, data-each, {{ }}, data-on-*) must be used by the component class"),
 		/** ARIA and basic accessibility problems in the template. Off by default. */
-		a11y: templateRule("Check the template for ARIA and basic accessibility problems", (html, c) => checkA11y(html, ignored(c))),
+		a11y: templateRule("a11y", "Check the template for ARIA and basic accessibility problems"),
 		/** Data flow suggestions and child component contract checks. Off by default. */
-		"data-flow": templateRule("Keep props flowing down and events flowing up one level at a time, and check child component attributes and events", (html, c, spec) => dataFlow(html, componentClasses(c.sourceCode.text, spec), ignored(c), getContracts()))
+		"data-flow": templateRule("data-flow", "Keep props flowing down and events flowing up one level at a time, and check child component attributes and events"),
+		...perRule("unused-markup", unusedMarkupRules),
+		...perRule("data-flow", DATA_FLOW_RULES),
+		...perRule("a11y", Object.fromEntries(Object.entries(A11Y_RULES).map(([k, v]) => [k, v.split(". Fix:")[0]])))
 	}
 };
 export { oxlint_plugin_default as default };

package/dist/vite-plugin.mjs

@@ -1,4 +1,4 @@
-import { c as generateFile, d as listHtml, f as scanDefines, i as CodegenError, l as isFullPage, n as checkA11y, o as formatDiagnostics, s as generateAll, u as isSelected } from "./a11y-Bn9pDvWV.mjs";
+import { c as generateAll, d as isSelected, f as listHtml, h as scanDefines, i as CodegenError, l as generateFile, n as checkA11y, s as formatDiagnostics, u as isFullPage } from "./a11y-wWL9rie7.mjs";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { resolve, sep } from "node:path";
 // src/lib/vite-plugin.ts

package/llms.txt

@@ -1,8 +1,8 @@
 # Nativele
 
-> A TypeScript-driven, HTML-first UI library. Bind HTML templates to TypeScript custom elements. HTML describes structure and where data goes; TypeScript owns state and behavior; the DOM is the only view. Fully typed by tsc, no virtual DOM, no bundler required.
+> Designed for AI agents. Driven by TypeScript. Defined in vanilla HTML. A lightweight library for building web components: bind HTML templates to TypeScript custom elements. HTML describes structure and where data goes; TypeScript owns state and behavior; the DOM is the only view. Fully typed by tsc, no virtual DOM, no bundler required.
 
-Workflow: write `x.html` + `x.ts`, run `npx ts-dom gen` (writes `x.html.ts`), then `npx tsc`. Import a template as `import tpl from "./x.html.js"` (note the `.js`). Lint with `npx ts-dom lint` (add `--a11y`). `npx ts-dom rules` lists every rule id. Every diagnostic is `file:line:col severity [rule-id] message` and ends with a `Fix:` hint: read the hint and apply it.
+Workflow: write `x.html` + `x.ts`, run `npx ts-dom check` (regenerates `x.html.ts`, runs tsc and lint, points errors at the template). Import a template as `import tpl from "./x.html.js"` (note the `.js`). Lint with `npx ts-dom lint` (add `--a11y`). `npx ts-dom rules` lists every rule id. Every diagnostic is `file:line:col severity [rule-id] message` and ends with a `Fix:` hint: read the hint and apply it.
 
 ## Template syntax (HTML only names things; no expressions)
 - `{{ name }}`: text hole, a single identifier only. NOT `{{ a.b }}` / `{{ a + 1 }}`. Not allowed in attributes.
@@ -38,11 +38,14 @@ define("my-counter", MyCounter);
 Rules the compiler enforces: every `{{ hole }}` / `data-if` name must exist in state, props or derive (error `missingStateKeys`); state/props/derive names must be unique (`conflictingKeys`); a prop must not be named like an HTMLElement/ts-dom member such as `title`, `hidden`, `render` (`reservedPropNames`); emitted event names must not be native events (`nativeEventNames`); every `data-on-*` method must exist as a public method (`missingHandlers`, reported by `define()`).
 
 ## Data flow (one direction)
+- `state`, `props`, `render`'s `view` and `derive` arguments are `DeepReadonly`: changing an object or array inside them is a tsc error. Replace with new objects (`s.items.map((i) => (i.id === id ? { ...i, done: true } : i))`). Annotate with read-only types (`readonly Item[]`, `DeepReadonly<State>`).
 - State: changed only by its owner with `this.set(patch | s => patch)`; no change => no render. `this.batch(fn)` merges several updates. Rendering is synchronous.
 - Props go DOWN: the parent sets them with an attribute or a property (`this.refs.child.value = v.x`, typed). A component never assigns its own props; to ask for a change it `emit`s an event.
 - Events go UP: `emit` does not bubble; the parent handles it with `data-on-<event>` on the child tag, casting with `EmitEvent<Child, "event-name">`.
 - Data needed several levels away: share a `createStore` module and `this.bind(store, fn)`; do not forward props or re-emit events through middle components (lint rules `prop-forwarding`, `emit-forwarding`).
-- Writing form values back: only assign `input.value` when it differs (`if (input.value !== v.value) input.value = v.value`), otherwise the caret jumps.
+- `store.set` REPLACES the value (a component's `this.set` merges): `store.set((s) => ({ ...s, status: "loading" }))`. In a component with state/props/derive every `{{ hole }}` must be one of them, so copy store data into state in the `bind` callback: `this.bind(store, (s) => this.set({ total: s.items.length }))`.
+- Loading/error states, modal dialogs (a public `open()` called through a typed ref), form validation messages, filtered lists: `docs/recipes.md` and `examples/recipes/` in the repository.
+- Writing form values back (lint rule `unguarded-input-value`): only assign `input.value` when it differs (`if (input.value !== v.value) input.value = v.value`), otherwise the caret jumps.
 
 ## Minimal example
 ```html
@@ -68,13 +71,21 @@ define("my-counter", MyCounter);
 `const view = tpl.instantiate()` returns `{ root: DocumentFragment, rootElement, refs, lists, text, show }` typed like a component (`rootElement` exists in the type only when the template has exactly one top-level element, `<style>` excluded), for pieces created in code. No host: `data-on-*` is inert (use `refs.x.addEventListener`) and `<slot>` is not projected.
 
 ## Lists
-- Items that are components: `<template data-each="todos" data-key="id" data-prop="todo"><todo-row></todo-row></template>`, then `this.lists.todos.items = view.todos` (inside `render`, guarded by `changed.has("todos")`). Keeps the element of each key, creates and removes the rest, sets the `todo` prop of each changed item; `hit.key` in handlers. The item component declares `todo` in its `props`; `tsc` checks the items against that prop type and the `data-key` field; an item component defined in a scanned folder must be exported and listed in `ts-dom-tags.ts` (run `ts-dom gen`), otherwise the assignment is a type error that names the problem.
+- Rule: an item with anything of its own (state, events, a nested list) is a component filled with `items =`; an item of a few texts and `data-if` is plain elements filled with `replace()`.
+- Subscribe in `connected()`, never in the constructor: without `moveBefore` a moved item is disconnected (its `bind`/`on`/`onCleanup` released) and connected again. Data every item needs goes in a `createStore` the item binds.
+- Full example (add, remove, sort, toggle, child emit): `examples/readme/task-board.ts` and `task-row.ts` in the repository.
+- Items that are components: `<template data-each="todos" data-key="id" data-prop="todo"><todo-row></todo-row></template>`, then `this.lists.todos.items = view.todos` (inside `render`, guarded by `changed.has("todos")`; `changed` holds the state, prop and derived names that changed, so a derived list is guarded by its own name). Keeps the element of each key, creates and removes the rest, sets the `todo` prop of each changed item; `hit.key` in handlers (`hit: EventHit<Todo, "id">` types `hit.key` and `hit.item`). The item component declares `todo` in its `props`; `tsc` checks the items against that prop type and the `data-key` field; an item component defined in a scanned folder must be exported and listed in `ts-dom-tags.ts` (run `ts-dom gen`), otherwise the assignment is a type error that names the problem.
 - Items that are plain elements: `<template data-each="x">` with `this.lists.x.replace(items, keyFn, (item, { text, show }) => ...)`.
 - `data-each` is never nested: a list inside an item is the item component's own `data-each`.
 
 ## Rules for agents
-- Never edit `x.html.ts` or `ts-dom-tags.ts` (generated). After any `.html` change run `npx ts-dom gen && npx tsc` and fix every type error instead of casting it away. Until `gen` has run, `tsc` only reports that `./x.html.js` is missing.
-- No expressions in HTML; computed values go in `derive`. Change state only with `this.set()`. Lists, attributes and focus go in `render(view, changed)`; check `changed.has("items")` before rebuilding a list.
+- Skills: `npx ts-dom skills` lists the task procedures shipped with the package (`nativele-core` for building components, `nativele-react` for React 19, ...), each with verified versions; `npx ts-dom skills <name>` prints one, `npx ts-dom skills add <name>` copies it into `.claude/skills/` or `.agents/skills/`, and `npx ts-dom doctor` suggests the ones that match the project's dependencies.
+- `npx ts-dom rules --explain=<id>` (or `rules --json`) explains any rule id from a diagnostic: why it exists, a wrong example and the fix.
+- Markup well-formedness is a formatter's job: `oxfmt --check` reports misnested tags that the library's parser would silently repair. Generate with `--whitespace=collapse` when a formatter is used.
+- If checks behave oddly (no types, a template not found), run `npx ts-dom doctor --json` first: it reports tsconfig, import path, runtime, generated file and plugin problems with a `Fix:` each.
+- `npx ts-dom gen --check` (writes nothing, exit 1) tells whether the generated files are stale before you trust `tsc` errors.
+- Never edit `x.html.ts` or `ts-dom-tags.ts` (generated). After any `.html` or component change run `npx ts-dom check --json`: it regenerates, runs tsc, maps template contract errors to the template line/col (`missing-binding`, `missing-handler`, item rules), and runs lint. Fix every issue by its `Fix:` hint; never cast a type error away.
+- No expressions in HTML; computed values go in `derive`. Change state only with `this.set()`. Lists, attributes and focus go in `render(view, changed)`; check `changed.has("items")` before rebuilding a list, and annotate `changed` with the names you check (`ReadonlySet<"items" | "visible">`), not `ReadonlySet<string>`, so tsc checks them.
 - Props go down (parent sets them), events go up (`emit`, handled with `data-on-<event>` on the child tag). `data-each` cannot be nested: make the inner list its own component.
 
 ## Setup
@@ -87,9 +98,11 @@ In a browser without a bundler map the bare name once: `<script type="importmap"
 ## Pitfalls
 - Import templates with `./x.html.js`, not `./x.html`. Run `ts-dom gen` before `tsc` (it creates `x.html.ts` and `ts-dom-tags.ts`; both are generated, do not edit or commit).
 - Exports: `export class` the component to get typed `refs.child` in parent templates (`define("tag", Class)` is scanned).
-- `data-if` content is hidden until the name is truthy; `{{ hole }}` stays empty until filled.
+- `data-if` content is hidden until the name is truthy (it stays in memory, so its `refs` still work); `{{ hole }}` stays empty until filled.
+- With Vite, `package.json` needs `"type": "module"`.
 - `slotchange()` is Light-DOM only; with `shadow: true` use the native `slotchange` event.
 
 ## Docs
-- [README](README.md): full guide. [README.zh-TW.md](README.zh-TW.md): same in Traditional Chinese.
+- [README](README.md): introduction, the short version, rules for agents, quick start. [README.zh-TW.md](README.zh-TW.md): the same in Traditional Chinese.
+- Guides (English): [templates](docs/templates.md), [components and data flow](docs/components.md), [lists](docs/lists.md), [setup, checks and lint](docs/tooling.md), [performance](docs/performance.md), [design](docs/design.md), [developing Nativele](docs/contributing.md).
 - `npx ts-dom rules`: every rule id with a description.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nativele/ts-dom",
-  "version": "0.4.0",
-  "description": "A TypeScript-driven, HTML-first UI library. Bind HTML to TypeScript: HTML describes the structure, TypeScript owns behavior and state, and the DOM is the single source of truth. Fully typed, no virtual DOM, no bundler required.",
+  "version": "0.5.0",
+  "description": "Designed for AI agents. Driven by TypeScript. Defined in vanilla HTML. A lightweight library for building web components: typed templates, native custom elements, no virtual DOM, no template expressions, no bundler required.",
   "keywords": [
     "html",
     "typescript",
@@ -49,6 +49,8 @@
     "README.md",
     "README.zh-TW.md",
     "llms.txt",
+    "skills/README.md",
+    "skills/*/SKILL.md",
     "LICENSE",
     "CHANGELOG.md"
   ],
@@ -68,7 +70,8 @@
     "test:browser": "vp test run browser/",
     "verify:pack": "vp pack --publint --attw",
     "smoke": "bash scripts/consumer-smoke.sh",
-    "smoke:no-bundler": "bash scripts/no-bundler-smoke.sh"
+    "smoke:no-bundler": "bash scripts/no-bundler-smoke.sh",
+    "bench": "node scripts/bench.ts"
   },
   "dependencies": {
     "parse5": "^8.1.0"

package/skills/README.md

@@ -0,0 +1,114 @@
+# Nativele Skills
+
+Skills extend what Nativele can be used with, without growing the library: each one is a task procedure for a coding agent, verified with exact versions. This page is the specification every Skill follows and the guide for contributing one.
+
+## What a Skill is
+
+A Skill is a task procedure for a coding agent: how to do one integration or one kind of work with Nativele, step by step, with a complete example, the known limitations, and commands that prove it worked. It is not reference documentation: facts about the library's API live in `docs/`, and a Skill links to them instead of restating them.
+
+A Skill never changes the library's runtime and never adds a dependency to the library's core. Third-party packages a Skill uses are dependencies of the user's project, installed by the Skill's own steps.
+
+## Layout
+
+```
+skills/
+├── README.md                     # this specification and the contribution guide
+├── nativele-core/
+│   └── SKILL.md
+├── nativele-react/
+│   ├── SKILL.md
+│   └── example/                  # Official only: the project the Skill is verified with
+│       ├── package.json          # exact versions of every tool the Skill names
+│       ├── ...                   # the minimal app the SKILL.md example comes from
+│       └── verify.mjs            # the browser checks `npm run verify` ends with
+└── ...
+```
+
+The npm package ships every `SKILL.md` (so the CLI can list and read them offline), not the `example/` folders.
+
+## SKILL.md format
+
+`SKILL.md` follows the Agent Skills format (YAML frontmatter with `name` and `description`, then Markdown), so Claude Code and other agents that read skills can load it as it is. Nativele's own fields go under `metadata`:
+
+```markdown
+---
+name: nativele-react
+description: "Use Nativele web components inside a React 19 app: props, events, children and slots, lifecycle, and TSX types. Use when a project has react and @nativele/ts-dom."
+metadata:
+  tier: official                 # official | community | experimental
+  nativele: ">=0.5.0 <0.6.0"     # the library versions the Skill was verified with
+  verified: "2026-11-05"         # date of the last verification
+  tools: "react@19.3.1 react-dom@19.3.1 vite@8.3.5 @vitejs/plugin-react@6.2.1 typescript@7.0.2"
+  author: "Nativele maintainers" # for community Skills: the contributor
+  detects: "react"               # package.json dependencies that make ts-dom doctor recommend this Skill
+---
+```
+
+Quote the `description` and any value that contains `: `, so the frontmatter stays valid YAML for every agent that loads it.
+
+Required sections, in this order:
+
+1. **When to use**: the situation and the signals (dependencies, files) that call for this Skill, and when not to use it.
+2. **Versions**: a table of every tool and the exact version it was verified with, and the date. If the project uses a different major version of a tool, the Skill says so and stops treating its steps as verified.
+3. **Set-up**: numbered steps with the exact commands and file contents.
+4. **Example**: a complete, minimal working example (every file it needs, short).
+5. **Known limitations**: what does not work or needs care, each with what to do instead. An agent must never have to guess these.
+6. **Verify**: the commands that prove the integration works in the user's project (for example `npx ts-dom check`, `npx tsc --noEmit`, the project's build, a test), with the output to expect.
+7. **Troubleshooting**: symptoms seen while verifying, their cause and fix.
+8. **See also**: links to the guides in `docs/` for the facts used.
+
+Rules for the content:
+
+- Only what was run: every step, example and limitation comes from the verified example, not from memory of how a tool used to work.
+- Version-bound statements say so ("React 19 passes object props as properties; React 18 passes everything as attributes").
+- No promises beyond the verified versions.
+- English, plain and concrete; no restating of `docs/`.
+
+## Tiers
+
+| Tier | Who maintains it | Requirements | Shown by `ts-dom skills` |
+|---|---|---|---|
+| Official | the Nativele maintainers | an `example/` project that `npm run verify` checks in CI; verified within the last 6 months | as official |
+| Community | its author | the full SKILL.md format, `author` and `verified` filled in, the verification commands run by the author | as community, with the author |
+| Experimental | its author | the SKILL.md format; verification not complete | as experimental, with a warning |
+
+- A new contribution starts as Experimental. It becomes Community when a reviewer has run its verification commands with the stated versions, and Official when the maintainers adopt it with an `example/` project in CI.
+- A Skill whose `verified` date is older than 6 months, or whose `nativele` range does not include the installed version, is shown as stale. A stale Official Skill whose CI check fails is moved to Experimental until fixed.
+
+## Delivering Skills to projects
+
+The library already lives in the user's `node_modules`, so its Skills travel with it:
+
+- `ts-dom skills` lists the Skills shipped with the installed version: name, tier, description, verified date and versions, whether it is stale, and its path inside `node_modules`. `--json` prints the same as data for agents.
+- `ts-dom skills <name>` prints that Skill (so an agent can read it without knowing the path).
+- `ts-dom skills add <name...>` copies Skills into the project: into `.claude/skills/<name>/` when the project has a `.claude` folder, otherwise into `.agents/skills/<name>/` (`--to=<dir>` for another folder), where agents that load skills pick them up. It only copies; it never installs the third-party packages a Skill mentions.
+- `ts-dom doctor` reads the project's `package.json` and, for each Skill whose `detects` dependency is present and that the project has no copy of, reports it as an `info` issue (`skill-available`); a copy that differs from the shipped one is reported as `skill-outdated`, for example: `package.json:1:1 info [skill-available] react is a dependency: the nativele-react Skill covers using Nativele components in React. Fix: run ts-dom skills add nativele-react, or read it with ts-dom skills nativele-react.` Info issues never change the exit code.
+
+None of this adds a runtime dependency: listing and copying read the Markdown files with Node's file API, and the frontmatter is parsed with a small reader for the fields above.
+
+## Verification of Official Skills
+
+- `skills/<name>/example/package.json` pins every tool version the Skill names, depends on the library through `file:../../..` (the library in the same repository), and has `npm run verify`, which runs `ts-dom check`, `ts-dom doctor`, `tsc`, the build, and a short real-browser test of what the Skill promises.
+- `nativele-core` has no example of its own: the library's CI, which checks every example in the repository, verifies it.
+- The workflow `.github/workflows/skills.yml` runs `npm run verify` for each Official Skill when anything under that Skill changes, when the library's runtime changes, and once a month, so a third-party release that breaks a Skill is found. It is not a required check for `main`.
+- The monthly run opens nothing by itself; a failure is reported in the workflow run, and the Skill is fixed or moved to Experimental.
+
+## Contributing a Skill
+
+- Copy `skills/_template/SKILL.md`, fill in every section, set `tier: experimental`.
+- Run the Skill's verification commands in a fresh project with the versions you list, and paste their output in the PR description.
+- The PR touches only `skills/<name>/`; a PR that changes the library and adds a Skill is split. Community and Experimental Skills live in this repository, in the same `skills/` folder, so they ship with the package and `ts-dom skills` lists them with their tier.
+- Review checklist: frontmatter complete; every step reproducible; limitations listed; verification commands and their output present; no restating of `docs/`; nothing that would add a dependency to the core.
+
+## Skills
+
+| Skill | Tier | Status | Covers |
+|---|---|---|---|
+| `nativele-core` | Official | available | building with Nativele itself: the `ts-dom check` loop, components, lists, data flow |
+| `nativele-react` | Official | available | Nativele components in React 19: props, events, children and slots, lifecycle, TSX types |
+| `nativele-integration` | Official | planned | what every framework integration shares: properties and attributes, events, slots, lifecycle, types |
+| `nativele-vite` | Official | planned | the Vite plugin, `root`, hot updates |
+| `nativele-vue` | Official | planned | Nativele components in Vue |
+| `nativele-state-management` | Official | planned | `createStore`, and Zustand or Redux through `bind` |
+| `nativele-testing` | Official | planned | Vitest and Playwright |
+| Svelte, Angular, Tailwind CSS, TanStack Query, Zod | Experimental or Community | open for contributions | |