sveld 0.37.9 → 0.38.1

package/README.md

@@ -3,29 +3,95 @@
 [![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, module exports, context, and `$$restProps`. Add types with [JSDoc](https://jsdoc.app/) when inference is not enough.
+`sveld` generates TypeScript definitions and component documentation (JSON and Markdown) for Svelte component libraries. It statically analyzes props, events, slots, snippets, context, module exports, and rest props, and reads [JSDoc](https://jsdoc.app/) where inference isn't 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.
+The generated `.d.ts` files give consumers autocomplete and type checking through the Svelte Language Server and TypeScript, with little effort from the library author. [Carbon Components Svelte](https://github.com/carbon-design-system/carbon-components-svelte) uses sveld to generate its component types and API metadata.
 
-[Carbon Components Svelte](https://github.com/carbon-design-system/carbon-components-svelte) uses this library to auto-generate component types and API metadata.
+sveld supports Svelte 3, Svelte 4, Svelte 5 without runes (`export let`, `<slot>`, `$$restProps`), and Svelte 5 runes (`$props()`, `$bindable()`, `{@render}`, callback props).
 
-`sveld` parses `.svelte` files with its own template parser (`src/template-parse/`), kept in parity with `svelte/compiler`'s parser by a differential test suite. 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`, …).
+## When to use sveld
 
-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 (whole-object and per-prop), local `interface`/`type`/`enum` declarations, and TypeScript signatures on accessor exports (`export function`). Any type a prop annotation or accessor signature depends on — whether imported with `import type` or as a plain value import used only in a type position — is re-emitted as an `import type` at the top of the generated `.d.ts`, and local `interface`/`type`/`enum` declarations it depends on are copied alongside it. Everything stays textual: no semantic expansion, and `satisfies`/`as` are treated alike. A `const enum` is widened to a literal union of its member values instead of being re-declared, since `const enum` isn't supported by common bundlers under `isolatedModules`.
+If your library is built with SvelteKit's `svelte-package`, it already emits `.d.ts` files through `svelte2tsx`; start there.
 
-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).
+sveld is for:
 
-## When to use sveld
+- **JavaScript-first libraries.** Components written in plain JavaScript with JSDoc, where you want full editor types without converting to `lang="ts"`.
+- **Docs from the same source as the types.** JSON and Markdown API docs, generated in the same run.
+- **API drift checks.** `--check` diffs the component API against a committed snapshot and fails CI on breaking changes.
+- **Richer types from JSDoc.** `@typedef`, `@callback`, `@slot`, `@event`, and context types that plain inference can't produce.
+
+`lang="ts"` components work too: sveld keeps their type annotations as written.
+
+## Install
+
+```sh
+npm i -D sveld
+# or: pnpm i -D sveld / bun i -D sveld / yarn add -D sveld
+```
+
+## Quick start
+
+sveld reads the `"svelte"` field of your `package.json` as the entry point: the file that re-exports your components.
+
+```json
+{
+  "svelte": "./src/index.js"
+}
+```
+
+### CLI
+
+```sh
+npx sveld                     # writes types/*.d.ts
+npx sveld --json --markdown   # also writes COMPONENT_API.json and COMPONENT_INDEX.md
+```
+
+Run `npx sveld --help` for every flag. Options can also live in a `sveld.config.js`:
+
+```js
+// sveld.config.js
+import { defineConfig } from "sveld";
+
+export default defineConfig({
+  json: true,
+  markdown: true,
+});
+```
+
+### Vite plugin
 
-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.
+```ts
+// vite.config.ts
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import sveld from "sveld";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [svelte(), sveld({ json: true })],
+});
+```
+
+The plugin runs during `vite build` (and during `vite dev` with `watch: true`). It also works in Rollup configs.
+
+### Node
+
+```js
+import { sveld } from "sveld";
+
+const { document, diagnostics, exitCode } = await sveld({
+  entry: "./src/index.js",
+  json: true,
+});
+```
 
----
+`document` is the same component API document `json: true` writes, so you can render your own formats from it. See [Options](docs/options.md) for everything `sveld()` accepts and returns.
 
-From a Svelte component, `sveld` can infer basic prop types and emit definitions the [Svelte Language Server](https://github.com/sveltejs/language-tools) understands:
+## Example
 
-**Button.svelte**
+Given this component:
 
 ```svelte
+<!-- Button.svelte -->
 <script>
   export let type = "button";
   export let primary = false;
@@ -36,11 +102,10 @@ From a Svelte component, `sveld` can infer basic prop types and emit definitions
 </button>
 ```
 
-The following generated `.d.ts` extends `SvelteComponentTyped`:
-
-**Button.svelte.d.ts**
+sveld infers prop types and defaults, the forwarded `click` event, the default slot, and the rest props spread onto `<button>`:
 
 ```ts
+// types/Button.svelte.d.ts
 import { SvelteComponentTyped } from "svelte";
 import type { SvelteHTMLElements } from "svelte/elements";
 
@@ -57,6 +122,8 @@ type $Props = {
    */
   primary?: boolean;
 
+  children?: (this: void) => void;
+
   [key: `data-${string}`]: unknown;
 };
 
@@ -69,28 +136,23 @@ 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.
+The default slot is also typed as a `children` snippet prop for Svelte 5 consumers, and the `data-*` index signature lets callers pass data attributes through `$$restProps`.
 
-Inference only gets you so far. Use [JSDoc](https://jsdoc.app/) to document prop, event, and slot types when you need more precision.
+Add JSDoc to tighten types and add descriptions:
 
-```js
-/** @type {"button" | "submit" | "reset"} */
-export let type = "button";
+```svelte
+<script>
+  /** @type {"button" | "submit" | "reset"} */
+  export let type = "button";
 
-/**
- * Set to `true` to use the primary variant
- */
-export let primary = false;
+  /**
+   * Set to `true` to use the primary variant
+   */
+  export let primary = false;
+</script>
 ```
 
-With JSDoc, the output looks like this:
-
 ```ts
-import { SvelteComponentTyped } from "svelte";
-import type { SvelteHTMLElements } from "svelte/elements";
-
-type $RestProps = SvelteHTMLElements["button"];
-
 type $Props = {
   /**
    * @default "button"
@@ -102,4350 +164,126 @@ type $Props = {
    * @default false
    */
   primary?: boolean;
-};
-
-export type ButtonProps = Omit<$RestProps, keyof $Props> & $Props;
-
-export default class Button extends SvelteComponentTyped<
-  ButtonProps,
-  { click: WindowEventMap["click"] },
-  { default: Record<string, never> }
-> {}
-```
-
----
-
-## 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)
-    - [Diagnostic codes](#diagnostic-codes)
-    - [Severity and `--strict=errors`](#severity-and---stricterrors)
-    - [Ignoring diagnostics](#ignoring-diagnostics)
-- [Requirements](#requirements)
-- [Usage](#usage)
-  - [Installation](#installation)
-  - [Vite](#vite)
-  - [CLI](#cli)
-  - [Exit codes](#exit-codes)
-  - [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check)
-  - [CI: strictness profiles (`--strict=ci`/`--strict=local`)](#ci-strictness-profiles---strictci---strictlocal)
-  - [Node.js](#nodejs)
-  - [Browser](#browser)
-  - [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)
-- [llms.txt Output](#llmstxt-output)
-- [Custom Writers](#custom-writers)
-  - [The `OutputWriter` contract](#the-outputwriter-contract)
-  - [Registering a writer](#registering-a-writer)
-  - [Running it via the plugin](#running-it-via-the-plugin)
-  - [Worked example: a `components.txt` name-list writer](#worked-example-a-componentstxt-name-list-writer)
-- [API Reference](#api-reference)
-  - [reactive](#reactive)
-  - [binding](#binding)
-  - [@type](#type)
-  - [@default](#default)
-  - [@typedef](#typedef)
-  - [@property](#property)
-  - [@callback](#callback)
-  - [@slot / @snippet](#slot--snippet)
-    - [Extra JSDoc tags before `@slot`](#extra-jsdoc-tags-before-slot)
-    - [Svelte 5 Snippet Compatibility](#svelte-5-snippet-compatibility)
-  - [@event](#event)
-  - [@ignore / @internal](#ignore--internal)
-  - [@deprecated](#deprecated)
-  - [@since](#since)
-  - [@see](#see)
-  - [@link](#link)
-  - [@example](#example)
-  - [Context API](#context-api)
-  - [@restProps](#restprops)
-  - [@extendProps](#extendprops)
-  - [@template](#template)
-  - [@generics](#generics)
-  - [@component comments](#component-comments)
-  - [Accessor Props](#accessor-props)
-- [Troubleshooting](#troubleshooting)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Approach
-
-`sveld` statically analyzes exported components and emits docs for consumers. Template parsing runs through sveld's own parser rather than `svelte/compiler`; `svelte/compiler` is imported only for its types, and `svelte/package.json` is read for the installed Svelte version. A differential test (`tests/svelte-template-parse-shim.test.ts`) parses every fixture `.svelte` file with both parsers and asserts the resulting ASTs match, and a weekly `svelte-canary` workflow re-runs that comparison against `svelte@latest` ahead of the lockfile pin.
-
-It extracts:
-
-- props
-- slots
-- forwarded events
-- dispatched events
-- context (setContext/getContext)
-- `$$restProps`
-
-When inference fails, props fall back to `any` rather than guessing wrong. Authors can tighten types with JSDoc. Comments are optional from the compiler's point of view, so plain JavaScript components still parse.
-
-When both TypeScript syntax and JSDoc are present, `sveld` resolves prop types in this order:
-
-1. explicit TypeScript annotation
-2. explicit JSDoc annotation
-3. initializer inference
-4. `any`
-
-`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.
-
-## 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.
+  children?: (this: void) => void;
 
-```ts
-await sveld({ types: true, typesOptions: { format: "component" } });
+  [key: `data-${string}`]: unknown;
+};
 ```
 
-Also available as `--types-format=component` on the CLI.
+The runes version (`let { type = "button", primary = false, children, ...rest } = $props()`, spreading `rest` and rendering `children`) produces the same `$Props`. It has no `click` event, since runes components take `onclick` as a prop through `rest`.
 
-`"component"`'s three type parameters:
+The `.d.ts` extends `SvelteComponentTyped` by default, which works for consumers on Svelte 3, 4, and 5. Set `typesOptions.format: "component"` (`--types-format=component`) to emit the Svelte 5 `Component` type instead. See [Output](docs/output.md#formats).
 
-- **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."
+### JSON and Markdown
 
-**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:
+`npx sveld --markdown` documents the same component in `COMPONENT_INDEX.md`:
 
-```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;
-```
+```md
+## `Button`
 
-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.
+### Props
 
-### Opt-in semantic resolution (`resolveTypes`)
+| Prop name | Required | Kind | Reactive | Binding | Type | Default value | Description |
+| :- | :- | :- | :- | :- | :- | :- | :- |
+| type | No | <code>let</code> | No | -- | <code>"button" &#124; "submit" &#124; "reset"</code> | <code>"button"</code> | -- |
+| primary | No | <code>let</code> | No | -- | <code>boolean</code> | <code>false</code> | Set to `true` to use the primary variant |
 
-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.
+### Slots
 
-```ts
-await sveld({ json: true, resolveTypes: true });
-```
+| Slot name | Default | Props | Fallback | Description |
+| :- | :- | :- | :- | :- |
+| -- | Yes | <code>Record&lt;string, never> </code> | <code>Click me</code> | -- |
 
-```svelte
-<script lang="ts">
-  import type { Props } from "./types";
+### Events
 
-  let props: Props = $props();
-</script>
+| Event name | Type | Detail | Description |
+| :- | :- | :- | :- |
+| click | forwarded | -- | -- |
 ```
 
-Without `resolveTypes`, JSON lists no props. With it, each field shows up with `"typeSource": "typescript"`:
+`npx sveld --json` writes the same data to `COMPONENT_API.json`, validated by a [JSON Schema](schema/component-api.schema.json) that ships with the package. An excerpt of the prop entry:
 
-```jsonc
+```json
 {
-  "props": [
-    { "name": "disabled", "type": "boolean", "isRequired": false, "typeSource": "typescript" },
-    { "name": "href", "type": "string", "isRequired": true, "typeSource": "typescript" },
-    { "name": "variant", "type": "\"primary\" | \"secondary\"", "isRequired": true, "typeSource": "typescript" }
-  ]
+  "name": "type",
+  "kind": "let",
+  "type": "\"button\" | \"submit\" | \"reset\"",
+  "typeSource": "jsdoc",
+  "value": "\"button\"",
+  "isRequired": false,
+  "reactive": false
 }
 ```
 
-**Performance.** Off by default. This is one of the two paths that load TypeScript. It needs `typescript` 7+ and a `tsconfig.json` (see [Requirements](#requirements)); if either is missing, `resolveTypes` fails the run instead of silently producing empty props. It also 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`)
-
-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. Generated `.d.ts` text is cached the same way, but is only reused when the component source _and_ every `typesOptions` value that affects output (for example [`format`](#dts-output-format-typesoptionsformat)) are unchanged; changing any of them regenerates that component's `.d.ts` without invalidating its cached parse.
-
-```ts
-await sveld({ json: true });
-```
-
-By default this writes to `node_modules/.cache/sveld/parse-cache.json` in the project root, the nearest directory above the entry that has a `package.json`. Pass a string to use a different location, e.g. `cache: ".cache/sveld.json"` (relative paths resolve against the same project root), 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`)
-
-`@example` blocks are just text. Rename a prop and the sample code can sit there broken for months. Set `checkExamples: true` to check them: plain TS/JS bodies run through the TypeScript program, and `svelte`/`html` bodies run through sveld's own template parser. Broken examples show up as `example-compile-error` (TS/JS) or `example-syntax-error` (markup) diagnostics.
-
-```ts
-await sveld({ json: true, checkExamples: true });
-```
-
-```svelte
-<script>
-  /**
-   * Formats a value.
-   * @param {string} value
-   * @returns {string}
-   * @example
-   * ```js
-   * formatValue("ok");
-   * ```
-   */
-  export function formatValue(value) {
-    return value;
-  }
-</script>
-```
-
-If `formatValue` is later renamed and the example is never updated, `checkExamples` reports it:
-
-```
-@example blocks that failed to compile (1):
-  ./Component.svelte
-    - Line 1: Cannot find name 'formatValue'.
-```
-
-A `svelte`/`html`-fenced example is syntax-checked, not type-checked: sveld parses the markup and discards the AST, so it catches malformed markup (a mismatched closing tag, an unterminated attribute) but not a prop that doesn't exist or a type error inside an expression. Those still need `svelte-check` in the consumer's own tests. Bare unfenced markup (`<Button />` with no code fence) is skipped either way.
-
-```
-@example blocks that failed to parse (1):
-  ./Component.svelte
-    - Line 1: sveld: invalid closing tag </span>.
-```
-
-The TS/JS check is narrow on purpose too. It catches renamed or removed symbols and wrong argument counts. Neither path is full type checking, and neither pulls in types sveld cannot see.
-
-The TS/JS path needs `typescript` 7+ and a `tsconfig.json`, same as `resolveTypes` (see [Requirements](#requirements)); missing either fails the run rather than silently skipping every example. The markup path needs neither: pass `checkExamples: "syntax"` to run only it, so a project with only `svelte`/`html` examples (or no `tsconfig.json`) never loads TypeScript. 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`/`example-syntax-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.
-
-A prop with no type annotation, no `@type` JSDoc, and no initializer has nothing to infer a type or a default from: its JSON `type` stays absent (`"typeSource": "unknown"`), it triggers a `prop-unknown-type` diagnostic, and the emitted `.d.ts` types it as `any` with no `@default` line (rather than the literal type `undefined`).
-
-With `reportDiagnostics` or `strict`, the grouped summary looks like this:
-
-```
-sveld: 5 diagnostics (1 error, 4 warnings).
-
-Props without inferred types (1):
-  ./icons/Add.svelte
-    - Prop "title" type could not be inferred; falling back to "any". (./icons/Add.svelte:4:2) [sveld/prop-unknown-type]
+See [Output](docs/output.md#json-output) for the full shape.
 
-Context values typed as `any` (1):
-  ./ThemeProvider.svelte
-    - Context "theme" variable "themeStore" has no type annotation; defaulted to "any". (./ThemeProvider.svelte:8:6) [sveld/context-any-type]
+## In CI
 
-@event tags with no dispatch or callback (2):
-  ./Modal.svelte
-    - @event "open" has no matching dispatch or callback prop. (./Modal.svelte:3:5) [sveld/event-no-source]
-    - @event "close" has no matching dispatch or callback prop. (./Modal.svelte:4:5) [sveld/event-no-source]
-
-Component syntax sveld skipped (1):
-  ./List.svelte
-    - Both the "generics" script attribute and @generics/@template JSDoc tags declare component generics; the script attribute takes precedence and the JSDoc declaration was ignored. (./List.svelte:1:1) [sveld/syntax-skipped]
-```
-
-When `checkExamples` is also enabled, `@example` failures appear as additional groups: TS/JS failures under `example-compile-error`, `svelte`/`html` failures under `example-syntax-error`.
-
-```
-@example blocks that failed to compile (1):
-  ./Component.svelte
-    - Line 1: Cannot find name 'formatValue'. [sveld/example-compile-error]
-
-@example blocks that failed to parse (1):
-  ./Component.svelte
-    - Line 1: sveld: invalid closing tag </span>. [sveld/example-syntax-error]
-```
-
-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 `4` when diagnostics exist. `strict` implies `reportDiagnostics`, so CI always shows why the run failed.
-
-```ts
-await sveld({ json: true, strict: true });
-```
-
-CLI equivalent:
+Commit `COMPONENT_API.json`, then gate pull requests on API changes and inference gaps:
 
 ```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.
-
-#### Diagnostic codes
-
-Every diagnostic carries a stable, namespaced `code` (`"sveld/<kind>"`) alongside the older `kind`, so CI config and `diagnostics.ignore` matchers (below) have something that won't shift if the human-readable `message` text changes:
-
-| Code | Severity | Fix |
-| --- | --- | --- |
-| `sveld/prop-unknown-type` | `warning` | Add a native TypeScript annotation, a `@type` JSDoc tag, or an initializer sveld can infer a type from. |
-| `sveld/context-any-type` | `warning` | Annotate the `setContext` value's declaration with `@type` or a native TypeScript type. |
-| `sveld/slot-missing-type` | `warning` | Add the required `{Type}` annotation to the `@slot`/`@snippet` tag (e.g. `@slot {{}} name`); until then it falls back to `Record<string, never>`. |
-| `sveld/event-no-source` | `warning` | Dispatch the event (`createEventDispatcher`/`dispatch`), forward it (`on:name`), or add a matching `on<Name>` callback prop; otherwise remove the stale `@event` tag. |
-| `sveld/dispatch-escapes` | `warning` | The `createEventDispatcher()` result is passed to a function sveld can't follow: one that isn't imported from a local module, names an event with something other than a string literal, or passes the dispatcher on. Document the events it dispatches with `@event` tags. Add `@sveld-ignore sveld/dispatch-escapes` to the dispatcher's JSDoc once they're covered. |
-| `sveld/example-compile-error` | `error` | Fix the `@example` TS/JS code block so it type-checks, or remove the broken example. |
-| `sveld/example-syntax-error` | `error` | Fix the `@example` `svelte`/`html` markup so it parses, or remove the broken example. |
-| `sveld/syntax-skipped` | `error` | Rewrite the flagged syntax in a form sveld can model (see the diagnostic's `message` for what was skipped). |
-| `sveld/rest-props-unresolved` | `warning` | Spread `$$restProps` onto a plain element (or `svelte:element`) instead of a component, or add an `@restProps` tag to type it manually. |
-| `sveld/context-duplicate-key` | `warning` | Remove the duplicate `setContext` call, or give it a distinct key; only the first call's shape is used. |
-| `sveld/context-key-unresolved` | `warning` | Use a string literal, a `const`-bound string, `Symbol()`, or a string or `Symbol()` `export const` imported from a relative module as the `setContext` key; otherwise the context is left out of every output. |
-| `sveld/context-value-unresolved` | `warning` | Pass an object literal or a typed variable as the `setContext` value (e.g. `const store = writable(0);` with a `@type` annotation, or `{ store }`); a call or other expression has no shape sveld can describe, so the context is left out of every output. |
-| `sveld/spread-unresolved` | `warning` | Spread a local object literal or a variable with a resolvable type instead; otherwise the spread widens the generated type to `Record<string, any>`. |
-| `sveld/export-unresolved` | `warning` | Export a local declaration directly. Instance-script exports are props, so move a re-export (`export { x } from "..."`, or `export { x }` of an import) into `<script context="module">`, where sveld writes it to the `.d.ts` as-is. A class can't be a prop either, so export it from `<script context="module">`, where sveld documents it. |
-| `sveld/module-export-conflict` | `warning` | Rename the module-script export. `default` is always skipped (it collides with the component itself); a name matching the generated `<Name>Props`/`<Name>Exports` type breaks the `.d.ts` if the export carries a type. |
-| `sveld/extend-props-target-missing` | `error` | Point `@extends`/`@extendProps` at a file that exists, and (for a bundled `.svelte` target) name its generated `<Name>Props` interface exactly. |
-| `sveld/extend-props-duplicate` | `warning` | Remove the extra `@extends`/`@extendProps` tag; only the last one is used. |
-| `sveld/extend-props-override` | `warning` | Rename the own prop, or accept that it intentionally overrides the `@extends` target's prop of the same name. |
-| `sveld/jsdoc-unknown-tag` | `warning` | Fix the tag name if it's a typo (e.g. `@depreacted` → `@deprecated`); otherwise no action needed, the tag still passes through unchanged. Only surfaced under `--strict`/`--report-diagnostics`. |
-| `sveld/typedef-duplicate` | `warning` | Rename one of the `@typedef`/`@callback` declarations; only the later one is kept. |
-| `sveld/property-duplicate` | `warning` | Remove the duplicate `@property`; only the later one is kept. |
-| `sveld/generics-conflict` | `warning` | Rename one of the `@generics`/`@template` declarations to a distinct generic name. |
-| `sveld/event-description-ambiguous` | `warning` | Put an event's description above its `@event` tag (or indent it as a continuation of the tag's line), or give each event its own comment block. Unindented text after an `@event` is read as the description of the tag below it. |
-| `sveld/jsdoc-tag-dropped` | `warning` | Move the tag next to a `@slot`/`@snippet`/`@event`/`@typedef`/`@callback` tag in the same comment block so it has something to attach to. |
-| `sveld/internal-typedef-referenced` | `error` | Remove `@internal`/`@ignore` from the referenced typedef, or stop referencing it from public type text (inline the shape, or make the referencing item `@internal` too). |
-| `sveld/types-inline-unresolved` | `warning` | The import is kept as-is. Point it at a relative `.ts` file that exports a `type`/`interface`, or rename the colliding type. |
-| `sveld/cross-file-unresolved` | `warning` | Only recorded by [`finalizeWithoutCrossFileResolution`](#browser) on a standalone parse: an imported `setContext` key, prop default, or dispatch helper needs the imported file read. Run `sveld` through the CLI or `generateBundle` to resolve it, or inline the value in the component. |
-| `sveld/export-ambiguous` | `warning` | Two `export *` statements in the entry barrel bring in the same name from different modules, so (as in ES modules) the barrel doesn't export it and the [entry exports](#documenting-entry-exports) leave it out. Export it explicitly from the barrel (`export { format } from "./a.js"`) to pick one. Reported with the barrel file (e.g. `./index.js`) as its `component`, and only when `documentExports` is on. |
-
-#### Severity and `--strict=errors`
-
-Each diagnostic's `severity` is `"error"` (`example-compile-error`, `example-syntax-error`, `syntax-skipped`, `extend-props-target-missing`, `internal-typedef-referenced` — sveld emitted broken or unmodeled output) or `"warning"` (`prop-unknown-type`, `context-any-type`, `slot-missing-type`, `event-no-source`, `dispatch-escapes`, `rest-props-unresolved`, `context-duplicate-key`, `context-key-unresolved`, `context-value-unresolved`, `spread-unresolved`, `export-unresolved`, `module-export-conflict`, `extend-props-duplicate`, `extend-props-override`, `jsdoc-unknown-tag`, `typedef-duplicate`, `property-duplicate`, `generics-conflict`, `event-description-ambiguous`, `jsdoc-tag-dropped`, `types-inline-unresolved`, `cross-file-unresolved`, `export-ambiguous` — a type fell back to `any`, or something was left out of the docs). Plain `strict: true` / `--strict` fails on both, unchanged from before. Pass `strict: "errors"` (or `--strict=errors`) to fail CI only on `error`-severity diagnostics, letting `any`-fallback warnings through:
-
-```sh
-npx sveld --json --strict=errors
-```
-
-```ts
-await sveld({ json: true, strict: "errors" });
-```
-
-#### Ignoring diagnostics
-
-Two ways to suppress a diagnostic without disabling `strict` for the whole run. Either way, the diagnostic still appears in `SveldResult.diagnostics` (with `ignored: true`) and is still counted in the text summary (`sveld: 2 diagnostics (0 errors, 2 warnings) (1 ignored).`), but never fails `--strict` / `--strict=errors`.
-
-**Config matchers** (`diagnostics.ignore`, an array of `{ code?, component?, name? }`): every field you set on a matcher must match for it to apply; an omitted field matches anything. `component` is a glob (`*` within a path segment, `**` across segments):
-
-```ts
-// sveld.config.js
-export default defineConfig({
-  diagnostics: {
-    ignore: [
-      // Every prop-unknown-type diagnostic under legacy/.
-      { code: "sveld/prop-unknown-type", component: "./legacy/**" },
-      // One named symbol, anywhere.
-      { name: "internalOnly" },
-    ],
-  },
-});
+npx sveld --check    # exit 3 on a breaking API change against the snapshot
+npx sveld --strict   # exit 4 when a prop fell back to `any`, a tag was dropped, ...
 ```
 
-**Inline `@sveld-ignore <code>`**, on the same JSDoc comment as the prop, `@event` tag, context variable, or event dispatcher it applies to:
-
-```svelte
-<script>
-  /**
-   * @sveld-ignore sveld/prop-unknown-type
-   */
-  export let value;
-</script>
 ```
+sveld --check: 2 API changes detected against "COMPONENT_API.json".
+Suggested semver bump: major.
 
-```svelte
-<script>
-  /**
-   * @event {CustomEvent<null>} legacyEvent
-   * @sveld-ignore sveld/event-no-source
-   */
-  export let label;
-</script>
+  Button
+    [BREAKING] prop "target" added (required)
+    [BREAKING] prop "href" removed
 ```
 
-A bare `@sveld-ignore` (no code) suppresses every diagnostic for that symbol.
+See [CI](docs/ci.md) for exit codes, the change classification table, diagnostic codes, and how to ignore a diagnostic.
+
+## JSDoc tags
+
+| Tag | Use it to | Example |
+| :- | :- | :- |
+| [`@type`](docs/jsdoc-tags.md#type) | Type a prop | `@type {"sm" \| "md" \| "lg"}` |
+| [`@default`](docs/jsdoc-tags.md#default) | Override the inferred default shown in docs | `@default () => true` |
+| [`@typedef`](docs/jsdoc-tags.md#typedef) | Declare a shared, exported type | `@typedef {{ id: string }} Item` |
+| [`@property`](docs/jsdoc-tags.md#property) | Document a field of a `@typedef {object}` or event detail | `@property {string} [label] - Label text` |
+| [`@callback`](docs/jsdoc-tags.md#callback) | Declare a function type | `@callback OnChange` + `@param`/`@returns` |
+| [`@slot` / `@snippet`](docs/jsdoc-tags.md#slot--snippet) | Type slot or snippet props | `@slot {{ item: Item }} row` |
+| [`@event`](docs/jsdoc-tags.md#event) | Type a dispatched event's detail | `@event {{ id: string }} save` |
+| [`@param` / `@returns`](docs/jsdoc-tags.md#accessor-props) | Type an exported function | `@param {string} id` |
+| [`@restProps`](docs/jsdoc-tags.md#restprops) | Name the element rest props are spread onto | `@restProps {button \| a}` |
+| [`@extendProps`](docs/jsdoc-tags.md#extendprops) | Extend another component's props | `@extendProps {"./Button.svelte"} ButtonProps` |
+| [`@template` / `@generics`](docs/jsdoc-tags.md#template--generics) | Declare generics in a JS component | `@template {Item} [T=Item]` |
+| [`@bindable`](docs/jsdoc-tags.md#bindable) | Document a prop's `bind:` contract | `@bindable writable` |
+| [`@deprecated`](docs/jsdoc-tags.md#deprecated) | Mark a prop, event, slot, or export deprecated | `@deprecated Use "size" instead.` |
+| [`@ignore` / `@internal`](docs/jsdoc-tags.md#ignore--internal) | Hide from every output | `@internal` |
+| [`@since` / `@see` / `@example`](docs/jsdoc-tags.md#since-see-example) | Pass structured tags through to all outputs | `@since 1.2.0` |
+| [`{@link}`](docs/jsdoc-tags.md#link) | Link in a description | `{@link https://example.com\|docs}` |
+| [`@csspart` / `@cssprop`](docs/jsdoc-tags.md#csspart--cssprop) | Document shadow-DOM styling hooks | `@cssprop {Color} [--bg=white]` |
+| [`@sveld-ignore`](docs/ci.md#ignoring-diagnostics) | Suppress a diagnostic | `@sveld-ignore sveld/prop-unknown-type` |
+| [`<!-- @component -->`](docs/jsdoc-tags.md#component-comments) | Document the component itself | `<!-- @component Renders a button. -->` |
+
+Context types come from `setContext` calls with no tag needed. See [Context](docs/jsdoc-tags.md#context).
+
+## Docs
+
+- [Options](docs/options.md): every option and CLI flag, the config file, the Vite plugin, `sveld()` and its result, and `sveld/browser`.
+- [JSDoc tags](docs/jsdoc-tags.md): how types are inferred and every tag sveld reads.
+- [Output](docs/output.md): `.d.ts` formats, JSON output and schema, Markdown, entry exports, custom element metadata, and custom output formats.
+- [CI](docs/ci.md): exit codes, `--check` for API drift, `--strict` and diagnostic codes, and `@example` checking.
+- [Troubleshooting](docs/troubleshooting.md)
+
+Try sveld in the browser at [sveld.onrender.com](https://sveld.onrender.com) (source in [`playground/`](playground)).
 
 ## Requirements
 
-- Node 22+ if your config is `sveld.config.js` or `sveld.config.mjs` — `sveld` declares no `engines.node` floor. A `sveld.config.ts` file loads via a raw `import()`, with no transpile step, so it only works if the runtime strips TypeScript itself: on Node this needs unflagged type stripping (Node 22.18 / 23.6+; on older Node 22 patches it's behind `--experimental-strip-types`, so use a `.js`/`.mjs` config instead), which is why Node 24 — the first current major where type stripping is always on — is the only reason to require it. Bun (see `.bun-version`) loads `.ts` configs without Node at all. CI runs on Bun and does not pin a Node version; the release workflow pins Node 24 for `actions/setup-node` on the npm publish job only, not a requirement for consumers.
-- `sveld` is ESM-only. `require("sveld")` does not work — use `import` or dynamic `import()`.
-- The [persistent parse cache](#persistent-parse-cache-cache) hashes source with `node:crypto`'s one-shot `hash()`, which needs Node 22 (or Bun).
-- `sveld` bundles its own template parser to parse `.svelte` files, kept in parity with `svelte/compiler` (see [Approach](#approach)). 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.
-- [`resolveTypes`](#opt-in-semantic-resolution-resolvetypes), [`checkExamples`](#compile-checked-example-blocks-checkexamples), and [`typesOptions.inline: "all"`](#typesoptionsinline) are optional and need `typescript` 7 or later (which provides `typescript/unstable/async`) plus a `tsconfig.json`. Everything else, including `.d.ts` generation and `typesOptions.inline: "local"`, is AST-only and never loads TypeScript. If any of the three is enabled and TypeScript can't be started (missing, too old, or no `tsconfig.json`), the run fails loudly: `sveld()` throws and the CLI exits `2` naming the requirement, rather than silently skipping the check. For `typesOptions.inline: "all"` this only actually triggers when there's a non-allow-listed bare import somewhere in the bundle to resolve; see [`typesOptions.inline`](#typesoptionsinline).
-
-## Usage
-
-### Installation
-
-Install `sveld` as a development dependency.
-
-```sh
-# npm
-npm i -D sveld
-
-# pnpm
-pnpm i -D sveld
-
-# Bun
-bun i -D sveld
-
-# Yarn
-yarn add -D sveld
-```
-
-### Vite
-
-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
-import { svelte } from "@sveltejs/vite-plugin-svelte";
-import sveld from "sveld";
-import { defineConfig } from "vite";
-
-export default defineConfig({
-  plugins: [svelte(), sveld()],
-});
-```
-
-Since Vite uses Rollup for production builds, the same plugin works in Rollup configs.
-
-Unlike the CLI and the programmatic `sveld()` API, the plugin ignores `sveld.config.*` by default: pass `config: true` to load it and merge it with the options given here (these take precedence over the same key in the file), or a string to point at a specific config file.
-
-```ts
-sveld({
-  config: true,
-  json: true, // wins over `json` set in sveld.config.*
-});
-```
-
-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({
-  entry: "src/index.js",
-});
-```
-
-When building the library, TypeScript definitions are emitted to the `types` folder by default.
-
-Customize the output folder using the `typesOptions.outDir` option.
-
-The following example emits the output to the `dist` folder:
-
-```diff
-sveld({
-+  typesOptions: {
-+    outDir: 'dist',
-+  }
-})
-```
-
-### CLI
-
-The CLI uses the `"svelte"` field from your `package.json` as the entry point:
-
-```sh
-npx sveld
-```
-
-Generate documentation in JSON and/or Markdown formats using the following flags:
-
-```sh
-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`, `--custom-elements`, `--llms`, `--fail-fast`, `--dry-run`, `--cache`, `--resolve-types`, `--check-examples`, `--report-diagnostics`, `--strict`, `--check`, `--check-level`, `--types-format`, `--types-export`, `--types-comments`, `--types-inline`, `--types-index-types`, `--types-props-declaration`, `--quiet`, `--stdout`, `--format`. The camelCase spellings `--resolveTypes` and `--checkExamples` still work as deprecated aliases for compatibility with existing scripts. `--entry`, `--cache`, `--check`, `--types-format`, `--types-export`, `--types-comments`, `--types-inline`, and `--types-props-declaration` take their value either as `--flag=value` or as a separate `--flag value` argument (`sveld --entry src/index.js` and `sveld --entry=src/index.js` are equivalent); if the next argument starts with `--` it's not consumed as a value, so `--cache` and `--check` fall back to their default location and the rest of that list report a usage error naming the flag. Boolean flags (`--json`, `--glob`, `--strict`, `--types-index-types`, and the like) never consume a following argument. An unrecognized flag (e.g. `--markdwon`) prints `sveld: unknown flag "--markdwon".` to `stderr`, exits `1`, and skips generation; when a close match exists it appends a suggestion, e.g. `Did you mean "--markdown"?`. sveld takes no positional arguments, so any non-flag argument errors the same way.
-
-Writer progress lines (`created "..."` / `unchanged "..."`) print to `stderr`, keeping `stdout` reserved for machine-readable data. Pass `--quiet` (or `quiet: true` in `sveld.config.*`) to suppress them; it does not suppress error messages, the diagnostics summary (`--report-diagnostics` / `--strict`), or the `--check` report.
-
-Pass `--dry-run` to resolve the entry, load config, and parse components through the real pipeline (so parse errors, diagnostics, `--strict`, and `--check` all behave as in a real run), then print `would write "<path>"` to `stdout` for each output file instead of writing it, e.g. `sveld --json --markdown --dry-run`. Nothing is written, including the parse cache. `--check` never writes regardless of `--dry-run`, since it only diffs against the committed snapshot.
-
-Pass `--stdout` alongside exactly one of `--json`, `--markdown`, or `--custom-elements` to print that single document to `stdout` instead of writing it to disk, e.g. `sveld --json --stdout | jq '.components[].moduleName'`. Zero or more than one of those three flags, `--types`, or `--check` combined with `--stdout` is a usage error that prints to `stderr` and exits `1` without generating anything; the default `.d.ts` generation is skipped in `--stdout` mode since type definitions span multiple files.
-
-`--stdout=ndjson` (only valid with `--json`) prints one minified JSON object per exported component per line instead of the single combined document, in the same order as the combined document's `components` array, e.g. `sveld --json --stdout=ndjson | jq -c 'select(.props | length > 0)'`. Lines are only written after the run completes (component records are only final after cross-component resolution), so this is a line-oriented serialization format, not incremental streaming. Bare `--stdout` (or `--stdout=json`) keeps the single-document behavior; any other value is a usage error.
-
-`--format=json` switches the `--check` report and the `--report-diagnostics` / `--strict` diagnostics summary from prose to JSON, so scripts and agents don't have to regex the text output, e.g. `sveld --json --check --format=json | jq '.bump'`. Channels are unchanged: the check report prints to `stdout` and the diagnostics summary to `stderr`, same as the text format. Each envelope (`{ kind: "check-report", schemaVersion: 1, ... }` / `{ kind: "diagnostics", schemaVersion: 1, diagnostics: [...] }`) carries its own `schemaVersion`, bumped independently of `COMPONENT_API.json`'s if either shape ever changes incompatibly. The default remains `--format=text`; an unrecognized value (e.g. `--format=yaml`) is a usage error that prints to `stderr` and exits `1` without generating anything.
-
-`--format=github` prints [GitHub Actions workflow commands](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions) instead: `::warning`/`::error` for each diagnostic (by `severity`) and `::error` for each `--check` change that meets `--check-level` (`major` by default), annotating the offending line directly in the PR's "Files changed" tab. Ignored diagnostics and changes below `--check-level` produce no annotation. When the `GITHUB_STEP_SUMMARY` env var is set (GitHub Actions sets it automatically), sveld also appends a Markdown table mirroring the same rows to that file, so the job summary shows them even for someone not reviewing the diff. A minimal workflow step:
-
-```yaml
-- run: npx sveld --json --check --report-diagnostics --strict=errors --format=github
-```
-
-Run `npx sveld --help` for the full flag list with descriptions, or `npx sveld --version` to print the installed version.
-
-Pass `--glob` with a directory as `--entry` (no barrel file) to document every `.svelte` file under it directly, with no re-export needed: each component's sanitized filename becomes its module name in JSON, Markdown, and the generated `index.d.ts`, in addition to the per-component `.d.ts` every `--glob` run already produces. This is the same set `mergeGlobbedComponents` discovers when `--glob` is combined with a file entry; a directory entry just has no barrel to layer it onto.
-
-### Exit codes
-
-| Code | Meaning |
-|------|---------|
-| `0` | Success |
-| `1` | Usage or configuration error (unknown flag, bad flag value, unresolvable entry, unresolved re-export or path alias) |
-| `2` | Generation failure (a component failed to parse under `--fail-fast`, or an unrecoverable pipeline error) |
-| `3` | Breaking API change detected by `--check` |
-| `4` | Diagnostics present under `--strict` |
-
-Every failure is still reported to its usual channel even when more than one applies in a single run (e.g. a breaking change under `--check` alongside diagnostics under `--strict`); the process exits with the lowest applicable code. All failure codes are nonzero, so existing `if sveld; then ...` and `set -e` scripts that only check for success keep working unmodified.
-
-### 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 `3` when it finds a breaking change.
-
-1. Generate and commit the snapshot once: `npx sveld --json`, then commit `COMPONENT_API.json`.
-2. Add `npx sveld --check` to CI:
-
-```sh
-npx sveld --check
-```
-
-```
-sveld --check: 2 API changes detected against "COMPONENT_API.json".
-Suggested semver bump: major.
-
-  Button
-    [BREAKING] prop "target" added (required)
-    [BREAKING] prop "href" removed
-```
-
-| Change | Bump |
-| --- | --- |
-| Component added | `minor` |
-| Component removed | `major` |
-| Prop/export added (optional) | `minor` |
-| Prop/export added (required) | `major` |
-| Prop/export removed | `major` |
-| Prop/export became required | `major` |
-| Prop/export became optional | `minor` |
-| Prop/export type widened (union gained a member) | `minor` |
-| Prop/export type narrowed (union lost a member) | `major` |
-| Prop/export type changed (anything else) | `major` |
-| Function-typed prop/export gained a trailing optional param | `minor` |
-| Function-typed prop/export lost a param, or return type changed | `major` |
-| Prop gained a writable binding (`bind:`-able) | `minor` |
-| Prop lost a writable binding | `major` |
-| Prop/export default value changed (type unchanged) | `patch` |
-| `@deprecated` added | `minor` |
-| `@deprecated` removed | `patch` |
-| `constant`/`reactive` flag flipped | `minor` |
-| Event/slot added | `minor` |
-| Event/slot removed | `major` |
-| Event detail / slot props type widened | `minor` |
-| Event detail / slot props type narrowed or otherwise changed | `major` |
-| `generics`, `@restProps`, `@extends`, or context shape changed | `major` (not classified further) |
-| Description-only change | not reported |
-
-`--check` does not write the snapshot. Run `sveld --json` (or `sveld --json --check`) and commit the file when you want to update it. If there is no snapshot yet, `--check` prints a notice and exits `0`.
-
-Use `--check=<path>` to diff against a snapshot at a custom location (defaults to `jsonOptions.outFile`, or `COMPONENT_API.json`).
-
-By default `--check` only fails the run (exit `3`) on a `major` bump; `minor` and `patch` changes are still reported but don't fail CI. Pass `--check-level=minor` or `--check-level=patch` to fail the run at a lower threshold, e.g. to gate a package that promises no additive changes without a minor release.
-
-If the committed snapshot's `schemaVersion` doesn't match the version `sveld` currently emits, `--check` reports a `kind: "schema"` entry instead of diffing (a version mismatch isn't a semver bump) and exits `1` (usage error): regenerate the snapshot with `sveld --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. See [Exit codes](#exit-codes) for how these are differentiated.
-
-Pass `--format=json` for a machine-readable report on `stdout` instead of the prose above, e.g. `sveld --check --format=json | jq '.bump'` or `sveld --check --format=json | jq '.changes[] | select(.bump == "major")'`.
-
-### CI: strictness profiles (`--strict=ci`/`--strict=local`)
-
-CI and local runs usually want a different bundle of `strict`, `reportDiagnostics`, `check`, and `checkExamples` flags, previously assembled by hand. `--strict=ci`/`strict: "ci"` and `--strict=local`/`strict: "local"` are shorthands for two common bundles. Bare `--strict`/`strict: true` (and `--strict=errors`) are unchanged.
-
-`--strict=ci` expands to `{ strict: true, reportDiagnostics: true, check: true, checkExamples: true }` — the full gate for a CI job:
-
-```sh
-npx sveld --json --strict=ci
-```
-
-`--strict=local` expands to `{ reportDiagnostics: true }` — diagnostics printed for a developer to see, without failing the command or requiring a committed `COMPONENT_API.json` snapshot:
-
-```sh
-npx sveld --json --strict=local
-```
-
-The profile's keys are applied first, then any other key set alongside `strict` overrides it, so you can opt back out of one piece:
-
-```ts
-// Everything --strict=ci implies, except the TypeScript-checked half of checkExamples.
-await sveld({ json: true, strict: "ci", checkExamples: "syntax" });
-```
-
-### Node.js
-
-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).
-
-> `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" };
-
-const { diagnostics } = await sveld({
-  entry: "./src/index.js",
-  glob: true,
-  markdown: true,
-  markdownOptions: {
-    onAppend: (type, document, components) => {
-      if (type === "h1")
-        document.append(
-          "quote",
-          `${components.size} components exported from ${pkg.name}@${pkg.version}.`,
-        );
-    },
-  },
-  json: true,
-  jsonOptions: {
-    outFile: "docs/src/COMPONENT_API.json",
-  },
-});
-```
-
-`diagnostics` is always populated; printing is opt-in via `reportDiagnostics` or `strict` (see [Type inference diagnostics](#type-inference-diagnostics)). `errors` is always populated too: components that failed to parse, whether or not `failFast` is set.
-
-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()` never touches `process.exitCode` itself; it returns a suggested `exitCode` (`0`, `3` for a breaking `check` result, or `4` for `strict` diagnostics — the same mapping the CLI uses, `3` winning over `4`) so you can assign it yourself:
-
-```js
-import { formatCheckReport } from "sveld";
-
-const { check, exitCode } = await sveld({ json: true, check: true });
-
-if (check) {
-  console.log(formatCheckReport(check));
-}
-
-process.exitCode = exitCode;
-```
-
-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.
-
-Use the `jsonOptions.outDir` option to specify the folder for individual JSON files to be emitted.
-
-```js
-sveld({
-  json: true,
-  jsonOptions: {
-    // an individual JSON file will be generated for each component API
-    // e.g. "docs/Button.api.json"
-    outDir: "docs",
-  },
-});
-```
-
-#### `jsonOptions.source`
-
-Every prop, slot, event, typedef, and context in `COMPONENT_API.json` carries a `source` position range (plus `componentCommentSource` on the component itself) when the parser has a stable AST position for it. For a large component library this is a substantial share of the file — roughly a quarter of `COMPONENT_API.json` for a 150+ component library — and many consumers (docs sites, LLM context) never read it.
-
-Set `jsonOptions.source` to `false` to omit every `source`/`componentCommentSource` range and shrink the file:
-
-```js
-sveld({
-  json: true,
-  jsonOptions: {
-    source: false,
-  },
-});
-```
-
-`source: true` is the default; every other field is unaffected. `EntryExport.source` (the declaring module's relative path, from `documentExports`) is a different field with a string value and is never stripped.
-
-### Browser
-
-`sveld/browser` is a Node-free subpath export for running `sveld` client-side — e.g. an in-browser Svelte playground or REPL that parses whatever `.svelte` source the user typed and renders docs for it live. It bundles with Vite, esbuild, webpack, or Rollup without a `node:fs`/`node:path` polyfill.
-
-It covers parsing one component's source and rendering that result to any output format `sveld` supports (JSON, Markdown, `.d.ts`, Custom Elements Manifest). It does not cover project-wide glob scanning, the config file, or the CLI/Vite plugin (`sveld()`/`pluginSveld()`) — those walk the filesystem and only make sense in Node. Use the main `sveld` entry point for those.
-
-```ts
-import {
-  asNormalizedPath,
-  ComponentParser,
-  finalizeWithoutCrossFileResolution,
-  buildComponentApiDocument,
-  writeMarkdownCore,
-  writeTsDefinition,
-  buildCustomElementsManifest,
-} from "sveld/browser";
-
-const parser = new ComponentParser();
-const moduleName = "Button";
-const filePath = "Button.svelte";
-const parsed = finalizeWithoutCrossFileResolution(
-  parser.parseSvelteComponent(source, { moduleName, filePath }),
-  { filePath },
-);
-
-// `parseSvelteComponent` returns component metadata only; add `moduleName`
-// and `filePath` yourself to match the `ComponentDocApi` shape the writers expect.
-const component = { ...parsed, moduleName, filePath: asNormalizedPath(filePath) };
-const components = new Map([[moduleName, component]]);
-
-// JSON
-const jsonDoc = buildComponentApiDocument(components);
-
-// Markdown
-const markdown = writeMarkdownCore(components);
-
-// TypeScript definitions (per component)
-const dts = writeTsDefinition(jsonDoc.components[0]);
-
-// Custom Elements Manifest
-const cem = buildCustomElementsManifest(components, {
-  resolveModulePath: (component) => component.filePath,
-});
-```
-
-A standalone parse can't read the files a component imports from, so some output the CLI and `generateBundle` produce is missing: a context whose `setContext` key is imported, the value of a prop default that names an imported `const`, the return type of a default that calls an imported function, and events dispatched by an imported helper (`wire(dispatch)`). `parseSvelteComponent` leaves these pending for the cross-file pass, which never runs here. Pass the result through `finalizeWithoutCrossFileResolution(parsed, { filePath })` to record a `sveld/cross-file-unresolved` warning for each one, naming the import (e.g. `` setContext key `keys.THEME` is imported from "./keys.js" ``), and to release the `sveld/event-no-source` warnings held back while a helper's events were unknown. It returns a new component and leaves the input unchanged.
-
-`ComponentParser` is stateful but reusable across parses — call `parseSvelteComponent` again on the same instance for the next component instead of constructing a new one each time.
-
-See [`playground/`](playground) in this repo for a working example: it parses Svelte source typed into an editor and renders JSON, Markdown, TypeScript, and Custom Elements Manifest tabs, all client-side. Deployed at [sveld.onrender.com](https://sveld.onrender.com).
-
-### Config File
-
-Put a `sveld.config.js`, `sveld.config.mjs`, or `sveld.config.ts` at your project root to set defaults for the CLI and the programmatic `sveld()` API. The Vite/Rollup plugin ignores it unless you opt in with the [`config`](#vite) option.
-
-Import `defineConfig` from `sveld` for typed options. Config files must use ESM syntax (`export default`).
-
-```js
-// sveld.config.js
-import { defineConfig } from "sveld";
-
-export default defineConfig({
-  glob: true,
-  json: true,
-  markdown: true,
-});
-```
-
-Later sources win when options overlap:
-
-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",
-};
-```
-
-Merging is one level deep for object-valued options (`typesOptions`, `jsonOptions`, `markdownOptions`, `customElementsOptions`, `additionalWriters`): setting one nested key at the CLI or in `sveld()` doesn't drop sibling keys set in the config file. Arrays and functions (e.g. `markdownOptions.onAppend`) are replaced outright, never merged.
-
-```js
-// sveld.config.js
-export default {
-  typesOptions: { outDir: "dist", preamble: "// license" },
-};
-```
-
-`npx sveld --types-format=component` keeps `outDir` and `preamble` from the file and adds `format: "component"`, rather than replacing `typesOptions` entirely.
-
-An unrecognized option key (top-level, or inside a `*Options` object) is not an error: it prints a `console.warn` naming the key, with a "did you mean" suggestion when a known key is close enough.
-
-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. 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",
-  "files": [
-    "src",
-    "lib",
-+   "types",
-  ]
-}
-```
-
-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 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.
-  - **`outDir`** (string, optional, default: `"types"`): Output directory for generated `.d.ts` files, relative to the project root.
-  - **`preamble`** (string, optional, default: `""`): Raw text prepended to the top of the generated `index.d.ts` barrel file, before the `export * from "./..."` lines. Useful for license headers or lint-disable comments. See [`typesOptions.preamble`](#typesoptionspreamble) below.
-  - **`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).
-  - **`exportTypes`** (`boolean | { props?, exports?, typedefs?, contexts? }`, optional, default: `true`): Which generated type declarations get an `export` keyword. `false` keeps them all local to the `.d.ts` file; an object picks per kind. Also available as `--types-export=<all|none>` (the CLI can only set the boolean form, not the per-kind object). See [`typesOptions.exportTypes`](#typesoptionsexporttypes).
-  - **`typeNames`** (`{ props?: string; exports?: string }`, optional, default: `{ props: "{name}Props", exports: "{name}Exports" }`): Templates for generated type names. No CLI flag; config file or `sveld()` only. See [`typesOptions.typeNames`](#typesoptionstypenames).
-  - **`comments`** (`"all" | "descriptions" | "none"`, optional, default: `"all"`): How much JSDoc lands in the generated `.d.ts`. `"all"` keeps descriptions, `@deprecated`, `@default`, and passthrough tags (`@since`, `@see`, `@example`, `@link`); `"descriptions"` keeps descriptions and `@deprecated` only; `"none"` emits no comments at all. Also available as `--types-comments=<all|descriptions|none>`. See [`typesOptions.comments`](#typesoptionscomments).
-  - **`propsDeclaration`** (`"type" | "interface"`, optional, default: `"type"`): `"interface"` emits the props type as an `interface` instead of a `type` alias when the props are a plain object. Also available as `--types-props-declaration=<type|interface>`. See [`typesOptions.propsDeclaration`](#typesoptionspropsdeclaration).
-  - **`transform`** (function, optional): Post-processes each generated file's text before it is written. Runs after the generated-text cache, so it applies on every run. No CLI flag; config file or `sveld()` only. See [`typesOptions.transform`](#typesoptionstransform).
-  - **`indexTypes`** (`boolean | { props?, exports?, typedefs?, contexts? }`, optional, default: `false`): Also re-export generated types from `index.d.ts`. `true` re-exports each component's `Props` type (and `Exports` under `format: "component"`); an object can additionally include typedefs and contexts. Also available as `--types-index-types` (the CLI can only set the boolean form, not the per-kind object). See [`typesOptions.indexTypes`](#typesoptionsindextypes).
-  - **`inline`** (`false | "local" | "all"`, optional, default: `false`): Copies `type`/`interface` declarations imported from a relative source (or a tsconfig/jsconfig path alias) directly into the `.d.ts`, dropping the import. Also available as `--types-inline=<local|all>` (`--types-inline=false` resets to the default). See [`typesOptions.inline`](#typesoptionsinline).
-- **`json`** (boolean, optional): Generate component documentation in JSON format.
-- **`jsonOptions`** (object, optional): Options for JSON output.
-  - **`outFile`** (string, optional, default: `"COMPONENT_API.json"`): Path (relative to the project root) for the single combined JSON document. Ignored when `outDir` is set.
-  - **`outDir`** (string, optional): Emit one JSON file per component (`<ComponentName>.api.json`) into this directory instead of a single combined file. See [`jsonOptions.outDir`](#jsonoptionsoutdir).
-  - **`source`** (boolean, optional, default: `true`): Set to `false` to omit every `source`/`componentCommentSource` position range from the output. See [`jsonOptions.source`](#jsonoptionssource).
-- **`markdown`** (boolean, optional): Generate component documentation in Markdown format.
-- **`markdownOptions`** (object, optional): Options for Markdown output.
-  - **`outFile`** (string, optional, default: `"COMPONENT_INDEX.md"`): Path (relative to the project root) for the single combined Markdown document. Ignored when `outDir` is set.
-  - **`outDir`** (string, optional): Emit one `<ModuleName>.md` file per component into this directory, plus an index `README.md` linking to each, instead of a single combined file. See [`markdownOptions.outDir`](#markdownoptionsoutdir).
-  - **`write`** (boolean, optional, default: `true`): Set to `false` to skip writing to disk — the rendered combined document is still returned, or (with `outDir` set) no files are written at all.
-  - **`onAppend`** (function, optional): Callback invoked every time a heading, quote, paragraph, divider, or raw block is appended to the document. Lets you inject extra content, e.g. a summary line under the title. See [`markdownOptions.onAppend`](#markdownoptionsonappend) below.
-- **`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.
-  - **`outFile`** (string, optional, default: `"custom-elements.json"`): Path (relative to the project root) for the generated manifest file.
-- **`llms`** (boolean, optional): Generate an [`llms.txt` / `llms-full.txt`](#llmstxt-output) pair. Also available as the `--llms` CLI flag.
-- **`llmsOptions`** (object, optional): Options for `llms.txt` / `llms-full.txt` output.
-  - **`outDir`** (string, optional): Directory (relative to the project root) both files are written into. Defaults to the project root.
-  - **`linkBase`** (string, optional, default: `""`): Prefixed to each component's link in `llms.txt`.
-  - **`title`** (string, optional, default: the `"name"` field from `package.json`): The `# <title>` heading both files start with.
-  - **`summary`** (string, optional, default: the `"description"` field from `package.json`): The `> <summary>` blockquote under the title.
-- **`config`** (boolean | string, optional, default: `false`): Load `sveld.config.{js,mjs,ts}` and merge it with these options; these options win when a key is set in both. `true` resolves the config from the Vite project root (or `process.cwd()` outside Vite); a string is an explicit path to the config file. The plugin warns about keys only the CLI and `sveld()` act on (`reportDiagnostics`, `strict`, `check`, `checkLevel`, `stdout`, `format`, `dryRun`). See [Config File](#config-file).
-- **`watch`** (boolean, optional, default: `false`): Regenerate output incrementally when relevant source changes during `vite dev` / `vite build --watch`. A reparse is triggered by: editing a component; editing the entry barrel itself, which adds/removes the corresponding component; or editing a non-`.svelte` file a component depends on via [`@extendProps`](#extendprops) / `@extends` or a typedef `import("./x")` reference. Only the affected components are re-parsed, rather than rebuilding every component. Overlapping regenerations are queued, never run concurrently. 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. 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 | "syntax"`, optional, default: `false`): `true` runs plain TS/JS `@example` blocks through the TypeScript program (`example-compile-error` diagnostics) and `svelte`/`html` blocks through sveld's own template parser (`example-syntax-error` diagnostics). `"syntax"` runs only the markup path, so `typescript` is never loaded. Also available as `--check-examples` / `--check-examples=syntax` (`--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 | "errors" | "ci" | "local"`, optional, default: `false`): Exit with code `4` when diagnostics exist. Implies `reportDiagnostics`. `"errors"` fails only on `severity: "error"` diagnostics, letting `warning` ones through. `"ci"` and `"local"` are strictness profiles that expand into other options before this object's own keys are applied. Also available as `--strict` / `--strict=errors` / `--strict=ci` / `--strict=local`. See [Type inference diagnostics](#type-inference-diagnostics) and [CI: strictness profiles](#ci-strictness-profiles---strictci---strictlocal).
-- **`diagnostics.ignore`** (`Array<{ code?: string; component?: string; name?: string }>`, optional): Marks matching diagnostics `ignored` — they're still reported and counted, but never fail `strict`. `component` is a glob; an omitted field on a matcher matches anything. No CLI flag; config-file or `sveld()` only. See [Ignoring diagnostics](#ignoring-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 `3` 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).
-- **`checkLevel`** (`"major" | "minor" | "patch"`, optional, default: `"major"`): Minimum bump `--check` fails the CLI run on. Also available as `--check-level`. See [CI: API-drift checks (`--check`)](#ci-api-drift-checks---check).
-- **`quiet`** (boolean, optional, default: `false`): Suppress writer progress logs (`created "..."` / `unchanged "..."`), which print to `stderr` by default. Does not suppress error messages, the diagnostics summary, or the `--check` report. Also available as `--quiet`.
-- **`dryRun`** (boolean, optional, default: `false`): Resolve the entry, load config, and parse components through the real pipeline, then print `would write "<path>"` to `stdout` for each output file instead of writing it, including the parse cache. Diagnostics, `strict`, and `check` behave as in a real run. CLI-only via `--dry-run`; the Vite plugin does not expose this option.
-
-By default, only TypeScript definitions are generated.
-
-To generate documentation in Markdown and JSON formats, set `markdown` and `json` to `true`.
-
-```diff
-sveld({
-+  markdown: true,
-+  json: true,
-})
-```
-
-#### `typesOptions.preamble`
-
-Use `typesOptions.preamble` to prepend raw text to the generated `types/index.d.ts` barrel file — for example, a license header that should ship with every published `.d.ts` file.
-
-```js
-sveld({
-  types: true,
-  typesOptions: {
-    preamble: "// Copyright (c) 2026 Acme Inc. All rights reserved.\n\n",
-  },
-});
-```
-
-```ts
-// types/index.d.ts
-// Copyright (c) 2026 Acme Inc. All rights reserved.
-
-export { default as Button } from "./Button.svelte";
-```
-
-`preamble` only affects the barrel file (`index.d.ts`); per-component `.d.ts` files are untouched.
-
-#### `typesOptions.exportTypes`
-
-Every type sveld generates is `export`ed by default. `typesOptions.exportTypes` lets a library keep some or all of them local to each component's `.d.ts` — useful when the props type is an implementation detail, or when it collides with a hand-written type of the same name in the package's own `index.d.ts`. Only the component itself needs to be public either way.
-
-```js
-sveld({
-  types: true,
-  typesOptions: {
-    exportTypes: false,
-  },
-});
-```
-
-**Button.svelte.d.ts** before:
-
-```ts
-export type ButtonProps = { label?: string };
-
-export default class Button extends SvelteComponentTyped<
-  ButtonProps,
-  { click: WindowEventMap["click"] },
-  { default: Record<string, never> }
-> {}
-```
-
-**Button.svelte.d.ts** after (`exportTypes: false`):
-
-```ts
-type ButtonProps = { label?: string };
-
-export default class Button extends SvelteComponentTyped<
-  ButtonProps,
-  { click: WindowEventMap["click"] },
-  { default: Record<string, never> }
-> {}
-```
-
-`Button` is still the only thing a consumer imports; `ButtonProps` is just no longer part of the public surface (it can still be referenced structurally — through `ComponentProps<typeof Button>`, for instance).
-
-Pass an object instead of a boolean to pick per kind:
-
-```js
-typesOptions: {
-  exportTypes: {
-    props: false,   // export type <Name>Props
-    exports: true,  // export type <Name>Exports (format: "component" only)
-    typedefs: true, // export interface|type <Typedef> from @typedef
-    contexts: true, // export type <Context> from setContext
-  },
-}
-```
-
-Any key left out defaults to `true`.
-
-`<script context="module">` exports (`export declare const` / `export declare function` / `export declare class`) are real runtime exports and are always emitted as exports, regardless of `exportTypes`. So are the types a module script exports (`export interface Item`, `export type Mode`, `export type { Local }`), since they're part of the component module's API.
-
-A module-script class (`export class Store {}`, or `class Store {}` then `export { Store }`) is emitted with its public surface: the constructor, methods (with their overload signatures, if any), fields, constructor parameter properties, getter/setter pairs, and `static`/`readonly`/`abstract`/optional modifiers. Types come from TypeScript annotations, then JSDoc (`@param`, `@returns`, `@type`, and `@template` on the class or a method), and are `any` otherwise. In a JS script, a `this.x = ...` assignment in the constructor declares property `x`. Private (`#x`, `private`), `protected`, computed-key, and `@internal` members are left out. `extends` and `implements` clauses are kept, and an imported base class or interface gets an `import type`. A class that extends something the `.d.ts` can't reference (a non-exported local class, or an expression like `mixin(Base)`) is declared without `extends`, with an `export-unresolved` warning, since its inherited members would be missing.
-
-```ts
-export declare class Store<T> {
-  constructor(initial: T);
-
-  value: T;
-
-  static create<U>(value: U): Store<U>;
-
-  subscribe(run: (value: T) => void): () => void;
-}
-```
-
-In JSON the class is a `moduleExports` entry with `kind: "class"`, `type: "typeof Store"`, and its members under `members`; the Markdown and `llms-full.txt` output list them in a members table after the Module exports table.
-
-One exception: when a bundled component uses [`@extendProps`](#extendprops) to extend another bundled component, sveld emits `import type { ButtonProps } from "./Button.svelte"` in the extending component's `.d.ts`. If `Button`'s props type stopped being exported, that import would break — so sveld always keeps a component's props type exported when another component in the same run extends it, even under `exportTypes: false`.
-
-Also available as `--types-export=<all|none>` on the CLI, mapped to the boolean form (`all` => `true`, `none` => `false`) — the CLI can't express the per-kind object form.
-
-#### `typesOptions.typeNames`
-
-By default, sveld names the generated props type `<Name>Props` and (for [`format: "component"`](#dts-output-format-typesoptionsformat)) the exports type `<Name>Exports`, where `<Name>` is the component's module name. `typesOptions.typeNames` lets a library follow its own naming convention instead, via a `{name}` placeholder template.
-
-```js
-sveld({
-  types: true,
-  typesOptions: {
-    typeNames: { props: "I{name}Props" },
-  },
-});
-```
-
-**Button.svelte.d.ts** before / after:
-
-```diff
-- export type ButtonProps = { label?: string };
-+ export type IButtonProps = { label?: string };
-
-- export default class Button extends SvelteComponentTyped<ButtonProps, ...> {}
-+ export default class Button extends SvelteComponentTyped<IButtonProps, ...> {}
-```
-
-Each template must contain `{name}` and produce a valid identifier once substituted, and the two must produce different names that aren't the component's own (`{name}`) or its generic-component interface's (`{name}Component`); sveld throws otherwise. Any key left out of the object keeps its default (`"{name}Props"` / `"{name}Exports"`).
-
-If a bundled component then [`@extendProps`](#extendprops)/`@extends`-es another one, the tag must name the *templated* interface — `@extendProps {"./Button.svelte"} IButtonProps`, not `ButtonProps` — or sveld reports [`extend-props-target-missing`](#type-inference-diagnostics).
-
-There's no CLI flag for `typeNames`; set it via a config file or the programmatic `sveld()` API.
-
-#### `typesOptions.comments`
-
-By default sveld carries every prop's JSDoc into the generated `.d.ts`: the description, `@deprecated`, `@default`, and passthrough tags like `@since`. `typesOptions.comments` lets a library ship a leaner `.d.ts` instead — useful when the docs live elsewhere (a docs site, Storybook) and duplicating them in the type declaration just adds noise.
-
-```svelte
-<script>
-  /**
-   * The button's visible label.
-   * @deprecated Use `text` instead.
-   * @default ""
-   * @since 1.2.0
-   */
-  export let label = "";
-</script>
-```
-
-**`comments: "all"`** (default) — description, `@deprecated`, `@default`, and passthrough tags:
-
-```ts
-/**
- * The button's visible label.
- * @deprecated Use `text` instead.
- * @default ""
- * @since 1.2.0
- */
-label?: string;
-```
-
-**`comments: "descriptions"`** — description and `@deprecated` only; `@default` and passthrough tags are dropped:
-
-```ts
-/**
- * The button's visible label.
- * @deprecated Use `text` instead.
- */
-label?: string;
-```
-
-`@deprecated` survives at this level on purpose: editors render a strikethrough from it, so it's API information a consumer needs, not documentation.
-
-**`comments: "none"`** — no comments at all; only the declaration:
-
-```ts
-label?: string;
-```
-
-```js
-sveld({
-  types: true,
-  typesOptions: {
-    comments: "descriptions",
-  },
-});
-```
-
-The same levels apply to the comments on slots, events, their snippet and `on<event>` callback props, `@restProps`, typedefs, contexts, module exports, and the component itself. A `@property` description inside a `@typedef` is part of the type's own text, so it stays at every level.
-
-`@internal`/`@ignore` members are removed from every output regardless of this option — see [`@ignore` / `@internal`](#ignore--internal). `comments` only controls how much JSDoc survives for members that *do* get emitted.
-
-Also available as `--types-comments=<all|descriptions|none>` on the CLI.
-
-#### `typesOptions.propsDeclaration`
-
-By default sveld emits the props type as a `type` alias. `typesOptions.propsDeclaration: "interface"` emits an `interface` instead, for consumers who want to extend it with `interface MyProps extends ButtonProps`, rely on declaration merging, or just prefer the shorter editor hover an `interface` gets.
-
-```js
-sveld({
-  types: true,
-  typesOptions: {
-    propsDeclaration: "interface",
-  },
-});
-```
-
-**Button.svelte.d.ts** before / after:
-
-```diff
-- export type ButtonProps = { label?: string };
-+ export interface ButtonProps { label?: string }
-```
-
-Only a plain object props type can become an `interface` safely. These shapes are intersections instead, and always stay a `type` alias regardless of this option:
-
-- a component with [`@restProps`](#restprops) (`Omit<$RestProps, keyof $Props> & $Props`)
-- a component with [`@extendProps`](#extendprops) (`Omit<Extended, keyof $Props> & $Props`)
-- a component with a whole-object `$props()` type resolved via [`resolveTypes`](#opt-in-semantic-resolution-resolvetypes) (`CanonicalPropsType & { ... }`)
-- a component with no props at all (`Record<string, never>`; an empty `interface` trips `noEmptyInterface` in consumer lint setups)
-
-Also available as `--types-props-declaration=<type|interface>` on the CLI.
-
-#### `typesOptions.transform`
-
-`typesOptions.transform` is an escape hatch for one-off edits no other option covers - appending a `/// <reference>` directive, rewriting an import specifier for a monorepo, stripping a banner. It runs on every generated `.d.ts` file's text, immediately before it's written, and receives the block's `kind` (`"component"` or `"index"`), and for `"component"` the parsed `ComponentDocApi` too, plus the output `filePath` relative to `outDir` (e.g. `"Button.svelte.d.ts"` or `"index.d.ts"`). Return the new text, synchronously or via a `Promise`.
-
-```js
-sveld({
-  types: true,
-  typesOptions: {
-    transform: (text, context) => {
-      if (context.kind !== "component") return text;
-      return `/// <reference types="svelte" />\n${text}`;
-    },
-  },
-});
-```
-
-```ts
-// Button.svelte.d.ts
-/// <reference types="svelte" />
-export type ButtonProps = { label?: string };
-// ...
-```
-
-`transform` runs after the [persistent parse cache](#persistent-parse-cache-cache)'s generated-text cache, so a changed transform is never served stale cached output - it always re-applies, even when the underlying `.d.ts` text was reused from a previous run. A transform that throws, or resolves to something other than a string, fails the whole `sveld` run with an error naming the file that failed.
-
-There's no CLI flag for `transform`; set it via a config file or the programmatic `sveld()` API.
-
-#### `typesOptions.indexTypes`
-
-By default, `types/index.d.ts` only re-exports components:
-
-```ts
-export { default as Button } from "./Button.svelte";
-```
-
-A consumer who wants `ButtonProps` has to deep-import `my-lib/types/Button.svelte`. `typesOptions.indexTypes` re-exports the generated types from the barrel instead, so `import type { ButtonProps } from "my-lib"` works directly.
-
-```js
-sveld({
-  types: true,
-  typesOptions: {
-    indexTypes: true,
-  },
-});
-```
-
-```ts
-// types/index.d.ts
-export { default as Button } from "./Button.svelte";
-
-export type { ButtonProps } from "./Button.svelte";
-```
-
-```ts
-import type { ButtonProps } from "my-lib";
-```
-
-`true` is shorthand for `{ props: true, exports: true }`: it re-exports each component's `Props` type, and (under [`format: "component"`](#dts-output-format-typesoptionsformat)) its `Exports` type. Pass an object to also re-export typedefs and/or contexts:
-
-```js
-typesOptions: {
-  indexTypes: { props: true, typedefs: true, contexts: true },
-}
-```
-
-`Props`/`Exports` names are unique per component by construction (they're derived from the module name), so they're always safe to re-export together. Typedef and context names are user-authored and can collide across components - when two components generate the same name, the first one in barrel order wins and every later collision is dropped with a one-line warning to `stderr`:
-
-```
-sveld: index.d.ts skips duplicate type export "TabsContext" from "./Tabs2.svelte" (already exported from "./Tabs.svelte").
-```
-
-`indexTypes` composes with [`exportTypes`](#typesoptionsexporttypes): a type that `exportTypes` keeps local to its component's `.d.ts` is never re-exported from the barrel either, since it wouldn't resolve.
-
-Also available as `--types-index-types` on the CLI, mapped to the boolean form (`true` re-exports `Props`/`Exports` only) — the CLI can't express the per-kind object form. Pass `--types-index-types=false` to disable it explicitly.
-
-#### `typesOptions.inline`
-
-A TypeScript component that imports a type keeps that import in its `.d.ts`:
-
-```svelte
-<script lang="ts">
-  import type { Size } from "./types";
-  let { size }: { size: Size } = $props();
-</script>
-```
-
-```ts
-import type { Component } from "svelte";
-import type { Size } from "./types";
-
-type $Props = { size: Size };
-export type MyComponentProps = $Props;
-```
-
-Publishers who don't ship their `.svelte` sources need `.d.ts` files without relative imports:
-`./types.ts` might sit outside the published `types/` output directory, or the package might be
-bundled to a single file. `typesOptions.inline: "local"` copies the imported declaration into
-the `.d.ts` instead of importing it:
-
-```js
-sveld({
-  types: true,
-  typesOptions: {
-    inline: "local",
-  },
-});
-```
-
-```ts
-import type { Component } from "svelte";
-
-type Size = "sm" | "md" | "lg";
-
-type $Props = { size: Size };
-export type MyComponentProps = $Props;
-```
-
-`"local"` follows:
-
-- relative sources (`./types`) and tsconfig/jsconfig `paths` aliases;
-- re-exports (`export { X as Y } from "./z"` and `export * from "./z"`);
-- same-file dependencies (a copied type that itself references another type or interface
-  declared in the same file copies that one too, before the type that references it).
-
-It leaves alone:
-
-- bare/package imports (`import type { CSSProperties } from "some-package"`) and `.svelte`
-  sources — `"all"` covers bare imports, see below;
-- `@extendProps`/`@extends` imports and `import("./x")` inline import types inside typedefs,
-  which are unrelated mechanisms;
-- `enum`, `class`, and `function` exports, which can't be safely copied as a `type`/`interface`.
-
-An import that can't be safely inlined (a missing file, a missing export, one of the unsupported
-export kinds above, or a name collision with something the component's `.d.ts` already declares
-or imports — a typedef, a context type, a local `type`/`interface`, its `Props`/`Exports` type
-name, the component's own name, `$Props`/`$RestProps`, the svelte types the `.d.ts` imports, or a
-name bound by an import that stays) is left
-as an import, with a [`types-inline-unresolved`](#diagnostic-codes) warning explaining why. If an
-`import type { A, B } from "./x"` statement imports several names and even one of them can't be
-inlined, the whole statement is kept and nothing from it is inlined — simpler, and always correct.
-
-**`"all"`** additionally inlines bare/package imports:
-
-```svelte
-<script lang="ts">
-  import type { HTMLButtonAttributes } from "svelte/elements";
-  import type { Alignment } from "some-design-system";
-  let { rest, align }: { rest: HTMLButtonAttributes; align: Alignment } = $props();
-</script>
-```
-
-```js
-sveld({
-  types: true,
-  typesOptions: {
-    inline: "all",
-  },
-});
-```
-
-```ts
-import type { Component } from "svelte";
-import type { HTMLButtonAttributes } from "svelte/elements";
-
-type Alignment = "start" | "center" | "end";
-
-type $Props = { rest: HTMLButtonAttributes; align: Alignment };
-export type MyComponentProps = $Props;
-```
-
-`some-design-system`'s `Alignment` got copied in, exactly like a `"local"` relative import would.
-`svelte`/`svelte/elements` did not, even though `HTMLButtonAttributes` is itself a bare import a
-real TypeScript checker could resolve and copy just as easily: those two specifiers are a
-hard-coded allow-list and always stay imports under `"all"`, regardless of what they resolve to.
-Copying framework types would freeze whatever Svelte version happened to be installed at
-generation time into every consumer's `.d.ts` output, which defeats the point of importing them
-from `svelte` in the first place.
-
-Resolving a bare specifier to a file needs a real module resolver, so `"all"` uses the actual
-TypeScript checker (the same one behind [`resolveTypes`](#opt-in-semantic-resolution-resolvetypes)
-and [`checkExamples`](#compile-checked-example-blocks-checkexamples), shared across all three when
-more than one is enabled) rather than sveld's own AST-only pass. This makes `"all"` a **hard
-requirement** on `typescript` 7+ and a resolvable `tsconfig.json` — same contract `resolveTypes`
-already has (see [Requirements](#requirements)): if TypeScript can't be started, the run fails
-loudly rather than silently falling back to `"local"` behavior. The requirement only actually
-kicks in when there's at least one non-allow-listed bare import somewhere in the bundle to
-resolve; an `"all"` run with nothing bare to inline never loads TypeScript at all.
-
-A reference inside a copied bare declaration is chased exactly like a local one: a same-file
-helper type is copied and recursed into, a relative/aliased import is followed the same way
-`"local"` already does, and a further bare import goes back through the checker (again skipping
-the svelte/svelte-elements allow-list). A reference that resolves to a TypeScript default-lib file
-(e.g. `Element`, `EventTarget` from `lib.dom.d.ts`) is left alone — it's already global and needs
-no import — the same way a local pass leaves an unimported name alone.
-
-`@extendProps`/`@extends` inlining (replacing `import type { ButtonProps } from "./Button.svelte"`
-with a copy of `Button`'s own generated declaration) is out of scope for both `"local"` and
-`"all"`; that's a distinct, deferred mechanism, not covered here.
-
-Copying from a large package can produce a large `.d.ts`: `svelte/elements`'s attribute-map
-interfaces (`HTMLButtonAttributes` and friends) are individually sizable, and every type they
-transitively reference gets copied too. Prefer `"local"` if you don't specifically need bare
-imports inlined.
-
-A component with at least one inlined declaration skips the generated-text cache (its output now
-depends on another file's contents, not just its own source hash), though its *parse* is still
-cached as usual. Also available as `--types-inline=<local|all>` on the CLI; `--types-inline=false`
-resets to the default.
-
-#### `markdownOptions.onAppend`
-
-`markdownOptions.onAppend` fires on every heading, quote, paragraph, divider, and raw block written to the Markdown document, and receives the block's `type`, the in-progress `WriterMarkdown` document, and the full component map. Use it to inject extra content, e.g. a summary line under the `h1` title.
-
-```js
-import pkg from "./package.json" with { type: "json" };
-
-sveld({
-  markdown: true,
-  markdownOptions: {
-    onAppend: (type, document, components) => {
-      if (type === "h1") {
-        document.append(
-          "quote",
-          `${components.size} components exported from ${pkg.name}@${pkg.version}.`,
-        );
-      }
-    },
-  },
-});
-```
-
-```md
-# Component Index
-
-> 1 components exported from sveld-scratch@1.0.0.
-```
-
-#### `markdownOptions.outDir`
-
-With `markdown: true`, `sveld` writes a single `COMPONENT_INDEX.md` at the project root, documenting every component.
-
-Use `markdownOptions.outDir` to split that into one `<ModuleName>.md` file per component, plus an index `README.md` that links to each one (and holds the Exports section when `documentExports` is on — per-component sections live entirely in their own file):
-
-```js
-sveld({
-  markdown: true,
-  markdownOptions: {
-    // e.g. "docs/Button.md", "docs/README.md"
-    outDir: "docs",
-  },
-});
-```
-
-`onAppend` still fires for both the index and every per-component file. `outFile` is ignored once `outDir` is set.
-
-## Documenting Entry Exports
-
-Most entry barrels re-export more than `.svelte` components. Set `documentExports: true` to add consts, functions, and types to the JSON and Markdown output.
-
-```diff
-sveld({
-  json: true,
-  markdown: true,
-+  documentExports: true,
-})
-```
-
-Example entry file:
-
-```ts
-// src/index.ts
-export { default as Button } from "./Button.svelte";
-export { VERSION } from "./constants";
-export { clamp } from "./utils";
-export type { Theme } from "./types";
-```
-
-From that barrel, `sveld` documents `VERSION`, `clamp`, and `Theme`. `Button` still goes through the component path. Type text is copied from source, not resolved with `tsc`, same as the rest of the tool.
-
-Nested barrels are followed too: `export { X } from "./dir"`, where `./dir/index.js` itself re-exports `.svelte` files, resolves `X` to the underlying component without needing `--glob`.
-
-JSON adds `exports` and `totalExports`. Markdown adds an "Exports" section. Each item has `name`, `kind`, type text, optional JSDoc `description`, `source`, and — same as props — optional `@deprecated` and pass-through `tags`. A deprecated export's name is struck through in the Markdown table, same as a deprecated prop. See [`@deprecated`](#deprecated).
-
-An overloaded function (repeated `export function f(...)` signatures, or an import re-exported through a barrel) always documents the implementation signature, i.e. the last declaration. An `enum` export's `type` is the literal union of its members' values (`"A" | "B"` for a string enum, `0 | 1` for a numeric one), falling back to the bare enum name when a member's value can't be determined (e.g. a computed initializer). A name the barrel exports itself (`export const X` or `export { X } from "./x"`) wins over the same name from an `export *`, as it does at runtime. When two `export *` statements bring in the same name from different modules (`export * from "./a"; export * from "./b"`), the name is ambiguous: the barrel doesn't export it at all, so `sveld` leaves it out and reports a [`sveld/export-ambiguous`](#diagnostic-codes) diagnostic naming both modules. Export it explicitly from the barrel (`export { format } from "./a"`) to pick one; that export wins silently. A namespace re-export (`export * as utils from "./utils"`, or an `import * as utils` the barrel re-exports) documents the one `const` export `utils`, with the wrapped module as its `source` and `typeof import("./utils.ts")` as its `type` (the module's path relative to the entry file, so the Markdown Type column names it); the names inside `./utils` aren't exports of the barrel, so they aren't listed. A re-exported default (`export { default as track } from "./track"`) is documented when that default export is a function, a class, or a named binding, with the JSDoc above `export default` as a named export would have; any other default (an object literal, say) is left out.
-
-## JSON Output
-
-When `json: true` is enabled, `sveld` emits a `COMPONENT_API.json` file with schema and generator metadata plus the parsed
-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.
-
-`sveld` also ships the schema as a package subpath, so you don't need network access to validate at build time:
-
-```ts
-import schema from "sveld/schema/component-api.schema.json" with { type: "json" };
-```
-
-`require.resolve("sveld/schema/component-api.schema.json")` works too. The `$id` in the schema still points at the `main` branch on GitHub for tooling that dereferences it by URL, but that URL always reflects the latest release; the copy packaged with your installed `sveld` version is the authoritative one for the output it produced.
-
-```ts
-interface ComponentApiJson {
-  schemaVersion: 1;
-  generator: {
-    name: string;
-    version: string;
-    svelteVersion: string;
-  };
-  total: number;
-  components: ComponentDocApi[];
-  // Present only when `documentExports` is enabled.
-  totalExports?: number;
-  exports?: EntryExport[];
-}
-
-interface EntryExport {
-  name: string;
-  kind: "const" | "let" | "var" | "function" | "class" | "type" | "interface" | "enum";
-  type?: string;
-  value?: string;
-  description?: string;
-  deprecated?: string | true;
-  tags?: Array<{ name: string; body: string }>;
-  source?: string;
-  isTypeOnly: boolean;
-}
-
-interface SourceRange {
-  start: SourcePosition;
-  end: SourcePosition;
-}
-
-interface SourcePosition {
-  line: number;
-  column: number;
-}
-
-interface ComponentDocApi {
-  moduleName: string;
-  filePath: string;
-  source?: SourceRange;
-  syntaxMode: "legacy" | "runes";
-  scriptLanguage?: "js" | "ts";
-  props: ComponentProp[];
-  moduleExports: ComponentProp[];
-  slots: ComponentSlot[];
-  events: ComponentEvent[];
-  typedefs: TypeDef[];
-  generics: null | [name: string, type: string];
-  rest_props?: RestProps;
-  extends?: { interface: string; import: string };
-  componentComment?: string;
-  componentCommentSource?: SourceRange;
-  contexts?: ComponentContext[];
-  customElementTag?: string;
-}
-
-interface ComponentProp {
-  name: string;
-  localName?: string;
-  // "re-export" and "class" are module exports only.
-  kind: "let" | "const" | "function" | "re-export" | "class";
-  constant: boolean;
-  type?: string;
-  typeSource?: "typescript" | "jsdoc" | "default" | "inferred" | "unknown";
-  value?: string;
-  defaultValue?: {
-    raw: string;
-    kind: "literal" | "array" | "object" | "expression" | "function" | "unknown";
-    value?: unknown;
-  };
-  description?: string;
-  params?: Array<{ name: string; type: string; description?: string; optional?: boolean }>;
-  returnType?: string;
-  isFunction: boolean;
-  isFunctionDeclaration: boolean;
-  isRequired: boolean;
-  reactive: boolean;
-  binding?: "readonly" | "writable";
-  bindable?: true;
-  // Set when `kind` is "class".
-  members?: Array<{
-    kind: "constructor" | "method" | "property";
-    name: string;
-    type?: string;
-    params?: Array<{ name: string; type: string; description?: string; optional?: boolean }>;
-    returnType?: string;
-    typeParameters?: string;
-    static?: true;
-    readonly?: true;
-    optional?: true;
-    abstract?: true;
-    description?: string;
-    deprecated?: string | true;
-    tags?: Array<{ name: string; body: string }>;
-  }>;
-  abstract?: true;
-  source?: SourceRange;
-}
-
-interface ComponentSlot {
-  name?: string | null;
-  default: boolean;
-  fallback?: string;
-  slot_props?: string;
-  description?: string;
-  tags?: Array<{ name: string; body: string }>;
-  source?: SourceRange;
-}
-
-type ComponentEvent =
-  | {
-      type: "forwarded";
-      name: string;
-      element: string;
-      description?: string;
-      detail?: string;
-      source?: SourceRange;
-    }
-  | {
-      type: "dispatched";
-      name: string;
-      detail?: string;
-      description?: string;
-      source?: SourceRange;
-    };
-```
-
-`source` fields appear only when the Svelte or JavaScript AST has stable positions. They omit source text and raw character offsets.
-
-`SourcePosition.line` is 1-based. `SourcePosition.column` is 0-based.
-
-Prop metadata is additive and keeps the older public fields:
-
-- `name` is always the public prop name. For runes `$props()` aliases such as `let { class: className } = $props()`, `localName` is emitted only when the local binding differs.
-- `typeSource` identifies the conservative source of the emitted `type`: TypeScript annotation, JSDoc, initializer/default inference, other parser inference, or unknown fallback.
-- `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 `export let`/`const` prop becomes a `ClassField` (`name`, `type.text`, `default`, `description`, `deprecated`; `readonly: true` for an `export const`). An accessor prop (`export function`) becomes a `ClassMethod` (`name`, `static: false`, `parameters`, `return.type.text`) instead — see [Accessor methods](#accessor-methods) below.
-- **Attributes** — every prop becomes an attribute (Svelte's custom-element runtime observes one for every prop by default), excluding `export function` accessors. The attribute name is `prop.toLowerCase()` by default, or the `customElement.props.<name>.attribute` config when set — see [Object-form `customElement` config](#object-form-customelement-config) below. Props that collide on the same attribute name keep the first (in declaration order); the rest are skipped with a console warning, since which one wins at runtime is ambiguous.
-- **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.
-- **`cssParts`/`cssProperties`** — from `@csspart`/`@cssprop` JSDoc tags — see [CSS parts and custom properties](#css-parts-and-custom-properties) below.
-
-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.
-
-### Object-form `customElement` config
-
-The object form of `<svelte:options customElement={{ ... }} />` is read in full, not just `tag`:
-
-```svelte
-<svelte:options
-  customElement={{
-    tag: "x-widget",
-    shadow: "none",
-    props: {
-      variant: { attribute: "data-variant" },
-      active: { reflect: true },
-      tags: { type: "Array" }
-    },
-    extend: (customElementConstructor) => customElementConstructor
-  }}
-/>
-```
-
-| Config | Effect on the manifest |
-| --- | --- |
-| `props.<name>.attribute` | Overrides that prop's attribute name (default: `name.toLowerCase()`). `attribute: false` omits the prop's attribute entirely. |
-| `props.<name>.reflect` | Adds `reflects: true` to that prop's attribute. |
-| `props.<name>.type` | `"Array"`/`"Object"` appends a note to the attribute's description that the value is JSON-serialized (matching Svelte's runtime `JSON.stringify`/`JSON.parse` for those types); the attribute's `type.text` is still the prop's own TS type, not this config value. |
-| `shadow`, `extend` | Parsed and available on the raw `ParsedComponent.customElement` (Node API), but don't affect the manifest. |
-
-This full config (`tag`, `shadow`, `props`, `extend`) is also on `ParsedComponent.customElement` in the JSON output (`COMPONENT_API.json`), alongside the existing `customElementTag` shorthand.
-
-### Accessor methods
-
-An `export function` prop (a Svelte accessor, e.g. `export function focus() { ... }`) becomes a `ClassMethod`, not a `ClassField`, and is excluded from `attributes` (accessors aren't part of Svelte's props definition). `parameters`/`return` come from `@param`/`@returns` JSDoc when present, otherwise from splitting the function's TypeScript signature text (e.g. `(id: string) => boolean`).
-
-### CSS parts and custom properties
-
-Document shadow-DOM styling hooks with `@csspart`/`@cssprop` (alias `@cssproperty`) tags in the component's own JSDoc comment (the same comment block `@slot` tags go in):
-
-```js
-/**
- * @csspart header - Styles the header region.
- * @cssprop {Color} [--card-background=white] - Background color of the card.
- * @cssprop --card-border-color - Border color of the card.
- */
-```
-
-`@cssprop`'s `{type}` and `[--name=default]` are both optional, following the [Custom Elements Manifest analyzer](https://custom-elements-manifest.open-wc.org/analyzer/getting-started/#css-custom-properties) grammar. These populate `cssParts`/`cssProperties` on the class declaration, and `ParsedComponent.cssParts`/`cssProperties` in the JSON output; the Markdown writer renders them as two extra tables when present.
-
-### 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.
-
-## llms.txt Output
-
-Set `llms: true` to emit an [`llms.txt`](https://llmstxt.org) / `llms-full.txt` pair: `llms.txt` is an index of every exported component (one link plus a one-line summary each), and `llms-full.txt` is the flattened full reference (every component's Props, Bindings, Events, Slots/Snippets, Typedefs, and Module exports, as terse Markdown tables). Props and Events Description columns include `@since`/`@example` tags, same as `COMPONENT_INDEX.md`. Fenced code in a Description cell is printed after its table as a regular fenced block, with `(code below)` left in the cell.
-
-```diff
-sveld({
-+  llms: true,
-})
-```
-
-- **`llms`** (boolean, optional): Generate `llms.txt` and `llms-full.txt`. Also available as the `--llms` CLI flag.
-- **`llmsOptions`** (object, optional):
-  - **`outDir`** (string, optional): Directory (relative to the project root) both files are written into. Defaults to the project root.
-  - **`linkBase`** (string, optional, default: `""`): Prefixed to each component's link in `llms.txt`, e.g. `[Button](<linkBase>/Button)`. Set this to your published docs site's base path.
-  - **`title`** (string, optional, default: the `"name"` field from `package.json`): The `# <title>` heading both files start with.
-  - **`summary`** (string, optional, default: the `"description"` field from `package.json`): The `> <summary>` blockquote under the title. Omitted when neither is set.
-
-Each component's one-line summary in `llms.txt` is the first sentence of its [`@component` comment](#component-comments), falling back to `"Component"`. Set `documentExports: true` to also list entry-barrel exports (consts, functions, types) in `llms.txt` under an `## Exports` heading.
-
-## Custom Writers
-
-`json`, `markdown`, `types`, and `custom-elements` are all built on the same
-extensibility point: a small writer registry that third parties can use to
-add new output formats without a core PR. This is a stable, public part of
-sveld's API — the four built-in writers register through it in
-`src/writer/built-in-writers.ts`, there is no separate "internal" path.
-
-### The `OutputWriter` contract
-
-```ts
-interface OutputWriter<TOptions = unknown> {
-  name: string;
-  /** Which component set this writer expects. @default "exported" */
-  componentSet?: "exported" | "all";
-  write(components: ComponentDocs, options: TOptions): Promise<unknown> | unknown;
-}
-```
-
-- **`name`** is how the plugin's `additionalWriters` option (and anything else
-  that calls `getWriter`) looks the writer up. Pick something that won't
-  collide with `types` / `json` / `markdown` / `custom-elements` or another
-  third-party writer.
-- **`componentSet`** picks which map `write` receives:
-  - `"exported"` (the default) — components reachable from the entry barrel,
-    keyed by `moduleName`. This is what `json` / `markdown` /
-    `custom-elements` use.
-  - `"all"` — every `--glob`-discovered `.svelte` file, keyed by resolved
-    `filePath` instead of `moduleName` (two files in different directories
-    can share a basename). This is what `types` uses.
-- **`write`** receives a `ComponentDocs` (`Map<string, ComponentDocApi>`) —
-  the same `ComponentDocApi` shape documented in [JSON Output](#json-output).
-  Don't iterate the raw map yourself; call `buildComponentApiDocument(components, { entryExports })`
-  (also exported from `sveld`) to get the sorted, `diagnostics`-stripped,
-  schema-versioned document the built-in writers build from. It's memoized
-  per `components` map, so calling it more than once in one run is free.
-- **`options`** always carries `dryRun` alongside whatever fields the writer
-  itself defines. See [The `dryRun` contract](#the-dryrun-contract) below.
-
-### Registering a writer
-
-```ts
-import { registerWriter } from "sveld";
-
-registerWriter({
-  name: "my-format",
-  write(components, options) {
-    // ...
-  },
-});
-```
-
-`registerWriter` is a side effect — call it once, before the plugin or CLI
-runs, e.g. at the top of `vite.config.ts` or `sveld.config.ts`, or in a file
-either of those imports.
-
-Registering a `name` that's already taken — a built-in writer's name, or
-another `registerWriter` call — throws instead of silently overwriting it.
-Pass `{ replace: true }` as a second argument when overwriting is intentional
-(e.g. re-registering a writer module during development):
-
-```ts
-registerWriter(
-  {
-    name: "my-format",
-    write(components, options) {
-      // ...
-    },
-  },
-  { replace: true },
-);
-```
-
-### The `dryRun` contract
-
-Every writer — built-in or `additionalWriters` — receives `dryRun: true` in
-its `options` when the run is `sveld --dry-run` (or `{ dryRun: true }` from
-the programmatic API). A writer must check it and skip touching disk; sveld
-does not do this for you:
-
-```ts
-import { writeFileSync } from "node:fs";
-
-registerWriter({
-  name: "my-format",
-  write(components, options: { outFile: string; dryRun?: boolean }) {
-    if (options.dryRun) {
-      console.log(`would write "${options.outFile}"`);
-      return;
-    }
-    writeFileSync(options.outFile, "...");
-  },
-});
-```
-
-A writer that throws — synchronously or from a rejected promise — has its
-error re-thrown as `sveld: writer "<name>" failed: <message>`, with the
-original error attached as `cause`, so a broken third-party writer never
-fails silently or without saying which one.
-
-### Running it via the plugin
-
-```ts
-// vite.config.ts
-import sveld from "sveld";
-import "./writers/my-format"; // calls registerWriter as a side effect
-
-export default {
-  plugins: [
-    sveld({
-      additionalWriters: {
-        "my-format": { outFile: "MY_FORMAT.txt" },
-      },
-    }),
-  ],
-};
-```
-
-`additionalWriters` is keyed by the writer's registered `name`; the value is
-whatever options object that writer's `write` expects. An unknown name logs a
-warning and is skipped rather than failing the build. Registered writers run
-alongside whichever built-in outputs (`types` / `json` / `markdown` /
-`customElements`) are also enabled, and the same option is available from the
-programmatic Node API and from `sveld.config.ts` (`additionalWriters` lives on
-the options shared by all three entry points).
-
-### Worked example: a `components.txt` name-list writer
-
-Looking for an `llms.txt` writer specifically? Sveld ships one — see [llms.txt Output](#llmstxt-output). This example is a much smaller custom writer, just to show the pattern: a plain-text list of exported component names, needing nothing beyond `ComponentApiDocument`.
-
-```ts
-// writers/components-txt-writer.ts
-import { writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { buildComponentApiDocument, registerWriter } from "sveld";
-
-interface ComponentsTxtWriterOptions {
-  outFile?: string;
-}
-
-registerWriter<ComponentsTxtWriterOptions>({
-  name: "components-txt",
-  componentSet: "exported",
-  write(components, options = {}) {
-    const document = buildComponentApiDocument(components);
-    const rendered = document.components.map((component) => component.moduleName).join("\n");
-
-    writeFileSync(join(process.cwd(), options.outFile ?? "components.txt"), rendered);
-  },
-});
-```
-
-```ts
-// vite.config.ts
-import sveld from "sveld";
-import "./writers/components-txt-writer";
-
-export default {
-  plugins: [
-    sveld({
-      additionalWriters: {
-        "components-txt": { outFile: "components.txt" },
-      },
-    }),
-  ],
-};
-```
-
-Running a build now produces a `components.txt` alongside the usual output,
-listing one exported component name per line.
-
-## API Reference
-
-A JSDoc block documents the declaration below it. Blank lines and ordinary comments may sit between the two, such as a `// biome-ignore ...` or `/* istanbul ignore next */` line.
-
-### `reactive`
-
-The `reactive` field in generated JSON is a heuristic. It does not fully answer whether a parent can use `bind:prop` in Svelte.
-
-`sveld` marks `reactive: true` when it finds internal evidence that a prop is writable, including:
-
-- the prop is assigned or mutated inside the component
-- the prop is marked bindable in runes mode with `$bindable(...)`
-- the prop is used as the target of `bind:*` on an element or child component
-- wrapper-forwarded bindings such as `bind:value`, `bind:selected`, and `bind:ref`
-
-Local variables or parameters that shadow a prop name do not count as writes to the exported prop.
-
-`reactive: false` means `sveld` found no such evidence. It does not imply that parent-side `bind:` usage is impossible.
-
-### `binding`
-
-The optional `binding` field documents a prop's intended `bind:` contract. It is separate from `reactive` and is never inferred from internal writes or `$bindable()`.
-
-Use `@bindable readonly` for component-owned or output-style bindings where the consumer binds to the current value emitted by the component:
-
-```svelte
-<script>
-  /**
-   * Bind to the current value emitted by the component.
-   * @bindable readonly
-   */
-  export let size = undefined;
-</script>
-```
-
-Use `@bindable writable` for two-way or shared state bindings where either the consumer or component may control the value:
-
-```svelte
-<script>
-  /**
-   * Bind to state controlled by either the consumer or component.
-   * @bindable writable
-   */
-  export let open = false;
-</script>
-```
-
-Generated JSON includes `"binding": "readonly"` or `"binding": "writable"` for annotated props. Unannotated props omit the field.
-
-This is documentation only. Generated `.svelte.d.ts` prop types do not change. TypeScript cannot express Svelte binding direction reliably.
-
-### `@type`
-
-Without a `@type` annotation, `sveld` infers the primitive type for a prop:
-
-```js
-export let kind = "primary";
-// inferred type: "string"
-```
-
-For template literal default values, `sveld` infers the type as `string`:
-
-```js
-export let id = `ccs-${Math.random().toString(36)}`;
-// inferred type: "string"
-```
-
-Use the `@type` tag to document the type explicitly. In the example below, `kind` is a string union.
-
-For `lang="ts"` components, prefer native TypeScript annotations when you already have them. `@type` still helps in JavaScript components, for overriding inferred types, and when the AST cannot recover a sharper type.
-
-**Signature:**
-
-```js
-/**
- * Optional description
- * @type {Type}
- */
-```
-
-**Example:**
-
-```svelte
-<script>
-  let {
-    /**
-     * Specify the kind of button
-     * @type {"primary" | "secondary" | "tertiary"}
-     */
-    kind = "primary",
-    /**
-     * Specify the Carbon icon to render
-     * @type {typeof import("carbon-icons-svelte").CarbonIcon}
-     */
-    renderIcon = Close20,
-  } = $props();
-</script>
-```
-
-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.
-
-A declaration-level `@type` naming an object `@typedef` (or an inline `{ ... }` type) types the whole `$props()` object instead, the form Svelte's docs recommend for JavaScript components. Each prop takes its type, optionality, and description from the matching member:
-
-```svelte
-<script>
-  /**
-   * @typedef {object} Props
-   * @property {string} title Card title
-   * @property {boolean} [elevated=false] Raise the card
-   */
-
-  /** @type {Props} */
-  let { title, elevated = false } = $props();
-</script>
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<script>
-  /**
-   * Specify the kind of button
-   * @type {"primary" | "secondary" | "tertiary"}
-   */
-  export let kind = "primary";
-
-  /**
-   * Specify the Carbon icon to render
-   * @type {typeof import("carbon-icons-svelte").CarbonIcon}
-   */
-  export let renderIcon = Close20;
-</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:
-
-- `import("module").Type` references an exported **type**.
-- `typeof import("module").value` references the type of an exported **value**.
-- `import("svelte").ComponentProps<...>` and other utility types compose with imports.
-
-This keeps third-party types (Svelte stores, another component's props, library types) out of runtime imports while still showing up in IntelliSense for consumers.
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * A store from `svelte/store`. No top-level `import` required.
-   * @type {import("svelte/store").Writable<string>}
-   */
-  export let value;
-
-  /**
-   * `typeof import(...)` references the type of a value export, here the
-   * `writable` factory itself rather than a type it exports.
-   * @type {typeof import("svelte/store").writable}
-   */
-  export let createStore;
-
-  /**
-   * Reuse another component's props with Svelte's `ComponentProps` utility.
-   * @type {import("svelte").ComponentProps<import("svelte").SvelteComponent>}
-   */
-  export let buttonProps;
-
-  /**
-   * `import(...)` works inside a `@typedef` too, which helps when typing values shared via `setContext` / `getContext`.
-   *
-   * @typedef {{ rows: import("svelte/store").Writable<string[]>; selected: import("svelte/store").Readable<number> }} TableContext
-   */
-
-  /** @type {TableContext} */
-  export let context;
-</script>
-```
-
-Output:
-
-```ts
-export interface TableContext {
-  rows: import("svelte/store").Writable<string[]>;
-  selected: import("svelte/store").Readable<number>;
-}
-
-export type ComponentProps = {
-  /** @default undefined */
-  value: import("svelte/store").Writable<string>;
-  /** @default undefined */
-  createStore: typeof import("svelte/store").writable;
-  /** @default undefined */
-  buttonProps: import("svelte").ComponentProps<import("svelte").SvelteComponent>;
-  /** @default undefined */
-  context: TableContext;
-};
-```
-
-#### Prefer `unknown` over `any`
-
-When a prop accepts data whose shape you do not know ahead of time, annotate it as `unknown` rather than `any`. `sveld` preserves either keyword in the emitted prop type, but they behave differently for consumers: `unknown` forces a narrowing check before use; `any` disables type checking everywhere the value flows. Reserve `any` for real escape hatches.
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * A value of unknown shape. Prefer `unknown` over `any`: consumers must
-   * narrow it before use instead of silently opting out of type checking.
-   *
-   * @type {unknown}
-   */
-  export let payload;
-
-  /**
-   * An escape hatch typed as `any`, shown for contrast. `any` disables type
-   * checking everywhere it flows, so reach for `unknown` at boundaries instead.
-   *
-   * @type {any}
-   */
-  export let raw;
-</script>
-```
-
-Output:
-
-```ts
-export type ComponentProps = {
-  /** @default undefined */
-  payload: unknown;
-  /** @default undefined */
-  raw: any;
-};
-```
-
-Consumers must narrow an `unknown` prop before using it, while an `any` prop silently accepts anything:
-
-```ts
-function handle(props: ComponentProps) {
-  // Error: 'payload' is of type 'unknown'. Narrow it first.
-  props.payload.toUpperCase();
-
-  if (typeof props.payload === "string") {
-    props.payload.toUpperCase(); // OK after narrowing
-  }
-}
-```
-
-### `@default`
-
-By default, `sveld` infers the `@default` value from the prop's initializer and includes it in the generated TypeScript definitions:
-
-```svelte
-<script>
-  export let open = false;
-</script>
-```
-
-```ts
-/**
- * @default false
- */
-open?: boolean;
-```
-
-A fallback or conditional initializer (`??`, `||`, `&&`, `?:`) shows its source text, folded onto one line, in the `.d.ts`, the JSON `value`, and the Markdown "Default value" column:
-
-```svelte
-<script>
-  export let theme = undefined;
-  const defaultSize = theme === "dense" ? "sm" : "md";
-
-  export let size = defaultSize ?? "md";
-</script>
-```
-
-```ts
-/**
- * @default defaultSize ?? "md"
- */
-size?: string;
-```
-
-Use `@default` to document the default value. When you supply `@default`, `sveld` uses it instead of the inferred value and avoids duplicate `@default` tags in the output.
-
-Use `@default` when the initializer references a variable or expression that means nothing to consumers:
-
-```svelte
-<script>
-  const defaultFilter = () => true;
-
-  /**
-   * @default () => true
-   * @type {(item: string, value: string) => boolean}
-   */
-  export let shouldFilter = defaultFilter;
-</script>
-```
-
-```ts
-/**
- * @default () => true
- */
-shouldFilter?: (item: string, value: string) => boolean;
-```
-
-#### Identifier resolution
-
-When a prop's initializer is a variable reference, `sveld` resolves it to the actual value:
-
-```svelte
-<script>
-  const DEFAULT_SIZE = "md";
-
-  /** @type {"sm" | "md" | "lg"} */
-  export let size = DEFAULT_SIZE;
-</script>
-```
-
-```ts
-/**
- * @default "md"
- */
-size?: "sm" | "md" | "lg";
-```
-
-Chained references are also resolved:
-
-```svelte
-<script>
-  const ACTUAL_VALUE = 42;
-  const ALIAS = ACTUAL_VALUE;
-
-  export let count = ALIAS;
-</script>
-```
-
-```ts
-/**
- * @default 42
- */
-count?: number;
-```
-
-Resolution follows up to 5 levels of indirection. Beyond that, the last resolved identifier name is used as the default value.
-
-A named import, or a member of a namespace import (`import * as timing from "./timing.js"` with `timing.TOOLTIP_LEAVE_DELAY_MS`, also through a namespace the module re-exports with `export * as`), resolves when the imported module (followed through re-exports) declares it as an `export const` with a string, number, boolean, or static template literal:
-
-```svelte
-<script>
-  // timing.js: export const TOOLTIP_LEAVE_DELAY_MS = 300;
-  import { TOOLTIP_LEAVE_DELAY_MS } from "./timing.js";
-
-  export let leaveDelayMs = TOOLTIP_LEAVE_DELAY_MS;
-</script>
-```
-
-```ts
-/**
- * @default 300
- */
-leaveDelayMs?: number;
-```
-
-Any other identifier that cannot be resolved (an `export let`, a computed value, a package import) is used as-is, and its type falls back to `any`.
-
-When an explicit `@default` annotation is provided, it always takes precedence over the resolved value.
-
-### `@typedef`
-
-The `@typedef` tag defines a shared type used multiple times in a component. All typedefs in a component are exported from the generated `.d.ts`.
-
-**Signature:**
-
-```js
-/**
- * @typedef {Type} TypeName
- */
-```
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * @typedef {string} AuthorName
-   * @typedef {{ name?: AuthorName; dob?: string; }} Author
-   */
-
-  let {
-    /** @type {Author} */
-    author = {},
-    /** @type {Author[]} */
-    authors = [],
-  } = $props();
-</script>
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<script>
-  /**
-   * @typedef {string} AuthorName
-   * @typedef {{ name?: AuthorName; dob?: string; }} Author
-   */
-
-  /** @type {Author} */
-  export let author = {};
-
-  /** @type {Author[]} */
-  export let authors = [];
-</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. See the [`@property`](#property) reference for the tag's valid contexts.
-
-**Signature:**
-
-```js
-/**
- * Type description
- * @typedef {object} TypeName
- * @property {Type} propertyName - Property description
- */
-```
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * Represents a user in the system
-   * @typedef {object} User
-   * @property {string} name - The user's full name
-   * @property {string} email - The user's email address
-   * @property {number} age - The user's age in years
-   */
-
-  /** @type {User} */
-  let { user = { name: "John", email: "john@example.com", age: 30 } } = $props();
-</script>
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<script>
-  /**
-   * Represents a user in the system
-   * @typedef {object} User
-   * @property {string} name - The user's full name
-   * @property {string} email - The user's email address
-   * @property {number} age - The user's age in years
-   */
-
-  /** @type {User} */
-  export let user = { name: "John", email: "john@example.com", age: 30 };
-</script>
-```
-
-</details>
-
-Output is identical for both syntax modes.
-
-Output:
-
-```ts
-export type User = {
-  /** The user's full name */
-  name: string;
-  /** The user's email address */
-  email: string;
-  /** The user's age in years */
-  age: number;
-};
-
-export type ComponentProps = {
-  /**
-   * Represents a user in the system
-   * @default { name: "John", email: "john@example.com", age: 30 }
-   */
-  user?: User;
-};
-```
-
-#### Optional properties and default values
-
-Use square brackets for optional properties, per JSDoc. Default values use `[propertyName=defaultValue]`.
-
-**Signature:**
-
-```js
-/**
- * @typedef {object} TypeName
- * @property {Type} [optionalProperty] - Optional property description
- * @property {Type} [propertyWithDefault=defaultValue] - Property with default value
- */
-```
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * Configuration options for the component
-   * @typedef {object} ComponentConfig
-   * @property {boolean} enabled - Whether the component is enabled
-   * @property {string} theme - The component theme
-   * @property {number} [timeout=5000] - Optional timeout in milliseconds
-   * @property {boolean} [debug] - Optional debug mode flag
-   */
-
-  /** @type {ComponentConfig} */
-  let { config = { enabled: true, theme: "dark" } } = $props();
-</script>
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<script>
-  /**
-   * Configuration options for the component
-   * @typedef {object} ComponentConfig
-   * @property {boolean} enabled - Whether the component is enabled
-   * @property {string} theme - The component theme
-   * @property {number} [timeout=5000] - Optional timeout in milliseconds
-   * @property {boolean} [debug] - Optional debug mode flag
-   */
-
-  /** @type {ComponentConfig} */
-  export let config = { enabled: true, theme: "dark" };
-</script>
-```
-
-</details>
-
-Output is identical for both syntax modes.
-
-Output:
-
-```ts
-export type ComponentConfig = {
-  /** Whether the component is enabled */
-  enabled: boolean;
-  /** The component theme */
-  theme: string;
-  /** Optional timeout in milliseconds @default 5000 */
-  timeout?: number;
-  /** Optional debug mode flag */
-  debug?: boolean;
-};
-
-export type ComponentProps = {
-  /**
-   * Configuration options for the component
-   * @default { enabled: true, theme: "dark" }
-   */
-  config?: ComponentConfig;
-};
-```
-
-> The inline syntax `@typedef {{ name: string }} User` still works for backwards compatibility.
-
-#### Discriminated unions
-
-A `@typedef` can be a union of object literals, optionally mixed with primitive members. `sveld` emits these as `export type X = ...` aliases (not `interface`), so the discriminant narrows correctly on the consumer side.
-
-**Signature:**
-
-```js
-/**
- * @typedef {A | B | C} TypeName
- */
-```
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * @typedef {{ kind: "success"; value: string } | { kind: "error"; error: Error }} Result
-   * @typedef {{ ok: true; data: number } | { ok: false; reason: string } | "pending"} Status
-   */
-
-  /** @type {Result} */
-  export let result = { kind: "success", value: "ok" };
-
-  /** @type {Status} */
-  export let status = "pending";
-</script>
-```
-
-Output:
-
-```ts
-export type Result = { kind: "success"; value: string } | { kind: "error"; error: Error };
-
-export type Status = { ok: true; data: number } | { ok: false; reason: string } | "pending";
-
-export type ComponentProps = {
-  /** @default { kind: "success", value: "ok" } */
-  result?: Result;
-  /** @default "pending" */
-  status?: Status;
-};
-```
-
-Consumers can then narrow on the discriminant:
-
-```ts
-function describe(r: Result) {
-  switch (r.kind) {
-    case "success":
-      return r.value;
-    case "error":
-      return r.error.message;
-  }
-}
-```
-
-The same pattern works inline via `@type`, which is useful when the union is only used for a single prop:
-
-```js
-/** @type {{ kind: "success"; value: string } | { kind: "error"; error: Error }} */
-export let result = { kind: "success", value: "ok" };
-```
-
-In `<script lang="ts">` components, write the type alias directly. `sveld` preserves it in the emitted `.d.ts`:
-
-```svelte
-<script lang="ts">
-  type Result = { kind: "success"; value: string } | { kind: "error"; error: Error };
-
-  let { result = { kind: "success", value: "ok" } }: { result?: Result } = $props();
-</script>
-```
-
-#### Branded types
-
-A branded type is a primitive plus a unique marker so values like `UserId` are not interchangeable with any other `string`. At runtime it is still the underlying primitive; TypeScript treats the brand as a separate type. Declare the brand inline with `@type`. `sveld` copies the intersection verbatim into the emitted prop type, so the brand shows up in IntelliSense, autocomplete, and hover tooltips on the consumer side.
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * A branded string. At runtime it is a plain `string`, but the brand makes it
-   * a distinct domain type that other strings cannot be assigned to.
-   *
-   * @type {string & { readonly __brand: "UserId" }}
-   */
-  export let userId;
-
-  /**
-   * A branded number representing a monetary amount in cents.
-   *
-   * @type {number & { readonly __brand: "Cents" }}
-   */
-  export let amount;
-</script>
-```
-
-Output:
-
-```ts
-export type ComponentProps = {
-  /**
-   * A branded string. At runtime it is a plain `string`, but the brand makes it
-   * a distinct domain type that other strings cannot be assigned to.
-   * @default undefined
-   */
-  userId: string & { readonly __brand: "UserId" };
-
-  /**
-   * A branded number representing a monetary amount in cents.
-   * @default undefined
-   */
-  amount: number & { readonly __brand: "Cents" };
-};
-```
-
-Consumers construct branded values with a narrowing cast, then get compile-time protection against mixing them up:
-
-```ts
-const userId = "user_123" as ComponentProps["userId"];
-
-// Error: a plain string is not assignable to the branded userId
-component.$set({ userId: "user_123" });
-```
-
-#### Utility types
-
-`sveld` preserves TypeScript utility types verbatim, so a prop type can be derived from an existing `@typedef` instead of restating its fields. `Pick`, `Omit`, `Partial`, `Required`, `Readonly`, `ReturnType`, `Parameters`, and `Awaited` pass through unchanged. When the base type changes, derived props follow.
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * @typedef {{ id: string; size: "sm" | "md" | "lg"; disabled: boolean }} Options
-   */
-
-  /**
-   * @typedef {() => Options} Factory
-   */
-
-  /**
-   * A subset of `Options`.
-   * @type {Pick<Options, "id" | "size">}
-   */
-  export let summary;
-
-  /**
-   * Everything in `Options` except `disabled`.
-   * @type {Omit<Options, "disabled">}
-   */
-  export let editable;
-
-  /**
-   * Derived from the factory's return type rather than restated.
-   * @type {ReturnType<Factory>}
-   */
-  export let defaults;
-
-  /**
-   * The resolved value of an async source.
-   * @type {Awaited<Promise<Options>>}
-   */
-  export let resolved;
-</script>
-```
-
-Output:
-
-```ts
-export interface Options {
-  id: string;
-  size: "sm" | "md" | "lg";
-  disabled: boolean;
-}
-
-export type Factory = () => Options;
-
-export type ComponentProps = {
-  summary: Pick<Options, "id" | "size">;
-  editable: Omit<Options, "disabled">;
-  defaults: ReturnType<Factory>;
-  resolved: Awaited<Promise<Options>>;
-};
-```
-
-#### Type guards
-
-A prop typed as a [type predicate](https://www.typescriptlang.org/docs/handbook/2/narrowing.html#using-type-predicates) (`value is T`) lets a component accept a user-defined type guard. `sveld` copies the predicate verbatim, whether you write it inline with `@type` or name it with `@typedef`, so narrowing survives in the generated `.d.ts`. Name guards `isX` or `hasX`, and make sure the implementation actually checks what the predicate claims.
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * @typedef {{ id: string; name: string }} User
-   */
-
-  /**
-   * A type guard. It accepts an `unknown` value and returns a type predicate,
-   * so callers can narrow `unknown` to `User` before accessing its fields.
-   *
-   * @type {(value: unknown) => value is User}
-   */
-  export let isUser;
-
-  /**
-   * A type guard expressed as a reusable `@typedef`.
-   *
-   * @typedef {(value: unknown) => value is User} UserGuard
-   */
-
-  /** @type {UserGuard} */
-  export let validate;
-</script>
-```
-
-Output:
-
-```ts
-export interface User {
-  id: string;
-  name: string;
-}
-
-export type UserGuard = (value: unknown) => value is User;
-
-export type ComponentProps = {
-  isUser: (value: unknown) => value is User;
-  validate: UserGuard;
-};
-```
-
-Consumers use the guard to narrow an `unknown` value:
-
-```ts
-function render(value: unknown, props: ComponentProps) {
-  if (props.isUser(value)) {
-    value.name; // narrowed to User
-  }
-}
-```
-
-### `@property`
-
-`@property` documents one field of an object. `sveld` only reads it in two places: directly inside a `@typedef {object}` block, and directly inside an `@event` block (after an explicit `@type {object}`, or with no `@type` at all — `sveld` builds the detail type from the collected `@property` entries). It has no effect anywhere else.
-
-**Valid contexts:**
-
-| Context | Behavior |
-| :- | :- |
-| After `@typedef {object} Name`, in the same comment block | Builds `Name`'s fields. See [Using `@property` for complex typedefs](#using-property-for-complex-typedefs). |
-| After `@event eventname`, in the same comment block | Builds the event's detail type. See [Using `@property` for complex event details](#using-property-for-complex-event-details). |
-| A plain prop with no `@typedef`/`@type {object}` | Not structured. Folded into the prop's description as literal text (`@property name - description`). |
-| Before a `@slot` / `@snippet` line | Dropped entirely — no structured output, and unlike other unrecognized tags in that position, it is not folded into the slot's description either. |
-| Inside `@callback` | Not read. Use `@param` for callback parameters instead. |
-
-**Signature:**
-
-```js
-/**
- * @typedef {object} TypeName
- * @property {Type} propertyName - Property description
- *
- * @event eventname
- * @type {object}
- * @property {Type} propertyName - Property description
- */
-```
-
-Both forms support the same modifiers as typedef properties elsewhere in this doc: optional properties (`[name]`), default values (`[name=value]`), and nested/discriminated-union shapes. See the linked sections above for full signatures and worked examples with generated output.
-
-A description can wrap onto continuation lines, which run until the next tag. Indent them past the `*` gutter to keep them attached to the tag unambiguously; an unindented line right above an `@event`/`@typedef`/`@slot` with no description of its own is read as that tag's description instead, and an unindented line after an event's last `@property` describes the event. A blank line between indented paragraphs doesn't end the description; it's kept as a paragraph break. Lines inside a ```` ``` ```` code fence keep their indentation relative to the fence.
-
-```js
-/**
- * @typedef {object} Config
- * @property {number} itemHeight Height of each item in pixels, used for
- *   virtualization math.
- */
-```
-
-A `{type}` can wrap too. The text after its closing `}` and the name is the tag's own description, exactly as if the type fit on one line:
-
-```js
-/**
- * @property {"ascending"
- *   | "descending"} [dir] - The next sort direction,
- *   reported regardless.
- */
-```
-
-### `@callback`
-
-The `@callback` tag defines a function type with `@param` and `@returns`, following the [TypeScript JSDoc `@callback` spec](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#callback). Like `@typedef`, callbacks are exported from the generated `.d.ts`.
-
-Use it for callback props when you do not want inline function type syntax.
-
-**Signature:**
-
-```js
-/**
- * Optional description
- * @callback CallbackName
- * @param {Type} paramName - Parameter description
- * @returns {ReturnType}
- */
-```
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * Callback fired when the value changes
-   * @callback OnChange
-   * @param {string} value - The new value
-   * @param {number} index - The index of the changed item
-   * @returns {void}
-   */
-
-  /** @type {OnChange} */
-  let { onChange = (value, index) => {} } = $props();
-</script>
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<script>
-  /**
-   * Callback fired when the value changes
-   * @callback OnChange
-   * @param {string} value - The new value
-   * @param {number} index - The index of the changed item
-   * @returns {void}
-   */
-
-  /** @type {OnChange} */
-  export let onChange = (value, index) => {};
-</script>
-```
-
-</details>
-
-Output is identical for both syntax modes.
-
-Output:
-
-```ts
-/**
- * Callback fired when the value changes
- */
-export type OnChange = (value: string, index: number) => void;
-
-export type ComponentProps = {
-  /**
-   * Callback fired when the value changes
-   */
-  onChange?: OnChange;
-};
-```
-
-Callbacks can be combined with `@typedef` in the same comment block:
-
-```js
-/**
- * @typedef {"asc" | "desc"} SortDirection
- * @callback SortFn
- * @param {any} a
- * @param {any} b
- * @param {SortDirection} direction
- * @returns {number}
- */
-```
-
-When `@returns` is omitted, the return type defaults to `void`. When no `@param` tags are present, the callback is typed as a no-argument function.
-
-### `@slot` / `@snippet`
-
-Use `@slot` to type component slots. In Svelte 5 runes components, `@snippet` is an alias. Both are non-standard JSDoc tags.
-
-Descriptions are optional for every slot, including the default slot. Put prose in the same `/** */` block above `@slot` / `@snippet`, or an inline description on the `@slot` line for named slots.
-
-**Signature:**
-
-```js
-/**
- * @slot {Type} slot-name [slot description]
- * @snippet {Type} snippet-name [snippet description]
- */
-```
-
-Omit the `slot-name` to type the default slot. `{Type}` itself is required; omitting it falls back to `Record<string, never>` and raises a [`sveld/slot-missing-type`](#diagnostic-codes) warning.
-
-```js
-/**
- * @slot {Type}
- * @snippet {Type}
- */
-```
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * @snippet {{ prop: number; doubled: number; }}
-   * @snippet {{}} title
-   * @snippet {{ prop: number }} body - Customize the paragraph text.
-   */
-
-  let { prop = 0, children, title, body } = $props();
-</script>
-
-<h1>
-  {@render children?.({ prop, doubled: prop * 2 })}
-  {@render title?.()}
-</h1>
-
-<p>
-  {@render body?.({ prop })}
-</p>
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<script>
-  /**
-   * @slot {{ prop: number; doubled: number; }}
-   * @slot {{}} title
-   * @slot {{ prop: number }} body - Customize the paragraph text.
-   */
-
-  export let prop = 0;
-</script>
-
-<h1>
-  <slot {prop} doubled={prop * 2} />
-  <slot name="title" />
-</h1>
-
-<p>
-  <slot name="body" {prop} />
-</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" }, ...]`.
-
-`@deprecated` is handled separately from passthrough slot tags. It fills the slot's `deprecated` JSON field, adds a Markdown badge, and emits `@deprecated` in the `.d.ts`. See [@deprecated](#deprecated).
-
-Put `@slot` / `@snippet` last in the block (description, optional extra tags, slot tag). Tags after `@slot` / `@snippet` in the same comment are not tied to that slot. Unknown tag names pass through as-is. Markdown docs render the description and these tags in the slot's **Description** column (newlines and tag boundaries become `<br />`), alongside TypeScript hover and JSON.
-
-**Example (default slot with `@example` and `@deprecated`):**
-
-````svelte
-<script>
-  /**
-   * Spread `props` onto a custom element.
-   * @example
-   * ```svelte
-   * <Item let:props>
-   *   <a {...props} href="/">Home</a>
-   * </Item>
-   * ```
-   * @deprecated Prefer the `link` snippet.
-   * @slot {{ props?: { class: string } }}
-   */
-</script>
-
-<slot props={{ class: "bx--link" }} />
-````
-
-#### Svelte 5 Snippet Compatibility
-
-For Svelte 5, `sveld` generates optional snippet props for all slots so consumers can use traditional slot syntax or `{#snippet}`.
-
-When parsing runes components, `sveld` maps `{@render ...}` calls back into the same slot metadata used for `<slot>`. Reserved snippet props like `children`, plus named snippet props from `{@render ...}`, live in `slots` metadata and generated snippet prop types, not duplicated in `props`.
-
-Positional snippet calls like `{@render row?.(item, index)}` stay typed props when the prop has an explicit type like `Snippet<[Item, number]>`. They are not turned into synthetic slot metadata.
-
-For slots with props (e.g., `let:prop`), the generated type uses a Snippet-compatible signature:
-
-```ts
-slotName?: (this: void, ...args: [{ prop: PropType }]) => void;
-```
-
-For slots without props:
-
-```ts
-slotName?: (this: void) => void;
-```
-
-**Why this signature?**
-
-- **`this: void`** blocks calling the snippet with a `this` context, matching Svelte's rule that snippets are pure render functions
-- **`...args: [Props]`** uses tuple spread for type-safe parameters. It accepts fixed-length tuples (like `[{ row: Row }]`) and rejects array types (like `Props[]`), matching Svelte's `Snippet<T>` type
-
-**Default slot (`children` prop):**
-
-The default slot generates an optional `children` snippet prop:
-
-```svelte
-<!-- Component with default slot that passes props -->
-<Dropdown {items} selectedId="1">
-  {#snippet children({ item, index })}
-    <span>{item.text} (#{index})</span>
-  {/snippet}
-</Dropdown>
-```
-
-Generated types:
-
-```ts
-type DropdownProps = {
-  items: Item[];
-  selectedId?: string;
-
-  // Default slot as children snippet prop
-  children?: (this: void, ...args: [{ item: Item; index: number }]) => void;
-};
-```
-
-**Named slots:**
-
-```svelte
-<!-- Using the generated types with Svelte 5 syntax -->
-<DataTable headers={headers} rows={rows}>
-  {#snippet cell({ cell, row })}
-    {#if cell.key === 'actions'}
-      <Button on:click={() => handleAction(row)}>Edit</Button>
-    {:else}
-      {cell.value}
-    {/if}
-  {/snippet}
-</DataTable>
-```
-
-Generated output includes both the snippet prop and the traditional slot definition:
-
-```ts
-type DataTableProps<Row> = {
-  // ... other props
-
-  // Snippet prop for Svelte 5 compatibility
-  cell?: (
-    this: void,
-    ...args: [
-      {
-        row: Row;
-        cell: DataTableCell<Row>;
-        rowIndex: number;
-        cellIndex: number;
-      },
-    ]
-  ) => void;
-
-  // Default slot as children prop
-  children?: (this: void) => void;
-};
-
-export default class DataTable<Row> extends SvelteComponentTyped<
-  DataTableProps<Row>,
-  {
-    /* events */
-  },
-  {
-    // Traditional slot definition (Svelte 3/4)
-    default: Record<string, never>;
-    cell: {
-      row: Row;
-      cell: DataTableCell<Row>;
-      rowIndex: number;
-      cellIndex: number;
-    };
-  }
-> {}
-```
-
-### `@event`
-
-Use the `@event` tag to type dispatched events. An event name is required and a description optional.
-
-In Svelte 5 runes components, callback props like `onclick` are props, not events. The `events` output stays reserved for dispatched events and legacy forwarded events. If a runes component documents `@event foo` and exposes a matching callback prop like `onfoo` without actually dispatching or forwarding `foo`, `sveld` aliases that documentation onto the callback prop instead of synthesizing an emitted event.
-
-Use `null` as the value if no event detail is provided.
-
-`sveld` infers events from `dispatch("name")` calls. When the dispatcher is passed to a function imported from a local module, as `helper(dispatch)` or `helper({ dispatch })` (a named or default import) or `helpers.open(dispatch)` (a namespace import, or a namespace another module re-exports with `export * as helpers from "./helpers.js"`), it reads that function too and picks up the events it dispatches:
-
-```js
-// dispatch-open-close.js
-export function createOpenCloseDispatcher(dispatch) {
-  return (open) => dispatch(open ? "open" : "close");
-}
-```
-
-```svelte
-<script>
-  import { createEventDispatcher } from "svelte";
-  import { createOpenCloseDispatcher } from "./dispatch-open-close.js";
-
-  const dispatch = createEventDispatcher();
-  // Types `open` and `close` as `CustomEvent<null>`
-  const notifyOpenChange = createOpenCloseDispatcher(dispatch);
-</script>
-```
-
-This happens when sveld builds the whole library (CLI, `sveld()`, or the Vite plugin), not when parsing a single component on its own. Each event name there must be a string literal, or a conditional between them. The detail is typed from a literal argument, and an object or array literal is typed member by member as for a dispatch in the component (`{ id: "a" }` is `{ id: string; }`); a member or argument the helper computes, including one of its own variables, is `any`, so add an `@event` tag to type it more precisely. When sveld can't follow the dispatcher (a package import, a local function, a computed event name, or a helper that passes the dispatcher on), it reports `sveld/dispatch-escapes`, and you document those events with `@event` tags.
-
-**Signature:**
-
-```js
-/**
- * Optional event description
- * @event {EventDetail} eventname [inline description]
- */
-```
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * Fired when a value is saved.
-   * @event {{ id: string }} save
-   */
-  let { onsave } = $props();
-</script>
-
-<button onclick={() => onsave?.({ id: "1" })}>Save</button>
-```
-
-**Svelte 5 Runes with dispatched events:**
-
-```svelte
-<script>
-  /**
-   * @event {{ key: string }} button:key
-   * @event {null} key - Fired when `key` changes.
-   */
-
-  let { key = "" } = $props();
-
-  import { createEventDispatcher } from "svelte";
-
-  const dispatch = createEventDispatcher();
-
-  $effect(() => {
-    dispatch("button:key", { key });
-    if (key) dispatch("key");
-  });
-</script>
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<script>
-  /**
-   * @event {{ key: string }} button:key
-   * @event {null} key - Fired when `key` changes.
-   */
-
-  export let key = "";
-
-  import { createEventDispatcher } from "svelte";
-
-  const dispatch = createEventDispatcher();
-
-  $: dispatch("button:key", { key });
-  $: if (key) dispatch("key");
-</script>
-```
-
-</details>
-
-Output is identical for both syntax modes.
-
-Output:
-
-```ts
-export default class Component extends SvelteComponentTyped<
-  ComponentProps,
-  {
-    "button:key": CustomEvent<{ key: string }>;
-    /** Fired when `key` changes. */ key: CustomEvent<null>;
-  },
-  Record<string, never>
-> {}
-```
-
-#### Detail inference without `@event`
-
-Without an `@event` tag or a typed dispatcher, `sveld` infers a dispatched event's detail type from the `dispatch()` call site itself:
-
-- A scalar literal argument narrows to its literal type: `dispatch("count", 5)` types the detail as `5`, not `number`. Use `@event` or a typed dispatcher (below) to widen it.
-- An object or array literal argument infers a structural type per field/element: `dispatch("save", { id })` types the detail as `{ id: string }` (resolving the `id` variable's own type), and `dispatch("items", [1, 2])` types it as `number[]`. Fields or elements sveld can't resolve fall back to `any` individually, not for the whole detail.
-- A variable, as the whole detail (`dispatch("count", count)`) or as a field or element, takes its JSDoc `@type` or TS annotation. Without one, it's typed from its initializer the way a prop default is: `let count = 0` and `let count = $state(0)` are `number`, `$state<Item[]>([])` is `Item[]`, and `$derived(total * 2)` is `number`. A literal widens to its primitive, since a `let` can be reassigned. A variable initialized from a call (`let roll = Math.random()`), a destructured binding without an annotation, or a function parameter or nested variable is `any`.
-- `$host().dispatchEvent(new CustomEvent("name", { detail }))` in a custom element types `detail` the same way.
-- An empty object literal (`dispatch("reset", {})`) types the detail as `Record<string, never>`. A spread or computed key (`{ ...state }`, `{ [key]: 1 }`) adds fields sveld can't name, so the detail becomes `Record<string, any>`, or keeps the named fields next to a `[key: string]: any` index signature (`{ id: number; [key: string]: any }`).
-
-#### Typed dispatchers
-
-`createEventDispatcher<T>()`'s generic argument (`lang="ts"`, or the JSDoc `/** @type {import('svelte').EventDispatcher<T>} */` cast form) works like an `@event` block for every member of `T`, including ones never actually dispatched in the file:
-
-```svelte
-<script lang="ts">
-  import { createEventDispatcher } from "svelte";
-
-  const dispatch = createEventDispatcher<{ save: { id: string }; cancel: null }>();
-</script>
-```
-
-`T` may also be a reference to a local `type`/`interface`. An `@event` tag for the same name still overrides the generic's detail type.
-
-#### Using `@property` for complex event details
-
-For events with complex object payloads, use `@property` to document individual fields. The main comment becomes the event description. See the [`@property`](#property) reference for the tag's valid contexts.
-
-This is the idiomatic way to describe each field of an event detail. An inline object literal such as `@event {{ items: string[]; added: string[] }} change` types the payload but cannot carry per-field descriptions, since a nested block comment would terminate the host JSDoc. Declare the detail with `@type {object}` and `@property` instead to document every field.
-
-**Signature:**
-
-```js
-/**
- * Event description
- * @event eventname
- * @type {object}
- * @property {Type} propertyName - Property description
- */
-```
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * Fired when the user submits the form
-   *
-   * @event submit
-   * @type {object}
-   * @property {string} name - The user's name
-   * @property {string} email - The user's email address
-   * @property {boolean} newsletter - Whether the user opted into the newsletter
-   */
-
-  let { name = "Jane Doe", email = "jane@example.com", newsletter = true } = $props();
-
-  import { createEventDispatcher } from "svelte";
-
-  const dispatch = createEventDispatcher();
-
-  function handleSubmit() {
-    dispatch("submit", { name, email, newsletter });
-  }
-</script>
-
-<button type="button" onclick={handleSubmit}>Submit</button>
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<script>
-  /**
-   * Fired when the user submits the form
-   *
-   * @event submit
-   * @type {object}
-   * @property {string} name - The user's name
-   * @property {string} email - The user's email address
-   * @property {boolean} newsletter - Whether the user opted into the newsletter
-   */
-
-  export let name = "Jane Doe";
-  export let email = "jane@example.com";
-  export let newsletter = true;
-
-  import { createEventDispatcher } from "svelte";
-
-  const dispatch = createEventDispatcher();
-
-  function handleSubmit() {
-    dispatch("submit", { name, email, newsletter });
-  }
-</script>
-
-<button type="button" on:click={handleSubmit}>Submit</button>
-```
-
-</details>
-
-Output is identical for both syntax modes.
-
-Output:
-
-```ts
-export default class Component extends SvelteComponentTyped<
-  ComponentProps,
-  {
-    /** Fired when the user submits the form */
-    submit: CustomEvent<{
-      /** The user's name */
-      name: string;
-      /** The user's email address */
-      email: string;
-      /** Whether the user opted into the newsletter */
-      newsletter: boolean;
-    }>;
-  },
-  Record<string, never>
-> {}
-```
-
-#### Optional properties in event details
-
-Like typedefs, you can mark event detail properties as optional with square brackets when they are not always in the payload.
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * Snowball event fired when throwing a snowball
-   *
-   * @event snowball
-   * @type {object}
-   * @property {boolean} isPacked - Indicates whether the snowball is tightly packed
-   * @property {number} speed - The speed of the snowball in mph
-   * @property {string} [color] - Optional color of the snowball
-   * @property {number} [density=0.9] - Optional density with default value
-   */
-
-  let { speed = 50 } = $props();
-
-  import { createEventDispatcher } from "svelte";
-
-  const dispatch = createEventDispatcher();
-
-  function throwSnowball() {
-    dispatch("snowball", {
-      isPacked: true,
-      speed,
-    });
-  }
-</script>
-
-<button type="button" onclick={throwSnowball}>Throw</button>
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<script>
-  /**
-   * Snowball event fired when throwing a snowball
-   *
-   * @event snowball
-   * @type {object}
-   * @property {boolean} isPacked - Indicates whether the snowball is tightly packed
-   * @property {number} speed - The speed of the snowball in mph
-   * @property {string} [color] - Optional color of the snowball
-   * @property {number} [density=0.9] - Optional density with default value
-   */
-
-  export let speed = 50;
-
-  import { createEventDispatcher } from "svelte";
-
-  const dispatch = createEventDispatcher();
-
-  function throwSnowball() {
-    dispatch("snowball", {
-      isPacked: true,
-      speed,
-    });
-  }
-</script>
-
-<button type="button" on:click={throwSnowball}>Throw</button>
-```
-
-</details>
-
-Output is identical for both syntax modes.
-
-Output:
-
-```ts
-export default class Component extends SvelteComponentTyped<
-  ComponentProps,
-  {
-    /** Snowball event fired when throwing a snowball */
-    snowball: CustomEvent<{
-      /** Indicates whether the snowball is tightly packed */
-      isPacked: boolean;
-      /** The speed of the snowball in mph */
-      speed: number;
-      /** Optional color of the snowball */
-      color?: string;
-      /** Optional density with default value @default 0.9 */
-      density?: number;
-    }>;
-  },
-  Record<string, never>
-> {}
-```
-
-#### Discriminated unions in event details
-
-When the event detail is a union (or any non-object shape), use `@type` to declare it directly. An explicit `@type` wins over `@property` tags, so the union is copied verbatim into the emitted `.d.ts` instead of being flattened into independent property unions. The only exception is `@type {object}`, which tells `sveld` to build the shape from `@property` tags (as shown above).
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * @event sort
-   * @type {{ key: null; direction: "none" } | { key: string; direction: "ascending" | "descending" }}
-   * Dispatched when a sortable column header would change the active sort.
-   */
-
-  import { createEventDispatcher } from "svelte";
-
-  const dispatch = createEventDispatcher();
-</script>
-```
-
-Output:
-
-```ts
-export default class Component extends SvelteComponentTyped<
-  ComponentProps,
-  {
-    /** Dispatched when a sortable column header would change the active sort. */
-    sort: CustomEvent<{ key: null; direction: "none" } | { key: string; direction: "ascending" | "descending" }>;
-  },
-  Record<string, never>
-> {}
-```
-
-Any free-text prose after the tags is attached to the event description, not to a property doc.
-
-### `@ignore` / `@internal`
-
-`@ignore` and `@internal` are equivalent aliases: either one excludes a prop, event, slot, typedef, module export, entry export, or context from every output — JSON, Markdown, `.d.ts`, and the Custom Elements Manifest. Use them for implementation details that would otherwise leak into the public API docs.
-
-The tag's position mirrors [`@deprecated`](#deprecated): before `@slot`/`@snippet`/`@typedef`/`@callback`, alongside the description, and after the `@event` line.
-
-```svelte
-<script>
-  /** The visible label. */
-  export let label = "";
-
-  /**
-   * Implementation detail; not part of the public API.
-   * @internal
-   */
-  export let debugId = "";
-
-  /**
-   * Fired when the value changes.
-   * @event {{ value: string }} change
-   */
-
-  /**
-   * Fired for internal diagnostics only.
-   * @event {{ reason: string }} debug
-   * @internal
-   */
-
-  /**
-   * @internal
-   * @slot {{}} debug-panel
-   */
-</script>
-```
-
-`debugId`, the `debug` event, and the `debug-panel` slot never appear in `COMPONENT_INDEX.md`, `COMPONENT_API.json`, the generated `.d.ts`, or the Custom Elements Manifest — as if they were never declared. Internally, the parser still records them (with an `internal: true` flag) on the raw parsed component; only `buildComponentApiDocument` — the shared step every writer runs through — filters them out, so a custom writer built on the raw parse result can still see them if it chooses to.
-
-For a context (`setContext(key, value)`), tag the JSDoc on the *value* variable, the same place its type annotation and description already live:
-
-```svelte
-<script>
-  /**
-   * @type {{ token: string }}
-   * @internal
-   */
-  let authContext = { token: "" };
-
-  setContext("auth", authContext);
-</script>
-```
-
-A whole inline object literal passed directly to `setContext` (no intermediate variable) has no JSDoc position of its own, so `@internal` isn't supported there. An individual property *inside* one can be marked `@internal`, though, as long as its value is an identifier carrying its own JSDoc:
-
-```svelte
-<script>
-  /**
-   * @type {string}
-   * @internal
-   */
-  let debugToken = "";
-
-  let publicUser = { name: "" };
-
-  setContext("session", { user: publicUser, debug: debugToken });
-</script>
-```
-
-Only the `debug` property is excluded from `session`'s generated shape; `user` and the context itself are unaffected.
-
-Because an internal member never appears in output, adding `@internal` to a previously-public prop, event, slot, or typedef is a breaking change for `--check` purposes (it disappears from the generated `.d.ts` just like an outright removal). Removing an already-`@internal` member, by contrast, is not breaking — it was never part of the committed public snapshot to begin with.
-
-### `@deprecated`
-
-Add `@deprecated` to a prop, event, slot, entry export, or exported accessor. An optional message after the tag can explain why or name a replacement.
-
-```svelte
-<script>
-  /**
-   * The visible label.
-   * @deprecated Use the `text` prop instead.
-   */
-  export let label = "";
-
-  /**
-   * Programmatically focus the field.
-   * @deprecated Focus the underlying element directly.
-   */
-  export function focus() {}
-
-  /**
-   * @event {{ value: string }} change
-   * @deprecated Listen for the native `input` event instead.
-   */
-
-  /**
-   * Badge content rendered next to the label.
-   * @deprecated Render the badge inline instead.
-   * @slot {{ count: number }} badge
-   */
-</script>
-```
-
-For slots, put `@deprecated` before the `@slot` / `@snippet` line, alongside the description and any other [extra tags](#extra-jsdoc-tags-before-slot). For events, put it after the `@event` line. For entry exports (see [Documenting Entry Exports](#documenting-entry-exports)), put it in the JSDoc directly above the `const`/`function`/`class`/`type`/`interface` declaration, same as a prop.
-
-Generated `.d.ts` files include an `@deprecated` JSDoc line so editors strike the symbol through. JSON adds a `deprecated` field (the message string, or `true` when the tag has no message). Markdown strikes through the name and adds a **Deprecated** badge with the message when present.
-
-```ts
-/**
- * The visible label.
- * @deprecated Use the `text` prop instead.
- */
-label?: string;
-```
-
-```json
-{ "name": "label", "deprecated": "Use the `text` prop instead." }
-```
-
-### `@since`
-
-`@since` records the version a prop, event, or slot was introduced. `sveld` does not validate or parse the version text — whatever follows the tag is copied through as-is.
-
-**Valid contexts:**
-
-- **Prop / module export** — captured as a structured tag: JSON adds a `tags: [{ "name": "since", "body": "..." }]` array on the prop (kept separate from `description`), the generated `.d.ts` emits `@since ...` as its own JSDoc line above `@default`, and the Markdown table's Description column appends `@since ...` after the description, same as slots.
-- **`@event`** — same structured behavior as props, but only when `@since` is placed **after** the `@event` line in the same comment block (matching the [`@deprecated`](#deprecated) rule for events). Placed before `@event`, it is silently dropped.
-- **`@slot` / `@snippet`** — placed before the `@slot`/`@snippet` line, alongside the description. Fully surfaced in JSON, `.d.ts`, *and* the Markdown table. See [extra tags before `@slot`](#extra-jsdoc-tags-before-slot).
-- **`@typedef`** — **not supported.** A `@since` before `@typedef` produces no output anywhere; it is silently dropped.
-- **`@component` comments** — passed through verbatim as part of the raw HTML comment text. See [@component comments](#component-comments).
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * A width prop.
-   * @since 1.2.0
-   * @type {number}
-   */
-  let { width = 0 } = $props();
-</script>
-```
-
-Output (`.d.ts`):
-
-```ts
-export type ScratchProps = {
-  /**
-   * A width prop.
-   * @since 1.2.0
-   * @default 0
-   */
-  width?: number;
-};
-```
-
-Output (JSON, relevant slice):
-
-```json
-{ "name": "width", "description": "A width prop.", "tags": [{ "name": "since", "body": "1.2.0" }] }
-```
-
-Output (Markdown props table Description column):
-
-```
-A width prop.<br />@since 1.2.0
-```
-
-### `@see`
-
-`@see` adds a reference link or citation. Like `@since`, `sveld` does not resolve or validate the target — it is free text.
-
-**Valid contexts:**
-
-- **Prop / module export** — `@see` is *not* one of the small set of tags `sveld` structures specially, so it is folded verbatim into the prop's `description` as an extra line (`@see ...`) rather than getting its own `tags` entry. Because it lives in `description`, it *does* show up everywhere `description` is used: JSON, `.d.ts`, and the Markdown table.
-- **`@event`** — **not supported in either position** (before or after `@event`). A `@see` tag near an `@event` block is silently dropped in both JSON and `.d.ts`.
-- **`@slot` / `@snippet`** — placed before `@slot`/`@snippet`, alongside the description: fully supported in JSON, `.d.ts`, and Markdown, same as `@since`. See [extra tags before `@slot`](#extra-jsdoc-tags-before-slot).
-- **`@typedef`** — **not supported.** Dropped silently, same as `@since`.
-- **`@component` comments** — passed through verbatim, same as `@since`.
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * A width prop.
-   * @see https://example.com/width-docs
-   * @type {number}
-   */
-  let { width = 0 } = $props();
-</script>
-```
-
-Output (`.d.ts`):
-
-```ts
-export type ScratchProps = {
-  /**
-   * A width prop.
-   * @see https://example.com/width-docs
-   * @default 0
-   */
-  width?: number;
-};
-```
-
-Output (Markdown props table Description column):
-
-```
-A width prop.<br />@see https://example.com/width-docs
-```
-
-### `@link`
-
-`{@link target}` (optionally `{@link target|display text}`) is an inline JSDoc tag used inside prose, not a block-level tag like the others on this page. `sveld`'s comment parser only treats a *line* as starting a new tag when it begins with `@` — `{@link ...}` always starts with `{`, so it's never intercepted. It is always literal text.
-
-**Valid contexts:** anywhere free-form description text is read — prop and module export descriptions, event descriptions, slot descriptions, entry export descriptions, typedef descriptions, `@component` HTML comments, and `@example` bodies. `sveld` never resolves or validates the target. JSON `description` and `.d.ts` JSDoc always keep the tag verbatim. **Markdown is the one exception:** in a prop, event, slot, or entry export's Description table cell, `{@link target|text}` / `{@link target}` is rewritten to a Markdown link, `[text](target)` / `[target](target)`, except inside a fenced code block. Typedef descriptions (rendered as a `.d.ts`-style code block) and `@component` comments keep the tag literal in Markdown too, since neither goes through the table-cell renderer.
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * The element's width in pixels. See {@link https://example.com/width|width docs}.
-   * @type {number}
-   */
-  let { width = 0 } = $props();
-</script>
-```
-
-Output (`.d.ts`):
-
-```ts
-export type ScratchProps = {
-  /**
-   * The element's width in pixels. See {@link https://example.com/width|width docs}.
-   * @default 0
-   */
-  width?: number;
-};
-```
-
-The same literal string appears unchanged in JSON `description`. The Markdown table's Description column instead shows: `The element's width in pixels. See [width docs](https://example.com/width).`
-
-### `@example`
-
-`@example` has two related uses: as a plain JSDoc tag whose body is copied into generated output, and — with `checkExamples: true` — as input to sveld's compile-checker for plain TS/JS example code. This section covers the tag itself; see [Compile-checked `@example` blocks (`checkExamples`)](#compile-checked-example-blocks-checkexamples) for the type-checking feature.
-
-`@example` shares its underlying mechanism with `@since` (both are in the small set of tags `sveld` treats as structured "IDE passthrough" tags), so the valid contexts are the same:
-
-- **Prop / module export (including functions)** — structured `tags` entry in JSON, its own `@example` block in `.d.ts`, and appended to the Markdown table's Description column, same as `@since`.
-- **`@event`** — only when placed **after** the `@event` line in the same block, same rule as `@since`.
-- **`@slot` / `@snippet`** — placed before `@slot`/`@snippet`: fully supported in JSON, `.d.ts`, and Markdown. See [extra tags before `@slot`](#extra-jsdoc-tags-before-slot).
-- **`@typedef`** — **not supported**, dropped silently, same as `@since`.
-- **`@component` comments** — passed through verbatim; this is already how the [`@component` comments](#component-comments) example on this page uses `@example`.
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * Formats a value.
-   * @param {string} value
-   * @returns {string}
-   * @example
-   * ```js
-   * formatValue("ok");
-   * ```
-   */
-  export function formatValue(value) {
-    return value;
-  }
-</script>
-```
-
-Output (`.d.ts`):
-
-```ts
-/**
- * Formats a value.
- * @example
- * ```js
- * formatValue("ok");
- * ```
- */
-formatValue: (value: string) => string;
-```
-
-`@param`/`@returns` are consumed into the function's type signature rather than kept as separate JSDoc lines.
-
-In Markdown table cells, a fenced block (in an `@example` body or anywhere in a description) renders as `<pre><code>` with one `<br />` per line, since a table row can't span lines. `<pre>` keeps the indentation, and GitHub renders it as a monospaced block inside the cell. The example above shows up in the Description column as:
-
-```
-Formats a value.<br />@example <pre><code>formatValue("ok");</code></pre>
-```
-
-`llms-full.txt` instead puts `(code below)` in the cell and prints the code after the table as a regular multi-line fenced block, under a ``Code for `formatValue`:`` line.
-
-Output (Markdown props table Description column, newlines rendered as `<br />`):
-
-````
-Formats a value.<br />@example ```js<br /> formatValue("ok");<br /> ```
-````
-
-### Context API
-
-`sveld` generates TypeScript definitions for Svelte's `setContext`/`getContext` by extracting types from JSDoc on context values.
-
-#### How it works
-
-When you call `setContext` in a component, `sveld`:
-
-1. Detects the `setContext` call
-2. Resolves the context key (see [Supported context keys](#supported-context-keys))
-3. Finds JSDoc `@type` annotations on the variables being passed
-4. Generates a TypeScript type export for the context
-
-#### Supported context keys
-
-The key becomes the `{PascalCase}Context` type name. `sveld` can resolve:
-
-| Key form | Example | Generated type |
-| --- | --- | --- |
-| String literal | `setContext("simple-modal", …)` | `SimpleModalContext` |
-| Static template literal | `` setContext(`simple-modal`, …) `` | `SimpleModalContext` |
-| `const`-bound string | `const KEY = "simple-modal";`<br>`setContext(KEY, …)` | `SimpleModalContext` |
-| `Symbol()` / `Symbol.for()` | `setContext(Symbol("tabs"), …)` | `TabsContext` |
-| Imported `export const` string | `import { KEY } from "./keys.js";`<br>`setContext(KEY, …)` | `SimpleModalContext` |
-| Namespace-imported `export const` string | `import * as keys from "./keys.js";`<br>`setContext(keys.KEY, …)` | `SimpleModalContext` |
-
-Characters that can't appear in a TypeScript identifier are dropped and start a new PascalCase word, and a name starting with a digit gets a leading `_`: `"@scope/ctx"` becomes `ScopeCtxContext` and `"123"` becomes `_123Context`.
-
-`const` identifiers are followed up to 5 levels deep (`const A = "x"; const B = A;`). Only `const` bindings count. `let`, `var`, and props are skipped because they can change at runtime.
-
-Symbol keys take their name from the description: `Symbol("tabs")` and `Symbol.for("tabs")` both become `TabsContext`. For `const ModalKey = Symbol()` with no description, the binding name wins: `ModalKeyContext`.
-
-An imported key (named, or read off a namespace import, including one another module re-exports with `export * as keys from "./keys.js"`) is read from its module, following re-exports, when that module is a relative `.js`/`.ts` file declaring it as `export const KEY = "simple-modal"` (or a static template literal). This works when sveld builds a whole library (CLI, `sveld()`, or the Vite plugin), not when parsing a single component on its own.
-
-Anything else (dynamic identifiers, `let` exports, template interpolation, other function calls) records a `sveld/context-key-unresolved` diagnostic. No context type is generated.
-
-#### Example
-
-**Modal.svelte**
-
-```svelte
-<script>
-  import { setContext } from "svelte";
-
-  /**
-   * Close the modal
-   * @type {() => void}
-   */
-  const close = () => {
-    // Close logic
-  };
-
-  /**
-   * Open the modal with content
-   * @type {(component: any, props?: any) => void}
-   */
-  const open = (component, props) => {
-    // Open logic
-  };
-
-  setContext("simple-modal", { open, close });
-
-  let { children } = $props();
-</script>
-
-<div class="modal">
-  {@render children?.()}
-</div>
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<script>
-  import { setContext } from "svelte";
-
-  /**
-   * Close the modal
-   * @type {() => void}
-   */
-  const close = () => {
-    // Close logic
-  };
-
-  /**
-   * Open the modal with content
-   * @type {(component: any, props?: any) => void}
-   */
-  const open = (component, props) => {
-    // Open logic
-  };
-
-  setContext("simple-modal", { open, close });
-</script>
-
-<div class="modal">
-  <slot />
-</div>
-```
-
-</details>
-
-Output is identical for both syntax modes.
-
-**Generated TypeScript definition:**
-
-```ts
-export type SimpleModalContext = {
-  /** Open the modal with content */
-  open: (component: any, props?: any) => void;
-  /** Close the modal */
-  close: () => void;
-};
-
-export type ModalProps = {};
-
-export default class Modal extends SvelteComponentTyped<
-  ModalProps,
-  Record<string, any>,
-  { default: Record<string, never> }
-> {}
-```
-
-**Consumer usage:**
-
-```svelte
-<script>
-  import { getContext } from 'svelte';
-  import type { SimpleModalContext } from 'modal-library/Modal.svelte';
-
-  const { close, open } = getContext<SimpleModalContext>('simple-modal');
-</script>
-
-<button on:click={close}>Close</button>
-```
-
-#### Explicitly typing contexts
-
-There are several ways to type contexts:
-
-**Option 1: Inline JSDoc on variables (recommended)**
-
-```svelte
-<script>
-  import { setContext } from 'svelte';
-
-  /**
-   * @type {() => void}
-   */
-  const close = () => {};
-
-  setContext('modal', { close });
-</script>
-```
-
-**Option 2: Using @typedef for complex types**
-
-```svelte
-<script>
-  import { setContext } from 'svelte';
-
-  /**
-   * @typedef {object} TabData
-   * @property {string} id
-   * @property {string} label
-   * @property {boolean} [disabled]
-   */
-
-  /**
-   * @type {(tab: TabData) => void}
-   */
-  const addTab = (tab) => {};
-
-  setContext('tabs', { addTab });
-</script>
-```
-
-**Option 3: Passing a typed variable as the whole value**
-
-```svelte
-<script>
-  import { setContext } from 'svelte';
-
-  /**
-   * Modal controls
-   * @type {import("./types").ModalAPI}
-   */
-  const modalAPI = {
-    open: () => {},
-    close: () => {}
-  };
-
-  setContext('modal', modalAPI);
-</script>
-```
-
-`getContext('modal')` returns `modalAPI` itself, so the context type is the variable's type, and the variable's description documents it:
-
-```ts
-/**
- * Modal controls
- */
-export type ModalContext = import("./types").ModalAPI;
-```
-
-When the variable's type is an object type literal (`@type {{ open: () => void }}` or `const api: { open: () => void } = ...`), its members become the context type's members instead. An untyped `const` holding an object literal is described from that literal, as with `{ ...api }`. Any other untyped variable is typed from its initializer the way a prop default is (`let count = $state(0)` or `let count = 0` gives `number`, `$state<Item[]>([])` gives `Item[]`), and one sveld can't type gives `any` with a `sveld/context-any-type` diagnostic. In `COMPONENT_API.json`, a context typed this way has a `type` field holding the whole type and an empty `properties` array.
-
-**Option 4: Direct object literal with inline functions**
-
-```svelte
-<script>
-  import { setContext } from 'svelte';
-
-  // sveld infers basic function signatures
-  setContext('modal', {
-    open: (component, props) => {}, // Inferred as (arg, arg) => any
-    close: () => {}                 // Inferred as () => any
-  });
-</script>
-```
-
-> Inline functions without `@type` annotations get generic inferred signatures. Add explicit JSDoc when you care about the shape.
-
-#### Notes
-
-- 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, either local or an imported `export const`. Dynamic expressions (runtime identifiers, template interpolation, other function calls) are skipped with a `sveld/context-key-unresolved` diagnostic.
-- Variables passed to `setContext` should have JSDoc `@type` annotations (or native TypeScript types) for accurate types. Without one, a variable is typed from its initializer the way a prop default is, unwrapping `$state`, `$state.raw`, and `$derived` (a rune's type argument, as in `$state<number>(0)`, wins). A variable passed as the whole value (`setContext("modal", modalAPI)`) types the context as that variable's type; one passed inside an object literal (`setContext("modal", { modalAPI })`) becomes a property
-- The value must be an object literal or a variable. Any other expression (such as `setContext("store", writable(0))`) is skipped with a `sveld/context-value-unresolved` diagnostic.
-- The generated type name follows the pattern: `{PascalCase}Context`. Separators (underscores and any character that can't appear in an identifier, such as hyphens, dots, colons, slashes, `@`, and spaces) are stripped and each segment is capitalized. A name starting with a digit gets a leading `_`:
-  | Context Key | Generated Type Name |
-  | --- | --- |
-  | `"simple-modal"` | `SimpleModalContext` |
-  | `"user_settings"` | `UserSettingsContext` |
-  | `"Carbon.Modal"` | `CarbonModalContext` |
-  | `"Carbon:Modal"` | `CarbonModalContext` |
-  | `"app/modal"` | `AppModalContext` |
-  | `"My Context"` | `MyContextContext` |
-  | `"@scope/ctx"` | `ScopeCtxContext` |
-  | `"123"` | `_123Context` |
-  | `"Tabs"` | `TabsContext` |
-- If no type annotation is found, the type defaults to `any` with a warning
-
-### `@restProps`
-
-`sveld` can detect inline HTML elements that `$$restProps` is forwarded to. It cannot infer the underlying element for instantiated components.
-
-Use `@restProps` to name the element tags `$$restProps` is forwarded to.
-
-**Signature:**
-
-```js
-/**
- * Single element
- * @restProps {tagname}
- *
- * Multiple elements
- * @restProps {tagname-1 | tagname-2 | tagname-3}
- */
-```
-
-**Example:**
-
-```svelte
-<script>
-  import Button from "./Button.svelte";
-
-  /** @restProps {h1 | button} */
-  let { edit = false, children, ...restProps } = $props();
-</script>
-
-{#if edit}
-  <Button {...restProps} />
-{:else}
-  <h1 {...restProps}>
-    {@render children?.()}
-  </h1>
-{/if}
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<script>
-  /** @restProps {h1 | button} */
-  export let edit = false;
-
-  import Button from "./Button.svelte";
-</script>
-
-{#if edit}
-  <Button {...$$restProps} />
-{:else}
-  <h1 {...$$restProps}><slot /></h1>
-{/if}
-```
-
-</details>
-
-### `@extendProps`
-
-When a component wraps another, use `@extendProps` to extend generated props.
-
-> `@extends` works as an alias, but prefer `@extendProps` to avoid clashing with standard JSDoc `@extends` for class inheritance.
-
-**Signature:**
-
-```js
-/**
- * @extendProps {<relative path to component>} ComponentProps
- */
-```
-
-**Example:**
-
-```js
-/** @extendProps {"./Button.svelte"} ButtonProps */
-
-export const secondary = true;
-
-import Button from "./Button.svelte";
-```
-
-The named interface must match the target's generated props type name exactly — the default `<Name>Props`, or whatever [`typesOptions.typeNames`](#typesoptionstypenames) templates it to.
-
-### `@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
-<script lang="ts" generics="Row extends DataTableRow = any"></script>
-```
-
-`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):
-
-```js
-/**
- * @template {Constraint} [Name=Default]
- */
-```
-
-**Example:**
-
-```js
-/**
- * @template {DataTableRow} [Row=DataTableRow]
- */
-```
-
-**Component example:**
-
-```svelte
-<script>
-  /**
-   * @typedef {{ id: string | number; [key: string]: any; }} DataTableRow
-   * @typedef {Exclude<keyof Row, "id">} DataTableKey<Row>
-   * @typedef {{ key: DataTableKey<Row>; value: string; }} DataTableHeader<Row=DataTableRow>
-   * @template {DataTableRow} [Row=DataTableRow]
-   */
-
-  let {
-    /** @type {ReadonlyArray<DataTableHeader<Row>>} */
-    headers = [],
-    /** @type {ReadonlyArray<Row>} */
-    rows = [],
-    children,
-  } = $props();
-</script>
-
-{@render children?.({ headers, rows })}
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<script>
-  /**
-   * @typedef {{ id: string | number; [key: string]: any; }} DataTableRow
-   * @typedef {Exclude<keyof Row, "id">} DataTableKey<Row>
-   * @typedef {{ key: DataTableKey<Row>; value: string; }} DataTableHeader<Row=DataTableRow>
-   * @template {DataTableRow} [Row=DataTableRow]
-   */
-
-  /** @type {ReadonlyArray<DataTableHeader<Row>>} */
-  export let headers = [];
-
-  /** @type {ReadonlyArray<Row>} */
-  export let rows = [];
-</script>
-
-<slot {headers} {rows} />
-```
-
-</details>
-
-Output is identical for both syntax modes.
-
-Generated output looks like this:
-
-```ts
-export type ComponentProps<Row extends DataTableRow = DataTableRow> = {
-  headers?: ReadonlyArray<DataTableHeader<Row>>;
-  rows?: ReadonlyArray<Row>;
-};
-
-export default class Component<
-  Row extends DataTableRow = DataTableRow,
-> extends SvelteComponentTyped<
-  ComponentProps<Row>,
-  Record<string, any>,
-  Record<string, any>
-> {}
-```
-
-For multiple generics, use separate `@template` tags:
-
-```js
-/**
- * @template {DataTableRow} [Row=DataTableRow]
- * @template {DataTableRow} [Header=DataTableRow]
- */
-```
-
-```ts
-export type ComponentProps<
-  Row extends DataTableRow = DataTableRow,
-  Header extends DataTableRow = DataTableRow,
-> = { ... };
-
-export default class Component<
-  Row extends DataTableRow = DataTableRow,
-  Header extends DataTableRow = DataTableRow,
-> extends SvelteComponentTyped<
-  ComponentProps<Row, Header>,
-  Record<string, any>,
-  Record<string, any>
-> {}
-```
-
-### `@generics`
-
-As an alternative to `@template`, sveld supports `@generics`. Unlike `@template`, which [JSDoc/TypeScript support officially](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#template), `@generics` is sveld-specific. The syntax can be easier to read because the full constraint is inline:
-
-```js
-/**
- * @generics {Row extends DataTableRow = DataTableRow} Row
- */
-```
-
-This is equivalent to:
-
-```js
-/**
- * @template {DataTableRow} [Row=DataTableRow]
- */
-```
-
-For multiple generics, use a single `@generics` tag with comma-separated names:
-
-```js
-/**
- * @generics {Row extends DataTableRow = DataTableRow, Header extends DataTableRow = DataTableRow} Row,Header
- */
-```
-
-### `@component` comments
-
-The Svelte Language Server supports component-level comments through the following syntax: `<!-- @component [comment] -->`.
-
-`sveld` copies these over to the exported default component in the TypeScript definition.
-
-**Example:**
-
-```svelte
-<!-- @component
-@example
-<Button>
-  Text
-</Button>
--->
-<script>
-  let { children } = $props();
-</script>
-
-<button>
-  {@render children?.()}
-</button>
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<!-- @component
-@example
-<Button>
-  Text
-</Button>
--->
-<button>
-  <slot />
-</button>
-```
-
-</details>
-
-Output is identical for both syntax modes.
-
-Output:
-
-```ts
-/**
- * @example
- * <Button>
- *   Text
- * </Button>
- */
-export default class Button extends SvelteComponentTyped<
-  ButtonProps,
-  Record<string, any>,
-  { default: Record<string, never> }
-> {}
-```
-
-### Accessor Props
-
-Exported functions and consts become accessor props in generated TypeScript definitions. Use `@type` for function signatures, or `@param` and `@returns` (or `@return`) for richer docs.
-
-`@type` wins over `@param`/`@returns` when both are present.
-
-**Signature:**
-
-```js
-/**
- * Function description
- * @param {Type} paramName - Parameter description
- * @param {Type} [optionalParam] - Optional parameter
- * @returns {ReturnType} Return value description
- */
-```
-
-**Example:**
-
-```svelte
-<script>
-  /**
-   * @typedef {object} NotificationData
-   * @property {string} [id] - Optional id for deduplication
-   * @property {"error" | "info" | "success"} [kind]
-   */
-
-  let { children } = $props();
-
-  /**
-   * Add a notification to the queue.
-   * @param {NotificationData} notification
-   * @returns {string} The notification id
-   */
-  export function add(notification) {
-    const id = notification.id ?? "id";
-    return id;
-  }
-
-  /**
-   * Remove a notification by id.
-   * @param {string} id
-   * @returns {boolean} True if the notification was found and removed
-   */
-  export function remove(id) {
-    return true;
-  }
-
-  /**
-   * Get notification count.
-   * @returns {number} The number of notifications
-   */
-  export function getCount() {
-    return 0;
-  }
-</script>
-
-<div>
-  {@render children?.()}
-</div>
-```
-
-<details>
-<summary>Svelte 3/4 (legacy) syntax</summary>
-
-```svelte
-<script>
-  /**
-   * @typedef {object} NotificationData
-   * @property {string} [id] - Optional id for deduplication
-   * @property {"error" | "info" | "success"} [kind]
-   */
-
-  /**
-   * Add a notification to the queue.
-   * @param {NotificationData} notification
-   * @returns {string} The notification id
-   */
-  export function add(notification) {
-    const id = notification.id ?? "id";
-    return id;
-  }
-
-  /**
-   * Remove a notification by id.
-   * @param {string} id
-   * @returns {boolean} True if the notification was found and removed
-   */
-  export function remove(id) {
-    return true;
-  }
-
-  /**
-   * Get notification count.
-   * @returns {number} The number of notifications
-   */
-  export function getCount() {
-    return 0;
-  }
-</script>
-```
-
-</details>
-
-Output is identical for both syntax modes.
-
-Output:
-
-```ts
-export type NotificationData = {
-  /** Optional id for deduplication */
-  id?: string;
-  kind?: "error" | "info" | "success";
-};
-
-export type ComponentProps = Record<string, never>;
-
-export default class Component extends SvelteComponentTyped<
-  ComponentProps,
-  Record<string, any>,
-  Record<string, never>
-> {
-  /**
-   * Add a notification to the queue.
-   */
-  add: (notification: NotificationData) => string;
-
-  /**
-   * Remove a notification by id.
-   */
-  remove: (id: string) => boolean;
-
-  /**
-   * Get notification count.
-   */
-  getCount: () => number;
-}
-```
-
-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`.
-
-The Markdown writer marks the same exports (a `const`, or a real function declaration) with Kind `accessor` in the Props table, instead of their raw `const`/`function` kind, matching the `.d.ts` output above.
-
-## 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.
-
-**`sveld: cannot resolve "..." from ...`.** An `export *` or a named re-export points at a module or path alias that doesn't resolve to a file on disk. Fix the specifier, or check the tsconfig/jsconfig `paths` entry it's supposed to match. This exits `1`; see [Exit codes](#exit-codes).
-
-**A path alias (`$lib`, `@components`, ...) isn't picked up.** sveld only reads aliases from `compilerOptions.paths` in the nearest `tsconfig.json` or `jsconfig.json`, found by walking up from the file doing the importing. Vite/SvelteKit alias config (`vite.config.*`, `svelte.config.*`) is not read directly — add the same aliases to `paths` so both tools agree. When a pattern has more than one mapping (`"$lib/*": ["./src/lib/*", "./lib/*"]`), sveld tries them in order and uses the first one that exists on disk, falling back to the first mapping if none do; among multiple matching patterns, the one with the longest non-wildcard prefix wins, regardless of declaration order (matching `tsc`).
+- Node 22 or later, or Bun. sveld is ESM-only.
+- A `sveld.config.ts` needs a runtime that strips TypeScript: Bun, or Node 22.18+ / 23.6+.
+- The optional [`checkExamples`](docs/ci.md#checking-example-blocks) check for TS/JS examples needs `typescript` 7+ and a `tsconfig.json`. Nothing else loads TypeScript.
+- Your installed Svelte version doesn't affect parsing. sveld parses with [sveast](https://github.com/metonym/sveast), kept in parity with `svelte/compiler`.
 
 ## Contributing
 
-See [contributing guidelines](CONTRIBUTING.md).
+See the [contributing guidelines](CONTRIBUTING.md).
 
 ## License