@nativele/ts-dom 0.4.6 → 0.5.1

package/skills/nativele-core/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: nativele-core
+description: "Build and change web components with Nativele (@nativele/ts-dom): the write-check-fix loop, templates, state, lists and data flow. Use whenever a project depends on @nativele/ts-dom and you add or change an .html template or a component."
+metadata:
+  tier: official
+  nativele: ">=0.5.0 <0.6.0"
+  verified: "2026-11-05"
+  tools: "typescript@7.0.2"
+  author: "Nativele maintainers"
+  detects: "@nativele/ts-dom"
+---
+
+# Nativele core
+
+## When to use
+
+- The project depends on `@nativele/ts-dom` and you write or change a component: an `x.html` template with its `x.ts` class.
+- Not for using Nativele components from a framework (React, Vue, ...): see the integration Skills (`npx ts-dom skills`), which build on this one.
+
+A component is two files. The HTML holds structure and names (`{{ name }}`, `data-ref`, `data-if`, `data-each`, `data-on-*`), never expressions; the TypeScript class holds state and behavior. `ts-dom gen` turns each `x.html` into a typed `x.html.ts`, and `tsc` checks that the two files agree.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.5.0 |
+| typescript | 7.0.2 |
+
+Verified on 2026-11-05 by the library's own CI, which type-checks, lints and runs every example in the repository in real Chrome.
+
+## Set-up
+
+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
+
+1. Write the `.html` and the `.ts` of a component together. Import the template as `./x.html.js`.
+2. Run `npx ts-dom check` (add `--json` to read the result as data). It regenerates the generated files, runs `tsc`, points template contract errors at the template line and column, and runs the lint rules. Use `--no-write` where the working tree must not change.
+3. Fix every issue by its `Fix:` hint. Never cast a type error away, and never edit `x.html.ts` or `ts-dom-tags.ts`: they are generated.
+4. `npx ts-dom rules --explain=<id>` explains any rule id from a diagnostic, with a wrong and a right example.
+5. Repeat until `ts-dom check` prints `no issues`.
+
+## Rules
+
+- 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` 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.
+- 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
+
+- Holes are text only; attributes are set in TypeScript through `data-ref`.
+- A derived value cannot read another derived value; share the calculation as a plain function.
+- `data-if` removes the element from the page (its state is kept in memory); to hide an element while it keeps focus or media playback, set `this.refs.x.hidden` in `render`.
+- Nativele has no router, data fetching, form validation library, styling system or global state manager by design; use the project's tools for those, and see the other Skills for how they connect.
+
+## Verify
+
+```sh
+npx ts-dom check --strict    # expect: ts-dom check: no issues
+npx ts-dom doctor            # expect: ts-dom doctor: the set-up looks right (info lines are suggestions)
+npx tsc --noEmit             # expect: no errors
+```
+
+Then exercise the changed component in a real browser (the project's own test runner, or the browser).
+
+## Troubleshooting
+
+| 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 |
+| A child component does not update | an object prop was changed in place | pass a new object |
+| No types in a parent's `refs.child` | the child class is not exported, or is defined outside the scanned folders | `export class`, and keep it in a folder `ts-dom gen` scans |
+
+## See also
+
+- Templates: https://github.com/Pixmi/nativele/blob/main/docs/templates.md
+- Components and data flow: https://github.com/Pixmi/nativele/blob/main/docs/components.md
+- Lists: https://github.com/Pixmi/nativele/blob/main/docs/lists.md
+- Recipes (loading states, dialogs, forms, store data): https://github.com/Pixmi/nativele/blob/main/docs/recipes.md
+- Setup, checks and lint: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md

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`

package/skills/nativele-react/SKILL.md

@@ -0,0 +1,213 @@
+---
+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"
+  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"
+---
+
+# Nativele + React
+
+## When to use
+
+- The project renders with React 19 and wants to use components written with Nativele (`@nativele/ts-dom`), for example a design-system layer or widgets shared with non-React pages.
+- Signals: `react` and `@nativele/ts-dom` in `package.json`, `.tsx` files that render tags with a hyphen (`<info-card>`).
+- Not for React 18 or earlier: React 18 sets every prop on a custom element as an attribute and does not attach `on...` handlers to custom events. The steps below are verified only with React 19.
+
+Nativele components are native custom elements. React renders them like any other tag; nothing wraps them.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.5.1 |
+| 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`), which CI runs again when the example or the library changes and once a month. 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.
+4. Add the Nativele Vite plugin next to the React plugin, pointing at that folder:
+
+   ```ts
+   // vite.config.ts
+   import { defineConfig } from "vite";
+   import react from "@vitejs/plugin-react";
+   import { tsDom } from "@nativele/ts-dom/vite";
+
+   export default defineConfig({ plugins: [tsDom({ dirs: ["src/nv"] }), react()] });
+   ```
+
+   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`.
+
+6. Import every Nativele component module in the entry file, before React renders anything:
+
+   ```tsx
+   // src/main.tsx
+   import "./nv/info-card.js";
+   import "./nv/shadow-card.js";
+   // then createRoot(...).render(...)
+   ```
+
+   React 19 sets a value as a property only when the element is already defined; before that it writes an attribute, and an object prop becomes the text `"[object Object]"`.
+
+7. Add the TSX declaration below as `src/nativele-react.d.ts`. It reads the tag map that `ts-dom gen` writes (`ts-dom-tags.ts`), so every exported component gets typed props and events, and new components need no edit:
+
+   ```ts
+   // src/nativele-react.d.ts
+   import type { DetailedHTMLProps, HTMLAttributes } from "react";
+
+   type NativeleTag = Extract<keyof HTMLElementTagNameMap, `${string}-${string}`>;
+   type NativeleProps<E> = E extends { readonly props: infer P } ? { [K in keyof P & keyof E]?: E[K] } : unknown;
+   type NativeleEvents<E> = E extends { readonly "~emits"?: infer M }
+     ? { [K in keyof NonNullable<M> & string as `on${K}`]?: (event: CustomEvent<NonNullable<M>[K]>) => void }
+     : unknown;
+   type NativeleElementProps<E extends HTMLElement> = Omit<DetailedHTMLProps<HTMLAttributes<E>, E>, keyof NativeleProps<E>> &
+     NativeleProps<E> &
+     NativeleEvents<E>;
+   type NativeleIntrinsics = { [K in NativeleTag]: NativeleElementProps<HTMLElementTagNameMap[K]> };
+
+   declare module "react" {
+     namespace JSX {
+       interface IntrinsicElements extends NativeleIntrinsics {}
+     }
+   }
+   ```
+
+   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).
+
+## Example
+
+A Nativele component with props and an event:
+
+```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);
+```
+
+Used from React:
+
+```tsx
+<info-card label={label} count={count} item={item} onitem-select={(e) => select(e.detail.id)} />
+```
+
+- `label`, `count` and `item` arrive as properties; the object is the same object React passed. Changing them from React state re-renders the Nativele component.
+- The event handler prop is `on` followed by the exact event name: `onitem-select`. `e.detail` is typed from the component's `emits`.
+
+A component with slots that receives React children: give it `shadow: true`, then pass children directly.
+
+```html
+<!-- src/nv/shadow-card.html -->
+<h2><slot name="title">Untitled</slot></h2>
+<div><slot></slot></div>
+```
+
+```ts
+// src/nv/shadow-card.ts
+export class ShadowCard extends Component(tpl, { shadow: true }) {}
+define("shadow-card", ShadowCard);
+```
+
+```tsx
+<shadow-card>
+  {showTitle && <span slot="title">{title}</span>}
+  {rows.map((r) => <p key={r.id}>{r.text}</p>)}
+</shadow-card>
+```
+
+## Known limitations
+
+1. **Define before render.** Import every Nativele module before React first renders its tag (step 6). Otherwise props become attributes and object props are lost.
+2. **Event prop names.** Only `on` plus the exact event name works (`onitem-select`); `onItemSelect` and `onItem-select` never fire. Nativele events do not bubble by default, so put the handler on the element that emits. A ref with `addEventListener` in `useEffect` also works (remove it in the cleanup).
+3. **Light DOM slots and React children do not mix.** In the default Light DOM mode (`Component(tpl)` with no `shadow`), Nativele moves the host's children into its slot positions. When React later inserts, removes or reorders those children it fails (`insertBefore`/`removeChild` errors that unmount the root) or leaves nodes outside the slot. Changing text in place and appending at the end happen to work, but do not rely on that. Use one of:
+   - `shadow: true` on the component (children can then change freely), or
+   - one stable React element per slot, and let React change only what is inside it:
+
+     ```tsx
+     <light-card>
+       <div slot="title">{showTitle && <span>{title}</span>}</div>
+       <div>{rows.map((r) => <p key={r.id}>{r.text}</p>)}</div>
+     </light-card>
+     ```
+
+     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. **New objects for changed props.** A Nativele component compares props by reference; pass a new object when the data changes (React state updates usually do).
+5. **TSX types need the declaration** in step 7; without it, every Nativele tag is `TS2339: Property 'info-card' does not exist on type 'JSX.IntrinsicElements'`. Check it with a `.tsx` that has a wrong prop under `// @ts-expect-error`, because `skipLibCheck` can hide mistakes inside the declaration itself. Keep these cases in a `.tsx` file of their own that the app never imports (the example uses `src/types-check.tsx`).
+6. Not verified: server-side rendering, form controls inside Nativele components submitting with a React form, and React versions other than 19.3.
+
+React StrictMode is fine: it runs effects twice but does not insert the custom element twice, so `connected()` runs once, and `bind` subscriptions are released when React unmounts the element.
+
+## Verify
+
+Run in the project:
+
+```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
+npx tsc --noEmit -p tsconfig.app.json   # expect: no errors (keep one @ts-expect-error case per component kind)
+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.
+
+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. The example project's [`verify.mjs`](https://github.com/Pixmi/nativele/blob/main/skills/nativele-react/example/verify.mjs) does these checks 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.
+
+## Troubleshooting
+
+| 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 &&` |
+| 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 |
+| `TS2339: Property 'x-y' does not exist on type 'JSX.IntrinsicElements'` | the declaration file is missing, or the component class is not exported | add `src/nativele-react.d.ts`, export the class, run `ts-dom gen` |
+| `ts-dom check` reports `unused-ref` | a `data-ref` the class never reads | use it in the class or remove the attribute |
+
+## See also
+
+- 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