sveld 0.37.9 → 0.38.0

package/lib/browser.d.ts

@@ -1,6 +1,8 @@
-import type { Node, Property } from "estree";
+import type { Property } from "estree";
 
-import type { FunctionDeclaration, VariableDeclaration } from "estree";
+import type { Dirent } from "node:fs";
+
+import { type Program } from "acorn";
 
 declare const brand: unique symbol;
 
@@ -12,6 +14,49 @@ export type NormalizedPath = Brand<string, "NormalizedPath">;
 
 export declare function asNormalizedPath(path: string): NormalizedPath;
 
+interface ComponentParserDiagnostics {
+    moduleName: string;
+    filePath: string;
+}
+
+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;
+    /**
+     * Resets parser state for reuse between parses.
+     *
+     * @example
+     * ```ts
+     * parser.parseSvelteComponent(source1, diagnostics1);
+     * parser.cleanup();
+     * parser.parseSvelteComponent(source2, diagnostics2);
+     * ```
+     */
+    cleanup(): void;
+    /**
+     * @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;
+    /**
+     * Like {@link parseSvelteComponent}, but returns the candidates only a
+     * pass with file access can resolve beside the component rather than
+     * inside its metadata.
+     */
+    parse(source: string, diagnostics: ComponentParserDiagnostics): ComponentParseResult;
+}
+
 interface JsDocPassthroughTag {
     name: string;
     body: string;
@@ -84,31 +129,18 @@ interface PendingDispatchEscapeCandidate {
     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`. */
+interface PendingCrossFileCandidates {
+    /** Unresolved CallExpression defaults. */
     pendingCallDefaultCandidates?: PendingCallDefaultCandidate[];
-    /** Imported-identifier defaults for the cross-file pass in `generateBundle`. */
+    /** Imported-identifier defaults. */
     pendingConstDefaultCandidates?: PendingConstDefaultCandidate[];
-    /** Unresolved `setContext` import keys for the cross-file pass in `generateBundle`. */
+    /** Unresolved `setContext` import keys. */
     pendingContextKeyCandidates?: PendingContextKeyCandidate[];
-    /** Dispatchers passed to imported functions, for the cross-file pass in `generateBundle`. */
+    /** Dispatchers passed to imported functions. */
     pendingDispatchEscapeCandidates?: PendingDispatchEscapeCandidate[];
     /**
      * `event-no-source` diagnostics held back while the dispatcher escapes to
-     * imported functions: `generateBundle` keeps those the functions don't dispatch.
+     * imported functions: the cross-file pass keeps those the functions don't dispatch.
      */
     deferredEventNoSourceDiagnostics?: SveldDiagnostic[];
     /**
@@ -118,6 +150,21 @@ interface ParsedComponentTypeScriptMetadata {
     untypedJsDocEventNames?: string[];
 }
 
+interface ParsedComponentTypeScriptMetadata extends PendingCrossFileCandidates {
+    canonicalPropsType?: string;
+    canonicalPropNames: string[];
+    localTypeDeclarations: string[];
+    /** Types the module script exports (`export interface Item`), emitted with `export`. */
+    moduleTypeDeclarations?: string[];
+    typeImportStatements: string[];
+}
+
+interface ComponentParseResult {
+    component: ParsedComponent;
+    /** Undefined when the component depends on no other file's contents. */
+    pending?: PendingCrossFileCandidates;
+}
+
 type SyntaxMode = "legacy" | "runes";
 
 type ScriptLanguage = "js" | "ts";
@@ -132,25 +179,6 @@ interface ComponentPropDefaultValue {
     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 {
@@ -489,154 +517,7 @@ interface ParsedComponent {
     [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 SveldDiagnosticKind = "prop-unknown-type" | "context-any-type" | "slot-missing-type" | "event-no-source" | "dispatch-escapes" | "example-compile-error" | "example-syntax-error" | "syntax-skipped" | "type-syntax-error" | "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" | "cross-file-unresolved" | "export-ambiguous";
 
 type SveldDiagnosticSeverity = "error" | "warning";
 
@@ -680,95 +561,6 @@ export interface ComponentDocApi extends ParsedComponent {
 
 export type ComponentDocs = Map<string, ComponentDocApi>;
 
-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[];
-}
-
-type CommentLevel = "all" | "descriptions" | "none";
-
-export declare function formatTsProps(props?: string): string;
-
-export declare function getTypeDefs(def: Pick<ComponentDocApi, "typedefs">, emit?: {
-    export: boolean;
-}, commentLevel?: CommentLevel): string;
-
-export declare function getContextDefs(def: Pick<ComponentDocApi, "contexts" | "generics">, emit?: {
-    export: boolean;
-}, commentLevel?: CommentLevel): string;
-
-export 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;
-}
-
-export declare function writeTsDefinition(component: ComponentDocApi, options?: WriteTsDefinitionOptions): string;
-
 interface EntryExport {
     name: string;
     kind: "const" | "let" | "var" | "function" | "class" | "type" | "interface" | "enum";
@@ -794,151 +586,28 @@ interface EntryExport {
 
 type EntryExports = EntryExport[];
 
-export interface CemType {
-    text: string;
-}
-
-export interface CemClassField {
-    kind: "field";
-    name: string;
-    type?: CemType;
-    default?: string;
-    description?: string;
-    deprecated?: DeprecatedValue;
-    /** Present, and `true`, for an `export const` prop. */
-    readonly?: true;
-}
-
-interface CemParameter {
-    name: string;
-    type?: CemType;
-    optional?: true;
-    rest?: true;
-}
-
-interface CemClassMethod {
-    kind: "method";
-    name: string;
-    static: boolean;
-    parameters?: CemParameter[];
-    return?: {
-        type: CemType;
-    };
-    description?: string;
-    deprecated?: DeprecatedValue;
-}
-
-export interface CemAttribute {
-    name: string;
-    fieldName: string;
-    type?: CemType;
-    default?: string;
-    description?: string;
-    /** Present, and `true`, when the prop's `customElement` config sets `reflect: true`. */
-    reflects?: true;
-}
-
-interface CemCssPart {
-    name: string;
-    description?: string;
-}
-
-interface CemCssCustomProperty {
-    /** Includes the leading `--`. */
-    name: string;
-    type?: CemType;
-    default?: string;
-    description?: string;
-}
-
-export interface CemEvent {
-    name: string;
-    type: CemType;
-    description?: string;
-    deprecated?: DeprecatedValue;
-}
-
-export interface CemSlot {
-    name: string;
-    description?: string;
-    deprecated?: DeprecatedValue;
-}
-
-export interface CemClassDeclaration {
-    kind: "class";
-    name: string;
-    description?: string;
-    members: Array<CemClassField | CemClassMethod>;
-    attributes: CemAttribute[];
-    events: CemEvent[];
-    slots: CemSlot[];
-    /** From component-level `@csspart` JSDoc tags. */
-    cssParts?: CemCssPart[];
-    /** From component-level `@cssprop`/`@cssproperty` JSDoc tags. */
-    cssProperties?: CemCssCustomProperty[];
-    /** Only present when the source component sets `<svelte:options customElement="..." />`. */
-    tagName?: string;
-    /** Only present when the source component sets `<svelte:options customElement="..." />`. */
-    customElement?: true;
-}
-
-export interface CemJavaScriptExport {
-    kind: "js";
-    name: string;
-    declaration: {
-        name: string;
-        module: string;
-    };
-}
+export declare const COMPONENT_API_SCHEMA_VERSION = 1;
 
-export interface CemCustomElementExport {
-    kind: "custom-element-definition";
-    name: string;
-    declaration: {
+export interface ComponentApiDocument {
+    schemaVersion: 1;
+    generator: {
         name: string;
-        module: string;
+        version: string;
+        svelteVersion: string;
     };
+    total: number;
+    components: ComponentDocApi[];
+    /** Only when `documentExports` is on. */
+    totalExports?: number;
+    exports?: EntryExports;
 }
 
-export type CemExport = CemJavaScriptExport | CemCustomElementExport;
-
-export interface CemModule {
-    kind: "javascript-module";
-    path: string;
-    declarations: CemClassDeclaration[];
-    exports: CemExport[];
-}
-
-export interface CustomElementsManifest {
-    schemaVersion: "1.0.0";
-    modules: CemModule[];
-}
-
-export interface BuildCustomElementsManifestOptions {
-    /** Resolves each component's manifest `path`. Defaults to the component's `filePath` as-is. */
-    resolveModulePath?: (component: ComponentDocApi) => string;
-}
-
-export declare function buildCustomElementsManifest(components: ComponentDocs, options?: BuildCustomElementsManifestOptions): CustomElementsManifest;
-
-type OnAppend = (type: AppendType, document: WriterMarkdown) => void;
-
-interface MarkdownOptions {
-    onAppend?: OnAppend;
+export interface BuildComponentApiDocumentOptions {
+    /** Entry-barrel exports when `documentExports` is on. */
+    entryExports?: EntryExports;
 }
 
-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;
-}
+export declare function buildComponentApiDocument(components: ComponentDocs, options?: BuildComponentApiDocumentOptions): ComponentApiDocument;
 
 export type AppendType = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "quote" | "p" | "divider" | "raw";
 
@@ -948,21 +617,18 @@ export interface TocLine {
     raw: string;
 }
 
-export interface MarkdownWriterBase {
-    sourceParts: string[];
-    hasToC: boolean;
-    toc: TocLine[];
-    appendLineBreaks(): this;
-    append(type: AppendType, raw?: string): this;
-    tableOfContents(): this;
-    end(): string;
-    get source(): string;
+type MarkdownAppendCallback = (type: AppendType, document: MarkdownDocument) => void;
+
+interface MarkdownDocumentOptions {
+    onAppend?: MarkdownAppendCallback;
 }
 
-declare class MarkdownWriterBaseImpl implements MarkdownWriterBase {
+export declare class MarkdownDocument {
     sourceParts: string[];
     hasToC: boolean;
     toc: TocLine[];
+    onAppend?: MarkdownAppendCallback;
+    constructor(options?: MarkdownDocumentOptions);
     get source(): string;
     appendLineBreaks(): this;
     append(type: AppendType, raw?: string): this;
@@ -970,70 +636,40 @@ declare class MarkdownWriterBaseImpl implements MarkdownWriterBase {
     end(): 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>;
+export declare class BrowserWriterMarkdown extends MarkdownDocument {
 }
 
-export declare const COMPONENT_API_SCHEMA_VERSION = 1;
+export type MarkdownWriterBase = MarkdownDocument;
 
-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;
-}
+export declare function formatTsProps(props?: string): string;
 
-export interface BuildComponentApiDocumentOptions {
-    /** Entry-barrel exports when `documentExports` is on. */
-    entryExports?: EntryExports;
-}
+export declare function getTypeDefs(def: Pick<ComponentDocApi, "typedefs">): string;
 
-export declare function buildComponentApiDocument(components: ComponentDocs, options?: BuildComponentApiDocumentOptions): ComponentApiDocument;
+export declare function getContextDefs(def: Pick<ComponentDocApi, "contexts" | "generics">): string;
 
-interface MarkdownDocument {
-    append(type: AppendType, raw?: string): MarkdownDocument;
-    tableOfContents(): MarkdownDocument;
+export 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";
 }
 
-export declare function renderComponentsToMarkdown(document: MarkdownDocument, components: ComponentDocs, entryExports?: EntryExports): void;
+export declare function writeTsDefinition(component: ComponentDocApi, options?: WriteTsDefinitionOptions): string;
 
-export declare class BrowserWriterMarkdown extends MarkdownWriterBaseImpl {
-    onAppend?: OnAppend;
-    constructor(options: MarkdownOptions);
-    append(type: AppendType, raw?: string): this;
+interface MarkdownRenderTarget {
+    append(type: AppendType, raw?: string): MarkdownRenderTarget;
+    tableOfContents(): MarkdownRenderTarget;
 }
 
+export declare function renderComponentsToMarkdown(document: MarkdownRenderTarget, components: ComponentDocs, entryExports?: EntryExports): void;
+
 export interface WriteMarkdownCoreOptions {
-    onAppend?: (type: AppendType, document: BrowserWriterMarkdown, components: ComponentDocs) => void;
+    onAppend?: (type: AppendType, document: MarkdownDocument, components: ComponentDocs) => void;
 }
 
 export declare function writeMarkdownCore(components: ComponentDocs, options?: WriteMarkdownCoreOptions): string;