@nativele/ts-dom 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -10,6 +10,43 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version
 - Adding a lint rule is a minor change; lint rules are warnings or opt-in and do not count as breaking.
 - Before every release run `npm run verify:pack` (`publint` and `attw`), `tsc`, the unit tests, the browser tests, `npm run smoke` and `npm run smoke:no-bundler`; all of them run in `.github/workflows/ci.yml`.
 
+## 0.5.4
+
+The guides, the Skills and the tools agree with each other: wrong statements in the guides are fixed, facts the Skills repeated now live in the guides, and the tools report the traps the Skill trials hit instead of staying silent.
+
+### New checks
+
+- `ts-dom doctor` reports `typecheck-before-gen` (warning): a package.json script, with its `pre` script and the scripts it runs through `npm run` (or pnpm, yarn, bun), that runs `tsc`, `vue-tsc`, `svelte-check` or `ng build`/`serve`/`test` before any `ts-dom gen` or `ts-dom check` while `.gitignore` leaves out `*.html.ts`; on a clean checkout it fails with TS2307. A `tsc -p` whose config covers none of the scanned folders is skipped.
+- `ts-dom doctor` reports `framework-template` (error): an `.html` in a scanned folder that a TypeScript file names as an Angular `templateUrl`. The `invalid-hole` and `no-importer` hints now also say that the folder may not be meant to be scanned.
+- `formatter-whitespace` also reports generated files written with `preserve` while a package.json script or the Vite config asks for `--whitespace=collapse`, with the command to regenerate them.
+- `vite-plugin-missing` also reports a `vitest.config.*` that replaces the Vite config for Vitest without the `tsDom()` plugin and without importing `./vite.config`.
+
+### Fixes
+
+- The Vite plugin warns (`dir-not-found`) when a `tsDom({ dirs })` entry does not exist under Vite's `root`, instead of skipping it silently.
+- A generated `ts-dom-tags.ts` in a subfolder that is not itself scanned (left over after components moved) is an orphan: `gen` deletes it, and `gen --check`, `check --no-write` and `doctor` report it as `stale-generated`.
+- A `tsc` error located in a generated `x.html.ts` or `ts-dom-tags.ts` now says to run `ts-dom gen` or delete the leftover file, not to change the TypeScript there.
+- `ts-dom check` leaves out `tsc` errors inside the body of a class it already reported for a contract error (for example an implicit `any` on a `bind` callback's parameter next to a `{{ hole }}` that names nothing).
+- `ts-dom --help` lists `--include`, `--exclude` and `--whitespace` under `check` and `doctor`, which accept them.
+
+### Documentation
+
+- `docs/components.md` gains:
+  - Light DOM slots and children managed by a framework;
+  - when a Light or Shadow component builds its content;
+  - the `props` and `"~emits"` members that framework declarations use;
+  - `EmitEvent` with an undeclared name;
+  - `ReadableStore`.
+- Five framework Skills link to the slot section instead of repeating it.
+- Corrected:
+  - the import map in `docs/design.md`;
+  - the generated files being "already in `.gitignore`" (a project adds them itself);
+  - duplicate and misplaced reordering notes;
+  - `llms.txt` lists every guide.
+- The Skills agree on one build-script rule: a project whose type check is plain `tsc` runs `ts-dom check` before the bundler, and a framework type checker gets `ts-dom gen` in front. The README Skill tables show the right tiers.
+- `test/skills.test.ts` checks the README Skill tables against each Skill's tier, and every link and anchor in the READMEs, `llms.txt`, the guides and the Skills.
+- `docs/tooling.md`: the new checks; the bare specifier to map is `@nativele/ts-dom`; the Vite plugin generates when the build, the dev server or Vitest starts, never type-checks, prints rejected templates only in the terminal, and sends a full reload to every client; a run without `--whitespace` keeps each file's recorded mode; `check` runs `tsc` once per referenced project of a solution-style tsconfig.
+
 ## 0.5.3
 
 How to lay out an app with several pages: a new architecture guide, an Official Skill that applies it, and a medium example app checked in CI. Building the example found a codegen bug with several scanned folders, fixed here.

package/README.md

@@ -63,11 +63,11 @@ npx ts-dom skills add nativele-core    # copy it into .claude/skills/ (when the
 | `nativele-core` | building components: the `ts-dom check` loop, templates, state, lists, data flow |
 | `nativele-react` | Nativele components in React 19: props, events, children and slots, lifecycle, TSX types |
 | `nativele-vue` | Nativele components in Vue 3: props, events, `v-model`, slots, `<KeepAlive>`, template types |
-| `nativele-svelte` | Nativele components in Svelte 5: props, events, slots, template types |
+| `nativele-svelte` | Nativele components in Svelte 5: props, events, slots, template types (Experimental) |
 | `nativele-angular` | Nativele components in Angular: bindings, change detection, the build, content projection (Experimental) |
 | `nativele-architecture` | app layout: feature folders, shared components and stores, pages mounted by a router, lazy pages, the test split |
 | `nativele-vite` | Nativele in a Vite app: the plugin and `root`, multi-page builds, hot updates |
-| `nativele-integration` | Nativele components in a framework without its own Skill (Preact, Solid, ...): properties, events, slots, lifecycle, template types (Experimental) |
+| `nativele-integration` | Nativele components in a framework without its own Skill (Preact, Solid, ...): properties, events, slots, lifecycle, template types |
 | `nativele-state-management` | where state lives; `createStore`, and Zustand, Redux Toolkit or nanostores through `bind` |
 | `nativele-testing` | component tests with Vitest, real-browser tests |
 | `nativele-tanstack-query` | data fetching with `@tanstack/query-core` (Experimental) |

package/README.zh-TW.md

@@ -63,11 +63,11 @@ npx ts-dom skills add nativele-core    # 複製到 .claude/skills/（專案有 .
 | `nativele-core` | 開發元件：`ts-dom check` 循環、範本、state、清單、資料流 |
 | `nativele-react` | 在 React 19 中使用 Nativele 元件：props、事件、子元素與 slot、生命週期、TSX 型別 |
 | `nativele-vue` | 在 Vue 3 中使用 Nativele 元件：props、事件、`v-model`、slot、`<KeepAlive>`、範本型別 |
-| `nativele-svelte` | 在 Svelte 5 中使用 Nativele 元件：props、事件、slot、範本型別 |
+| `nativele-svelte` | 在 Svelte 5 中使用 Nativele 元件：props、事件、slot、範本型別（Experimental） |
 | `nativele-angular` | 在 Angular 中使用 Nativele 元件：綁定、變更偵測、建置流程、內容投影（Experimental） |
 | `nativele-architecture` | 應用的結構：功能資料夾、共用元件與 store、由 router 掛載的頁面、延遲載入、測試分層 |
 | `nativele-vite` | 在 Vite 應用中使用 Nativele：外掛與 `root`、多頁建置、熱更新 |
-| `nativele-integration` | 在沒有專屬 Skill 的框架（Preact、Solid 等）中使用 Nativele 元件：property、事件、slot、生命週期、範本型別（Experimental） |
+| `nativele-integration` | 在沒有專屬 Skill 的框架（Preact、Solid 等）中使用 Nativele 元件：property、事件、slot、生命週期、範本型別 |
 | `nativele-state-management` | 狀態放在哪裡；`createStore`，以及透過 `bind` 接上 Zustand、Redux Toolkit、nanostores |
 | `nativele-testing` | 用 Vitest 做元件測試、真實瀏覽器測試 |
 | `nativele-tanstack-query` | 用 `@tanstack/query-core` 取資料（Experimental） |

package/dist/{a11y-Bw-8ZIAK.mjs → a11y-CiEJj_e6.mjs}

@@ -104,7 +104,7 @@ function analyze(html) {
 				mark(listName ? `text:${listName}/${name}` : `text:${name}`, at);
 			} else {
 				const inner = (m[1] ?? "").trim();
-				report("invalid-hole", "error", `{{ ${inner} }} is not a valid hole: a hole must be a single identifier, paths and expressions are not supported. Fix: compute the value in TypeScript (state, derive or this.text) and use a named hole such as {{ name }}.`, at);
+				report("invalid-hole", "error", `{{ ${inner} }} is not a valid hole: a hole must be a single identifier, paths and expressions are not supported. Fix: compute the value in TypeScript (state, derive or this.text) and use a named hole such as {{ name }}. If the file is another framework's template, this folder is not meant to be scanned: scan only the folder with the Nativele templates, or leave the file out with --exclude.`, at);
 			}
 		}
 	}
@@ -517,8 +517,9 @@ function renderTags(dir) {
 /**
 * Everything `generateAll` would write for a directory, in memory: generated path to content, or null for a file that should not exist.
 * Templates with error diagnostics are left out and their messages returned in `errors`.
+* `scanned` are all the directories of the run: a ts-dom-tags.ts in a subfolder is an orphan unless that subfolder is one of them.
 */
-function planGenerated(dir, options = {}, defs = scanDefines(dir)) {
+function planGenerated(dir, options = {}, defs = scanDefines(dir), scanned = [dir]) {
 	const files = /* @__PURE__ */ new Map();
 	const errors = [];
 	for (const f of listHtml(dir)) {
@@ -538,26 +539,26 @@ function planGenerated(dir, options = {}, defs = scanDefines(dir)) {
 		if (e instanceof CodegenError) errors.push(e.message);
 		else throw e;
 	}
-	for (const f of listGenerated(dir)) if (!files.has(f) && !existsSync(f.slice(0, -3))) files.set(f, null);
+	for (const f of listGenerated(dir, scanned)) if (!files.has(f) && !existsSync(f.slice(0, -3))) files.set(f, null);
 	return {
 		files,
 		errors
 	};
 }
 /** Generated files under `dir` that differ from what `ts-dom gen` would write now. */
-function staleGenerated(dir, options = {}, defs) {
-	return checkGenerated(dir, options, defs).stale;
+function staleGenerated(dir, options = {}, defs, scanned) {
+	return checkGenerated(dir, options, defs, scanned).stale;
 }
 /** `staleGenerated`, plus the errors that would make `ts-dom gen` fail (template diagnostics, a tag defined twice). */
-function checkGenerated(dir, options = {}, defs) {
-	const plan = planGenerated(dir, options, defs);
+function checkGenerated(dir, options = {}, defs, scanned) {
+	const plan = planGenerated(dir, options, defs, scanned);
 	const out = [];
 	for (const [file, next] of plan.files) {
 		const prev = existsSync(file) ? readFileSync(file, "utf8") : null;
 		if (next === null) {
 			if (prev !== null && prev.startsWith(TAGS_HEADER)) out.push({
 				file,
-				reason: file.endsWith(".html.ts") ? "orphan" : "outdated"
+				reason: file === join(dir, TAGS_FILE) ? "outdated" : "orphan"
 			});
 		} else if (prev === null) out.push({
 			file,
@@ -573,13 +574,14 @@ function checkGenerated(dir, options = {}, defs) {
 		errors: plan.errors
 	};
 }
-function listGenerated(dir) {
+function listGenerated(dir, scanned, top = true) {
 	const out = [];
+	const ownTags = top || scanned.some((d) => resolve(d) === resolve(dir));
 	for (const name of readdirSync(dir)) {
 		if (name === "node_modules") continue;
 		const full = join(dir, name);
-		if (statSync(full).isDirectory()) out.push(...listGenerated(full));
-		else if (name.endsWith(".html.ts") && readFileSync(full, "utf8").startsWith(TAGS_HEADER)) out.push(full);
+		if (statSync(full).isDirectory()) out.push(...listGenerated(full, scanned, false));
+		else if ((name.endsWith(".html.ts") || name === TAGS_FILE && !ownTags) && readFileSync(full, "utf8").startsWith(TAGS_HEADER)) out.push(full);
 	}
 	return out;
 }
@@ -587,7 +589,7 @@ function listGenerated(dir) {
 * Generate every `x.html.ts` (and the tag map) under a directory; collects all errors and throws them together.
 * `defs` are the define() calls templates import child components from (default: those under `dir`).
 */
-function generateAll(dir, options = {}, defs = scanDefines(dir)) {
+function generateAll(dir, options = {}, defs = scanDefines(dir), scanned = [dir]) {
 	const written = [];
 	const errors = [];
 	for (const f of listHtml(dir)) {
@@ -606,7 +608,7 @@ function generateAll(dir, options = {}, defs = scanDefines(dir)) {
 		if (e instanceof CodegenError) errors.push(e.message);
 		else throw e;
 	}
-	for (const f of listGenerated(dir)) if (!existsSync(f.slice(0, -3))) unlinkSync(f);
+	for (const f of listGenerated(dir, scanned)) if (!existsSync(f.slice(0, -3))) unlinkSync(f);
 	if (errors.length) throw new CodegenError(errors.join("\n"));
 	return written;
 }
@@ -616,7 +618,7 @@ function generateDirs(dirs, options = {}) {
 	const written = [];
 	const errors = [];
 	for (const dir of dirs) try {
-		written.push(...generateAll(dir, options, defs));
+		written.push(...generateAll(dir, options, defs, dirs));
 	} catch (e) {
 		if (e instanceof CodegenError) errors.push(e.message);
 		else throw e;

package/dist/cli.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { _ as staleGenerated, a as analyze, c as formatDiagnostics, f as isSelected, g as scanDefines, h as renderTags, i as CodegenError, l as generateDirs, m as listTs, n as checkA11y, o as checkGenerated, p as listHtml, r as CODEGEN_RULES, s as crossDirDuplicates, t as A11Y_RULES, v as watchAll } from "./a11y-Bw-8ZIAK.mjs";
-import { c as lintUsage, n as UNUSED_MARKUP_RULES, o as formatIssue, s as lintDataFlow, t as DATA_FLOW_RULES } from "./lint-qEPgmmMa.mjs";
+import { _ as staleGenerated, a as analyze, c as formatDiagnostics, f as isSelected, g as scanDefines, h as renderTags, i as CodegenError, l as generateDirs, m as listTs, n as checkA11y, o as checkGenerated, p as listHtml, r as CODEGEN_RULES, s as crossDirDuplicates, t as A11Y_RULES, v as watchAll } from "./a11y-CiEJj_e6.mjs";
+import { c as lintUsage, n as UNUSED_MARKUP_RULES, o as formatIssue, s as lintDataFlow, t as DATA_FLOW_RULES } from "./lint-Did4w-NL.mjs";
 import { createRequire } from "node:module";
 import { cpSync, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 // src/lib/tsconfig.ts
@@ -164,13 +164,22 @@ function mapTscErrors(errors, cwd) {
 		}
 	};
 	const brokenClasses = /* @__PURE__ */ new Set();
+	const brokenBodies = [];
 	for (const e of errors) {
 		if (!/missingStateKeys|conflictingKeys|reservedPropNames|nativeEventNames/.test(e.message)) continue;
-		const line = readFileSync(resolve(cwd, e.file), "utf8").split("\n")[e.line - 1] ?? "";
-		const name = /class\s+([A-Za-z_$][\w$]*)\s+extends\s+Component\s*\(/.exec(line)?.[1];
-		if (name) brokenClasses.add(name);
+		const text = readFileSync(resolve(cwd, e.file), "utf8");
+		const lines = text.split("\n");
+		const m = /class\s+([A-Za-z_$][\w$]*)\s+extends\s+Component\s*\(/.exec(lines[e.line - 1] ?? "");
+		if (!m?.[1]) continue;
+		brokenClasses.add(m[1]);
+		const end = classBodyEnd(text, lines.slice(0, e.line - 1).join("\n").length + (e.line > 1 ? 1 : 0) + m.index + m[0].length - 1);
+		if (end !== -1) brokenBodies.push({
+			file: rel(resolve(cwd, e.file)),
+			from: e.line,
+			to: text.slice(0, end).split("\n").length
+		});
 	}
-	const followsBroken = (message) => [...brokenClasses].some((c) => message.includes(`'${c}'`) || message.includes(`'typeof ${c}'`));
+	const followsBroken = (i) => [...brokenClasses].some((c) => i.message.includes(`'${c}'`) || i.message.includes(`'typeof ${c}'`)) || brokenBodies.some((b) => b.file === i.file && i.line > b.from && i.line <= b.to);
 	for (const e of errors) {
 		const file = resolve(cwd, e.file);
 		const where = `${rel(file)}:${e.line}:${e.col}`;
@@ -208,9 +217,31 @@ function mapTscErrors(errors, cwd) {
 			named = true;
 			issue(rule, `${e.message.split("\n")[0]} Fix: ${fix}.`);
 		}
-		if (!named) issue("tsc", `${e.code}: ${e.message} Fix: change the TypeScript at this location so the types agree; ts-dom rules --explain=tsc.`);
+		if (named) continue;
+		if (file.endsWith(".html.ts") || file.endsWith(`${sep}ts-dom-tags.ts`)) issue("tsc", `${e.code}: ${e.message} This file is generated, so an edit to it is overwritten. Fix: run ts-dom gen for the folder that holds it; if it is left over from a template or folder that is no longer scanned, delete it.`);
+		else issue("tsc", `${e.code}: ${e.message} Fix: change the TypeScript at this location so the types agree; ts-dom rules --explain=tsc.`);
 	}
-	return out.filter((i) => i.rule !== "tsc" || !followsBroken(i.message));
+	return out.filter((i) => i.rule !== "tsc" || !followsBroken(i));
+}
+/** The offset of the `}` that closes a class body, given the offset of the `(` of its `extends Component(`; -1 when it cannot be found. Strings and comments are skipped. */
+function classBodyEnd(text, open) {
+	let depth = 0;
+	let inBody = false;
+	for (let i = open; i < text.length; i++) {
+		const c = text[i];
+		if (c === "\"" || c === "'" || c === "`") {
+			for (i++; i < text.length && text[i] !== c; i++) if (text[i] === "\\") i++;
+		} else if (c === "/" && text[i + 1] === "/") i = text.indexOf("\n", i) === -1 ? text.length : text.indexOf("\n", i);
+		else if (c === "/" && text[i + 1] === "*") i = text.indexOf("*/", i) === -1 ? text.length : text.indexOf("*/", i) + 1;
+		else if ("([{".includes(c)) {
+			if (c === "{" && depth === 0) inBody = true;
+			depth++;
+		} else if (")]}".includes(c)) {
+			depth--;
+			if (depth === 0 && inBody) return i;
+		}
+	}
+	return -1;
 }
 function findTsc(cwd) {
 	const req = createRequire(join(cwd, "package.json"));
@@ -278,7 +309,7 @@ function runCheck(options) {
 	});
 	if (options.write === false) {
 		const defs = scanDefines(dirs);
-		for (const dir of dirs) for (const s of staleGenerated(dir, generate, defs)) issues.push({
+		for (const dir of dirs) for (const s of staleGenerated(dir, generate, defs, dirs)) issues.push({
 			file: rel(s.file),
 			line: 1,
 			col: 1,
@@ -451,9 +482,11 @@ const DOCTOR_RULES = {
 	"runtime-not-installed": "the runtime package the generated files import cannot be resolved",
 	"template-import-without-js": "a template is imported as ./x.html instead of ./x.html.js",
 	"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",
+	"framework-template": "a scanned .html is an Angular component's templateUrl, not a Nativele template",
+	"typecheck-before-gen": "a package.json script type-checks before ts-dom gen while *.html.ts is git-ignored, so it fails on a clean checkout",
+	"vite-plugin-missing": "the Vite config, or a vitest.config that replaces it for Vitest, does not use the ts-dom plugin, so templates are not generated by the dev server or the tests",
 	"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; or the scripts or Vite config ask for collapse while the generated files were written with preserve",
 	"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"
 };
@@ -467,6 +500,24 @@ function covers(pattern, dir) {
 	if (pattern.slice(star).startsWith("**")) return d === prefix || d.startsWith(`${prefix}/`);
 	return d === prefix;
 }
+const TYPECHECK = /(?:^|\s)(?:npx\s+)?(tsc|vue-tsc|svelte-check|ng\s+(?:build|serve|test))(?=\s|$)/;
+const TSC_PROJECT = /(?:^|\s)(?:npx\s+)?(?:vue-)?tsc(?:\s.*?)?\s(?:-p|--project)[\s=]+(\S+)/;
+const GENERATES = /(?:^|\s)ts-dom\s+(?:gen|check)(?=\s|$)/;
+const RUN_SCRIPT = /^(?:npm\s+run(?:-script)?|pnpm(?:\s+run)?|yarn(?:\s+run)?|bun\s+run)\s+([\w:.-]+)/;
+/** The commands a script runs in order, with its pre and post scripts and the scripts it runs through npm run (or pnpm, yarn, bun) spelled out. */
+function scriptSteps(scripts, name, depth = 0) {
+	const command = scripts[name];
+	if (depth > 5 || command === void 0) return [];
+	const own = command.split(/&&|;/).flatMap((step) => {
+		const ref = RUN_SCRIPT.exec(step.trim())?.[1];
+		return ref && scripts[ref] !== void 0 ? scriptSteps(scripts, ref, depth + 1) : [step.trim()];
+	});
+	return [
+		...scriptSteps(scripts, `pre${name}`, depth + 1),
+		...own,
+		...scriptSteps(scripts, `post${name}`, depth + 1)
+	];
+}
 const templateFolders = (dir) => [...new Set(listHtml(dir).map((f) => dirname(f)))];
 const hasTemplates = (dir) => listHtml(dir).length > 0;
 /** Check the project set-up an agent or a developer could get wrong; every issue names its rule and ends with a Fix hint. */
@@ -537,7 +588,14 @@ function runDoctor(options) {
 				line: i + 1
 			});
 		});
-		for (const s of staleGenerated(d, generate, defs)) add("stale-generated", "warning", `The generated file is ${s.reason}. Fix: run ts-dom gen (or ts-dom check, which regenerates).`, { file: rel(s.file) });
+		for (const s of staleGenerated(d, generate, defs, dirs)) add("stale-generated", "warning", `The generated file is ${s.reason}. Fix: run ts-dom gen (or ts-dom check, which regenerates).`, { file: rel(s.file) });
+	}
+	const scannedHtml = new Set(dirs.flatMap(listHtml));
+	if (scannedHtml.size) for (const f of listTs(cwd)) for (const m of readFileSync(f, "utf8").matchAll(/templateUrl\s*:\s*["'`]([^"'`]+\.html)["'`]/g)) {
+		const html = resolve(dirname(f), m[1]);
+		if (!scannedHtml.has(html)) continue;
+		scannedHtml.delete(html);
+		add("framework-template", "error", `${rel(html)} is the Angular template of ${rel(f)} (templateUrl), not a Nativele template, so ts-dom gen reports its Angular syntax as errors. Fix: scan only the folder with the Nativele templates (for example ts-dom gen src/nv, and the same folder for check, doctor and tsDom({ dirs })).`, { file: rel(html) });
 	}
 	const viteConfig = [
 		"vite.config.ts",
@@ -547,6 +605,16 @@ function runDoctor(options) {
 	].map((n) => join(cwd, n)).find((f) => existsSync(f));
 	const vite = viteConfig ? readText(viteConfig) : null;
 	if (viteConfig && vite !== null && !/@nativele\/ts-dom\/vite|vite-plugin(\.ts)?["']/.test(vite)) add("vite-plugin-missing", "warning", "The Vite config does not use the ts-dom plugin, so templates are not regenerated while the dev server runs. Fix: import { tsDom } from \"@nativele/ts-dom/vite\" and add tsDom() to plugins.", { file: rel(viteConfig) });
+	const vitestConfig = [
+		"ts",
+		"mts",
+		"cts",
+		"js",
+		"mjs",
+		"cjs"
+	].map((ext) => join(cwd, `vitest.config.${ext}`)).find((f) => existsSync(f));
+	const vitest = vitestConfig ? readText(vitestConfig) : null;
+	if (vitestConfig && vitest !== null && !/@nativele\/ts-dom\/vite|vite-plugin(\.ts)?["']/.test(vitest) && !/["']\.\/vite\.config(\.[cm]?[jt]s)?["']/.test(vitest)) add("vite-plugin-missing", "warning", `${rel(vitestConfig)} replaces the Vite config for Vitest and does not use the ts-dom plugin, so the templates are not generated when the tests start and a clean checkout fails to resolve ./x.html.js. Fix: add tsDom() to its plugins, or merge the Vite config into it: mergeConfig(viteConfig, defineConfig({ test: { ... } })) with viteConfig imported from "./vite.config".`, { file: rel(vitestConfig) });
 	const oxlintrc = [".oxlintrc.json", "oxlintrc.json"].map((n) => join(cwd, n)).find((f) => existsSync(f));
 	const lintConfigs = [oxlintrc ? readText(oxlintrc) : null, vite && /\blint\s*:/.test(vite) ? vite : null].filter((t) => t !== null);
 	if (lintConfigs.length && !lintConfigs.some((t) => /@nativele\/ts-dom\/oxlint|oxlint-plugin(\.ts)?["']/.test(t))) add("oxlint-plugin-missing", "warning", "The lint config does not load the ts-dom oxlint plugin, so unused markup, data flow and accessibility rules do not run in the editor. Fix: add { name: \"ts-dom\", specifier: \"@nativele/ts-dom/oxlint\" } to jsPlugins and enable \"ts-dom/unused-markup\".", { file: rel(oxlintrc ?? viteConfig) });
@@ -557,6 +625,31 @@ function runDoctor(options) {
 		...pkg.devDependencies
 	};
 	const scripts = Object.values(pkg.scripts ?? {});
+	if ((readText(join(cwd, ".gitignore")) ?? "").split("\n").some((l) => !l.trim().startsWith("!") && /\*\.html\.ts\s*$/.test(l)) && dirs.some(hasTemplates)) {
+		const all = pkg.scripts ?? {};
+		const checksTemplates = (step) => {
+			const project = TSC_PROJECT.exec(step)?.[1];
+			if (!project && !/(?:^|\s)(?:npx\s+)?(?:vue-)?tsc(?=\s|$)/.test(step)) return true;
+			const config = resolve(cwd, project ?? "tsconfig.json");
+			const configs = projectConfigs(cwd, existsSync(config) && statSync(config).isDirectory() ? join(config, "tsconfig.json") : config);
+			return !configs.length || configs.some((c) => {
+				const include = readTsConfig(c).include;
+				return !include || targets.some((t) => include.some((p) => covers(p, t)));
+			});
+		};
+		const dirArgs = options.dirs.join(" ");
+		for (const name of Object.keys(all)) {
+			if (/^(pre|post)./.test(name) && all[name.replace(/^(pre|post)/, "")] !== void 0) continue;
+			const step = scriptSteps(all, name).find((s) => GENERATES.test(s) || TYPECHECK.test(s) && checksTemplates(s));
+			if (step === void 0 || GENERATES.test(step)) continue;
+			const tool = TYPECHECK.exec(step)[1]?.replace(/\s+/g, " ");
+			const line = pkgText.split("\n").findIndex((l) => l.includes(`${JSON.stringify(name)}:`)) + 1;
+			add("typecheck-before-gen", "warning", `The script "${name}" runs ${tool} before any ts-dom gen, and .gitignore leaves out *.html.ts, so on a clean checkout ${tool} fails with TS2307 (cannot find module './x.html.js'). Fix: put "ts-dom gen ${dirArgs} && " in front of it, or use "ts-dom check ${dirArgs}" as the type check when the project uses plain tsc.`, {
+				file: "package.json",
+				...line ? { line } : {}
+			});
+		}
+	}
 	const ignoredHtml = /(^|\n)\s*(\*\*\/)?\*\.html\s*($|\n)/.test(readText(join(cwd, ".prettierignore")) ?? "");
 	const formatter = [".oxfmtrc.json", ".oxfmtrc.jsonc"].some((n) => existsSync(join(cwd, n))) || "oxfmt" in deps || scripts.some((c) => /(^|[\s;&|])(oxfmt|vp fmt)(\s|$)/.test(c)) || vite !== null && /\bfmt\s*:/.test(vite) || !ignoredHtml && ([
 		".prettierrc",
@@ -565,7 +658,22 @@ function runDoctor(options) {
 		"prettier.config.js",
 		"prettier.config.mjs"
 	].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")));
+	const collapseScript = Object.entries(pkg.scripts ?? {}).find(([, c]) => c.includes("--whitespace=collapse"))?.[0];
+	const collapseVite = vite !== null && /whitespace\s*:\s*["']collapse["']/.test(vite);
+	const generatedModes = dirs.flatMap(listHtml).flatMap((f) => {
+		const head = (readText(`${f}.ts`) ?? "").split("\n", 3);
+		return head[0]?.startsWith("// Generated by ts-dom.") ? [{
+			file: `${f}.ts`,
+			collapse: head.includes("// whitespace: collapse")
+		}] : [];
+	});
+	const preserved = generatedModes.filter((g) => !g.collapse);
+	if ((collapseScript || collapseVite) && preserved.length) {
+		const asker = collapseScript ? `The script "${collapseScript}"` : "The Vite config";
+		const rerun = collapseScript ? `npm run ${collapseScript}` : `ts-dom gen ${options.dirs.join(" ")} --whitespace=collapse`;
+		add("formatter-whitespace", "warning", `${asker} asks for whitespace "collapse", but ${preserved.length === 1 ? "this generated file was" : `${preserved.length} generated files (this one first) were`} written with "preserve" (by a gen or check run without the flag, for example), and a run without --whitespace keeps the mode a file was last written with, so the page gets the whitespace as written instead of collapsed. Fix: regenerate with the flag once: ${rerun}.`, { file: rel(preserved[0].file) });
+	}
+	const collapsed = collapseScript !== void 0 || collapseVite || generatedModes.some((g) => g.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);
@@ -1030,7 +1138,7 @@ this.refs.list.items = ["a", "b"];`
 		good: `<button data-on-click="open">open</button>`
 	},
 	"stale-generated": {
-		why: "Types come from the generated *.html.ts files. If one is missing, outdated or orphaned, tsc checks against old templates and its errors may not match the HTML. ts-dom doctor reports the same condition as a warning.",
+		why: "Types come from the generated *.html.ts files. If one is missing, outdated or orphaned (its template was deleted, or a ts-dom-tags.ts was left in a subfolder that is no longer scanned and declares its tags a second time), tsc checks against old templates and its errors may not match the HTML. ts-dom doctor reports the same condition as a warning.",
 		bad: `# card.html was edited, card.html.ts was not regenerated
 npx ts-dom check --no-write`,
 		good: `npx ts-dom gen
@@ -1100,9 +1208,11 @@ const n: number = 1;`
 		good: `npx ts-dom check --project=tsconfig.json`
 	},
 	"dir-not-found": {
-		why: "A folder given to ts-dom check or doctor that does not exist would otherwise be skipped silently, and a clean result would only mean that nothing was looked at.",
-		bad: `npx ts-dom check ap   # the templates live in app/`,
-		good: `npx ts-dom check app`
+		why: "A folder given to ts-dom check or doctor, or to tsDom({ dirs }) in the Vite plugin, that does not exist would otherwise be skipped silently, and a clean result would only mean that nothing was looked at. The Vite plugin resolves dirs against Vite's root, not the working directory.",
+		bad: `npx ts-dom check ap   # the templates live in app/
+// vite.config.ts with root: "web": tsDom({ dirs: ["web/src"] }) looks for web/web/src`,
+		good: `npx ts-dom check app
+// vite.config.ts with root: "web": tsDom({ dirs: ["src"] })`
 	},
 	"tsc-not-found": {
 		why: "ts-dom check runs the TypeScript compiler of the project. Without it installed, nothing can be type-checked.",
@@ -1154,13 +1264,35 @@ npx ts-dom check`
 		bad: `import tpl from "./card.html";`,
 		good: `import tpl from "./card.html.js";`
 	},
+	"framework-template": {
+		why: "Every .html in a scanned folder is read as a Nativele template. An Angular component's templateUrl file uses Angular syntax ({{ user.name }}, *ngIf, (click)), so gen reports errors whose hints ask to rewrite a file that belongs to another framework.",
+		bad: `// src/app/app.ts
+@Component({ selector: "app-root", templateUrl: "./app.html" })
+# package.json
+"build": "ts-dom gen src && ng build"`,
+		good: `# keep the Nativele components in their own folder and scan only it
+"build": "ts-dom gen src/nv && ng build"`
+	},
+	"typecheck-before-gen": {
+		why: "The generated *.html.ts files are not committed. A script that runs tsc (or vue-tsc, svelte-check, ng build) before ts-dom gen works on a machine that has generated them once, and fails on a clean checkout or in CI with TS2307 for every ./x.html.js import.",
+		bad: `// package.json, with *.html.ts in .gitignore
+"build": "tsc && vite build"`,
+		good: `"build": "ts-dom gen src && tsc && vite build"
+// or, with plain tsc, let check generate and type-check in one step:
+"typecheck": "ts-dom check src"`
+	},
 	"vite-plugin-missing": {
-		why: "The Vite plugin regenerates the .html.ts files while the dev server runs. Without it, edits to a template are not reflected until gen is run by hand.",
+		why: "The Vite plugin regenerates the .html.ts files while the dev server runs. Without it, edits to a template are not reflected until gen is run by hand. A vitest.config file replaces vite.config for Vitest, so unless it has the plugin too or merges vite.config, the tests start without generated files and fail on a clean checkout.",
 		bad: `// vite.config.ts
-export default defineConfig({ plugins: [] });`,
+export default defineConfig({ plugins: [] });
+// vitest.config.ts next to a vite.config.ts that has tsDom()
+export default defineConfig({ test: { environment: "happy-dom" } });`,
 		good: `// vite.config.ts
 import { tsDom } from "@nativele/ts-dom/vite";
-export default defineConfig({ plugins: [tsDom()] });`
+export default defineConfig({ plugins: [tsDom()] });
+// vitest.config.ts
+import viteConfig from "./vite.config";
+export default mergeConfig(viteConfig, defineConfig({ test: { environment: "happy-dom" } }));`
 	},
 	"oxlint-plugin-missing": {
 		why: "The oxlint plugin runs the template rules (unused markup, data flow, accessibility) in the editor. Without it they only run from the CLI.",
@@ -1173,11 +1305,14 @@ export default defineConfig({ plugins: [tsDom()] });`
 }`
 	},
 	"formatter-whitespace": {
-		why: "Text whitespace in a template is kept as written. A formatter that re-indents the HTML can then change the spaces rendered on the page.",
+		why: "Text whitespace in a template is kept as written. A formatter that re-indents the HTML can then change the spaces rendered on the page. The same warning is given when the scripts or the Vite config ask for collapse but the generated files were written with preserve: a run without --whitespace keeps the mode a file was last written with, so one run without the flag leaves the project on preserve.",
 		bad: `# formatter is configured, templates keep their whitespace
-npx ts-dom gen`,
+npx ts-dom gen
+# or: package.json has "gen": "ts-dom gen src --whitespace=collapse", but the files came from a plain run
+npx ts-dom check src`,
 		good: `npx ts-dom gen --whitespace=collapse
-// or in vite.config.ts: tsDom({ whitespace: "collapse" })`
+// or in vite.config.ts: tsDom({ whitespace: "collapse" })
+# and after a plain run: npm run gen (the script with the flag) once`
 	},
 	"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.",
@@ -1212,11 +1347,14 @@ Commands
         --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)
+        --include=<glob>, --exclude=<glob>, --whitespace=collapse|preserve   as for gen
         --a11y            also check ARIA / accessibility (warnings)
         --strict          exit with code 1 on warnings too (errors always do)
         --json            print the issues as JSON instead of text
   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)
+        --include=<glob>, --exclude=<glob>, --whitespace=collapse|preserve   as for gen (they decide which
+                          generated files are stale)
         --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
@@ -1363,7 +1501,7 @@ if (!dirs.length) dirs.push("src");
 try {
 	if (cmd === "gen" && flags.has("--check")) {
 		const defs = scanDefines(dirs);
-		const results = dirs.map((d) => checkGenerated(d, generate, defs));
+		const results = dirs.map((d) => checkGenerated(d, generate, defs, dirs));
 		const stale = results.flatMap((r) => r.stale);
 		const errors = [...results.flatMap((r) => r.errors), ...crossDirDuplicates(dirs).map((d) => formatDiagnostics(d.file, [d]))];
 		if (flags.has("--json")) console.log(JSON.stringify({

package/dist/{lint-qEPgmmMa.mjs → lint-Did4w-NL.mjs}

@@ -1,4 +1,4 @@
-import { a as analyze, g as scanDefines, p as listHtml } from "./a11y-Bw-8ZIAK.mjs";
+import { a as analyze, g as scanDefines, p as listHtml } from "./a11y-CiEJj_e6.mjs";
 import { readFileSync } from "node:fs";
 import { basename, dirname, relative } from "node:path";
 // src/lib/lint.ts
@@ -126,7 +126,7 @@ function lintUsage(dirs, tsFiles) {
 				severity: "error",
 				line: 1,
 				col: 1,
-				message: `No TypeScript file imports this template. Fix: add \`import tpl from "./${name}.js"\` and \`class X extends Component(tpl)\` next to it, or delete the file.`
+				message: `No TypeScript file imports this template. Fix: add \`import tpl from "./${name}.js"\` and \`class X extends Component(tpl)\` next to it, or delete the file; if it is not a Nativele template, this folder is not meant to be scanned: scan only the folder with the Nativele templates.`
 			});
 			continue;
 		}

package/dist/oxlint-plugin.mjs

@@ -1,5 +1,5 @@
-import { n as checkA11y, t as A11Y_RULES } from "./a11y-Bw-8ZIAK.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-qEPgmmMa.mjs";
+import { n as checkA11y, t as A11Y_RULES } from "./a11y-CiEJj_e6.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-Did4w-NL.mjs";
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 // src/lib/oxlint-plugin.ts

package/dist/vite-plugin.mjs

@@ -1,6 +1,6 @@
-import { c as formatDiagnostics, d as isFullPage, f as isSelected, g as scanDefines, i as CodegenError, l as generateDirs, n as checkA11y, p as listHtml, u as generateFile } from "./a11y-Bw-8ZIAK.mjs";
+import { c as formatDiagnostics, d as isFullPage, f as isSelected, g as scanDefines, i as CodegenError, l as generateDirs, n as checkA11y, p as listHtml, u as generateFile } from "./a11y-CiEJj_e6.mjs";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
-import { resolve, sep } from "node:path";
+import { relative, resolve, sep } from "node:path";
 // src/lib/vite-plugin.ts
 const GENERATED_HEADER = "// Generated by ts-dom.";
 const slashes = (file) => file.split(sep).join("/");
@@ -17,6 +17,7 @@ function tsDom(opts = {}) {
 		exclude: opts.exclude
 	};
 	const a11y = opts.a11y === true ? {} : opts.a11y || null;
+	let root = process.cwd();
 	let dirs = (opts.dirs ?? ["src"]).map((d) => resolve(d));
 	const shown = /* @__PURE__ */ new Map();
 	let defs;
@@ -83,10 +84,12 @@ function tsDom(opts = {}) {
 		name: "ts-dom",
 		enforce: "pre",
 		configResolved(config) {
+			root = config.root;
 			dirs = (opts.dirs ?? ["src"]).map((d) => resolve(config.root, d));
 			defs = void 0;
 		},
 		buildStart() {
+			for (const d of dirs) if (!existsSync(d)) this.warn(`${relative(process.cwd(), d) || "."}:1:1 warning [dir-not-found] The folder ${d} given in tsDom({ dirs }) does not exist, so no templates in it are generated. Fix: dirs are resolved against Vite's root (${root}), not the working directory; give the folder relative to that root, or an absolute path.`);
 			try {
 				generateDirs(existing(), generate);
 			} catch (e) {

package/llms.txt

@@ -101,8 +101,10 @@ In a browser without a bundler map the bare name once: `<script type="importmap"
 - `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.
+- A Light DOM component builds its content when connected (a `shadow: true` one in the constructor), so a new Light element has no children, `refs` or `text` until it is appended.
+- Inside a framework (React, Vue, Svelte, ...), children the framework later inserts, removes or reorders in a Light DOM host with slots break or land in the wrong slot: use `shadow: true`, or one stable element per slot.
 
 ## Docs
 - [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), [architecture](docs/architecture.md), [setup, checks and lint](docs/tooling.md), [performance](docs/performance.md), [design](docs/design.md), [developing Nativele](docs/contributing.md).
+- Guides (English): [templates](docs/templates.md), [components and data flow](docs/components.md), [recipes](docs/recipes.md), [lists](docs/lists.md), [architecture](docs/architecture.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,6 +1,6 @@
 {
   "name": "@nativele/ts-dom",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "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",

package/skills/README.md

@@ -22,7 +22,7 @@ skills/
 │   └── 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
+│       └── verify.mjs            # browser checks run by `npm run verify` (or the project's own tests, see below)
 └── ...
 ```
 
@@ -90,7 +90,7 @@ None of this adds a runtime dependency: listing and copying read the Markdown fi
 
 ## 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.
+- `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 real-browser test of what the Skill promises: usually a `verify.mjs` script; an example whose Skill sets up tests (`nativele-testing`, `nativele-architecture`) runs its own Vitest and Playwright Test suites instead.
 - `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 an `example/` changes, when the library's runtime changes, and once a month, so a third-party release that breaks a Skill is found. A change to `SKILL.md` runs only `.github/workflows/skills-format.yml`, which checks every `SKILL.md` against this specification. Neither is 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.

package/skills/nativele-angular/SKILL.md

@@ -274,9 +274,7 @@ export class App {
 1. **`CUSTOM_ELEMENTS_SCHEMA` turns off binding checks for unknown elements.** With it, Angular's compiler accepts any property on any hyphenated tag: `[item]="42"`, `[count]="'x'"` and `[nope]="1"` on `<info-card>` all build without an error. Angular has no mechanism to type-check bindings on custom elements, so keep the values typed in the Angular class (`signal<Item>(...)`) and check the Nativele side with `ts-dom check src/nv`.
 2. **`$event` is typed `Event`.** Angular's template type checker types `$event` of a DOM event it does not know as `Event`, so `select($event.detail)` or a handler parameter typed `CustomEvent<...>` fails with `TS2339: Property 'detail' does not exist on type 'Event'` or `TS2345: Argument of type 'Event' is not assignable to parameter of type 'CustomEvent<...>'`. Take `Event` and cast it with `EmitEvent<Component, 'event-name'>` from `@nativele/ts-dom`; a wrong event name there becomes `never` and fails with `Property 'detail' does not exist on type 'never'`. Nothing checks that the cast names the element the listener is on.
 3. **Bind properties, not attributes, for objects.** `[attr.item]="item()"` writes the attribute `item="[object Object]"` and the prop stays `null`. `[attr.count]` works for a number prop (the attribute text is converted), but `[count]` is simpler.
-4. **Light DOM slots and Angular-managed children do not mix.** In the default Light DOM mode (`Component(tpl)` without `shadow`), Nativele moves the host's children into its slot positions. When `@if` or `@for` sit directly inside the tag, Angular still adds and removes nodes, but a node it re-inserts lands in the wrong place: a `<span slot="title">` brought back by `@if` ends up in the default slot while the title shows its fallback, and `assignedNodes()` stops matching the page. Angular reports no error. Use one of:
-   - `shadow: true` on the component; `@if` and `@for` children can then change freely;
-   - one stable element per slot that Angular never removes, with `@if`/`@for` inside it (the `light-card` above). A stable but empty wrapper still fills its slot, so the slot's fallback content does not show; when the fallback matters, use `shadow: true`.
+4. **Light DOM slots and Angular-managed children do not mix** (https://github.com/Pixmi/nativele/blob/main/docs/components.md#slots-and-children-managed-by-a-framework). When `@if` or `@for` sit directly inside a Light DOM host with slots, Angular still adds and removes nodes, but a node it re-inserts lands in the wrong place: a `<span slot="title">` brought back by `@if` ends up in the default slot while the title shows its fallback, and `assignedNodes()` stops matching the page. Angular reports no error. Use `shadow: true`, or one stable element per slot that Angular never removes, with `@if`/`@for` inside it (the `light-card` above).
 5. **Zoneless rendering is scheduled.** In the CLI's default zoneless app, Angular updates the DOM after a click in a later task, so code that calls `button.click()` and reads the DOM right away sees the old values; with `zone.js` the DOM is already updated when `click()` returns. A test that reads the DOM right after dispatching an event must wait (Playwright: wait for the expected text; TestBed: `await fixture.whenStable()`). The Nativele component itself renders synchronously as soon as Angular sets the property.
 6. **State changed outside Angular's listeners.** In a zoneless app, a plain field set from a Nativele store subscription (`session.subscribe(...)` in an Angular class) or a `setTimeout` does not re-render the Angular view; put the value in a signal. Nativele components that `bind` the store update themselves either way.
 7. **`ng serve` started before the modules were generated stays broken.** It fails with `Could not resolve "./info-card.html.js"` and does not rebuild when `ts-dom gen` creates the files later. Use `npm start` (step 4 runs `gen` first), or restart `ng serve`, or save one of the component `.ts` files.

package/skills/nativele-architecture/SKILL.md

@@ -167,7 +167,7 @@ Verified on 2026-11-05 with Node 24 and Google Chrome 148, with the example proj
     npm pkg set scripts.verify="npm run build && ts-dom doctor src && npm test && npm run test:browser && npm run test:e2e"
     ```
 
-    Add `test-results` and `playwright-report` to `.gitignore`, next to `*.html.ts` and `ts-dom-tags.ts`.
+    The build script is for a project whose type check is plain `tsc`: `ts-dom check` generates the files and type-checks. In a framework project, keep the framework's type check (`tsc -b`, `vue-tsc -b`, `svelte-check`) and put `ts-dom gen src &&` in front of it instead (the framework's Skill shows the script). Add `test-results` and `playwright-report` to `.gitignore`, next to `*.html.ts` and `ts-dom-tags.ts`.
 
 ## Example
 

package/skills/nativele-integration/SKILL.md

@@ -16,7 +16,7 @@ metadata:
 
 - The app is built with a UI framework and wants to use components written with Nativele (`@nativele/ts-dom`), and no Skill exists for that framework yet. React, Vue, Svelte and Angular have their own (`nativele-react`, `nativele-vue`, `nativele-svelte`, `nativele-angular`); `npx ts-dom skills` lists every Skill.
 - It is a procedure for finding out how the framework treats custom elements and connecting it correctly. It does not cover setting the framework itself up: start from the app as it is, with its own type checker and build.
-- A framework with its own file format type-checks it with its own tool (Vue: `vue-tsc`). `ts-dom check` runs `vue-tsc` instead of `tsc` when the project's `package.json` lists it; for other formats see Troubleshooting. A framework that uses TSX (Preact, Solid) is checked by plain `tsc`, and `ts-dom check` reports its errors too.
+- A framework with its own file format type-checks it with its own tool (Vue: `vue-tsc`). `ts-dom check` runs `vue-tsc` instead of `tsc` when the project's `package.json` lists it and it resolves from the project folder; for other formats see Troubleshooting. A framework that uses TSX (Preact, Solid) is checked by plain `tsc`, and `ts-dom check` reports its errors too.
 - Not for writing the Nativele components themselves: use `nativele-core` (`npx ts-dom skills add nativele-core`).
 
 Nativele components are native custom elements. The framework renders their tags like any other tag; nothing wraps them. Every rule below follows from that.
@@ -56,8 +56,8 @@ Verified on 2026-11-05 in Google Chrome 148, starting from `create-vite` 9.3.4 w
 
    Many frameworks decide between property and attribute by checking whether the element already has the property, which is only true after `define()` has run.
 
-5. Give the framework's template type checker the Nativele tags. `ts-dom gen` writes `ts-dom-tags.ts`, which adds every exported component to `HTMLElementTagNameMap`; a component's props are the keys of its `props` member, and its events are in the optional `"~emits"` member (event name to `detail` type). Build the framework's tag declaration from these, so new components need no edit; "In Preact (verified)" below has the one for Preact's JSX, `nativele-react` the one for React and `nativele-vue` the Vue one. Check how the framework names an event listener in its types: Preact and React type `item-select` as the prop `onitem-select`, Vue types `@item-select` as `onItemSelect`. If the framework has no typed templates, skip this step.
-6. The generated files are not committed, so on a clean checkout a build script that runs the type checker before the bundler (the `preact-ts` template's `"build": "tsc -b && vite build"`) fails with `TS2307: Cannot find module './x.html.js'`. Put `ts-dom gen src/nv &&` in front: `"build": "ts-dom gen src/nv && tsc -b && vite build"`. The dev server needs no change: the Vite plugin generates the files when it starts.
+5. Give the framework's template type checker the Nativele tags. `ts-dom gen` writes `ts-dom-tags.ts`, which adds every exported component to `HTMLElementTagNameMap`; the element type members a declaration reads (`props` and `"~emits"`) are in https://github.com/Pixmi/nativele/blob/main/docs/components.md#element-types-for-framework-declarations. Build the framework's tag declaration from these, so new components need no edit; "In Preact (verified)" below has the one for Preact's JSX, `nativele-react` the one for React and `nativele-vue` the Vue one. Check how the framework names an event listener in its types: Preact and React type `item-select` as the prop `onitem-select`, Vue types `@item-select` as `onItemSelect`. If the framework has no typed templates, skip this step.
+6. The generated files are not committed, so on a clean checkout a build script that runs the type checker before the bundler (the `preact-ts` template's `"build": "tsc -b && vite build"`) fails with `TS2307: Cannot find module './x.html.js'`. Put `ts-dom gen src/nv &&` in front: `"build": "ts-dom gen src/nv && tsc -b && vite build"`. Do the same in front of whatever type check the framework's template runs (`vue-tsc -b`, `svelte-check`). Only a project whose type check is plain `tsc` replaces it with `ts-dom check`, which generates and type-checks: `"build": "ts-dom check src/nv && vite build"`, as `nativele-vite` sets it up. The dev server needs no change: the Vite plugin generates the files when it starts.
 
 ## Example
 
@@ -138,9 +138,7 @@ A template ref is typed from the same map: `useRef<HTMLElementTagNameMap["nv-inf
 
 1. **Define before render.** Import the component modules before the framework mounts (step 4). A framework that sees an undefined element may write an attribute instead of a property: in Preact, `item={item}` becomes the attribute `item="[object Object]"`, the component gets `null` after `define()`, and the attribute stays even after a later new object is set as a property. A property set before `define()` is kept: Nativele takes it over when the element is upgraded. So when a module really is loaded later, set object props through the framework's property syntax, or, where it has none (Preact), from a ref: `ref={(el) => { if (el) el.item = item; }}`, and leave `item={item}` out of that tag, or Preact also writes the attribute.
 2. **Props.** A prop whose default is a string, number or boolean can also come from an attribute, with camelCase names in kebab-case (`maxLength` from `max-length`, a boolean `true` when the attribute is present). Arrays and objects can only be set as properties. Pass a new object when data changes: props are compared by reference.
-3. **Light DOM slots and framework-managed children do not mix.** In the default Light DOM mode (`Component(tpl)` without `shadow`), Nativele moves the tag's children into its slot positions; a framework that later inserts, removes or reorders those children can fail or leave nodes outside the slot. In Preact, toggling or reordering such children throws `NotFoundError: Failed to execute 'moveBefore' on 'Element'` (or `'insertBefore' on 'Node'`) and the slot loses its children. Use one of:
-   - `shadow: true` on the component, so the browser assigns slots natively and the children can change freely;
-   - one stable element per slot that the framework never removes, with the changing content inside it (`<div slot="title">...</div>`, `<div>...</div>` for the default slot). A stable but empty wrapper still fills its slot, so the slot's fallback content does not show; when the fallback matters, use `shadow: true`.
+3. **Light DOM slots and framework-managed children do not mix** (https://github.com/Pixmi/nativele/blob/main/docs/components.md#slots-and-children-managed-by-a-framework): a framework that inserts, removes or reorders the children of a Light DOM host with slots can fail or leave nodes in the wrong slot. In Preact, toggling or reordering such children throws `NotFoundError: Failed to execute 'moveBefore' on 'Element'` (or `'insertBefore' on 'Node'`) and the slot loses its children. Use `shadow: true`, or one stable element per slot that the framework never removes, with the changing content inside it.
 4. **Events do not bubble.** `emit` dispatches a `CustomEvent` on the component that does not bubble, so the listener must be on that element, not on an ancestor. The event data is `event.detail`.
 5. **Lifecycle.** `connected()` runs each time the element is inserted and `disconnected()` each time it is removed, and `bind` subscriptions end on removal and start again on insertion. A framework that moves an element (reordering a keyed list) with `insertBefore` runs both; one that moves it with `moveBefore` keeps it connected, so neither runs and its subscriptions continue. Preact 11 uses `moveBefore` where the browser has it (Chrome does) and `insertBefore` elsewhere. Either way the moved element keeps its props and the children in its Light DOM slots. So subscribe in `connected()`, and do not rely on a move running it.
 6. **The framework's templates are checked by the framework's type checker**, with the declaration from step 5, not by the Nativele rules. How much it checks depends on the framework: with the Preact declaration, `tsc` reports a wrong prop type, a wrong object shape, a wrong use of `e.detail`, an unknown prop name, an event prop in the wrong case (`onItemSelect`) and an unknown tag, but not a hyphenated attribute name (`selected-item`), which TypeScript never checks in JSX; `vue-tsc` reports a wrong prop type or event detail, but not an unknown prop name.

package/skills/nativele-react/SKILL.md

@@ -162,18 +162,14 @@ define("shadow-card", ShadowCard);
 
 1. **Define before render.** Import every Nativele module before React first renders its tag (step 6). Otherwise props become attributes and object props are lost.
 2. **Event prop names.** Only `on` plus the exact event name works (`onitem-select`); `onItemSelect` and `onItem-select` never fire. Nativele events do not bubble by default, so put the handler on the element that emits. A ref with `addEventListener` in `useEffect` also works (remove it in the cleanup).
-3. **Light DOM slots and React children do not mix.** In the default Light DOM mode (`Component(tpl)` with no `shadow`), Nativele moves the host's children into its slot positions. When React later inserts, removes or reorders those children it fails (`insertBefore`/`removeChild` errors that unmount the root) or leaves nodes outside the slot. Changing text in place and appending at the end happen to work, but do not rely on that. Use one of:
-   - `shadow: true` on the component (children can then change freely), or
-   - one stable React element per slot, and let React change only what is inside it:
-
-     ```tsx
-     <light-card>
-       <div slot="title">{showTitle && <span>{title}</span>}</div>
-       <div>{rows.map((r) => <p key={r.id}>{r.text}</p>)}</div>
-     </light-card>
-     ```
-
-     A stable but empty wrapper still fills its slot, so the slot's fallback content does not show; when the fallback matters, use `shadow: true`.
+3. **Light DOM slots and React children do not mix** (https://github.com/Pixmi/nativele/blob/main/docs/components.md#slots-and-children-managed-by-a-framework). When React inserts, removes or reorders the children of a Light DOM host with slots, it fails with `insertBefore`/`removeChild` errors that unmount the root, or leaves nodes outside the slot. Changing text in place and appending at the end happen to work, but do not rely on that. Use `shadow: true`, or one stable React element per slot and let React change only what is inside it:
+
+   ```tsx
+   <light-card>
+     <div slot="title">{showTitle && <span>{title}</span>}</div>
+     <div>{rows.map((r) => <p key={r.id}>{r.text}</p>)}</div>
+   </light-card>
+   ```
 4. **New objects for changed props.** A Nativele component compares props by reference; pass a new object when the data changes (React state updates usually do).
 5. **TSX types need the declaration** in step 7; without it, every Nativele tag is `TS2339: Property 'info-card' does not exist on type 'JSX.IntrinsicElements'`. Check it with a `.tsx` that has a wrong prop under `// @ts-expect-error`, because `skipLibCheck` can hide mistakes inside the declaration itself. Keep these cases in a `.tsx` file of their own that the app never imports (the example uses `src/types-check.tsx`).
 6. Not verified: server-side rendering, form controls inside Nativele components submitting with a React form, and React versions other than 19.3.

package/skills/nativele-svelte/SKILL.md

@@ -196,18 +196,14 @@ Used from Svelte:
 
 1. **Define before mount.** Import the component modules before `mount` (step 6). Svelte 5 decides per value: when the element is defined, it sets a property the element has; when it is not defined yet (for example a module loaded later with `import()`), it sets objects and arrays as properties and writes every other value as an attribute string. Nativele reads both when the element is upgraded, which was verified for string, number and boolean props with one-word names (`count={0}` becomes `count="0"`, `false` becomes `open="false"`, both arrive with the right type). Other cases were not verified, so define first.
 2. **Event attribute names.** Only `on` plus the exact event name works (`onitem-select`). `onItemSelect` listens to an event named `ItemSelect` and never fires; with the declaration it is also a `svelte-check` error. The legacy directive `on:item-select` fires too, but only use the event attributes: in a runes component `on:` is deprecated (compiler warning `event_directive_deprecated`), a component cannot mix it with event attributes (compile error `mixed_event_handler_syntaxes`), and the declaration in step 7 does not type it. Nativele events do not bubble, so put the handler on the element that emits.
-3. **Light DOM slots and Svelte-managed children do not mix.** In the default Light DOM mode (`Component(tpl)` with no `shadow`), Nativele moves the host's children into its slot positions, together with the comment nodes Svelte uses as anchors. Svelte does not throw, but it goes wrong silently: an `{#if}` that adds `<span slot="title">` back inserts it next to its anchor, which now sits in the default slot, so the title slot shows its fallback; and `assignedNodes()` stops matching what is on the page. Keyed `{#each}` reordering happened to look right, but do not rely on it. Use one of:
-   - `shadow: true` on the component (children can then change freely), or
-   - one stable element per slot, and let Svelte change only what is inside it:
-
-     ```svelte
-     <light-card>
-       <div slot="title">{#if showTitle}<span>Title</span>{/if}</div>
-       <div>{#each rows as r (r)}<p>{r}</p>{/each}</div>
-     </light-card>
-     ```
-
-     A stable but empty wrapper still fills its slot, so the slot's fallback content does not show; when the fallback matters, use `shadow: true`.
+3. **Light DOM slots and Svelte-managed children do not mix** (https://github.com/Pixmi/nativele/blob/main/docs/components.md#slots-and-children-managed-by-a-framework). Nativele moves the comment nodes Svelte uses as anchors into the slot positions together with the children. Svelte does not throw, but it goes wrong silently: an `{#if}` that adds `<span slot="title">` back inserts it next to its anchor, which now sits in the default slot, so the title slot shows its fallback; and `assignedNodes()` stops matching what is on the page. Keyed `{#each}` reordering happened to look right, but do not rely on it. Use `shadow: true`, or one stable element per slot and let Svelte change only what is inside it:
+
+   ```svelte
+   <light-card>
+     <div slot="title">{#if showTitle}<span>Title</span>{/if}</div>
+     <div>{#each rows as r (r)}<p>{r}</p>{/each}</div>
+   </light-card>
+   ```
 4. **New objects for changed props.** A Nativele component compares props by reference. Changing a `$state` object in place (`item.name = "kiwi"`) does not re-render it; assign a new object (`item = { ...item, name: "kiwi" }`).
 5. **Write closing tags.** `<info-card ... />` works, but the Svelte compiler warns `element_invalid_self_closing_tag` (shown in the dev server's terminal); write `<info-card ...></info-card>`.
 6. **Template types need the declaration** in step 7. Without it, Svelte accepts any attribute on a hyphenated tag, and an inline handler's parameter is `any` (`Parameter 'e' implicitly has an 'any' type` under `strict`). With it, `svelte-check` reports a wrong prop type, an unknown prop name, a wrong `e.detail` field and a camelCase handler name. `<!-- @ts-expect-error -->` in markup does not silence an error, so keep the expected-error cases in a `.ts` file (step 8). To type an element reference, use the tag map: `let card: HTMLElementTagNameMap["info-card"] | undefined = $state()` with `bind:this={card}`.

package/skills/nativele-testing/SKILL.md

@@ -69,7 +69,7 @@ Verified on 2026-11-05 with Node 24 and Google Chrome 148, starting from `create
    npm pkg set scripts.test="vitest run --project unit"
    ```
 
-   Keep `ts-dom check src/nv` in the build script (as `nativele-vite` sets it up) or run it before or after the tests: it is what reports type errors in the tests and the templates.
+   `ts-dom check src/nv` is what reports type errors in the tests and the templates. In a project whose type check is plain `tsc`, the build script `ts-dom check src/nv && vite build` (as `nativele-vite` sets it up) runs it; in a framework project, whose build puts `ts-dom gen src/nv &&` in front of its own type check (`tsc -b`, `vue-tsc -b`, `svelte-check`), run `ts-dom check src/nv` before or after the tests.
 
 5. For the real-browser tests, install the Vitest provider and Playwright, and add a second project. It drives the Chrome already installed on the machine (`CHROME_BIN`, or `/usr/bin/google-chrome`, which GitHub's `ubuntu-latest` runners have), so nothing is downloaded and `npx playwright install` is not needed:
 

package/skills/nativele-vite/SKILL.md

@@ -17,7 +17,7 @@ metadata:
 - A Vite app with no UI framework (for example one started with `npm create vite@latest -- --template vanilla-ts`) that adds components written with Nativele (`@nativele/ts-dom`).
 - Any Vite project with Nativele whose set-up goes beyond the defaults: `root` in a sub-folder, several HTML pages, Vite+, or questions about what `vite dev` does when a template changes.
 - Signals: `vite` or `vite-plus` and `@nativele/ts-dom` in `package.json`, a `vite.config.ts`.
-- With React, follow `nativele-react`; with another framework, `nativele-integration`. The parts about `dirs`, `root` and the build script apply there too, but the hot-update behavior below was verified without a framework.
+- With a UI framework, follow its Skill: `nativele-react`, `nativele-vue`, `nativele-svelte`, `nativele-angular`, or `nativele-integration` for any other. The parts about `dirs` and `root` apply there too; the build script in step 5 does not: it is for a project whose type check is plain `tsc`, while a framework project keeps its own type check (`tsc -b`, `vue-tsc -b`, `svelte-check`) and puts `ts-dom gen <folder> &&` in front of that script. The hot-update behavior below was verified without a framework.
 - Not for writing the components themselves (`npx ts-dom skills add nativele-core`), and not for setting Vite up.
 
 ## Versions

package/skills/nativele-vue/SKILL.md

@@ -219,7 +219,7 @@ define("nv-light-card", LightCard);
 3. **camelCase prop names in templates.** Write Nativele props as they are declared: `:selectedItem="item"`, `:maxCount="3"`. Vue sets a kebab-case binding (`:selected-item`) as an attribute, because the element has no property of that name: a number or string still converts from the attribute, an object or array arrives as `"[object Object]"` and the prop stays `null`. `vue-tsc` does not report this (limitation 8).
 4. **Exact event names.** On a custom element, Vue listens to the event name exactly as written after `@`: `@item-select` hears `item-select`, `@pickedOne` hears `pickedOne`, and `@itemSelect` never hears `item-select`. Name events in kebab-case and write that name. Nativele events do not bubble by default, so the listener goes on the element that emits.
 5. **`v-model` does not work on a Nativele component.** It compiles, `vue-tsc` accepts it and Vue logs no warning; it writes the first value into the element, but typing never updates the Vue state. Use a prop and an event, as `nv-text-field` above: `:value="text" @value-change="(e) => (text = e.detail.value)"`. In the component, compare before writing the input's value, so the cursor does not jump (see "A Small Reminder About Form Inputs" in the components guide).
-6. **Light DOM slots and Vue children do not mix.** In the default Light DOM mode, Nativele moves the host's children into its slot positions. When Vue later inserts, removes or reorders those children (`v-if`, `v-for`), the update throws (`Cannot read properties of null (reading 'insertBefore')`, `Cannot set properties of null (setting '__vnode')`) and the slots show the wrong children. Use `shadow: true`, or one stable element per slot as in the example. A stable but empty wrapper still fills its slot, so the slot's fallback content does not show; when the fallback matters, use `shadow: true`.
+6. **Light DOM slots and Vue children do not mix** (https://github.com/Pixmi/nativele/blob/main/docs/components.md#slots-and-children-managed-by-a-framework). When Vue inserts, removes or reorders the children of a Light DOM host with slots (`v-if`, `v-for`), the update throws (`Cannot read properties of null (reading 'insertBefore')`, `Cannot set properties of null (setting '__vnode')`) and the slots show the wrong children. Use `shadow: true`, or one stable element per slot as in the example.
 7. **Lifecycle follows the DOM.** When a keyed `v-for` reorders Nativele elements, Vue moves the same element with `insertBefore`: it runs `disconnected()` then `connected()`, keeps its props and its Light DOM slot children, and `bind` subscriptions end and start again. `<KeepAlive>` deactivation takes the element out of the document (`disconnected()`, no store updates while inactive); activation puts the same element back (`connected()`, and `bind` calls back at once with the current value). `v-if` removal runs `disconnected()` and ends the subscriptions. So subscribe in `connected()`, as the lists guide says for moved items.
 8. **What `vue-tsc` checks.** With the declaration from step 7, it reports a wrong prop type (`count="1"` on a number prop), a wrong object shape and a wrong use of `e.detail`. It does not report an unknown prop name, an unknown tag with the prefix, a kebab-case prop name, `v-model`, or an event name whose case differs from the declared one. In a template, mark an expected error with `<!-- @vue-expect-error -->`; `// @ts-expect-error` is rendered as text and suppresses nothing.
 9. Not verified: server-side rendering and hydration, Nuxt, `<Transition>` around Nativele elements, and Vue versions other than 3.5.
@@ -235,7 +235,7 @@ npx vue-tsc -b               # expect: no output
 npx vite build               # expect: built
 ```
 
-`ts-dom check` runs `vue-tsc` instead of `tsc` when `vue-tsc` is installed, so it also reports type errors in `.vue` files.
+`ts-dom check` runs `vue-tsc` instead of `tsc` when the project's `package.json` lists `vue-tsc` (in `dependencies` or `devDependencies`) and it resolves from the project folder, so it also reports type errors in `.vue` files.
 
 Prove that the declaration types props: keep a `.vue` file that the app never imports (the example uses `src/TypesCheck.vue`) with one wrong case per kind under `<!-- @vue-expect-error -->`: