sveld 0.37.6 → 0.37.8

package/README.md

@@ -308,7 +308,7 @@ Parsed output is written to disk and reused when the source file has not changed
 await sveld({ json: true });
 ```
 
-By default this writes to `node_modules/.cache/sveld/parse-cache.json`. Pass a string to use a different location, e.g. `cache: ".cache/sveld.json"`, or `cache: false` to disable it. Also available as `--cache` / `--cache=<path>` / `--cache=false` on the CLI.
+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.
 
@@ -435,9 +435,10 @@ Every diagnostic carries a stable, namespaced `code` (`"sveld/<kind>"`) alongsid
 | `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 `export const` imported from a relative module as the `setContext` key; otherwise the context is left out of every output. |
+| `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. |
+| `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. |
@@ -450,10 +451,12 @@ Every diagnostic carries a stable, namespaced `code` (`"sveld/<kind>"`) alongsid
 | `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`, `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:
+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
@@ -808,6 +811,7 @@ It covers parsing one component's source and rendering that result to any output
 import {
   asNormalizedPath,
   ComponentParser,
+  finalizeWithoutCrossFileResolution,
   buildComponentApiDocument,
   writeMarkdownCore,
   writeTsDefinition,
@@ -817,7 +821,10 @@ import {
 const parser = new ComponentParser();
 const moduleName = "Button";
 const filePath = "Button.svelte";
-const parsed = parser.parseSvelteComponent(source, { moduleName, filePath });
+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.
@@ -839,6 +846,8 @@ const cem = buildCustomElementsManifest(components, {
 });
 ```
 
+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).
@@ -1057,7 +1066,23 @@ typesOptions: {
 
 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`.
+`<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`.
 
@@ -1086,7 +1111,7 @@ sveld({
 + 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"`).
+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).
 
@@ -1147,6 +1172,8 @@ sveld({
 });
 ```
 
+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.
@@ -1313,8 +1340,10 @@ It leaves alone:
 - `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
+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.
@@ -1461,7 +1490,7 @@ Nested barrels are followed too: `export { X } from "./dir"`, where `./dir/index
 
 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). When two different modules export the same name (most commonly via `export * from "./a"; export * from "./b"`), `sveld` keeps whichever was declared first and prints a warning; it does not silently pick one or emit both.
+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
 
@@ -1538,7 +1567,8 @@ interface ComponentDocApi {
 interface ComponentProp {
   name: string;
   localName?: string;
-  kind: "let" | "const" | "function";
+  // "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";
@@ -1557,6 +1587,23 @@ interface ComponentProp {
   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;
 }
 
@@ -1689,7 +1736,7 @@ With that in place:
 
 ## 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`.
+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({
@@ -1879,6 +1926,8 @@ 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.
@@ -2128,6 +2177,24 @@ By default, `sveld` infers the `@default` value from the prop's initializer and
 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:
@@ -2191,7 +2258,7 @@ 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 resolves when the imported module (followed through re-exports) declares it as an `export const` with a string, number, boolean, or static template literal:
+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>
@@ -2691,7 +2758,7 @@ 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.
+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
 /**
@@ -3013,7 +3080,7 @@ In Svelte 5 runes components, callback props like `onclick` are props, not 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 })`, it reads that function too and picks up the events it dispatches:
+`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
@@ -3033,7 +3100,7 @@ export function 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 is `any` otherwise, 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.
+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:**
 
@@ -3124,6 +3191,9 @@ Without an `@event` tag or a typed dispatcher, `sveld` infers a dispatched event
 
 - 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
 
@@ -3585,7 +3655,7 @@ A width prop.<br />@see https://example.com/width-docs
 
 `{@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)`. 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.
+**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:**
 
@@ -3650,15 +3720,23 @@ Output (`.d.ts`):
 /**
  * Formats a value.
  * @example
- *  ```js
- *  formatValue("ok");
- *  ```
+ * ```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 />`):
 
 ````
@@ -3689,12 +3767,15 @@ The key becomes the `{PascalCase}Context` type name. `sveld` can resolve:
 | `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 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.
+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.
 
@@ -3840,14 +3921,15 @@ There are several ways to type contexts:
 </script>
 ```
 
-**Option 3: Referencing imported types**
+**Option 3: Passing a typed variable as the whole value**
 
 ```svelte
 <script>
   import { setContext } from 'svelte';
 
   /**
-   * @type {typeof import("./types").ModalAPI}
+   * Modal controls
+   * @type {import("./types").ModalAPI}
    */
   const modalAPI = {
     open: () => {},
@@ -3858,6 +3940,17 @@ There are several ways to type contexts:
 </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
@@ -3876,9 +3969,10 @@ There are several ways to type contexts:
 
 #### Notes
 
-- Context keys must be statically resolvable: a string literal, a static template literal, a `const`-bound string (local or an imported `export const`), or a `Symbol()` / `Symbol.for()` call with a static description. 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 for accurate types
-- The generated type name follows the pattern: `{PascalCase}Context`. Separators (hyphens, underscores, dots, colons, slashes, spaces) are stripped and each segment is capitalized:
+- Context 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` |
@@ -3887,6 +3981,8 @@ There are several ways to type contexts:
   | `"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
 

package/lib/browser.d.ts

@@ -42,13 +42,23 @@ interface PendingConstDefaultCandidate {
     location: "props" | "moduleExports";
     importSource: string;
     importedName: string;
+    /** Members read off the import, through namespace exports: `["DELAY"]` for `C.timing.DELAY`. */
+    members?: string[];
 }
 
 interface PendingContextKeyCandidate {
     importSource: string;
     importedName: string;
+    /** Members read off the import, through namespace exports: `["THEME"]` for `ns.keys.THEME`. */
+    members?: string[];
+    /** See {@link ComponentContext.type}. */
+    type?: string;
     properties: ComponentContextProp[];
     description?: string;
+    /** See {@link ComponentContext.hasUnresolvedSpread}. */
+    hasUnresolvedSpread?: boolean;
+    /** See {@link ComponentContext.internal}. */
+    internal?: boolean;
     /** Source range of the `setContext(...)` call, when available. */
     source?: SourceRange;
 }
@@ -56,6 +66,8 @@ interface PendingContextKeyCandidate {
 interface PendingDispatchEscapeCandidate {
     importSource: string;
     importedName: string;
+    /** Members read off the import, through namespace exports: `["helper"]` for `ns.helper`. */
+    members?: string[];
     /** Callee as written, for messages. */
     calleeText: string;
     /** Local name of the `createEventDispatcher()` result. */
@@ -74,6 +86,8 @@ interface ParsedComponentTypeScriptMetadata {
     canonicalPropsType?: string;
     canonicalPropNames: string[];
     localTypeDeclarations: string[];
+    /** Types the module script exports (`export interface Item`), emitted with `export`. */
+    moduleTypeDeclarations?: string[];
     typeImportStatements: string[];
     /**
      * Whether `canonicalPropsType` mentions one of the component's own
@@ -95,6 +109,11 @@ interface ParsedComponentTypeScriptMetadata {
      * imported functions: `generateBundle` keeps those the functions don't dispatch.
      */
     deferredEventNoSourceDiagnostics?: SveldDiagnostic[];
+    /**
+     * `@event` tags with no `{type}` or `@property`, whose `null` detail no
+     * same-file dispatch replaced; an escaped dispatcher's helper may still.
+     */
+    untypedJsDocEventNames?: string[];
 }
 
 type SyntaxMode = "legacy" | "runes";
@@ -150,6 +169,29 @@ interface ComponentPropReExport {
     imported: string;
 }
 
+interface ComponentClassMember {
+    /** `"property"` covers fields, constructor parameter properties, and getter/setter pairs. */
+    kind: "constructor" | "method" | "property";
+    /** Member name; `"constructor"` for the constructor. */
+    name: string;
+    /** Property type text; `"any"` when neither TypeScript nor JSDoc types it. */
+    type?: string;
+    /** Method or constructor parameters, typed from TypeScript or JSDoc `@param`, else `"any"`. A rest parameter's name starts with `...`. */
+    params?: ComponentPropParam[];
+    /** Method return type from TypeScript or JSDoc `@returns`; unset when neither gives one. */
+    returnType?: string;
+    /** A method's own type parameter list (`U extends object`), without the angle brackets. */
+    typeParameters?: string;
+    static?: true;
+    /** A `readonly` field, or a getter with no setter. */
+    readonly?: true;
+    optional?: true;
+    abstract?: true;
+    description?: string;
+    deprecated?: DeprecatedValue;
+    tags?: JsDocPassthroughTag[];
+}
+
 interface ComponentProp {
     /** Public prop name; `"*"` for a bare `export * from "..."`. */
     name: string;
@@ -157,8 +199,10 @@ interface ComponentProp {
      * `"let"` (required), `"const"` (default), or `"function"`. `"re-export"`
      * is module-export only: `export { x } from "..."`, `export * from "..."`,
      * or `export { x }` of an imported binding, written to the `.d.ts` as-is.
+     * `"class"` is module-export only too: a class the module script declares,
+     * with its public surface in {@link ComponentProp.members}.
      */
-    kind: "let" | "const" | "function" | "re-export";
+    kind: "let" | "const" | "function" | "re-export" | "class";
     /** True when declared with `const`. */
     constant: boolean;
     /** TypeScript type text. */
@@ -181,8 +225,17 @@ interface ComponentProp {
      * A function's own type parameter list from its `@template` tags (e.g.
      * `T extends { id: string }`), without the angle brackets. Also prefixed
      * onto `type` when that signature is built from `@param`/`@returns`.
+     * For a `"class"`, the class's type parameters, from TypeScript or `@template`.
      */
     typeParameters?: string;
+    /** Set when `kind` is `"class"`: its public constructor, methods, and properties, in source order. */
+    members?: ComponentClassMember[];
+    /** Set when `kind` is `"class"` and the class is `abstract`. */
+    abstract?: true;
+    /** Set when `kind` is `"class"` and it extends a base class: `Base<T>`. */
+    extends?: string;
+    /** Set when `kind` is `"class"` and it implements interfaces: `["Disposable"]`. */
+    implements?: string[];
     /**
      * True for arrow/function-expression initializers and bare `function`
      * declarations in every mode; additionally true for a function-shaped
@@ -381,9 +434,15 @@ interface ComponentContext {
     key: string;
     /** Generated type name (e.g. `"ModalContext"`). */
     typeName: string;
+    /**
+     * The context's whole type, when the `setContext` value is a variable whose
+     * type isn't an object type literal (`ModalAPI`, `Writable<number>`, or `any`
+     * when untyped). `properties` is empty then.
+     */
+    type?: string;
     /** From JSDoc. */
     description?: string;
-    /** Context object properties. */
+    /** Context object properties. Empty when {@link ComponentContext.type} is set. */
     properties: ComponentContextProp[];
     /** True when a `{...spread}` in the context's object literal couldn't be resolved; the generated type intersects with `Record<string, any>`. */
     hasUnresolvedSpread?: boolean;
@@ -476,13 +535,37 @@ export class ComponentParser {
     } | undefined;
     private addModuleExport;
     /**
-     * Resolves one `export { local as exported }` specifier to the variable
-     * declarator it names. Each specifier resolves on its own, so
+     * Resolves one `export { local as exported }` specifier to the top-level
+     * function, class, or variable declarator (including one destructured
+     * from a pattern) it names. Each specifier resolves on its own, so
      * `export { a, b }` exports both, and `const a = 1, b = ""; export { b }`
      * exports `b`'s declarator rather than the first one in the declaration.
+     *
+     * `program` is the script the export sits in: only its top-level
+     * declarations count, not a same-named variable inside a function. An
+     * instance-script export can also name a module-script declaration, or a
+     * variable that a `$: local = ...` reactive declaration declares implicitly.
      */
     private resolveExportSpecifier;
     private recordUnresolvedExportSpecifier;
+    /**
+     * Doc comment for a declaration exported by `node`. A specifier uses the
+     * comment on the declaration it names. An `export { ... }` list's own
+     * comment documents it too, but only when the list has a single specifier;
+     * its tags and description then override the declaration's.
+     */
+    private exportJSDoc;
+    /** An instance-script `export class Foo {}` or `export { Foo }` of a class: neither a prop nor a documented accessor. */
+    private recordClassExport;
+    /**
+     * The `.d.ts` can only say `extends Base` when `Base` is in scope there:
+     * imported, or another exported class. A class extending anything else
+     * (a local class, a call like `mixin(Base)`) is declared without it, and
+     * flagged, since consumers won't see its inherited members.
+     */
+    private dropUndeclaredClassBases;
+    /** A module-script `export class Foo {}` or `export { Foo }` of a class, with its public members. */
+    private addModuleClassExport;
     /**
      * @example
      * ```ts
@@ -510,6 +593,17 @@ export class ComponentParser {
         description?: string;
         internal?: boolean;
     } | null;
+    /**
+     * The description and `@internal` flag of the JSDoc above `varName`,
+     * whether or not it has a `@type`. For a variable typed some other way,
+     * such as from its initializer.
+     */
+    findVariableJsDoc(varName: string): {
+        description?: string;
+        internal?: boolean;
+    };
+    /** The JSDoc table entry for `varName`, building the table on first use. */
+    private variableJsDocEntry;
     accumulateGeneric(name: string, constraint: string): void;
     /**
      * Resets parser state for reuse between parses.
@@ -523,6 +617,7 @@ export class ComponentParser {
      */
     cleanup(): void;
     private static readonly SCRIPT_BLOCK_REGEX;
+    /** A `// @ts-...` comment, but not one on a `*` line of a JSDoc block (e.g. in an `@example`). */
     private static readonly TS_DIRECTIVE_REGEX;
     private static stripTypeScriptDirectivesFromScripts;
     /**
@@ -539,12 +634,15 @@ export class ComponentParser {
     parseSvelteComponent(source: string, diagnostics: ComponentParserDiagnostics): ParsedComponent;
 }
 
-export type SveldDiagnosticKind = "prop-unknown-type" | "context-any-type" | "slot-missing-type" | "event-no-source" | "dispatch-escapes" | "example-compile-error" | "example-syntax-error" | "syntax-skipped" | "rest-props-unresolved" | "context-duplicate-key" | "context-key-unresolved" | "spread-unresolved" | "export-unresolved" | "module-export-conflict" | "extend-props-target-missing" | "extend-props-duplicate" | "extend-props-override" | "jsdoc-unknown-tag" | "typedef-duplicate" | "property-duplicate" | "generics-conflict" | "event-description-ambiguous" | "jsdoc-tag-dropped" | "internal-typedef-referenced" | "types-inline-unresolved";
+export type SveldDiagnosticKind = "prop-unknown-type" | "context-any-type" | "slot-missing-type" | "event-no-source" | "dispatch-escapes" | "example-compile-error" | "example-syntax-error" | "syntax-skipped" | "rest-props-unresolved" | "context-duplicate-key" | "context-key-unresolved" | "context-value-unresolved" | "spread-unresolved" | "export-unresolved" | "module-export-conflict" | "extend-props-target-missing" | "extend-props-duplicate" | "extend-props-override" | "jsdoc-unknown-tag" | "typedef-duplicate" | "property-duplicate" | "generics-conflict" | "event-description-ambiguous" | "jsdoc-tag-dropped" | "internal-typedef-referenced" | "types-inline-unresolved" | "cross-file-unresolved" | "export-ambiguous";
 
 type SveldDiagnosticSeverity = "error" | "warning";
 
 export interface SveldDiagnostic {
-    /** File this came from, e.g. `"./Button.svelte"`. */
+    /**
+     * File this came from, e.g. `"./Button.svelte"`, or the entry barrel
+     * (`"./index.js"`) for `export-ambiguous`.
+     */
     component: string;
     kind: SveldDiagnosticKind;
     /** Stable, namespaced identifier for `kind` (e.g. `"sveld/prop-unknown-type"`). */
@@ -566,6 +664,13 @@ export interface SveldDiagnostic {
 
 declare const PARSED_COMPONENT_TYPE_SCRIPT_METADATA: unique symbol;
 
+export interface FinalizeWithoutCrossFileResolutionOptions {
+    /** Path recorded on the new diagnostics. Defaults to the component's own `filePath`, if it has one. */
+    filePath?: string;
+}
+
+export declare function finalizeWithoutCrossFileResolution<T extends ParsedComponent>(component: T, options?: FinalizeWithoutCrossFileResolutionOptions): T;
+
 export interface ComponentDocApi extends ParsedComponent {
     filePath: NormalizedPath;
     moduleName: string;
@@ -665,7 +770,11 @@ export declare function writeTsDefinition(component: ComponentDocApi, options?:
 interface EntryExport {
     name: string;
     kind: "const" | "let" | "var" | "function" | "class" | "type" | "interface" | "enum";
-    /** Type text from the source, when present. */
+    /**
+     * Type text from the source, when present. A namespace export
+     * (`export * as ns from "./x"`) gets `typeof import("./x.ts")`, the
+     * wrapped module relative to the entry file.
+     */
     type?: string;
     /** Initializer text for simple constants. */
     value?: string;