@nativele/ts-dom 0.4.6 → 0.5.1

package/skills/README.md

@@ -0,0 +1,135 @@
+# Nativele Skills
+
+Skills extend what Nativele can be used with, without growing the library: each one is a task procedure for a coding agent, verified with exact versions. This page is the specification every Skill follows and the guide for contributing one.
+
+## What a Skill is
+
+A Skill is a task procedure for a coding agent: how to do one integration or one kind of work with Nativele, step by step, with a complete example, the known limitations, and commands that prove it worked. It is not reference documentation: facts about the library's API live in `docs/`, and a Skill links to them instead of restating them.
+
+An integration Skill (a framework, a build tool, a library) starts from a project that already uses that tool and teaches how to bring Nativele into it: what to add, what to change, and what to watch for. It does not teach how to set the tool itself up from nothing; the tool's own documentation and starter projects cover that.
+
+A Skill never changes the library's runtime and never adds a dependency to the library's core. Third-party packages a Skill uses are dependencies of the user's project, installed by the Skill's own steps.
+
+## Layout
+
+```
+skills/
+├── README.md                     # this specification and the contribution guide
+├── nativele-core/
+│   └── SKILL.md
+├── nativele-react/
+│   ├── SKILL.md
+│   └── example/                  # Official only: the project the Skill is verified with
+│       ├── package.json          # exact versions of every tool the Skill names
+│       ├── ...                   # the minimal app the SKILL.md example comes from
+│       └── verify.mjs            # the browser checks `npm run verify` ends with
+└── ...
+```
+
+The npm package ships every `SKILL.md` (so the CLI can list and read them offline), not the `example/` folders.
+
+## SKILL.md format
+
+`SKILL.md` follows the Agent Skills format (YAML frontmatter with `name` and `description`, then Markdown), so Claude Code and other agents that read skills can load it as it is. Nativele's own fields go under `metadata`:
+
+```markdown
+---
+name: nativele-react
+description: "Use Nativele web components inside a React 19 app: props, events, children and slots, lifecycle, and TSX types. Use when a project has react and @nativele/ts-dom."
+metadata:
+  tier: official                 # official | community | experimental
+  nativele: ">=0.5.0 <0.6.0"     # the library versions the Skill was verified with
+  verified: "2026-11-05"         # date of the last verification
+  tools: "react@19.3.1 react-dom@19.3.1 vite@8.3.5 @vitejs/plugin-react@6.2.1 typescript@7.0.2"
+  author: "Nativele maintainers" # for community Skills: the contributor
+  detects: "react"               # package.json dependencies that make ts-dom doctor recommend this Skill
+---
+```
+
+Quote the `description` and any value that contains `: `, so the frontmatter stays valid YAML for every agent that loads it.
+
+Required sections, in this order:
+
+1. **When to use**: the situation and the signals (dependencies, files) that call for this Skill, and when not to use it.
+2. **Versions**: a table of every tool and the exact version it was verified with, and the date. If the project uses a different major version of a tool, the Skill says so and stops treating its steps as verified.
+3. **Set-up**: numbered steps with the exact commands and file contents, starting from a working project of the tool (for an integration Skill) and covering only what Nativele adds or changes.
+4. **Example**: a complete, minimal working example (every file it needs, short).
+5. **Known limitations**: what does not work or needs care, each with what to do instead. An agent must never have to guess these.
+6. **Verify**: the commands that prove the integration works in the user's project (for example `npx ts-dom check`, `npx tsc --noEmit`, the project's build, a test), with the output to expect.
+7. **Troubleshooting**: symptoms seen while verifying, their cause and fix.
+8. **See also**: links to the guides in `docs/` for the facts used.
+
+Rules for the content:
+
+- Only what was run: every step, example and limitation comes from the verified example, not from memory of how a tool used to work.
+- Version-bound statements say so ("React 19 passes object props as properties; React 18 passes everything as attributes").
+- No promises beyond the verified versions.
+- English, plain and concrete; no restating of `docs/`.
+
+## Tiers
+
+| Tier | Who maintains it | Requirements | Shown by `ts-dom skills` |
+|---|---|---|---|
+| Official | the Nativele maintainers | accepted through an agent trial, and an `example/` project that `npm run verify` checks in CI; verified within the last 6 months | as official |
+| Community | its author | the full SKILL.md format, `author` and `verified` filled in, accepted through a maintainer's agent trial | as community, with the author |
+| Experimental | its author | the SKILL.md format; verification not complete | as experimental, with a warning |
+
+- A new contribution starts as Experimental. It becomes Community when it passes a maintainer's agent trial (see "How a Skill pull request is accepted"), and Official when the maintainers adopt it with an `example/` project in CI.
+- A Skill whose `verified` date is older than 6 months, or whose `nativele` range does not include the installed version, is shown as stale. A stale Official Skill whose CI check fails is moved to Experimental until fixed.
+
+## Delivering Skills to projects
+
+The library already lives in the user's `node_modules`, so its Skills travel with it:
+
+- `ts-dom skills` lists the Skills shipped with the installed version: name, tier, description, verified date and versions, whether it is stale, and its path inside `node_modules`. `--json` prints the same as data for agents.
+- `ts-dom skills <name>` prints that Skill (so an agent can read it without knowing the path).
+- `ts-dom skills add <name...>` copies Skills into the project: into `.claude/skills/<name>/` when the project has a `.claude` folder, otherwise into `.agents/skills/<name>/` (`--to=<dir>` for another folder), where agents that load skills pick them up. It only copies; it never installs the third-party packages a Skill mentions.
+- `ts-dom doctor` reads the project's `package.json` and, for each Skill whose `detects` dependency is present and that the project has no copy of, reports it as an `info` issue (`skill-available`); a copy that differs from the shipped one is reported as `skill-outdated`, for example: `package.json:1:1 info [skill-available] react is a dependency: the nativele-react Skill covers using Nativele components in React. Fix: run ts-dom skills add nativele-react, or read it with ts-dom skills nativele-react.` Info issues never change the exit code.
+
+None of this adds a runtime dependency: listing and copying read the Markdown files with Node's file API, and the frontmatter is parsed with a small reader for the fields above.
+
+## Verification of Official Skills
+
+- `skills/<name>/example/package.json` pins every tool version the Skill names, depends on the library through `file:../../..` (the library in the same repository), and has `npm run verify`, which runs `ts-dom check`, `ts-dom doctor`, `tsc`, the build, and a short real-browser test of what the Skill promises.
+- `nativele-core` has no example of its own: the library's CI, which checks every example in the repository, verifies it.
+- The workflow `.github/workflows/skills.yml` runs `npm run verify` for each Official Skill when an `example/` changes, when the library's runtime changes, and once a month, so a third-party release that breaks a Skill is found. A change to `SKILL.md` runs only `.github/workflows/skills-format.yml`, which checks every `SKILL.md` against this specification. Neither is a required check for `main`.
+- The monthly run opens nothing by itself; a failure is reported in the workflow run, and the Skill is fixed or moved to Experimental.
+
+## Contributing a Skill
+
+- Copy `skills/_template/SKILL.md`, fill in every section, set `tier: experimental`.
+- Run the Skill's verification commands in a fresh project with the versions you list, and paste their output in the PR description.
+- The PR touches only `skills/<name>/`; a PR that changes the library and adds a Skill is split. Community and Experimental Skills live in this repository, in the same `skills/` folder, so they ship with the package and `ts-dom skills` lists them with their tier.
+
+## How a Skill pull request is accepted
+
+A Skill is written for agents, so the maintainers accept it by having an agent use it: a fresh agent that knows nothing about the Skill does real work with nothing but the Skill, and the result is checked. Reading the Skill or rerunning its verification commands is not enough, because neither shows what the Skill leaves out.
+
+1. **Check the format**: the frontmatter is complete, every required section is there, the facts link to `docs/` instead of restating them, and nothing would add a dependency to the library's core.
+2. **Build the package from the PR branch** (`npm run build:lib && npm pack`), so the trial uses the real delivery path.
+3. **Start a fresh project** in an empty folder outside the repository: for an integration Skill, the tool's own starter project at the versions the Skill lists (for example `create-vite` with the `react-ts` template), built once to confirm it works before Nativele is added. Install the packed library and the exact tool versions the Skill lists, and install the Skill the way users do: `npx ts-dom skills add <name>`.
+4. **Give a fresh agent a task** that the Skill says it covers, written from its "When to use" and "Example": a small but real piece of work that goes through every set-up step and touches every known limitation. The agent may use the Skill, `npx ts-dom` and the public guides in `docs/`, but not the Nativele source, this repository or the Skill's `example/`. It reports the files it wrote, the output of every Verify command, every point where it had to guess or look elsewhere, and every error it hit and how it fixed it.
+5. **Check the result independently**, without relying on the agent's report: run the Verify commands again and check the behavior in a real browser or with a test.
+
+The Skill is accepted when:
+
+- every Verify command gives the expected output, and the work does what the task asked;
+- the agent followed the Skill's steps as written, and no step was wrong for the stated versions;
+- every guess, outside search or unexplained error in the report is already covered by the Skill; a guess about the tool itself (how to configure the framework, the build tool or the test runner beyond what Nativele needs) is not a gap in the Skill.
+
+Otherwise the maintainers send the gaps back to the contributor as review comments (a missing step, a limitation to list, a Troubleshooting row to add), and the trial runs again, with a new agent, on the updated Skill. The record of the passing trial (agent and model, date, versions, Verify output) is added to the PR as a review comment.
+
+## Skills
+
+| Skill | Tier | Status | Covers |
+|---|---|---|---|
+| `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-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 | |

package/skills/_template/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: nativele-<tool>
+description: "What the Skill lets an agent do, and when to use it (the dependencies or files that call for it)."
+metadata:
+  tier: experimental
+  nativele: ">=0.5.0 <0.6.0"
+  verified: "YYYY-MM-DD"
+  tools: "<tool>@<exact version> <other tool>@<exact version>"
+  author: "<your name or GitHub handle>"
+  detects: "<package.json dependency names, space-separated>"
+---
+
+# Nativele + <tool>
+
+## When to use
+
+- The situation, and the signals (dependencies, files) that call for this Skill.
+- When not to use it.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | x.y.z |
+| <tool> | x.y.z |
+
+Verified on YYYY-MM-DD. With a different major version of <tool>, treat every step as unverified.
+
+## Set-up
+
+1. Numbered steps with the exact commands and file contents.
+
+## Example
+
+The complete, minimal working example: every file it needs.
+
+## Known limitations
+
+1. What does not work or needs care, and what to do instead.
+
+## Verify
+
+```sh
+npx ts-dom check     # expect: ts-dom check: no issues
+npx tsc --noEmit     # expect: no errors
+```
+
+What to check in the browser or with a test.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+
+## See also
+
+- Links to the guides in https://github.com/Pixmi/nativele/tree/main/docs for the facts used.

package/skills/nativele-angular/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: nativele-angular
+description: "Use Nativele web components inside an existing Angular 22 app with standalone components: CUSTOM_ELEMENTS_SCHEMA, property and event bindings, change detection, content projection into slots, lifecycle, and generating the templates for the Angular CLI build. Use when a project depends on @angular/core and @nativele/ts-dom."
+metadata:
+  tier: experimental
+  nativele: ">=0.5.1 <0.6.0"
+  verified: "2026-11-05"
+  tools: "@angular/core@22.2.4 @angular/compiler-cli@22.2.4 @angular/build@22.2.6 @angular/cli@22.2.6 typescript@6.0.3 vitest@5.1.0 jsdom@30.1.3"
+  author: "Nativele maintainers"
+  detects: "@angular/core"
+---
+
+# Nativele + Angular
+
+## When to use
+
+- The project is an Angular 22 app with standalone components (as made by `ng new`) and wants to use components written with Nativele (`@nativele/ts-dom`), for example widgets shared with non-Angular pages.
+- Signals: `@angular/core` and `@nativele/ts-dom` in `package.json`, `angular.json`, Angular templates that use tags such as `<info-card>`.
+- Not for writing the Nativele components themselves: use `nativele-core` (`npx ts-dom skills add nativele-core`).
+- Not verified with NgModule-based apps, server-side rendering or hydration, or Angular versions other than 22.
+
+Nativele components are native custom elements. Angular renders their tags like any other DOM element; nothing wraps them.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.5.1 |
+| @angular/core, @angular/common, @angular/compiler, @angular/compiler-cli, @angular/platform-browser, @angular/router | 22.2.4 |
+| @angular/cli, @angular/build | 22.2.6 |
+| typescript | 6.0.3 |
+| vitest (through `ng test`) | 5.1.0 |
+| jsdom | 30.1.3 |
+
+Verified on 2026-11-05 in Google Chrome 148, against `ng serve` (development and production configurations), in an app made with `npx @angular/cli@latest new <name> --defaults --skip-git`. That app is zoneless (no `zone.js`); the same checks also passed with `zone.js` 0.16.3 and `provideZoneChangeDetection()`. With a different major version of Angular, 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 `compilerOptions` of the root `tsconfig.json` (the Angular 22 CLI template leaves it out; `tsconfig.app.json` and `tsconfig.spec.json` extend the root, so both get it). Nativele's type checks depend on it. If turning it on for the whole app is not possible yet, set it in `tsconfig.app.json` only; `ts-dom doctor` then still warns about `tsconfig.spec.json`.
+4. Generate the template modules before every Angular command. The Angular CLI build (`@angular/build:application`) takes no Vite plugins from the project, so `tsDom()` cannot be added; run `ts-dom gen` from npm's `pre` scripts instead:
+
+   ```sh
+   npm pkg set scripts.prestart="ts-dom gen src/nv --whitespace=collapse" \
+               scripts.prebuild="ts-dom gen src/nv --whitespace=collapse" \
+               scripts.pretest="ts-dom gen src/nv --whitespace=collapse"
+   ```
+
+   `npm start`, `npm run build` and `npm test` then generate first (`npx ng ...` called directly does not). `--whitespace=collapse` is there because the CLI template sets up Prettier, and `ts-dom doctor` asks for it; doctor finds the flag in the `package.json` scripts. Collapsing also drops the whitespace between tags, so `textContent` reads `x1A1:new`, not `x1 A1:new`; write test expectations that way.
+
+   While `npm start` runs, keep a second terminal with `npx ts-dom gen src/nv --watch --whitespace=collapse`: editing a template or adding a component regenerates its module, and `ng serve` rebuilds and reloads the page.
+
+5. Pass the folder to every `ts-dom` command (`npx ts-dom check src/nv`). Without it the default is `src`, and `ts-dom` reads Angular's own templates (`src/app/*.html`) as Nativele templates and reports errors for them.
+6. Add the generated files to `.gitignore`:
+
+   ```gitignore
+   *.html.ts
+   ts-dom-tags.ts
+   ```
+
+7. Import every Nativele component module in `src/main.ts`, before `bootstrapApplication`:
+
+   ```ts
+   // src/main.ts
+   import "./nv/info-card.js";
+   import "./nv/shadow-card.js";
+   import "./nv/light-card.js";
+   import "./nv/live-badge.js";
+   import { bootstrapApplication } from '@angular/platform-browser';
+   import { appConfig } from './app/app.config';
+   import { App } from './app/app';
+
+   bootstrapApplication(App, appConfig)
+     .catch((err) => console.error(err));
+   ```
+
+   Angular sets `[prop]` bindings as properties even on an element that is not defined yet, and Nativele takes those values over when `define()` runs, so a late import loses no data; but until then the element is empty. Importing first makes the first render complete.
+
+8. Add `schemas: [CUSTOM_ELEMENTS_SCHEMA]` to every standalone component whose template uses a Nativele tag. Without it the build fails with `NG8001: 'info-card' is not a known element` and `NG8002: Can't bind to 'item' since it isn't a known property of 'info-card'`.
+
+## Example
+
+The Nativele components, as in `nativele-core`:
+
+```html
+<!-- src/nv/info-card.html -->
+<span>{{ label }}</span>
+<b>{{ count }}</b>
+<i data-ref="itemName"></i>
+<button type="button" data-on-click="pick">Pick</button>
+```
+
+```ts
+// src/nv/info-card.ts
+import { Component, define, event } from "@nativele/ts-dom";
+import tpl from "./info-card.html.js";
+
+export interface Item {
+  id: number;
+  name: string;
+}
+
+export class InfoCard extends Component(tpl, {
+  props: { label: "", count: 0, item: null as Item | null },
+  emits: { "item-select": event<{ id: number }>() },
+}) {
+  pick(): void {
+    const item = this.props.item;
+    if (item) this.emit("item-select", { id: item.id });
+  }
+  override render(view: { item: Item | null }): void {
+    this.refs.itemName.textContent = view.item ? view.item.name : "-";
+  }
+}
+define("info-card", InfoCard);
+```
+
+```html
+<!-- src/nv/shadow-card.html and src/nv/light-card.html -->
+<h2><slot name="title">Untitled</slot></h2>
+<div><slot></slot></div>
+```
+
+```ts
+// src/nv/shadow-card.ts
+import { Component, define } from "@nativele/ts-dom";
+import tpl from "./shadow-card.html.js";
+
+export class ShadowCard extends Component(tpl, { shadow: true }) {}
+define("shadow-card", ShadowCard);
+```
+
+```ts
+// src/nv/light-card.ts
+import { Component, define } from "@nativele/ts-dom";
+import tpl from "./light-card.html.js";
+
+export class LightCard extends Component(tpl) {}
+define("light-card", LightCard);
+```
+
+```html
+<!-- src/nv/live-badge.html -->
+<span>{{ user }}</span>
+```
+
+```ts
+// src/nv/session.ts
+import { createStore } from "@nativele/ts-dom";
+
+export const session = createStore({ user: "Ada" });
+```
+
+```ts
+// src/nv/live-badge.ts
+import { Component, define } from "@nativele/ts-dom";
+import tpl from "./live-badge.html.js";
+import { session } from "./session.js";
+
+export class LiveBadge extends Component(tpl) {
+  override connected(): void {
+    this.bind(session, (s) => (this.text.user = s.user));
+  }
+}
+define("live-badge", LiveBadge);
+```
+
+The Angular component that uses them:
+
+```ts
+// src/app/app.ts
+import { Component, CUSTOM_ELEMENTS_SCHEMA, signal } from '@angular/core';
+import type { EmitEvent } from '@nativele/ts-dom';
+import type { InfoCard, Item } from '../nv/info-card.js';
+import { session } from '../nv/session.js';
+
+const fruits: Item[] = [
+  { id: 1, name: 'apple' },
+  { id: 2, name: 'pear' },
+  { id: 3, name: 'plum' },
+];
+
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.html',
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+})
+export class App {
+  protected readonly count = signal(0);
+  protected readonly item = signal<Item>(fruits[0]!);
+  protected readonly picked = signal<number[]>([]);
+  protected pickedPlain = '';
+  protected readonly fruits = signal(fruits);
+  protected readonly rows = signal(['a', 'b', 'c']);
+  protected readonly showTitle = signal(true);
+  protected readonly showBadge = signal(true);
+
+  select(e: Event): void {
+    const id = (e as EmitEvent<InfoCard, 'item-select'>).detail.id;
+    this.picked.update((p) => [...p, id]);
+    this.pickedPlain += id;
+  }
+  next(): void {
+    this.count.update((c) => c + 1);
+    this.item.set(fruits[1]!);
+  }
+  rotate(): void {
+    this.rows.update((r) => [r.at(-1)!, ...r.slice(0, -1)]);
+    this.fruits.update((f) => [f.at(-1)!, ...f.slice(0, -1)]);
+  }
+  toggleB(): void {
+    this.rows.update((r) => (r.includes('b') ? r.filter((x) => x !== 'b') : ['b', ...r]));
+  }
+  rename(): void {
+    session.set({ user: 'Grace' });
+  }
+}
+```
+
+```html
+<!-- src/app/app.html -->
+<info-card id="card" label="Fruit" [count]="count()" [item]="item()" (item-select)="select($event)" />
+<p id="picked">{{ picked().join(',') }}</p>
+<p id="picked-plain">{{ pickedPlain }}</p>
+<button type="button" id="next" (click)="next()">Next</button>
+
+<ul id="cards">
+  @for (f of fruits(); track f.id) {
+    <li><info-card [label]="f.name" [item]="f" (item-select)="select($event)" /><live-badge /></li>
+  }
+</ul>
+
+<shadow-card id="shadow">
+  @if (showTitle()) {
+    <span slot="title">Shadow</span>
+  }
+  @for (r of rows(); track r) {
+    <p>{{ r }}</p>
+  }
+</shadow-card>
+
+<light-card id="light">
+  <div slot="title">
+    @if (showTitle()) {
+      <span>Light</span>
+    }
+  </div>
+  <div>
+    @for (r of rows(); track r) {
+      <p>{{ r }}</p>
+    }
+  </div>
+</light-card>
+
+@if (showBadge()) {
+  <live-badge id="badge" />
+}
+
+<button type="button" id="rotate" (click)="rotate()">Rotate</button>
+<button type="button" id="toggle-b" (click)="toggleB()">Toggle b</button>
+<button type="button" id="toggle-title" (click)="showTitle.set(!showTitle())">Toggle title</button>
+<button type="button" id="toggle-badge" (click)="showBadge.set(!showBadge())">Toggle badge</button>
+<button type="button" id="rename" (click)="rename()">Rename</button>
+```
+
+- `[item]`, `[count]` and `[label]` are set as properties; the object is the same object the signal holds. A plain attribute (`label="Fruit"`) also fills a string prop.
+- `(item-select)` listens to the exact, hyphenated event name on the element. The handler receives the `CustomEvent`; read its data through `EmitEvent<InfoCard, 'item-select'>`.
+- A signal change re-renders the Nativele component in the same change detection pass. Changing state inside an `(item-select)` handler needs no extra call, in a zoneless app too, even for a plain field such as `pickedPlain`, because Angular runs change detection after every template listener.
+- `@for` with `track` moves `<info-card>` hosts when the list is reordered; they keep their props and listeners.
+
+## Known limitations
+
+1. **`CUSTOM_ELEMENTS_SCHEMA` turns off binding checks for unknown elements.** With it, Angular's compiler accepts any property on any hyphenated tag: `[item]="42"`, `[count]="'x'"` and `[nope]="1"` on `<info-card>` all build without an error. Angular has no mechanism to type-check bindings on custom elements, so keep the values typed in the Angular class (`signal<Item>(...)`) and check the Nativele side with `ts-dom check src/nv`.
+2. **`$event` is typed `Event`.** Angular's template type checker types `$event` of a DOM event it does not know as `Event`, so `select($event.detail)` or a handler parameter typed `CustomEvent<...>` fails with `TS2339: Property 'detail' does not exist on type 'Event'` or `TS2345: Argument of type 'Event' is not assignable to parameter of type 'CustomEvent<...>'`. Take `Event` and cast it with `EmitEvent<Component, 'event-name'>` from `@nativele/ts-dom`; a wrong event name there becomes `never` and fails with `Property 'detail' does not exist on type 'never'`. Nothing checks that the cast names the element the listener is on.
+3. **Bind properties, not attributes, for objects.** `[attr.item]="item()"` writes the attribute `item="[object Object]"` and the prop stays `null`. `[attr.count]` works for a number prop (the attribute text is converted), but `[count]` is simpler.
+4. **Light DOM slots and Angular-managed children do not mix.** In the default Light DOM mode (`Component(tpl)` without `shadow`), Nativele moves the host's children into its slot positions. When `@if` or `@for` sit directly inside the tag, Angular still adds and removes nodes, but a node it re-inserts lands in the wrong place: a `<span slot="title">` brought back by `@if` ends up in the default slot while the title shows its fallback, and `assignedNodes()` stops matching the page. Angular reports no error. Use one of:
+   - `shadow: true` on the component; `@if` and `@for` children can then change freely;
+   - one stable element per slot that Angular never removes, with `@if`/`@for` inside it (the `light-card` above). A stable but empty wrapper still fills its slot, so the slot's fallback content does not show; when the fallback matters, use `shadow: true`.
+5. **Zoneless rendering is scheduled.** In the CLI's default zoneless app, Angular updates the DOM after a click in a later task, so code that calls `button.click()` and reads the DOM right away sees the old values; with `zone.js` the DOM is already updated when `click()` returns. A test that reads the DOM right after dispatching an event must wait (Playwright: wait for the expected text; TestBed: `await fixture.whenStable()`). The Nativele component itself renders synchronously as soon as Angular sets the property.
+6. **State changed outside Angular's listeners.** In a zoneless app, a plain field set from a Nativele store subscription (`session.subscribe(...)` in an Angular class) or a `setTimeout` does not re-render the Angular view; put the value in a signal. Nativele components that `bind` the store update themselves either way.
+7. **`ng serve` started before the modules were generated stays broken.** It fails with `Could not resolve "./info-card.html.js"` and does not rebuild when `ts-dom gen` creates the files later. Use `npm start` (step 4 runs `gen` first), or restart `ng serve`, or save one of the component `.ts` files.
+8. **Lifecycle.** `@if` removing a host runs `disconnected()` and ends its `bind` subscriptions; inserting it again runs `connected()` and subscribes again. `@for` reordering moves hosts, which runs `disconnected()` and `connected()` on them; `bind` keeps working after the move.
+9. **Unit tests.** `main.ts` is not loaded by `ng test`: import the Nativele modules at the top of each spec that renders their tags. `tsconfig.spec.json` includes only `*.spec.ts` and `*.d.ts`, so `HTMLElementTagNameMap['info-card']` is not known there; import the class type (`import type { InfoCard } from '../nv/info-card.js'`). Nativele components render in `ng test`'s jsdom environment.
+10. Not verified: NgModule-based apps, server-side rendering and hydration, Angular forms (`ngModel`, reactive forms) bound to Nativele components, `ng build --watch`, and Angular versions other than 22.
+
+## Verify
+
+Run in the project:
+
+```sh
+npx ts-dom gen src/nv --whitespace=collapse          # writes the modules; prints nothing
+npx ts-dom check src/nv --whitespace=collapse        # expect: ts-dom check: no issues
+npx ts-dom doctor src/nv     # expect: ts-dom doctor: the set-up looks right (info lines are suggestions)
+npx ngc -p tsconfig.app.json --noEmit                # expect: no output, exit code 0
+npm run build                # expect: Application bundle generation complete.
+npm test -- --watch=false    # expect: the specs pass
+```
+
+- `ts-dom check` runs `tsc` on the app's TypeScript through the references of the root `tsconfig.json`, so it reports a type error in `src/app/app.ts` too. It does not read Angular templates. `ngc` (or the build) is what type-checks the Angular templates, including the `EmitEvent` casts.
+- Run `ts-dom check` with `--whitespace=collapse` or after `gen`: when the generated files are missing, `check` writes them with whitespace kept as written; once they exist, it keeps the mode they were written with.
+
+In the browser, against `npm start` (the development server shows Angular's warnings in the console), check:
+
+- the element has no attribute for the object prop (`el.getAttributeNames()`) and `el.item` is the object;
+- a click on the component's button runs the `(item-select)` handler once and updates the Angular view;
+- after `@for` reorders hosts, each keeps its own `item`, and its events still fire;
+- removing a host with `@if` ends its `bind` subscription: keep a reference to the removed element, change the store, and its text stays old;
+- children that `@if`/`@for` toggle, reorder, add and remove stay in the right slot; read a slot with `el.assignedNodes(name)` (`""` is the default slot), which works in both modes, and compare elements, since Angular leaves comment anchors among the children;
+- no errors or warnings in the console.
+
+With Playwright, wait for each expected change instead of reading the DOM right after a click (limitation 5).
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `NG8001: 'info-card' is not a known element` | the standalone component has no `CUSTOM_ELEMENTS_SCHEMA` | add `schemas: [CUSTOM_ELEMENTS_SCHEMA]` to that component |
+| `NG8002: Can't bind to 'item' since it isn't a known property of 'info-card'` | the same | the same |
+| `TS2339: Property 'detail' does not exist on type 'Event'`, or `Argument of type 'Event' is not assignable to parameter of type 'CustomEvent<...>'` | Angular types `$event` of a custom event as `Event` | take `Event` in the handler and cast with `EmitEvent<Component, 'event-name'>` |
+| `Property 'detail' does not exist on type 'never'` | `EmitEvent` names an event the component does not emit | use the exact name from the component's `emits` |
+| `Could not resolve "./info-card.html.js"` from `ng build` or `ng serve` | the template modules were not generated | run `ts-dom gen src/nv --whitespace=collapse`; use `npm start`/`npm run build`, which run it first (step 4); restart a running `ng serve` |
+| An object prop is `null`, and the element has `item="[object Object]"` | `[attr.item]` was used | bind the property: `[item]` |
+| The element stays empty | its module is not imported | import it in `src/main.ts` (step 7) |
+| A slotted child shows in the wrong slot or the slot fallback stays visible | `@if`/`@for` directly inside a Light DOM component with slots | `shadow: true`, or a stable element per slot |
+| `ts-dom check` reports `invalid-hole` or `no-importer` in `src/app/app.html` | the command ran without a folder and read Angular templates | pass the Nativele folder: `ts-dom check src/nv` |
+| `ts-dom doctor` warns `tsconfig-not-strict` | the Angular 22 CLI template does not set `strict` | step 3 |
+| `ts-dom doctor` warns `formatter-whitespace` | Prettier is set up and no script generates with `--whitespace=collapse` | step 4 |
+| `Property 'info-card' does not exist on type 'HTMLElementTagNameMap'` in a spec | `tsconfig.spec.json` does not include `ts-dom-tags.ts` | import the component class type instead |
+| The Angular view does not update after a store change or a timer | zoneless change detection does not run for plain fields changed outside template listeners | keep that value in a signal |
+
+## See also
+
+- Components, props, events and `EmitEvent`: https://github.com/Pixmi/nativele/blob/main/docs/components.md#data-flow-props-down-events-up
+- Slots, Light DOM and Shadow DOM: https://github.com/Pixmi/nativele/blob/main/docs/components.md#light-default-and-shadow
+- Lifecycle and `bind`: https://github.com/Pixmi/nativele/blob/main/docs/components.md#components
+- Stores: https://github.com/Pixmi/nativele/blob/main/docs/components.md#state-store-when-not-using-state
+- Setup, `gen --watch`, whitespace and checks: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md
+- A framework integration with typed templates: `npx ts-dom skills nativele-react`