@nativele/ts-dom 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -10,6 +10,52 @@ 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.5
+
+Skills are verified by agent trials and stand on their own: each Skill can be followed and is accurate without its example project, which stays in the repository only as a reference.
+
+- A Skill is verified by its agent trials. An `example/` is an optional reference project from the trial and is no longer run in CI; Official means accepted through an agent trial and maintained by the maintainers. Each Skill's Versions table names the version of its last agent trial, and `test/skills.test.ts` keeps that row in line with the `nativele` range.
+- "SKILL.md format" (in `skills.yml`) is a required check for `main`: it reports on every pull request, skips its steps when nothing it checks changed, and also covers the links in the READMEs, `llms.txt` and the guides.
+- `skills/README.md` gives a fixed form for the agent trial record added to a Skill pull request.
+- Every Skill is self-contained. The architecture Skill names the interfaces of the small components its example code uses. Across the Skills, an example project is mentioned only as a reference implementation, never as the source of a step or a fact.
+
+## 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,18 +63,18 @@ 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) |
 | `nativele-zod` | form validation with Zod or Valibot (Experimental) |
 | `nativele-tailwind` | Tailwind CSS in templates and Shadow DOM (Experimental) |
 
-Tiers: Official Skills are verified by the maintainers against an example project in CI; Community Skills are contributed and show their author and last verified versions; Experimental Skills are not fully verified yet. `ts-dom skills` marks a Skill as stale when its verification is more than six months old or does not cover the installed version.
+Tiers: Official Skills are verified through agent trials and maintained by the maintainers; Community Skills are contributed and show their author and last verified versions; Experimental Skills are not fully verified yet. `ts-dom skills` marks a Skill as stale when its verification is more than six months old or does not cover the installed version.
 
 Nativele stays a light UI layer and grows its integrations through Skills: a new Skill changes no runtime code and adds no dependency. The planned Skills and how to contribute one are in [the Skills guide](https://github.com/Pixmi/nativele/blob/main/skills/README.md).
 

package/README.zh-TW.md

@@ -63,18 +63,18 @@ 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） |
 | `nativele-zod` | 用 Zod 或 Valibot 驗證表單（Experimental） |
 | `nativele-tailwind` | 在範本與 Shadow DOM 中使用 Tailwind CSS（Experimental） |
 
-等級：Official 由維護者以 CI 中的範例專案驗證；Community 由社群貢獻，標示作者與最後驗證版本；Experimental 尚未充分驗證。驗證超過六個月，或不涵蓋已安裝的版本時，`ts-dom skills` 會標示為可能過期。
+等級：Official 經 agent 實際驗收、由維護者維護；Community 由社群貢獻，標示作者與最後驗證版本；Experimental 尚未充分驗證。驗證超過六個月，或不涵蓋已安裝的版本時，`ts-dom skills` 會標示為可能過期。
 
 Nativele 維持輕量的 UI 層，整合能力透過 Skill 擴展：新增 Skill 不改動執行期程式碼，也不增加依賴。規劃中的 Skill 與貢獻方式見 [Skills 指南](https://github.com/Pixmi/nativele/blob/main/skills/README.md)。
 

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.5",
   "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",