@nativele/ts-dom 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -10,6 +10,24 @@ 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.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.
+
+### Guide and Skill
+
+- New guide `docs/architecture.md`:
+  - feature folders with their components, stores and tests, and a shared folder whose components' interface is their props and events;
+  - pages as custom elements mounted by an external router: route params as props, leaving a page, lazy page modules;
+  - where state lives at each level, and the split between unit, real-browser and end-to-end tests;
+  - one scanned folder for the generated files, checks and tsconfig.
+- New `nativele-architecture` (Official): the procedure for starting a multi-page Nativele app or restructuring one into this layout. The recommended router uses the Navigation API and `URLPattern` with no dependency; universal-router is the alternative. It covers the abort check after a lazy `import()` and the test split.
+- Its example, a project tracker with lazy pages, shared components, feature and app-wide stores, unit, browser and end-to-end tests, runs in CI.
+
+### Fixes
+
+- When several folders are scanned (`ts-dom gen a b`, `ts-dom check a b`, `ts-dom doctor a b`, the Vite plugin's `dirs`), each folder was generated on its own, so a template in one folder that used a component defined in another got no import of it and the build silently left the component out, while the types still passed. The folders now share their `define()` calls: the template imports the child by its relative path, `gen --check` and `doctor` agree with what `gen` writes, and the Vite plugin keeps the imports across folders when a template is saved or a `define()` is added or removed. A tag defined with different classes in two scanned folders is now reported as `duplicate-define` at the second `define()` call.
+
 ## 0.5.2
 
 Skills for the libraries a Nativele app most often sits next to: state stores, testing, data fetching, form validation and Tailwind CSS. Each was accepted through agent trials, and the trials found two bugs in the library, fixed here.

package/README.md

@@ -65,6 +65,7 @@ npx ts-dom skills add nativele-core    # copy it into .claude/skills/ (when the
 | `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-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-state-management` | where state lives; `createStore`, and Zustand, Redux Toolkit or nanostores through `bind` |
@@ -228,6 +229,7 @@ The full guide is in English:
 - [Components and data flow: state, props, derive, events, composition, stores](https://github.com/Pixmi/nativele/blob/main/docs/components.md)
 - [Recipes: loading and error states, store data, filtered lists, dialogs, form validation](https://github.com/Pixmi/nativele/blob/main/docs/recipes.md)
 - [Lists: lists of components with `items =`, plain lists with `replace()`, moving items](https://github.com/Pixmi/nativele/blob/main/docs/lists.md)
+- [Architecture: feature folders, shared components and stores, pages mounted by a router, where state lives, testing strategy](https://github.com/Pixmi/nativele/blob/main/docs/architecture.md)
 - [Setup, checks and lint: installation, Vite, oxlint, `ts-dom check`, `ts-dom doctor`, accessibility](https://github.com/Pixmi/nativele/blob/main/docs/tooling.md)
 - [Performance: the large list benchmark](https://github.com/Pixmi/nativele/blob/main/docs/performance.md)
 - [Design: principles, deliberate decisions, limitations](https://github.com/Pixmi/nativele/blob/main/docs/design.md)

package/README.zh-TW.md

@@ -65,6 +65,7 @@ npx ts-dom skills add nativele-core    # 複製到 .claude/skills/（專案有 .
 | `nativele-vue` | 在 Vue 3 中使用 Nativele 元件：props、事件、`v-model`、slot、`<KeepAlive>`、範本型別 |
 | `nativele-svelte` | 在 Svelte 5 中使用 Nativele 元件：props、事件、slot、範本型別 |
 | `nativele-angular` | 在 Angular 中使用 Nativele 元件：綁定、變更偵測、建置流程、內容投影（Experimental） |
+| `nativele-architecture` | 應用的結構：功能資料夾、共用元件與 store、由 router 掛載的頁面、延遲載入、測試分層 |
 | `nativele-vite` | 在 Vite 應用中使用 Nativele：外掛與 `root`、多頁建置、熱更新 |
 | `nativele-integration` | 在沒有專屬 Skill 的框架（Preact、Solid 等）中使用 Nativele 元件：property、事件、slot、生命週期、範本型別（Experimental） |
 | `nativele-state-management` | 狀態放在哪裡；`createStore`，以及透過 `bind` 接上 Zustand、Redux Toolkit、nanostores |
@@ -228,6 +229,7 @@ define("task-board", TaskBoard);
 - [Components and data flow: state, props, derive, events, composition, stores](https://github.com/Pixmi/nativele/blob/main/docs/components.md)
 - [Recipes: loading and error states, store data, filtered lists, dialogs, form validation](https://github.com/Pixmi/nativele/blob/main/docs/recipes.md)
 - [Lists: lists of components with `items =`, plain lists with `replace()`, moving items](https://github.com/Pixmi/nativele/blob/main/docs/lists.md)
+- [Architecture: feature folders, shared components and stores, pages mounted by a router, where state lives, testing strategy](https://github.com/Pixmi/nativele/blob/main/docs/architecture.md)
 - [Setup, checks and lint: installation, Vite, oxlint, `ts-dom check`, `ts-dom doctor`, accessibility](https://github.com/Pixmi/nativele/blob/main/docs/tooling.md)
 - [Performance: the large list benchmark](https://github.com/Pixmi/nativele/blob/main/docs/performance.md)
 - [Design: principles, deliberate decisions, limitations](https://github.com/Pixmi/nativele/blob/main/docs/design.md)

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

@@ -1,6 +1,6 @@
 import { i as RESERVED_NAMES, n as IDENT, r as holeName, t as HOLE_ANY } from "./holes-DTBtTZF_.mjs";
 import { existsSync, readFileSync, readdirSync, statSync, unlinkSync, watch, writeFileSync } from "node:fs";
-import { dirname, join, relative, sep } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { parseFragment } from "parse5";
 // src/lib/codegen.ts
 /** Every diagnostic that `ts-dom gen` can report while analyzing a template. */
@@ -29,7 +29,7 @@ const CODEGEN_RULES = {
 	"forbidden-tag": "<script> cannot be in a template (it would run code)",
 	"forbidden-attribute": "on* event attributes and srcdoc cannot be in a template (they run code or are blocked by Trusted Types)",
 	"unsafe-url": "href / src / action / formaction cannot start with javascript:",
-	"duplicate-define": "a custom element tag can be defined only once per scanned directory"
+	"duplicate-define": "a custom element tag can be defined only once across the scanned directories"
 };
 const RESERVED_ELEMENT_NAMES = /* @__PURE__ */ new Set([
 	"annotation-xml",
@@ -406,13 +406,15 @@ function nonCodeRanges(code) {
 	return out;
 }
 /**
-* Scan a directory for every `define("my-tag", MyClass)` call.
+* Scan one or more directories for every `define("my-tag", MyClass)` call; a file under two of them is read once.
 * Calls that only appear inside a string or a comment (for example sample code in a test or in documentation) are ignored.
 */
-function scanDefines(dir) {
+function scanDefines(dirs) {
 	const defs = [];
 	const re = /\bdefine\(\s*(["'])([a-z][a-z0-9]*(?:-[a-z0-9]+)+)\1\s*,\s*([A-Za-z_$][\w$]*)\s*\)/g;
-	for (const file of listTs(dir)) {
+	const files = /* @__PURE__ */ new Map();
+	for (const dir of typeof dirs === "string" ? [dirs] : dirs) for (const f of listTs(dir)) if (!files.has(resolve(f))) files.set(resolve(f), f);
+	for (const file of files.values()) {
 		const code = readFileSync(file, "utf8");
 		const skip = nonCodeRanges(code);
 		const inCode = (pos) => !skip.some(([a, b]) => pos >= a && pos < b);
@@ -422,12 +424,15 @@ function scanDefines(dir) {
 			const [, , tag, className] = m;
 			const named = has(new RegExp(`export\\s+class\\s+${className}\\b`, "g")) || has(new RegExp(`export\\s*\\{[^}]*\\b${className}\\b[^}]*\\}`, "g"));
 			const isDefault = has(new RegExp(`export\\s+default\\s+class\\s+${className}\\b`, "g"));
+			const before = code.slice(0, m.index);
 			defs.push({
 				tag,
 				className,
 				file,
 				exported: named || isDefault,
-				isDefault
+				isDefault,
+				line: before.split("\n").length,
+				col: m.index - before.lastIndexOf("\n")
 			});
 		}
 	}
@@ -437,6 +442,30 @@ const relImport = (fromDir, file) => {
 	const r = relative(fromDir, file).split(sep).join("/").replace(/\.ts$/, ".js");
 	return r.startsWith(".") ? r : `./${r}`;
 };
+/**
+* A tag that two of the directories define with different classes, reported at its second define() call.
+* A tag defined twice within one directory is reported by `generateTags` instead.
+*/
+function crossDirDuplicates(dirs) {
+	const byTag = /* @__PURE__ */ new Map();
+	for (const d of scanDefines(dirs)) byTag.set(d.tag, [...byTag.get(d.tag) ?? [], d]);
+	const inside = (dir, file) => resolve(file).startsWith(resolve(dir) + sep);
+	const out = [];
+	for (const [tag, defs] of byTag) {
+		const [first, second] = defs;
+		if (defs.length < 2 || dirs.some((dir) => defs.every((d) => inside(dir, d.file)))) continue;
+		const at = (d) => `${relative(process.cwd(), d.file)}:${d.line ?? 1}`;
+		out.push({
+			file: second.file,
+			line: second.line ?? 1,
+			col: second.col ?? 1,
+			severity: "error",
+			rule: "duplicate-define",
+			message: `The tag <${tag}> is defined more than once in the scanned folders (${at(first)} and ${at(second)}), so the second define() fails at runtime. Fix: each custom element name can be defined only once; rename one of them.`
+		});
+	}
+	return out;
+}
 /** Scan `define("my-tag", MyClass)` calls and return the components a type can be generated for (the class must be exported). */
 function scanTags(dir) {
 	return scanDefines(dir).filter((d) => d.exported).map((d) => ({
@@ -489,10 +518,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`.
 */
-function planGenerated(dir, options = {}) {
+function planGenerated(dir, options = {}, defs = scanDefines(dir)) {
 	const files = /* @__PURE__ */ new Map();
 	const errors = [];
-	const defs = scanDefines(dir);
 	for (const f of listHtml(dir)) {
 		if (!isSelected(dir, f, options)) continue;
 		try {
@@ -517,12 +545,12 @@ function planGenerated(dir, options = {}) {
 	};
 }
 /** Generated files under `dir` that differ from what `ts-dom gen` would write now. */
-function staleGenerated(dir, options = {}) {
-	return checkGenerated(dir, options).stale;
+function staleGenerated(dir, options = {}, defs) {
+	return checkGenerated(dir, options, defs).stale;
 }
 /** `staleGenerated`, plus the errors that would make `ts-dom gen` fail (template diagnostics, a tag defined twice). */
-function checkGenerated(dir, options = {}) {
-	const plan = planGenerated(dir, options);
+function checkGenerated(dir, options = {}, defs) {
+	const plan = planGenerated(dir, options, defs);
 	const out = [];
 	for (const [file, next] of plan.files) {
 		const prev = existsSync(file) ? readFileSync(file, "utf8") : null;
@@ -555,11 +583,13 @@ function listGenerated(dir) {
 	}
 	return out;
 }
-/** Generate every `x.html.ts` (and the tag map) under a directory; collects all errors and throws them together. */
-function generateAll(dir, options = {}) {
+/**
+* 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)) {
 	const written = [];
 	const errors = [];
-	const defs = scanDefines(dir);
 	for (const f of listHtml(dir)) {
 		if (!isSelected(dir, f, options)) continue;
 		try {
@@ -580,17 +610,31 @@ function generateAll(dir, options = {}) {
 	if (errors.length) throw new CodegenError(errors.join("\n"));
 	return written;
 }
+/** `generateAll` for every directory, with the define() calls of all of them: a template imports a child component defined in another directory. */
+function generateDirs(dirs, options = {}) {
+	const defs = scanDefines(dirs);
+	const written = [];
+	const errors = [];
+	for (const dir of dirs) try {
+		written.push(...generateAll(dir, options, defs));
+	} catch (e) {
+		if (e instanceof CodegenError) errors.push(e.message);
+		else throw e;
+	}
+	for (const d of crossDirDuplicates(dirs)) errors.push(formatDiagnostics(d.file, [d]));
+	if (errors.length) throw new CodegenError(errors.join("\n"));
+	return written;
+}
 /** Watch .html (and define() calls in .ts) under the directories and regenerate; returns a stop function. Errors go to onError and never stop the watcher. */
 function watchAll(dirs, opts = {}) {
 	const timers = /* @__PURE__ */ new Map();
 	const watchers = dirs.map((dir) => watch(dir, { recursive: true }, (_event, name) => {
 		if (!name || name.includes("node_modules")) return;
 		if (name.endsWith(".ts") && !name.endsWith(".html.ts") && !name.endsWith(".d.ts") && !name.endsWith(TAGS_FILE)) {
-			const key = `${dir}:tags`;
-			clearTimeout(timers.get(key));
-			timers.set(key, setTimeout(() => {
+			clearTimeout(timers.get("tags"));
+			timers.set("tags", setTimeout(() => {
 				try {
-					for (const f of generateAll(dir, opts)) opts.onGenerate?.(f);
+					for (const f of generateDirs(dirs, opts)) opts.onGenerate?.(f);
 				} catch (e) {
 					if (e instanceof CodegenError) opts.onError?.(e.message);
 					else throw e;
@@ -604,7 +648,7 @@ function watchAll(dirs, opts = {}) {
 		timers.set(file, setTimeout(() => {
 			try {
 				if (!existsSync(file) || !isSelected(dir, file, opts) || isFullPage(readFileSync(file, "utf8"))) return;
-				opts.onGenerate?.(generateFile(file, opts, dir));
+				opts.onGenerate?.(generateFile(file, opts, scanDefines(dirs)));
 			} catch (e) {
 				if (e instanceof CodegenError) opts.onError?.(e.message);
 				else throw e;
@@ -814,4 +858,4 @@ function checkA11y(html, ignore = []) {
 	for (const { id, el } of labelFor) if (!ids.has(id)) report("label-for", el, `<label for="${id}"> points to an id that does not exist in this template. Fix: add id="${id}" to the control, or wrap the control in the label.`);
 	return out.sort((a, b) => a.line - b.line || a.col - b.col);
 }
-export { watchAll as _, analyze as a, generateAll as c, isSelected as d, listHtml as f, staleGenerated as g, scanDefines as h, CodegenError as i, generateFile as l, renderTags as m, checkA11y as n, checkGenerated as o, listTs as p, CODEGEN_RULES as r, formatDiagnostics as s, A11Y_RULES as t, isFullPage as u };
+export { staleGenerated as _, analyze as a, formatDiagnostics as c, isFullPage as d, isSelected as f, scanDefines as g, renderTags as h, CodegenError as i, generateDirs as l, listTs as m, checkA11y as n, checkGenerated as o, listHtml as p, CODEGEN_RULES as r, crossDirDuplicates as s, A11Y_RULES as t, generateFile as u, watchAll as v };

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/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-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 { createRequire } from "node:module";
 import { cpSync, existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
@@ -272,16 +272,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)) 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;
 	}
@@ -522,6 +528,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 +537,7 @@ 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)) 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 viteConfig = [
 		"vite.config.ts",
@@ -1355,9 +1362,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));
 		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 +1381,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-qEPgmmMa.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-Bw-8ZIAK.mjs";
 import { readFileSync } from "node:fs";
 import { basename, dirname, relative } from "node:path";
 // src/lib/lint.ts

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-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 { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 // src/lib/oxlint-plugin.ts

package/dist/vite-plugin.mjs

@@ -1,4 +1,4 @@
-import { c as generateAll, d as isSelected, f as listHtml, h as scanDefines, i as CodegenError, l as generateFile, n as checkA11y, s as formatDiagnostics, u as isFullPage } from "./a11y-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-Bw-8ZIAK.mjs";
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
 import { resolve, sep } from "node:path";
 // src/lib/vite-plugin.ts
@@ -19,16 +19,10 @@ function tsDom(opts = {}) {
 	const a11y = opts.a11y === true ? {} : opts.a11y || null;
 	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 +42,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 +51,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);
@@ -90,10 +84,11 @@ function tsDom(opts = {}) {
 		enforce: "pre",
 		configResolved(config) {
 			dirs = (opts.dirs ?? ["src"]).map((d) => resolve(config.root, d));
+			defs = void 0;
 		},
 		buildStart() {
 			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 +100,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 +123,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.
@@ -104,5 +104,5 @@ In a browser without a bundler map the bare name once: `<script type="importmap"
 
 ## 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), [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.3",
   "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

@@ -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-architecture/SKILL.md

@@ -0,0 +1,541 @@
+---
+name: nativele-architecture
+description: "Lay out an app built with Nativele that has several pages: feature folders with their components, stores and tests, shared components and app-wide stores, pages as custom elements that a router mounts (the Navigation API with URLPattern, or universal-router), lazy-loaded page modules, one scanned folder for the generated files, and which behavior goes to unit, real-browser and end-to-end tests. Use when starting such an app or restructuring one, or when a project depends on @nativele/ts-dom and universal-router."
+metadata:
+  tier: official
+  nativele: ">=0.5.3 <0.6.0"
+  verified: "2026-11-05"
+  tools: "vite@8.3.6 typescript@7.0.2 vitest@5.1.0 happy-dom@21.0.4 @vitest/browser-playwright@5.1.0 playwright@1.64.1 @playwright/test@1.64.1 create-vite@9.3.4 universal-router@10.0.3"
+  author: "Nativele maintainers"
+  detects: "universal-router"
+---
+
+# Nativele app architecture
+
+## When to use
+
+- A Vite app that already uses Nativele (`@nativele/ts-dom`), set up as in `nativele-vite` (started with `npm create vite@latest -- --template vanilla-ts`), that has or will have several pages: you are starting its structure, or restructuring a flat `src/nv/` folder into features.
+- Signals: more than one page or URL, a component folder that has grown past a screen of files, the same component or store wanted by two parts of the app, a router dependency such as `universal-router`.
+- The reasoning behind every step (why features, where state lives, why one scanned folder) is in the architecture guide: https://github.com/Pixmi/nativele/blob/main/docs/architecture.md. This Skill is the procedure.
+- Not for writing components (`nativele-core`), setting up Vite (`nativele-vite`), choosing or connecting a state library (`nativele-state-management`), or writing the tests themselves (`nativele-testing`); this Skill uses all four and links to them.
+- Not for an app whose pages are rendered by a UI framework (React, Vue): there the framework's router mounts the pages; see that framework's Skill.
+
+`ts-dom doctor` suggests this Skill when `universal-router` is a dependency. The recommended router needs no dependency, so there is nothing else in `package.json` that tells a multi-page app from a single widget; detecting `@nativele/ts-dom` itself would suggest it to every project, which `nativele-core` already covers.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.5.3 |
+| vite | 8.3.6 |
+| typescript | 7.0.2 |
+| create-vite (`vanilla-ts` template, the starting point) | 9.3.4 |
+| vitest | 5.1.0 |
+| happy-dom | 21.0.4 |
+| @vitest/browser-playwright | 5.1.0 |
+| playwright | 1.64.1 (drives the installed Chrome; no browser is downloaded) |
+| @playwright/test | 1.64.1 |
+| universal-router | 10.0.3 (checked by hand with the example's tests, see step 5; the example project does not run it) |
+
+Verified on 2026-11-05 with Node 24 and Google Chrome 148, with the example project in the Nativele repository (https://github.com/Pixmi/nativele/tree/main/skills/nativele-architecture/example; it is not in the npm package), which CI runs again when the example or the library changes and once a month. The router relies on the Navigation API and `URLPattern`, verified in Chrome only. With another major version of any tool above, treat every step as unverified.
+
+## Set-up
+
+1. **Make the folders** under `src/`:
+
+   ```
+   src/main.ts                 # imports the shell, starts the router
+   src/app/                    # the router, the shell, stores of the app itself
+   src/shared/                 # components and stores used by more than one feature
+   src/shared/stores/
+   src/features/<feature>/     # each feature's pages, components, store and tests
+   e2e/                        # tests of the built app
+   ```
+
+   Restructuring: move each page component and the components only it uses into its feature folder, each component used by two features into `src/shared/`, and the header or navigation into `src/app/`. Templates need no change (the import of a child component is generated); fix the relative `import` paths in the `.ts` files, and `ts-dom check src` (step 2) reports the ones you missed as `TS2307`. A feature never imports another feature: move what both need to `src/shared/`.
+
+2. **Scan one folder, `src`, everywhere.** In `vite.config.ts`, `tsDom({ dirs: ["src"] })`; in every script and command, `ts-dom check src` and `ts-dom doctor src`. One folder gives one `ts-dom-tags.ts` and one argument for every command (limitation 1). When the app used another folder before (`src/nv` from `nativele-vite`), delete the `ts-dom-tags.ts` left in it, and the folder itself once its components have moved (Troubleshooting).
+
+3. **Set `tsconfig.json`'s `include`** to `["src", "e2e"]`: `src` covers the app, the tests next to the code and `ts-dom-tags.ts`, and `e2e` the end-to-end specs, so `ts-dom check src` type-checks all of them. Keep `"strict": true` from `nativele-vite`.
+
+4. **Put the shell and the outlet in `index.html`**, and start the router from `src/main.ts`:
+
+   ```html
+   <app-nav></app-nav>
+   <main id="outlet"></main>
+   <script type="module" src="/src/main.ts"></script>
+   ```
+
+   ```ts
+   // src/main.ts
+   import "./app/app-nav.ts";
+   import { startRouter } from "./app/router.ts";
+
+   void startRouter(document.querySelector("#outlet")!);
+   ```
+
+5. **Add the router**, `src/app/router.ts` from the Example, with one `page(path, tag, () => import(module), params => props)` per route. Keep three things from it: the page module is imported before `document.createElement(tag)`, the route params are set as props, and `if (signal?.aborted) return;` comes after the import (limitation 3). If the app already has a router, keep it and call the same `mount()` from its route handler. With `universal-router` 10 (`npm i universal-router@10.0.3`) and the History API, keep the imports, `Tag`, `Params` and `mount()`, and replace `Route`, `page()`, `routes`, `loaded()`, `show()` and `startRouter()` with:
+
+   ```ts
+   import UniversalRouter from "universal-router";
+
+   interface Match {
+     tag: Tag;
+     load: () => Promise<unknown>;
+     props: object;
+   }
+
+   function page<K extends Tag>(path: string, tag: K, load: () => Promise<unknown>, props: (params: Params) => Partial<HTMLElementTagNameMap[K]> = () => ({})) {
+     return { path, action: ({ params }: { params: Record<string, unknown> }): Match => ({ tag, load, props: props(params as Params) }) };
+   }
+
+   const router = new UniversalRouter<Match | null>(
+     [
+       page("/", "projects-page", () => import("../features/projects/projects-page.ts")),
+       page("/projects/:id", "project-page", () => import("../features/projects/project-page.ts"), (p) => ({ projectId: p.id ?? "" })),
+       page("/settings", "settings-page", () => import("../features/settings/settings-page.ts")),
+     ],
+     { errorHandler: () => null },
+   );
+
+   async function loaded(match: Match): Promise<boolean> {
+     try {
+       await match.load();
+       return true;
+     } catch {
+       return false;
+     }
+   }
+
+   export async function show(outlet: Element, url: string, signal?: AbortSignal): Promise<void> {
+     const path = new URL(url).pathname;
+     const match = await router.resolve(path);
+     const ok = match != null && (await loaded(match));
+     if (signal?.aborted) return;
+     if (match && ok) mount(outlet, match.tag, match.props);
+     else if (match) mount(outlet, "route-message", { heading: "This page could not be loaded", detail: "Check the connection and reload the page." });
+     else mount(outlet, "route-message", { heading: "Page not found", detail: `Nothing lives at ${path}.` });
+     currentPath.set(path);
+   }
+
+   let pending: AbortController | undefined;
+
+   export function startRouter(outlet: Element): Promise<void> {
+     const go = () => {
+       pending?.abort();
+       pending = new AbortController();
+       return show(outlet, location.href, pending.signal);
+     };
+     document.addEventListener("click", (e) => {
+       if (e.defaultPrevented || e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+       const a = e.target instanceof Element ? e.target.closest("a") : null;
+       if (!a || a.target || a.hasAttribute("download") || a.origin !== location.origin) return;
+       e.preventDefault();
+       history.pushState(null, "", a.href);
+       void go();
+     });
+     addEventListener("popstate", () => void go());
+     return go();
+   }
+   ```
+
+   `router.resolve()` returns `undefined` when an action returns nothing, so test the match with `!= null`. With this router, the example's unit tests and its end-to-end tests pass except the one for a browser without the Navigation API (links are always handled by the click handler) and the one that calls `navigation.navigate()`, which passes when it clicks a link instead; its browser router tests use the Navigation API and do not apply.
+
+6. **Write each page as a component** in its feature folder: route params arrive as string props (`props: { projectId: "" }`), the page shows what an unknown id means, and it binds its stores in `connected()`. Everything a page must keep after the user leaves goes into a store: leaving removes the page, which ends its `bind` subscriptions, and coming back creates a new element.
+
+7. **Put state at the lowest level that holds it** (the table in the guide): a component's `state` for what one component shows; a feature store (`src/features/<feature>/<feature>-store.ts`: `createStore` plus its actions as exported functions and a `seed...()` function that returns fresh initial data, for tests) for what a feature's pages share; an app-wide store in `src/shared/stores/` for what the shell or several features read. For an existing Zustand, Redux or nanostores store, follow `nativele-state-management`.
+
+8. **Make shared components take props and emit events** only; they never import a feature or a feature store. The feature decides what an event means (`text-entry` emits `entry-submit`; the projects page adds a project, the project page a task).
+
+9. **Add the tests** as in `nativele-testing`, with the patterns for tests next to the code:
+
+   ```sh
+   npm i -D vitest@5.1.0 happy-dom@21.0.4 @vitest/browser-playwright@5.1.0 playwright@1.64.1 @playwright/test@1.64.1
+   ```
+
+   - `src/**/*.test.ts` in happy-dom: store actions, components with props, events and stores, pages given their params as props, and the route table through `show()`.
+   - `src/**/*.browser.test.ts` in Chrome: the router with the Navigation API, and moves and focus in reordered lists.
+   - `e2e/*.spec.ts` with Playwright Test against `vite preview` of the build: deep links, navigation, back and forward, lazy chunks, data across pages.
+
+10. **Set the scripts**:
+
+    ```sh
+    npm pkg set scripts.build="ts-dom check src && vite build"
+    npm pkg set scripts.test="vitest run --project unit"
+    npm pkg set scripts.test:browser="vitest run --project browser"
+    npm pkg set scripts.test:e2e="playwright test"
+    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`.
+
+## Example
+
+The example project is a project tracker: a projects list (`/`), a project page with its tasks (`/projects/:id`) and a settings page (`/settings`).
+
+```
+index.html  package.json  tsconfig.json  vite.config.ts  playwright.config.ts
+src/main.ts
+src/app/router.ts  src/app/current-path.ts  src/app/app-nav.*  src/app/route-message.*  src/app/*.test.ts  src/app/router.browser.test.ts
+src/shared/text-entry.*  src/shared/progress-meter.*  src/shared/text-entry.test.ts  src/shared/stores/preferences.ts
+src/features/projects/projects-store.ts  projects-page.*  project-page.*  project-card.*  task-row.*  *.test.ts  project-page.browser.test.ts
+src/features/settings/settings-page.*  settings-page.test.ts
+e2e/app.spec.ts
+```
+
+The router (Navigation API and `URLPattern`, no dependency):
+
+```ts
+// src/app/router.ts
+import { currentPath } from "./current-path.ts";
+import "./route-message.ts";
+
+type Tag = keyof HTMLElementTagNameMap;
+type Params = Record<string, string | undefined>;
+
+interface Route {
+  pattern: URLPattern;
+  tag: Tag;
+  load: () => Promise<unknown>;
+  props: (params: Params) => object;
+}
+
+function page<K extends Tag>(
+  pathname: string,
+  tag: K,
+  load: () => Promise<unknown>,
+  props: (params: Params) => Partial<HTMLElementTagNameMap[K]> = () => ({}),
+): Route {
+  return { pattern: new URLPattern({ pathname }), tag, load, props };
+}
+
+const routes: Route[] = [
+  page("/", "projects-page", () => import("../features/projects/projects-page.ts")),
+  page("/projects/:id", "project-page", () => import("../features/projects/project-page.ts"), (p) => ({ projectId: p.id ?? "" })),
+  page("/settings", "settings-page", () => import("../features/settings/settings-page.ts")),
+];
+
+function mount<K extends Tag>(outlet: Element, tag: K, props: Partial<HTMLElementTagNameMap[K]>): void {
+  const el = document.createElement(tag);
+  Object.assign(el, props);
+  outlet.replaceChildren(el);
+}
+
+async function loaded(route: Route): Promise<boolean> {
+  try {
+    await route.load();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function show(outlet: Element, url: string, signal?: AbortSignal): Promise<void> {
+  const route = routes.find((r) => r.pattern.test(url));
+  const ok = route !== undefined && (await loaded(route));
+  if (signal?.aborted) return;
+  const path = new URL(url).pathname;
+  if (route && ok) mount(outlet, route.tag, route.props(route.pattern.exec(url)?.pathname.groups ?? {}));
+  else if (route) mount(outlet, "route-message", { heading: "This page could not be loaded", detail: "Check the connection and reload the page." });
+  else mount(outlet, "route-message", { heading: "Page not found", detail: `Nothing lives at ${path}.` });
+  currentPath.set(path);
+}
+
+export function startRouter(outlet: Element): Promise<void> {
+  if ("navigation" in window) {
+    navigation.addEventListener("navigate", (e) => {
+      if (!e.canIntercept || e.hashChange || e.downloadRequest !== null || e.formData !== null) return;
+      e.intercept({ handler: () => show(outlet, e.destination.url, e.signal) });
+    });
+  }
+  return show(outlet, location.href);
+}
+```
+
+```ts
+// src/app/current-path.ts: an app store the router sets and the shell binds to mark the current link
+import { createStore } from "@nativele/ts-dom";
+
+export const currentPath = createStore(location.pathname);
+```
+
+`route-message` is a component with the props `heading` and `detail`. A wrong tag or prop in the route table is a `tsc` error, because the types come from `ts-dom-tags.ts`: `TS2345: Argument of type '"projects-pag"' is not assignable to parameter of type 'keyof HTMLElementTagNameMap'`, or `Type 'number' is not assignable to type 'string'` for `projectId`.
+
+A feature store and a page of that feature:
+
+```ts
+// src/features/projects/projects-store.ts (abridged: the example adds addProject and more seed data)
+import { createStore } from "@nativele/ts-dom";
+
+export interface Project { id: string; name: string }
+export interface Task { id: string; projectId: string; title: string; done: boolean }
+export interface ProjectsState { projects: readonly Project[]; tasks: readonly Task[]; nextId: number }
+
+export function seedProjects(): ProjectsState {
+  return { projects: [{ id: "p1", name: "Website" }], tasks: [{ id: "t1", projectId: "p1", title: "Publish", done: false }], nextId: 2 };
+}
+
+export const projects = createStore<ProjectsState>(seedProjects());
+
+export function addTask(projectId: string, title: string): void {
+  projects.set((s) => ({ ...s, tasks: [...s.tasks, { id: `t${s.nextId}`, projectId, title, done: false }], nextId: s.nextId + 1 }));
+}
+
+export function toggleTask(id: string): void {
+  projects.set((s) => ({ ...s, tasks: s.tasks.map((t) => (t.id === id ? { ...t, done: !t.done } : t)) }));
+}
+
+export function tasksOf(s: ProjectsState, projectId: string): readonly Task[] {
+  return s.tasks.filter((t) => t.projectId === projectId);
+}
+```
+
+```html
+<!-- src/features/projects/project-page.html -->
+<p><a href="/">All projects</a></p>
+<section data-if="found">
+  <h1>{{ name }}</h1>
+  <progress-meter data-ref="meter"></progress-meter>
+  <text-entry label="New task" action="Add task" data-on-entry-submit="onAdd"></text-entry>
+  <ul>
+    <template data-each="tasks" data-key="id" data-prop="task">
+      <task-row role="listitem" data-on-task-toggle="onToggle"></task-row>
+    </template>
+  </ul>
+  <p data-if="someHidden">{{ hiddenCount }} done tasks are hidden.</p>
+</section>
+<p data-if="missing">There is no project with this id.</p>
+```
+
+```ts
+// src/features/projects/project-page.ts
+import { Component, define } from "@nativele/ts-dom";
+import type { DeepReadonly, EmitEvent, EventHit } from "@nativele/ts-dom";
+import { preferences } from "../../shared/stores/preferences.ts";
+import type { TextEntry } from "../../shared/text-entry.ts";
+import { addTask, projects, tasksOf, toggleTask, type ProjectsState, type Task } from "./projects-store.ts";
+import tpl from "./project-page.html.js";
+
+type View = DeepReadonly<{ projectId: string; data: ProjectsState; showDone: boolean }>;
+
+const project = (v: View) => v.data.projects.find((p) => p.id === v.projectId);
+const all = (v: View) => tasksOf(v.data, v.projectId);
+const visible = (v: View) => all(v).filter((t) => v.showDone || !t.done);
+
+export class ProjectPage extends Component(tpl, {
+  props: { projectId: "" },
+  state: { data: { projects: [], tasks: [], nextId: 0 } as ProjectsState, showDone: true },
+  derive: {
+    found: (v) => project(v) !== undefined,
+    missing: (v) => project(v) === undefined,
+    name: (v) => project(v)?.name ?? "",
+    tasks: (v) => [...visible(v)].sort((a, b) => Number(a.done) - Number(b.done)),
+    doneCount: (v) => all(v).filter((t) => t.done).length,
+    totalCount: (v) => all(v).length,
+    hiddenCount: (v) => all(v).length - visible(v).length,
+    someHidden: (v) => all(v).length > visible(v).length,
+  },
+}) {
+  override connected(): void {
+    this.bind(projects, (data) => this.set({ data }));
+    this.bind(preferences, (p) => this.set({ showDone: p.showDone }));
+  }
+
+  onAdd(e: Event): void {
+    addTask(this.props.projectId, (e as EmitEvent<TextEntry, "entry-submit">).detail.value);
+  }
+
+  onToggle(_e: Event, hit: EventHit<Task, "id">): void {
+    toggleTask(hit.key);
+  }
+
+  override render(
+    view: { tasks: readonly Task[]; doneCount: number; totalCount: number },
+    changed: ReadonlySet<"tasks" | "doneCount" | "totalCount">,
+  ): void {
+    if (changed.has("tasks")) this.lists.tasks.items = view.tasks;
+    if (changed.has("doneCount")) this.refs.meter.done = view.doneCount;
+    if (changed.has("totalCount")) this.refs.meter.total = view.totalCount;
+  }
+}
+define("project-page", ProjectPage);
+```
+
+`preferences` is the app-wide store (`createStore<Preferences>({ userName: "", showDone: true })` in `src/shared/stores/preferences.ts`), written by the settings page and read by the shell and this page. `text-entry` and `progress-meter` come from `src/shared/`; `task-row` is this feature's own item component. The page's template uses their tags, and the generated `project-page.html.ts` imports all three.
+
+The configuration (the browser project and the Playwright config follow `nativele-testing`, with this project's ports):
+
+```ts
+// vite.config.ts
+import { playwright } from "@vitest/browser-playwright";
+import { defineConfig } from "vitest/config";
+import { tsDom } from "@nativele/ts-dom/vite";
+
+const chrome = process.env.CHROME_BIN ?? "/usr/bin/google-chrome";
+
+export default defineConfig({
+  plugins: [tsDom({ dirs: ["src"] })],
+  server: { port: 5481, strictPort: true },
+  preview: { port: 4481, strictPort: true },
+  test: {
+    projects: [
+      {
+        extends: true,
+        test: { name: "unit", include: ["src/**/*.test.ts"], exclude: ["src/**/*.browser.test.ts"], environment: "happy-dom" },
+      },
+      {
+        extends: true,
+        test: {
+          name: "browser",
+          include: ["src/**/*.browser.test.ts"],
+          api: { port: 63481, strictPort: true },
+          browser: {
+            enabled: true,
+            headless: true,
+            provider: playwright({ launchOptions: { executablePath: chrome, args: ["--no-sandbox", "--no-zygote", "--disable-gpu", "--disable-dev-shm-usage"] } }),
+            instances: [{ browser: "chromium" }],
+          },
+        },
+      },
+    ],
+  },
+});
+```
+
+```ts
+// playwright.config.ts: the build comes from npm run build, which verify runs first
+import { defineConfig } from "@playwright/test";
+
+const chrome = process.env.CHROME_BIN ?? "/usr/bin/google-chrome";
+
+export default defineConfig({
+  testDir: "e2e",
+  use: {
+    baseURL: "http://localhost:4481",
+    launchOptions: { executablePath: chrome, args: ["--no-sandbox", "--no-zygote", "--disable-gpu", "--disable-dev-shm-usage"] },
+  },
+  webServer: { command: "npx vite preview", url: "http://localhost:4481" },
+});
+```
+
+One test of each kind:
+
+```ts
+// src/features/projects/project-page.test.ts (happy-dom)
+beforeEach(() => {
+  projects.set(seedProjects());
+  preferences.set(defaultPreferences);
+});
+afterEach(() => document.body.replaceChildren());
+
+test("leaving the page ends its subscriptions: a removed page no longer renders on store changes", () => {
+  const el = document.createElement("project-page");
+  el.projectId = "p1";
+  document.body.append(el);
+  const render = vi.spyOn(ProjectPage.prototype, "render");
+  preferences.set({ ...preferences.get(), showDone: false });
+  expect(render).toHaveBeenCalledTimes(1);
+  render.mockClear();
+  el.remove();
+  projects.set(seedProjects());
+  preferences.set({ ...preferences.get(), showDone: true });
+  expect(render).not.toHaveBeenCalled();
+});
+```
+
+```ts
+// src/app/router.browser.test.ts (Chrome)
+const start = location.href;
+const outlet = document.createElement("main");
+document.body.append(outlet);
+const ready = startRouter(outlet);
+
+afterAll(() => navigation.navigate(start, { history: "replace" }).finished);
+
+test("the Navigation API carries same-document navigations to the router", async () => {
+  await ready;
+  await navigation.navigate("/settings").finished;
+  expect(outlet.firstElementChild?.localName).toBe("settings-page");
+});
+```
+
+```ts
+// e2e/app.spec.ts (Playwright Test, built app)
+test("each page module is loaded only when its route is first shown", async ({ page }) => {
+  const scripts: string[] = [];
+  page.on("request", (r) => {
+    if (r.resourceType() === "script") scripts.push(new URL(r.url()).pathname.replace(/-[\w-]{8}\.js$/, ".js"));
+  });
+  await page.goto("/settings");
+  await expect(page.locator("#outlet h1")).toHaveText("Settings");
+  expect(scripts.sort()).toEqual(["/assets/index.js", "/assets/settings-page.js"]);
+});
+```
+
+## Known limitations
+
+1. **Scan one folder.** Several folders work too (`dirs: ["src/shared", "src/features"]`): a template imports a child defined in any scanned folder, and a tag defined in two of them is `duplicate-define`. But every folder then needs to be named in `tsDom({ dirs })`, `ts-dom check`, `ts-dom doctor` and the tsconfig `include` alike, and a folder left out of one of them is silently not generated or not checked there. One folder, `src`, avoids that. A component outside every scanned folder is not imported automatically: import its module where it is used.
+2. **Browser support.** The router needs `URLPattern`: without it the app stops at start-up with `URLPattern is not defined`. Without the Navigation API, `startRouter` attaches nothing, every link loads a new document, and the router renders the route at start-up (verified in Chrome with `navigation` removed). Only Chrome 148 was verified; check your target browsers, or use a History API router (step 5).
+3. **Keep the abort check.** Without `if (signal?.aborted) return;` after the import, a page module that loads slowly mounts over the page of a later navigation, and the address bar and the page disagree. The example's end-to-end test delays a chunk to prove the check, for both routers.
+4. **Every app path must return `index.html`.** Deep links and reloads (and every link, without the Navigation API) ask the server for the page's path. `vite dev` and `vite preview` answer with `index.html`; a production server must be set up the same way (not verified here).
+5. **A page is a new element on every navigation.** Its `state` starts over, also on back and forward, and also between `/projects/p1` and `/projects/p2`. Keep what must survive in a store.
+6. **Feature stores live as long as the document.** A store created in a lazily loaded module is created on the first visit to the feature and kept until a reload; reset it in tests with `store.set(seed())` in `beforeEach`.
+7. **happy-dom has no Navigation API and no `moveBefore`.** A test that uses `navigation` fails there with `ReferenceError: navigation is not defined`, and a reordered list item runs `disconnected()` and loses focus where Chrome keeps both. Put them in `*.browser.test.ts`; the route table can still be tested in happy-dom through `show()`.
+8. Not verified: routers other than the two in step 5, nested routes and layouts, route guards, query strings and hashes as props (the `URLPattern` here matches the path only), scroll restoration and focus after a navigation, server-side rendering, browsers other than Chrome, production servers, and oxlint with tests next to the components (the `ts-dom/unused-markup` rule counts only the component's own class, see `nativele-testing`).
+
+## Verify
+
+Run in the project:
+
+```sh
+npm run build              # expect: ts-dom check: no issues, then ✓ built, with one chunk per page module
+npx ts-dom doctor src      # expect: ts-dom doctor: the set-up looks right (info lines are suggestions)
+npm test                   # expect: every src/**/*.test.ts passes in happy-dom
+npm run test:browser       # expect: every src/**/*.browser.test.ts passes in headless Chrome
+npm run test:e2e           # expect: every e2e spec passes against vite preview on the built app
+```
+
+The example project's `npm run verify` runs exactly these, from a clean checkout with nothing generated; its output (the `info` lines left out):
+
+```
+ts-dom check: no issues
+dist/index.html                         0.49 kB
+dist/assets/settings-page-CdmdUBHw.js   0.72 kB
+dist/assets/projects-page-C9cYN-pF.js   1.20 kB
+dist/assets/text-entry-C1mgKfH1.js      1.54 kB
+dist/assets/project-page-CqUTMG_P.js    1.98 kB
+dist/assets/index-B8nptlG1.js          21.00 kB
+✓ built in 100ms
+ts-dom doctor: the set-up looks right
+ Test Files  7 passed (7)
+      Tests  19 passed (19)
+ Test Files  2 passed (2)
+      Tests  4 passed (4)
+  8 passed (3.9s)
+```
+
+The end-to-end tests cover: a deep link, links without a new document and a store keeping data across pages, the app-wide store reaching the shell and another feature, page chunks loaded on demand, a superseded navigation, a page chunk that fails to load, an unknown path, and a browser without the Navigation API.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| A shared component's tag stays empty on a page, with no error from `check`, `doctor`, `lint` or the build | the component is defined outside every scanned folder, so the generated module does not import it | scan the folder that holds it (`tsDom({ dirs: ["src"] })`, `ts-dom check src`), or import the component's module yourself |
+| `TS2307: Cannot find module './x.js'` in `src/nv/ts-dom-tags.ts` after moving components | a `ts-dom-tags.ts` left in the folder that was scanned before | delete it, and the old folder once it is empty; only `src/ts-dom-tags.ts` is generated now |
+| `[duplicate-define] the tag <x> is defined more than once` after merging folders into one scan | two features define the same tag | rename one; tags share one registry |
+| The page of an earlier link appears after a later one, and the address bar shows the later URL | the abort check after the import is missing | `if (signal?.aborted) return;` after `await` in `show()` |
+| `URLPattern is not defined` at start-up | the browser has no `URLPattern` | use a History API router (step 5) for those browsers |
+| `ReferenceError: navigation is not defined` in a Vitest test | the test runs in happy-dom | rename it `*.browser.test.ts`, or test `show()` instead |
+| 404 on a reload or a deep link in production | the server does not answer app paths with `index.html` | configure the server's fallback to `index.html` |
+| `TS2345: ... is not assignable to parameter of type 'keyof HTMLElementTagNameMap'` in the route table | the tag is misspelled | use the tag the page module passes to `define()` |
+| `TS2345: ... has no properties in common with type 'Partial<...>'` in the route table | the props function names a prop the page does not declare | use the page's prop name |
+
+## See also
+
+- Why the layout, the routing contract and the state levels: https://github.com/Pixmi/nativele/blob/main/docs/architecture.md
+- `bind`, `createStore`, props and events: https://github.com/Pixmi/nativele/blob/main/docs/components.md
+- Lists of item components (`data-key`, `data-prop`) and moving items: https://github.com/Pixmi/nativele/blob/main/docs/lists.md
+- What `ts-dom check`, `doctor` and `gen` check and write: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#checks
+- Setting up Vite: `npx ts-dom skills nativele-vite`
+- State libraries through `bind`: `npx ts-dom skills nativele-state-management`
+- Writing the tests: `npx ts-dom skills nativele-testing`