sveld 0.34.0 → 0.35.0

package/README.md

@@ -3,24 +3,21 @@
 [![NPM][npm]][npm-url]
 ![npm downloads to date](https://img.shields.io/npm/dt/sveld?color=262626&style=for-the-badge)
 
-`sveld` generates TypeScript definitions and component documentation (Markdown/JSON) for Svelte components. It statically analyzes props, events, slots, and the rest. Add types with [JSDoc](https://jsdoc.app/) when inference is not enough.
+`sveld` generates TypeScript definitions and component documentation (Markdown/JSON) for Svelte components. It statically analyzes props, events, slots, module exports, context, and `$$restProps`. Add types with [JSDoc](https://jsdoc.app/) when inference is not enough.
 
 The goal is to get third-party Svelte libraries working with the Svelte Language Server and TypeScript with minimal effort from the author. Generated `.d.ts` files give you autocomplete in VS Code and other IDEs.
 
 [Carbon Components Svelte](https://github.com/carbon-design-system/carbon-components-svelte) uses this library to auto-generate component types and API metadata.
 
-`sveld` uses the Svelte 5 compiler to parse `.svelte` files. That single parse path powers docgen and TypeScript output for Svelte 3, Svelte 4, Svelte 5 without runes (`export let`, `<slot>`, `$$restProps`, …), and Svelte 5 Runes (`$props()`, `$bindable()`, `{@render ...}`, callback props such as `onclick`, …).
+`sveld` uses the Svelte 5 compiler to parse `.svelte` files. That single parse path powers docgen and TypeScript output for Svelte 3, Svelte 4, and Svelte 5 without runes (`export let`, `<slot>`, `$$restProps`, …). It also covers Svelte 5 Runes (`$props()`, `$bindable()`, `{@render ...}`, callback props such as `onclick`, …).
 
 For `lang="ts"` components, `sveld` keeps source-level prop type annotations when it can, instead of forcing JSDoc. That covers legacy `export let` props, typed `$props()` destructuring, typed whole-object `$props()` captures, local `interface`/`type` declarations, and imported type references in emitted `.d.ts` files.
 
-| Syntax mode          | Supported |
-| :------------------- | :-------: |
-| Svelte 3             |     ✓     |
-| Svelte 4             |     ✓     |
-| Svelte 5 (non-Runes) |     ✓     |
-| Svelte 5 Runes       |     ✓     |
+By default, generated `.d.ts` files extend `SvelteComponentTyped` from `svelte`, so TypeScript and the Svelte Language Server work whether consumers use Svelte 3, Svelte 4, or Svelte 5. Set `typesOptions.format: "component"` to instead emit the Svelte 5 `Component` type; see [`typesOptions.format`](#typesoptionsformat).
 
-Generated `.d.ts` files extend `SvelteComponentTyped` from `svelte`, so TypeScript and the Svelte Language Server work whether consumers use Svelte 3, Svelte 4, or Svelte 5.
+## When to use sveld
+
+SvelteKit's library tooling (`svelte-package`) and `svelte2tsx` already emit `.d.ts` files for SvelteKit-based projects, so start there if that's your setup. `sveld` targets JS-first Svelte libraries: components authored in plain JavaScript with JSDoc rather than `lang="ts"`, where you still want full editor types without adopting TypeScript. It also covers cases `svelte-package` doesn't: generating JSON and Markdown component docs from the same source as the types, checking for API drift between releases (`--check`), and deriving richer types from JSDoc tags (`@typedef`, `@callback`, `@slot`, context types) than plain type inference produces.
 
 ---
 
@@ -72,6 +69,8 @@ export default class Button extends SvelteComponentTyped<
 > {}
 ```
 
+`sveld` adds the `[key: \`data-${string}\`]: unknown;` index signature whenever `$$restProps` is spread onto an element, so callers can pass arbitrary `data-*` attributes.
+
 Inference only gets you so far. Use [JSDoc](https://jsdoc.app/) to document prop, event, and slot types when you need more precision.
 
 ```js
@@ -87,6 +86,7 @@ export let primary = false;
 With JSDoc, the output looks like this:
 
 ```ts
+import { SvelteComponentTyped } from "svelte";
 import type { SvelteHTMLElements } from "svelte/elements";
 
 type $RestProps = SvelteHTMLElements["button"];
@@ -117,19 +117,31 @@ export default class Button extends SvelteComponentTyped<
 
 ## Table of Contents
 
+- [When to use sveld](#when-to-use-sveld)
 - [Approach](#approach)
+- [Features](#features)
+  - [`.d.ts` output format (`typesOptions.format`)](#dts-output-format-typesoptionsformat)
+  - [Opt-in semantic resolution (`resolveTypes`)](#opt-in-semantic-resolution-resolvetypes)
+  - [Persistent parse cache (`cache`)](#persistent-parse-cache-cache)
+  - [Compile-checked `@example` blocks (`checkExamples`)](#compile-checked-example-blocks-checkexamples)
+  - [Type inference diagnostics](#type-inference-diagnostics)
+- [Requirements](#requirements)
 - [Usage](#usage)
   - [Installation](#installation)
   - [Vite](#vite)
-  - [Node.js](#nodejs)
   - [CLI](#cli)
   - [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check)
+  - [Node.js](#nodejs)
   - [Config File](#config-file)
   - [Publishing to NPM](#publishing-to-npm)
 - [Available Options](#available-options)
 - [Documenting Entry Exports](#documenting-entry-exports)
 - [JSON Output](#json-output)
+- [Custom Elements Manifest](#custom-elements-manifest)
+  - [Consuming the manifest](#consuming-the-manifest)
 - [API Reference](#api-reference)
+  - [reactive](#reactive)
+  - [binding](#binding)
   - [@type](#type)
   - [@default](#default)
   - [@typedef](#typedef)
@@ -146,6 +158,7 @@ export default class Button extends SvelteComponentTyped<
   - [@generics](#generics)
   - [@component comments](#component-comments)
   - [Accessor Props](#accessor-props)
+- [Troubleshooting](#troubleshooting)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -173,7 +186,73 @@ When both TypeScript syntax and JSDoc are present, `sveld` resolves prop types i
 
 `sveld` stays AST-only. It copies imported and local type text into generated `.d.ts` output but does not run project-wide semantic resolution with the TypeScript compiler. Opaque imported whole-object `$props()` types can therefore stay in declarations without being fully expanded into JSON metadata.
 
-#### Opt-in semantic resolution (`resolveTypes`)
+## Features
+
+### `.d.ts` output format (`typesOptions.format`)
+
+`typesOptions.format` controls the shape of generated `.d.ts` files: `"class"` (the default) or `"component"`.
+
+`"class"` extends `SvelteComponentTyped`, deprecated in Svelte 5 and plausibly removed in Svelte 6:
+
+```ts
+import { SvelteComponentTyped } from "svelte";
+
+export type ButtonProps = { label?: string };
+
+export default class Button extends SvelteComponentTyped<
+  ButtonProps,
+  { click: WindowEventMap["click"] },
+  { default: Record<string, never> }
+> {}
+```
+
+`"component"` emits the Svelte 5 `Component` type instead:
+
+```ts
+import type { Component } from "svelte";
+
+export type ButtonProps = { label?: string; onclick?: (event: WindowEventMap["click"]) => void };
+export type ButtonExports = Record<string, never>;
+
+declare const Button: Component<ButtonProps, ButtonExports, "">;
+export default Button;
+```
+
+Publish `"component"` if you target Svelte 5+ consumers. `"class"` remains compatible with Svelte 3, 4, and 5.
+
+```ts
+await sveld({ types: true, typesOptions: { format: "component" } });
+```
+
+Also available as `--types-format=component` on the CLI.
+
+`"component"`'s three type parameters:
+
+- **Props**: the same `$Props`/`<Name>Props` type as `"class"`. Runes components already declare callback props (e.g. `onclick`) as regular props. Legacy (non-runes) components additionally get `on<name>?: (event: Type) => void` callback props for every dispatched and forwarded event, so Svelte 5 consumers can attach handlers as props instead of `on:event`.
+- **Exports**: the component's accessor props (exported `function`/`const` members), the same members that render as class members under `"class"`.
+- **Bindings**: a union of string literals for props declared with `$bindable(...)` (runes) or marked `@bindable writable` ([see `binding`](#binding)) (legacy) — e.g. `"value"`, or `"value" | "open"` for more than one. `""` when the component declares none, matching Svelte's own convention for "no bindings."
+
+**Generic components.** A `declare const X: Component<...>` value can't itself carry a generic type parameter the way a class can, so generic components (`@template`/`generics`) get a per-component interface instead of `Component<...>` directly:
+
+```ts
+interface GenericListComponent {
+  new <Item extends { id: string | number } = { id: string }>(
+    options: ComponentConstructorOptions<GenericListProps<Item>>,
+  ): SvelteComponent<GenericListProps<Item>> & GenericListExports;
+  <Item extends { id: string | number } = { id: string }>(
+    this: void,
+    internals: ComponentInternals,
+    props: GenericListProps<Item>,
+  ): { $on?(...): () => void; $set?(...): void } & GenericListExports;
+  z_$$bindings?: "";
+}
+declare const GenericList: GenericListComponent;
+export default GenericList;
+```
+
+Both signatures carry their own generic parameter (not the `const` itself), so `Item` is inferred per usage site, e.g. `<GenericList items={numbers} />` infers `Item` from `numbers`. The `new` signature is the one place `"component"` format still touches a legacy type (`SvelteComponent`/`ComponentConstructorOptions`, not the deprecated `SvelteComponentTyped`): the Svelte language server resolves generic inference for `<Comp prop={...} />` template usage through `new`, not the plain call signature, confirmed by comparing against `@sveltejs/package`'s own generated output for the same component. Omitting it silently breaks inference instead of erroring, so it stays in even though it means one legacy import for generic components.
+
+### Opt-in semantic resolution (`resolveTypes`)
 
 Imported whole-object `$props()` types stay opaque in JSON by default (`"props": []`). Turn on `resolveTypes` when a docs site or prop table needs the individual fields.
 
@@ -203,19 +282,19 @@ Without `resolveTypes`, JSON lists no props. With it, each field shows up with `
 
 **Performance.** Off by default. This is the only path that loads TypeScript. It needs `typescript` and a `tsconfig.json`, runs slower than the AST-only pipeline, and gets slower as your types grow. Use it only when you need expanded JSON. `.d.ts` output is unchanged.
 
-#### Persistent parse cache (`cache`)
+### Persistent parse cache (`cache`)
 
-By default, every component is re-parsed on every run. With `cache`, parsed output is written to disk and reused when the source file has not changed. That applies across runs, including CI on a fresh checkout.
+Parsed output is written to disk and reused when the source file has not changed, on by default. That applies across runs, including CI on a fresh checkout.
 
 ```ts
-await sveld({ json: true, cache: true });
+await sveld({ json: true });
 ```
 
-`cache: true` writes to `node_modules/.cache/sveld/parse-cache.json`. Pass a string to use a different location, e.g. `cache: ".cache/sveld.json"`. Also available as `--cache` / `--cache=<path>` on the CLI.
+By default this writes to `node_modules/.cache/sveld/parse-cache.json`. Pass a string to use a different location, e.g. `cache: ".cache/sveld.json"`, or `cache: false` to disable it. Also available as `--cache` / `--cache=<path>` / `--cache=false` on the CLI.
 
 If a component [`@extendProps`](#extendprops) / [`@extends`](#extendprops) another file, it is re-parsed when that dependency changes, same as in [`watch`](#available-options) mode. Bumping the `sveld` or Svelte version clears the cache.
 
-#### Compile-checked `@example` blocks (`checkExamples`)
+### Compile-checked `@example` blocks (`checkExamples`)
 
 `@example` blocks are just text. Rename a prop and the sample code can sit there broken for months. Set `checkExamples: true` to run plain TS/JS `@example` blocks through the TypeScript program. Broken examples show up as `example-compile-error` diagnostics.
 
@@ -254,6 +333,68 @@ The check is narrow on purpose. It catches renamed or removed symbols and wrong
 
 Needs `typescript` and a `tsconfig.json`, same as `resolveTypes`. Use `--strict` (or the `strict` option) to fail CI when an example breaks.
 
+### Type inference diagnostics
+
+`sveld` collects unresolved-type diagnostics on every run: props that fall back to `any`, context values typed as `any`, `@event` tags with no dispatch or callback, `$props()`/`{@render}` syntax sveld can't model, and (when `checkExamples` is enabled) `example-compile-error`. They are always returned from the programmatic `sveld()` API in `SveldResult.diagnostics`. Each diagnostic carries an optional `source` range (the same `{ start: { line, column }, end: { line, column } }` shape as JSON output source ranges) whenever the parser holds a stable position for it.
+
+With `reportDiagnostics` or `strict`, the grouped summary looks like this:
+
+```
+sveld: 5 unresolved types found.
+
+Props without inferred types (1):
+  ./icons/Add.svelte
+    - Prop "title" type could not be inferred; falling back to "any". (./icons/Add.svelte:4:2)
+
+Context values typed as `any` (1):
+  ./ThemeProvider.svelte
+    - Context "theme" variable "themeStore" has no type annotation; defaulted to "any". (./ThemeProvider.svelte:8:6)
+
+@event tags with no dispatch or callback (2):
+  ./Modal.svelte
+    - @event "open" has no matching dispatch or callback prop. (./Modal.svelte:3:5)
+    - @event "close" has no matching dispatch or callback prop. (./Modal.svelte:4:5)
+
+Component syntax sveld skipped (1):
+  ./Tabs.svelte
+    - {@render tabs(getTabProps())} argument is not a plain object literal; the render call was not mapped to slot metadata. (./Tabs.svelte:6:4)
+```
+
+When `checkExamples` is also enabled, `@example` compile failures appear as a fifth group:
+
+```
+@example blocks that failed to compile (1):
+  ./Component.svelte
+    - Line 1: Cannot find name 'formatValue'.
+```
+
+By default, nothing is printed. Opt in when you are working on types or want CI output:
+
+```ts
+await sveld({ json: true, reportDiagnostics: true });
+```
+
+Use `strict: true` (or `--strict`) to exit with code `1` when diagnostics exist. `strict` implies `reportDiagnostics`, so CI always shows why the run failed.
+
+```ts
+await sveld({ json: true, strict: true });
+```
+
+CLI equivalent:
+
+```sh
+npx sveld --json --report-diagnostics
+npx sveld --json --strict
+```
+
+`--check` is separate: it diffs `COMPONENT_API.json` for API drift and semver classification, not inference warnings.
+
+## Requirements
+
+- Node 22+. CI tests against Node 22 on Linux, Windows, and macOS; earlier LTS versions are not verified.
+- `sveld` is ESM-only. `require("sveld")` does not work — use `import` or dynamic `import()`.
+- `sveld` bundles its own Svelte 5 compiler to parse `.svelte` files. Parsing does not depend on the Svelte version installed in your project, so Svelte 3 and Svelte 4 codebases parse the same way Svelte 5 codebases do — there is no compiler version to match up.
+
 ## Usage
 
 ### Installation
@@ -276,7 +417,7 @@ yarn add -D sveld
 
 ### Vite
 
-Import and add `sveld` as a plugin to your `vite.config.ts`. The plugin only runs during `vite build` (not the dev server).
+Import and add `sveld` as a plugin to your `vite.config.ts`. The plugin only runs during `vite build`, unless `watch: true` is set, in which case it also regenerates output during `vite dev`.
 
 ```ts
 // vite.config.ts
@@ -291,7 +432,7 @@ export default defineConfig({
 
 Since Vite uses Rollup for production builds, the same plugin works in Rollup configs.
 
-By default, `sveld` will use the `"svelte"` field from your `package.json` to determine the entry point. You can override this by specifying an explicit `entry` option:
+By default, `sveld` uses the `"svelte"` field from your `package.json` to determine the entry point. You can override this by specifying an explicit `entry` option:
 
 ```js
 sveld({
@@ -302,7 +443,6 @@ sveld({
 When building the library, TypeScript definitions are emitted to the `types` folder by default.
 
 Customize the output folder using the `typesOptions.outDir` option.
-Use `typesOptions.printWidth` to control Prettier wrapping for generated `.d.ts` files. The default is `80`.
 
 The following example emits the output to the `dist` folder:
 
@@ -310,7 +450,6 @@ The following example emits the output to the `dist` folder:
 sveld({
 +  typesOptions: {
 +    outDir: 'dist',
-+    printWidth: 80
 +  }
 })
 ```
@@ -329,6 +468,12 @@ Generate documentation in JSON and/or Markdown formats using the following flags
 npx sveld --json --markdown
 ```
 
+If no entry point can be resolved (no `package.json#svelte` field and no `--entry`), the CLI exits `1` and prints the reason to `stderr`. If `src/index.js` happens to exist relative to your working directory, sveld falls back to it and prints a one-line note asking you to set `package.json#svelte` (or `--entry`) instead of relying on the fallback.
+
+Flags are kebab-case: `--entry`, `--glob`, `--types`, `--json`, `--markdown`, `--fail-fast`, `--cache`, `--resolve-types`, `--check-examples`, `--report-diagnostics`, `--strict`, `--check`, `--types-format`. The camelCase spellings `--resolveTypes` and `--checkExamples` still work as deprecated aliases for compatibility with existing scripts. An unrecognized flag (e.g. `--markdwon`) prints `Unknown flag: --markdwon` to `stderr`, exits `1`, and skips generation; sveld takes no positional arguments, so any non-flag argument errors the same way.
+
+Run `npx sveld --help` for the full flag list with descriptions, or `npx sveld --version` to print the installed version.
+
 ### CI: API-drift checks (`--check`)
 
 `--check` diffs the parsed component API against a committed `COMPONENT_API.json` snapshot, assigns a semver bump to each change, and exits `1` when it finds a breaking change.
@@ -355,18 +500,22 @@ Removed props, events, or slots, and props that become required, are breaking (`
 
 Use `--check=<path>` to diff against a snapshot at a custom location (defaults to `jsonOptions.outFile`, or `COMPONENT_API.json`).
 
+The CLI exits non-zero on any fatal error (an unreadable entry, a config file that throws, etc.), not just on `--strict`/`--check` findings, so it's safe to use either flag as a CI gate.
+
 ### Node.js
 
-You can also call `sveld` from Node.js. The package is **ESM-only**; `require("sveld")` does not work. Use `import` or dynamic `import()`.
+You can also call `sveld` from Node.js. See [Requirements](#requirements) for supported Node versions and the ESM-only constraint.
+
+If no `entry` is specified, `sveld` infers the entry point based on the `package.json#svelte` field. If no entry point can be resolved, `sveld()` throws with an actionable message (previously it resolved to `{ diagnostics: [] }` and generated nothing).
 
-If no `input` is specified, `sveld` will infer the entry point based on the `package.json#svelte` field.
+> `input` was renamed to `entry` to match the CLI, plugin, and config. Calls passing `input` throw with a message pointing at `entry`.
 
 ```js
 import { sveld } from "sveld";
 import pkg from "./package.json" with { type: "json" };
 
-sveld({
-  input: "./src/index.js",
+const { diagnostics } = await sveld({
+  entry: "./src/index.js",
   glob: true,
   markdown: true,
   markdownOptions: {
@@ -385,6 +534,23 @@ sveld({
 });
 ```
 
+`diagnostics` is always populated; printing is opt-in via `reportDiagnostics` or `strict` (see [Type inference diagnostics](#type-inference-diagnostics)).
+
+Pass `check: true` (or `check: "<path>"` for a custom snapshot location) to diff against a committed `COMPONENT_API.json`, the same way `--check` does on the CLI. The result lands on `SveldResult.check`; sveld does not print it or touch `process.exitCode` for you, so inspect and act on it yourself:
+
+```js
+import { formatCheckReport } from "sveld";
+
+const { check } = await sveld({ json: true, check: true });
+
+if (check) {
+  console.log(formatCheckReport(check));
+  if (check.bump === "major") process.exitCode = 1;
+}
+```
+
+See [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check) for how changes are classified.
+
 #### `jsonOptions.outDir`
 
 With `json: true`, `sveld` writes `COMPONENT_API.json` at the project root. The file documents all components.
@@ -425,17 +591,34 @@ CLI flags > config file > `package.json#svelte` inference / defaults
 
 With the config above, `npx sveld --json` keeps `glob` and `markdown` from the file. A CLI flag overrides the same key in the config.
 
+`strict`, `reportDiagnostics`, and `check` are valid config keys too — not just CLI flags or `sveld()` options — and follow the same precedence: a CLI flag (or an option passed to `sveld()`) overrides the same key set in the config file.
+
+```js
+// sveld.config.js
+export default {
+  json: true,
+  strict: true,
+  check: "snapshots/COMPONENT_API.json",
+};
+```
+
 A bad config (syntax error, throws at load time, or no default-export object) fails with an error that names the file.
 
 ### Publishing to NPM
 
-TypeScript definitions land in the `types` folder by default. Include that folder in `package.json` when you publish to npm.
+TypeScript definitions land in the `types` folder by default. Point consumers at them with an `exports` map, and include that folder in `package.json` when you publish to npm.
 
 ```diff
 {
   "svelte": "./src/index.js",
++ "exports": {
++   ".": {
++     "types": "./types/index.d.ts",
++     "svelte": "./src/index.js",
++     "default": "./lib/index.mjs"
++   }
++ },
   "main": "./lib/index.mjs",
-+ "types": "./types/index.d.ts",
   "files": [
     "src",
     "lib",
@@ -444,24 +627,36 @@ TypeScript definitions land in the `types` folder by default. Include that folde
 }
 ```
 
+The `svelte` condition lets bundlers that understand it (Vite, Rollup, webpack via `svelte-loader`) resolve straight to source; `types` and `default` cover TypeScript and everything else. Keep the top-level `"svelte"` field too — older tooling that predates conditional exports still reads it directly.
+
 ## Available Options
 
 ### Plugin Options
 
-- **`entry`** (string, optional): Specify the entry point to uncompiled Svelte source. If not provided, sveld will use the `"svelte"` field from `package.json`.
+- **`entry`** (string, optional): Specify the entry point to uncompiled Svelte source. If not provided, sveld uses the `"svelte"` field from `package.json`.
 - **`glob`** (boolean, optional): Enable glob mode to analyze all `*.svelte` files.
 - **`documentExports`** (boolean, optional): Include consts, functions, and types from the entry barrel in JSON (`exports`) and Markdown ("Exports"). Off by default. See [Documenting Entry Exports](#documenting-entry-exports).
 - **`types`** (boolean, optional, default: `true`): Generate TypeScript definitions.
-- **`typesOptions`** (object, optional): Options for TypeScript definition generation, including `outDir`, `preamble`, and `printWidth`.
+<<<<<<< HEAD
+- **`typesOptions`** (object, optional): Options for TypeScript definition generation, including `outDir`, `preamble`, and `format`.
+  - **`format`** (`"class"` | `"component"`, optional, default: `"class"`): `.d.ts` output shape. `"class"` extends `SvelteComponentTyped`; `"component"` emits the Svelte 5 `Component` type. Also available as `--types-format`. See [`.d.ts` output format](#dts-output-format-typesoptionsformat).
+=======
+- **`typesOptions`** (object, optional): Options for TypeScript definition generation, including `outDir` and `preamble`.
+>>>>>>> 0724225 (feat(writer)!: remove prettier entirely)
 - **`json`** (boolean, optional): Generate component documentation in JSON format.
 - **`jsonOptions`** (object, optional): Options for JSON output.
 - **`markdown`** (boolean, optional): Generate component documentation in Markdown format.
 - **`markdownOptions`** (object, optional): Options for Markdown output.
+- **`customElements`** (boolean, optional): Generate a [Custom Elements Manifest](#custom-elements-manifest) (`custom-elements.json`). Also available as the `--custom-elements` CLI flag.
+- **`customElementsOptions`** (object, optional): Options for Custom Elements Manifest output, including `outFile`.
 - **`watch`** (boolean, optional, default: `false`): Regenerate output incrementally when `.svelte` source changes during `vite dev` / `vite build --watch`. Only the changed component and the components that depend on it via [`@extendProps`](#extendprops) / `@extends` are re-parsed, rather than rebuilding every component. Without this option, the plugin only runs during `vite build`.
 - **`failFast`** (boolean, optional, default: `false`): Abort the entire run when a single component fails to parse. By default, parse failures are collected as diagnostics (and reported to `stderr`) so the remaining components still emit their output. Also available as the `--fail-fast` CLI flag.
-- **`resolveTypes`** (boolean, optional, default: `false`): Load the TypeScript program to expand opaque imported whole-object `$props()` types into JSON. See [Opt-in semantic resolution](#opt-in-semantic-resolution-resolvetypes).
-- **`cache`** (boolean | string, optional, default: `false`): Write parsed component output to disk and skip re-parsing unchanged files on later runs. `true` uses `node_modules/.cache/sveld/parse-cache.json`; a string sets a custom path. Also available as `--cache` / `--cache=<path>`. See [Persistent parse cache](#persistent-parse-cache-cache).
-- **`checkExamples`** (boolean, optional, default: `false`): Run plain TS/JS `@example` blocks through the TypeScript program. Broken ones get an `example-compile-error` diagnostic. See [Compile-checked `@example` blocks](#compile-checked-example-blocks-checkexamples).
+- **`resolveTypes`** (boolean, optional, default: `false`): Load the TypeScript program to expand opaque imported whole-object `$props()` types into JSON. Also available as `--resolve-types` (`--resolveTypes` remains as a deprecated alias). See [Opt-in semantic resolution](#opt-in-semantic-resolution-resolvetypes).
+- **`cache`** (boolean | string, optional, default: `true`): Write parsed component output to disk and skip re-parsing unchanged files on later runs. On by default, writing to `node_modules/.cache/sveld/parse-cache.json`; a string sets a custom path; pass `false` to disable. Also available as `--cache` / `--cache=<path>` / `--cache=false`. See [Persistent parse cache](#persistent-parse-cache-cache).
+- **`checkExamples`** (boolean, optional, default: `false`): Run plain TS/JS `@example` blocks through the TypeScript program. Broken ones get an `example-compile-error` diagnostic. Also available as `--check-examples` (`--checkExamples` remains as a deprecated alias). See [Compile-checked `@example` blocks](#compile-checked-example-blocks-checkexamples).
+- **`reportDiagnostics`** (boolean, optional, default: `false`): Print unresolved-type diagnostics to stderr (CLI) or `console.warn` (programmatic API). Also available as `--report-diagnostics`. See [Type inference diagnostics](#type-inference-diagnostics).
+- **`strict`** (boolean, optional, default: `false`): Exit with code `1` when diagnostics exist. Implies `reportDiagnostics`. Also available as `--strict`. See [Type inference diagnostics](#type-inference-diagnostics).
+- **`check`** (boolean | string, optional, default: `false`): Diff the parsed component API against a committed snapshot and assign a semver bump to each change. `true` uses the `json` writer's `outFile` (or `COMPONENT_API.json`); a string sets a custom snapshot path. Also available as `--check` / `--check=<path>`. On the CLI this exits `1` on a breaking change; from `sveld()` it's returned on `SveldResult.check` for you to act on. See [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check).
 
 By default, only TypeScript definitions are generated.
 
@@ -503,7 +698,7 @@ JSON adds `exports` and `totalExports`. Markdown adds an "Exports" section. Each
 ## JSON Output
 
 When `json: true` is enabled, `sveld` emits a `COMPONENT_API.json` file with schema and generator metadata plus the parsed
-component API.
+component API. For stable output, generated `events` arrays are emitted in deterministic sorted order.
 
 The JSON Schema lives on GitHub ([path to file](https://github.com/carbon-design-system/sveld/blob/main/schema/component-api.schema.json), [raw URL](https://raw.githubusercontent.com/carbon-design-system/sveld/main/schema/component-api.schema.json)). Use it to validate generated `COMPONENT_API.json` files. Optional fields may be missing when the parser has no stable source for that metadata.
 
@@ -559,6 +754,7 @@ interface ComponentDocApi {
   componentComment?: string;
   componentCommentSource?: SourceRange;
   contexts?: ComponentContext[];
+  customElementTag?: string;
 }
 
 interface ComponentProp {
@@ -625,6 +821,47 @@ Prop metadata is additive and keeps the older public fields:
 - `value` remains the raw default expression string. `defaultValue` adds structured metadata with the same raw expression, a coarse `kind`, and a parsed `value` only for JSON-safe literals, arrays, and plain objects. `sveld` does not evaluate arbitrary code.
 - `bindable: true` is emitted only for props explicitly declared with Svelte 5 `$bindable(...)`. Missing `bindable` should be treated as false.
 
+## Custom Elements Manifest
+
+Set `customElements: true` to emit a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) (`custom-elements.json`, `schemaVersion: "1.0.0"`). This is the interchange format the web-components ecosystem standardized on: Storybook autodocs, VS Code/JetBrains HTML data, and other CEM-aware tooling can all read it directly.
+
+```diff
+sveld({
++  customElements: true,
+})
+```
+
+- **`customElements`** (boolean, optional): Generate `custom-elements.json`.
+- **`customElementsOptions.outFile`** (string, optional, default: `"custom-elements.json"`): Override the output path.
+- Also available as the `--custom-elements` CLI flag.
+
+Each exported component becomes one `javascript-module` with a class declaration:
+
+- **Members** — every prop becomes a `ClassField` (`name`, `type.text`, `default`, `description`, `deprecated`).
+- **Attributes** — derived conservatively from props: only props with a bare primitive type (`string`, `number`, or `boolean`) become attributes, using the same default name Svelte's custom-element runtime uses (`prop.toLowerCase()`, unless the tool's own `attribute` override applies). Props whose lowercased name collides with another prop are dropped from `attributes` on both sides, since which one wins at runtime is ambiguous. Complex types (arrays, objects, unions, custom types) never become attributes.
+- **Events** — dispatched events (`createEventDispatcher()`, and `$host().dispatchEvent(...)` from inside a custom element) become `{ name, type: { text: "CustomEvent<...>" } }`. Forwarded (`on:click`) events are left out, since they aren't dispatched by the component's own class.
+- **Slots** — named and default slots, with descriptions. The default slot's `name` is `""`, matching the CEM convention.
+
+When a component sets `<svelte:options customElement="x-foo" />` (or the object form, `<svelte:options customElement={{ tag: "x-foo" }} />`), its declaration gets `tagName: "x-foo"` and `customElement: true`, and the module's `exports` include a `custom-element-definition` export alongside the plain `js` export.
+
+Components without `customElement` still emit a plain class declaration (no `tagName`/`customElement`) — useful for documenting the class shape even before it's compiled as a custom element, but the manifest is most useful for `customElement`-compiled builds, where downstream tooling can resolve `tagName`, `attributes`, and `events` for actual custom-element usage.
+
+### Consuming the manifest
+
+Most tools discover `custom-elements.json` through a `customElements` field in `package.json`, pointing at the generated file:
+
+```json
+{
+  "customElements": "custom-elements.json"
+}
+```
+
+With that in place:
+
+- The [VS Code custom elements extension](https://marketplace.visualstudio.com/items?itemName=BendingSpoons.vscode-custom-elements) and JetBrains IDEs pick it up automatically, giving tag name, attribute, and slot completion/hover in HTML and Svelte templates.
+- [Storybook](https://storybook.js.org/docs/api/doc-blocks/doc-block-argtypes#extracting-argtypes) for web components reads the manifest to auto-generate `argTypes` (controls, docs tables) for `customElement`-compiled components, once you point it at the file (e.g. `setCustomElementsManifest` from `@storybook/web-components`, or `customElements: "custom-elements.json"` in `.storybook/main.js`).
+- Any other tool built against the [Custom Elements Manifest spec](https://github.com/webcomponents/custom-elements-manifest) (API viewers, doc generators, linters) can read the file directly without sveld-specific integration.
+
 ## API Reference
 
 ### `reactive`
@@ -674,11 +911,9 @@ Generated JSON includes `"binding": "readonly"` or `"binding": "writable"` for a
 
 This is documentation only. Generated `.svelte.d.ts` prop types do not change. TypeScript cannot express Svelte binding direction reliably.
 
-For stable output, generated `events` arrays are emitted in deterministic sorted order.
-
 ### `@type`
 
-Without a `@type` annotation, `sveld` will infer the primitive type for a prop:
+Without a `@type` annotation, `sveld` infers the primitive type for a prop:
 
 ```js
 export let kind = "primary";
@@ -707,8 +942,6 @@ For `lang="ts"` components, prefer native TypeScript annotations when you alread
 
 **Example:**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <script>
   let {
@@ -728,7 +961,8 @@ For `lang="ts"` components, prefer native TypeScript annotations when you alread
 
 For runes components with multiple destructured props, put JSDoc on the property you want to document. A declaration-level block is a fallback when the destructure exposes a single public prop.
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <script>
@@ -746,6 +980,8 @@ For runes components with multiple destructured props, put JSDoc on the property
 </script>
 ```
 
+</details>
+
 #### Importing types
 
 `sveld` supports TypeScript's [`import(...)` type syntax](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#import-types), so a `@type` or `@typedef` can reference a type from another module without a top-level `import`. The expression is copied verbatim into the generated `.d.ts` and resolves the same way as hand-written TypeScript:
@@ -956,8 +1192,6 @@ The `@typedef` tag defines a shared type used multiple times in a component. All
 
 **Example:**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <script>
   /**
@@ -974,7 +1208,8 @@ The `@typedef` tag defines a shared type used multiple times in a component. All
 </script>
 ```
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <script>
@@ -991,6 +1226,8 @@ The `@typedef` tag defines a shared type used multiple times in a component. All
 </script>
 ```
 
+</details>
+
 #### Using `@property` for complex typedefs
 
 For complex object types, use `@property` to document individual fields. That gives per-property tooltips in the IDE.
@@ -1007,8 +1244,6 @@ For complex object types, use `@property` to document individual fields. That gi
 
 **Example:**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <script>
   /**
@@ -1024,7 +1259,8 @@ For complex object types, use `@property` to document individual fields. That gi
 </script>
 ```
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <script>
@@ -1041,6 +1277,10 @@ For complex object types, use `@property` to document individual fields. That gi
 </script>
 ```
 
+</details>
+
+Output is identical for both syntax modes.
+
 Output:
 
 ```ts
@@ -1078,8 +1318,6 @@ Use square brackets for optional properties, per JSDoc. Default values use `[pro
 
 **Example:**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <script>
   /**
@@ -1096,7 +1334,8 @@ Use square brackets for optional properties, per JSDoc. Default values use `[pro
 </script>
 ```
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <script>
@@ -1114,6 +1353,10 @@ Use square brackets for optional properties, per JSDoc. Default values use `[pro
 </script>
 ```
 
+</details>
+
+Output is identical for both syntax modes.
+
 Output:
 
 ```ts
@@ -1403,8 +1646,6 @@ Use it for callback props when you do not want inline function type syntax.
 
 **Example:**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <script>
   /**
@@ -1420,7 +1661,8 @@ Use it for callback props when you do not want inline function type syntax.
 </script>
 ```
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <script>
@@ -1437,6 +1679,10 @@ Use it for callback props when you do not want inline function type syntax.
 </script>
 ```
 
+</details>
+
+Output is identical for both syntax modes.
+
 Output:
 
 ```ts
@@ -1494,8 +1740,6 @@ Omit the `slot-name` to type the default slot.
 
 **Example:**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <script>
   /**
@@ -1517,7 +1761,8 @@ Omit the `slot-name` to type the default slot.
 </p>
 ```
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <script>
@@ -1540,6 +1785,8 @@ Omit the `slot-name` to type the default slot.
 </p>
 ```
 
+</details>
+
 #### Extra JSDoc tags before `@slot`
 
 Tags such as `@example`, `@see`, or `@since` that appear after the prose description and before the `@slot` / `@snippet` line are copied into generated `.d.ts` files. The emitted JSDoc above each slot's snippet prop (and the traditional `SlotDefs` shape) lists the description, then those tags in source order. The same entries appear in JSON as `tags: [{ "name", "body" }, ...]`.
@@ -1693,8 +1940,6 @@ Use `null` as the value if no event detail is provided.
 
 **Example:**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <script>
   /**
@@ -1729,7 +1974,8 @@ Use `null` as the value if no event detail is provided.
 </script>
 ```
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <script>
@@ -1749,6 +1995,10 @@ Use `null` as the value if no event detail is provided.
 </script>
 ```
 
+</details>
+
+Output is identical for both syntax modes.
+
 Output:
 
 ```ts
@@ -1781,8 +2031,6 @@ This is the idiomatic way to describe each field of an event detail. An inline o
 
 **Example:**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <script>
   /**
@@ -1809,7 +2057,8 @@ This is the idiomatic way to describe each field of an event detail. An inline o
 <button type="button" onclick={handleSubmit}>Submit</button>
 ```
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <script>
@@ -1839,6 +2088,10 @@ This is the idiomatic way to describe each field of an event detail. An inline o
 <button type="button" on:click={handleSubmit}>Submit</button>
 ```
 
+</details>
+
+Output is identical for both syntax modes.
+
 Output:
 
 ```ts
@@ -1865,8 +2118,6 @@ Like typedefs, you can mark event detail properties as optional with square brac
 
 **Example:**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <script>
   /**
@@ -1897,7 +2148,8 @@ Like typedefs, you can mark event detail properties as optional with square brac
 <button type="button" onclick={throwSnowball}>Throw</button>
 ```
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <script>
@@ -1929,6 +2181,10 @@ Like typedefs, you can mark event detail properties as optional with square brac
 <button type="button" on:click={throwSnowball}>Throw</button>
 ```
 
+</details>
+
+Output is identical for both syntax modes.
+
 Output:
 
 ```ts
@@ -2067,8 +2323,6 @@ Anything else (dynamic identifiers, template interpolation, other function calls
 
 **Modal.svelte**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <script>
   import { setContext } from "svelte";
@@ -2099,7 +2353,8 @@ Anything else (dynamic identifiers, template interpolation, other function calls
 </div>
 ```
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <script>
@@ -2129,6 +2384,10 @@ Anything else (dynamic identifiers, template interpolation, other function calls
 </div>
 ```
 
+</details>
+
+Output is identical for both syntax modes.
+
 **Generated TypeScript definition:**
 
 ```ts
@@ -2238,7 +2497,7 @@ There are several ways to type contexts:
 
 #### Notes
 
-- Context keys must be string literals (dynamic keys are not supported)
+- Context keys must be statically resolvable: a string literal, a static template literal, a `const`-bound string, or a `Symbol()` / `Symbol.for()` call with a static description. Dynamic expressions (runtime identifiers, template interpolation, other function calls) are skipped with a warning.
 - Variables passed to `setContext` should have JSDoc `@type` annotations for accurate types
 - The generated type name follows the pattern: `{PascalCase}Context`. Separators (hyphens, underscores, dots, colons, slashes, spaces) are stripped and each segment is capitalized:
   | Context Key | Generated Type Name |
@@ -2272,8 +2531,6 @@ Use `@restProps` to name the element tags `$$restProps` is forwarded to.
 
 **Example:**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <script>
   import Button from "./Button.svelte";
@@ -2291,7 +2548,8 @@ Use `@restProps` to name the element tags `$$restProps` is forwarded to.
 {/if}
 ```
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <script>
@@ -2308,6 +2566,8 @@ Use `@restProps` to name the element tags `$$restProps` is forwarded to.
 {/if}
 ```
 
+</details>
+
 ### `@extendProps`
 
 When a component wraps another, use `@extendProps` to extend generated props.
@@ -2334,14 +2594,15 @@ import Button from "./Button.svelte";
 
 ### `@template`
 
-Svelte supports defining generics via the [`generics` attribute](https://svelte.dev/docs/svelte/typescript) on the script tag, but this requires `lang="ts"`.
+Svelte supports defining generics via the [`generics` attribute](https://svelte.dev/docs/svelte/typescript) on the script tag, but this requires `lang="ts"`:
 
 ```svelte
-<!-- Requires lang="ts" -->
 <script lang="ts" generics="Row extends DataTableRow = any"></script>
 ```
 
-Because `sveld` targets JavaScript-only usage as a baseline, generics use the standard JSDoc `@template` tag. `@generics` is also supported as an alias.
+`sveld` reads the `generics` attribute directly, and it's the recommended way to declare generics for `lang="ts"` components. Because `sveld` also targets JavaScript-only usage as a baseline, plain JS (or JS-with-JSDoc) components instead use the standard JSDoc `@template` tag; `@generics` is also supported as an alias.
+
+**Precedence:** if a component declares generics both ways, the `generics` attribute wins — it's the compiler-checked source of truth — and the `@generics`/`@template` tag is reported as a `syntax-skipped` diagnostic rather than silently dropped. The attribute is invalid without `lang="ts"`; if present on a plain-JS script, sveld reports `syntax-skipped` and ignores it rather than guessing.
 
 **Signature:** Uses standard [JSDoc `@template` syntax](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template):
 
@@ -2361,8 +2622,6 @@ Because `sveld` targets JavaScript-only usage as a baseline, generics use the st
 
 **Component example:**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <script>
   /**
@@ -2384,7 +2643,8 @@ Because `sveld` targets JavaScript-only usage as a baseline, generics use the st
 {@render children?.({ headers, rows })}
 ```
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <script>
@@ -2405,6 +2665,10 @@ Because `sveld` targets JavaScript-only usage as a baseline, generics use the st
 <slot {headers} {rows} />
 ```
 
+</details>
+
+Output is identical for both syntax modes.
+
 Generated output looks like this:
 
 ```ts
@@ -2477,12 +2741,10 @@ For multiple generics, use a single `@generics` tag with comma-separated names:
 
 The Svelte Language Server supports component-level comments through the following syntax: `<!-- @component [comment] -->`.
 
-`sveld` will copy these over to the exported default component in the TypeScript definition.
+`sveld` copies these over to the exported default component in the TypeScript definition.
 
 **Example:**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <!-- @component
 @example
@@ -2499,7 +2761,8 @@ The Svelte Language Server supports component-level comments through the followi
 </button>
 ```
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <!-- @component
@@ -2513,6 +2776,10 @@ The Svelte Language Server supports component-level comments through the followi
 </button>
 ```
 
+</details>
+
+Output is identical for both syntax modes.
+
 Output:
 
 ```ts
@@ -2548,8 +2815,6 @@ Exported functions and consts become accessor props in generated TypeScript defi
 
 **Example:**
 
-**Svelte 5 Runes:**
-
 ```svelte
 <script>
   /**
@@ -2593,7 +2858,8 @@ Exported functions and consts become accessor props in generated TypeScript defi
 </div>
 ```
 
-**Svelte 3, 4, 5 (non-Runes):**
+<details>
+<summary>Svelte 3/4 (legacy) syntax</summary>
 
 ```svelte
 <script>
@@ -2632,6 +2898,10 @@ Exported functions and consts become accessor props in generated TypeScript defi
 </script>
 ```
 
+</details>
+
+Output is identical for both syntax modes.
+
 Output:
 
 ```ts
@@ -2667,6 +2937,14 @@ export default class Component extends SvelteComponentTyped<
 
 When only `@param` tags are present without `@returns`, the return type defaults to `any`. When only `@returns` is present without `@param`, the function signature is `() => returnType`.
 
+## Troubleshooting
+
+**A prop came out `any`.** Enable [`reportDiagnostics`](#type-inference-diagnostics) (or `strict` to fail CI) to see which props sveld couldn't infer, then tighten them with `@type` or a native TypeScript annotation.
+
+**Generated types don't appear for consumers.** Check that the `types` folder is listed in `exports` and `files` in `package.json`. See [Publishing to NPM](#publishing-to-npm).
+
+**Output differs in CI.** Commit `COMPONENT_API.json` and run [`--check`](#ci-api-drift-checks---check) in CI so API drift fails the build instead of silently diverging.
+
 ## Contributing
 
 See [contributing guidelines](CONTRIBUTING.md).