@nativele/ts-dom 0.4.6 → 0.5.1

package/dist/{a11y-wWL9rie7.mjs → a11y-CV3nBgBn.mjs}

@@ -482,7 +482,7 @@ function renderTags(dir) {
 	const entries = [...seen.values()].map((d) => `    ${JSON.stringify(d.tag)}: ${alias(d)};`);
 	return {
 		out,
-		next: `${TAGS_HEADER}\n${imports.join("\n")}\n\ndeclare global {\n  interface HTMLElementTagNameMap {\n${entries.join("\n")}\n  }\n}\n\nexport {};\n`
+		next: `${TAGS_HEADER}\n${imports.join("\n")}\n\ndeclare global {\n  interface HTMLElementTagNameMap {\n${entries.join("\n")}\n  }\n}\n`
 	};
 }
 /**

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 { _ 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-CV3nBgBn.mjs";
+import { c as lintUsage, n as UNUSED_MARKUP_RULES, o as formatIssue, s as lintDataFlow, t as DATA_FLOW_RULES } from "./lint-DfUAh7t3.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) {
@@ -45,7 +46,7 @@ function readTsConfig(file, depth = 0) {
 		};
 	}
 	const own = json.include;
-	const include = own ? own.map((p) => resolve(dirname(file), p).split("\\").join("/")) : merged.include;
+	const include = own ? own.map((p) => resolve(dirname(file), p).split("\\").join("/")) : merged.include ?? (Array.isArray(json.files) ? [] : void 0);
 	return {
 		compilerOptions: {
 			...merged.compilerOptions,
@@ -212,13 +213,25 @@ function mapTscErrors(errors, cwd) {
 	return out.filter((i) => i.rule !== "tsc" || !followsBroken(i.message));
 }
 function findTsc(cwd) {
+	const req = createRequire(join(cwd, "package.json"));
+	let deps = {};
 	try {
-		const pkgPath = createRequire(join(cwd, "package.json")).resolve("typescript/package.json");
-		const bin = JSON.parse(readFileSync(pkgPath, "utf8")).bin?.tsc;
-		return bin ? resolve(dirname(pkgPath), bin) : null;
-	} catch {
-		return null;
-	}
+		const json = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+		deps = {
+			...json.dependencies,
+			...json.devDependencies
+		};
+	} catch {}
+	const candidates = "vue-tsc" in deps ? [["vue-tsc", "vue-tsc"], ["typescript", "tsc"]] : [["typescript", "tsc"]];
+	for (const [pkg, name] of candidates) try {
+		const pkgPath = req.resolve(`${pkg}/package.json`);
+		const bin = JSON.parse(readFileSync(pkgPath, "utf8")).bin?.[name];
+		if (bin) return {
+			name,
+			bin: resolve(dirname(pkgPath), bin)
+		};
+	} catch {}
+	return null;
 }
 /**
 * Everything an agent needs in one pass: template diagnostics, generated files, TypeScript errors mapped back to the templates, and the lint rules.
@@ -287,7 +300,7 @@ function runCheck(options) {
 		const parsed = [];
 		for (const extra of runs) {
 			const run = spawnSync(process.execPath, [
-				tsc,
+				tsc.bin,
 				"--noEmit",
 				"--pretty",
 				"false",
@@ -308,7 +321,7 @@ function runCheck(options) {
 					col: 1,
 					rule: "tsc-failed",
 					severity: "error",
-					message: `tsc did not check the types: ${detail} Fix: make \`npx tsc --noEmit\` run in this folder (a tsconfig.json, or --project=<path>).`
+					message: `${tsc.name} did not check the types: ${detail} Fix: make \`npx ${tsc.name} --noEmit\` run in this folder (a tsconfig.json, or --project=<path>).`
 				});
 			}
 		}
@@ -333,6 +346,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 +447,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`. */
@@ -381,24 +484,34 @@ function runDoctor(options) {
 	if (!configs.length) add("no-tsconfig", "error", "There is no tsconfig.json. Fix: add one with \"strict\": true, \"lib\": [\"ES2022\", \"DOM\"] and \"moduleResolution\": \"bundler\" (or \"NodeNext\").");
 	const includes = [];
 	let everyConfigIncludes = true;
-	for (const configPath of configs) {
-		const config = readTsConfig(configPath);
+	const scanned = dirs.map((dir) => ({
+		dir,
+		folders: templateFolders(dir)
+	}));
+	const targets = scanned.flatMap(({ dir, folders }) => folders.length ? folders : [dir]);
+	const read = configs.map((path) => ({
+		path,
+		config: readTsConfig(path)
+	}));
+	const covering = read.filter(({ config: { include } }) => !include || targets.some((t) => include.some((p) => covers(p, t))));
+	for (const { path: configPath, config } of read) {
 		const o = config.compilerOptions;
 		const file = rel(configPath);
 		paths = {
 			...paths,
 			...o.paths
 		};
+		if (config.include) includes.push(...config.include);
+		else everyConfigIncludes = false;
+		if (covering.length && !covering.some((r) => r.path === configPath)) continue;
 		if (o.strict !== true) add("tsconfig-not-strict", "warning", "compilerOptions.strict is not true, so tsc lets wrong names and null values through. Fix: set \"strict\": true.", { file });
 		const lib = o.lib;
 		if (lib && !lib.some((l) => l.toLowerCase() === "dom")) add("tsconfig-no-dom-lib", "error", "compilerOptions.lib leaves out DOM, so element types such as HTMLButtonElement are missing. Fix: add \"DOM\" to lib.", { file });
 		if (String(o.moduleResolution ?? "").toLowerCase() === "classic") add("tsconfig-classic-resolution", "error", "moduleResolution \"classic\" cannot resolve ./x.html.js to the generated x.html.ts. Fix: use \"bundler\" or \"NodeNext\".", { file });
-		if (config.include) includes.push(...config.include);
-		else everyConfigIncludes = false;
 	}
 	if (configs.length && everyConfigIncludes) {
 		const missed = /* @__PURE__ */ new Set();
-		for (const d of dirs) for (const folder of templateFolders(d)) if (!includes.some((p) => covers(p, folder))) missed.add(rel(folder));
+		for (const folder of scanned.flatMap((s) => s.folders)) if (!includes.some((p) => covers(p, folder))) missed.add(rel(folder));
 		for (const folder of missed) add("tsconfig-misses-templates", "error", `No tsconfig include covers ${folder}, which has templates, so their generated types are never checked. Fix: add "${folder === "." ? "**/*" : `${folder}/**/*`}" to include.`, { file: rel(configs[0]) });
 	}
 	let resolvable = Object.keys(paths).includes(runtime);
@@ -447,6 +560,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 +859,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 +1171,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 +1201,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 +1211,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 +1288,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 +1408,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 +1424,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-DfUAh7t3.mjs}

@@ -1,4 +1,4 @@
-import { a as analyze, f as listHtml, h as scanDefines } from "./a11y-wWL9rie7.mjs";
+import { a as analyze, f as listHtml, h as scanDefines } from "./a11y-CV3nBgBn.mjs";
 import { readFileSync } from "node:fs";
 import { basename, dirname, relative } from "node:path";
 // src/lib/lint.ts
@@ -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 { n as checkA11y, t as A11Y_RULES } from "./a11y-CV3nBgBn.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-DfUAh7t3.mjs";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 // src/lib/oxlint-plugin.ts

package/dist/vite-plugin.mjs

@@ -1,4 +1,4 @@
-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 { 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-CV3nBgBn.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 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.
+Workflow: write `x.html` + `x.ts`, run `npx ts-dom check` (regenerates `x.html.ts`, runs tsc, or vue-tsc when the project has it, 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.
@@ -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`, `nativele-vue`, `nativele-svelte` and `nativele-angular` for those frameworks, `nativele-vite` for Vite, `nativele-integration` for other frameworks, ...), 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.1",
+  "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"
   ],