sveld 0.37.9 → 0.38.0

package/lib/index.d.ts

@@ -1,8 +1,51 @@
-/// <reference types="node" />
+import type { Property } from "estree";
 
-import type { Node, Property } from "estree";
+import type { Dirent } from "node:fs";
 
-import type { FunctionDeclaration, VariableDeclaration } from "estree";
+import { type Program } from "acorn";
+
+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;
@@ -76,31 +119,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[];
     /**
@@ -110,6 +140,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";
@@ -124,25 +169,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 {
@@ -481,154 +507,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";
 
 export type SveldDiagnosticSeverity = "error" | "warning";
 
@@ -735,11 +614,6 @@ interface GenerateBundleOptions {
      * 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;
     /**
@@ -759,11 +633,6 @@ interface GenerateBundleOptions {
      * 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;
@@ -774,16 +643,6 @@ interface GenerateBundleOptions {
     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;
@@ -796,84 +655,75 @@ 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 {
+interface EntryExport {
+    name: string;
+    kind: "const" | "let" | "var" | "function" | "class" | "type" | "interface" | "enum";
     /**
-     * `"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`).
+     * 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.
      */
-    format?: "class" | "component";
+    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[];
+
+export interface SveldRuntimeOptions extends PluginSveldOptions {
+    /** Print unresolved-type diagnostics to stderr. */
+    reportDiagnostics?: boolean;
     /**
-     * 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.
+     * 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.
      */
-    exportTypes?: boolean | {
-        props?: boolean;
-        exports?: boolean;
-        typedefs?: boolean;
-        contexts?: boolean;
-    };
-    /** @internal Set by `writeTsDefinitions` for `@extends` targets; overrides `exportTypes.props`. */
-    forceExportProps?: boolean;
+    strict?: boolean | "errors";
     /**
-     * Templates for generated type names. `{name}` is replaced with the
-     * component's module name. Defaults: `"{name}Props"`, `"{name}Exports"`.
+     * 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.
      */
-    typeNames?: {
-        props?: string;
-        exports?: string;
-    };
+    check?: boolean | 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.
+     * Minimum bump `--check` fails the run (exit `3`) on: `"major"` (default,
+     * preserves prior behavior), `"minor"`, or `"patch"`.
      */
-    comments?: "all" | "descriptions" | "none";
+    checkLevel?: "major" | "minor" | "patch";
+    /** Suppress writer progress logs (`created "..."` / `unchanged "..."`). */
+    quiet?: boolean;
     /**
-     * `"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.
+     * Print the single selected `json` / `markdown` document to stdout
+     * instead of writing it to disk. Requires exactly one of those two
+     * outputs; CLI-only (the Vite plugin ignores it).
      */
-    propsDeclaration?: "type" | "interface";
+    stdout?: boolean;
     /**
-     * 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
+     * Output format for the `--check` report and the `--report-diagnostics` /
+     * `--strict` diagnostics summary: `"text"` (default) or `"json"`.
+     * Channels are unchanged, the check report on stdout and diagnostics on
+     * stderr. CLI-only; `sveld()` ignores `format` for its own console output.
      */
-    inline?: false | "local" | "all";
-    /** @internal Set by `writeTsDefinitions` from `GenerateBundleResult.inlinedTypesByFilePath` when `inline` resolved something for this component. */
-    inlined?: InlinedTypes;
+    format?: "text" | "json";
 }
 
-interface PluginSveldOptions extends Pick<GenerateBundleOptions, "resolveTypes" | "cache" | "checkExamples" | "diagnostics"> {
+export type SveldConfig = SveldRuntimeOptions;
+
+export declare function defineConfig(config: SveldConfig): SveldConfig;
+
+interface PluginSveldOptions extends Pick<GenerateBundleOptions, "cache" | "checkExamples" | "diagnostics"> {
     /**
      * Specify the entry point to uncompiled Svelte source.
      * If not provided, sveld will use the "svelte" field from package.json.
@@ -893,23 +743,11 @@ interface PluginSveldOptions extends Pick<GenerateBundleOptions, "resolveTypes"
     /** Record consts, functions, and types from the entry barrel. Off by default. */
     documentExports?: boolean;
     types?: boolean;
-    typesOptions?: Partial<Omit<WriteTsDefinitionsOptions, "inputDir">>;
+    typesOptions?: TypesOptions;
     json?: boolean;
-    jsonOptions?: Partial<Omit<WriteJsonOptions, "inputDir">>;
+    jsonOptions?: JsonOptions;
     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>;
+    markdownOptions?: MarkdownOptions;
     /**
      * Abort the entire run when a single component fails to parse.
      * When `false` (the default), parse failures are collected as diagnostics
@@ -919,9 +757,10 @@ interface PluginSveldOptions extends Pick<GenerateBundleOptions, "resolveTypes"
     /**
      * 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.
+     * (adding/removing an export), a module a component reads a value from,
+     * or a non-`.svelte` file a component names via `@extendProps` /
+     * `@extends`. Only the edited components and those that read an edited
+     * module are re-parsed.
      * @default false
      */
     watch?: boolean;
@@ -956,27 +795,18 @@ interface SveldPlugin {
 
 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;
+export interface JsonOptions {
     /**
-     * @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.
+     * Path (relative to the project root) for the single combined JSON
+     * document. Ignored when `outDir` is set.
+     * @default "COMPONENT_API.json"
      */
-    entryExports?: EntryExports;
+    outFile?: string;
+    /**
+     * Emit one `<ComponentName>.api.json` file per component into this
+     * directory instead of the single combined `outFile`.
+     */
+    outDir?: string;
     /**
      * Include `source`/`componentCommentSource` position ranges in the
      * output. These are the bulk of a large component library's
@@ -986,52 +816,36 @@ interface WriteJsonOptions {
      * @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;
+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;
 }
 
-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. */
+interface BuildComponentApiDocumentOptions {
+    /** Entry-barrel exports when `documentExports` is on. */
     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;
+export declare function buildComponentApiDocument(components: ComponentDocs, options?: BuildComponentApiDocumentOptions): ComponentApiDocument;
+
+export interface MarkdownOptions {
+    /**
+     * Path (relative to the project root) for the single combined Markdown
+     * document. Ignored when `outDir` is set.
+     * @default "COMPONENT_INDEX.md"
+     */
+    outFile?: string;
     /**
      * Emit one `<ModuleName>.md` file per component into this directory,
      * plus an index `README.md` linking to each, instead of the single
@@ -1040,33 +854,10 @@ interface WriteMarkdownOptions {
      */
     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.
+     * Called every time a heading, quote, paragraph, divider, or raw block is
+     * appended to the document, to inject extra content.
      */
-    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;
+    onAppend?: (type: AppendType, document: MarkdownDocument, components: ComponentDocs) => void;
 }
 
 type AppendType = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "quote" | "p" | "divider" | "raw";
@@ -1077,30 +868,23 @@ interface TocLine {
     raw: string;
 }
 
-interface WriterOptions {
-    /** Report the resolved path to stdout instead of writing. Set by `sveld --dry-run`. */
-    dryRun?: boolean;
+type MarkdownAppendCallback = (type: AppendType, document: MarkdownDocument) => void;
+
+interface MarkdownDocumentOptions {
+    onAppend?: MarkdownAppendCallback;
 }
 
-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>;
+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;
+    tableOfContents(): this;
+    end(): string;
 }
 
 type TransformContext = {
@@ -1112,34 +896,19 @@ type TransformContext = {
     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>;
+export interface TypesOptions extends WriteTsDefinitionOptions {
     /**
-     * @internal See `cache`. For components whose output was resolved from
-     * other files, so their text is keyed on their content too.
+     * Output directory for generated `.d.ts` files, relative to the project
+     * root.
+     * @default "types"
      */
-    crossFileResolvedPathByFilePath?: Map<string, string>;
+    outDir?: string;
     /**
-     * @internal From `GenerateBundleResult.inlinedTypesByFilePath`, populated when
-     * `typesOptions.inline` is `"local"`/`"all"`. Lookups use `component.filePath`.
+     * Raw text prepended to the generated `index.d.ts` barrel, e.g. a license
+     * header.
+     * @default ""
      */
-    inlinedTypesByFilePath?: Map<string, InlinedTypes>;
+    preamble?: string;
     /**
      * 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
@@ -1147,159 +916,24 @@ interface WriteTsDefinitionsOptions extends WriteTsDefinitionOptions {
      */
     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.
+     * Also re-export generated types from `index.d.ts`: each component's
+     * `Props` type, and its `Exports` type under `format: "component"`.
      */
-    indexTypes?: boolean | {
-        props?: boolean;
-        exports?: boolean;
-        typedefs?: boolean;
-        contexts?: boolean;
-    };
+    indexTypes?: 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";
+interface WriteTsDefinitionOptions {
     /**
-     * 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.
+     * `"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`).
      */
-    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;
+    format?: "class" | "component";
 }
 
-export declare function buildComponentApiDocument(components: ComponentDocs, options?: BuildComponentApiDocumentOptions): ComponentApiDocument;
-
-export declare function cli(process: NodeJS.Process): Promise<void>;
-
 type SveldOptions = SveldRuntimeOptions;
 
 export interface SveldResult {
@@ -1310,41 +944,19 @@ export interface SveldResult {
     /** 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.
+     * The component API document for the exported components, exactly as the
+     * `json` writer writes `COMPONENT_API.json`. Populated whether or not
+     * `json` is enabled, so custom output can be rendered from it directly.
      */
-    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;
+    document: ComponentApiDocument;
     /**
-     * `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`.
+     * Suggested process exit code for this run, using the same mapping as the
+     * CLI (see {@link resolveExitCode}). `sveld()` never mutates `process.exitCode` itself; assign this
+     * value yourself if you want the process to exit non-zero.
      */
-    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;
+    exitCode: ExitCode;
 }
 
-export declare function registerWriter<TOptions = unknown>(writer: OutputWriter<TOptions>, options?: RegisterWriterOptions): void;
+type ExitCode = 0 | 1 | 2 | 3 | 4;
 
-export declare function getWriter(name: string): OutputWriter<unknown> | undefined;
-
-export declare function listWriters(): OutputWriter<unknown>[];
+export declare function sveld(opts?: SveldOptions): Promise<SveldResult>;