@nativele/ts-dom 0.5.0 → 0.5.1

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`

package/skills/nativele-core/SKILL.md

@@ -30,10 +30,92 @@ Verified on 2026-11-05 by the library's own CI, which type-checks, lints and run
 
 ## Set-up
 
-1. `npm i @nativele/ts-dom` and `npm i -D typescript`.
-2. `tsconfig.json` with `"strict": true`, `"lib"` including `"DOM"`, and `"moduleResolution"` `"NodeNext"` or `"bundler"`; its `include` must cover the folders with templates.
-3. With Vite, add `tsDom()` from `@nativele/ts-dom/vite` to `plugins` and set `"type": "module"` in `package.json`. Without a bundler, `ts-dom gen` plus `tsc` is enough.
-4. Run `npx ts-dom doctor` once; fix every error and warning it reports. Its `info` lines name the other Skills that fit the project.
+1. `npm i @nativele/ts-dom` and `npm i -D typescript`, and set `"type": "module"` in `package.json` (with or without a bundler).
+2. Put the components under `src/`, the folder every `ts-dom` command scans by default; for another folder, pass it to each command (`npx ts-dom check web/ui`).
+3. `tsconfig.json` with `"strict": true`, `"lib"` including `"DOM"`, and `"moduleResolution"` `"NodeNext"` or `"bundler"`; its `include` must cover the folders with templates. A complete one for the no-bundler case is in the setup guide: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#installation-and-setup
+4. With Vite, add `tsDom()` from `@nativele/ts-dom/vite` to `plugins`. Without a bundler, `ts-dom gen` plus `tsc` compiles the code, and the page needs an import map for `@nativele/ts-dom` plus a `<script type="module">` for the compiled entry, a module that imports the top-level components: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#running-in-the-browser-no-bundler
+5. Add `*.html.ts` and `ts-dom-tags.ts` to `.gitignore`: they are generated.
+6. Run `npx ts-dom doctor` once; fix every error and warning it reports. Its `info` lines name the other Skills that fit the project.
+
+## Example
+
+A list whose items are components, with a store, a derived value and events from the items:
+
+```html
+<!-- src/todo-item.html -->
+<input type="checkbox" data-ref="check" data-on-change="onToggle" />
+<span>{{ text }}</span>
+<button type="button" data-on-click="onRemove">remove</button>
+```
+
+```ts
+// src/todo-item.ts
+import { Component, define, event } from "@nativele/ts-dom";
+import tpl from "./todo-item.html.js";
+import type { Todo } from "./store.js";
+
+export class TodoItem extends Component(tpl, {
+  props: { todo: { id: 0, title: "", done: false } as Todo },
+  derive: { text: (v) => v.todo.title },
+  emits: { toggled: event(), removed: event() },
+}) {
+  onToggle(): void {
+    this.emit("toggled");
+  }
+  onRemove(): void {
+    this.emit("removed");
+  }
+  override render(view: { todo: Todo }, changed: ReadonlySet<"todo">): void {
+    if (changed.has("todo")) this.refs.check.checked = view.todo.done;
+  }
+}
+define("todo-item", TodoItem);
+```
+
+```html
+<!-- src/todo-app.html -->
+<p data-if="empty">Nothing to do</p>
+<ul>
+  <template data-each="items" data-key="id" data-prop="todo">
+    <todo-item role="listitem" data-on-toggled="toggle" data-on-removed="drop"></todo-item>
+  </template>
+</ul>
+<p>{{ remaining }} left</p>
+```
+
+```ts
+// src/todo-app.ts
+import { Component, define, type EventHit } from "@nativele/ts-dom";
+import tpl from "./todo-app.html.js";
+import { todos, type Todo } from "./store.js"; // export const todos = createStore<readonly Todo[]>([]);
+import "./todo-item.js";
+
+export class TodoApp extends Component(tpl, {
+  state: { items: [] as readonly Todo[] },
+  derive: {
+    remaining: (v) => v.items.filter((t) => !t.done).length,
+    empty: (v) => v.items.length === 0,
+  },
+}) {
+  override connected(): void {
+    this.bind(todos, (items) => this.set({ items }));
+  }
+  toggle(_e: Event, hit: EventHit<Todo, "id">): void {
+    todos.set((s) => s.map((t) => (t.id === hit.key ? { ...t, done: !t.done } : t)));
+  }
+  drop(_e: Event, hit: EventHit<Todo, "id">): void {
+    todos.set((s) => s.filter((t) => t.id !== hit.key));
+  }
+  override render(view: { items: readonly Todo[] }, changed: ReadonlySet<"items">): void {
+    if (changed.has("items")) this.lists.items.items = view.items;
+  }
+}
+define("todo-app", TodoApp);
+```
+
+- A `derive` function takes one argument: the state and props merged into one read-only object (other derived values are not in it).
+- `emits` declares each event with `event()`, or `event<Detail>()` when it carries data; send the data with `this.emit("name", detail)`. The parent listens with `data-on-<event>` on the child tag and reads the data as `(e as EmitEvent<Child, "name">).detail`, because an HTML attribute cannot carry the event's type.
+- `bind` goes in `connected()`; the subscription is released when the element is removed.
 
 ## The loop
 
@@ -47,14 +129,15 @@ Verified on 2026-11-05 by the library's own CI, which type-checks, lints and run
 
 - No expressions in HTML: `{{ name }}` is a single identifier. Compute in `derive` (or in TypeScript) and fill a named hole.
 - Change state only with `this.set()`. Rendering is synchronous; `this.batch()` combines updates.
-- Once a component has `state`, `props` or `derive`, every `{{ hole }}` and `data-if` must name one of them. Show store data by copying it into state in the `bind` callback.
+- Once a component has `state`, `props` or `derive`, every `{{ hole }}` and `data-if` outside a `<template data-each>` must name one of them (holes inside a plain-element list are filled by `replace`). Show store data by copying it into state in the `bind` callback.
 - `store.set` replaces the whole value; a component's `this.set` merges. Spread the rest yourself: `store.set((s) => ({ ...s, status: "loading" }))`.
 - Lists, attributes and focus go in `render(view, changed)`. `changed` holds the state, prop and derived names that changed; annotate it with the names you check (`changed: ReadonlySet<"items" | "visible">`), never `ReadonlySet<string>`.
 - Props go down (the parent sets them), events go up (`emit`, handled with `data-on-<event>` on the child tag). `emit` does not bubble; data needed several levels away goes in a shared `createStore` that the components `bind`.
 - State, props and the view are deeply read-only: replace objects instead of changing them (`{ ...todo, done: true }`).
 - A `data-each` list cannot be nested: the inner list belongs to its own item component.
-- For a list of components, write `data-key` and `data-prop` on the `<template data-each>`, give the item component `role="listitem"` inside `<ul>` or `<ol>`, assign `this.lists.x.items = ...` in `render`, and type item handlers as `hit: EventHit<Item, "id">`.
-- Do not name a handler or prop like a DOM or Nativele member (`remove`, `click`, `title`, `render`, ...); `ts-dom check` reports it.
+- A list of plain elements (no item component) has neither `data-key` nor `data-prop`; fill it with `this.lists.x.replace(items, key, fill)` in `render`: https://github.com/Pixmi/nativele/blob/main/docs/lists.md
+- For a list of components, write `data-key` and `data-prop` on the `<template data-each>`, give the item component `role="listitem"` inside `<ul>` or `<ol>`, assign `this.lists.x.items = ...` in `render`, and type item handlers as `hit: EventHit<Item, "id">`. Each item component gets its item through that one prop; to pass more (selected, leading), map the items to objects that carry it before assigning.
+- Do not name a handler or prop like a DOM or Nativele member (`remove`, `click`, `title`, `text`, `refs`, `state`, `render`, ...), or an emitted event like a native event (`click`, `change`, `input`, ...); `ts-dom check` reports both.
 
 ## Known limitations
 
@@ -77,6 +160,8 @@ Then exercise the changed component in a real browser (the project's own test ru
 
 | Symptom | Cause | Fix |
 |---|---|---|
+| `ReferenceError: exports is not defined` in the browser | `package.json` has no `"type": "module"`, so `tsc` emitted CommonJS | set `"type": "module"`, delete the output folder, run `tsc` again |
+| `Failed to resolve module specifier "@nativele/ts-dom"` | no bundler and no import map | add the import map from the setup guide before the module script |
 | `Cannot find module './x.html.js'` | the generated file is missing | run `npx ts-dom check` (or `ts-dom gen`) |
 | `missing-binding` at a template line | a hole or `data-if` name that state, props and derive do not have | add the field, or rename the hole |
 | A list stays empty | `render` never assigns it, or guards it with a name that is not in `changed` | assign `this.lists.x.items` in `render`, guarded by the name of what it shows |

package/skills/nativele-integration/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: nativele-integration
+description: "Use Nativele web components inside an app built with a UI framework that has no Nativele Skill of its own (Preact, Solid, Lit, ...; React, Vue, Svelte and Angular have their own): defining before render, props as properties, listening to events, children and slots, lifecycle, and template types. Use when a project depends on @nativele/ts-dom and on such a framework."
+metadata:
+  tier: experimental
+  nativele: ">=0.5.1 <0.6.0"
+  verified: "2026-11-05"
+  tools: "vue@3.5.44 vite@8.3.6 @vitejs/plugin-vue@6.0.10 vue-tsc@3.3.14 typescript@6.0.3"
+  author: "Nativele maintainers"
+  detects: "preact solid-js"
+---
+
+# Nativele in a framework app
+
+## When to use
+
+- The app is built with a UI framework and wants to use components written with Nativele (`@nativele/ts-dom`), and no Skill exists for that framework yet. React, Vue, Svelte and Angular have their own (`nativele-react`, `nativele-vue`, `nativele-svelte`, `nativele-angular`); `npx ts-dom skills` lists every Skill.
+- It is a procedure for finding out how the framework treats custom elements and connecting it correctly. It does not cover setting the framework itself up: start from the app as it is, with its own type checker and build.
+- A framework with its own file format type-checks it with its own tool (Vue: `vue-tsc`). `ts-dom check` runs `vue-tsc` instead of `tsc` when the project's `package.json` lists it; for other formats see Troubleshooting.
+- Not for writing the Nativele components themselves: use `nativele-core` (`npx ts-dom skills add nativele-core`).
+
+Nativele components are native custom elements. The framework renders their tags like any other tag; nothing wraps them. Every rule below follows from that.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.5.1 |
+| vue | 3.5.44 |
+| vite | 8.3.6 |
+| @vitejs/plugin-vue | 6.0.10 |
+| vue-tsc | 3.3.14 |
+| typescript | 6.0.3 |
+
+Verified on 2026-11-05 by an agent that followed this Skill in a fresh Vue app made with `create-vite` (`vue-ts`), and checked in Google Chrome. The rules come from the custom element standard and hold for any framework, but each framework's own behavior (step 3) is verified only for the frameworks named here and in `nativele-react`.
+
+## Set-up
+
+1. Keep the Nativele components in their own folder, for example `src/nv/`, each as `x.html` plus `x.ts`, written with the core Skill.
+2. Connect the build: with Vite, add `tsDom({ dirs: ["src/nv"] })` from `@nativele/ts-dom/vite` to `plugins`, and pass the same folder to every `ts-dom` command (`npx ts-dom check src/nv`). In the tsconfig whose `include` covers that folder, set `"strict": true`. If the project lints with oxlint, add `{ "name": "ts-dom", "specifier": "@nativele/ts-dom/oxlint" }` to `jsPlugins` and `"ts-dom/unused-markup": "error"` to `rules`. Add `*.html.ts` and `ts-dom-tags.ts` to `.gitignore`. Run `npx ts-dom doctor src/nv` and fix what it reports.
+3. Find out, from the framework's documentation on custom elements (often called "web components"), these four things before writing any template:
+
+   | Question | Why it matters |
+   |---|---|
+   | Does the compiler need to be told that hyphenated tags are custom elements? | Otherwise it may try to resolve them as framework components and warn or fail. |
+   | Does a binding set a JS property or an HTML attribute on a custom element, and how do you force a property? | Objects and arrays reach a Nativele component only as properties. |
+   | How do you listen to a DOM event with an exact, hyphenated name? | Nativele events use names like `item-select`, and some syntaxes change the case. |
+   | Does the framework add, move and remove the children it renders inside the tag? | Light DOM slots move those children (limitation 3). |
+
+4. Import every Nativele component module in the app's entry file, before the framework mounts anything:
+
+   ```ts
+   // src/main.ts
+   import "./nv/info-card.js";
+   // then create and mount the app
+   ```
+
+   Many frameworks decide between property and attribute by checking whether the element already has the property, which is only true after `define()` has run.
+
+5. Give the framework's template type checker the Nativele tags. `ts-dom gen` writes `ts-dom-tags.ts`, which adds every exported component to `HTMLElementTagNameMap`; a component's props are the keys of its `props` member, and its events are in the optional `"~emits"` member (event name to `detail` type). Build the framework's tag declaration from these, so new components need no edit; `nativele-react` has the TSX one and `nativele-vue` the Vue one. Check how the framework names an event listener in its types: Vue types `@user-select` as the prop `onUserSelect`. If the framework has no typed templates, skip this step.
+
+## Example
+
+What every framework does underneath, in plain DOM calls. Check the framework's output against it:
+
+```ts
+import "./nv/info-card.js";                       // define() runs first
+
+const card = document.createElement("info-card");
+card.label = "Ada";                               // a string prop: property or attribute label="Ada"
+card.item = { id: 1, name: "Ada" };               // an object prop: property only
+card.addEventListener("item-select", (e) => {     // the exact event name, on the element itself
+  console.log(e.detail.id);
+});
+host.append(card);                                // connected() runs here
+card.item = { id: 2, name: "Grace" };             // a new object re-renders; changing item.name in place does not
+card.remove();                                    // disconnected() runs, bind() subscriptions end
+```
+
+In a framework, the same calls come from its template syntax. `nativele-vue` (`npx ts-dom skills nativele-vue`) is a complete worked example: its compiler option, property binding, event listener and template type declaration answer the four questions of step 3 for Vue.
+
+## Known limitations
+
+1. **Define before render.** Import the component modules before the framework mounts (step 4). A framework that sees an undefined element may write an attribute instead of a property, and an object then arrives as the text `"[object Object]"`. A property set before `define()` is kept: Nativele takes it over when the element is upgraded.
+2. **Props.** A prop whose default is a string, number or boolean can also come from an attribute, with camelCase names in kebab-case (`maxLength` from `max-length`, a boolean `true` when the attribute is present). Arrays and objects can only be set as properties. Pass a new object when data changes: props are compared by reference.
+3. **Light DOM slots and framework-managed children do not mix.** In the default Light DOM mode (`Component(tpl)` without `shadow`), Nativele moves the tag's children into its slot positions; a framework that later inserts, removes or reorders those children can fail or leave nodes outside the slot. Use one of:
+   - `shadow: true` on the component, so the browser assigns slots natively and the children can change freely;
+   - one stable element per slot that the framework never removes, with the changing content inside it (`<div slot="title">...</div>`, `<div>...</div>` for the default slot). A stable but empty wrapper still fills its slot, so the slot's fallback content does not show; when the fallback matters, use `shadow: true`.
+4. **Events do not bubble.** `emit` dispatches a `CustomEvent` on the component that does not bubble, so the listener must be on that element, not on an ancestor. The event data is `event.detail`.
+5. **Lifecycle.** `connected()` runs each time the element is inserted and `disconnected()` each time it is removed; a framework that moves an element (reordering a keyed list) runs both. `bind` subscriptions end on removal and start again on insertion, and the children already in a Light DOM component's slots move with it.
+6. **The framework's templates are checked by the framework's type checker**, with the declaration from step 5, not by the Nativele rules. How much it checks depends on the framework: `vue-tsc` reports a wrong prop type or event detail, but not an unknown prop name.
+
+## Verify
+
+```sh
+npx ts-dom check src/nv      # 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)
+```
+
+Then run the app's own type check and build (for example `npm run build` when it runs the framework's type checker). Keep one wrong prop per component kind that has props in a file the app never imports, under the framework's expect-error comment (a template comment such as `<!-- @ts-expect-error -->` is often not honored; check that a wrong prop fails without it), so the declaration is proved to type props.
+
+In the browser, render a component with an object prop and an event listener, and check:
+
+- the element has no attribute for the object prop (`el.getAttributeNames()`) and `el.<prop>` is the object;
+- the listener runs once per event;
+- children that the framework toggles, reorders, adds and removes stay in the right slot, with no errors or framework warnings in the console (run this check once against the dev server too: production builds drop framework warnings). Read a slot with `el.assignedNodes(name)` (`""` is the default slot), which works in both modes; a Light DOM component has no `<slot>` elements once rendered. Frameworks leave comment and empty text nodes as anchors among the children, so compare elements, not all nodes.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| An object prop shows `[object Object]`, or the element has an attribute holding it | the framework set an attribute: the element was not defined yet, or the binding syntax sets attributes | import the module before mounting; use the framework's property binding |
+| The framework warns that it cannot resolve the component `info-card` | its compiler treats the tag as a framework component | mark hyphenated tags as custom elements in the framework's compiler options |
+| The event listener never runs | the name was changed (camelCase), or the listener is on an ancestor | listen with the exact name, on the element that emits |
+| Children vanish, appear outside the slot, or the framework throws during an update | framework-managed children inside a Light DOM component with slots | `shadow: true`, or a stable element per slot |
+| `ts-dom check` reports `TS2307: Cannot find module` for a framework file (`./App.vue`, ...) | plain `tsc` cannot read the framework's files | Vue: keep `vue-tsc` in `package.json` (Vue's own type checker; `ts-dom check` uses it when listed). Other formats: pass `--project=` a tsconfig whose `include` covers only the Nativele folder, and type-check the rest with the framework's tool |
+| The framework's type checker does not know the tag | no declaration built from `ts-dom-tags.ts`, or the component class is not exported | add the declaration (step 5), export the class, run `ts-dom gen` |
+
+## See also
+
+- Props, events and data flow: 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: https://github.com/Pixmi/nativele/blob/main/docs/components.md#components
+- Setup and checks: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md
+- A complete framework integration: `npx ts-dom skills nativele-react`