@nativele/ts-dom 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -10,6 +10,57 @@ 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.
+
+### Skills
+
+- New `nativele-state-management` (Official): where state lives (component `state`, `createStore` or an external store), and a selector adapter that connects Zustand, Redux Toolkit or nanostores to `bind`, so a component re-renders only when its slice changes. Its example project runs in CI.
+- New `nativele-testing` (Official): component tests with Vitest and happy-dom or jsdom, real-browser tests with Vitest browser mode, and end-to-end tests with Playwright. It covers what the unit-test DOM cannot do (`moveBefore`, focus during a reorder), forms, slots, isolation between test files, and a clean checkout. Its example project runs in CI.
+- New `nativele-tanstack-query` (Experimental): `@tanstack/query-core` observers through `bind`. It covers loading, error and refreshing states; keys from props; shared requests; mutations; and stopping requests when a component is removed.
+- New `nativele-zod` (Experimental): form validation with Zod or Valibot. It covers per-field messages, nested and array fields, `aria-invalid` and descriptions (also with several instances on a page), cross-field checks, and the emitted data typed from the schema.
+- New `nativele-tailwind` (Experimental): Tailwind CSS v4 in templates. It covers source detection (and excluding the installed Skills), `shadow: true` with an adopted stylesheet, `<style scoped>` defaults in a layer so utilities win, class-based dark mode in a shadow root, and templates outside the project.
+- `nativele-integration` is now Official, verified with Preact 11 and an example project in CI. Its worked example is Preact:
+  - the JSX declaration that types Nativele tags;
+  - `onitem-select` event props;
+  - a ref that sets the property for a component defined after render;
+  - keyed moves, which keep the element connected where the browser has `moveBefore`.
+
+### Fixes
+
+- In a list item, a `data-ref` on an element inside a `data-if` block was missing from the item's `refs` (the generated type declared it, so the code compiled and then threw). The refs are now collected before the item hides its `data-if` blocks.
+- `unused-ref` (and the matching checks for holes and lists) reported every ref as unused when the class held `this.refs` in a variable (`const r = this.refs; r.name.focus()`). Such an alias now counts as using every name, like `this.refs[k]`; destructuring (`const { name } = this.refs`) is still checked name by name.
+
+### Documentation
+
+- `bind`: it calls back at once and on every change, and only a `bind` in `connected()` comes back after re-insertion. A source's `subscribe` must return its unsubscribe function and must not call the listener when subscribing.
+- Styles:
+  - a template's `<style>` is not in a cascade layer, so it beats layered framework styles unless its rules are put in a layer;
+  - a `shadow: true` component uses an outside stylesheet through `adoptedStyleSheets`.
+- Lists: without `moveBefore` (older browsers, happy-dom, jsdom), a moved item reconnects and loses focus.
+- Slots: children added later are placed after a microtask.
+- `define()`: defining a name a second time keeps the first class.
+- Form recipe: `aria-invalid` must be `"true"`, and blur validation needs `data-on-focusout`.
+
 ## 0.5.1
 
 Nativele components now have a Skill for each major framework, every Skill is accepted only after a fresh agent has done real work with it, and the checks that those trials found wrong in real framework projects are fixed.

package/README.md

@@ -63,10 +63,16 @@ npx ts-dom skills add nativele-core    # copy it into .claude/skills/ (when the
 | `nativele-core` | building components: the `ts-dom check` loop, templates, state, lists, data flow |
 | `nativele-react` | Nativele components in React 19: props, events, children and slots, lifecycle, TSX types |
 | `nativele-vue` | Nativele components in Vue 3: props, events, `v-model`, slots, `<KeepAlive>`, template types |
-| `nativele-svelte` | Nativele components in Svelte 5: props, events, slots, template types (Experimental) |
+| `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` |
+| `nativele-testing` | component tests with Vitest, real-browser tests |
+| `nativele-tanstack-query` | data fetching with `@tanstack/query-core` (Experimental) |
+| `nativele-zod` | form validation with Zod or Valibot (Experimental) |
+| `nativele-tailwind` | Tailwind CSS in templates and Shadow DOM (Experimental) |
 
 Tiers: Official Skills are verified by the maintainers against an example project in CI; Community Skills are contributed and show their author and last verified versions; Experimental Skills are not fully verified yet. `ts-dom skills` marks a Skill as stale when its verification is more than six months old or does not cover the installed version.
 
@@ -223,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

@@ -63,10 +63,16 @@ npx ts-dom skills add nativele-core    # 複製到 .claude/skills/（專案有 .
 | `nativele-core` | 開發元件：`ts-dom check` 循環、範本、state、清單、資料流 |
 | `nativele-react` | 在 React 19 中使用 Nativele 元件：props、事件、子元素與 slot、生命週期、TSX 型別 |
 | `nativele-vue` | 在 Vue 3 中使用 Nativele 元件：props、事件、`v-model`、slot、`<KeepAlive>`、範本型別 |
-| `nativele-svelte` | 在 Svelte 5 中使用 Nativele 元件：props、事件、slot、範本型別（Experimental） |
+| `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 |
+| `nativele-testing` | 用 Vitest 做元件測試、真實瀏覽器測試 |
+| `nativele-tanstack-query` | 用 `@tanstack/query-core` 取資料（Experimental） |
+| `nativele-zod` | 用 Zod 或 Valibot 驗證表單（Experimental） |
+| `nativele-tailwind` | 在範本與 Shadow DOM 中使用 Tailwind CSS（Experimental） |
 
 等級：Official 由維護者以 CI 中的範例專案驗證；Community 由社群貢獻，標示作者與最後驗證版本；Experimental 尚未充分驗證。驗證超過六個月，或不涵蓋已安裝的版本時，`ts-dom skills` 會標示為可能過期。
 
@@ -223,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-DfUAh7t3.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/index.mjs

@@ -268,14 +268,14 @@ var List = class {
 		holder.append(el);
 		const conds = mountConds(holder);
 		const text = mountHoles(holder);
-		conds.hideAll();
-		const show = conds.show;
-		el.remove();
 		const refs = {};
 		for (const n of [el, ...el.querySelectorAll("[data-ref]")]) {
 			const name = n.getAttribute("data-ref");
 			if (name) refs[name] = n;
 		}
+		conds.hideAll();
+		const show = conds.show;
+		el.remove();
 		this.onCreate?.(el);
 		const entry = {
 			el,

package/dist/{lint-DfUAh7t3.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
@@ -87,7 +87,7 @@ function unusedMarkup(html, code) {
 		message,
 		...at(a, key)
 	});
-	const dynamic = (obj) => used(`\\b${obj}\\[\\s*[^"'\\s\\]]`);
+	const dynamic = (obj) => used(`\\b${obj}\\[\\s*[^"'\\s\\]]`) || used(`[\\w$]\\s*=\\s*this\\.${obj}\\s*[;,)\\n]|[(,]\\s*this\\.${obj}\\s*[,)]`);
 	const dynRefs = dynamic("refs");
 	const dynText = dynamic("text");
 	const dynLists = dynamic("lists");

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-DfUAh7t3.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, ...), 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.1",
+  "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

@@ -125,11 +125,15 @@ Otherwise the maintainers send the gaps back to the contributor as review commen
 |---|---|---|---|
 | `nativele-core` | Official | available | building with Nativele itself: the `ts-dom check` loop, components, lists, data flow |
 | `nativele-react` | Official | available | Nativele components in React 19: props, events, children and slots, lifecycle, TSX types |
-| `nativele-integration` | Experimental | available | Nativele components in a framework without its own Skill: defining before render, properties and attributes, events, slots, lifecycle, types |
+| `nativele-integration` | Official | available | Nativele components in a framework without its own Skill: defining before render, properties and attributes, events, slots, lifecycle, types; verified with Preact |
 | `nativele-vite` | Official | available | Nativele in a Vite app: the plugin and `root`, multi-page builds, the build script, hot updates, Vite+ |
 | `nativele-vue` | Official | available | Nativele components in Vue 3: `isCustomElement`, props, events, `v-model`, slots, `<KeepAlive>`, template types |
 | `nativele-svelte` | Experimental | available | Nativele components in Svelte 5: props, event attributes, slots, `bind:this`, template types |
 | `nativele-angular` | Experimental | available | Nativele components in Angular: `CUSTOM_ELEMENTS_SCHEMA`, bindings, zoneless change detection, `ts-dom gen` in the build, content projection |
-| `nativele-state-management` | Official | planned | `createStore`, and Zustand or Redux through `bind` |
-| `nativele-testing` | Official | planned | Vitest and Playwright |
-| Tailwind CSS, TanStack Query, Zod | Experimental or Community | open for contributions | |
+| `nativele-state-management` | Official | available | where state lives; `createStore`, and Zustand, Redux Toolkit or nanostores through `bind` with a selector adapter |
+| `nativele-testing` | Official | available | component tests with Vitest and happy-dom or jsdom, real-browser tests with Vitest browser mode or Playwright |
+| `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 | |