sveld 0.37.2 → 0.37.4

package/README.md

@@ -302,7 +302,7 @@ Without `resolveTypes`, JSON lists no props. With it, each field shows up with `
 
 ### 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.
+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 });
@@ -435,7 +435,8 @@ Every diagnostic carries a stable, namespaced `code` (`"sveld/<kind>"`) alongsid
 | `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/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 instead of re-exporting an import or a binding from another file; sveld only resolves exports of a local declaration. |
+| `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. |
+| `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. |
@@ -443,12 +444,14 @@ Every diagnostic carries a stable, namespaced `code` (`"sveld/<kind>"`) alongsid
 | `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. |
 
 #### 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`, `rest-props-unresolved`, `context-duplicate-key`, `spread-unresolved`, `export-unresolved`, `extend-props-duplicate`, `extend-props-override`, `jsdoc-unknown-tag`, `typedef-duplicate`, `property-duplicate`, `generics-conflict`, `jsdoc-tag-dropped` — a type fell back to `any`). 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:
+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`, `rest-props-unresolved`, `context-duplicate-key`, `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` — a type fell back to `any`). 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
@@ -505,8 +508,9 @@ A bare `@sveld-ignore` (no code) suppresses every diagnostic for that symbol.
 
 - 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) and [`checkExamples`](#compile-checked-example-blocks-checkexamples) are optional and need `typescript` 7 or later (which provides `typescript/unstable/async`) plus a `tsconfig.json`. Everything else, including `.d.ts` generation, is AST-only and never loads TypeScript. If either 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.
+- [`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
 
@@ -592,7 +596,7 @@ 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`, `--quiet`, `--stdout`, `--format`. The camelCase spellings `--resolveTypes` and `--checkExamples` still work as deprecated aliases for compatibility with existing scripts. `--entry`, `--cache`, `--check`, and `--types-format` 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 `--entry` and `--types-format` report a usage error naming the flag. Boolean flags (`--json`, `--glob`, `--strict`, and the like) never consume a following argument. An unrecognized flag (e.g. `--markdwon`) prints `Unknown flag: --markdwon` to `stderr`, exits `1`, and skips generation; when a close match exists it appends a suggestion, e.g. `Unknown flag: --markdwon Did you mean --markdown?`. sveld takes no positional arguments, so any non-flag argument errors the same way.
+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 `Unknown flag: --markdwon` to `stderr`, exits `1`, and skips generation; when a close match exists it appends a suggestion, e.g. `Unknown flag: --markdwon 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.
 
@@ -923,6 +927,13 @@ The `svelte` condition lets bundlers that understand it (Vite, Rollup, webpack v
   - **`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.
@@ -990,6 +1001,390 @@ 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`) are real runtime exports and are always emitted as exports, regardless of `exportTypes`.
+
+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; 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",
+  },
+});
+```
+
+`@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 already declares — a
+typedef, a context type, a local `type`/`interface`, or its `Props`/`Exports` type name) 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.
@@ -2274,6 +2669,16 @@ function render(value: unknown, props: ComponentProps) {
 
 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.
+
+```js
+/**
+ * @typedef {object} Config
+ * @property {number} itemHeight Height of each item in pixels, used for
+ *   virtualization math.
+ */
+```
+
 ### `@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`.
@@ -3509,6 +3914,8 @@ 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"`: