sveld 0.37.7 → 0.37.9

package/lib/index.d.ts

@@ -1,3 +1,1350 @@
 /// <reference types="node" />
 
-export declare function parse(source: string): unknown;
+import type { Node, Property } from "estree";
+
+import type { FunctionDeclaration, VariableDeclaration } from "estree";
+
+interface JsDocPassthroughTag {
+    name: string;
+    body: string;
+}
+
+type DeprecatedValue = string | true;
+
+interface SourcePosition {
+    /** 1-based source line number */
+    line: number;
+    /** 0-based source column number */
+    column: number;
+}
+
+interface SourceRange {
+    start: SourcePosition;
+    end: SourcePosition;
+}
+
+interface PendingCallDefaultCandidate {
+    propName: string;
+    location: "props" | "moduleExports";
+    calleeName: string;
+    importSource?: string;
+    importedName?: string;
+}
+
+interface PendingConstDefaultCandidate {
+    propName: string;
+    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;
+}
+
+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. */
+    dispatcherName: string;
+    /** Argument position the dispatcher is passed at. */
+    argumentIndex: number;
+    /** Set when passed as an object literal property (`{ dispatch }`): that property's key. */
+    property?: string;
+    /** Source range of the call, when available. */
+    source?: SourceRange;
+    /** `@sveld-ignore sveld/dispatch-escapes` on the dispatcher's declaration. */
+    ignored?: boolean;
+}
+
+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
+     * `<script generics="...">` parameters (e.g. `Props<T>`). The semantic
+     * resolver has no binding for `T`, so `resolveTypes` must leave this
+     * component's props as their AST-derived text rather than expand them.
+     */
+    referencesComponentGenerics?: boolean;
+    /** Unresolved CallExpression defaults for the cross-file pass in `generateBundle`. */
+    pendingCallDefaultCandidates?: PendingCallDefaultCandidate[];
+    /** Imported-identifier defaults for the cross-file pass in `generateBundle`. */
+    pendingConstDefaultCandidates?: PendingConstDefaultCandidate[];
+    /** Unresolved `setContext` import keys for the cross-file pass in `generateBundle`. */
+    pendingContextKeyCandidates?: PendingContextKeyCandidate[];
+    /** Dispatchers passed to imported functions, for the cross-file pass in `generateBundle`. */
+    pendingDispatchEscapeCandidates?: PendingDispatchEscapeCandidate[];
+    /**
+     * `event-no-source` diagnostics held back while the dispatcher escapes to
+     * 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";
+
+type ScriptLanguage = "js" | "ts";
+
+type ComponentPropTypeSource = "typescript" | "jsdoc" | "default" | "inferred" | "unknown";
+
+type ComponentPropDefaultValueKind = "literal" | "array" | "object" | "expression" | "function" | "unknown";
+
+interface ComponentPropDefaultValue {
+    raw: string;
+    kind: ComponentPropDefaultValueKind;
+    value?: unknown;
+}
+
+type ModernScriptAttribute = {
+    name?: string;
+    value?: Array<{
+        data?: string;
+        raw?: string;
+    }> | boolean;
+    start?: number;
+    end?: number;
+};
+
+type ModernScriptNode = {
+    attributes?: ModernScriptAttribute[];
+};
+
+interface ComponentParserDiagnostics {
+    moduleName: string;
+    filePath: string;
+}
+
+type ComponentPropBinding = "readonly" | "writable";
+
+interface ComponentPropParam {
+    /** Parameter name. */
+    name: string;
+    /** Parameter type (e.g. `"string"`, `"CustomType"`). */
+    type: string;
+    /** From JSDoc `@param`. */
+    description?: string;
+    /** True when optional. */
+    optional?: boolean;
+}
+
+interface ComponentPropReExport {
+    /** Module specifier as written in the source (e.g. `"./utils.js"`). */
+    from: string;
+    /** Name `from` exports: `"default"` for a default import, `"*"` for `export *` or a namespace import. */
+    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;
+    /**
+     * `"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" | "class";
+    /** True when declared with `const`. */
+    constant: boolean;
+    /** TypeScript type text. */
+    type?: string;
+    /** Conservative provenance for the prop type. See the precedence rule on {@link ComponentProp}. */
+    typeSource?: ComponentPropTypeSource;
+    /** Local binding when it differs from the public name. */
+    localName?: string;
+    /** Default value as source text; unset when the prop has no initializer/default. */
+    value?: string;
+    /** Structured default value metadata for docs UIs; set alongside `value` from the same initializer. */
+    defaultValue?: ComponentPropDefaultValue;
+    /** From JSDoc, or a matching `@typedef`'s own description (legacy only; see {@link ComponentProp}). */
+    description?: string;
+    /** From JSDoc `@param` on function props. */
+    params?: ComponentPropParam[];
+    /** From JSDoc `@returns` on function props. */
+    returnType?: string;
+    /**
+     * 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
+     * type/JSDoc signature in runes only (see {@link ComponentProp}).
+     */
+    isFunction: boolean;
+    /** True for `function` declarations. */
+    isFunctionDeclaration: boolean;
+    /** True when declared with `let` and no default. */
+    isRequired: boolean;
+    /**
+     * True when the prop is mutated locally (legacy, inferred from assignment/
+     * binding targets) or declared with `$bindable()` (runes).
+     */
+    reactive: boolean;
+    /** Binding direction from `@bindable` JSDoc. */
+    binding?: ComponentPropBinding;
+    /** True when declared with Svelte 5 `$bindable()` (runes only). */
+    bindable?: true;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
+    /** `@since` / `@example` tags in source order. */
+    tags?: JsDocPassthroughTag[];
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** Set when `kind` is `"re-export"`. */
+    reExport?: ComponentPropReExport;
+    /** Source range when available. */
+    source?: SourceRange;
+}
+
+interface ComponentSlot {
+    /** Slot name (`null` for the default slot). */
+    name?: string | null;
+    /** True for the default slot. */
+    default: boolean;
+    /** Fallback content when the slot is empty. */
+    fallback?: string;
+    /** Slot props as TypeScript type text. */
+    slot_props?: string;
+    /** From JSDoc `@slot` or `@snippet`. */
+    description?: string;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
+    /** Tags between the description and `@slot`/`@snippet` (e.g. `@example`), in source order. */
+    tags?: JsDocPassthroughTag[];
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** Source range when available. */
+    source?: SourceRange;
+}
+
+interface DispatchedEvent {
+    /** Discriminator: `"dispatched"`. */
+    type: "dispatched";
+    /** Event name. */
+    name: string;
+    /** Detail type text. */
+    detail?: string;
+    /** From JSDoc `@event`. */
+    description?: string;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
+    /** `@since` / `@example` tags in source order. */
+    tags?: JsDocPassthroughTag[];
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** Source range when available. */
+    source?: SourceRange;
+}
+
+interface SerializedForwardedEvent {
+    /** Discriminator: `"forwarded"`. */
+    type: "forwarded";
+    /** Event name. */
+    name: string;
+    /** Element name as a string for JSON output. */
+    element: string;
+    /** From JSDoc `@event`. */
+    description?: string;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
+    /** Detail type from `@event`. */
+    detail?: string;
+    /** `@since` / `@example` tags in source order. */
+    tags?: JsDocPassthroughTag[];
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** Source range when available. */
+    source?: SourceRange;
+}
+
+export type SerializedComponentEvent = SerializedForwardedEvent | DispatchedEvent;
+
+interface TypeDef {
+    /** Type text (e.g. `"{ x: number; y: number }"`). */
+    type: string;
+    /** Type name. */
+    name: string;
+    /** From JSDoc. */
+    description?: string;
+    /** Full `type` alias declaration text. */
+    ts: string;
+    /** Tags in the same block (e.g. `@since`, `@example`, `@see`), in source order. */
+    tags?: JsDocPassthroughTag[];
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** Source range of the `@typedef`/`@callback` tag, when available. */
+    source?: SourceRange;
+}
+
+type ComponentGenerics = [name: string, type: string] | null;
+
+interface ComponentInlineElement {
+    /** Discriminator: `"InlineComponent"`. */
+    type: "InlineComponent";
+    /** Component name. */
+    name: string;
+}
+
+interface ComponentElement {
+    type: "Element";
+    name: string;
+    /**
+     * Static tag for `svelte:element this="div"`. Undefined when `this` is dynamic.
+     *
+     * @example
+     * ```svelte
+     * <!-- Static tag -->
+     * <svelte:element this="div" bind:this={elementRef} />
+     * // thisValue: "div"
+     *
+     * <!-- Dynamic tag -->
+     * <svelte:element this={tagName} bind:this={elementRef} />
+     * // thisValue: undefined
+     * ```
+     */
+    thisValue?: string;
+    /** From `@restProps` JSDoc. */
+    description?: string;
+}
+
+type RestProps = undefined | ComponentInlineElement | ComponentElement;
+
+interface Extends {
+    /** Interface name (e.g. `"ButtonProps"`). */
+    interface: string;
+    /** Import path (e.g. `"./types"`). */
+    import: string;
+}
+
+type CustomElementPropType = "String" | "Boolean" | "Number" | "Array" | "Object";
+
+interface CustomElementPropConfig {
+    /** Explicit attribute name. Svelte itself always observes every prop as an attribute; sveld's own output omits the attribute entirely when this is `false`. */
+    attribute?: string | false;
+    reflect?: boolean;
+    type?: CustomElementPropType;
+}
+
+interface CustomElementOptions {
+    tag?: string;
+    shadow?: "open" | "none";
+    props?: Record<string, CustomElementPropConfig>;
+    extend?: true;
+}
+
+interface ComponentCssPart {
+    name: string;
+    description?: string;
+}
+
+interface ComponentCssProperty {
+    /** Includes the leading `--`. */
+    name: string;
+    type?: string;
+    default?: string;
+    description?: string;
+}
+
+interface ComponentContextProp {
+    /** Property name. */
+    name: string;
+    /** Property type text. */
+    type: string;
+    /** From JSDoc. */
+    description?: string;
+    /** True when optional. */
+    optional: boolean;
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+}
+
+interface ComponentContext {
+    /** Context key from `setContext`. */
+    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. 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;
+    /** True from `@ignore`/`@internal` JSDoc on the `setContext` call; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** Source range of the `setContext(...)` call, when available. */
+    source?: SourceRange;
+}
+
+interface ParsedComponent {
+    /** Source range of the parsed file. */
+    source?: SourceRange;
+    syntaxMode: SyntaxMode;
+    scriptLanguage?: ScriptLanguage;
+    /** Instance-level props (`export let`/`export function`, or runes `$props()`). See {@link ComponentProp} for the shared IR these are built from. */
+    props: ComponentProp[];
+    /** Exports from `<script context="module">`. Same {@link ComponentProp} shape as `props`, resolved through the same shared decisions. */
+    moduleExports: ComponentProp[];
+    slots: ComponentSlot[];
+    /** Serialized events for JSON/API output. */
+    events: SerializedComponentEvent[];
+    typedefs: TypeDef[];
+    generics: null | ComponentGenerics;
+    rest_props: RestProps;
+    extends?: Extends;
+    /** From `@component` HTML comment. */
+    componentComment?: string;
+    componentCommentSource?: SourceRange;
+    contexts?: ComponentContext[];
+    customElementTag?: string;
+    /** Full `<svelte:options customElement=... />` config (shorthand or object form), when present. */
+    customElement?: CustomElementOptions;
+    /** From component-level `@csspart` JSDoc tags. */
+    cssParts?: ComponentCssPart[];
+    /** From component-level `@cssprop`/`@cssproperty` JSDoc tags. */
+    cssProperties?: ComponentCssProperty[];
+    /**
+     * Type guesses from this parse (unknown props, `any` contexts, orphan `@event` tags).
+     */
+    diagnostics?: SveldDiagnostic[];
+    /** Writer-only TypeScript metadata. Not serialized to JSON. */
+    [PARSED_COMPONENT_TYPE_SCRIPT_METADATA]?: ParsedComponentTypeScriptMetadata;
+}
+
+export class ComponentParser {
+    /**
+     * All per-parse mutable state (props, slots, events, scopes, source, etc.).
+     * See {@link ParserContext} for field-by-field documentation. Replaced
+     * wholesale by `cleanup()` between parses.
+     */
+    private ctx;
+    private static mapToArray;
+    private static getStaticAttributeValue;
+    resolveScriptLanguage(parsed: {
+        instance?: ModernScriptNode;
+        module?: ModernScriptNode;
+    }): ScriptLanguage | undefined;
+    /**
+     * Reads the `generics` attribute off the instance script (Svelte only allows
+     * it there, and only alongside `lang="ts"`). Returns the raw value for later
+     * precedence resolution against `@generics`/`@template` JSDoc tags, or
+     * `undefined` if absent. Records a `syntax-skipped` diagnostic and returns
+     * `undefined` if the attribute is present without `lang="ts"`, since sveld
+     * can't safely guess how to parse it as plain JavaScript.
+     */
+    resolveScriptGenericsAttribute(parsed: {
+        instance?: ModernScriptNode;
+    }): {
+        value: string;
+        source?: SourceRange;
+    } | undefined;
+    private resolvePublicPropName;
+    trackPropLocalName(propName: string, localName?: string): void;
+    private getPropByLocalOrPublic;
+    getPropTypeByLocalOrPublic(name: string): string | undefined;
+    getExplicitPropType(name: string): string | undefined;
+    getPropertyName(node: Property["key"]): string | undefined;
+    isNumericConstant(memberExpr: unknown): boolean;
+    resolveLocalVarJSDoc(name: string): {
+        type?: string;
+        params?: ComponentPropParam[];
+        returnType?: string;
+        description?: string;
+        binding?: ComponentPropBinding;
+        deprecated?: DeprecatedValue;
+        tags?: JsDocPassthroughTag[];
+        sveldIgnore?: string[];
+        internal: boolean;
+        typeParameters?: string;
+    } | undefined;
+    private addModuleExport;
+    /**
+     * 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
+     * aliasType("*"); // "any"
+     * aliasType(" string "); // "string"
+     * ```
+     */
+    aliasType(type: string): string;
+    /**
+     * @example
+     * ```ts
+     * // Given:
+     * // /**
+     * //  * @type {number}
+     * //  * The count value
+     * //  *\/
+     * // const count = 0;
+     *
+     * findVariableTypeAndDescription("count");
+     * // { type: "number", description: "The count value" }
+     * ```
+     */
+    findVariableTypeAndDescription(varName: string): {
+        type: string;
+        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.
+     *
+     * @example
+     * ```ts
+     * parser.parseSvelteComponent(source1, diagnostics1);
+     * parser.cleanup();
+     * parser.parseSvelteComponent(source2, diagnostics2);
+     * ```
+     */
+    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;
+    /**
+     * @example
+     * ```ts
+     * const parser = new ComponentParser();
+     * const result = parser.parseSvelteComponent(source, {
+     *   moduleName: "Button",
+     *   filePath: "./Button.svelte"
+     * });
+     * // { props, slots, events, typedefs, ... }
+     * ```
+     */
+    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" | "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";
+
+export type SveldDiagnosticSeverity = "error" | "warning";
+
+export declare const DIAGNOSTIC_CODES: Record<SveldDiagnosticKind, string>;
+
+export interface SveldDiagnostic {
+    /**
+     * 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"`). */
+    code: string;
+    severity: SveldDiagnosticSeverity;
+    /** Prop, context field, or event name. */
+    name: string;
+    /** What went wrong and what type sveld used. */
+    message: string;
+    /** Where in the component source this diagnostic points, when the parser holds a stable position. */
+    source?: SourceRange;
+    /**
+     * True when suppressed by an inline `@sveld-ignore` tag or a `diagnostics.ignore`
+     * config matcher. Still present here (and counted in the summary) but never
+     * fails `--strict` / `--strict=errors`.
+     */
+    ignored?: boolean;
+}
+
+export interface DiagnosticIgnoreMatcher {
+    code?: string;
+    component?: string;
+    name?: string;
+}
+
+export declare const DIAGNOSTICS_SCHEMA_VERSION = 1;
+
+export interface DiagnosticsJson {
+    kind: "diagnostics";
+    schemaVersion: typeof DIAGNOSTICS_SCHEMA_VERSION;
+    diagnostics: SveldDiagnostic[];
+}
+
+declare const PARSED_COMPONENT_TYPE_SCRIPT_METADATA: unique symbol;
+
+export type SemverBump = "major" | "minor" | "patch" | "none";
+
+export interface ApiChange {
+    /** Component `moduleName` this change belongs to, or `"*"` for document-wide notices. */
+    component: string;
+    kind: "component" | "prop" | "moduleExport" | "event" | "slot" | "shape" | "schema";
+    /** Prop, event, slot, or shape-field name, when applicable. */
+    name?: string;
+    bump: SemverBump;
+    message: string;
+}
+
+export interface CheckResult {
+    /** `false` when there was nothing on disk to diff against (e.g. first run). */
+    snapshotExists: boolean;
+    snapshotFile: string;
+    changes: ApiChange[];
+    /** Highest bump across all changes. */
+    bump: SemverBump;
+}
+
+export declare function diffApiDocuments(previous: ComponentApiDocument, next: ComponentApiDocument): ApiChange[];
+
+interface RunCheckOptions {
+    /** Entry-barrel exports when `documentExports` is on. */
+    entryExports?: EntryExports;
+}
+
+export declare function runCheck(components: ComponentDocs, snapshotFile: string, options?: RunCheckOptions): Promise<CheckResult>;
+
+export declare function formatCheckReport(result: CheckResult): string;
+
+export declare const CHECK_REPORT_SCHEMA_VERSION = 1;
+
+export type CheckReportJson = CheckResult & {
+    kind: "check-report";
+    schemaVersion: typeof CHECK_REPORT_SCHEMA_VERSION;
+};
+
+export declare function formatCheckReportJson(result: CheckResult): string;
+
+interface ComponentDocApi extends ParsedComponent {
+    filePath: NormalizedPath;
+    moduleName: string;
+}
+
+type ComponentDocs = Map<string, ComponentDocApi>;
+
+interface ComponentParseError {
+    filePath: string;
+    moduleName: string;
+    message: string;
+    stack?: string;
+}
+
+interface GenerateBundleOptions {
+    /**
+     * Throw on the first component that fails to parse instead of collecting
+     * the failure and continuing with the remaining components.
+     */
+    failFast?: boolean;
+    /**
+     * Load the TypeScript program to expand opaque imported whole-object `$props()`
+     * types into JSON/Markdown props. Off by default; requires `typescript`.
+     */
+    resolveTypes?: boolean;
+    /** Record consts, functions, and types from the entry barrel. Off by default. */
+    documentExports?: boolean;
+    /**
+     * Cache parsed component output to disk. Unchanged files skip re-parsing 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.
+     */
+    cache?: boolean | string;
+    /**
+     * Check `@example` blocks on props, module exports, slots, and events.
+     * `true` runs plain TS/JS examples through the TypeScript program
+     * (`example-compile-error` diagnostics; requires `typescript`) and
+     * Svelte/HTML examples through sveld's own template parser
+     * (`example-syntax-error` diagnostics; no `typescript` needed). Pass
+     * `"syntax"` to run only the markup path, so `typescript` is never loaded
+     * even when TS/JS examples exist. Off by default.
+     */
+    checkExamples?: boolean | "syntax";
+    /**
+     * Parse as usual (so cache reads and real errors still apply) but skip
+     * persisting the parse cache to disk. Set by the CLI's `--dry-run`.
+     */
+    dryRun?: boolean;
+    /**
+     * `ignore`: diagnostics matching at least one `{ code?, component?, name? }`
+     * matcher are marked `ignored` (an omitted field matches anything;
+     * `component` is a glob). Ignored diagnostics still appear in
+     * `SveldResult.diagnostics` and are counted in the text summary, but never
+     * fail `--strict` / `--strict=errors`.
+     */
+    diagnostics?: {
+        ignore?: DiagnosticIgnoreMatcher[];
+    };
+    /**
+     * Mirrors `typesOptions.typeNames`: templates for the `<Name>Props`
+     * interface name that `@extends`/`@extendProps` validation checks against.
+     */
+    typesTypeNames?: WriteTsDefinitionOptions["typeNames"];
+    /**
+     * Mirrors `typesOptions.inline`: `"local"`/`"all"` runs the cross-file
+     * inlining pass (see `inline-types.ts`) after every component has parsed.
+     */
+    typesInline?: WriteTsDefinitionOptions["inline"];
+}
+
+declare const brand: unique symbol;
+
+type Brand<TBase extends string, TBrand extends string> = TBase & {
+    readonly [brand]: TBrand;
+};
+
+export type SvelteEntryPoint = Brand<string, "SvelteEntryPoint">;
+
+type NormalizedPath = Brand<string, "NormalizedPath">;
+
+type RelativeSourcePath = Brand<string, "RelativeSourcePath">;
+
+interface InlinedTypes {
+    /** Exact `typeImportStatements` entries the writer must drop. */
+    droppedImportStatements: string[];
+    /** Declarations to emit (already stripped of `export`), in dependency order. */
+    declarations: string[];
+    /** Absolute paths of every file read, for watch-mode invalidation. */
+    dependencies: string[];
+}
+
+interface WriteTsDefinitionOptions {
+    /**
+     * `"class"` (default) extends the deprecated `SvelteComponentTyped`.
+     * `"component"` emits `declare const X: Component<Props, Exports, Bindings>`
+     * instead, for Svelte 5+ consumers. Generic components get a per-component
+     * interface with a generic call signature instead of `Component<...>`
+     * directly, since a `declare const` can't itself carry a generic type
+     * parameter (see `genGenericComponentDeclaration`).
+     */
+    format?: "class" | "component";
+    /**
+     * Which generated type declarations get an `export` keyword. `true`
+     * (default) exports all; `false` exports none; an object picks per kind.
+     * Module-script exports (`export declare const/function`) are runtime
+     * exports and are always emitted as exports.
+     */
+    exportTypes?: boolean | {
+        props?: boolean;
+        exports?: boolean;
+        typedefs?: boolean;
+        contexts?: boolean;
+    };
+    /** @internal Set by `writeTsDefinitions` for `@extends` targets; overrides `exportTypes.props`. */
+    forceExportProps?: boolean;
+    /**
+     * Templates for generated type names. `{name}` is replaced with the
+     * component's module name. Defaults: `"{name}Props"`, `"{name}Exports"`.
+     */
+    typeNames?: {
+        props?: string;
+        exports?: string;
+    };
+    /**
+     * How much JSDoc to emit. `"all"` (default) keeps descriptions,
+     * `@deprecated`, `@default`, and passthrough tags (`@since`, `@see`,
+     * `@example`, `@link`). `"descriptions"` keeps descriptions and
+     * `@deprecated` only. `"none"` emits no comments at all.
+     */
+    comments?: "all" | "descriptions" | "none";
+    /**
+     * `"type"` (default) emits the props type as a type alias.
+     * `"interface"` emits `interface <Name>Props { ... }` when the props are a
+     * plain object (no `@restProps`, no `@extendProps`, no whole-object
+     * `$props()` type); other shapes are intersections and stay aliases.
+     */
+    propsDeclaration?: "type" | "interface";
+    /**
+     * Copies `type`/`interface` declarations imported from a relative source (or a
+     * tsconfig/jsconfig path alias) directly into the `.d.ts`, dropping the import. `"local"`
+     * follows relative sources, path aliases, re-exports, and same-file dependencies; bare package
+     * imports, `.svelte` sources, and unsupported exports (enums, classes, functions, consts,
+     * namespaces) stay imports and get a `types-inline-unresolved` warning. `"all"` additionally
+     * inlines bare/package imports (e.g. `import type { Foo } from "some-lib"`) using the real
+     * TypeScript checker - same unsupported-export/collision rules, same warning on failure - with
+     * two exceptions kept as plain imports regardless: `svelte`/`svelte/elements` (a hard-coded
+     * allow-list; copying framework types would freeze a Svelte version into consumer output) and
+     * `@extendProps`/`@extends` targets (deferred; unrelated mechanism). `"all"` needs `typescript`
+     * 7+ and a `tsconfig.json`, same hard requirement as `resolveTypes`. `false` (default)
+     * preserves every import as-is.
+     * @default false
+     */
+    inline?: false | "local" | "all";
+    /** @internal Set by `writeTsDefinitions` from `GenerateBundleResult.inlinedTypesByFilePath` when `inline` resolved something for this component. */
+    inlined?: InlinedTypes;
+}
+
+interface PluginSveldOptions extends Pick<GenerateBundleOptions, "resolveTypes" | "cache" | "checkExamples" | "diagnostics"> {
+    /**
+     * Specify the entry point to uncompiled Svelte source.
+     * If not provided, sveld will use the "svelte" field from package.json.
+     */
+    entry?: string;
+    /**
+     * 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()` if the plugin isn't running
+     * under Vite); a string is an explicit path to the config file itself.
+     * @default false
+     */
+    config?: boolean | string;
+    glob?: boolean;
+    /** Suppress writer progress logs (`created "..."` / `unchanged "..."`). */
+    quiet?: boolean;
+    /** Record consts, functions, and types from the entry barrel. Off by default. */
+    documentExports?: boolean;
+    types?: boolean;
+    typesOptions?: Partial<Omit<WriteTsDefinitionsOptions, "inputDir">>;
+    json?: boolean;
+    jsonOptions?: Partial<Omit<WriteJsonOptions, "inputDir">>;
+    markdown?: boolean;
+    markdownOptions?: Partial<WriteMarkdownOptions>;
+    /** Generate a Custom Elements Manifest (`custom-elements.json`, schemaVersion "1.0.0"). */
+    customElements?: boolean;
+    customElementsOptions?: Partial<Omit<WriteCustomElementsOptions, "inputDir">>;
+    /** Generate a first-party `llms.txt` / `llms-full.txt` pair (per https://llmstxt.org). */
+    llms?: boolean;
+    llmsOptions?: Partial<WriteLlmsOptions>;
+    /**
+     * Run additional, userland-registered writers (via `registerWriter` from
+     * "sveld") beyond the built-in `json`/`markdown`/`types` outputs. Keyed by
+     * the writer's registered `name`, valued by that writer's options.
+     */
+    additionalWriters?: Record<string, unknown>;
+    /**
+     * Abort the entire run when a single component fails to parse.
+     * When `false` (the default), parse failures are collected as diagnostics
+     * and the remaining components still emit their output.
+     */
+    failFast?: boolean;
+    /**
+     * Regenerate output incrementally when relevant source changes during
+     * `vite dev` / `vite build --watch`: a component, the entry barrel itself
+     * (adding/removing an export), or a non-`.svelte` file a component depends
+     * on via `@extendProps` / `@extends` or a typedef `import("./x")`
+     * reference. Only the affected components are re-parsed.
+     * @default false
+     */
+    watch?: boolean;
+}
+
+interface HotUpdateContext {
+    file: string;
+}
+
+interface RollupPluginContext {
+    error(message: string): never;
+}
+
+interface ResolvedViteConfig {
+    root: string;
+}
+
+interface SveldPlugin {
+    name: string;
+    apply?: "build" | "serve";
+    enforce?: "pre" | "post";
+    /** Vite-only hook: captures the project root before `buildStart` runs. */
+    configResolved?(config: ResolvedViteConfig): void;
+    buildStart(): void | Promise<void>;
+    generateBundle(this: RollupPluginContext): Promise<void>;
+    writeBundle(this: RollupPluginContext): Promise<void>;
+    /** Vite dev-server HMR hook (serve mode). */
+    handleHotUpdate?(ctx: HotUpdateContext): void;
+    /** Rollup/Vite watch hook (build `--watch`). */
+    watchChange?(id: string): void;
+}
+
+export default function pluginSveld(opts?: PluginSveldOptions): SveldPlugin;
+
+interface WriteCustomElementsOptions {
+    /** @internal Resolved from `entry` and always injected by the caller (`plugin.ts`); not user-configurable via `customElementsOptions`. */
+    inputDir: string;
+    outFile: string;
+    /** @internal Report the resolved path instead of writing. Always set by the caller from `sveld --dry-run`. */
+    dryRun?: boolean;
+}
+
+interface WriteJsonOptions {
+    /** @internal Unused by this writer; kept for backward compatibility. Always set by the caller. */
+    input: string;
+    /** @internal Resolved from `entry` and always injected by the caller (`plugin.ts`); not user-configurable via `jsonOptions`. */
+    inputDir: string;
+    outFile: string;
+    outDir?: string;
+    /**
+     * @internal Entry-barrel exports when `documentExports` is on. Always
+     * computed from the parsed bundle and injected by the caller; setting it
+     * via `jsonOptions` has no effect.
+     */
+    entryExports?: EntryExports;
+    /**
+     * Include `source`/`componentCommentSource` position ranges in the
+     * output. These are the bulk of a large component library's
+     * `COMPONENT_API.json` (roughly a quarter of the file for a 150+
+     * component library); set to `false` to omit them and shrink the file
+     * when consumers don't need exact source positions.
+     * @default true
+     */
+    source?: boolean;
+    /** @internal Report resolved paths instead of writing. Always set by the caller from `sveld --dry-run`. */
+    dryRun?: boolean;
+}
+
+interface EntryExport {
+    name: string;
+    kind: "const" | "let" | "var" | "function" | "class" | "type" | "interface" | "enum";
+    /**
+     * 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;
+    description?: string;
+    /** From `@deprecated` JSDoc. */
+    deprecated?: DeprecatedValue;
+    /** `@since` / `@example` / `@see` tags in source order. */
+    tags?: JsDocPassthroughTag[];
+    /** True from `@ignore`/`@internal` JSDoc; excluded from every output by `buildComponentApiDocument`. */
+    internal?: boolean;
+    /** Declaring module, relative to the entry file. */
+    source?: string;
+    isTypeOnly: boolean;
+}
+
+type EntryExports = EntryExport[];
+
+interface WriteLlmsOptions {
+    outDir?: string;
+    /** Prefixed to each component's link path, e.g. `[Name](<linkBase>/Name)`. @default "" */
+    linkBase?: string;
+    /** @default the "name" field from the project's package.json */
+    title?: string;
+    /** @default the "description" field from the project's package.json */
+    summary?: string;
+    /** @internal Entry-barrel exports when `documentExports` is on. Always computed from the parsed bundle and injected by the caller. */
+    entryExports?: EntryExports;
+    /** @internal Report the resolved paths instead of writing. Always set by the caller from `sveld --dry-run`. */
+    dryRun?: boolean;
+}
+
+interface WriteMarkdownOptions {
+    write?: boolean;
+    outFile: string;
+    /**
+     * Emit one `<ModuleName>.md` file per component into this directory,
+     * plus an index `README.md` linking to each, instead of the single
+     * combined `outFile`. See `jsonOptions.outDir` for the equivalent JSON
+     * option.
+     */
+    outDir?: string;
+    /**
+     * @internal Entry-barrel exports when `documentExports` is on. Always
+     * computed from the parsed bundle and injected by the caller; setting it
+     * via `markdownOptions` has no effect.
+     */
+    entryExports?: EntryExports;
+    onAppend?: (type: AppendType, document: WriterMarkdown, components: ComponentDocs) => void;
+    /** @internal Report the resolved path instead of writing. Always set by the caller from `sveld --dry-run`. */
+    dryRun?: boolean;
+}
+
+type OnAppend = (type: AppendType, document: WriterMarkdown) => void;
+
+interface MarkdownOptions {
+    onAppend?: OnAppend;
+}
+
+declare class WriterMarkdown extends Writer {
+    onAppend?: OnAppend;
+    private markdownBase;
+    constructor(options: MarkdownOptions);
+    get source(): string;
+    get hasToC(): boolean;
+    get toc(): TocLine[];
+    appendLineBreaks(): this;
+    append(type: AppendType, raw?: string): this;
+    tableOfContents(): this;
+    end(): string;
+}
+
+type AppendType = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "quote" | "p" | "divider" | "raw";
+
+interface TocLine {
+    /** Leading space count; 0 for the top-level (`h2`) entries the TOC currently lists. */
+    indent: number;
+    raw: string;
+}
+
+interface WriterOptions {
+    /** Report the resolved path to stdout instead of writing. Set by `sveld --dry-run`. */
+    dryRun?: boolean;
+}
+
+declare class Writer {
+    private readonly dryRun;
+    /** Directories already created by this writer, so sibling files skip the `mkdir` round trip. */
+    private readonly ensuredDirs;
+    constructor(options?: WriterOptions);
+    /**
+     * Skips the write when `filePath` already contains `raw`, so repeated runs
+     * over unchanged sources don't touch the file (or its mtime). In dry-run
+     * mode, prints `would write "<path>"` to stdout and touches nothing.
+     *
+     * @returns `true` if the file was written, `false` if it was already up to date.
+     *
+     * @example
+     * ```ts
+     * const writer = new Writer();
+     * await writer.write("./dist/index.d.ts", "export type Props = {};");
+     * ```
+     */
+    write(filePath: string, raw: string): Promise<boolean>;
+}
+
+type TransformContext = {
+    kind: "component";
+    component: ComponentDocApi;
+    filePath: string;
+} | {
+    kind: "index";
+    filePath: string;
+};
+
+interface WriteTsDefinitionsOptions extends WriteTsDefinitionOptions {
+    outDir: string;
+    /** @internal Resolved from `entry` and always injected by the caller (`plugin.ts`); not user-configurable via `typesOptions`. */
+    inputDir: string;
+    preamble: string;
+    /** @internal Always computed from the parsed bundle and injected by the caller; not user-configurable via `typesOptions`. */
+    exports: ParsedExports;
+    /** @internal Report resolved paths instead of writing. Always set by the caller from `sveld --dry-run`. */
+    dryRun?: boolean;
+    /**
+     * @internal Reuses generated `.d.ts` text across runs for components whose
+     * source (and every emit option from `serializeEmitOptions`) hasn't
+     * changed. Requires `resolvedPathByFilePath` to key lookups; both come
+     * from `GenerateBundleResult`.
+     */
+    cache?: ParseCache;
+    /** @internal See `cache`. Lookups use `component.filePath`. */
+    resolvedPathByFilePath?: Map<string, string>;
+    /**
+     * @internal See `cache`. For components whose output was resolved from
+     * other files, so their text is keyed on their content too.
+     */
+    crossFileResolvedPathByFilePath?: Map<string, string>;
+    /**
+     * @internal From `GenerateBundleResult.inlinedTypesByFilePath`, populated when
+     * `typesOptions.inline` is `"local"`/`"all"`. Lookups use `component.filePath`.
+     */
+    inlinedTypesByFilePath?: Map<string, InlinedTypes>;
+    /**
+     * Post-processes each generated file's text before it is written. Runs
+     * after the generated-text cache, so it applies on every run. Config file
+     * or `sveld()` only.
+     */
+    transform?: (text: string, context: TransformContext) => string | Promise<string>;
+    /**
+     * 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. Skips any type
+     * that `exportTypes` keeps local.
+     */
+    indexTypes?: boolean | {
+        props?: boolean;
+        exports?: boolean;
+        typedefs?: boolean;
+        contexts?: boolean;
+    };
+}
+
+declare class ParseCache {
+    private readonly cacheFilePath;
+    private readonly file;
+    private readonly next;
+    /** Paths forced to miss this run (e.g. dependents of a changed `@extends` target). */
+    private readonly blocked;
+    /**
+     * Whether `next` differs from what's on disk: an entry was added or its
+     * generated text changed. Dropped entries show up as `next` holding fewer
+     * entries than `savedEntryCount`, since without a `set()` every entry in
+     * `next` came from the file.
+     */
+    private dirty;
+    private savedEntryCount;
+    constructor(cacheFilePath: string);
+    /** True when `get()` would return a hit for `resolvedPath` and `hash`. */
+    has(resolvedPath: string, hash: string): boolean;
+    /** Returns the cached parse for `resolvedPath` when its content hash still matches. */
+    get(resolvedPath: string, hash: string): ParsedComponent | null;
+    /**
+     * Records a freshly parsed component so it can be reused on a future run.
+     * Stores a copy, for the same reason `get()` returns one.
+     */
+    set(resolvedPath: string, hash: string, parsed: ParsedComponent): void;
+    /** Skip cache for `resolvedPath` this run (e.g. an @extends dependent). */
+    invalidate(resolvedPath: string): void;
+    /**
+     * Returns the cached generated `.d.ts` text for `resolvedPath`, if this
+     * run's parse entry for it (a fresh parse or a hash-verified hit - see
+     * `get()`/`set()`) already carries text generated for `key`, the
+     * serialized emit options (see `serializeEmitOptions`).
+     */
+    getGeneratedText(resolvedPath: string, key: string): string | undefined;
+    /**
+     * Records generated `.d.ts` text against this run's parse entry for
+     * `resolvedPath`. No-op if that entry hasn't been recorded via `get()`/`set()`
+     * (shouldn't happen: the write phase only runs after every component has
+     * been parsed).
+     */
+    setGeneratedText(resolvedPath: string, key: string, text: string): void;
+    /**
+     * Persists this run's cache entries back to disk. Writes to a pid-suffixed
+     * temp file and renames it over the target so concurrent sveld processes
+     * sharing a cache dir can't interleave writes into a truncated file; a
+     * failed rename (e.g. read-only cache dir) falls back to a direct write so
+     * generation never fails just because the cache couldn't be saved.
+     * Skipped when nothing changed since the file was read or last saved.
+     */
+    save(): void;
+}
+
+type ParsedExports = Record<string, {
+    source: RelativeSourcePath;
+    default: boolean;
+    mixed?: boolean;
+}>;
+
+export interface SveldRuntimeOptions extends PluginSveldOptions {
+    /** Print unresolved-type diagnostics to stderr. */
+    reportDiagnostics?: boolean;
+    /**
+     * Exit code 4 when diagnostics exist. Implies `reportDiagnostics`. Pass
+     * `"errors"` to fail only on `severity: "error"` diagnostics
+     * (`example-compile-error`, `syntax-skipped`), letting warnings
+     * (`prop-unknown-type`, `context-any-type`, `event-no-source`) through.
+     *
+     * `"ci"` and `"local"` are strictness profiles, expanded by
+     * {@link expandStrictProfile} into a set of other options before this
+     * object's own explicit keys are applied (so they can still opt back out
+     * of one, e.g. `{ strict: "ci", checkExamples: false }`):
+     * - `"ci"`: `{ strict: true, reportDiagnostics: true, check: true, checkExamples: true }`.
+     * - `"local"`: `{ reportDiagnostics: true }` (does not itself enable `strict`).
+     */
+    strict?: boolean | "errors" | "ci" | "local";
+    /**
+     * Diff the parsed component API against a committed snapshot (default:
+     * the `json` writer's `outFile`, or `COMPONENT_API.json`) and assign a
+     * semver bump to each change. Exits `3` on a breaking change. Pass a
+     * string for a custom snapshot path.
+     */
+    check?: boolean | string;
+    /**
+     * Minimum bump `--check` fails the run (exit `3`) on: `"major"` (default,
+     * preserves prior behavior), `"minor"`, or `"patch"`.
+     */
+    checkLevel?: "major" | "minor" | "patch";
+    /** Suppress writer progress logs (`created "..."` / `unchanged "..."`). */
+    quiet?: boolean;
+    /**
+     * Print the single selected `json` / `markdown` / `customElements` document
+     * to stdout instead of writing it to disk. Requires exactly one of those
+     * three outputs; CLI-only (the Vite plugin ignores it). `"ndjson"` is only
+     * valid with `json` and prints one minified JSON object per component per
+     * line instead of the single combined document.
+     */
+    stdout?: boolean | "json" | "ndjson";
+    /**
+     * Output format for the `--check` report and the `--report-diagnostics` /
+     * `--strict` diagnostics summary: `"text"` (default), `"json"`, or
+     * `"github"` (GitHub Actions `::error`/`::warning` workflow commands, plus
+     * a `GITHUB_STEP_SUMMARY` Markdown table when that env var is set).
+     * Channels are unchanged, the check report on stdout and diagnostics on
+     * stderr. CLI-only; `sveld()` ignores `format` for its own console output.
+     */
+    format?: "text" | "json" | "github";
+    /**
+     * Resolve the entry, load config, and parse components as usual, but print
+     * `would write "<path>"` for each output file to stdout instead of writing
+     * it (including the parse cache). CLI-only; the Vite plugin ignores it.
+     */
+    dryRun?: boolean;
+}
+
+export type SveldConfig = SveldRuntimeOptions;
+
+export declare function defineConfig(config: SveldConfig): SveldConfig;
+
+export interface ComponentApiDocument {
+    schemaVersion: 1;
+    generator: {
+        name: string;
+        version: string;
+        svelteVersion: string;
+    };
+    total: number;
+    components: ComponentDocApi[];
+    /** Only when `documentExports` is on. */
+    totalExports?: number;
+    exports?: EntryExports;
+}
+
+interface BuildComponentApiDocumentOptions {
+    /** Entry-barrel exports when `documentExports` is on. */
+    entryExports?: EntryExports;
+}
+
+export declare function buildComponentApiDocument(components: ComponentDocs, options?: BuildComponentApiDocumentOptions): ComponentApiDocument;
+
+export declare function cli(process: NodeJS.Process): Promise<void>;
+
+type SveldOptions = SveldRuntimeOptions;
+
+export interface SveldResult {
+    /** Diagnostics from this run. */
+    diagnostics: SveldDiagnostic[];
+    /** Populated when `check` is enabled: the API diff against the committed snapshot. */
+    check?: CheckResult;
+    /** Parse errors for components that failed to parse (empty unless `failFast` is disabled and a component errors). */
+    errors: ComponentParseError[];
+    /**
+     * Suggested process exit code for this run, using the same mapping as the
+     * CLI (a breaking `check` result wins over `strict` diagnostics): `0` on
+     * success, `3` on a breaking API change, `4` when `strict` diagnostics
+     * exist. `sveld()` never mutates `process.exitCode` itself; assign this
+     * value yourself if you want the process to exit non-zero.
+     */
+    exitCode: 0 | 3 | 4;
+}
+
+export declare function sveld(opts?: SveldOptions): Promise<SveldResult>;
+
+type WriterComponentSet = "exported" | "all";
+
+export interface OutputWriter<TOptions = unknown> {
+    name: string;
+    /** Which component set this writer expects — see {@link WriterComponentSet}. @default "exported" */
+    componentSet?: WriterComponentSet;
+    /**
+     * `options` always carries `dryRun: true` under `sveld --dry-run` (or
+     * `{ dryRun: true }` from the programmatic API), alongside whatever
+     * `TOptions` fields the writer defines. `write` must check it and skip
+     * touching disk; sveld does not do this for you. A thrown error (sync or
+     * async) is re-thrown by the caller as `sveld: writer "<name>" failed: ...`
+     * with the original error as `cause`.
+     */
+    write(components: ComponentDocs, options: TOptions): Promise<unknown> | unknown;
+}
+
+export interface RegisterWriterOptions {
+    /** Overwrite an existing writer registered under the same `name` instead of throwing. @default false */
+    replace?: boolean;
+}
+
+export declare function registerWriter<TOptions = unknown>(writer: OutputWriter<TOptions>, options?: RegisterWriterOptions): void;
+
+export declare function getWriter(name: string): OutputWriter<unknown> | undefined;
+
+export declare function listWriters(): OutputWriter<unknown>[];