@nativele/ts-dom 0.5.0 → 0.5.1

package/skills/nativele-react/SKILL.md

@@ -3,7 +3,7 @@ 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.0 <0.6.0"
+  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"
@@ -24,20 +24,21 @@ Nativele components are native custom elements. React renders them like any othe
 
 | Tool | Verified version |
 |---|---|
-| @nativele/ts-dom | 0.5.0 |
+| @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 Skill or the library changes and once a month. With a different major version of React, treat every step as unverified.
+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` (see the core Skill or the guides).
+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. Add the Nativele Vite plugin next to the React plugin, pointing at that folder:
+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
@@ -48,7 +49,11 @@ Verified on 2026-11-05 in Google Chrome 148 with the example project in the Nati
    export default defineConfig({ plugins: [tsDom({ dirs: ["src/nv"] }), react()] });
    ```
 
-4. Import every Nativele component module in the entry file, before React renders anything:
+   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
@@ -59,7 +64,7 @@ Verified on 2026-11-05 in Google Chrome 148 with the example project in the Nati
 
    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]"`.
 
-5. 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:
+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
@@ -84,6 +89,8 @@ Verified on 2026-11-05 in Google Chrome 148 with the example project in the Nati
 
    The component class must be exported and passed to `define()` in a folder that `ts-dom gen` scans, so it appears in `ts-dom-tags.ts`.
 
+The generated files are not committed, so on a clean checkout the type check in `npm run build` runs before anything has written them and fails with `TS2307: Cannot find module './x.html.js'`. Generate them first: `"build": "ts-dom gen src/nv && tsc -b && vite build"` (the template's script with `ts-dom gen src/nv &&` in front).
+
 ## Example
 
 A Nativele component with props and an event:
@@ -132,6 +139,12 @@ Used from React:
 
 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 }) {}
@@ -147,9 +160,9 @@ define("shadow-card", ShadowCard);
 
 ## Known limitations
 
-1. **Define before render.** Import every Nativele module before React first renders its tag (step 4). Otherwise props become attributes and object props are lost.
+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, 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:
+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:
 
@@ -160,9 +173,9 @@ define("shadow-card", ShadowCard);
      </light-card>
      ```
 
-     A stable but empty wrapper still fills its slot, so the slot's fallback content does not show.
+     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 5; 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.
+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.
@@ -174,16 +187,19 @@ 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             # expect: no errors (keep one @ts-expect-error case per component kind)
-npx vite build               # expect: built
+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)
 ```
 
-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` 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.
+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 |

package/skills/nativele-svelte/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: nativele-svelte
+description: "Use Nativele web components inside an existing Svelte 5 app: passing props, listening to events, children and slots, lifecycle, template types with svelte-check, and ts-dom check. Use when a project depends on svelte and @nativele/ts-dom."
+metadata:
+  tier: experimental
+  nativele: ">=0.5.1 <0.6.0"
+  verified: "2026-11-05"
+  tools: "svelte@5.57.3 vite@8.3.6 @sveltejs/vite-plugin-svelte@7.3.1 svelte-check@4.7.8 @tsconfig/svelte@5.0.8 typescript@6.0.3"
+  author: "Nativele maintainers"
+  detects: "svelte"
+---
+
+# Nativele + Svelte
+
+## When to use
+
+- The project renders with Svelte 5 (with Vite) and wants to use components written with Nativele (`@nativele/ts-dom`), for example a design-system layer or widgets shared with non-Svelte pages.
+- Signals: `svelte` and `@nativele/ts-dom` in `package.json`, `.svelte` files that render tags with a hyphen (`<info-card>`).
+- Not for Svelte 4 or earlier, and not for SvelteKit (server rendering and hydration were not verified). Not for compiling Svelte components into custom elements (`<svelte:options customElement>`): that is the opposite direction.
+- Not for writing the Nativele components themselves: use `nativele-core` (`npx ts-dom skills add nativele-core`).
+
+Nativele components are native custom elements. Svelte renders them like any other tag; nothing wraps them.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.5.1 |
+| svelte | 5.57.3 |
+| @sveltejs/vite-plugin-svelte | 7.3.1 |
+| svelte-check | 4.7.8 |
+| @tsconfig/svelte | 5.0.8 |
+| vite | 8.3.6 |
+| typescript | 6.0.3 |
+
+Verified on 2026-11-05 in Google Chrome 148, against the Vite dev server (so Svelte's development warnings would show), in a fresh app made with `npm create vite@latest -- --template svelte-ts`. Runes mode (`$state`) is what was verified; legacy mode was checked only for the `on:` directive (limitation 2). With a different major version of Svelte, 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. Leave the tsconfig as it is: Vite's Svelte template has `tsconfig.app.json` extend `@tsconfig/svelte`, which sets `"strict": true`, and its `include` already covers `src/nv`. If the project turned `strict` off, set it back in that file.
+4. Add the Nativele Vite plugin before the Svelte plugin, pointing at that folder:
+
+   ```ts
+   // vite.config.ts
+   import { svelte } from "@sveltejs/vite-plugin-svelte";
+   import { defineConfig } from "vite";
+   import { tsDom } from "@nativele/ts-dom/vite";
+
+   export default defineConfig({ plugins: [tsDom({ dirs: ["src/nv"] }), svelte()] });
+   ```
+
+   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`. Svelte needs no option to accept hyphenated tags.
+
+5. Add the generated files to `.gitignore`:
+
+   ```
+   *.html.ts
+   ts-dom-tags.ts
+   ```
+
+6. Import every Nativele component module in `src/main.ts`, before `mount`:
+
+   ```ts
+   // src/main.ts
+   import "./nv/info-card.js";
+   import "./nv/shadow-card.js";
+   import { mount } from "svelte";
+   import App from "./App.svelte";
+
+   mount(App, { target: document.getElementById("app")! });
+   ```
+
+   Svelte 5 sets a value as a property when the element is defined and has that property (limitation 1).
+
+7. Add the template declaration below as `src/nativele-svelte.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 in `.svelte` files, and new components need no edit:
+
+   ```ts
+   // src/nativele-svelte.d.ts
+   import type { HTMLAttributes } from "svelte/elements";
+
+   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<HTMLAttributes<E>, keyof NativeleProps<E>> & NativeleProps<E> & NativeleEvents<E>;
+   type NativeleElements = { [K in NativeleTag]: NativeleElementProps<HTMLElementTagNameMap[K]> };
+
+   declare module "svelte/elements" {
+     interface SvelteHTMLElements extends NativeleElements {}
+   }
+   ```
+
+   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`.
+
+8. Prove the declaration types props with a `.ts` file that the app never imports, one wrong case per component kind under `// @ts-expect-error` (an expect-error comment in Svelte markup does not work, limitation 6):
+
+   ```ts
+   // src/types-check.ts
+   import type { SvelteHTMLElements } from "svelte/elements";
+
+   // @ts-expect-error an object prop given a string
+   export const badProp: SvelteHTMLElements["info-card"] = { item: "apple" };
+   // @ts-expect-error a prop name the component does not declare
+   export const badName: SvelteHTMLElements["info-card"] = { lable: "x" };
+   // @ts-expect-error a detail field the event does not have
+   export const badEvent: SvelteHTMLElements["info-card"] = { "onitem-select": (e) => e.detail.name };
+   ```
+
+The generated files are not committed, so on a clean checkout the type check in `npm run check` runs before anything has written them and fails with `TS2307: Cannot find module './x.html.js'`. Generate them first: `"check": "ts-dom gen src/nv && svelte-check --tsconfig ./tsconfig.app.json && tsc -p tsconfig.node.json"` (the template's script with `ts-dom gen src/nv &&` in front). `npm run build` needs no change: the Vite plugin generates the files.
+
+## 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);
+```
+
+A component with slots, in Shadow DOM:
+
+```html
+<!-- src/nv/shadow-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);
+```
+
+Used from Svelte:
+
+```svelte
+<!-- src/App.svelte -->
+<script lang="ts">
+  import type { Item } from "./nv/info-card.js";
+
+  let count = $state(0);
+  let item = $state<Item>({ id: 1, name: "apple" });
+  let picked = $state<number[]>([]);
+  let rows = $state(["a", "b", "c"]);
+  let showTitle = $state(true);
+</script>
+
+<info-card label="Fruit" {count} {item} onitem-select={(e) => picked.push(e.detail.id)}></info-card>
+<button type="button" onclick={() => { count++; item = { ...item, name: "pear" }; }}>Next</button>
+
+<shadow-card>
+  {#if showTitle}<span slot="title">Title</span>{/if}
+  {#each rows as r (r)}<p>{r}</p>{/each}
+</shadow-card>
+```
+
+- `label`, `count` and `item` arrive as properties; the element has no attribute for them. Changing them from Svelte state re-renders the Nativele component.
+- The event attribute is `on` followed by the exact event name: `onitem-select`. `e.detail` is typed from the component's `emits`.
+- In a `shadow: true` component, `{#if}` and keyed `{#each}` children can change freely.
+
+## Known limitations
+
+1. **Define before mount.** Import the component modules before `mount` (step 6). Svelte 5 decides per value: when the element is defined, it sets a property the element has; when it is not defined yet (for example a module loaded later with `import()`), it sets objects and arrays as properties and writes every other value as an attribute string. Nativele reads both when the element is upgraded, which was verified for string, number and boolean props with one-word names (`count={0}` becomes `count="0"`, `false` becomes `open="false"`, both arrive with the right type). Other cases were not verified, so define first.
+2. **Event attribute names.** Only `on` plus the exact event name works (`onitem-select`). `onItemSelect` listens to an event named `ItemSelect` and never fires; with the declaration it is also a `svelte-check` error. The legacy directive `on:item-select` fires too, but only use the event attributes: in a runes component `on:` is deprecated (compiler warning `event_directive_deprecated`), a component cannot mix it with event attributes (compile error `mixed_event_handler_syntaxes`), and the declaration in step 7 does not type it. Nativele events do not bubble, so put the handler on the element that emits.
+3. **Light DOM slots and Svelte-managed 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, together with the comment nodes Svelte uses as anchors. Svelte does not throw, but it goes wrong silently: an `{#if}` that adds `<span slot="title">` back inserts it next to its anchor, which now sits in the default slot, so the title slot shows its fallback; and `assignedNodes()` stops matching what is on the page. Keyed `{#each}` reordering happened to look right, but do not rely on it. Use one of:
+   - `shadow: true` on the component (children can then change freely), or
+   - one stable element per slot, and let Svelte change only what is inside it:
+
+     ```svelte
+     <light-card>
+       <div slot="title">{#if showTitle}<span>Title</span>{/if}</div>
+       <div>{#each rows as r (r)}<p>{r}</p>{/each}</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. Changing a `$state` object in place (`item.name = "kiwi"`) does not re-render it; assign a new object (`item = { ...item, name: "kiwi" }`).
+5. **Write closing tags.** `<info-card ... />` works, but the Svelte compiler warns `element_invalid_self_closing_tag` (shown in the dev server's terminal); write `<info-card ...></info-card>`.
+6. **Template types need the declaration** in step 7. Without it, Svelte accepts any attribute on a hyphenated tag, and an inline handler's parameter is `any` (`Parameter 'e' implicitly has an 'any' type` under `strict`). With it, `svelte-check` reports a wrong prop type, an unknown prop name, a wrong `e.detail` field and a camelCase handler name. `<!-- @ts-expect-error -->` in markup does not silence an error, so keep the expected-error cases in a `.ts` file (step 8). To type an element reference, use the tag map: `let card: HTMLElementTagNameMap["info-card"] | undefined = $state()` with `bind:this={card}`.
+7. **`ts-dom check` does not read `.svelte` files.** It runs the project's `tsc`, which checks the Nativele folder and the `.ts` files (including `types-check.ts`); `.svelte` imports resolve through the `*.svelte` module declaration in Svelte's own types, so they cause no error, but the markup and scripts inside `.svelte` files are checked only by `svelte-check`. Run both (Verify).
+8. **Lifecycle.** Removing an element with `{#if}` runs `disconnected()` and ends its `bind` subscriptions; adding it back runs `connected()` and subscribes again. Reordering a keyed `{#each}` of Nativele elements moves them, which runs `disconnected()` and then `connected()`; each element keeps its slotted children, and every `bind` callback still runs once per store change.
+9. Not verified: SvelteKit, server rendering and hydration, form controls inside Nativele components submitting with a Svelte form, `$state.raw`, hot updates of `.svelte` files that contain Nativele tags, and Svelte versions other than 5.57.
+
+## 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 (info lines are suggestions)
+npm run check                # svelte-check plus tsc for vite.config.ts; expect: svelte-check found 0 errors and 0 warnings
+npm run build                # expect: built
+```
+
+When `npm run check` is not run in a terminal (an agent, CI), `svelte-check` prints `COMPLETED ... 0 ERRORS 0 WARNINGS ...` instead. Delete `src/nativele-svelte.d.ts` once to see the check work: `svelte-check` must then report `Unused '@ts-expect-error' directive` in `src/types-check.ts`.
+
+In the browser, against the dev server (production builds drop Svelte's warnings), render a component with an object prop and an event attribute, and check:
+
+- the element has no attribute for the object prop (`el.getAttributeNames()`) and `el.item` is the object;
+- the handler runs once per event;
+- children that Svelte toggles with `{#if}` and reorders, adds and removes with keyed `{#each}` stay in the right slot, both in a `shadow: true` component and in stable wrappers in a Light DOM component, with no errors or warnings in the console. 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. Svelte leaves comment nodes as anchors among the children, so compare elements, not all nodes.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `svelte-check` reports `Cannot find module './x.html.js'` on a clean checkout | it runs before the generated files exist | start the `check` script with `ts-dom gen src/nv &&` |
+| The event handler never runs | the attribute is camelCased (`onItemSelect`), or it is on an ancestor | use `on` plus the exact event name (`onitem-select`) on the element that emits |
+| `svelte-check`: `'"on:item-select"' does not exist in type 'NativeleElementProps<...>'` | the legacy `on:` directive, which the declaration does not type | use the event attribute `onitem-select` |
+| `Mixing old (on:item-select) and new syntaxes for event handling is not allowed` | `on:` and event attributes in the same component | use only event attributes |
+| `svelte-check`: `Parameter 'e' implicitly has an 'any' type` on a handler of a Nativele tag | the declaration file is missing, or the component class is not exported | add `src/nativele-svelte.d.ts`, export the class, run `npx ts-dom check src/nv` |
+| `svelte-check`: `Unused '@ts-expect-error' directive` in `types-check.ts` | the declaration is not applied | same as above |
+| A slotted child shows up in the wrong slot, or the fallback shows although Svelte rendered the child | Svelte-managed children directly inside a Light DOM component with slots | `shadow: true`, or a stable wrapper element per slot |
+| The component does not update after `item.name = ...` | the object was changed in place; props compare by reference | assign a new object |
+| `Self-closing HTML tags for non-void elements are ambiguous` | `<info-card />` | write `<info-card></info-card>` |
+| `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
+- How attributes convert to props: 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
+- Stores and `bind`: https://github.com/Pixmi/nativele/blob/main/docs/components.md#state-store-when-not-using-state
+- Setup and checks: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md
+- The framework-neutral rules: `npx ts-dom skills nativele-integration`

package/skills/nativele-vite/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: nativele-vite
+description: "Add Nativele to an existing Vite app without a UI framework, and set up the tsDom() Vite plugin correctly: dirs and Vite's root, multi-page apps, the build script, and what vite dev does when a template or component changes. Use when a project depends on vite (or vite-plus) and @nativele/ts-dom."
+metadata:
+  tier: official
+  nativele: ">=0.5.1 <0.6.0"
+  verified: "2026-11-05"
+  tools: "vite@8.3.6 typescript@7.0.2 create-vite@9.3.4 vite-plus@1.5.0"
+  author: "Nativele maintainers"
+  detects: "vite vite-plus"
+---
+
+# Nativele + Vite
+
+## When to use
+
+- A Vite app with no UI framework (for example one started with `npm create vite@latest -- --template vanilla-ts`) that adds components written with Nativele (`@nativele/ts-dom`).
+- Any Vite project with Nativele whose set-up goes beyond the defaults: `root` in a sub-folder, several HTML pages, Vite+, or questions about what `vite dev` does when a template changes.
+- Signals: `vite` or `vite-plus` and `@nativele/ts-dom` in `package.json`, a `vite.config.ts`.
+- With React, follow `nativele-react`; with another framework, `nativele-integration`. The parts about `dirs`, `root` and the build script apply there too, but the hot-update behavior below was verified without a framework.
+- Not for writing the components themselves (`npx ts-dom skills add nativele-core`), and not for setting Vite up.
+
+## Versions
+
+| Tool | Verified version |
+|---|---|
+| @nativele/ts-dom | 0.5.1 |
+| vite | 8.3.6 |
+| typescript | 7.0.2 |
+| create-vite (`vanilla-ts` template, the starting point) | 9.3.4 |
+| vite-plus | 1.5.0 (checked by hand with `vp dev`, `vp build` and `vp lint`; the example project does not run it) |
+
+Verified on 2026-11-05 in Google Chrome 148 with the example project in the Nativele repository (`skills/nativele-vite/example`), which CI runs again when the example or the library changes and once a month. With a different major version of Vite, treat every step as unverified.
+
+## Set-up
+
+Starting from the `vanilla-ts` template, which already has `"type": "module"`, a `tsconfig.json` with `"include": ["src"]` and no `strict`, no `vite.config.ts`, and `"build": "tsc && vite build"`:
+
+1. `npm i @nativele/ts-dom`.
+2. Keep the components in their own folder, for example `src/nv/`, each as `x.html` plus `x.ts` (write them with `nativele-core`).
+3. Add `"strict": true` to `compilerOptions` in `tsconfig.json`. The template's other options (`verbatimModuleSyntax`, `erasableSyntaxOnly`, `noUnusedLocals`, `allowImportingTsExtensions`) work with the generated files as they are, and `"include": ["src"]` already covers `src/nv`.
+4. Create `vite.config.ts` (the template has none, so `ts-dom doctor` cannot report the plugin as missing yet):
+
+   ```ts
+   import { defineConfig } from "vite";
+   import { tsDom } from "@nativele/ts-dom/vite";
+
+   export default defineConfig({ plugins: [tsDom({ dirs: ["src/nv"] })] });
+   ```
+
+   `dirs` is resolved against Vite's `root`, not against the folder you run commands in (see step 8). The other options are in the setup guide.
+
+5. Replace `tsc` in the build script with `ts-dom check`, given the same folder:
+
+   ```sh
+   npm pkg set scripts.build="ts-dom check src/nv && vite build"
+   ```
+
+   The generated files are not committed, so on a clean checkout `tsc` runs before anything has written them and fails with `TS2307: Cannot find module './x.html.js'` and follow-on errors. `ts-dom check` writes them, then runs `tsc` and the lint rules. `vite build` writes them too, but it never type-checks.
+
+6. Add `*.html.ts` and `ts-dom-tags.ts` to `.gitignore`.
+7. Import each page's components from that page's entry module, and write the tags straight into the page's HTML (`<hello-card name="home"></hello-card>`; attributes reach string props). Import the component modules the way the project imports its own (`./nv/hello-card.ts` in this template), and templates always as `./x.html.js`.
+8. When `root` is a sub-folder (a multi-page app or a monorepo app kept in `web/`), each path is relative to a different folder:
+
+   | Setting | Relative to | With `root: "web"` |
+   |---|---|---|
+   | `tsDom({ dirs })` | Vite's `root` | `["src/nv"]` |
+   | `ts-dom check`, `doctor`, `gen`, `lint` arguments | the folder they run in (the one with `package.json` and `tsconfig.json`) | `web/src/nv` |
+   | `include` in `tsconfig.json` | the tsconfig's folder | `["web/src"]` |
+   | `build.rolldownOptions.input` | write absolute paths (see Troubleshooting) | `resolve(import.meta.dirname, "web/about.html")` |
+
+   Nativele needs nothing per page: each page's entry imports the components that page uses.
+
+9. With Vite+ instead of Vite, import `defineConfig` from `"vite-plus"`; the plugin, `dirs` and the build script are the same, and the lint settings in the setup guide work with `vp lint`. If `vp build` then stops with `Cannot find package 'vite'`, see Troubleshooting.
+
+## Example
+
+A two-page app with `root: "web"`, as in the example project:
+
+```
+package.json  tsconfig.json  vite.config.ts
+web/index.html  web/about.html
+web/src/main.ts  web/src/about.ts
+web/src/nv/hello-card.html  web/src/nv/hello-card.ts  web/src/nv/about-card.html  web/src/nv/about-card.ts
+```
+
+```jsonc
+// package.json (scripts)
+"dev": "vite",
+"build": "ts-dom check web/src/nv && vite build"
+```
+
+```jsonc
+// tsconfig.json: the template's, with "strict": true and
+"include": ["web/src"]
+```
+
+```ts
+// vite.config.ts
+import { resolve } from "node:path";
+import { defineConfig } from "vite";
+import { tsDom } from "@nativele/ts-dom/vite";
+
+const page = (file: string) => resolve(import.meta.dirname, "web", file);
+
+export default defineConfig({
+  root: "web",
+  plugins: [tsDom({ dirs: ["src/nv"] })],
+  build: {
+    outDir: "../dist",
+    emptyOutDir: true,
+    rolldownOptions: { input: { main: page("index.html"), about: page("about.html") } },
+  },
+});
+```
+
+```html
+<!-- web/index.html (body); web/about.html has <about-card></about-card> and /src/about.ts -->
+<hello-card name="home"></hello-card>
+<script type="module" src="/src/main.ts"></script>
+```
+
+```ts
+// web/src/main.ts
+import "./nv/hello-card.ts";
+```
+
+```html
+<!-- web/src/nv/hello-card.html -->
+<p>Hello, {{ name }}</p>
+<button type="button" data-on-click="bump">clicked {{ count }}</button>
+```
+
+```ts
+// web/src/nv/hello-card.ts
+import { Component, define } from "@nativele/ts-dom";
+import tpl from "./hello-card.html.js";
+
+export class HelloCard extends Component(tpl, { props: { name: "" }, state: { count: 0 } }) {
+  bump(): void {
+    this.set({ count: this.state.count + 1 });
+  }
+}
+define("hello-card", HelloCard);
+```
+
+## Known limitations
+
+1. **Every change reloads the page; component state is lost.** A custom element tag can be defined only once, so there is no hot swap of a component. During `vite dev`:
+
+   | Change | What happens |
+   |---|---|
+   | A template is edited | its `x.html.ts` is regenerated and the browser reloads; the terminal prints `[vite] (client) page reload src/nv/x.html` |
+   | A template is saved with no change | no reload (the terminal still prints the `page reload` line) |
+   | A template no page has loaded since the dev server started is edited | no reload |
+   | A template some page has loaded is edited | every open page reloads, also pages that do not use it |
+   | A template that `ts-dom gen` rejects is saved | no reload: the page keeps the last good version, and the error (`file:line:col error [rule-id] ... Fix: ...`) is printed only in the terminal, with no overlay in the browser |
+   | A template uses a name the component does not have (`{{ nope }}`) | it is regenerated and reloads, the hole stays empty, and nothing reports it: only `ts-dom check` does |
+   | A component `.ts` is edited | Vite reloads the page, and the new class runs |
+
+2. **Do not call `import.meta.hot.accept()` in a module that imports components.** Vite then re-runs the modules instead of reloading, `define()` finds the tag already defined and keeps the old class, and the edit silently has no effect until a manual reload.
+3. **Neither `vite dev` nor `vite build` type-checks.** Run `ts-dom check` (the build script in step 5 does), and run it after a template change that `vite dev` accepted without complaint.
+4. **A wrong `dirs` fails without a warning from the plugin.** If `dirs` does not point at the templates from Vite's `root` (for example `["web/src/nv"]` with `root: "web"`), nothing is generated, and the first sign is an unresolved `./x.html.js` (see Troubleshooting).
+5. **Pass one folder to every `ts-dom` command.** `ts-dom-tags.ts` is written into the folder a command is given, so `ts-dom check web` next to `ts-dom check web/src/nv` leaves a second `ts-dom-tags.ts` in `web/`; delete it and use the same folder everywhere.
+6. Not verified: hot updates under a framework plugin (React Fast Refresh, Vue), server-side rendering, Vite library mode, an npm workspaces monorepo where the app has its own `package.json` (only `root` in a sub-folder of one package was verified), and Vite versions other than 8.3.
+
+## Verify
+
+Run in the project (with `root: "web"`, the folder is `web/src/nv`):
+
+```sh
+npm run build                 # expect: ts-dom check: no issues, then ✓ built, and one HTML file per page in the output
+npx ts-dom doctor src/nv      # expect: ts-dom doctor: the set-up looks right
+```
+
+Then run `npm run dev`, open every page and check that its components render and respond. Edit a template and check that the page reloads once and shows the change. The example project's [`verify.mjs`](https://github.com/Pixmi/nativele/blob/main/skills/nativele-vite/example/verify.mjs) checks with Playwright that `vite build` alone writes the generated files, that both built pages work under `vite preview`, and every row of the table in Known limitations, restoring the files it edits.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `TS2307: Cannot find module './x.html.js'` from `npm run build` on a clean checkout | the build script starts with `tsc`, before anything generated the files | `"build": "ts-dom check <folder> && vite build"` |
+| `vite build`: `[UNRESOLVED_IMPORT] Could not resolve './x.html.js'`; `vite dev`: `Failed to resolve import "./x.html.js"` and a 500 for the module | `dirs` is not relative to Vite's `root`, or leaves out the folder | give `dirs` relative to `root` (`["src/nv"]` with `root: "web"`) |
+| `ts-dom check`: `[dir-not-found] The folder src does not exist` | the commands default to `src` in the folder they run in | pass the folder from there: `ts-dom check web/src/nv` |
+| `ts-dom doctor`: `[tsconfig-misses-templates]`; `ts-dom check`: `TS18003: No inputs were found` | `include` is relative to the tsconfig, not to Vite's `root` | `"include": ["web/src"]` |
+| An edit to a component has no effect until the page is reloaded by hand | a module calls `import.meta.hot.accept()` | remove it |
+| A template edit never reaches the page, and the terminal shows `error [rule-id]` | the template breaks a template rule | fix it by the `Fix:` hint; once the template generates again, the page shows it |
+| `vite dev`: `(!) Failed to run dependency scan ... failed to resolve rolldownOptions.input value: "web/index.html"` | `vite dev` resolves a relative `input` against `root` | write absolute paths, as in the example |
+| Vite warns `ESM syntax in a file loaded as CommonJS (vite.config.ts:1:1)` | `package.json` has no `"type": "module"` | `npm pkg set type=module` |
+| `vp build`: `Cannot find package 'vite' imported from .../vitest/dist/config.js` | npm left `vite` nested under `vite-plus` on the first install (seen with npm 11.19, also without Nativele) | run `npm i` once more |
+
+## See also
+
+- The Vite plugin, its options and the dev server: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#with-vite-optional
+- Lint settings for `vite.config.ts` (Vite+): https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#lint-optional
+- What `ts-dom check`, `doctor` and `gen` check and write: https://github.com/Pixmi/nativele/blob/main/docs/tooling.md#checks
+- Writing the components: `npx ts-dom skills nativele-core`