sveld 0.35.0 → 0.35.2

package/lib/parse-cache.d.ts

@@ -1,4 +1,4 @@
-import { type ParsedComponent } from "./ComponentParser";
+import type { ParsedComponent } from "./ComponentParser";
 /** Default on-disk location for the persistent parse cache, relative to the project root. */
 export declare const DEFAULT_CACHE_FILE: string;
 /** Resolves the effective cache file path for `cache: true | string`. */

package/lib/parse-entry-exports.d.ts

@@ -23,8 +23,8 @@ export type EntryExports = EntryExport[];
  * @example
  * ```ts
  * // entry: export { VERSION } from "./constants"; export type { Theme } from "./types";
- * parseEntryExports("/abs/src/index.ts");
+ * await parseEntryExports("/abs/src/index.ts");
  * // [{ name: "Theme", kind: "type", isTypeOnly: true, ... }, { name: "VERSION", kind: "const", ... }]
  * ```
  */
-export declare function parseEntryExports(entryFile: string): EntryExports;
+export declare function parseEntryExports(entryFile: string): Promise<EntryExports>;

package/lib/parse-exports.d.ts

@@ -17,5 +17,9 @@ export type ParsedExports = Record<string, {
  * //   App: { source: "./App.svelte", default: true }
  * // }
  * ```
+ *
+ * @param resolving - Absolute paths currently being resolved on this call
+ *   stack, used to break `export *` cycles between files that re-export
+ *   each other. Callers should not pass this; it is threaded internally.
  */
-export declare function parseExports(source: string, dir: string): ParsedExports;
+export declare function parseExports(source: string, dir: string, resolving?: Set<string>): ParsedExports;

package/lib/parsed-component-metadata.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Runtime helpers for `ParsedComponent`'s symbol-keyed TypeScript metadata,
+ * split out of `./ComponentParser` so callers that only need to read or
+ * write this field (`parse-cache.ts`, `writer/writer-ts-definitions-core.ts`,
+ * `bundle.ts`) don't have to import the parser stack to get it.
+ */
+import type { ParsedComponent, ParsedComponentTypeScriptMetadata, ResolvedComponentProp } from "./ComponentParser";
+export declare const PARSED_COMPONENT_TYPE_SCRIPT_METADATA: unique symbol;
+export declare function getParsedComponentTypeScriptMetadata(component: {
+    [PARSED_COMPONENT_TYPE_SCRIPT_METADATA]?: ParsedComponentTypeScriptMetadata;
+}): ParsedComponentTypeScriptMetadata | undefined;
+/** Append checker-resolved props. Names the AST walker already found are left alone. */
+export declare function applyResolvedProps(component: ParsedComponent, resolved: ResolvedComponentProp[]): void;

package/lib/parser/bindings.d.ts

@@ -1,6 +1,4 @@
 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

@@ -1,110 +1,72 @@
 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 { ComponentContext, ComponentElement, ComponentEvent, ComponentGenerics, ComponentInlineElement, ComponentProp, ComponentPropBindings, Extends, InternalComponentSlot, 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 */
+    /**
+     * Explicit `<svelte:options runes={...} />` value. When set, overrides rune-reference detection.
+     */
+    runesOptionOverride?: boolean;
     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}.
+     * Raw `generics` script attribute (with `lang="ts"` validated). Held until parse end so it can
+     * override 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 explicitVariableTypesByName: Map<string, string>;
     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 slots: Map<string | null, InternalComponentSlot>;
     readonly snippetPropLocals: Set<string>;
-    /** @template tags in a @slot/@snippet block (no @extends), held until finalization. */
+    /** `@template` tags from 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. */
+    /** Source range per `@event` JSDoc tag, 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;
     }>;
+    /** True after the per-component variable/JSDoc symbol table has populated {@link variableInfoCache}. */
+    variableInfoCacheBuilt: boolean;
 }
 /** Fresh {@link ParserContext}. Keep in sync with new fields on {@link ParserContext}. */
 export declare function createParserContext(): ParserContext;

package/lib/parser/events.d.ts

@@ -1,7 +1,6 @@
 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"> & {
@@ -13,7 +12,6 @@ export declare function addDispatchedEvent(ctx: ParserContext, { name, detail, h
  * 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;

package/lib/parser/jsdoc.d.ts

@@ -3,7 +3,6 @@ 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[];
@@ -14,7 +13,6 @@ export declare function getCommentTags(parsed: ReturnType<typeof parseComment>):
     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;
@@ -45,7 +43,6 @@ export declare function processLeadingCommentsJSDoc(ctx: ParserContext, parser:
     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[];
@@ -55,5 +52,4 @@ export declare function processJSDocComment(parser: ComponentParser, leadingComm
     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/prop-shared.d.ts

@@ -0,0 +1,84 @@
+import type { ComponentPropParam, ComponentPropTypeSource } from "../ComponentParser";
+/**
+ * Decides a prop's provenance for docs UIs. Order is fixed and mirrors the
+ * precedence used to pick the prop's final `type` text in
+ * {@link resolvePropTypeAndDocs}: an explicit TypeScript annotation always
+ * wins, then JSDoc `@type`/`@param`/`@returns`, then a type resolved from an
+ * identifier default's own JSDoc, and only then a bare inferred/initializer
+ * type. `"unknown"` means none of the above produced any type text at all.
+ */
+export declare function resolveTypeSource({ hasTypeScriptType, hasJSDocType, inferredType, finalType, }: {
+    hasTypeScriptType?: boolean;
+    hasJSDocType?: boolean;
+    inferredType?: string;
+    finalType?: string;
+}): ComponentPropTypeSource;
+export interface ResolvePropTypeAndDocsInput {
+    /** Explicit TypeScript type text: a legacy `: T` annotation, or the matching `$props()` type-literal member in runes. */
+    explicitType?: string;
+    /**
+     * Lowest-precedence type text, used only when nothing else applies: the
+     * initializer's inferred type, or the literal `"() => any"` seed for a
+     * bare `export function` declaration (which has no initializer).
+     */
+    typeSeed?: string;
+    /**
+     * Value fed to {@link resolveTypeSource}'s `inferredType` bucket. Distinct
+     * from `typeSeed` for function declarations, which have an initializer-less
+     * `typeSeed` placeholder but no actual inferred type.
+     */
+    inferredTypeForSource?: string;
+    jsdocType?: string;
+    jsdocDescription?: string;
+    jsdocParams?: ComponentPropParam[];
+    jsdocReturnType?: string;
+    /**
+     * Type/description/params/returnType resolved from an identifier default's
+     * own JSDoc (e.g. `export let onClick = defaultHandler;` where
+     * `defaultHandler` carries its own doc comment). Callers should gate this
+     * to `undefined` whenever `explicitType`/`jsdocType` is already set, so it
+     * only ever fills a genuine gap (see {@link resolvePropIsFunction}, which
+     * relies on the same gating).
+     */
+    resolvedType?: string;
+    resolvedDescription?: string;
+    resolvedParams?: ComponentPropParam[];
+    resolvedReturnType?: string;
+    /** True when the initializer itself is an arrow/function expression. */
+    initializerIsFunction: boolean;
+    /** True for a bare `export function foo() {}` declaration. */
+    isFunctionDeclaration: boolean;
+    /**
+     * Runes-only: also treat the prop as a function when its resolved type
+     * text looks like a callback signature (`@param`/`@returns`/`=>` from
+     * TypeScript, JSDoc, or an identifier default). Legacy `export let` never
+     * applies this signature check; the mode difference predates this helper
+     * and is preserved here rather than silently converged.
+     */
+    inferIsFunctionFromTypeSignature?: boolean;
+    /**
+     * Legacy-only: fall back to a `@typedef`'s own description when the prop
+     * has none of its own. Runes omits this today (a preserved mode
+     * difference); pass `undefined` there.
+     */
+    typedefs?: Map<string, {
+        description?: string;
+    }>;
+}
+export interface ResolvedPropTypeAndDocs {
+    type?: string;
+    typeSource: ComponentPropTypeSource;
+    description?: string;
+    params?: ComponentPropParam[];
+    returnType?: string;
+    isFunction: boolean;
+}
+/**
+ * Resolves the type/description/params/returnType/isFunction decisions
+ * shared by every prop front-end (legacy module exports, legacy instance
+ * `export let`/`export function`, and runes `$props()` destructuring). The
+ * front-ends differ only in how they extract the raw signals below from
+ * their respective AST shapes; once extracted, the decisions are identical
+ * except where explicitly parameterized above.
+ */
+export declare function resolvePropTypeAndDocs(input: ResolvePropTypeAndDocsInput): ResolvedPropTypeAndDocs;

package/lib/parser/props.d.ts

@@ -2,9 +2,7 @@ import type { ArrowFunctionExpression, FunctionDeclaration, FunctionExpression }
 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.
@@ -51,6 +49,12 @@ export declare function inferReturnTypeFromNode(node: FunctionDeclaration | Func
 /**
  * Walk a block body and collect each `return`'s argument, skipping nested
  * functions. Bare `return;` becomes `null`.
+ *
+ * Not fused with the componentRoot walk: this runs from `processInitializer`, called
+ * synchronously while the outer walk is still on the ancestor `ExportNamedDeclaration`/
+ * `VariableDeclaration` node, so it needs the inferred type before the outer walk would
+ * otherwise reach these descendant statements. Deferring it to ride along with the outer
+ * traversal would mean computing prop types in a second pass instead of inline.
  */
 export declare function collectReturnArguments(body: unknown): unknown[];
 /**

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

@@ -1,6 +1,4 @@
 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-detection.d.ts

@@ -0,0 +1,13 @@
+import type { SyntaxMode } from "../ComponentParser";
+import type { ParserContext } from "./context";
+/**
+ * Determines a component's syntax mode without running the svelte compiler's analyze phase.
+ *
+ * Mirrors `analyze_component`'s own logic (`node_modules/svelte/src/compiler/phases/2-analyze/index.js`):
+ * an explicit `<svelte:options runes={...} />` always wins; otherwise the component is in runes
+ * mode if any rune name is referenced - and not shadowed by a local declaration of the same name -
+ * anywhere in the module script, instance script, or template.
+ *
+ * Mirrors svelte analyze runes detection. Omitted: top-level `await` forces runes (no fixture).
+ */
+export declare function detectSyntaxMode(ctx: ParserContext): SyntaxMode;

package/lib/parser/scopes.d.ts

@@ -1,11 +1,8 @@
 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>;
@@ -34,7 +31,26 @@ export declare function declareFunctionLikeScopeBindings(node: FunctionExpressio
 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;
+/**
+ * Resets `ctx.componentScope` / `ctx.scopeDeclarations` / `ctx.activeScopes` and declares the
+ * top-level `<script>` bindings. Does not walk the component tree; nested scope declarations are
+ * built incrementally by {@link enterNestedScopeDeclarationNode} inside the caller's own traversal
+ * of `componentRoot` (fused with prop/slot/event extraction there rather than walked separately).
+ */
+export declare function initComponentScope(parser: ComponentParser, ctx: ParserContext): void;
+/** Mutable stack tracking the enclosing `var`-hoisting scope while walking `componentRoot`. */
+export type ScopeWalkState = {
+    varScopeStack: LexicalScope[];
+};
+/** Creates the scope-walk state for a fresh traversal of `componentRoot`, seeded with `ctx.componentScope`. */
+export declare function createScopeWalkState(ctx: ParserContext): ScopeWalkState;
+/**
+ * Per-node `enter` step of the (formerly standalone) nested-scope-declaration walk. Declares
+ * bindings for `node` if it's a scope owner and pushes it as the active `var` scope for its
+ * descendants. Must be called during the same top-down traversal of `componentRoot` that
+ * {@link leaveNestedScopeDeclarationNode} tears down, and before any logic that reads
+ * `ctx.scopeDeclarations` for `node` itself (its own scope is only created here, on entry).
+ */
+export declare function enterNestedScopeDeclarationNode(parser: ComponentParser, ctx: ParserContext, state: ScopeWalkState, node: unknown): void;
+/** Per-node `leave` step counterpart to {@link enterNestedScopeDeclarationNode}. */
+export declare function leaveNestedScopeDeclarationNode(state: ScopeWalkState, node: unknown): void;

package/lib/parser/slots.d.ts

@@ -2,25 +2,20 @@ 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_props?: string | SlotProps;
     slot_fallback?: string;
     slot_description?: string;
     slot_deprecated?: DeprecatedValue;

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

@@ -5,11 +5,8 @@ import type { ParserContext } from "./context";
  * 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
@@ -26,5 +23,4 @@ export declare function sourceRangeFromCommentTag(ctx: ParserContext, blockSourc
     };
 }> | 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

@@ -1,27 +1,17 @@
 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 getTypeNodeText(ctx: ParserContext, typeNode: {
+    start?: number;
+    end?: number;
+} | undefined): string | undefined;
 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/parser/typescript-casts.d.ts

@@ -0,0 +1 @@
+export declare function stripTypeCastWrappers(root: unknown): void;

package/lib/parser/utils.d.ts

@@ -0,0 +1 @@
+export declare function assignValueOrUndefined(value?: "" | string): string | undefined;

package/lib/parser/variable-jsdoc.d.ts

@@ -0,0 +1,12 @@
+import type ComponentParser from "../ComponentParser";
+import type { ParserContext } from "./context";
+/**
+ * Maps every top-level variable/function name declared in a component's module and instance
+ * scripts to the `@type`/description from its attached JSDoc block. Used by
+ * {@link ComponentParser.findVariableTypeAndDescription} to resolve plain identifiers (e.g. a
+ * value passed to `setContext`) that aren't otherwise typed by a prop or a TS annotation.
+ */
+export declare function buildVariableJsDocTable(ctx: ParserContext, parser: ComponentParser): Map<string, {
+    type: string;
+    description?: string;
+}>;

package/lib/parser-stack.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Lazily loads the parser stack (`ComponentParser` and the pruned svelte
+ * parser in `./svelte-parse`, which together pull in acorn,
+ * `@sveltejs/acorn-typescript`, comment-parser, and estree-walker) behind a
+ * dynamic import.
+ *
+ * A fully cached run never needs to parse a single component, so it never
+ * has to pay for evaluating any of that. Callers that are about to parse
+ * (`bundle.ts`, `parse-entry-exports.ts`, `watch.ts`) await
+ * `loadParserStack()` once up front, then read the resolved stack back
+ * synchronously via `getParserStack()` for the rest of the (otherwise
+ * synchronous) parse path. The load happens at most once per process.
+ */
+export interface ParserStack {
+    ComponentParser: typeof import("./ComponentParser").default;
+    parseSvelte: typeof import("./svelte-parse").parse;
+}
+export declare function loadParserStack(): Promise<ParserStack>;
+/** Reads back the stack resolved by a prior, already-awaited `loadParserStack()` call. */
+export declare function getParserStack(): ParserStack;

package/lib/path.d.ts

@@ -1,3 +1,2 @@
 import type { NormalizedPath } from "./brands";
-/** Normalize path separators to `/`. */
 export declare function normalizeSeparators(filePath: string): NormalizedPath;

package/lib/resolve-types.d.ts

@@ -23,6 +23,7 @@ export interface ExampleCheckDiagnostic {
 export declare class TypeResolver {
     private readonly api;
     private readonly symbolFlags;
+    private readonly typeFlags;
     private readonly tsconfigPath;
     private readonly overlay;
     private constructor();
@@ -45,7 +46,6 @@ export declare class TypeResolver {
     checkExamples(targets: ExampleCheckTarget[]): Promise<Map<string, ExampleCheckDiagnostic[]>>;
     /** Closes the TypeScript server process. */
     dispose(): Promise<void>;
-    private resolveFile;
     private createFileSystem;
     private virtualFileName;
     private exampleFileName;

package/lib/svelte-parse.d.ts

@@ -0,0 +1,4 @@
+export declare function parse(source: string, { modern, loose }?: {
+    modern?: boolean;
+    loose?: boolean;
+}): unknown;

package/lib/svelte-version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/lib/writer/Writer.d.ts

@@ -1,37 +1,19 @@
-/**
- * Base writer class for file system operations.
- *
- * Automatically creates directories as needed before writing.
- *
- * @example
- * ```ts
- * const writer = new Writer();
- * await writer.write("./dist/index.d.ts", "export type Props = {};");
- * ```
- */
 export default class Writer {
     /**
-     * Writes content to a file.
-     *
-     * Creates the directory structure if needed, then writes the content
-     * to the specified file path.
+     * Skips the write when `filePath` already contains `raw`, so repeated runs
+     * over unchanged sources don't touch the file (or its mtime).
      *
-     * @param filePath - The path where the file should be written
-     * @param raw - The content to write
+     * @returns `true` if the file was written, `false` if it was already up to date.
      *
      * @example
      * ```ts
-     * await writer.write("./dist/index.d.ts", "export type Props={}");
-     * // Creates ./dist/index.d.ts with the given content
+     * const writer = new Writer();
+     * await writer.write("./dist/index.d.ts", "export type Props = {};");
      * ```
      */
-    write(filePath: string, raw: string): Promise<void>;
+    write(filePath: string, raw: string): Promise<boolean>;
 }
 /**
- * Creates a Writer instance for JSON files.
- *
- * @returns A Writer instance
- *
  * @example
  * ```ts
  * const writer = createJsonWriter();
@@ -40,14 +22,10 @@ export default class Writer {
  */
 export declare function createJsonWriter(): Writer;
 /**
- * Creates a Writer instance for TypeScript files.
- *
- * @returns A Writer instance
- *
  * @example
  * ```ts
  * const writer = createTypeScriptWriter();
- * await writer.write("index.d.ts", "export type Props={};");
+ * await writer.write("index.d.ts", "export type Props = {};");
  * ```
  */
 export declare function createTypeScriptWriter(): Writer;

package/lib/writer/WriterMarkdown.d.ts

@@ -6,8 +6,6 @@ interface MarkdownOptions {
 }
 export type { AppendType };
 /**
- * Markdown writer with optional append callbacks.
- *
  * @example
  * ```ts
  * const writer = new WriterMarkdown({