@nativele/ts-dom 0.4.6 → 0.5.0

package/dist/cli.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { _ as watchAll, a as analyze, c as generateAll, d as isSelected, f as listHtml, g as staleGenerated, i as CodegenError, m as renderTags, n as checkA11y, o as checkGenerated, p as listTs, r as CODEGEN_RULES, t as A11Y_RULES } from "./a11y-wWL9rie7.mjs";
-import { c as lintUsage, n as UNUSED_MARKUP_RULES, o as formatIssue, s as lintDataFlow, t as DATA_FLOW_RULES } from "./lint-CP_i4VPA.mjs";
+import { c as lintUsage, n as UNUSED_MARKUP_RULES, o as formatIssue, s as lintDataFlow, t as DATA_FLOW_RULES } from "./lint-5vo_ifIc.mjs";
 import { createRequire } from "node:module";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { cpSync, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 // src/lib/tsconfig.ts
 /** tsconfig is JSONC: drop comments and trailing commas before parsing. */
 function parseJsonc(text) {
@@ -333,6 +334,94 @@ function runCheck(options) {
 		return !seen.has(k) && seen.add(k) !== void 0;
 	}).sort((x, y) => x.file.localeCompare(y.file) || x.line - y.line || x.col - y.col);
 }
+// src/lib/skills.ts
+const STALE_DAYS = 183;
+/** The skills folder shipped with this package (next to its package.json). */
+function skillsRoot() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	while (!existsSync(join(dir, "package.json")) || !existsSync(join(dir, "skills"))) {
+		const up = dirname(dir);
+		if (up === dir) return join(dirname(fileURLToPath(import.meta.url)), "skills");
+		dir = up;
+	}
+	return join(dir, "skills");
+}
+const unquote = (v) => v.trim().replace(/^(["'])(.*)\1$/, "$2");
+/** Read the frontmatter fields Nativele uses; returns null when the file has none. */
+function parseSkill(text, dir) {
+	const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+	if (!m) return null;
+	const top = {};
+	const meta = {};
+	for (const line of m[1].split(/\r?\n/)) {
+		const kv = /^(\s*)([\w-]+):\s?(.*)$/.exec(line);
+		if (!kv) continue;
+		const value = unquote(kv[3].replace(/\s+#.*$/, ""));
+		(kv[1] ? meta : top)[kv[2]] = value;
+	}
+	if (!top.name) return null;
+	const tier = meta.tier === "official" || meta.tier === "community" ? meta.tier : "experimental";
+	return {
+		name: top.name,
+		description: top.description ?? "",
+		tier,
+		nativele: meta.nativele ?? "",
+		verified: meta.verified ?? "",
+		tools: meta.tools ?? "",
+		author: meta.author ?? "",
+		detects: (meta.detects ?? "").split(/[\s,]+/).filter(Boolean),
+		dir
+	};
+}
+function listSkills(root = skillsRoot()) {
+	if (!existsSync(root)) return [];
+	return readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith("_") && existsSync(join(root, e.name, "SKILL.md"))).map((e) => parseSkill(readFileSync(join(root, e.name, "SKILL.md"), "utf8"), join(root, e.name))).filter((s) => s !== null).sort((a, b) => a.name.localeCompare(b.name));
+}
+const parts = (v) => v.split(/[.-]/).slice(0, 3).map((n) => Number.parseInt(n, 10) || 0);
+const compare = (a, b) => {
+	const x = parts(a);
+	const y = parts(b);
+	for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i];
+	return 0;
+};
+/** Whether `version` satisfies a range of space-separated comparators such as ">=0.5.0 <0.6.0". */
+function inRange(version, range) {
+	return range.split(/\s+/).filter(Boolean).every((c) => {
+		const m = /^(>=|<=|>|<|=)?v?(\d[\w.-]*)$/.exec(c);
+		if (!m) return false;
+		const d = compare(version, m[2]);
+		return m[1] === ">=" ? d >= 0 : m[1] === "<=" ? d <= 0 : m[1] === ">" ? d > 0 : m[1] === "<" ? d < 0 : d === 0;
+	});
+}
+/** Why a Skill should not be trusted as verified for this version, or null when it is current. */
+function staleReason(skill, version, today = /* @__PURE__ */ new Date()) {
+	if (!skill.nativele || !inRange(version, skill.nativele)) return `verified for Nativele ${skill.nativele || "(no range)"}, installed ${version}`;
+	const verified = Date.parse(skill.verified);
+	if (Number.isNaN(verified)) return "no verification date";
+	if ((today.getTime() - verified) / 864e5 > STALE_DAYS) return `last verified ${skill.verified}, more than six months ago`;
+	return null;
+}
+/** The folder a project keeps its skills in: .claude/skills when the project has .claude, otherwise .agents/skills. */
+function skillsTarget(cwd, to) {
+	if (to) return resolve(cwd, to);
+	return existsSync(join(cwd, ".claude")) ? join(cwd, ".claude", "skills") : join(cwd, ".agents", "skills");
+}
+/** Every place a project may already hold a copy of a Skill. */
+function installedCopies(cwd, name) {
+	return [join(cwd, ".claude", "skills", name), join(cwd, ".agents", "skills", name)].filter((d) => existsSync(join(d, "SKILL.md")));
+}
+/** Copy a Skill (its files, not its example project) into `target/<name>`; returns the folder written. */
+function addSkill(skill, target) {
+	const dest = join(target, skill.name);
+	cpSync(skill.dir, dest, {
+		recursive: true,
+		filter: (src) => !src.startsWith(join(skill.dir, "example"))
+	});
+	return dest;
+}
+function libraryVersion(root = skillsRoot()) {
+	return JSON.parse(readFileSync(join(dirname(root), "package.json"), "utf8")).version ?? "0.0.0";
+}
 // src/lib/doctor.ts
 const DOCTOR_RULES = {
 	"dir-not-found": "a folder given on the command line does not exist, so nothing in it was checked",
@@ -346,7 +435,9 @@ const DOCTOR_RULES = {
 	"stale-generated": "a generated file is missing, outdated or orphaned",
 	"vite-plugin-missing": "the Vite config does not use the ts-dom plugin, so templates are not regenerated while the dev server runs",
 	"oxlint-plugin-missing": "the lint config does not load the ts-dom oxlint plugin, so the template rules do not run in the editor",
-	"formatter-whitespace": "a formatter is set up while templates keep their whitespace, so reformatting can change the rendered spacing"
+	"formatter-whitespace": "a formatter is set up while templates keep their whitespace, so reformatting can change the rendered spacing",
+	"skill-available": "the project uses a tool that a Nativele Skill covers, and the project has no copy of that Skill",
+	"skill-outdated": "the project's copy of a Nativele Skill differs from the one shipped with the installed version"
 };
 const readText = (file) => existsSync(file) ? readFileSync(file, "utf8") : null;
 /** Whether an include pattern (absolute, forward slashes) makes tsc read the files directly in `dir`. */
@@ -447,6 +538,13 @@ function runDoctor(options) {
 	].some((n) => existsSync(join(cwd, n))) || "prettier" in deps || scripts.some((c) => /(^|[\s;&|])prettier(\s|$)/.test(c)));
 	const collapsed = scripts.some((c) => c.includes("--whitespace=collapse")) || vite !== null && /whitespace\s*:\s*["']collapse["']/.test(vite) || dirs.some((d) => listHtml(d).some((f) => (readText(`${f}.ts`) ?? "").split("\n", 3).includes("// whitespace: collapse")));
 	if (formatter && !collapsed && dirs.some(hasTemplates)) add("formatter-whitespace", "warning", "A formatter (oxfmt or Prettier) is set up, and templates keep their whitespace as written, so reformatting a template can change the spacing on the page. Fix: generate with whitespace \"collapse\" (ts-dom gen --whitespace=collapse, or tsDom({ whitespace: \"collapse\" })).");
+	for (const skill of listSkills(options.skillsDir ?? skillsRoot())) {
+		const copies = installedCopies(cwd, skill.name);
+		const shipped = readFileSync(join(skill.dir, "SKILL.md"), "utf8");
+		for (const copy of copies) if (readFileSync(join(copy, "SKILL.md"), "utf8") !== shipped) add("skill-outdated", "info", `${rel(copy)} differs from the ${skill.name} Skill shipped with the installed Nativele. Fix: run ts-dom skills add ${skill.name} to replace it with the shipped version.`, { file: rel(join(copy, "SKILL.md")) });
+		const found = skill.detects.filter((d) => d in deps);
+		if (!copies.length && found.length) add("skill-available", "info", `${found.join(", ")} ${found.length > 1 ? "are dependencies" : "is a dependency"}, and the ${skill.name} Skill covers it: ${skill.description} Fix: run ts-dom skills add ${skill.name}, or read it with ts-dom skills ${skill.name}.`, { file: "package.json" });
+	}
 	return issues;
 }
 function formatDoctorIssue(i) {
@@ -739,6 +837,17 @@ onChange(e) { this.set({ value: e.detail.value }); }`
 inc() { this.count = this.count + 1; }`,
 		good: `// counter.ts
 inc() { this.emit("count-change", { value: this.props.count + 1 }); }`
+	},
+	"unguarded-input-value": {
+		why: "render() runs on every change, including the change the user is typing. Assigning a form control's value, even to the same text, moves the caret to the end, so the write must be skipped when nothing differs.",
+		bad: `// form.ts
+override render(view: { name: string }) {
+  this.refs.name.value = view.name;
+}`,
+		good: `// form.ts
+override render(view: { name: string }) {
+  if (this.refs.name.value !== view.name) this.refs.name.value = view.name;
+}`
 	},
 	"custom-event-on-native": {
 		why: "A child's custom event does not bubble, so a handler on a native element would never receive it. Events are handled on the tag of the component that emits them.",
@@ -1040,6 +1149,17 @@ export default defineConfig({ plugins: [tsDom()] });`
 npx ts-dom gen`,
 		good: `npx ts-dom gen --whitespace=collapse
 // or in vite.config.ts: tsDom({ whitespace: "collapse" })`
+	},
+	"skill-available": {
+		why: "A Nativele Skill gives an agent the verified steps, limitations and checks for a tool the project already uses. This is a suggestion and never changes the exit code.",
+		bad: `// package.json lists "react", and the project has no copy of the nativele-react Skill`,
+		good: `npx ts-dom skills add nativele-react   # copies it into .claude/skills/ or .agents/skills/
+npx ts-dom skills nativele-react       # or just read it`
+	},
+	"skill-outdated": {
+		why: "A copied Skill does not update with the package. After an upgrade the copy may describe an older version of Nativele or of the tool it covers.",
+		bad: `// .claude/skills/nativele-core/SKILL.md was copied from an older @nativele/ts-dom`,
+		good: `npx ts-dom skills add nativele-core   # replaces the copy with the one shipped with the installed version`
 	}
 };
 // src/cli.ts
@@ -1059,8 +1179,9 @@ Commands
         --strict          exit with code 1 on warnings too (errors always do)
         --json            print the issues as JSON instead of text (also for gen --check)
   check [dirs...]   One pass for agents and CI: template diagnostics, generated files, tsc errors mapped back
-                    to the templates, and the lint rules (default dir: src)
-        --no-write        do not regenerate; report stale generated files instead
+                    to the templates, and the lint rules (default dir: src). It rewrites the generated files first.
+        --no-write        write nothing: report stale generated files instead (for a CI job that must not
+                          change the working tree; gen --check only checks the generated files)
         --project=<path>  tsconfig for tsc (default: tsc's own lookup)
         --a11y            also check ARIA / accessibility (warnings)
         --strict          exit with code 1 on warnings too (errors always do)
@@ -1068,6 +1189,13 @@ Commands
   doctor [dirs...]  Check the project set-up: tsconfig, template imports, generated files, the runtime package,
                     and the Vite, oxlint and formatter configuration (default dir: src)
         --json            print the issues as JSON instead of text
+  skills            List the Nativele Skills shipped with this version: task procedures for coding agents
+                    (set-up, a complete example, known limitations, verification), with the versions verified
+        <name>            print one Skill
+        add <name...>     copy Skills into the project: .claude/skills/ when the project has .claude,
+                          otherwise .agents/skills/
+        --to=<dir>        copy into this folder instead
+        --json            print the list as JSON
   rules             List every rule id with its description
         --explain=<id>    why the rule exists, a wrong example and the fix (the id as printed in [brackets])
         --json            print every rule as JSON: { id, group, description, why, bad, good }
@@ -1138,6 +1266,60 @@ function printRules() {
 	}
 	console.log("\nts-dom rules --explain=<id> shows why a rule exists, with a wrong and a right example.");
 }
+function skillsCommand() {
+	const skills = listSkills();
+	const version = libraryVersion();
+	const names = args.filter((a) => !a.startsWith("--"));
+	const find = (name) => {
+		const skill = skills.find((s) => s.name === name);
+		if (!skill) {
+			console.error(`Unknown Skill "${name}". Fix: run ts-dom skills to see the Skills shipped with this version.`);
+			process.exitCode = 1;
+		}
+		return skill;
+	};
+	if (names[0] === "add") {
+		if (names.length < 2) {
+			console.error("Name the Skills to add. Fix: ts-dom skills add <name...> (ts-dom skills lists them).");
+			process.exitCode = 1;
+			return;
+		}
+		const to = args.find((a) => a.startsWith("--to="))?.slice(5);
+		const target = skillsTarget(process.cwd(), to);
+		for (const name of names.slice(1)) {
+			const skill = find(name);
+			if (skill) console.log(`added ${relative(process.cwd(), addSkill(skill, target))}`);
+		}
+		return;
+	}
+	if (names.length) {
+		for (const name of names) {
+			const skill = find(name);
+			if (skill) console.log(readFileSync(`${skill.dir}/SKILL.md`, "utf8"));
+		}
+		return;
+	}
+	const rows = skills.map((skill) => {
+		const { dir: _dir, ...s } = skill;
+		return {
+			...s,
+			stale: staleReason(skill, version)
+		};
+	});
+	if (flags.has("--json")) {
+		console.log(JSON.stringify({
+			version,
+			skills: rows
+		}, null, 2));
+		return;
+	}
+	console.log(`Nativele Skills shipped with @nativele/ts-dom ${version}:\n`);
+	for (const s of rows) {
+		console.log(`  ${s.name.padEnd(28)} ${s.tier.padEnd(13)} verified ${s.verified}${s.stale ? ` (stale: ${s.stale})` : ""}`);
+		console.log(`  ${"".padEnd(28)} ${s.description}`);
+	}
+	console.log("\nts-dom skills <name> prints one; ts-dom skills add <name> copies it into the project for your agent.");
+}
 const [cmd, ...args] = process.argv.slice(2);
 const flags = new Set(args.filter((a) => a.startsWith("--")));
 const globs = (name) => args.filter((a) => a.startsWith(`--${name}=`)).map((a) => a.slice(name.length + 3));
@@ -1204,9 +1386,9 @@ try {
 			generate
 		});
 		if (flags.has("--json")) console.log(JSON.stringify({ issues }, null, 2));
-		else for (const i of issues) (i.severity === "error" ? console.error : console.warn)(formatDoctorIssue(i));
+		else for (const i of issues) (i.severity === "error" ? console.error : i.severity === "warning" ? console.warn : console.log)(formatDoctorIssue(i));
 		if (issues.some((i) => i.severity === "error")) process.exitCode = 1;
-		if (!flags.has("--json") && !issues.length) console.log("ts-dom doctor: the set-up looks right");
+		if (!flags.has("--json") && !issues.some((i) => i.severity !== "info")) console.log("ts-dom doctor: the set-up looks right");
 	} else if (cmd === "lint") {
 		const files = dirs.flatMap(listTs);
 		const issues = [...lintUsage(dirs, files), ...lintDataFlow(dirs, files)];
@@ -1220,6 +1402,7 @@ try {
 		if (issues.filter((i) => i.severity === "error").length || flags.has("--strict") && issues.length) process.exitCode = 1;
 		if (!flags.has("--json") && !issues.length) console.log("ts-dom lint: no issues");
 	} else if (cmd === "rules") printRules();
+	else if (cmd === "skills") skillsCommand();
 	else {
 		console.log(HELP);
 		if (cmd && cmd !== "--help" && cmd !== "-h" && cmd !== "help") process.exitCode = 1;

package/dist/index.d.mts

@@ -218,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"];
@@ -266,9 +276,9 @@ interface StatefulInstance<S extends Schema, St extends object, P extends object
   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. */

package/dist/index.mjs

@@ -662,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-CP_i4VPA.mjs → lint-5vo_ifIc.mjs}

@@ -145,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+/));
@@ -308,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.mjs

@@ -1,5 +1,5 @@
 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-CP_i4VPA.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

package/llms.txt

@@ -1,6 +1,6 @@
 # Nativele
 
-> A TypeScript-driven, HTML-first UI library built for type safety and AI agents. 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 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.
 
@@ -43,7 +43,9 @@ Rules the compiler enforces: every `{{ hole }}` / `data-if` name must exist in s
 - 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
@@ -72,17 +74,18 @@ define("my-counter", MyCounter);
 - 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")`). 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.
+- 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
+- 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.
+- 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
@@ -95,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.6",
-  "description": "A TypeScript-driven, HTML-first UI library built for type safety and AI agents: HTML describes the structure, TypeScript owns behavior and state, the native DOM renders it. No virtual DOM, no template expressions, 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"
   ],

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 | |

package/skills/_template/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: nativele-<tool>
+description: "What the Skill lets an agent do, and when to use it (the dependencies or files that call for it)."
+metadata:
+  tier: experimental
+  nativele: ">=0.5.0 <0.6.0"
+  verified: "YYYY-MM-DD"
+  tools: "<tool>@<exact version> <other tool>@<exact version>"
+  author: "<your name or GitHub handle>"
+  detects: "<package.json dependency names, space-separated>"
+---
+
+# Nativele + <tool>
+
+## When to use
+
+- The situation, and the signals (dependencies, files) that call for this Skill.
+- When not to use it.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | x.y.z |
+| <tool> | x.y.z |
+
+Verified on YYYY-MM-DD. With a different major version of <tool>, treat every step as unverified.
+
+## Set-up
+
+1. Numbered steps with the exact commands and file contents.
+
+## Example
+
+The complete, minimal working example: every file it needs.
+
+## Known limitations
+
+1. What does not work or needs care, and what to do instead.
+
+## Verify
+
+```sh
+npx ts-dom check     # expect: ts-dom check: no issues
+npx tsc --noEmit     # expect: no errors
+```
+
+What to check in the browser or with a test.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+
+## See also
+
+- Links to the guides in https://github.com/Pixmi/nativele/tree/main/docs for the facts used.