sveld 0.34.1 → 0.35.0

package/lib/load-config.d.ts

@@ -1,9 +1,27 @@
 import type { PluginSveldOptions } from "./plugin";
+/**
+ * Options shared by the config file, the CLI, and the programmatic `sveld()`
+ * API. Superset of `PluginSveldOptions` with the CLI-oriented flags that only
+ * make sense as part of a full `sveld` run (not the Vite/Rollup plugin).
+ */
+export interface SveldRuntimeOptions extends PluginSveldOptions {
+    /** Print unresolved-type diagnostics to stderr. */
+    reportDiagnostics?: boolean;
+    /** Exit code 1 when diagnostics exist. Implies `reportDiagnostics`. */
+    strict?: boolean;
+    /**
+     * 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 `1` on a breaking change. Pass a
+     * string for a custom snapshot path.
+     */
+    check?: boolean | string;
+}
 /**
  * Public shape of a `sveld.config.{js,ts,mjs}` file. Identical to the options
- * accepted by the Vite/Rollup plugin and the CLI.
+ * accepted by the CLI and the programmatic `sveld()` API.
  */
-export type SveldConfig = PluginSveldOptions;
+export type SveldConfig = SveldRuntimeOptions;
 /** Config file names probed at the project root. First existing file wins. */
 export declare const CONFIG_FILE_NAMES: readonly ["sveld.config.js", "sveld.config.mjs", "sveld.config.ts"];
 /**

package/lib/parser/bindings.d.ts

@@ -0,0 +1,6 @@
+import type ComponentParser from "../ComponentParser";
+import type { ParserContext } from "./context";
+/** Pull `propName`'s type out of an object type string like `{ value: string; other: number }`. */
+export declare function extractPropertyType(typeStr: string, propName: string): string | undefined;
+/** Resolve `obj.prop` by looking up `obj`'s type and calling {@link extractPropertyType}. */
+export declare function resolveMemberExpressionType(ctx: ParserContext, parser: ComponentParser, expr: unknown): string | undefined;

package/lib/parser/context.d.ts

@@ -0,0 +1,110 @@
+import type { FunctionDeclaration, VariableDeclaration } from "estree";
+import type { compile } from "svelte/compiler";
+import type { ComponentContext, ComponentElement, ComponentEvent, ComponentGenerics, ComponentInlineElement, ComponentProp, ComponentPropBindings, ComponentSlot, Extends, LegacyAstRoot, LexicalScope, LocalTypeDeclaration, RestProps, RunesPropsDeclarationMetadata, ScriptLanguage, SourceRange, SyntaxMode, TypeDef, TypeImportBinding } from "../ComponentParser";
+import type { SveldDiagnostic } from "../diagnostics";
+/** Per-parse mutable state for {@link ComponentParser}. Reset via {@link createParserContext} on each parse. */
+export interface ParserContext {
+    /** Whether the component uses legacy or runes syntax according to compiler metadata */
+    syntaxMode: SyntaxMode;
+    /** Language used by the component's instance or module script, when supported */
+    scriptLanguage?: ScriptLanguage;
+    /** Raw source code of the Svelte component being parsed */
+    source?: string;
+    /** Compiled Svelte code containing extracted variables and AST */
+    compiled?: ReturnType<typeof compile>;
+    /** Parsed abstract syntax tree from the Svelte compiler */
+    parsed?: LegacyAstRoot;
+    /** Cached `ctx.source` split on newlines */
+    sourceLinesCache?: string[];
+    /** Cached 0-based source offsets for the start of each line */
+    sourceLineStartOffsetsCache?: number[];
+    /** Rest props configuration (e.g., `$$restProps`) if present in component */
+    rest_props?: RestProps;
+    /** Component extension information (e.g., `extends` attribute) */
+    extends?: Extends;
+    /** Custom-element tag name from `<svelte:options customElement="x-foo" />` (or the object form's `tag`), when present */
+    customElementTag?: string;
+    /** Component-level description extracted from `@component` HTML comment */
+    componentComment?: string;
+    /** Source range for the `@component` HTML comment, when available */
+    componentCommentSource?: SourceRange;
+    /** Component generic type parameters (null if no generics) */
+    generics: ComponentGenerics;
+    /**
+     * Raw `generics` script attribute value (with `lang="ts"` already validated),
+     * held until the end of parsing so it can override any `@generics`/`@template`
+     * JSDoc-derived {@link ParserContext.generics}.
+     */
+    scriptGenericsAttribute?: {
+        value: string;
+        source?: SourceRange;
+    };
+    /** Diagnostics for the parse in progress. */
+    readonly diagnosticRecords: SveldDiagnostic[];
+    /** File path tagged onto each diagnostic. */
+    componentFilePath: string;
+    /** Map of component props keyed by prop name */
+    readonly props: Map<string, ComponentProp>;
+    /** Map of module exports (functions/variables exported from script) keyed by name */
+    readonly moduleExports: Map<string, ComponentProp>;
+    /** Maps local binding names back to their public prop names */
+    readonly propLocalToPublicName: Map<string, string>;
+    /** Set of reactive variable names found in the component */
+    readonly reactive_vars: Set<string>;
+    /** Function declarations in the component script, by name */
+    readonly funcDecls: Map<string, FunctionDeclaration>;
+    /** Set of all variable declarations found in the component script */
+    readonly vars: Set<VariableDeclaration>;
+    /** Per-declarator type metadata extracted from modern AST `$props()` annotations */
+    readonly runesPropsDeclarationMetadataByDeclaratorStart: Map<number, RunesPropsDeclarationMetadata>;
+    /** Typed `$props()` declarations discovered in source order */
+    readonly typedRunesPropsDeclarations: RunesPropsDeclarationMetadata[];
+    /** Explicit TypeScript prop annotations for legacy `export let` declarations keyed by local name */
+    readonly explicitPropTypesByName: Map<string, string>;
+    /** Type-only imports keyed by their local binding names */
+    readonly typeImportBindingsByLocalName: Map<string, TypeImportBinding>;
+    /** Local interface/type declarations keyed by type name */
+    readonly localTypeDeclarationsByName: Map<string, LocalTypeDeclaration>;
+    /** Tracks identifier bindings that capture the entire `$props()` object */
+    readonly wholePropsLocals: Set<string>;
+    /** Tracks `$props()` bindings that are used as spread/rest props */
+    readonly restPropLocals: Set<string>;
+    /** Component-level lexical scope shared by instance script and template */
+    readonly componentScope: LexicalScope;
+    /** Precomputed lexical scopes for nested AST nodes */
+    scopeDeclarations: WeakMap<object, LexicalScope>;
+    /** Active lexical scopes while walking the component AST */
+    readonly activeScopes: LexicalScope[];
+    /** Map of component slots keyed by slot name (null for default slot) */
+    readonly slots: Map<string | null, ComponentSlot>;
+    /** Tracks prop locals that are used as snippet/render props */
+    readonly snippetPropLocals: Set<string>;
+    /** @template tags in a @slot/@snippet block (no @extends), held until finalization. */
+    deferredSlotBlockGenerics: Array<{
+        name: string;
+        constraint: string;
+    }>;
+    /** Map of component events (dispatched events) keyed by event name */
+    readonly events: Map<string, ComponentEvent>;
+    /** Map of event descriptions extracted from JSDoc comments keyed by event name */
+    readonly eventDescriptions: Map<string, string | undefined>;
+    /** Map of forwarded events (events forwarded from child components) keyed by event name */
+    readonly forwardedEvents: Map<string, ComponentInlineElement | ComponentElement>;
+    /** `@event` names from JSDoc, checked against dispatches at end of parse. */
+    readonly jsDocEventNames: Set<string>;
+    /** Source range of each `@event` JSDoc tag, keyed by event name, for `event-no-source` diagnostics. */
+    readonly jsDocEventSources: Map<string, SourceRange | undefined>;
+    /** Map of prop bindings (e.g., `bind:value`) keyed by prop name */
+    readonly bindings: Map<string, ComponentPropBindings>;
+    /** Map of component contexts (created with `setContext`) keyed by context name */
+    readonly contexts: Map<string, ComponentContext>;
+    /** Map of type definitions (typedefs) extracted from JSDoc comments keyed by type name */
+    readonly typedefs: Map<string, TypeDef>;
+    /** Memoized `findVariableTypeAndDescription` results */
+    variableInfoCache: Map<string, {
+        type: string;
+        description?: string;
+    }>;
+}
+/** Fresh {@link ParserContext}. Keep in sync with new fields on {@link ParserContext}. */
+export declare function createParserContext(): ParserContext;

package/lib/parser/contexts.d.ts

@@ -0,0 +1,19 @@
+import type { CallExpression, NewExpression } from "estree";
+import type { Node } from "estree-walker";
+import type ComponentParser from "../ComponentParser";
+import type { ComponentContext } from "../ComponentParser";
+import type { ParserContext } from "./context";
+/** Turn `simple-modal` into `SimpleModalContext`. */
+export declare function generateContextTypeName(key: string): string;
+/** Build a {@link ComponentContext} from an object literal or variable reference. */
+export declare function parseContextValue(ctx: ParserContext, parser: ComponentParser, node: Node, key: string): ComponentContext | null;
+/** Static description from `Symbol()` / `Symbol.for()`, or `""` when unknown. Returns `null` for other calls. */
+export declare function resolveSymbolKeyDescription(node: CallExpression | NewExpression): string | null;
+/**
+ * Resolve a `setContext` key to the string used in `{PascalCase}Context`.
+ * Accepts literals, static templates, `const` chains (depth 5), and `Symbol()`.
+ * Description-less symbols fall back to the binding name.
+ */
+export declare function resolveContextKey(ctx: ParserContext, keyArg: unknown, depth?: number): string | null;
+/** Parse `setContext(key, value)` when the key resolves statically. */
+export declare function parseSetContextCall(ctx: ParserContext, parser: ComponentParser, node: Node, _parent?: Node): void;

package/lib/parser/diagnostics.d.ts

@@ -0,0 +1,8 @@
+import type { SourceRange } from "../ComponentParser";
+import type { SveldDiagnosticKind } from "../diagnostics";
+import type { ParserContext } from "./context";
+/**
+ * Appends a diagnostic (a place sveld had to guess a type) to `ctx.diagnosticRecords`,
+ * tagged with the file path of the component currently being parsed.
+ */
+export declare function recordDiagnostic(ctx: ParserContext, kind: SveldDiagnosticKind, name: string, message: string, source?: SourceRange): void;

package/lib/parser/events.d.ts

@@ -0,0 +1,23 @@
+import type { CallExpression } from "estree";
+import type { DispatchedEvent } from "../ComponentParser";
+import type { ParserContext } from "./context";
+/** Render a literal event-detail value (from a `dispatch()`/`CustomEvent` argument) as TS type text, quoting strings. */
+export declare function literalDetailToTypeText(value: unknown): string;
+/** Merge or add a dispatched event. Detail defaults to `null` when the dispatch has no argument and no `@event` detail. */
+export declare function addDispatchedEvent(ctx: ParserContext, { name, detail, has_argument, description, deprecated, tags, source, }: Pick<DispatchedEvent, "name" | "description" | "deprecated" | "tags" | "source"> & {
+    detail: string;
+    has_argument: boolean;
+}): void;
+/**
+ * Detect `$host().dispatchEvent(new CustomEvent("name", { detail }))` (or `new Event(...)`) and
+ * record it as a dispatched event, mirroring `createEventDispatcher()` detection.
+ */
+export declare function parseHostDispatchEventCall(ctx: ParserContext, dispatchEventCall: CallExpression): string | undefined;
+/** Build an inline object type (with optional JSDoc per property) for event details or typedefs. */
+export declare function buildEventDetailFromProperties(properties: Array<{
+    name: string;
+    type: string;
+    description?: string;
+    optional?: boolean;
+    default?: string;
+}>, _eventName?: string, multiline?: boolean): string;

package/lib/parser/generics.d.ts

@@ -0,0 +1,24 @@
+import type { ComponentGenerics } from "../ComponentParser";
+import type { ParserContext } from "./context";
+/**
+ * Splits a string on top-level commas, ignoring commas nested inside
+ * `<>`, `()`, `[]`, or `{}`. Shared by the `generics` script attribute parser
+ * and the TypeScript definition writer, both of which must separate generic
+ * constraint declarations that may themselves contain commas (e.g. `Value extends Record<string, any>`).
+ */
+export declare function splitTopLevelCommas(value: string): string[];
+/**
+ * Parses the `generics` script attribute value (a TypeScript type-parameter
+ * list, e.g. `"Row extends DataTableRow = DataTableRow, Header"`) into the
+ * same `[names, constraints]` tuple the `@generics`/`@template` JSDoc tags produce.
+ */
+export declare function parseGenericsAttribute(value: string): ComponentGenerics;
+/**
+ * Extends `referencedImportedTypes`/`referencedLocalTypes` with any type names
+ * mentioned in the `generics` script attribute (e.g. the `DataTableRow` in
+ * `Row extends DataTableRow = DataTableRow`). These names only appear in the
+ * raw attribute string, not in the `$props()` type annotation AST that
+ * {@link collectReferencedTypeDependencies} normally walks, so without this
+ * they would never get hoisted into the emitted `.d.ts`.
+ */
+export declare function collectGenericsAttributeTypeDependencies(ctx: ParserContext, referencedImportedTypes: Set<string>, referencedLocalTypes: Set<string>): void;

package/lib/parser/jsdoc.d.ts

@@ -0,0 +1,59 @@
+import { parse as parseComment } from "comment-parser";
+import type ComponentParser from "../ComponentParser";
+import type { ComponentPropBinding, ComponentPropParam, DeprecatedValue, JsDocPassthroughTag } from "../ComponentParser";
+import type { ParserContext } from "./context";
+export declare function formatComment(comment: string): string;
+/** Split JSDoc tags into type/param/returns/passthrough buckets. */
+export declare function getCommentTags(parsed: ReturnType<typeof parseComment>): {
+    type: import("comment-parser").Spec | undefined;
+    param: import("comment-parser").Spec[];
+    returns: import("comment-parser").Spec | undefined;
+    binding: ComponentPropBinding | undefined;
+    deprecated: DeprecatedValue | undefined;
+    additional: import("comment-parser").Spec[];
+    passthrough: import("comment-parser").Spec[];
+    description: string;
+};
+/** Last leading comment (JSDoc when present). TypeScript directives are stripped first. */
+export declare function findJSDocComment(leadingComments: unknown[]): {
+    value: string;
+} | undefined;
+export declare function findAdjacentJSDocComment(ctx: ParserContext, leadingComments: unknown[] | undefined, nodeStart: number | undefined): {
+    value: string;
+} | undefined;
+export declare function processNodeJSDoc(ctx: ParserContext, parser: ComponentParser, node: {
+    leadingComments?: unknown[];
+    start?: number;
+} | null | undefined): {
+    type?: string;
+    params?: ComponentPropParam[];
+    returnType?: string;
+    description?: string;
+    binding?: ComponentPropBinding;
+    deprecated?: DeprecatedValue;
+    tags?: JsDocPassthroughTag[];
+} | undefined;
+export declare function processLeadingCommentsJSDoc(ctx: ParserContext, parser: ComponentParser, node: {
+    leadingComments?: unknown[];
+    start?: number;
+} | null | undefined): {
+    type?: string;
+    params?: ComponentPropParam[];
+    returnType?: string;
+    description?: string;
+    binding?: ComponentPropBinding;
+    deprecated?: DeprecatedValue;
+    tags?: JsDocPassthroughTag[];
+} | undefined;
+/** Parse adjacent JSDoc into type, params, returns, description, and passthrough tags. */
+export declare function processJSDocComment(parser: ComponentParser, leadingComments: unknown[]): {
+    type?: string;
+    params?: ComponentPropParam[];
+    returnType?: string;
+    description?: string;
+    binding?: ComponentPropBinding;
+    deprecated?: DeprecatedValue;
+    tags?: JsDocPassthroughTag[];
+} | undefined;
+/** Scan source JSDoc for events, typedefs, callbacks, slots, extends, and generics. */
+export declare function parseCustomTypes(ctx: ParserContext, parser: ComponentParser): void;

package/lib/parser/props.d.ts

@@ -0,0 +1,67 @@
+import type { ArrowFunctionExpression, FunctionDeclaration, FunctionExpression } from "estree";
+import type ComponentParser from "../ComponentParser";
+import type { ComponentProp, ComponentPropParam, ProcessedInitializer } from "../ComponentParser";
+import type { ParserContext } from "./context";
+/** Merge a prop into `ctx.props`, or add it if missing. */
+export declare function addProp(parser: ComponentParser, ctx: ParserContext, prop_name: string, data: ComponentProp): void;
+/** Read value, type, and function-ness from a prop initializer expression. */
+export declare function processInitializer(parser: ComponentParser, ctx: ParserContext, init: unknown, depth?: number): ProcessedInitializer;
+/**
+ * Look up a local variable's initializer AST node by name.
+ * Returns the init node if found, or undefined.
+ */
+export declare function resolveLocalVarInitializer(ctx: ParserContext, name: string): unknown | undefined;
+/**
+ * Look up the initializer for a local `const` by name.
+ *
+ * {@link resolveLocalVarInitializer} also walks `let`/`var`. This method does not.
+ * Props and mutable bindings can change at runtime, so they cannot be context keys.
+ *
+ * @param name - The variable name to look up
+ * @returns The initializer node for a matching `const` binding, or undefined
+ */
+export declare function resolveConstInitializer(ctx: ParserContext, name: string): unknown | undefined;
+/**
+ * Build a function type from `@param`/`@returns` when `@type` is missing.
+ * If JSDoc has no params or return either, try the function `node`, then
+ * `(...args: any[]) => any`.
+ */
+export declare function buildFunctionTypeFromParts(jsdoc?: {
+    params?: ComponentPropParam[];
+    returnType?: string;
+}, node?: FunctionDeclaration | FunctionExpression | ArrowFunctionExpression): string;
+/**
+ * Guess arity and return type for a function default with no JSDoc `@type`.
+ * Explicit `@type`/`@param`/`@returns` on the prop beat this every time.
+ * A default's body is a weak signal for the prop contract. We only read
+ * named params and literal returns. Everything else becomes `any`.
+ */
+export declare function inferFunctionTypeFromNode(node: FunctionDeclaration | FunctionExpression | ArrowFunctionExpression): string;
+/**
+ * Turn params into `name: any`, or use `...args: any[]` when arity is unclear:
+ * no params, destructuring, rest, or defaults.
+ */
+export declare function inferParamsFromNode(node: FunctionDeclaration | FunctionExpression | ArrowFunctionExpression): string;
+/**
+ * Infer return type from literal returns only. Every `return` must agree on
+ * the same primitive. Bare `return;`, no returns, identifiers, calls,
+ * objects, ternaries, async, or generators all become `any`.
+ */
+export declare function inferReturnTypeFromNode(node: FunctionDeclaration | FunctionExpression | ArrowFunctionExpression): string;
+/**
+ * Walk a block body and collect each `return`'s argument, skipping nested
+ * functions. Bare `return;` becomes `null`.
+ */
+export declare function collectReturnArguments(body: unknown): unknown[];
+/**
+ * Map one return expression to `string`, `number`, or `boolean`, or `null`
+ * if it isn't a literal, template literal, or `String`/`Number`/`Boolean` call.
+ */
+export declare function inferReturnPrimitive(expr: unknown): "string" | "number" | "boolean" | null;
+/**
+ * Unwraps `$bindable(...)` calls so defaults are documented as their underlying values.
+ */
+export declare function unwrapBindableInitializer(init: unknown): {
+    init?: unknown;
+    bindable: boolean;
+};

package/lib/parser/rest-props.d.ts

@@ -0,0 +1,6 @@
+import type { RestProps } from "../ComponentParser";
+import type { ParserContext } from "./context";
+/** {@link RestProps} for the parent of a `{...$$restProps}` spread. */
+export declare function createRestPropsFromParent(parent: unknown): RestProps;
+/** Record the first `{...$$restProps}` target on `ctx.rest_props`. */
+export declare function maybeSetRestProps(ctx: ParserContext, parent: unknown): void;

package/lib/parser/runes-props.d.ts

@@ -0,0 +1,18 @@
+import type { VariableDeclaration } from "estree";
+import type ComponentParser from "../ComponentParser";
+import type { ModernRunesTypeNode, RunesPropTypeMetadata } from "../ComponentParser";
+import type { ParserContext } from "./context";
+/** Flatten a runes `$props()` type node into prop name -> metadata, following local aliases and intersections. */
+export declare function buildRunesPropTypeMetadataMap(parser: ComponentParser, ctx: ParserContext, typeNode: ModernRunesTypeNode | undefined, localTypeDeclarations: Map<string, ModernRunesTypeNode>, visitedTypeNames?: Set<string>): Map<string, RunesPropTypeMetadata>;
+/**
+ * Re-parse `ctx.source` in modern AST mode before the legacy walk: type imports,
+ * local types, explicit `export let` annotations, and `$props()` metadata.
+ */
+export declare function buildRunesPropTypeMetadata(parser: ComponentParser, ctx: ParserContext): void;
+/** Top-level `$props()` declarations in runes components. */
+export declare function parseRunesPropsDeclaration(parser: ComponentParser, ctx: ParserContext, node: VariableDeclaration): void;
+/**
+ * Runes-only: fold phantom `@event` entries into matching `on<Event>` callback props
+ * when nothing in the component actually dispatches that event.
+ */
+export declare function normalizeRunesCallbackProps(ctx: ParserContext, actuallyDispatchedEvents: Set<string>): void;

package/lib/parser/scopes.d.ts

@@ -0,0 +1,40 @@
+import type { ArrowFunctionExpression, Expression, FunctionDeclaration, FunctionExpression, Pattern, VariableDeclaration, VariableDeclarator } from "estree";
+import type { Node } from "estree-walker";
+import type ComponentParser from "../ComponentParser";
+import type { LexicalScope, ScopeBinding, ScopeBindingKind } from "../ComponentParser";
+import type { ParserContext } from "./context";
+/** Declares `name` into `scope` unless it's empty/already bound (first declaration wins). */
+export declare function declareScopeBinding(scope: LexicalScope, name: string, binding: ScopeBinding): void;
+/** Resolves `name` to its public prop name by walking active scopes innermost-first. */
+export declare function resolveIdentifierToReactiveProp(ctx: ParserContext, name: string): string | undefined;
+/** Collects all identifier names bound by a destructuring/assignment pattern (or plain expression). */
+export declare function collectPatternIdentifiers(target: Pattern | Expression | null | undefined, names?: Set<string>): Set<string>;
+/** Marks any reactive props referenced by a mutation target (assignment LHS / update argument) as reactive. */
+export declare function markReactivePropsFromMutationTarget(ctx: ParserContext, target: Pattern | Expression | null | undefined): void;
+/** True for AST/Svelte node types that introduce a new lexical scope. */
+export declare function isScopeOwner(node: unknown): boolean;
+/** True for node types that introduce a new `var`-hoisting (function) scope. */
+export declare function isFunctionScopeOwner(node: unknown): boolean;
+/** Returns the scope map for `node`, creating and caching an empty one on first access. */
+export declare function getOrCreateScope(ctx: ParserContext, node: object): LexicalScope;
+/** Scope bindings from `const { a, b: c } = $props()`. Destructured props are `prop`; rest is `local`. */
+export declare function extractRunesScopeBindings(parser: ComponentParser, _node: VariableDeclaration, declarator: VariableDeclarator): {
+    kind: ScopeBindingKind;
+    name: string;
+    publicPropName?: string;
+}[];
+/** Declares bindings for every declarator in a `var`/`let`/`const` declaration into the appropriate scope. */
+export declare function declareVariableDeclaration(parser: ComponentParser, declaration: unknown, lexicalScope: LexicalScope, varScope: LexicalScope, options?: {
+    allowRunesProps?: boolean;
+    forceProp?: boolean;
+}): void;
+/** Declares a function-like node's own name (if any) and its parameter bindings into `scope`. */
+export declare function declareFunctionLikeScopeBindings(node: FunctionExpression | ArrowFunctionExpression | FunctionDeclaration, scope: LexicalScope): void;
+/** Declares top-level `var`/`function`/`class` bindings directly within a block's statement list. */
+export declare function collectDirectBlockDeclarations(parser: ComponentParser, body: unknown, lexicalScope: LexicalScope, varScope: LexicalScope): void;
+/** Declares all component-instance-level (`<script>`) bindings into `ctx.componentScope`. */
+export declare function collectComponentScopeDeclarations(parser: ComponentParser, ctx: ParserContext, instance: unknown): void;
+/** Walks the component AST, declaring bindings for every nested lexical/function scope it encounters. */
+export declare function collectNestedScopeDeclarations(parser: ComponentParser, ctx: ParserContext, componentRoot: Node): void;
+/** Rebuilds `ctx.componentScope` / `ctx.scopeDeclarations` / `ctx.activeScopes` from scratch for `componentRoot`. */
+export declare function buildScopeDeclarations(parser: ComponentParser, ctx: ParserContext, componentRoot: Node): void;

package/lib/parser/slots.d.ts

@@ -0,0 +1,29 @@
+import type { Expression, ObjectExpression } from "estree";
+import type ComponentParser from "../ComponentParser";
+import type { DeprecatedValue, JsDocPassthroughTag, SlotProps, SlotPropValue, SourceRange } from "../ComponentParser";
+import type { ParserContext } from "./context";
+/** Infer a slot prop value/type from an expression (identifier, literal, member access, or source text). */
+export declare function inferSlotPropValueFromExpression(ctx: ParserContext, parser: ComponentParser, expression: unknown): SlotPropValue;
+/** Slot props from an object expression, e.g. `{@render mySnippet({ foo: 1 })}`. */
+export declare function buildSlotPropsFromObjectExpression(ctx: ParserContext, parser: ComponentParser, expression: ObjectExpression): SlotProps;
+/** Snippet prop behind `{@render children()}` or `{@render props.children()}`. */
+export declare function resolveRenderTagPropReference(ctx: ParserContext, callee: unknown): {
+    publicName: string;
+    trackingName: string;
+} | null;
+/** Callee and arguments from a `{@render ...}` expression (unwraps `ChainExpression` first). */
+export declare function extractRenderTagInfo(ctx: ParserContext, expression: unknown): {
+    publicName: string;
+    trackingName: string;
+    arguments: Array<Expression | unknown>;
+} | null;
+/** Merge or add a slot. Empty `slot_name` is the default slot. */
+export declare function addSlot(ctx: ParserContext, { slot_name, slot_props, slot_fallback, slot_description, slot_deprecated, slot_tags, source, }: {
+    slot_name?: string;
+    slot_props?: string;
+    slot_fallback?: string;
+    slot_description?: string;
+    slot_deprecated?: DeprecatedValue;
+    slot_tags?: JsDocPassthroughTag[];
+    source?: SourceRange;
+}): void;

package/lib/parser/source-position.d.ts

@@ -0,0 +1,30 @@
+import type { SourcePosition, SourceRange } from "../ComponentParser";
+import type { ParserContext } from "./context";
+/**
+ * Returns (and lazily computes/caches on `ctx`) the 0-based source offset for
+ * the start of each line in `ctx.source`.
+ */
+export declare function getSourceLineStartOffsets(ctx: ParserContext): number[];
+/** Converts a 0-based source offset into a 1-based line / 0-based column {@link SourcePosition}. */
+export declare function sourcePositionFromOffset(ctx: ParserContext, offset: number): SourcePosition | undefined;
+/** Converts a pair of 0-based source offsets into a {@link SourceRange}. */
+export declare function sourceRangeFromOffsets(ctx: ParserContext, start: number | undefined, end: number | undefined): SourceRange | undefined;
+/** Converts an AST node's `start`/`end` offsets into a {@link SourceRange}. */
+export declare function sourceRangeFromNode(ctx: ParserContext, node: unknown): SourceRange | undefined;
+/**
+ * Computes the {@link SourceRange} for a JSDoc tag within a parsed comment
+ * block, given the block's own source lines and starting offset.
+ */
+export declare function sourceRangeFromCommentTag(ctx: ParserContext, blockSource: Array<{
+    number: number;
+    source: string;
+}>, tagSource: Array<{
+    number: number;
+    source: string;
+    tokens: {
+        tag?: string;
+    };
+}> | undefined, blockStartOffset: number | undefined): SourceRange | undefined;
+export declare function sourceAtPos(ctx: ParserContext, start: number, end: number): string | undefined;
+/** Source text for an expression, newlines collapsed to one line. */
+export declare function sourceForExpression(ctx: ParserContext, node: unknown): string | undefined;

package/lib/parser/type-resolution.d.ts

@@ -0,0 +1,27 @@
+import type { ModernRunesTypeNode, ParsedComponentTypeScriptMetadata } from "../ComponentParser";
+import type { ParserContext } from "./context";
+/**
+ * Looks up the modern-runes `$props()` declaration metadata recorded for the
+ * declarator starting at `declaratorStart`, if any.
+ */
+export declare function getRunesPropsDeclarationMetadata(ctx: ParserContext, declaratorStart: number | undefined): import("../ComponentParser").RunesPropsDeclarationMetadata | undefined;
+/**
+ * Looks up the per-prop type metadata (optionality, source range, type text)
+ * for `propName` within the `$props()` declaration starting at `declaratorStart`.
+ */
+export declare function getRunesPropTypeMetadata(ctx: ParserContext, declaratorStart: number | undefined, propName: string): import("../ComponentParser").RunesPropTypeMetadata | undefined;
+/** Rightmost name from a type reference (`Foo` or `NS.Foo`). */
+export declare function getTypeReferenceName(typeName: unknown): string | undefined;
+/** Leftmost name from a type reference, for import/local lookup. */
+export declare function getTypeDependencyName(typeName: unknown): string | undefined;
+/** Returns the trimmed source text spanned by a type annotation node, if positions are available. */
+export declare function getTypeAnnotationText(ctx: ParserContext, typeAnnotation: {
+    start?: number;
+    end?: number;
+} | undefined): string | undefined;
+/** Collect imported and local type names referenced by a type AST node. */
+export declare function collectReferencedTypeDependencies(ctx: ParserContext, typeNode: ModernRunesTypeNode | undefined, referencedImportedTypes: Set<string>, referencedLocalTypes: Set<string>, visitedLocalTypes?: Set<string>): void;
+/** Emit `import type` statements for referenced type names, grouped by module. */
+export declare function buildTypeImportStatements(ctx: ParserContext, referencedImportedTypes: Set<string>): string[];
+/** `ParsedComponentTypeScriptMetadata` for a single typed `$props()` declaration, if any. */
+export declare function buildTypeScriptMetadata(ctx: ParserContext): ParsedComponentTypeScriptMetadata | undefined;

package/lib/plugin.d.ts

@@ -1,5 +1,6 @@
 import { type GenerateBundleOptions, type GenerateBundleResult } from "./bundle";
 import "./writer/built-in-writers";
+import type { WriteCustomElementsOptions } from "./writer/writer-custom-elements";
 import type { WriteJsonOptions } from "./writer/writer-json";
 import type { WriteMarkdownOptions } from "./writer/writer-markdown";
 import type { WriteTsDefinitionsOptions } from "./writer/writer-ts-definitions";
@@ -20,6 +21,9 @@ export interface PluginSveldOptions extends Pick<GenerateBundleOptions, "resolve
     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">>;
     /**
      * Run additional, userland-registered writers (via `registerWriter` from
      * "sveld") beyond the built-in `json`/`markdown`/`types` outputs. Keyed by
@@ -50,7 +54,7 @@ interface SveldPlugin {
     enforce?: "pre" | "post";
     buildStart(): void | Promise<void>;
     generateBundle(): Promise<void>;
-    writeBundle(): void;
+    writeBundle(): Promise<void>;
     /** Vite dev-server HMR hook (serve mode). */
     handleHotUpdate?(ctx: HotUpdateContext): void;
     /** Rollup/Vite watch hook (build `--watch`). */
@@ -70,7 +74,7 @@ export default function pluginSveld(opts?: PluginSveldOptions): SveldPlugin;
  *
  * @example
  * ```ts
- * writeOutput(result, {
+ * await writeOutput(result, {
  *   types: true,
  *   json: true,
  *   markdown: true
@@ -78,4 +82,4 @@ export default function pluginSveld(opts?: PluginSveldOptions): SveldPlugin;
  * // Generates: types/*.d.ts, COMPONENT_API.json, COMPONENT_INDEX.md
  * ```
  */
-export declare function writeOutput(result: GenerateBundleResult, opts: PluginSveldOptions, input: string): void;
+export declare function writeOutput(result: GenerateBundleResult, opts: PluginSveldOptions, input: string): Promise<void>;

package/lib/sveld.d.ts

@@ -1,28 +1,15 @@
+import { type CheckResult } from "./check";
 import { type SveldDiagnostic } from "./diagnostics";
-import { type PluginSveldOptions } from "./plugin";
-interface SveldOptions extends Omit<PluginSveldOptions, "entry"> {
-    /**
-     * Specify the input to the uncompiled Svelte source.
-     * If no value is provided, `sveld` will attempt to infer
-     * the entry point from the `package.json#svelte` field.
-     */
-    input?: string;
-    /**
-     * Print unresolved-type diagnostics to stderr. Default `false`.
-     */
-    reportDiagnostics?: boolean;
-    /**
-     * Exit with code 1 when diagnostics are present. Implies `reportDiagnostics`.
-     * Default `false`.
-     */
-    strict?: boolean;
-}
+import { type SveldRuntimeOptions } from "./load-config";
+type SveldOptions = SveldRuntimeOptions;
 /**
  * Result of a programmatic `sveld` run.
  */
 interface SveldResult {
     /** Diagnostics from this run. */
     diagnostics: SveldDiagnostic[];
+    /** Populated when `check` is enabled: the API diff against the committed snapshot. */
+    check?: CheckResult;
 }
 /**
  * Programmatic entry point for sveld.
@@ -30,7 +17,7 @@ interface SveldResult {
  * @example
  * ```ts
  * await sveld({
- *   input: "./src",
+ *   entry: "./src",
  *   types: true,
  *   json: true,
  *   markdown: true,

package/lib/writer/MarkdownWriterBase.d.ts

@@ -1,6 +1,7 @@
 export type AppendType = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "quote" | "p" | "divider" | "raw";
 export interface TocLine {
-    array: number[];
+    /** Leading space count; 0 for the top-level (`h2`) entries the TOC currently lists. */
+    indent: number;
     raw: string;
 }
 export interface MarkdownWriterBase {