svelte-shaker 0.15.3 → 0.16.1

package/README.md

@@ -47,17 +47,21 @@ reachable value set of `variant` and removes the `.btn-danger` rule.
 npm i -D svelte-shaker   # requires svelte@^5
 ```
 
-Nothing else to install. By default the plugin parses with rsvelte, loaded from
-`@rsvelte/compiler` (a bundled WASM dependency — no peer, no platform-specific
-binary). `parser: 'svelte'` falls back to svelte/compiler if you ever need it
-(see [Options](#options)).
+Nothing else to install. The plugin picks its engine automatically (see
+[Options](#options)): if a **native (napi) Rust** binary loads it runs there —
+parsing with rsvelte in process, fastest, no size ceiling; otherwise a small/medium
+app runs on the **WASM Rust engine** (parsing with **rsvelte** from
+`@rsvelte/compiler`, a bundled WASM dependency — no peer, no platform-specific
+binary) and a large app on the **JS engine** with **svelte/compiler**. `engine` and
+`parser` let you pin the choice.
 
 ## Usage (Vite)
 
 Add the plugin **before** `svelte()`. By default it runs only in `vite build` —
 dev/HMR is a pass-through (opt into dev shaking with the `dev` option, see
-[Options](#options)). Out of the box it runs the native **Rust (WASM) engine**
-and parses with **rsvelte**; both fall back cleanly (see [Options](#options)).
+[Options](#options)). The engine is chosen automatically (native Rust if a binary
+loads, else WASM Rust for small/medium or JS for large), and every path falls back
+cleanly (see [Options](#options)).
 
 ```ts
 // vite.config.ts
@@ -82,8 +86,8 @@ that monomorphization additionally needs the `?shaker_variant` requests routed
 through your plugin's `resolveId`/`load` hooks; the unused-prop fold / constant
 fold / value-set narrowing shake only needs the `transform` swap. The
 environment-free engine and the in-browser playground parse with svelte/compiler
-— the rsvelte default is a Vite-plugin concern (it loads a Node-only WASM
-module); the engine takes an optional `parse` argument if you want to swap it.
+— the Vite plugin's rsvelte selection is a plugin concern (it loads a Node-only
+WASM module); the engine takes an optional `parse` argument if you want to swap it.
 
 ### Options
 
@@ -95,14 +99,17 @@ shaker({
   devOnly: [...], // glob patterns of files that never ship (tests, stories); they
   // stop counting as call sites. Defaults to tests/mocks/stories; replaces, spread
   // to extend.
+  exclude: [], // build-output dirs to skip walking (a SvelteKit adapter's `build/`,
+  // a `dist/`). The Vite `build.outDir` is always skipped; add other generated
+  // output here. Not source — see below.
   monomorphize: true, // default on; `false` disables it for faster builds,
   // or { maxVariants: 16, minSavings: 0.05 } to tune
   verbose: false, // true = per-file size breakdown after the build
 
-  // Escape hatches — the defaults ARE the Rust path; set these only to opt
-  // out (e.g. if you ever hit a bug in it).
-  engine: 'auto', // 'auto' (default: Rust/WASM, else JS) | 'js' | 'rust'
-  parser: 'rsvelte', // 'rsvelte' (default) | 'svelte' (fallback)
+  // Engine is auto-selected; set these only to pin.
+  engine: 'auto', // 'auto' (native Rust if it loads, else WASM if <=~300, else JS) | 'js' | 'rust'
+  parser: undefined, // JS/WASM parse only (native always uses in-process rsvelte);
+  // default follows the engine (WASM->rsvelte, JS->svelte); set 'rsvelte' | 'svelte' to pin
 
   dev: false, // default off: dev is a pass-through. 'incremental' (re-parse only
   // changed files) | 'coarse' (re-analyze everything) opts in; never monomorphizes
@@ -113,17 +120,33 @@ That list is exhaustive: any other key **fails the build**, naming the key and t
 options that do exist. A typo would otherwise be ignored — and a misspelled
 `preserve` ships the component you meant to protect, over-shaken.
 
-- **The defaults are the Rust path.** Out of the box svelte-shaker runs the
-  native **Rust (WASM) engine** and parses with **rsvelte**, loaded from
-  [`@rsvelte/compiler`](https://github.com/baseballyama/rsvelte) (a bundled WASM
-  dependency — nothing to install). The Rust (WASM) engine is differentially
-  tested to shake **byte-identically** to the JS engine. The parser choice is
-  **soundness-neutral**: the engine reads only UTF-16 `start`/`end`, so
-  svelte/compiler and rsvelte are differentially tested to produce
-  **SSR-equivalent** output — the choice never changes what renders. rsvelte is
-  the default as the Rust parser the pipeline is standardizing on (end-to-end
-  Rust with the WASM engine); `parser: 'svelte'` stays available as the
-  fallback.
+- **`engine`** — which engine runs the shake. There are two Rust engines (the same
+  analysis behind two frontends) plus the JS engine. The **native (napi)** engine
+  parses with rsvelte **in process** and keeps the ASTs Rust-side, so no
+  whole-program AST crosses a boundary — fastest, no size ceiling — but it ships as
+  a per-platform prebuilt binary that may not exist for every install. The **WASM**
+  engine is the same Rust engine, but the whole-program AST must cross the JS↔WASM
+  boundary as JSON (tens of MB past a few hundred components), so it only wins for
+  small/medium apps; the **JS** engine needs no boundary crossing, so it wins for a
+  large app when the native binary isn't available. **`'auto'`** (default) uses the
+  native engine if a binary loads (no size gate), else the WASM engine for a
+  small/medium app or the JS engine for a large one. **`'rust'`** forces a Rust
+  engine — native if it loads, else WASM (throwing if `@rsvelte/compiler` can't load
+  for the WASM fallback); **`'js'`** forces the JS engine. All three are
+  differentially tested to shake **byte-identically**, so this is **speed-only** — it
+  never changes what ships.
+- **`parser`** — how the **JS / WASM** engines parse `.svelte`. It does **not** apply
+  to the native engine, which always parses with rsvelte in process. The default
+  **follows the engine**: **rsvelte** on the WASM engine (its AST crosses into Rust
+  directly), **svelte/compiler** on the JS engine (where rsvelte's parse is ~2× slower
+  with no downstream benefit). The choice is **soundness-neutral** — the engine reads
+  only UTF-16 `start`/`end`, so both parsers are differentially tested to produce
+  **byte-identical** output, never changing what renders. `parser: 'svelte'` also
+  forces the native engine **off** (it can't honor svelte/compiler), so the shake uses
+  a JS/WASM engine with svelte/compiler. When rsvelte is the resolved JS-side parser
+  (`parser: 'rsvelte'`, or the WASM engine's default) and `@rsvelte/compiler` can't
+  load, the plugin **throws** rather than silently swapping (so the same source can't
+  shake differently on another machine); `parser: 'svelte'` is the explicit opt-out.
 - **`monomorphize`** — the one shaking knob, **on** by default. A measured
   net-win gate only specializes a component when that strictly shrinks the whole
   program, so monomorphization **never bloats**: whatever the knobs are set to,
@@ -146,13 +169,6 @@ options that do exist. A typo would otherwise be ignored — and a misspelled
   monomorphize: { maxVariants: 16, minSavings: 0.05 } // e.g. a variant-heavy
   // design system, while skipping specializations that save under 5%
   ```
-- **Escape hatches (`engine` / `parser`).** If you ever hit a bug in the Rust
-  path, opt out per axis: `engine: 'js'` forces the JS engine, `parser: 'svelte'`
-  forces svelte/compiler (the previous default). `@rsvelte/compiler` is a bundled
-  dependency, so the default parser normally just loads; in the unlikely event it
-  can't (a broken install), the plugin **throws** rather than silently falling
-  back — so the same source always shakes the same on every machine. Reinstall
-  dependencies, or set `parser: 'svelte'`.
 - **`dev`** — whether to shake in `vite dev` too. **Off** by default: dev is a
   pass-through, which is always correct and keeps HMR simple. Opt in with
   `dev: 'incremental'` — re-parses only the changed files and re-runs the
@@ -212,6 +228,28 @@ options that do exist. A typo would otherwise be ignored — and a misspelled
   [`docs/ARCHITECTURE.md` §8.1.1](https://github.com/baseballyama/svelte-shaker/blob/main/docs/ARCHITECTURE.md)
   for the full argument.
 
+- **`exclude`** — directories the scans must **not walk at all**: a compiled,
+  generated tree that is **not source**. Each entry is a Vite-root-relative or
+  absolute path naming a directory, matched on a plain path-prefix basis (like
+  `entries`, no glob). The resolved Vite **`build.outDir` is always excluded
+  automatically** — it is the destination the build overwrites, so it holds no
+  source the app depends on. Use this option for output dirs the plugin can't infer,
+  most importantly a **SvelteKit adapter's `build/`** (adapter-static): it sits
+  _outside_ `build.outDir`, and left unpruned the escape scan parses megabytes of
+  minified output looking for call sites it can never contain, which can dominate
+  the crawl.
+
+  ```ts
+  shaker({ entries: ['.'], exclude: ['build'] }); // skip adapter-static output
+  ```
+
+  Distinct from `devOnly`: that marks non-shipping **source** files (tests, stories)
+  by glob; `exclude` prunes whole generated-**output** directories that are not
+  source at all. Like `entries`, **over-listing errs unsafe** — a pruned directory's
+  call sites stop counting, exactly as if it were outside the crawl — so name **only
+  generated output, never source**. That is why there is no default beyond the
+  always-safe `build.outDir`.
+
 ## What it removes
 
 | Pass                    | What it removes                                                                                                                              | Default |

package/dist/analyze.d.ts

@@ -237,14 +237,32 @@ export declare function planFixpoint(models: Map<ComponentId, FileModel>): Map<C
  * import is never crawled — its `<Comp/>` site cannot exist, so it cannot taint a
  * value set), keeping the produced model set — and thus the output — identical.
  */
-export declare function buildAnalyzeInput(entries: ComponentId | ComponentId[], resolve: Resolve, readFile: ReadFile, parseCache?: ParseCache, parse?: Parse, escaped?: ComponentId[]): Promise<AnalyzeInput>;
+/**
+ * The three per-file facts the crawl needs to resolve edges — import specifiers,
+ * rendered `<Local>` tag names, and `<ns.X>` member tag names. `null` when the file
+ * has no instance script (nothing to attribute), matching the crawl's skip.
+ */
+export interface CrawlFacts {
+    imports: ImportInfo[];
+    renderedTags: Set<string>;
+    memberTags: Set<string>;
+}
+/**
+ * Source of {@link CrawlFacts} for one `(id, code)`. The default is a JS parse +
+ * extraction ({@link jsCrawlFacts}); the native engine passes a provider backed by
+ * `ShakeSession` facts, so the crawl resolves the SAME edges without the JS parse.
+ */
+export type FactsProvider = (id: ComponentId, code: string) => CrawlFacts | null;
+/** The default facts provider: parse (svelte/compiler or rsvelte) and extract. */
+export declare function jsCrawlFacts(id: ComponentId, code: string, parseCache?: ParseCache, parse?: Parse): CrawlFacts | null;
+export declare function buildAnalyzeInput(entries: ComponentId | ComponentId[], resolve: Resolve, readFile: ReadFile, parseCache?: ParseCache, parse?: Parse, escaped?: ComponentId[], factsProvider?: FactsProvider): Promise<AnalyzeInput>;
 /**
  * Synchronous twin of {@link buildAnalyzeInput} for callers that cannot await
  * (an ESLint rule runs synchronously). Byte-for-byte the same crawl with sync
  * `resolve`/`readFile`; the `tests/build-analyze-input-sync` differential test
  * pins it identical to the async path, so keep the two bodies in lockstep.
  */
-export declare function buildAnalyzeInputSync(entries: ComponentId | ComponentId[], resolve: ResolveSync, readFile: ReadFileSync, parseCache?: ParseCache, parse?: Parse, escaped?: ComponentId[]): AnalyzeInput;
+export declare function buildAnalyzeInputSync(entries: ComponentId | ComponentId[], resolve: ResolveSync, readFile: ReadFileSync, parseCache?: ParseCache, parse?: Parse, escaped?: ComponentId[], factsProvider?: FactsProvider): AnalyzeInput;
 /**
  * Dead `{#if}` spans per component implied by `plans`, via the SAME shared
  * predicate the transform uses ({@link computeDeadSpans}).  A bailed component
@@ -299,6 +317,22 @@ export declare function findNeverPassedProps(input: AnalyzeInput): Map<Component
  * maps cleanly; an external name with no matching declared local is dropped.
  */
 export declare function remapToLocalNames<V>(map: Map<string, V>, model: FileModel): Map<string, V>;
+/**
+ * The bare component tag names this file RENDERS (`<Local/>`, excluding dotted
+ * `<ns.X/>` member tags). The Shell crawl uses this to resolve a barrel (a
+ * `.js`/`.ts` re-export, which costs a module read+parse) only for named imports
+ * actually rendered as a component — a value-only named import (a helper / type)
+ * is never a `<Local>` call site, so following it would read+parse a module for
+ * nothing. Skipping it only ever drops a non-call-site, so attribution (and the
+ * resulting models) are unchanged.
+ */
+export declare function renderedComponentTagNames(ast: Root): Set<string>;
+/**
+ * Every dotted component tag a file renders (`<ns.Child/>` -> `"ns.Child"`).  The
+ * Shell resolves each through its namespace import's barrel; bare `<Child/>` tags
+ * have no dot and are bound by the plain import maps instead.
+ */
+export declare function memberComponentTags(ast: Root): Set<string>;
 /**
  * Read one `<Child .../>` into a {@link CallSite}.  Attributes are in source
  * order, so we resolve last-write-wins (a later `a={…}` overrides an earlier
@@ -323,3 +357,11 @@ export declare function readCallSite(component: AnyNode, owner?: ComponentId): C
  * monomorphization specialization (mono.ts) must honor this identically.
  */
 export declare function isFoldBlockedName(model: FileModel, name: string): boolean;
+export interface ImportInfo {
+    value: string;
+    local: string;
+    /** `default` for a default import, the exported name for a named import, or
+     * `*` for a namespace import. */
+    imported: string;
+}
+export declare function importSources(instance: AnyNode): Generator<ImportInfo>;

package/dist/analyze.js

@@ -150,39 +150,44 @@ function buildModels(input, parseCache) {
     }
     return models;
 }
-/**
- * The Shell-side resolution + IO layer (docs/RUST-MIGRATION.md §2.1): BFS-crawl
- * the component graph from `entries`, resolving every import edge and reading
- * every reachable `.svelte` file up front, into a batched {@link AnalyzeInput}.
- *
- * This is the half that STAYS in JS — it owns `this.resolve` / file IO for Vite
- * ecosystem compat (docs ARCHITECTURE §5/§9) — so the engine ({@link
- * analyzeInput}) consumes its output with no callback across the boundary.  The
- * traversal mirrors the old crawl exactly: direct default-`.svelte` children and
- * the barrel children a file actually RENDERS are followed (an unrendered barrel
- * import is never crawled — its `<Comp/>` site cannot exist, so it cannot taint a
- * value set), keeping the produced model set — and thus the output — identical.
- */
-export async function buildAnalyzeInput(entries, resolve, readFile, parseCache, parse, escaped = []) {
+/** The default facts provider: parse (svelte/compiler or rsvelte) and extract. */
+export function jsCrawlFacts(id, code, parseCache, parse) {
+    const ast = parseCached(id, code, parseCache, parse);
+    const instance = ast.instance;
+    if (!instance)
+        return null;
+    return {
+        imports: [...importSources(instance)],
+        renderedTags: renderedComponentTagNames(ast),
+        memberTags: memberComponentTags(ast),
+    };
+}
+export async function buildAnalyzeInput(entries, resolve, readFile, parseCache, parse, escaped = [], 
+// The facts source. Defaults to a JS parse + extract; the native engine injects a
+// `ShakeSession`-backed provider (docs M3). Internal — the public crawl is unchanged.
+factsProvider) {
+    const getFacts = factsProvider ?? ((id, code) => jsCrawlFacts(id, code, parseCache, parse));
     const entryList = Array.isArray(entries) ? [...entries] : [entries];
     const files = [];
     const edges = [];
     const queue = [...entryList];
     const seen = new Set(queue);
+    // Parse each `.js`/`.ts` barrel at most once across the whole crawl (a shared
+    // design-system `index.ts` is re-imported hundreds of times).
+    const barrelCache = new Map();
     while (queue.length > 0) {
         const id = queue.shift();
         const code = await readFile(id);
         files.push({ id, code });
-        const ast = parseCached(id, code, parseCache, parse);
-        const instance = ast.instance;
-        if (!instance)
+        const facts = getFacts(id, code);
+        if (!facts)
             continue;
         // The bare component tags this file renders (`<Local …>`). Resolving a barrel
         // (a `.js`/`.ts` re-export) means READING and PARSING the target module to
         // chase the export, so we do it ONLY for named imports actually rendered as a
         // component here — a named import used as a value (a helper / type) can never
         // be a `<Local>` call site, so chasing it is pure waste.
-        const renderedTags = renderedComponentTagNames(ast);
+        const renderedTags = facts.renderedTags;
         // Resolve this file's imports into the three attributable edge kinds.  Direct
         // default `.svelte` and simple barrel/named imports bind a bare local; a
         // namespace import (`import * as ns`) binds no single component, so it is
@@ -190,7 +195,7 @@ export async function buildAnalyzeInput(entries, resolve, readFile, parseCache,
         const barrelLocals = new Map();
         const namespaceSources = new Map();
         const directChildren = [];
-        for (const imp of importSources(instance)) {
+        for (const imp of facts.imports) {
             if (imp.imported === '*') {
                 namespaceSources.set(imp.local, imp.value);
                 continue;
@@ -206,7 +211,7 @@ export async function buildAnalyzeInput(entries, resolve, readFile, parseCache,
             // Not rendered as `<imp.local>` -> not a call site -> skip the costly barrel read.
             if (!renderedTags.has(imp.local))
                 continue;
-            const childId = await resolveThroughBarrel(imp.value, imp.imported, id, resolve, readFile);
+            const childId = await resolveThroughBarrel(imp.value, imp.imported, id, resolve, readFile, barrelCache);
             if (childId) {
                 edges.push({ from: id, local: imp.local, to: childId, kind: 'barrel' });
                 barrelLocals.set(imp.local, childId);
@@ -220,12 +225,12 @@ export async function buildAnalyzeInput(entries, resolve, readFile, parseCache,
         // renders, so the engine attributes `<ns.X .../>` by name lookup.
         const nsChildren = [];
         if (namespaceSources.size > 0) {
-            for (const tag of memberComponentTags(ast)) {
+            for (const tag of facts.memberTags) {
                 const dot = tag.indexOf('.');
                 const source = namespaceSources.get(tag.slice(0, dot));
                 if (source == null)
                     continue;
-                const childId = await resolveThroughBarrel(source, tag.slice(dot + 1), id, resolve, readFile);
+                const childId = await resolveThroughBarrel(source, tag.slice(dot + 1), id, resolve, readFile, barrelCache);
                 if (childId) {
                     edges.push({ from: id, local: tag, to: childId, kind: 'namespace' });
                     nsChildren.push(childId);
@@ -250,28 +255,29 @@ export async function buildAnalyzeInput(entries, resolve, readFile, parseCache,
  * `resolve`/`readFile`; the `tests/build-analyze-input-sync` differential test
  * pins it identical to the async path, so keep the two bodies in lockstep.
  */
-export function buildAnalyzeInputSync(entries, resolve, readFile, parseCache, parse, escaped = []) {
+export function buildAnalyzeInputSync(entries, resolve, readFile, parseCache, parse, escaped = [], factsProvider) {
+    const getFacts = factsProvider ?? ((id, code) => jsCrawlFacts(id, code, parseCache, parse));
     const entryList = Array.isArray(entries) ? [...entries] : [entries];
     const files = [];
     const edges = [];
     const queue = [...entryList];
     const seen = new Set(queue);
+    const barrelCache = new Map();
     while (queue.length > 0) {
         const id = queue.shift();
         const code = readFile(id);
         files.push({ id, code });
-        const ast = parseCached(id, code, parseCache, parse);
-        const instance = ast.instance;
-        if (!instance)
+        const facts = getFacts(id, code);
+        if (!facts)
             continue;
         // See {@link buildAnalyzeInput}: resolve a barrel only for named imports
         // actually rendered as a `<Local>` component here, to avoid reading+parsing
         // modules behind value-only named imports.
-        const renderedTags = renderedComponentTagNames(ast);
+        const renderedTags = facts.renderedTags;
         const barrelLocals = new Map();
         const namespaceSources = new Map();
         const directChildren = [];
-        for (const imp of importSources(instance)) {
+        for (const imp of facts.imports) {
             if (imp.imported === '*') {
                 namespaceSources.set(imp.local, imp.value);
                 continue;
@@ -286,7 +292,7 @@ export function buildAnalyzeInputSync(entries, resolve, readFile, parseCache, pa
             }
             if (!renderedTags.has(imp.local))
                 continue;
-            const childId = resolveThroughBarrelSync(imp.value, imp.imported, id, resolve, readFile);
+            const childId = resolveThroughBarrelSync(imp.value, imp.imported, id, resolve, readFile, barrelCache);
             if (childId) {
                 edges.push({ from: id, local: imp.local, to: childId, kind: 'barrel' });
                 barrelLocals.set(imp.local, childId);
@@ -294,12 +300,12 @@ export function buildAnalyzeInputSync(entries, resolve, readFile, parseCache, pa
         }
         const nsChildren = [];
         if (namespaceSources.size > 0) {
-            for (const tag of memberComponentTags(ast)) {
+            for (const tag of facts.memberTags) {
                 const dot = tag.indexOf('.');
                 const source = namespaceSources.get(tag.slice(0, dot));
                 if (source == null)
                     continue;
-                const childId = resolveThroughBarrelSync(source, tag.slice(dot + 1), id, resolve, readFile);
+                const childId = resolveThroughBarrelSync(source, tag.slice(dot + 1), id, resolve, readFile, barrelCache);
                 if (childId) {
                     edges.push({ from: id, local: tag, to: childId, kind: 'namespace' });
                     nsChildren.push(childId);
@@ -1265,7 +1271,7 @@ function collectChildCalls(ast, imports) {
  * nothing. Skipping it only ever drops a non-call-site, so attribution (and the
  * resulting models) are unchanged.
  */
-function renderedComponentTagNames(ast) {
+export function renderedComponentTagNames(ast) {
     const names = new Set();
     walk(ast.fragment, null, {
         Component(node, { next }) {
@@ -1282,7 +1288,7 @@ function renderedComponentTagNames(ast) {
  * Shell resolves each through its namespace import's barrel; bare `<Child/>` tags
  * have no dot and are bound by the plain import maps instead.
  */
-function memberComponentTags(ast) {
+export function memberComponentTags(ast) {
     const tags = new Set();
     walk(ast.fragment, null, {
         Component(node, { next }) {
@@ -1646,7 +1652,7 @@ function literalDefault(expr) {
         return { known: true, value: undefined };
     return { known: false };
 }
-function* importSources(instance) {
+export function* importSources(instance) {
     const program = instance.content;
     for (const stmt of program?.body ?? []) {
         if (stmt.type !== 'ImportDeclaration')
@@ -1708,7 +1714,7 @@ const MAX_BARREL_HOPS = 8;
  * we cannot follow returns `null` — sound, because a child we never resolve is
  * never planned (a pure-barrel `.js` component is simply out of scope).
  */
-async function resolveThroughBarrel(source, imported, importer, resolve, readFile, hops = 0) {
+async function resolveThroughBarrel(source, imported, importer, resolve, readFile, cache, hops = 0) {
     if (hops > MAX_BARREL_HOPS)
         return null;
     const targetId = await resolve(source, importer);
@@ -1720,15 +1726,20 @@ async function resolveThroughBarrel(source, imported, importer, resolve, readFil
     if (isSvelte(source) || isSvelte(targetId)) {
         return imported === 'default' || imported === '*' ? targetId : null;
     }
-    // A `.js`/`.ts` barrel: read it and chase the matching re-export.
-    let code;
-    try {
-        code = await readFile(targetId);
-    }
-    catch {
-        return null;
+    // A `.js`/`.ts` barrel: read + parse it (once per crawl, memoized) and chase the
+    // matching re-export.
+    let body = cache.get(targetId);
+    if (body === undefined) {
+        let code;
+        try {
+            code = await readFile(targetId);
+        }
+        catch {
+            code = null;
+        }
+        body = code === null ? null : parseModuleBody(code, targetId);
+        cache.set(targetId, body);
     }
-    const body = parseModuleBody(code, targetId);
     if (!body)
         return null;
     for (const stmt of body) {
@@ -1737,7 +1748,7 @@ async function resolveThroughBarrel(source, imported, importer, resolve, readFil
             for (const spec of stmt.specifiers ?? []) {
                 if (specName(spec.exported) !== imported)
                     continue;
-                return resolveThroughBarrel(String(stmt.source.value), specName(spec.local) ?? 'default', targetId, resolve, readFile, hops + 1);
+                return resolveThroughBarrel(String(stmt.source.value), specName(spec.local) ?? 'default', targetId, resolve, readFile, cache, hops + 1);
             }
             continue;
         }
@@ -1752,13 +1763,13 @@ async function resolveThroughBarrel(source, imported, importer, resolve, readFil
                 const found = followLocalImport(body, localName);
                 if (!found)
                     return null;
-                return resolveThroughBarrel(found.value, found.imported, targetId, resolve, readFile, hops + 1);
+                return resolveThroughBarrel(found.value, found.imported, targetId, resolve, readFile, cache, hops + 1);
             }
             continue;
         }
         // `export * from './x'` — the name may live behind the wildcard.
         if (stmt.type === 'ExportAllDeclaration' && stmt.source?.value) {
-            const via = await resolveThroughBarrel(String(stmt.source.value), imported, targetId, resolve, readFile, hops + 1);
+            const via = await resolveThroughBarrel(String(stmt.source.value), imported, targetId, resolve, readFile, cache, hops + 1);
             if (via)
                 return via;
         }
@@ -1767,7 +1778,7 @@ async function resolveThroughBarrel(source, imported, importer, resolve, readFil
 }
 /** Synchronous twin of {@link resolveThroughBarrel} (see {@link
  * buildAnalyzeInputSync}). Keep in lockstep with the async body above. */
-function resolveThroughBarrelSync(source, imported, importer, resolve, readFile, hops = 0) {
+function resolveThroughBarrelSync(source, imported, importer, resolve, readFile, cache, hops = 0) {
     if (hops > MAX_BARREL_HOPS)
         return null;
     const targetId = resolve(source, importer);
@@ -1776,14 +1787,18 @@ function resolveThroughBarrelSync(source, imported, importer, resolve, readFile,
     if (isSvelte(source) || isSvelte(targetId)) {
         return imported === 'default' || imported === '*' ? targetId : null;
     }
-    let code;
-    try {
-        code = readFile(targetId);
-    }
-    catch {
-        return null;
+    let body = cache.get(targetId);
+    if (body === undefined) {
+        let code;
+        try {
+            code = readFile(targetId);
+        }
+        catch {
+            code = null;
+        }
+        body = code === null ? null : parseModuleBody(code, targetId);
+        cache.set(targetId, body);
     }
-    const body = parseModuleBody(code, targetId);
     if (!body)
         return null;
     for (const stmt of body) {
@@ -1791,7 +1806,7 @@ function resolveThroughBarrelSync(source, imported, importer, resolve, readFile,
             for (const spec of stmt.specifiers ?? []) {
                 if (specName(spec.exported) !== imported)
                     continue;
-                return resolveThroughBarrelSync(String(stmt.source.value), specName(spec.local) ?? 'default', targetId, resolve, readFile, hops + 1);
+                return resolveThroughBarrelSync(String(stmt.source.value), specName(spec.local) ?? 'default', targetId, resolve, readFile, cache, hops + 1);
             }
             continue;
         }
@@ -1805,12 +1820,12 @@ function resolveThroughBarrelSync(source, imported, importer, resolve, readFile,
                 const found = followLocalImport(body, localName);
                 if (!found)
                     return null;
-                return resolveThroughBarrelSync(found.value, found.imported, targetId, resolve, readFile, hops + 1);
+                return resolveThroughBarrelSync(found.value, found.imported, targetId, resolve, readFile, cache, hops + 1);
             }
             continue;
         }
         if (stmt.type === 'ExportAllDeclaration' && stmt.source?.value) {
-            const via = resolveThroughBarrelSync(String(stmt.source.value), imported, targetId, resolve, readFile, hops + 1);
+            const via = resolveThroughBarrelSync(String(stmt.source.value), imported, targetId, resolve, readFile, cache, hops + 1);
             if (via)
                 return via;
         }

package/dist/escape-scan.d.ts

@@ -1,6 +1,7 @@
 import type { ComponentId } from './ir.js';
 import type { Resolve, ReadFile } from './analyze.js';
 import { type DevOnlyFilter } from './dev-only.js';
+import { type ExcludeFilter } from './exclude.js';
 /**
  * Is `file` a module the escape scan reads — a non-`.svelte` JS/TS source
  * ({@link NON_SVELTE_MODULE_EXTS}), excluding `.d.ts` declaration files (types-only,
@@ -53,6 +54,13 @@ export declare function computeEscapedComponents(opts: {
      * matched relative to `root`.  Pass `compileDevOnly(root, [])` to scan everything.
      */
     devOnly?: DevOnlyFilter | undefined;
+    /**
+     * Build-output directories to prune from the escape scan (docs §8.1.1) — the SAME
+     * {@link ExcludeFilter} the seed scan applies, so a compiled-output tree is
+     * skipped by both.  Omitted, nothing is excluded ({@link excludeNothing}); the
+     * Vite plugin seeds it with `build.outDir` plus the user's `exclude`.
+     */
+    exclude?: ExcludeFilter | undefined;
     resolve: Resolve;
     readFile: ReadFile;
 }): Promise<EscapeScanResult>;

package/dist/escape-scan.js

@@ -9,6 +9,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { parseModuleProgram, walk } from './parse.js';
 import { compileDevOnly } from './dev-only.js';
+import { excludeNothing } from './exclude.js';
 /**
  * The non-`.svelte` module extensions we scan for `.svelte` call sites (docs
  * §4.2).  A component imported by any of these has a consumer the `.svelte`-only
@@ -30,13 +31,15 @@ export function isScannableModule(file) {
 }
 /**
  * Recursively collect every non-`.svelte` module under `dir` (skipping
- * `node_modules` and dot-directories, mirroring `collectSvelteFiles`).  Same
- * include scope as the seed scan — `.ts` inside `node_modules` is deliberately NOT
- * scanned (docs §4.2).  `devOnly` drops modules that never ship (a `Button.test.ts`)
- * so a colocated test does not mark the component it imports escaped (docs §8.1.1);
- * it is the SAME predicate the seed scan uses, so both scans discount the same files.
+ * `node_modules`, dot-directories, and any `exclude`d build-output tree, mirroring
+ * `collectSvelteFiles`).  Same include scope as the seed scan — `.ts` inside
+ * `node_modules` is deliberately NOT scanned (docs §4.2).  `devOnly` drops modules
+ * that never ship (a `Button.test.ts`) so a colocated test does not mark the
+ * component it imports escaped (docs §8.1.1); `exclude` prunes a compiled-output
+ * directory (`build.outDir`, an adapter's `build/`).  Both are the SAME predicates
+ * the seed scan uses, so both scans discount the same files.
  */
-function collectNonSvelteModules(dir, devOnly, out) {
+function collectNonSvelteModules(dir, devOnly, exclude, out) {
     let entries;
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -48,8 +51,11 @@ function collectNonSvelteModules(dir, devOnly, out) {
         if (entry.name === 'node_modules' || entry.name.startsWith('.'))
             continue;
         const full = path.join(dir, entry.name);
-        if (entry.isDirectory())
-            collectNonSvelteModules(full, devOnly, out);
+        if (entry.isDirectory()) {
+            if (exclude(full))
+                continue; // a build-output tree — pruned from the escape scan
+            collectNonSvelteModules(full, devOnly, exclude, out);
+        }
         else if (entry.isFile() && isScannableModule(entry.name) && !devOnly(full))
             out.push(full);
     }
@@ -175,9 +181,10 @@ export function matchPreserve(preserve, root, components) {
  */
 export async function computeEscapedComponents(opts) {
     const devOnly = opts.devOnly ?? compileDevOnly(opts.root);
+    const exclude = opts.exclude ?? excludeNothing;
     const modules = [];
     for (const dir of opts.entryDirs)
-        collectNonSvelteModules(dir, devOnly, modules);
+        collectNonSvelteModules(dir, devOnly, exclude, modules);
     const { escaped, unscannable } = await collectModuleEscapes(modules, opts.resolve, opts.readFile);
     const { matched, unmatched } = partitionPreserve(opts.preserve, opts.root, opts.components);
     for (const id of matched)

package/dist/exclude.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A directory the scans must NOT descend into: a build-output tree.  Returns
+ * `true` for an absolute path that is, or lives under, one of the declared roots.
+ * Both directory walks ({@link import('./scan.js').collectSvelteFiles} and the
+ * escape scan's `collectNonSvelteModules`) consult it, so a compiled-output dir is
+ * pruned from BOTH — the same predicate feeds both scans, mirroring `devOnly`.
+ */
+export type ExcludeFilter = (absPath: string) => boolean;
+/** Never excludes anything — the default when no build-output roots are declared. */
+export declare const excludeNothing: ExcludeFilter;
+/**
+ * Compile an {@link ExcludeFilter} from build-output directory roots (the Vite
+ * plugin's resolved `build.outDir` plus any user-declared `exclude`).  Each entry
+ * is resolved against `root` (an absolute entry is left as-is), then matched on a
+ * plain path-prefix basis — the same "directory or file prefix" basis as `entries`
+ * / `preserve`, no glob.  Empty / omitted -> {@link excludeNothing}.
+ *
+ * Unlike `entries`, over-listing here errs UNSAFE (a pruned directory's call sites
+ * stop counting, exactly as if it were outside the crawl), so it must name ONLY
+ * generated build output, never source.  That is why nothing is excluded by
+ * default: the plugin only ever seeds this with `build.outDir` (unconditionally
+ * safe — it is the destination the current build overwrites) and whatever the user
+ * explicitly declares via `exclude`.
+ */
+export declare function compileExclude(root: string, exclude?: string[]): ExcludeFilter;