@nativele/ts-dom 0.5.2 → 0.5.4

package/dist/cli.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { _ as watchAll, a as analyze, c as generateAll, d as isSelected, f as listHtml, g as staleGenerated, i as CodegenError, m as renderTags, n as checkA11y, o as checkGenerated, p as listTs, r as CODEGEN_RULES, t as A11Y_RULES } from "./a11y-CV3nBgBn.mjs";
-import { c as lintUsage, n as UNUSED_MARKUP_RULES, o as formatIssue, s as lintDataFlow, t as DATA_FLOW_RULES } from "./lint-Bwytj7L8.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));
+}
+/** 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 out.filter((i) => i.rule !== "tsc" || !followsBroken(i.message));
+	return -1;
 }
 function findTsc(cwd) {
 	const req = createRequire(join(cwd, "package.json"));
@@ -272,16 +303,22 @@ function runCheck(options) {
 			message: e.message.replace(/^[^[]*\[duplicate-define\]\s*/, "")
 		});
 	}
-	if (options.write === false) for (const dir of dirs) for (const s of staleGenerated(dir, generate)) issues.push({
-		file: rel(s.file),
-		line: 1,
-		col: 1,
-		rule: "stale-generated",
-		severity: "error",
-		message: `The generated file is ${s.reason}, so the type errors below may not match the templates. Fix: run ts-dom gen (or ts-dom check without --no-write).`
+	for (const d of crossDirDuplicates(dirs)) issues.push({
+		...d,
+		file: rel(d.file)
 	});
-	else for (const dir of dirs) try {
-		generateAll(dir, generate);
+	if (options.write === false) {
+		const defs = scanDefines(dirs);
+		for (const dir of dirs) for (const s of staleGenerated(dir, generate, defs, dirs)) issues.push({
+			file: rel(s.file),
+			line: 1,
+			col: 1,
+			rule: "stale-generated",
+			severity: "error",
+			message: `The generated file is ${s.reason}, so the type errors below may not match the templates. Fix: run ts-dom gen (or ts-dom check without --no-write).`
+		});
+	} else try {
+		generateDirs(dirs, generate);
 	} catch (e) {
 		if (!(e instanceof CodegenError)) throw e;
 	}
@@ -445,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"
 };
@@ -461,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. */
@@ -522,6 +579,7 @@ function runDoctor(options) {
 		resolvable = false;
 	}
 	if (!resolvable) add("runtime-not-installed", "error", `The generated files import "${runtime}", which cannot be resolved from this project. Fix: npm i ${runtime}.`);
+	const defs = scanDefines(dirs);
 	for (const d of dirs) {
 		for (const f of listTs(d)) readFileSync(f, "utf8").split("\n").forEach((text, i) => {
 			const m = /from\s+["'](\.{1,2}\/[^"']+\.html)["']/.exec(text);
@@ -530,7 +588,14 @@ function runDoctor(options) {
 				line: i + 1
 			});
 		});
-		for (const s of staleGenerated(d, generate)) 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",
@@ -540,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) });
@@ -550,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",
@@ -558,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);
@@ -1023,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
@@ -1093,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.",
@@ -1147,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.",
@@ -1166,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.",
@@ -1205,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
@@ -1355,9 +1500,10 @@ const dirs = args.filter((a) => !a.startsWith("--"));
 if (!dirs.length) dirs.push("src");
 try {
 	if (cmd === "gen" && flags.has("--check")) {
-		const results = dirs.map((d) => checkGenerated(d, generate));
+		const defs = scanDefines(dirs);
+		const results = dirs.map((d) => checkGenerated(d, generate, defs, dirs));
 		const stale = results.flatMap((r) => r.stale);
-		const errors = results.flatMap((r) => r.errors);
+		const errors = [...results.flatMap((r) => r.errors), ...crossDirDuplicates(dirs).map((d) => formatDiagnostics(d.file, [d]))];
 		if (flags.has("--json")) console.log(JSON.stringify({
 			stale: stale.map((s) => ({
 				...s,
@@ -1373,8 +1519,8 @@ try {
 		if (stale.length || errors.length) process.exitCode = 1;
 	} else if (cmd === "gen") {
 		let failed = false;
-		for (const d of dirs) try {
-			generateAll(d, generate);
+		try {
+			generateDirs(dirs, generate);
 		} catch (e) {
 			if (!(e instanceof CodegenError) || !flags.has("--watch")) throw e;
 			console.error(e.message);

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

@@ -1,4 +1,4 @@
-import { a as analyze, f as listHtml, h as scanDefines } from "./a11y-CV3nBgBn.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-CV3nBgBn.mjs";
-import { a as dataFlow, i as contractsFor, l as templateCode, n as UNUSED_MARKUP_RULES, r as componentClasses, t as DATA_FLOW_RULES, u as unusedMarkup } from "./lint-Bwytj7L8.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 generateAll, d as isSelected, f as listHtml, h as scanDefines, i as CodegenError, l as generateFile, n as checkA11y, s as formatDiagnostics, u as isFullPage } from "./a11y-CV3nBgBn.mjs";
+import { 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,18 +17,13 @@ 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();
-	const defsByDir = /* @__PURE__ */ new Map();
-	const defsOf = (dir) => {
-		let defs = defsByDir.get(dir);
-		if (!defs) defsByDir.set(dir, defs = existsSync(dir) ? scanDefines(dir) : []);
-		return defs;
-	};
-	const isDefineFile = (file) => {
-		const dir = dirOf(file);
-		return dir !== void 0 && defsOf(dir).some((d) => resolve(d.file) === file);
-	};
+	let defs;
+	const existing = () => dirs.filter((d) => existsSync(d));
+	const allDefs = () => defs ??= scanDefines(existing());
+	const isDefineFile = (file) => allDefs().some((d) => resolve(d.file) === file);
 	const dirOf = (file) => dirs.find((d) => file.startsWith(d + sep));
 	const warnA11y = (warn) => {
 		if (!a11y) return;
@@ -48,7 +43,7 @@ function tsDom(opts = {}) {
 		const out = `${file}.ts`;
 		const before = read(out);
 		try {
-			generateFile(file, generate, defsOf(dir));
+			generateFile(file, generate, allDefs());
 		} catch (e) {
 			if (e instanceof CodegenError) logger.error(e.message);
 			else throw e;
@@ -57,16 +52,16 @@ function tsDom(opts = {}) {
 		if (a11y) for (const diag of checkA11y(html, a11y.ignore)) logger.warn(formatDiagnostics(file, [diag]));
 		return read(out) !== before;
 	};
-	/** Regenerate a directory after a define() call may have changed: the tag map and the child imports of every template. */
-	const regenerateDir = (dir, logger) => {
-		const before = new Map(listHtml(dir).map((f) => [`${f}.ts`, read(`${f}.ts`)]));
+	/** Regenerate after a define() call may have changed: the tag maps and the child imports of every template. */
+	const regenerateAll = (logger) => {
+		const before = new Map(existing().flatMap(listHtml).map((f) => [`${f}.ts`, read(`${f}.ts`)]));
 		try {
-			generateAll(dir, generate);
+			generateDirs(existing(), generate);
 		} catch (e) {
 			if (e instanceof CodegenError) logger.error(e.message);
 			else throw e;
 		}
-		defsByDir.set(dir, scanDefines(dir));
+		defs = scanDefines(existing());
 		for (const [out, content] of before) {
 			const now = read(out);
 			if (now !== null && now !== content) shown.set(out, now);
@@ -89,11 +84,14 @@ 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 {
-				for (const d of dirs) if (existsSync(d)) generateAll(d, generate);
+				generateDirs(existing(), generate);
 			} catch (e) {
 				if (e instanceof CodegenError) this.error(e.message);
 				throw e;
@@ -105,15 +103,13 @@ function tsDom(opts = {}) {
 			server.watcher.add(dirs);
 			server.watcher.on("add", (f) => {
 				const file = resolve(f);
-				const dir = dirOf(file);
 				if (file.endsWith(".html")) regenerate(file, logger);
-				else if (dir && isSourceTs(file) && read(file)?.includes("define(")) regenerateDir(dir, logger);
+				else if (dirOf(file) && isSourceTs(file) && read(file)?.includes("define(")) regenerateAll(logger);
 			});
 			server.watcher.on("unlink", (f) => {
 				const file = resolve(f);
-				const dir = dirOf(file);
 				if (file.endsWith(".html")) removeGenerated(file);
-				else if (dir && isDefineFile(file)) regenerateDir(dir, logger);
+				else if (dirOf(file) && isDefineFile(file)) regenerateAll(logger);
 			});
 		},
 		handleHotUpdate(ctx) {
@@ -130,9 +126,8 @@ function tsDom(opts = {}) {
 				if (regenerate(file, logger)) reload(ctx.server, `${file}.ts`);
 				return [];
 			}
-			const dir = dirOf(file);
-			if (!dir || !isSourceTs(file)) return;
-			if (read(file)?.includes("define(") || isDefineFile(file)) regenerateDir(dir, logger);
+			if (!dirOf(file) || !isSourceTs(file)) return;
+			if (read(file)?.includes("define(") || isDefineFile(file)) regenerateAll(logger);
 		}
 	};
 }

package/llms.txt

@@ -79,7 +79,7 @@ define("my-counter", MyCounter);
 - `data-each` is never nested: a list inside an item is the item component's own `data-each`.
 
 ## Rules for agents
-- Skills: `npx ts-dom skills` lists the task procedures shipped with the package (`nativele-core` for building components, `nativele-react`, `nativele-vue`, `nativele-svelte` and `nativele-angular` for those frameworks, `nativele-vite` for Vite, `nativele-integration` for other frameworks, `nativele-state-management`, `nativele-testing`, `nativele-tanstack-query`, `nativele-zod` and `nativele-tailwind` for those tools, ...), each with verified versions; `npx ts-dom skills <name>` prints one, `npx ts-dom skills add <name>` copies it into `.claude/skills/` or `.agents/skills/`, and `npx ts-dom doctor` suggests the ones that match the project's dependencies.
+- Skills: `npx ts-dom skills` lists the task procedures shipped with the package (`nativele-core` for building components, `nativele-react`, `nativele-vue`, `nativele-svelte` and `nativele-angular` for those frameworks, `nativele-vite` for Vite, `nativele-integration` for other frameworks, `nativele-state-management`, `nativele-testing`, `nativele-tanstack-query`, `nativele-zod` and `nativele-tailwind` for those tools, `nativele-architecture` for laying out an app with several pages, ...), each with verified versions; `npx ts-dom skills <name>` prints one, `npx ts-dom skills add <name>` copies it into `.claude/skills/` or `.agents/skills/`, and `npx ts-dom doctor` suggests the ones that match the project's dependencies.
 - `npx ts-dom rules --explain=<id>` (or `rules --json`) explains any rule id from a diagnostic: why it exists, a wrong example and the fix.
 - Markup well-formedness is a formatter's job: `oxfmt --check` reports misnested tags that the library's parser would silently repair. Generate with `--whitespace=collapse` when a formatter is used.
 - If checks behave oddly (no types, a template not found), run `npx ts-dom doctor --json` first: it reports tsconfig, import path, runtime, generated file and plugin problems with a `Fix:` each.
@@ -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), [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.2",
+  "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.
@@ -135,4 +135,5 @@ Otherwise the maintainers send the gaps back to the contributor as review commen
 | `nativele-tanstack-query` | Experimental | available | `@tanstack/query-core` observers through `bind`: loading and error states, keys from props, mutations |
 | `nativele-zod` | Experimental | available | form validation with Zod or Valibot: per-field messages, nested and array fields, `aria-invalid` |
 | `nativele-tailwind` | Experimental | available | Tailwind CSS v4 in templates: source detection, `shadow: true` with adopted style sheets, `<style scoped>` layers |
+| `nativele-architecture` | Official | available | app layout: feature folders, shared components and stores, pages as custom elements mounted by a router (Navigation API or universal-router), lazy pages, one scanned folder, unit/browser/end-to-end split |
 | Other libraries | Experimental or Community | open for contributions | |

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.