@nativele/ts-dom 0.5.5 → 0.6.0

package/skills/nativele-linting/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: nativele-linting
+description: "Bring the Nativele (@nativele/ts-dom) template lint rules into a project's existing linter (oxlint, Vite+ vp lint, or ESLint flat config) without replacing it: which rules exist and where they run (ts-dom lint, ts-dom check, the ts-dom JS plugin), choosing groups, single rule ids, severities and ignore lists, and keeping generated files and test folders out. Use when a project with @nativele/ts-dom has oxlint or eslint, when ts-dom doctor reports oxlint-plugin-missing, or when a ts-dom lint finding needs a decision."
+metadata:
+  tier: official
+  nativele: ">=0.6.0 <0.7.0"
+  verified: "2026-11-06"
+  tools: "oxlint@1.91.0 vite-plus@1.5.0 eslint@10.14.0 eslint@9.39.4 typescript-eslint@8.72.1 typescript@7.0.2 typescript@6.0.3"
+  author: "Nativele maintainers"
+  detects: "oxlint eslint"
+---
+
+# Nativele linting
+
+## When to use
+
+- The project depends on `@nativele/ts-dom` and lints with oxlint (`.oxlintrc.json`), Vite+ (`vp lint`, a `lint` block in `vite.config.ts`) or ESLint (`eslint.config.*`), and the Nativele rules should run in that linter, in the editor and in the project's lint command.
+- `ts-dom doctor` reports `oxlint-plugin-missing`, or a lint finding (`unused-ref`, `img-alt`, `unknown-prop`, ...) needs a decision: fix it, give the rule another severity, or ignore an id.
+- Generated files (`*.html.ts`, `ts-dom-tags.ts`) show up in the linter's output, or a template used only by tests is reported.
+- This Skill owns the lint configuration as far as Nativele is concerned: `.oxlintrc.json`, the `lint` block of `vite.config.ts`, and `eslint.config.*`. It does not own the rest of `vite.config.ts` (the build: `nativele-vite`), `tsconfig*.json` (`nativele-typescript`), formatting (`nativele-formatting`), the components themselves (`nativele-core`), tests (`nativele-testing`) or CI (`nativele-ci`). It keeps the project's linter, plugins and rules; it never replaces a linter, adds a second one, or rewrites a config.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.6.0 (the last agent trial) |
+| oxlint | 1.91.0 (`.oxlintrc.json`) |
+| vite-plus | 1.5.0 (`vp lint`, which runs oxlint 1.91.0, with the `lint` block in `vite.config.ts`) |
+| eslint | 10.14.0 and 9.39.4 (flat config `eslint.config.js`) |
+| typescript-eslint | 8.72.1 (the parser for `.ts` files in ESLint; it requires `typescript` below 6.1, so the ESLint projects used 6.0.3) |
+| typescript | 7.0.2 (oxlint and Vite+ projects), 6.0.3 (ESLint projects) |
+
+Verified on 2026-11-06 in fresh projects built from the packed library, with a fixture that has an unused `data-ref`, a template no file imports, an `<img>` without `alt`, a misspelled child prop, a missing handler and a test-only component. With a different major version of oxlint or ESLint, or a legacy `.eslintrc*` config, treat every step as unverified.
+
+## Set-up
+
+Check first, then change only what the task needs. Keep the user's plugins, rules, categories, ignore patterns, key order and formatting.
+
+1. **Find the linter the project actually uses.** Look for `.oxlintrc.json` (or `.oxlintrc.jsonc`), a `lint:` block in `vite.config.ts` (Vite+), `eslint.config.js`/`.mjs`/`.ts`, and the `lint` script in `package.json`. Use the one the `lint` script runs. If there is none, do not add a linter: `ts-dom check` (which `nativele-core` already runs) and `ts-dom lint` give the same findings without one. Other linters were not tried; for them, run `npx ts-dom lint <dir>` as its own step and leave their config alone.
+2. **See what is reported today.** Run `npx ts-dom lint <dir> --a11y` with the folders the project passes to `ts-dom check`, and the project's own lint command. The first shows every Nativele finding; the second shows what the linter already reports, so a new finding after the change can be told apart from an old one. Run `npx ts-dom doctor <dir>`: `oxlint-plugin-missing` names the config file that lacks the plugin.
+3. **Load the plugin in that config, next to what is there.**
+   - oxlint (`.oxlintrc.json`) and Vite+ (`lint` in `vite.config.ts`, same keys): add `{ "name": "ts-dom", "specifier": "@nativele/ts-dom/oxlint" }` to `jsPlugins` (create the array if missing; keep other entries). The plain string `"@nativele/ts-dom/oxlint"` also works. Do not touch `plugins` (the built-in ones) or `categories`.
+   - ESLint (flat config): `import tsDom from "@nativele/ts-dom/oxlint"` and add a config object `{ plugins: { "ts-dom": tsDom }, rules: { ... } }` to the exported array. The same module is a valid ESLint plugin. It needs the TypeScript parser the project already uses for `.ts` files (verified with `typescript-eslint`).
+   - Loading the plugin enables nothing: with `jsPlugins` set and no `ts-dom/*` rule, nothing is reported and doctor is satisfied. Step 4 decides the rules.
+4. **Choose rules and severities** (see "Rules, groups and severities" below). The baseline is `"ts-dom/unused-markup": "error"`. Add `"ts-dom/data-flow"` and `"ts-dom/a11y"` as `"warn"` when the user wants them; ask before turning on a11y in an existing project with many templates, and show the count from step 2.
+5. **Keep generated files out of the linter.** The rules run on the component files, never on `*.html.ts` or `ts-dom-tags.ts`, but the project's own rules do. oxlint and `vp lint` skip what `.gitignore` lists, so when `.gitignore` has `*.html.ts` and `ts-dom-tags.ts` (as the setup guide recommends), nothing is needed. Otherwise, and always with ESLint (it does not read `.gitignore`), add `**/*.html.ts` and `**/ts-dom-tags.ts` to the existing ignore list: `ignorePatterns` for oxlint and Vite+, `globalIgnores([...])` from `eslint/config` for ESLint. Never fix a finding inside a generated file: it is rewritten on the next `ts-dom gen`.
+6. **Test folders.** Access from a test never counts as use (Known limitations 3), and the rules only report a template in the file that imports it. Turn `ts-dom/unused-markup` off only for files that import a template themselves (a test-only host component): an `overrides` entry `{ "files": ["test/**"], "rules": { "ts-dom/unused-markup": "off" } }` in oxlint, or `{ files: ["test/**"], rules: { "ts-dom/unused-markup": "off" } }` in ESLint, with the project's own test globs. Do not lower `unused-ref` for component files to make room for tests; a ref that only a test reads is removed and the test queries the DOM (the testing Skill owns how).
+7. **State what other areas need, and leave the how to them.** The lint script belongs to the build owner and the CI steps to `nativele-ci`: the project's lint command covers the Nativele rules, except `no-importer` (Known limitations 1), which `ts-dom check` reports. The type check order (generated files before `tsc`) is a requirement `nativele-typescript` states; the script that runs it belongs to the build owner. Formatting templates, and keeping the formatter off the generated files, belongs to `nativele-formatting`.
+8. **Run Verify.**
+
+### What runs where
+
+| | `ts-dom lint [dirs]` | `ts-dom check [dirs]` | The `ts-dom` JS plugin in oxlint, `vp lint` or ESLint |
+|---|---|---|---|
+| unused-markup (errors) | all 7 ids, including `no-importer` | all 7 ids, including `no-importer` | 6 ids; `no-importer` does not exist here |
+| data-flow (warnings) | always | always | when `ts-dom/data-flow` or a single id is on |
+| a11y (warnings) | with `--a11y` | with `--a11y` | when `ts-dom/a11y` or a single id is on |
+| Also runs | nothing else; needs no generated files and writes nothing | codegen (writes the generated files unless `--no-write`) and `tsc` | the project's other rules |
+| Severity and ignore | fixed: unused-markup is an error, the rest warnings; no per-id switch (filter `--json` if needed) | the same | per rule in the config, `ignore` on the three groups |
+| Where a finding points | `src/nv/card.html:3:3 error [unused-ref] ...` | the same | the template's `import` line in the `.ts` file, with the HTML location first: `src/nv/card.ts:2:1: error ts-dom(unused-markup): ./card.html.js:3:3 [unused-ref] ...` |
+| Exit code | 1 on an error (also with `--json`); 1 on a warning too with `--strict`; 0 otherwise | the same | the linter's own (oxlint and ESLint: 1 on an error, 0 on warnings only) |
+| `--json` | `{ "issues": [{ file, rule, severity, message, line, col }] }`; data-flow child issues add `tag`, `attrs`, `events` | `{ "issues": [...] }` | the linter's own format |
+
+`ts-dom lint` and `ts-dom check` scan only the folders passed to them, and `--include`/`--exclude` do not filter their lint findings. Neither reads the linter's config, so a severity or ignore chosen there does not change them (Known limitations 2).
+
+### Rules, groups and severities
+
+- Three groups: `ts-dom/unused-markup`, `ts-dom/data-flow`, `ts-dom/a11y`. A group reports all of its ids; `["warn", { "ignore": ["img-alt"] }]` drops ids from it. `npx ts-dom rules` lists every id by group, and `npx ts-dom rules --explain=<id>` says why it exists.
+- Every id is also a rule of its own (`ts-dom/unused-ref`, `ts-dom/img-alt`, `ts-dom/unknown-prop`, ...; 38 rules in all), for a severity per id. A single-id rule takes no options.
+- To give one id another severity, ignore it in its group and enable it alone: `"ts-dom/unused-markup": ["error", { "ignore": ["unused-ref"] }], "ts-dom/unused-ref": "warn"`. A group and one of its ids both on report the finding twice.
+- Choose by what each id costs when it is missed: unused-markup ids are dead or broken markup (blank text, an empty list, a handler that does not exist) and stay errors. data-flow ids are design advice plus child contract checks (`unknown-prop`, `invalid-prop-value`, `unknown-event`), warnings by default; raise the contract ids to `"error"` singly if the user wants. a11y ids are static hints, warnings, and `ignore` takes the ids that do not apply (for example `aria-idref` when labels point outside the template).
+- An `ignore` id that does not exist is silently accepted: check every id against `npx ts-dom rules` before writing it.
+
+## Example
+
+An oxlint project, before:
+
+```json
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "unicorn"],
+  "rules": {
+    "no-console": "warn",
+    "eqeqeq": "error"
+  }
+}
+```
+
+`.gitignore` already lists `node_modules`, `*.html.ts` and `ts-dom-tags.ts`; tests in `test/` include a host component that imports its own template. After (only `jsPlugins`, three rules and `overrides` added):
+
+```json
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript", "unicorn"],
+  "jsPlugins": [{ "name": "ts-dom", "specifier": "@nativele/ts-dom/oxlint" }],
+  "rules": {
+    "no-console": "warn",
+    "eqeqeq": "error",
+    "ts-dom/unused-markup": "error",
+    "ts-dom/a11y": ["warn", { "ignore": [] }],
+    "ts-dom/data-flow": ["warn", { "ignore": [] }]
+  },
+  "overrides": [{ "files": ["test/**"], "rules": { "ts-dom/unused-markup": "off" } }]
+}
+```
+
+With Vite+, the same keys go into the existing `lint` block of `vite.config.ts` (`jsPlugins`, the `ts-dom/*` rules, and `ignorePatterns: ["**/*.html.ts", "**/ts-dom-tags.ts"]` only if `.gitignore` does not list them); the `plugins: [tsDom()]` entry and the rest of the file belong to the build.
+
+An ESLint project (flat config), after; the lines added are the `globalIgnores`, the `tsDom` import and the last two objects:
+
+```js
+import { globalIgnores } from "eslint/config";
+import tseslint from "typescript-eslint";
+import tsDom from "@nativele/ts-dom/oxlint";
+
+export default tseslint.config(
+  globalIgnores(["**/*.html.ts", "**/ts-dom-tags.ts"]),
+  tseslint.configs.recommended,
+  {
+    plugins: { "ts-dom": tsDom },
+    rules: { "ts-dom/unused-markup": "error", "ts-dom/data-flow": "warn" },
+  },
+  { files: ["test/**"], rules: { "ts-dom/unused-markup": "off" } },
+);
+```
+
+Without `globalIgnores`, `tseslint.configs.recommended` reports `@typescript-eslint/no-empty-object-type` errors in the generated `*.html.ts` files.
+
+## Known limitations
+
+1. **`no-importer` runs only in `ts-dom lint` and `ts-dom check`.** The plugin checks a template from the file that imports it, so a template nobody imports is invisible to it, and `"ts-dom/no-importer"` fails with `Rule 'no-importer' not found in plugin 'ts-dom'`. Keep `ts-dom check` (or `ts-dom lint`) in the project's checks; a lint command alone does not cover it.
+2. **The CLI ignores the linter's choices.** `ts-dom lint` and `ts-dom check` always report unused-markup as errors and have no ignore option: an id set to `"warn"` or ignored in the linter still fails `ts-dom check`. Fix the finding rather than relax the linter when the project runs both; relax only what the user accepts in both places (or filter `--json` in the user's own script).
+3. **Use from outside the class does not count.** `unused-markup` compares a template with the body of `class X extends Component(tpl)`; `el.refs.x` in a test, in another component or in a script outside the class is not use, in any of the three tools. Turning the rule off for test folders silences only templates those test files import.
+4. **Child contracts are read from the working directory.** `unknown-prop`, `invalid-prop-value` and `unknown-event` need the child component's `define()`; the plugin scans for them from the folder the linter runs in. Run from a folder that does not contain the child (oxlint started in `test/` on `src`), the `unknown-prop` finding disappeared without a message. Run the linter from the project folder.
+5. **Disable comments hide the whole template.** Every finding is reported on the `import` line, so `// oxlint-disable-next-line ts-dom/unused-markup` (or `eslint-disable`) above it silences every unused-markup finding of that template, while `ts-dom check` keeps reporting them. Do not use disable comments for template findings; fix the template or use `ignore` for an a11y or data-flow id the user accepts.
+6. **Doctor reads only `.oxlintrc.json`, `.oxlintrc.jsonc`, `oxlintrc.json`, `oxlint.config.ts`, `oxlint.config.mts` and the `lint` block of `vite.config.*`.** It does not look at ESLint configs at all. Doctor also counts the plugin as configured when `jsPlugins` names it, even with no `ts-dom/*` rule on. Check the config yourself, and confirm with a finding (Verify).
+7. **No fix for findings in the HTML.** The only suggestion is `missing-handler`, which adds an empty method to the class (`oxlint --fix-suggestions` wrote `save(_e: Event): void {}`); the user's own rules (for example `@typescript-eslint/no-empty-function` in typescript-eslint's `strict`) may then report that empty method, which the developer fills in. An unused `data-ref` or a11y finding is fixed by editing the `.html`.
+8. **Not verified:** the editor integration (the Oxc and ESLint VS Code extensions), whether the plugin picks up a child's new prop in a long-running editor session without a restart, legacy `.eslintrc*`, oxlint's JavaScript or TypeScript config files, and linters other than oxlint and ESLint.
+
+## Verify
+
+```sh
+npx ts-dom lint src/nv --a11y      # expect: ts-dom lint: no issues (or only findings the user accepted)
+npx oxlint                         # or: npx vp lint / npx eslint . ; expect: exit code 0 and no ts-dom(...) or generated-file findings
+npx ts-dom doctor src/nv           # expect: no oxlint-plugin-missing
+npx ts-dom check src/nv            # expect: ts-dom check: no issues
+```
+
+Then prove the linter runs the rules: add `<span data-ref="probe"></span>` to a template, run the project's lint command, and expect `error ts-dom(unused-markup): ./<name>.html.js:<line>:<col> [unused-ref] data-ref="probe" is never used by the component class.` on the template's import line (ESLint prints the same message under the `.ts` file); exit code 1. Remove it afterwards. If a11y or data-flow is on, an `<img>` without `alt` gives `[img-alt]`, and a misspelled attribute on a child tag gives `[unknown-prop]`, both as warnings.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `x Plugin 'ts-dom' not found` | a `ts-dom/*` rule without the `jsPlugins` entry | add `{ "name": "ts-dom", "specifier": "@nativele/ts-dom/oxlint" }` to `jsPlugins` |
+| `x Failed to load JS plugin: @nativele/ts-dom/oxlint-plugin` ... `is not exported` | a wrong specifier | `@nativele/ts-dom/oxlint` |
+| `x Rule 'no-importer' not found in plugin 'ts-dom'` | `no-importer` has no rule in the plugin | remove it; `ts-dom check` reports it (Known limitations 1) |
+| `Error: Rule 'ts-dom/unused-ref' does not accept options` | `ignore` on a single-id rule | `ignore` only on the three groups |
+| `Unexpected property "ignor". Expected properties: "ignore".` | a misspelled option key | `ignore` |
+| An ignored id is still reported | the id is misspelled (accepted silently), or it is ignored in the group but also enabled alone | check the id with `npx ts-dom rules`; one place per id |
+| Every finding appears twice, once as `ts-dom(unused-markup)` and once as `ts-dom(unused-ref)` | the group and a single id are both on | ignore the id in the group, or drop one of them |
+| The linter is clean but `ts-dom check` fails with `[unused-ref]` or `[no-importer]` | Known limitations 1 and 2 | fix the template; the CLI does not read the linter's config |
+| `@typescript-eslint/no-empty-object-type`, `sort-keys`, `import(newline-after-import)` or similar in `*.html.ts` | the project's own rules run on generated files | ignore `**/*.html.ts` and `**/ts-dom-tags.ts` in the linter (step 5); never edit the generated files |
+| oxlint reports thousands of findings in `node_modules` | the project has no `.gitignore` listing `node_modules` (oxlint linted `node_modules` then, and stopped once `.gitignore` listed it) | add `node_modules` to `.gitignore` or `ignorePatterns`, as the user prefers |
+| `[unused-ref]` for a ref a test reads | test access is not use (Known limitations 3) | remove the ref and query the DOM in the test |
+| `[unknown-prop]` missing for a child tag | the linter ran from a folder without the child's `define()` (Known limitations 4) | run it from the project folder |
+
+## See also
+
+- Lint settings, the oxlint plugin, the editor and the `ts-dom lint` flags: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#lint-optional
+- What each tool checks, `ts-dom check` and `ts-dom doctor`: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#checks
+- The a11y ids and what each checks: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#aria--accessibility-checks
+- The data-flow rules and what to do instead of passing through layers: https://github.com/Pixmi/nativele/blob/main/docs/components.md#avoiding-layer-by-layer-passing-lint-ts-domdata-flow
+- How Skills share a project, and who owns which configuration: https://github.com/Pixmi/nativele/blob/main/skills/README.md#how-skills-work-together

package/skills/nativele-monorepo/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: nativele-monorepo
+description: "Use Nativele across the packages of a workspace (npm or pnpm workspaces, optionally with a task runner such as turbo): a package of shared components used by one or more apps, where each package generates and checks its own components, how an app gets their modules and their tag types, where @nativele/ts-dom and typescript must be installed, and which package must be generated or built before another type-checks. Use when a repository has several package.json files and Nativele components in one of them are used by another."
+metadata:
+  tier: official
+  nativele: ">=0.6.0 <0.7.0"
+  verified: "2026-11-06"
+  tools: "npm@11.19.1 pnpm@12.16.1 turbo@2.11.10 vite@8.3.6 typescript@7.0.2 create-vite@9.3.4 vue-tsc@3.3.14"
+  author: "Nativele maintainers"
+  detects: "turbo nx lerna"
+---
+
+# Nativele in a monorepo
+
+## When to use
+
+- The repository is a workspace (a root `package.json` with `workspaces`, or a `pnpm-workspace.yaml`), and Nativele components live in a package that another package uses: a component package (`packages/ui`) consumed by one or more apps (`apps/web`), or several packages that each have components.
+- Signals: more than one `package.json` that lists `@nativele/ts-dom`; an app that depends on a workspace package (`"@acme/ui": "workspace:*"` or a version) whose source has `define()` calls; `turbo`, `nx` or `lerna` in the root `package.json`, which is what `ts-dom doctor` matches (it reads only dependencies, and a workspace is declared by `workspaces` or `pnpm-workspace.yaml`, not by a dependency).
+- This Skill owns the workspace side of Nativele: where each package's `ts-dom` commands run and on which folder, how a component package exposes its modules and tag types, which package declares `@nativele/ts-dom` and `typescript`, and the order in which packages must be generated or built. It keeps the user's package manager, workspace layout and task runner. It does not own `tsconfig*.json` (`nativele-typescript`), the build tool and its config (`nativele-vite` or the framework's Skill), lint, CI, or the task runner's config; it states what they must do and leaves the how to them.
+- Not for one package with several folders: scan one folder, as the [architecture guide](https://github.com/Pixmi/nativele/blob/main/docs/architecture.md#generated-files-checks-and-tsconfig) says. Not for setting a workspace up from nothing.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.6.0 (the last agent trial) |
+| npm (workspaces) | 11.19.1, on Node 24.22.2 |
+| pnpm (workspaces) | 12.16.1 |
+| turbo | 2.11.10 (with npm workspaces) |
+| vite | 8.3.6 |
+| typescript | 7.0.2 (and 6.0.3 where hoisting put it, see Known limitations) |
+| create-vite (`vanilla-ts`, the app) | 9.3.4 |
+| vue-tsc | 3.3.14 (only to see which package's checker `ts-dom check` runs) |
+
+Verified on 2026-11-06 in Google Chrome 148 with a component package `packages/ui` and a Vite app `apps/web` from `create-vite`, built once before Nativele was added, in an npm workspace and a pnpm workspace: the component package exported as TypeScript source and as built JavaScript with declarations, and the built one also packed and installed into a separate app. Not verified: yarn and Bun workspaces, nx, lerna, TypeScript project references across packages (`tsc -b` with `composite`), and apps with a UI framework consuming the package. With a different major version of npm, pnpm or turbo, treat every step as unverified.
+
+## Set-up
+
+Check first, then change only what fails. Use the workspace's own package manager and commands for every install and script; never add or switch one.
+
+1. **Read the workspace.** The root `package.json` (`workspaces`, `packageManager`, scripts), `pnpm-workspace.yaml`, the lockfile (which package manager), and a task runner's config (`turbo.json`, `nx.json`). For each package: does its `package.json` list `@nativele/ts-dom` and `typescript`, where are its templates (the folder with `.html` and `define()` files), which workspace packages does it depend on, and what is its `exports`.
+   When a component that already lives in an app moves into the package, keep its tag name, and remove what pointed to its old place in the app: the old folder in the app's `tsDom({ dirs })` and in its `ts-dom` scripts (point them at the folder that holds the app's own components; a folder that no longer exists fails with `dir-not-found`, and the app's own templates are then not generated), the import in the app's entry, and the `ts-dom-tags.ts` left in the old folder.
+2. **Check the copies of the library:** `npm ls @nativele/ts-dom` or `pnpm why -r @nativele/ts-dom`. Expect one version (npm prints the others as `deduped`; pnpm prints `Found 1 version of @nativele/ts-dom`). Two versions work, but ship the runtime twice (Known limitations 6).
+3. **Declare the dependencies in every package that needs them.** Each package resolves `@nativele/ts-dom`, `typescript` and the `ts-dom` command from its own folder, so relying on another package's hoisted copy breaks when the layout changes (Known limitations 7):
+
+   | Package | `@nativele/ts-dom` | `typescript` |
+   |---|---|---|
+   | component package | `peerDependencies` with the range the apps use (`"^0.6.0"`), and the same version in `devDependencies` for its own `ts-dom` and tests | `devDependencies` |
+   | app | `dependencies` | `devDependencies` |
+
+   The peer lets an app outside the workspace install the package without a second copy (verified: a packed component package installed into a separate app gave one `@nativele/ts-dom`, `deduped`). Inside the workspace the package's own `devDependencies` entry satisfies its peer, so the peer does not stop a second version there; step 2 does. Install with the workspace's command (`npm i -D -w @acme/ui @nativele/ts-dom typescript`, `pnpm --filter @acme/ui add -D @nativele/ts-dom typescript`), then add the peer to that `package.json` (`npm pkg set "peerDependencies.@nativele/ts-dom=^0.6.0" -w @acme/ui`, or by editing the file). The app depends on the component package the way the workspace already links its packages (`"workspace:*"` in pnpm, a version in npm).
+4. **Each package scans only its own folder, and its `ts-dom` commands run in that package.** In `packages/ui`: `ts-dom check src`; in `apps/web`: `ts-dom check src`, and `tsDom()` keeps the app's own `dirs`. From the root, run them through the workspace (`npm exec -w web -- ts-dom check src`, `pnpm --filter web exec ts-dom check src`, `pnpm -r exec ts-dom check src`, or each package's script). Do not give one command the folders of several packages, and do not add another package's folder to `tsDom({ dirs })` (Known limitations 4).
+5. **The component package exposes its components through one entry module** (its `exports`):
+   - it imports or re-exports every module that calls `define()`, so importing the package registers the tags;
+   - it has the line `export type {} from "./ts-dom-tags.js";`, which brings the package's generated tag map into every program that imports the package, so consumers get the props, events and list item types of its tags (Known limitations 2); the component classes it exports must be `export class`, as in [Composition](https://github.com/Pixmi/nativele/blob/main/docs/components.md#composition-using-multiple-components-together);
+   - its `package.json` has no `"sideEffects": false`. If the project wants `sideEffects`, list the entry module and every module that calls `define()` (Known limitations 9).
+6. **Source or built.** Both were verified inside a workspace with Vite; which one is the user's choice, and the build belongs to the build owner:
+   - Source: `"exports": { ".": "./src/index.ts" }`. The app's bundler compiles the package, and the app's type check reads the package's source with the app's tsconfig, so the package's generated files must exist before the app type-checks or builds.
+   - Built: the package's build writes JavaScript and declarations (`tsc` with `declaration` and `outDir: "dist"` was verified), and `"exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" } }`. The generated templates are compiled into `dist` (`x.html.js`, `x.html.d.ts`, `ts-dom-tags.d.ts`), the declaration of the entry keeps `export type {} from "./ts-dom-tags.js"`, and a consumer runs no `ts-dom` on the package. A package published outside the workspace must be built: the consumer's `ts-dom` does not generate inside `node_modules`, and `npm pack` leaves out the git-ignored generated files, so a source package installed from a tarball failed to resolve its `./x.html.js` imports. Ship `dist` (`"files": ["dist"]`); the templates and generated sources are not needed.
+   The tsconfig for the package's build belongs to the TypeScript Skill (`nativele-typescript`); what this Skill needs from it is that it includes the folder with `ts-dom-tags.ts` and emits declarations.
+7. **The app imports the package once for its side effect** in its entry module (`import "@acme/ui";`), and the types it needs (`import type { UiButton, Tag } from "@acme/ui";`). An object or array prop such as `badge` cannot be written as an attribute in the app's template; set it from TypeScript (`this.refs.badge.badge = {...}` in `render`, or the element's property). A template in the app that uses `<ui-button>` gets no import of it from `ts-dom gen`, because the tag is not defined in the app's folder ([architecture guide](https://github.com/Pixmi/nativele/blob/main/docs/architecture.md#generated-files-checks-and-tsconfig)).
+8. **State the order to the owner of the scripts or the task runner.** The component package's `ts-dom gen` (source) or its build (built) must finish before the app's `ts-dom check`, `tsc` or `vite build`. What was observed with each tool, for the owner to use:
+   - `npm run <script> --workspaces` runs the packages in the order of the `workspaces` array, not by dependency: `["packages/*", "apps/*"]` ran `packages/ui` first, `["apps/*", "packages/*"]` ran the app first. Do not reorder an array that lists apps first (the order is the team's, and other scripts may depend on it); name the packages in order instead: `npm run build -w @acme/ui && npm run build -w web`.
+   - `pnpm -r run <script>` ran `packages/ui` first although `pnpm-workspace.yaml` listed `apps/*` first, because the app depends on it.
+   - turbo with `"dependsOn": ["^build"]` ran the package first. Its `outputs` must contain what the next package reads: `dist/**` for a built package, and for a source package also the generated files (`"src/**/*.html.ts"`, `"src/**/ts-dom-tags.ts"`); with only `dist/**`, a cache hit on a clean checkout restored nothing and the app's check failed with `TS2307: Cannot find module './ui-button.html.js'` inside `packages/ui`.
+   Each package's own script still type-checks after generating (`ts-dom check src && ...`), as the Vite Skill and the TypeScript Skill say; doctor's `typecheck-before-gen` reads the `.gitignore` files from the package up to the workspace root, so a root-only `.gitignore` counts.
+9. **During development**, the app's dev server does not regenerate another package's templates. For a source package, run `ts-dom gen --watch src` in the component package next to the app's `vite`: the app's dev server then reloads the page when the package's generated file changes. A built package needs its own watch build, which is the build owner's.
+10. **Skills and doctor.** `ts-dom skills add` copies into the folder it runs in (`.claude/skills/` or `.agents/skills/`), and `ts-dom doctor` looks for copies in the folder it runs in and the folders above it up to the workspace root (a `package.json` with `workspaces`, a `pnpm-workspace.yaml`, else the git root). Copy the Skills where the agent is started (usually the root); doctor in each package then sees them there.
+11. **Run Verify.**
+
+## Example
+
+npm workspaces; with pnpm, the root has `pnpm-workspace.yaml` (`packages: ["apps/*", "packages/*"]`), the app depends on `"@acme/ui": "workspace:*"`, and the root script is `pnpm -r run build`. The app is `create-vite`'s `vanilla-ts` template with its `tsconfig.json` and `.gitignore` unchanged; its starter files (`counter.ts`, `assets`, `public`) were removed.
+
+```json
+// package.json (root)
+{
+  "name": "shop",
+  "private": true,
+  "workspaces": ["packages/*", "apps/*"],
+  "scripts": { "build": "npm run build --workspaces" }
+}
+```
+
+```gitignore
+# .gitignore (root)
+node_modules
+*.html.ts
+ts-dom-tags.ts
+```
+
+```json
+// packages/ui/package.json
+{
+  "name": "@acme/ui",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "exports": { ".": "./src/index.ts" },
+  "scripts": { "build": "ts-dom check src" },
+  "peerDependencies": { "@nativele/ts-dom": "^0.6.0" },
+  "devDependencies": { "@nativele/ts-dom": "^0.6.0", "typescript": "^7.0.2" }
+}
+```
+
+```json
+// packages/ui/tsconfig.json (owned by TypeScript; shown as verified)
+{
+  "compilerOptions": {
+    "target": "es2023",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2023", "DOM"],
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}
+```
+
+```html
+<!-- packages/ui/src/ui-button.html -->
+<button type="button" data-on-click="press">{{ label }}</button>
+```
+
+```ts
+// packages/ui/src/ui-button.ts
+import { Component, define, event } from "@nativele/ts-dom";
+import tpl from "./ui-button.html.js";
+
+export class UiButton extends Component(tpl, {
+  props: { label: "" },
+  emits: { "ui-press": event<{ label: string }>() },
+}) {
+  press(): void {
+    this.emit("ui-press", { label: this.props.label });
+  }
+}
+define("ui-button", UiButton);
+```
+
+```html
+<!-- packages/ui/src/ui-tag.html -->
+<span>{{ text }}</span>
+```
+
+```ts
+// packages/ui/src/ui-tag.ts
+import { Component, define } from "@nativele/ts-dom";
+import tpl from "./ui-tag.html.js";
+
+export interface Tag {
+  id: string;
+  label: string;
+}
+
+export class UiTag extends Component(tpl, {
+  props: { tag: { id: "", label: "" } as Tag },
+  derive: { text: (s) => s.tag.label },
+}) {}
+define("ui-tag", UiTag);
+```
+
+```ts
+// packages/ui/src/index.ts
+export type {} from "./ts-dom-tags.js";
+export { UiButton } from "./ui-button.js";
+export { UiTag, type Tag } from "./ui-tag.js";
+```
+
+```json
+// apps/web/package.json (the parts that change)
+{
+  "scripts": { "build": "ts-dom check src && vite build" },
+  "dependencies": { "@acme/ui": "^0.0.0", "@nativele/ts-dom": "^0.6.0" },
+  "devDependencies": { "typescript": "~7.0.2", "vite": "^8.3.6" }
+}
+```
+
+```ts
+// apps/web/vite.config.ts
+import { defineConfig } from "vite";
+import { tsDom } from "@nativele/ts-dom/vite";
+
+export default defineConfig({
+  plugins: [tsDom()],
+});
+```
+
+```ts
+// apps/web/src/main.ts (index.html has <app-shell></app-shell> in its body)
+import "./style.css";
+import "@acme/ui";
+import "./app-shell.ts";
+```
+
+```html
+<!-- apps/web/src/app-shell.html -->
+<p>{{ message }}</p>
+<ui-button data-ref="add" label="Add tag" data-on-ui-press="onAdd"></ui-button>
+<div role="list">
+  <template data-each="tags" data-key="id" data-prop="tag">
+    <ui-tag role="listitem"></ui-tag>
+  </template>
+</div>
+```
+
+```ts
+// apps/web/src/app-shell.ts
+import { Component, define } from "@nativele/ts-dom";
+import type { EmitEvent } from "@nativele/ts-dom";
+import type { Tag, UiButton } from "@acme/ui";
+import tpl from "./app-shell.html.js";
+
+export class AppShell extends Component(tpl, {
+  state: { message: "No tags yet", tags: [] as Tag[] },
+}) {
+  onAdd(e: Event): void {
+    const { label } = (e as EmitEvent<UiButton, "ui-press">).detail;
+    const n = this.state.tags.length + 1;
+    this.set({ message: `${label}: ${n}`, tags: [...this.state.tags, { id: `t${n}`, label: `tag ${n}` }] });
+  }
+  override render(v: { tags: readonly Tag[] }): void {
+    this.refs.add.label = v.tags.length ? "Add another" : "Add tag";
+    this.lists.tags.items = v.tags;
+  }
+}
+define("app-shell", AppShell);
+```
+
+`this.refs.add` is `UiButton` and `this.lists.tags.items` takes `Tag` items only because the package's tag map reaches the app through `export type {} from "./ts-dom-tags.js"`.
+
+## Known limitations
+
+1. **A tag from another package is neither imported nor defined for you.** The app's generated `x.html.ts` imports only components defined in the app's scanned folder. With only `import type` from the package, the build succeeds and the page shows the tags as empty, never-upgraded elements (`customElements.get("ui-button")` is `undefined`), with no error in the console. Import the package for its side effect (step 7).
+2. **The package's `ts-dom-tags.ts` does not reach consumers by itself**: nothing imports it. Without step 5's line, the app's `refs` of the package's tags are plain `HTMLElement` (`TS2339: Property 'label' does not exist on type 'HTMLElement'`), and a keyed list of the package's item component takes any object type with the key field but rejects items typed by an interface (`Index signature for type 'string' is missing in type 'Tag'`). `import type {} from "./ts-dom-tags.js"` and `/// <reference path="./ts-dom-tags.ts" />` work for a source package, but both are dropped from the emitted `index.d.ts` of a built one; `export type {} from` is kept there and erased from the JavaScript. `import "./ts-dom-tags.js"` is kept too, but as a runtime import of an empty module.
+3. **Lint does not see another package's components.** With the tag map in place, `tsc` checks their prop types (`TS2322: Type 'number' is not assignable to type 'string'`), list item types and `EmitEvent` details, but a misspelled attribute (`lable="Save"`) or event (`data-on-ui-pres`) on the package's tag is not reported: `unknown-prop` and `unknown-event` read only the scanned folders.
+4. **One `ts-dom` run over several packages' folders breaks package boundaries.** `ts-dom gen packages/ui/src apps/web/src` from the root writes `import "../../../packages/ui/src/ui-button.js"` into the app's generated files, bypassing the package's `exports`; the app's own run (and `tsDom()` at build start) writes the files without it, so `ts-dom gen --check` from either side reports the other's files as `stale-generated`. With a built package, an app bundled from those files contained both `packages/ui/dist/ui-button.js` and `packages/ui/src/ui-button.ts`. `tsDom({ dirs: ["src", "../../packages/ui/src"] })` does the same. From the root, `ts-dom check` also needs a root `tsconfig.json` (without one: `tsc-failed`; `ts-dom doctor`: `no-tsconfig`), and uses what resolves from the root: its `typescript`, and `vue-tsc` only if the root `package.json` lists it (`ts-dom check` picks the checker by the `package.json` of the folder it runs in: in a pnpm workspace it ran `vue-tsc` in the app that listed it and `tsc` in the component package).
+5. **A tag defined in two packages fails silently at runtime.** `define()` skips a tag that is already registered, so the module loaded first wins and the other class is never used, with no error. Per package, `ts-dom check` reports it only when both tag maps are in one program, as `duplicate-define` (from tsc's `TS2717` in `ts-dom-tags.ts`; its `Fix:` says to rename the tag). A run over both folders reports `duplicate-define`, with the problems of limitation 4. Give each package's new tags a prefix of their own; a component moved in from an app keeps its tag (step 1), because the pages and tests that use it name that tag.
+6. **Two versions of `@nativele/ts-dom` work but ship twice.** With the component package on another version than the app, props, events, a keyed list of the package's item component and a store created in the package and bound in the app all worked, and the minified bundle grew from 18.20 kB to 34.29 kB. No `ts-dom` command reports it, and inside the workspace the peer does not prevent it (step 3); step 2 does.
+7. **Hoisting hides missing dependencies until an install changes it.** In an npm workspace, a component package that lists neither `@nativele/ts-dom` nor `typescript` still generates, checks and builds through the root's hoisted copies, and doctor reports nothing. When an install moves `typescript` into another package's `node_modules` (adding and removing `vue-tsc` in the app does), `ts-dom check src` in the package stops with `error [tsc-not-found]`. A hoisted `typescript` at the root can also differ from the app's own (6.0.3 against `~7.0.2`), so `npx tsc` in the app and `ts-dom check` from the root run different compilers. In pnpm the same package fails at once: `Command "ts-dom" not found`, and the app's check reports `TS2307: Cannot find module '@nativele/ts-dom'` in the package's files. Step 3 fixes all of these.
+8. **`ts-dom doctor` reads the folder it runs in** for its `package.json`, `tsconfig.json` and Vite config, and the folders up to the workspace root for `.gitignore` and Skill copies. At the root without folders it reports `dir-not-found` for `src`. Run it in each package with that package's folder, and check the script order yourself (step 8).
+9. **`"sideEffects": false` drops the components from a production build.** With it in the component package, `vite build` removed `import "@acme/ui"` and every `define()`, and no tag was registered. A list must name the entry module too: a list of only the modules that call `define()` still dropped them, while `["./src/index.ts", "./src/ui-*.ts"]` and `["**/*.ts"]` kept them.
+10. **The app's dev server does not watch another package's templates** (step 9).
+
+## Verify
+
+At the root:
+
+```sh
+npm ls @nativele/ts-dom          # pnpm: pnpm why -r @nativele/ts-dom; expect one version
+```
+
+In each package that has components (here `packages/ui`, then `apps/web`; pnpm: `pnpm exec ts-dom ...`):
+
+```sh
+npx ts-dom doctor src            # expect: no error; tsconfig-* findings go to the TypeScript Skill; skill-available is info
+npx ts-dom check src             # expect: ts-dom check: no issues (never tsc-not-found)
+```
+
+From the root, the build through the workspace on a clean checkout (no `*.html.ts`, no `ts-dom-tags.ts`, no `dist`):
+
+```sh
+npm run build                    # pnpm: pnpm run build; expect: packages/ui's script before apps/web's, each "ts-dom check: no issues", then vite's "built in"
+```
+
+Then prove the types cross the package boundary: in the app's `render`, write `this.refs.add.label = v.tags.length;` and expect `TS2322: Type 'number' is not assignable to type 'string'` from `npx ts-dom check src`; write `this.lists.tags.items = v.tags.map((t) => ({ id: t.id, name: t.label }));` and expect a `TS2322` that ends with `Property 'label' is missing in type '{ id: string; name: string; }'`. Undo both. In the browser (`vite preview`), `customElements.get("ui-button")` and `customElements.get("ui-tag")` are defined, clicking the button changes its label to "Add another" and adds a `<ui-tag>` per click, and the console has no errors.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| The package's tags render nothing, no console error, `customElements.get(tag)` is `undefined` | the app imports the package only as types, or `"sideEffects": false` dropped it from the build | `import "@acme/ui"` in the app's entry (step 7); remove `sideEffects: false` or list the entry and `define()` modules |
+| `TS2339: Property 'label' does not exist on type 'HTMLElement'` on a ref of the package's tag | the package's tag map does not reach the app | `export type {} from "./ts-dom-tags.js"` in the package's entry; for a built package, rebuild it |
+| `TS2307: Cannot find module './ui-button.html.js'` in `../../packages/ui/src/...` during the app's check | the source package was not generated first (clean checkout, wrong order, or a task runner cache without the generated files in `outputs`) | run the package's `ts-dom gen src` first (step 8) |
+| `TS2307: Cannot find module '@acme/ui'` and `TS2882` for `import "@acme/ui"` | the built package's `dist` does not exist yet | build the package first (step 8) |
+| `Index signature for type 'string' is missing in type 'Tag'` on a keyed list of the package's item component | the package's tag map does not reach the app (limitation 2) | as above |
+| `Could not resolve './ui-tag.html.js' in node_modules/@acme/ui/src/ui-tag.ts`, and `TS2307` for it | a source package installed from a tarball or a registry: `npm pack` left out the git-ignored generated files, and the app's `ts-dom` does not generate inside `node_modules` | publish the package built (step 6) |
+| `TS2307: Cannot find module '@nativele/ts-dom'` in the package's files (pnpm) | the component package does not list it | step 3 |
+| `pnpm exec ts-dom ...` stops with `Command "ts-dom" not found`, and `npx ts-dom` asks the registry for an unrelated package named `ts-dom` (`404`) | the package where it runs does not list `@nativele/ts-dom` | step 3 |
+| `error [tsc-not-found]` and exit code 1 | `typescript` is not resolvable from that package (it was only hoisted) | `typescript` in the package's `devDependencies` |
+| `stale-generated` for the app's files right after a run elsewhere | one run covered several packages' folders (limitation 4) | run each package on its own folder; regenerate with `ts-dom gen src` in the app |
+| `error [duplicate-define]` mentioning `TS2717` | two packages define the same tag (limitation 5) | rename one tag |
+| `tsc-failed`: `vue-tsc did not check the types` in one package only | `ts-dom check` runs `vue-tsc` where that package lists it; with TypeScript 7 it fails | see the TypeScript Skill (`nativele-typescript`) |
+| `npm i -D -w @acme/ui ...` reports success but the package's `package.json` is unchanged | npm 11.19.1 did not save to a workspace folder created after the last install | run `npm i` at the root once, then the command again |
+| pnpm prints `Agent skills awaiting approval: @nativele/ts-dom` on install | a pnpm 12 permissions message; `ts-dom skills` and `ts-dom skills add` worked without approving | the user decides with `pnpm approve` |
+
+## See also
+
+- One scanned folder, and components outside the scanned folders: https://github.com/Pixmi/nativele/blob/main/docs/architecture.md#generated-files-checks-and-tsconfig
+- How a template brings in child components, and `ts-dom-tags.ts`: https://github.com/Pixmi/nativele/blob/main/docs/components.md#composition-using-multiple-components-together
+- Scanning several folders, the generated files, `ts-dom gen --check` and `--watch`: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#installation-and-setup
+- What `ts-dom check` and `ts-dom doctor` check, and how `check` picks `vue-tsc`: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#checks
+- The tsconfig of each package: https://github.com/Pixmi/nativele/blob/main/skills/nativele-typescript/SKILL.md
+- The Vite plugin, `dirs` and the build script: https://github.com/Pixmi/nativele/blob/main/skills/nativele-vite/SKILL.md
+- How Skills share a project, and who owns which configuration: https://github.com/Pixmi/nativele/blob/main/skills/README.md#how-skills-work-together

package/skills/nativele-react/SKILL.md

@@ -3,8 +3,8 @@ name: nativele-react
 description: "Use Nativele web components inside a React 19 app: passing props, receiving events, children and slots, lifecycle, and TSX types. Use when a project depends on react and @nativele/ts-dom."
 metadata:
   tier: official
-  nativele: ">=0.5.1 <0.6.0"
-  verified: "2026-11-05"
+  nativele: ">=0.6.0 <0.7.0"
+  verified: "2026-11-06"
   tools: "react@19.3.1 react-dom@19.3.1 @types/react@19.3.0 @types/react-dom@19.3.0 vite@8.3.5 @vitejs/plugin-react@6.2.1 typescript@7.0.2"
   author: "Nativele maintainers"
   detects: "react"
@@ -24,20 +24,20 @@ Nativele components are native custom elements. React renders them like any othe
 
 | Tool | Verified version |
 |---|---|
-| @nativele/ts-dom | 0.5.1 (the last agent trial) |
+| @nativele/ts-dom | 0.6.0 (the last agent trial) |
 | react, react-dom | 19.3.1 |
 | @types/react, @types/react-dom | 19.3.0 |
 | vite | 8.3.5 |
 | @vitejs/plugin-react | 6.2.1 |
 | typescript | 7.0.2 |
 
-Verified on 2026-11-05 in Google Chrome 148 with the example project in the Nativele repository (`skills/nativele-react/example`), and by an agent trial: a fresh agent did real work with only the Skill, and the result was checked independently. The example is a reference; it is not run in CI. With a different major version of React, treat every step as unverified.
+Verified on 2026-11-06 in Google Chrome 148 with the example project in the Nativele repository (`skills/nativele-react/example`), and by an agent trial: a fresh agent did real work with only the Skill, and the result was checked independently. The example is a reference; it is not run in CI. With a different major version of React, treat every step as unverified.
 
 ## Set-up
 
 1. Keep the Nativele components in their own folder, for example `src/nv/`, each as `x.html` plus `x.ts`. Write them with the core Skill: `npx ts-dom skills add nativele-core`.
 2. Install: `npm i @nativele/ts-dom`.
-3. Set `"strict": true` in the tsconfig whose `include` covers that folder (`tsconfig.app.json` in Vite's React template, which leaves it off); Nativele's type checks depend on it. Other configs, such as the one for `vite.config.ts`, stay as they are.
+3. The tsconfig whose `include` covers that folder (`tsconfig.app.json` in Vite's React template, which does not set `strict`) must meet Nativele's requirements: check and adjust it with the TypeScript Skill (`npx ts-dom skills nativele-typescript`).
 4. Add the Nativele Vite plugin next to the React plugin, pointing at that folder:
 
    ```ts
@@ -51,7 +51,7 @@ Verified on 2026-11-05 in Google Chrome 148 with the example project in the Nati
 
    Pass the same folder to every `ts-dom` command (`npx ts-dom check src/nv`), so there is one `ts-dom-tags.ts`, in `src/nv`.
 
-5. If the project lints with oxlint (`.oxlintrc.json`, as in Vite's React template), load the ts-dom rules there: add `{ "name": "ts-dom", "specifier": "@nativele/ts-dom/oxlint" }` to `jsPlugins` and `"ts-dom/unused-markup": "error"` to `rules`.
+5. If the project lints (Vite's React template has oxlint), the ts-dom rules go into its linter: follow the linting Skill (`npx ts-dom skills nativele-linting`).
 
 6. Import every Nativele component module in the entry file, before React renders anything:
 
@@ -89,7 +89,7 @@ Verified on 2026-11-05 in Google Chrome 148 with the example project in the Nati
 
    The component class must be exported and passed to `define()` in a folder that `ts-dom gen` scans, so it appears in `ts-dom-tags.ts`.
 
-The generated files are not committed, so on a clean checkout the type check in `npm run build` runs before anything has written them and fails with `TS2307: Cannot find module './x.html.js'`. Generate them first: `"build": "ts-dom gen src/nv && tsc -b && vite build"` (the template's script with `ts-dom gen src/nv &&` in front).
+The generated files are not committed, so on a clean checkout the type check in `npm run build` runs before anything has written them and fails with `TS2307: Cannot find module './x.html.js'` (why: `nativele-typescript`). Generate them first: `"build": "ts-dom gen src/nv && tsc -b && vite build"` (the template's script with `ts-dom gen src/nv &&` in front). CI starts from such a checkout; the rest of what its job needs is in `npx ts-dom skills nativele-ci`.
 
 ## Example
 
@@ -187,7 +187,7 @@ npx tsc --noEmit -p tsconfig.app.json   # expect: no errors (keep one @ts-expect
 npm run build                # expect: ✓ built (it runs ts-dom gen, tsc -b and vite build)
 ```
 
-Pass `tsc` the tsconfig from step 3. A root `tsconfig.json` that only lists `references` (as in Vite's template) checks nothing itself, so `tsc --noEmit` without `-p` passes even with type errors.
+Pass `tsc` the tsconfig from step 3: the template's root `tsconfig.json` only lists `references`, so `tsc --noEmit` without `-p` checks nothing (`nativele-typescript`).
 
 In the browser, render a component with an object prop and an event handler, and check that the element has no `item` attribute (`el.getAttributeNames()`), that `el.item` is the object, and that the handler fires once per click. A reference implementation of these checks is the [`verify.mjs`](https://github.com/Pixmi/nativele/blob/main/skills/nativele-react/example/verify.mjs) of the trial's example project, which does them with Playwright, plus children that React reorders, adds and removes inside a `shadow: true` component and inside stable wrappers in a Light DOM component. A Light DOM component has no `<slot>` elements once rendered; check where the children ended up with `el.assignedNodes(name)`, where `""` is the default slot.
 
@@ -195,7 +195,7 @@ In the browser, render a component with an object prop and an event handler, and
 
 | Symptom | Cause | Fix |
 |---|---|---|
-| `TS2307: Cannot find module './x.html.js'` from `npm run build` on a clean checkout | `tsc -b` runs before the generated files exist | start the script with `ts-dom gen src/nv &&` |
+| `TS2307: Cannot find module './x.html.js'` from `npm run build` on a clean checkout | `tsc -b` runs before the generated files exist | start the script with `ts-dom gen src/nv &&`; for CI, `nativele-ci` |
 | An object prop shows `[object Object]` or is missing | the component was rendered before `define()` ran | import the component module in the entry file before rendering |
 | The event handler never runs | the prop name is camelCased (`onItemSelect`) | use `on` plus the exact event name (`onitem-select`) |
 | `insertBefore`/`removeChild` errors, the React root disappears | React children changed inside a Light DOM component with slots | use `shadow: true`, or stable wrapper elements per slot |
@@ -207,3 +207,6 @@ In the browser, render a component with an object prop and an event handler, and
 - Components, props and events: https://github.com/Pixmi/nativele/blob/main/docs/components.md
 - Slots, Light DOM and Shadow DOM: https://github.com/Pixmi/nativele/blob/main/docs/components.md#light-default-and-shadow
 - Setup and checks: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md
+- The tsconfig: https://github.com/Pixmi/nativele/blob/main/skills/nativele-typescript/SKILL.md
+- The ts-dom rules in the project's linter: https://github.com/Pixmi/nativele/blob/main/skills/nativele-linting/SKILL.md
+- CI: https://github.com/Pixmi/nativele/blob/main/skills/nativele-ci/SKILL.md

package/skills/nativele-state-management/SKILL.md

@@ -3,8 +3,8 @@ name: nativele-state-management
 description: "Decide where state lives in an app built with Nativele (component state, a shared createStore, or an existing Zustand, Redux Toolkit or nanostores store) and connect external stores to this.bind with a small adapter: selectors that limit re-rendering, actions and dispatch from event handlers, unsubscribing when a component is removed. Use when a project depends on @nativele/ts-dom and on zustand, @reduxjs/toolkit, redux or nanostores, or when components need to share data."
 metadata:
   tier: official
-  nativele: ">=0.5.2 <0.6.0"
-  verified: "2026-11-05"
+  nativele: ">=0.6.0 <0.7.0"
+  verified: "2026-11-06"
   tools: "zustand@5.0.16 @reduxjs/toolkit@2.14.0 redux@5.0.1 nanostores@1.5.5 vite@8.3.6 typescript@7.0.2 create-vite@9.3.4"
   author: "Nativele maintainers"
   detects: "zustand @reduxjs/toolkit redux nanostores"
@@ -24,7 +24,7 @@ metadata:
 
 | Tool | Verified version |
 |---|---|
-| @nativele/ts-dom | 0.5.2 (the last agent trial) |
+| @nativele/ts-dom | 0.6.0 (the last agent trial) |
 | zustand (`zustand/vanilla`) | 5.0.16 |
 | @reduxjs/toolkit | 2.14.0 |
 | redux | 5.0.1 (installed by `@reduxjs/toolkit`; a `legacy_createStore` store with the adapter was checked by hand with `tsc` and Node) |
@@ -33,7 +33,7 @@ metadata:
 | typescript | 7.0.2 |
 | create-vite (`vanilla-ts` template, the starting point) | 9.3.4 |
 
-Verified on 2026-11-05 in Google Chrome 148 with the example project in the Nativele repository (`skills/nativele-state-management/example`), and by an agent trial: a fresh agent did real work with only the Skill, and the result was checked independently. The example is a reference; it is not run in CI. With a different major version of a state library, treat the adapter and every limitation about that library as unverified.
+Verified on 2026-11-06 in Google Chrome 148 with the example project in the Nativele repository (`skills/nativele-state-management/example`). With a different major version of a state library, treat the adapter and every limitation about that library as unverified.
 
 ## Set-up