svelte-shaker 0.15.2 → 0.16.0

package/README.md

@@ -47,17 +47,19 @@ 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 and parser automatically
+(see [Options](#options)): a small/medium app runs on the native **Rust (WASM)
+engine** and parses with **rsvelte** (loaded from `@rsvelte/compiler`, a bundled
+WASM dependency — no peer, no platform-specific binary); a large app runs on the
+**JS engine** with **svelte/compiler**. `engine` and `parser` let you pin either.
 
 ## 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 and parser are chosen automatically per app size
+(Rust + rsvelte for small/medium, JS + svelte/compiler for large), and both fall
+back cleanly (see [Options](#options)).
 
 ```ts
 // vite.config.ts
@@ -82,8 +84,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 +97,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 + parser are auto-selected by app size; set these only to pin.
+  engine: 'auto', // 'auto' (Rust/WASM if <=~300 components, else JS) | 'js' | 'rust'
+  parser: undefined, // default follows the engine (Rust->rsvelte, JS->svelte);
+  // set 'rsvelte' | 'svelte' to pin one
 
   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 +118,27 @@ 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
+- **`engine`** — which engine runs the shake. **`'auto'`** (default) picks by app
+  size: a small/medium app (up to a few hundred components) uses the native
+  **Rust (WASM) engine**, 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.
+  dependency — nothing to install); a **large** app stays on the **JS engine**,
+  because the native engine's speed-up comes from a fast parse, but it must ship
+  the whole-program AST across the JS↔WASM boundary as JSON, and past a few
+  hundred components that round-trip (tens of MB) costs more than it saves.
+  `'rust'` forces the native engine (throwing if `@rsvelte/compiler` can't load);
+  `'js'` forces the JS engine. The two engines are differentially tested to shake
+  **byte-identically**, so this is **speed-only** — it never changes what ships.
+- **`parser`** — which parser feeds the engine. The default **follows the
+  engine**: **rsvelte** on the native engine (its AST crosses into Rust directly),
+  **svelte/compiler** on the JS engine (where rsvelte's parse is ~2× slower with
+  no downstream benefit). Set `'rsvelte'` or `'svelte'` to pin one regardless of
+  engine. 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. When rsvelte is the
+  resolved parser 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 +161,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 +220,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.js

@@ -1,7 +1,7 @@
 import { parseCached, parseModuleProgram, walk, } from './parse.js';
-import { emptyPlan, } from './ir.js';
+import { emptyPlan, isFoldableValue, } from './ir.js';
 import { computeDeadSpans, inSpans } from './dead.js';
-import { evaluate, setVar, unwrapTsAssertions } from './eval.js';
+import { evaluate, literalValue, setVar, unwrapTsAssertions } from './eval.js';
 const isSvelte = (source) => source.endsWith('.svelte');
 /** Floor for the fixpoint iteration bound (see {@link fixpointIterationBound}). */
 const MIN_FIXPOINT_ITERATIONS = 10;
@@ -169,6 +169,9 @@ export async function buildAnalyzeInput(entries, resolve, readFile, parseCache,
     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);
@@ -206,7 +209,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);
@@ -225,7 +228,7 @@ export async function buildAnalyzeInput(entries, resolve, readFile, parseCache,
                 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);
@@ -256,6 +259,7 @@ export function buildAnalyzeInputSync(entries, resolve, readFile, parseCache, pa
     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);
@@ -286,7 +290,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);
@@ -299,7 +303,7 @@ export function buildAnalyzeInputSync(entries, resolve, readFile, parseCache, pa
                 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);
@@ -1488,7 +1492,7 @@ function literalAttrValue(value) {
             // `dynamic` flag itself must match — mono's `specializableShape` reads it.
             const expr = unwrapTsAssertions(part.expression);
             if (expr?.type === 'Literal')
-                return { known: true, value: expr.value };
+                return literalValue(expr);
         }
         return { known: false };
     }
@@ -1549,7 +1553,9 @@ function buildPlan(model, u, ownerEnv) {
             continue;
         // constant fold: a clean singleton value set is the foldable case.
         if (set.values.length === 1) {
-            plan.constFold.set(decl.name, set.values[0]);
+            const only = set.values[0];
+            if (isFoldableValue(only))
+                plan.constFold.set(decl.name, only);
             continue;
         }
         // value-set narrowing: >= 2 distinct literals with no dynamic/⊤ contribution is a fully
@@ -1633,8 +1639,13 @@ function literalDefault(expr) {
     expr = unwrapTsAssertions(expr) ?? undefined;
     if (!expr)
         return { known: true, value: undefined }; // omitted default -> undefined
+    // `literalValue` is the same gate `literalAttrValue` and `evaluate` use: a
+    // BigInt/RegExp default (no faithful source form) or a `null` that is really
+    // `1e999` surviving JSON transport must stay UNKNOWN here too, or a call site
+    // that merely omits the prop reintroduces the crash/misfold this default path
+    // exists to prevent.
     if (expr.type === 'Literal')
-        return { known: true, value: expr.value };
+        return literalValue(expr);
     if (expr.type === 'Identifier' && expr.name === 'undefined')
         return { known: true, value: undefined };
     return { known: false };
@@ -1701,7 +1712,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);
@@ -1713,15 +1724,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) {
@@ -1730,7 +1746,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;
         }
@@ -1745,13 +1761,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;
         }
@@ -1760,7 +1776,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);
@@ -1769,14 +1785,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) {
@@ -1784,7 +1804,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;
         }
@@ -1798,12 +1818,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/eval.d.ts

@@ -31,6 +31,21 @@ export declare function unwrapTsAssertions(node: AnyNode | null | undefined): An
  * unknown on non-distributive ops), just without the interprocedural lattice.
  */
 export declare function evaluate(node: AnyNode | null | undefined, env: ReadonlyMap<string, Literal>): EvalResult;
+/**
+ * The `Literal` value of an ESTree `Literal` node, or unknown when the node
+ * carries a value outside that union.  This is the ONLY door through which a
+ * parsed value enters the engine, so it is where the union is enforced:
+ *
+ *  - **RegExp / BigInt literals** (`/x/g`, `1n`) hold a `RegExp` / `bigint` in
+ *    `value` — no faithful literal source form, and `JSON.stringify` throws on
+ *    the latter and flattens the former to `{}`.  Both carry a discriminator.
+ *  - **`value: null`** is ambiguous: an AST that reached us as JSON (the rsvelte
+ *    parser crosses a WASM boundary that way) cannot represent `Infinity`, so
+ *    `1e999` arrives indistinguishable from a genuine `null` except by `raw`.
+ *
+ * Anything unproven stays unknown, which costs one fold — never a wrong one.
+ */
+export declare function literalValue(node: AnyNode): EvalResult;
 /**
  * Sound set-aware predicate.  `constEnv` holds props collapsed to a single
  * literal (`constFold`); `setEnv` holds props whose reachable value set is known

package/dist/eval.js

@@ -37,7 +37,7 @@ export function evaluate(node, env) {
         return UNKNOWN;
     switch (node.type) {
         case 'Literal':
-            return { known: true, value: node.value };
+            return literalValue(node);
         case 'Identifier': {
             const name = node.name ?? '';
             if (name === 'undefined')
@@ -132,6 +132,30 @@ export function evaluate(node, env) {
             return UNKNOWN;
     }
 }
+/**
+ * The `Literal` value of an ESTree `Literal` node, or unknown when the node
+ * carries a value outside that union.  This is the ONLY door through which a
+ * parsed value enters the engine, so it is where the union is enforced:
+ *
+ *  - **RegExp / BigInt literals** (`/x/g`, `1n`) hold a `RegExp` / `bigint` in
+ *    `value` — no faithful literal source form, and `JSON.stringify` throws on
+ *    the latter and flattens the former to `{}`.  Both carry a discriminator.
+ *  - **`value: null`** is ambiguous: an AST that reached us as JSON (the rsvelte
+ *    parser crosses a WASM boundary that way) cannot represent `Infinity`, so
+ *    `1e999` arrives indistinguishable from a genuine `null` except by `raw`.
+ *
+ * Anything unproven stays unknown, which costs one fold — never a wrong one.
+ */
+export function literalValue(node) {
+    if (node.regex !== undefined || node.bigint !== undefined)
+        return UNKNOWN;
+    const v = node.value;
+    if (v === null)
+        return node.raw === 'null' ? { known: true, value: null } : UNKNOWN;
+    if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+        return { known: true, value: v };
+    return UNKNOWN;
+}
 /**
  * Sound set-aware predicate.  `constEnv` holds props collapsed to a single
  * literal (`constFold`); `setEnv` holds props whose reachable value set is known

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;

package/dist/exclude.js

@@ -0,0 +1,29 @@
+// ----------------------------------------------------------------------
+// Build-output exclusion for the directory scans (docs/ARCHITECTURE.md §8.1.1).
+// Shell-side glue, kept in its own module (like `dev-only.ts`) so both the
+// `.svelte` seed scan (`scan.ts`) and the non-`.svelte` escape scan
+// (`escape-scan.ts`) can share it without an import cycle.
+// ----------------------------------------------------------------------
+import * as path from 'node:path';
+/** Never excludes anything — the default when no build-output roots are declared. */
+export const excludeNothing = () => false;
+/**
+ * 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 function compileExclude(root, exclude) {
+    if (!exclude || exclude.length === 0)
+        return excludeNothing;
+    const prefixes = exclude.map((e) => path.resolve(root, e));
+    return (absPath) => prefixes.some((p) => absPath === p || absPath.startsWith(p + path.sep));
+}

package/dist/ir.d.ts

@@ -131,4 +131,18 @@ export interface ComponentPlan {
      */
     valueSets: Map<string, PropValueSet>;
 }
+/**
+ * Whether a proven value may be SUBSTITUTED into the residual as a constant.
+ *
+ * Every member of {@link Literal} has a faithful source form except `-0`: the
+ * Svelte compiler constant-folds the expression it is spliced into and loses the
+ * sign of zero there (`{1 / n}` renders `-Infinity` with `n = -0` at runtime,
+ * but the folded `{1 / (-0)}` compiles to a literal `Infinity`).  Emitting it
+ * would therefore change what renders even though the value we proved is right,
+ * so a `-0`-valued prop is simply left alone — one missed fold, no risk.
+ *
+ * Narrowing is unaffected: a narrowed prop stays dynamic and is never
+ * substituted, and the comparisons it feeds use real JS semantics.
+ */
+export declare function isFoldableValue(value: Literal): boolean;
 export declare function emptyPlan(id: ComponentId): ComponentPlan;

package/dist/ir.js

@@ -3,6 +3,22 @@
 // See docs/ARCHITECTURE.md §5.1.  This is the M0 (walking-skeleton) subset:
 // only the pieces basic1 exercises, but shaped so later levels slot in.
 // ----------------------------------------------------------------------
+/**
+ * Whether a proven value may be SUBSTITUTED into the residual as a constant.
+ *
+ * Every member of {@link Literal} has a faithful source form except `-0`: the
+ * Svelte compiler constant-folds the expression it is spliced into and loses the
+ * sign of zero there (`{1 / n}` renders `-Infinity` with `n = -0` at runtime,
+ * but the folded `{1 / (-0)}` compiles to a literal `Infinity`).  Emitting it
+ * would therefore change what renders even though the value we proved is right,
+ * so a `-0`-valued prop is simply left alone — one missed fold, no risk.
+ *
+ * Narrowing is unaffected: a narrowed prop stays dynamic and is never
+ * substituted, and the comparisons it feeds use real JS semantics.
+ */
+export function isFoldableValue(value) {
+    return !Object.is(value, -0);
+}
 export function emptyPlan(id) {
     return {
         id,

package/dist/mono.d.ts

@@ -1,6 +1,6 @@
 import { type FileModel } from './analyze.js';
 import { type AnyNode } from './parse.js';
-import type { ComponentId, ComponentPlan, Literal } from './ir.js';
+import { type ComponentId, type ComponentPlan, type Literal } from './ir.js';
 /** Tuning knobs for monomorphization (docs §8.1, §13.2).  All have sound defaults. */
 export interface MonomorphizeOptions {
     /** Master switch.  Default OFF — every existing behavior is unchanged. */

package/dist/mono.js

@@ -60,6 +60,7 @@ import { inSpans } from './dead.js';
 import { shakeBody } from './transform.js';
 import { readCallSite, deadSpansForPlans, isFoldBlockedName, } from './analyze.js';
 import { parseSvelte, walk } from './parse.js';
+import { isFoldableValue } from './ir.js';
 export const DEFAULT_MONO_OPTIONS = {
     enabled: false,
     maxVariants: 8,
@@ -127,14 +128,29 @@ export function monomorphize(models, plans, options = DEFAULT_MONO_OPTIONS, entr
                 liveSitesByChild.set(call.childId, [{ owner: owner.id, node: call.node, shape, code }]);
         }
     }
+    // No child folds a non-base residual at EVERY live site -> nothing is
+    // specializable, so skip the whole-program base-size setup entirely (the step-3
+    // loop would emit nothing anyway).  Byte-identical to running it, just cheaper.
+    let anyCandidate = false;
+    for (const childId of liveSitesByChild.keys())
+        if (!ineligible.has(childId)) {
+            anyCandidate = true;
+            break;
+        }
+    if (!anyCandidate)
+        return { variants, bindings };
     // (2) Build the whole-program base render graph + the base module sizes, and
     // the set of components reachable from the shake entries.  `ownSize` is
     // memoized (compile is the hot cost) and a compile error makes a component
     // non-specializable (we treat it as un-sizable -> skip any child involved).
     const baseSource = baseSourceMap(models, plans);
     const baseChildrenOf = new Map();
+    // Parse each DISTINCT residual at most once across the whole gate (base sources
+    // + variant residuals).  An UNCHANGED residual reuses the AST the analysis
+    // already produced ({@link liveChildIds}), so only genuinely-folded files parse.
+    const astCache = new Map();
     for (const model of models.values())
-        baseChildrenOf.set(model.id, liveChildIds(baseSource.get(model.id), model));
+        baseChildrenOf.set(model.id, liveChildIds(baseSource.get(model.id), model, astCache));
     // Reachability roots = the shake entries (docs §3 monomorphization, §13.2), narrowed to the
     // TRUE import-graph roots.  The Shell seeds the crawl with EVERY `.svelte` file
     // (so it can attribute every call site), which would make every module its own
@@ -211,7 +227,7 @@ export function monomorphize(models, plans, options = DEFAULT_MONO_OPTIONS, entr
             continue; // exceeding the cap means we cannot specialize all-sites
         // Measure: does replacing the base child with its variants strictly shrink
         // the whole-program reachable module bytes?
-        if (!netWin(childId, variantSources, models, baseSource, baseChildrenOf, roots, ownSize, options.minSavings))
+        if (!netWin(childId, variantSources, models, baseSource, baseChildrenOf, roots, ownSize, options.minSavings, astCache))
             continue;
         // The gate passed: emit the variants and bind every live site.
         for (const v of variantSources) {
@@ -250,13 +266,13 @@ export function monomorphize(models, plans, options = DEFAULT_MONO_OPTIONS, entr
  * Specialize IFF Sigma_spec < Sigma_base * (1 - minSavings).  Any compile error
  * (un-sizable module) makes us decline — never bloat.
  */
-function netWin(childId, variantSources, models, baseSource, baseChildrenOf, roots, ownSize, minSavings) {
+function netWin(childId, variantSources, models, baseSource, baseChildrenOf, roots, ownSize, minSavings, astCache) {
     // The variants' OWN live children, parsed from each variant residual via the
     // child's import map (variants never add imports — they only fold/remove).
     const childModel = models.get(childId);
     const variantChildren = new Map();
     for (const v of variantSources)
-        variantChildren.set(v.id, liveChildIds(v.code, childModel));
+        variantChildren.set(v.id, liveChildIds(v.code, childModel, astCache));
     // --- Reachability is graph-only (NO compile): the costly `ownSize` is deferred
     // until we know which modules actually differ between the two scenarios.
     // BASE scenario: components reachable from the roots through the base graph.
@@ -366,14 +382,34 @@ function netWin(childId, variantSources, models, baseSource, baseChildrenOf, roo
  * residual that fails to parse would also fail to compile in {@link ownSize},
  * declining the child).
  */
-function liveChildIds(source, model) {
+function liveChildIds(source, model, astCache) {
+    // An unchanged residual (no fold touched this file) is byte-identical to the
+    // source the analysis already parsed, so reuse `model.ast` instead of parsing
+    // again — the common case (most components fold nothing).  A changed residual is
+    // parsed once and memoized by its source, so a variant shared across candidates
+    // never re-parses.  The filename only colors parse-error messages (swallowed), so
+    // a shared source yields the same fragment regardless of which model asks.
     let ast;
-    try {
-        ast = parseSvelte(source, model.id);
+    if (source === model.code) {
+        ast = model.ast;
     }
-    catch {
-        return [];
+    else {
+        const cached = astCache?.get(source);
+        if (cached !== undefined) {
+            ast = cached;
+        }
+        else {
+            try {
+                ast = parseSvelte(source, model.id);
+            }
+            catch {
+                ast = null;
+            }
+            astCache?.set(source, ast);
+        }
     }
+    if (!ast)
+        return [];
     const ids = [];
     walk(ast.fragment, null, {
         Component(node, { next }) {
@@ -418,6 +454,8 @@ function specializableShape(node, child, plan) {
         // override — exactly the analysis's "safely explicit" condition.
         if (explicit.dynamic || !explicit.afterLastSpread)
             continue;
+        if (!isFoldableValue(explicit.value))
+            continue; // no safe source form — exactly as constant fold
         shape.set(name, explicit.value);
     }
     return shape;

package/dist/parse.d.ts

@@ -75,6 +75,13 @@ export interface AnyNode {
     kind?: string | undefined;
     /** ObjectExpression `Property` shorthand-method flag (`{ m() {} }`). */
     method?: boolean | undefined;
+    /** ESTree `Literal` discriminators, present only on a RegExp (`/x/g`) or
+     * BigInt (`1n`) literal — neither of which carries a foldable `value`. */
+    regex?: {
+        pattern: string;
+        flags: string;
+    } | undefined;
+    bigint?: string | undefined;
     value?: unknown;
 }
 export interface Root extends AnyNode {

package/dist/scan.d.ts

@@ -1,8 +1,10 @@
 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';
 export { computeEscapedComponents, type EscapeScanResult } from './escape-scan.js';
 export { DEFAULT_DEV_ONLY, compileDevOnly, type DevOnlyFilter } from './dev-only.js';
+export { compileExclude, excludeNothing, type ExcludeFilter } from './exclude.js';
 /** Default filesystem resolver: resolve `source` relative to its importer. */
 export declare const fsResolve: Resolve;
 /** Default filesystem reader. */
@@ -21,4 +23,4 @@ export declare const fsReadFile: ReadFile;
  * custom pattern is root-relative there.  Pass `compileDevOnly(dir, [])` to seed
  * every file.
  */
-export declare function collectSvelteFiles(dir: string, devOnly?: DevOnlyFilter): ComponentId[];
+export declare function collectSvelteFiles(dir: string, devOnly?: DevOnlyFilter, exclude?: ExcludeFilter): ComponentId[];

package/dist/scan.js

@@ -6,6 +6,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { compileDevOnly } from './dev-only.js';
+import { excludeNothing } from './exclude.js';
 // The escape-scan machinery lives in `./escape-scan.js` (internal); only the single
 // entry helper is part of the public `svelte-shaker/node` surface.
 export { computeEscapedComponents } from './escape-scan.js';
@@ -13,6 +14,10 @@ export { computeEscapedComponents } from './escape-scan.js';
 // `svelte-shaker/node` surface, so a plain-Rollup pipeline can compile the same
 // predicate the Vite plugin does and feed it to both scans.
 export { DEFAULT_DEV_ONLY, compileDevOnly } from './dev-only.js';
+// Build-output exclusion (docs §8.1.1): the same "compile a predicate, feed both
+// scans" shape as `devOnly`, exposed on `svelte-shaker/node` so a plain-Rollup
+// pipeline can prune a compiled-output tree exactly as the Vite plugin does.
+export { compileExclude, excludeNothing } from './exclude.js';
 /** Default filesystem resolver: resolve `source` relative to its importer. */
 export const fsResolve = (source, importer) => {
     if (!source.startsWith('.'))
@@ -35,13 +40,13 @@ export const fsReadFile = (id) => fs.readFileSync(id, 'utf-8');
  * custom pattern is root-relative there.  Pass `compileDevOnly(dir, [])` to seed
  * every file.
  */
-export function collectSvelteFiles(dir, devOnly = compileDevOnly(dir)) {
+export function collectSvelteFiles(dir, devOnly = compileDevOnly(dir), exclude = excludeNothing) {
     const out = [];
-    collectSvelteFilesInto(dir, devOnly, out);
+    collectSvelteFilesInto(dir, devOnly, exclude, out);
     return out;
 }
-/** Recursive worker: the compiled `devOnly` predicate is threaded, never recompiled. */
-function collectSvelteFilesInto(dir, devOnly, out) {
+/** Recursive worker: the compiled `devOnly` / `exclude` predicates are threaded, never recompiled. */
+function collectSvelteFilesInto(dir, devOnly, exclude, out) {
     let entries;
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -53,8 +58,11 @@ function collectSvelteFilesInto(dir, devOnly, out) {
         if (entry.name === 'node_modules' || entry.name.startsWith('.'))
             continue;
         const full = path.join(dir, entry.name);
-        if (entry.isDirectory())
-            collectSvelteFilesInto(full, devOnly, out);
+        if (entry.isDirectory()) {
+            if (exclude(full))
+                continue; // a build-output tree — pruned from the scan
+            collectSvelteFilesInto(full, devOnly, exclude, out);
+        }
         else if (entry.isFile() && entry.name.endsWith('.svelte') && !devOnly(full))
             out.push(full);
     }

package/dist/transform.js

@@ -349,9 +349,8 @@ extraDrops) {
     // are removed), so a constFold prop used inside a surviving arm is handled.
     const refs = collectPropRefs(model, localEnv, dead);
     for (const [name, value] of localEnv) {
-        const lit = literalSource(value);
         for (const ref of refs.get(name) ?? [])
-            s.overwrite(ref.start, ref.end, ref.head + lit + ref.tail);
+            s.overwrite(ref.start, ref.end, foldReplacement(ref, value));
     }
     // (3) Drop the folded (constFold) props from the `$props()` signature, together
     // with any unread declared props (docs §PR7) — one {@link dropProps} call so
@@ -721,12 +720,31 @@ function substitutedSlice(from, to, roots, env, code) {
     let cursor = from;
     for (const ref of refs) {
         out += code.slice(cursor, ref.start);
-        out += ref.head + literalSource(env.get(ref.name)) + ref.tail;
+        out += foldReplacement(ref, env.get(ref.name));
         cursor = ref.end;
     }
     out += code.slice(cursor, to);
     return out;
 }
+/**
+ * The replacement text for a folded reference: `head + <literal> + tail`, but a
+ * NUMBER used as the object of a member access is parenthesized.  `count.toFixed()`
+ * with `count` = 5000 would otherwise emit `5000.toFixed()`, where the parser reads
+ * `5000.` as a float literal and then hits `toFixed` — "Identifier directly after
+ * number".  `(5000)` disambiguates.
+ *
+ * Strictly, only a decimal INTEGER literal is ambiguous here: `5.5.toFixed()` and
+ * `5e3.toFixed()` already parse (the number token ends before the `.`), and a
+ * `Literal` never carries a BigInt.  We wrap EVERY number uniformly anyway — the
+ * parens are always valid and the rule is simpler than sniffing the numeric form.
+ * Non-number literals (string / boolean / `null`) are never wrapped: they need no
+ * disambiguation, so existing golden output is unchanged.
+ */
+function foldReplacement(ref, value) {
+    const lit = literalSource(value);
+    const body = ref.memberObject === true && typeof value === 'number' ? `(${lit})` : lit;
+    return ref.head + body + ref.tail;
+}
 /** Find every folded-prop reference in `model`, outside dead spans, by name. */
 function collectPropRefs(model, env, dead) {
     const refs = new Map();
@@ -823,7 +841,11 @@ function foldRefFor(node, parent, grandparent, code) {
         const name = code.slice(node.start, node.end);
         return { start: node.start, end: node.end, head: `${name}: `, tail: '' };
     }
-    return { start: node.start, end: node.end, head: '', tail: '' };
+    // Plain expression read.  Flag a member-access object (`NAME.foo`) so a folded
+    // number is parenthesized ({@link foldReplacement}); a computed access
+    // (`NAME[i]`) needs no wrapping (`5000[i]` parses), so it stays unflagged.
+    const memberObject = parent?.type === 'MemberExpression' && parent.object === node && parent.computed !== true;
+    return { start: node.start, end: node.end, head: '', tail: '', memberObject };
 }
 /** True when an Identifier is a property key / member name, not a value read. */
 function isNonReference(node, parent) {
@@ -1014,8 +1036,29 @@ function setDefault(map, key) {
 function isSpace(ch) {
     return ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r';
 }
+/** Source text for a folded value, faithful for every member of {@link Literal}
+ * (the union {@link evaluate} admits).  Always an expression, so it drops into
+ * both substitution positions unchanged. */
 function literalSource(value) {
     if (value === undefined)
         return 'undefined';
+    if (typeof value === 'number')
+        return numberSource(value);
+    return JSON.stringify(value);
+}
+/**
+ * `JSON.stringify` flattens `Infinity`/`-Infinity`/`NaN` to `null`, so those get
+ * an explicit form.  Written as arithmetic rather than the `Infinity`/`NaN`
+ * globals because the substituted text lands in the CALLEE's scope, where a
+ * local of either name would silently capture it; `(0/0)` cannot be shadowed.
+ * (`-0`, the fourth lossy case, never reaches here — see `isFoldableValue`.)
+ */
+function numberSource(value) {
+    if (Number.isNaN(value))
+        return '(0/0)';
+    if (value === Infinity)
+        return '(1/0)';
+    if (value === -Infinity)
+        return '(-1/0)';
     return JSON.stringify(value);
 }

package/dist/vite.d.ts

@@ -82,6 +82,28 @@ export interface ShakerOptions {
      * count every file (the pre-`devOnly` behavior).
      */
     devOnly?: string[];
+    /**
+     * Build-output directories the scans must NOT walk (docs/ARCHITECTURE.md §8.1.1) —
+     * a compiled/generated tree that is not source: a SvelteKit adapter's `build/`,
+     * a `dist/`, any prior build artifact.  Each entry is a Vite-root-relative or
+     * absolute path naming a directory, matched on a plain path-prefix basis — the
+     * same "directory prefix" basis as {@link entries}, no glob.
+     *
+     * The resolved Vite `build.outDir` is ALWAYS excluded automatically (it is the
+     * destination this build overwrites, so it can hold no source the app depends
+     * on); this option is for output dirs the plugin cannot infer — most importantly
+     * a SvelteKit adapter's `build/`, which sits outside `build.outDir`. Excluding it
+     * skips parsing megabytes of minified output the escape scan would otherwise read
+     * (issue: adapter-static `build/` dominated the crawl).
+     *
+     * Distinct from {@link devOnly}: `devOnly` marks non-shipping SOURCE files (tests,
+     * stories) by glob; `exclude` prunes whole generated-OUTPUT directories that are
+     * not source at all. Like {@link 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`.
+     */
+    exclude?: string[];
     /**
      * Per-call-site monomorphization tuning (docs §13.2).  Monomorphization is ON
      * by default because it is bail-safe and never bloats (the measured net-win
@@ -100,8 +122,11 @@ export interface ShakerOptions {
      * implements every pass — for monomorphization it calls back into JS only for
      * the per-module compiled-size proxy the net-win gate needs — so it is the
      * default fast path:
-     *  - `'auto'` — use the native Rust engine when it can be loaded; otherwise fall
-     *    back to the JS engine.
+     *  - `'auto'` — use the native Rust engine for small/medium apps; a large app
+     *    (more than a few hundred components) stays on the JS engine, because the
+     *    whole-program AST that must cross the JS<->WASM boundary as JSON grows to
+     *    tens of MB and the round-trip then costs more than the faster parse saves.
+     *    Also falls back to JS if the WASM module can't be loaded.
      *  - `'rust'` — force the Rust engine; throws if the WASM module can't be loaded.
      *  - `'js'` — force the JS engine.
      * Both engines are differentially tested to produce byte-identical output, so the
@@ -121,17 +146,20 @@ export interface ShakerOptions {
      */
     dev?: false | DevMode;
     /**
-     * Which parser feeds the engine.  Default `'rsvelte'` — rsvelte's parser,
-     * loaded from `@rsvelte/compiler` (a bundled WASM dependency, so there is
-     * nothing extra to install and no platform-specific binary).  `'svelte'` is
-     * the escape hatch: it uses svelte/compiler (the previous default) and is the
-     * fallback to reach for if you ever hit an rsvelte parser bug.  The engine
-     * reads only UTF-16 `start`/`end`, never `loc`, so the choice can never affect
-     * what renders — it is soundness-neutral, differentially tested to produce
-     * SSR-equivalent output either way.  With the default `'rsvelte'`, if
-     * `@rsvelte/compiler` can't be loaded (a broken install) the plugin THROWS
-     * rather than silently falling back to svelte/compiler, so the output stays
-     * deterministic across machines: set `parser: 'svelte'` to opt out.
+     * Which parser feeds the engine.  Defaults to FOLLOW THE ENGINE: `'rsvelte'` on
+     * the native (Rust) engine — its AST crosses the WASM boundary directly — and
+     * `'svelte'` (svelte/compiler) on the JS engine, where rsvelte's parse is pure
+     * overhead (~2x slower) with no downstream benefit.  Set this to pin one parser
+     * regardless of engine.  rsvelte loads from `@rsvelte/compiler` (a bundled WASM
+     * dependency — nothing extra to install, no platform-specific binary).
+     *
+     * The engine reads only UTF-16 `start`/`end`, never `loc`, so the choice can
+     * never affect what renders — it is soundness-neutral, differentially tested to
+     * produce byte-identical output either way.  When rsvelte IS the resolved parser
+     * (the native engine, or an explicit `parser: 'rsvelte'`) and `@rsvelte/compiler`
+     * can't be loaded, the plugin THROWS rather than silently swapping to
+     * svelte/compiler, so the same source can't shake differently on another machine:
+     * set `parser: 'svelte'` to opt out.
      */
     parser?: 'svelte' | 'rsvelte';
     /**

package/dist/vite.js

@@ -6,6 +6,7 @@ import { DevShaker } from './engine.js';
 import { collectSvelteFiles, fsResolve } from './scan.js';
 import { computeEscapedComponents, isScannableModule, } from './escape-scan.js';
 import { compileDevOnly } from './dev-only.js';
+import { compileExclude } from './exclude.js';
 // Re-export so a user can extend the default dev-only list: `devOnly: [...DEFAULT_DEV_ONLY, '…']`.
 export { DEFAULT_DEV_ONLY } from './dev-only.js';
 import { DEFAULT_MONO_OPTIONS } from './mono.js';
@@ -90,6 +91,16 @@ function reportSizes(shaken, read, root, verbose, log) {
 }
 /** Query flag a specialized-variant `.svelte` request carries (see below). */
 const VARIANT_QUERY = 'shaker_variant';
+/**
+ * Above this many seed components, `auto` uses the JS engine instead of the native
+ * one.  The native engine's parse is faster, but it marshals the whole-program AST
+ * across the JS<->WASM boundary as JSON; for a large app (hundreds of components,
+ * tens of MB of AST) that round-trip outweighs the parse saving, so the
+ * boundary-free JS engine wins.  A round proxy for "the AST is big enough that the
+ * boundary tax dominates", not a measured knife-edge — the choice is speed-only
+ * (both engines emit byte-identical output), so being approximate is fine.
+ */
+const RUST_ENGINE_MAX_COMPONENTS = 300;
 /**
  * Resolve the {@link MonomorphizeOptions} from the public option surface.
  * Monomorphization is ON by default (it is bail-safe and never bloats); it is
@@ -130,6 +141,7 @@ const KNOWN_OPTIONS = {
     entries: true,
     preserve: true,
     devOnly: true,
+    exclude: true,
     monomorphize: true,
     engine: true,
     dev: true,
@@ -185,6 +197,10 @@ export function shaker(options = {}) {
     /** Variant request id (`<childPath>?shaker_variant=<n>`) -> residual source. */
     let variantSources = new Map();
     let root = process.cwd();
+    // Build-output dirs pruned from both scans (docs §8.1.1): the resolved
+    // `build.outDir` (when safe) plus the user's `exclude`.  Compiled in
+    // `configResolved`, once `build.outDir` is known.
+    let exclude = compileExclude(root, options.exclude);
     // Vite's logger, captured in `configResolved`; until then fall back to console
     // so the size report still surfaces if `buildStart` somehow runs first.
     let log = (msg) => console.info(`[svelte-shaker] ${msg}`);
@@ -215,29 +231,40 @@ export function shaker(options = {}) {
     /** The long-lived incremental engine, created in `configureServer` (serve only). */
     let devShaker = null;
     // Resolve the parser ONCE (lazily, so the rsvelte wasm is only loaded when a
-    // parser is actually needed). The default is `'rsvelte'`; `undefined` (returned
-    // for the `parser: 'svelte'` opt-out) means svelte/compiler. `@rsvelte/compiler`
-    // is a bundled dependency, so this normally just works; if it somehow can't be
-    // loaded (a broken install, an environment that can't instantiate the wasm) the
-    // default THROWS rather than silently falling back to svelte/compiler — a silent
-    // swap would make the same source shake differently depending on the machine, a
-    // reproducibility footgun. Failing loudly keeps the output deterministic;
-    // `parser: 'svelte'` is the explicit opt-out.
-    let parseResolved = false;
-    let parse;
-    const getParse = () => {
-        if (parseResolved)
-            return parse;
-        parseResolved = true;
-        if ((options.parser ?? 'rsvelte') === 'rsvelte') {
-            parse = tryLoadRsvelteParser() ?? undefined;
-            if (!parse)
-                throw new Error('[vite-plugin-svelte-shaker] the default parser "rsvelte" could not load its ' +
+    // parser is actually needed).  `undefined` means svelte/compiler.
+    //
+    // The default FOLLOWS THE ENGINE: rsvelte feeds the native (Rust) engine — its
+    // AST crosses the WASM boundary directly — but on the JS engine rsvelte's parse
+    // is pure overhead (~2x slower than svelte/compiler here) with no downstream
+    // benefit, so the JS path defaults to svelte/compiler.  The two parsers are
+    // differentially tested to produce byte-identical output, so this is speed-only.
+    //
+    // When rsvelte IS the resolved parser (the native engine, or explicit
+    // `parser: 'rsvelte'`) and `@rsvelte/compiler` can't be loaded, the plugin THROWS
+    // rather than silently swapping to svelte/compiler — a silent swap would make the
+    // same source shake on one machine and not another. `parser: 'svelte'` is the
+    // explicit opt-out; `parser: 'rsvelte'` forces rsvelte even on the JS engine.
+    // Memoized PER ENGINE: `vite build --watch` reuses this plugin instance across
+    // rebuilds, and `auto` can flip engine as the app grows/shrinks past the size
+    // threshold — so the parser must be able to follow.  Keyed by `useRust` (a
+    // present key is a resolved slot, whose value may legitimately be `undefined` =
+    // svelte/compiler).
+    const parseByEngine = new Map();
+    const getParse = (useRust) => {
+        if (parseByEngine.has(useRust))
+            return parseByEngine.get(useRust);
+        const parser = options.parser ?? (useRust ? 'rsvelte' : 'svelte');
+        let resolved;
+        if (parser === 'rsvelte') {
+            resolved = tryLoadRsvelteParser() ?? undefined;
+            if (!resolved)
+                throw new Error('[vite-plugin-svelte-shaker] the "rsvelte" parser could not load its ' +
                     'bundled dependency `@rsvelte/compiler` (a broken install, or an environment that ' +
                     'can\'t instantiate its wasm). Reinstall dependencies, or set `parser: "svelte"` ' +
                     'to use svelte/compiler (the fallback parser).');
         }
-        return parse;
+        parseByEngine.set(useRust, resolved);
+        return resolved;
     };
     /** The module specifier the rewritten owner imports a given variant from. */
     const variantSpecifier = (variantId) => {
@@ -259,6 +286,25 @@ export function shaker(options = {}) {
             root = config.root;
             log = (msg) => config.logger.info(`[svelte-shaker] ${msg}`);
             warn = (msg) => config.logger.warn(`[svelte-shaker] ${msg}`);
+            // Prune the resolved `build.outDir` (the destination this build overwrites —
+            // normally it can hold no source the app depends on) plus any user-declared
+            // `exclude` (an adapter's `build/`, a `dist/`).  docs §8.1.1.
+            //
+            // But a misconfigured `outDir` that is the crawl root itself or an ANCESTOR
+            // of an entry dir (e.g. `outDir: '.'`) would prune real source — a silent
+            // over-shake.  Sound-first: in that case skip the automatic `outDir`
+            // exclusion and warn, keeping only what the user explicitly listed.
+            const outDir = path.resolve(root, config.build.outDir);
+            const entryDirs = (options.entries ?? ['.']).map((p) => path.resolve(root, p));
+            const outDirCoversSource = entryDirs.some((d) => d === outDir || d.startsWith(outDir + path.sep));
+            if (outDirCoversSource) {
+                warn(`build.outDir (${path.relative(root, outDir) || '.'}) is the crawl root or ` +
+                    `contains an entry directory, so excluding it would prune source; skipping the ` +
+                    `automatic build-output exclusion. Set an outDir outside your source, or list the ` +
+                    `real output dir in the \`exclude\` option.`);
+            }
+            const autoExclude = outDirCoversSource ? [] : [outDir];
+            exclude = compileExclude(root, [...autoExclude, ...(options.exclude ?? [])]);
         },
         // Dev (serve): drive the long-lived incremental engine instead of the
         // one-shot build crawl.  `configureServer` runs before `buildStart`, so
@@ -273,7 +319,7 @@ export function shaker(options = {}) {
             const isDevOnly = compileDevOnly(root, options.devOnly);
             // The engine's entry components, collected from the entry DIRS: `entries`
             // names the roots to crawl from, these are the `.svelte` files under them.
-            const entryComponents = dirs.flatMap((d) => collectSvelteFiles(d, isDevOnly));
+            const entryComponents = dirs.flatMap((d) => collectSvelteFiles(d, isDevOnly, exclude));
             const read = (id) => fs.readFileSync(id, 'utf-8');
             const underDirs = (file) => dirs.some((d) => file === d || file.startsWith(d + path.sep));
             // Re-scan the non-`.svelte` modules for `.svelte` call sites and re-apply
@@ -289,6 +335,7 @@ export function shaker(options = {}) {
                     preserve: options.preserve,
                     components: entryComponents,
                     devOnly: isDevOnly,
+                    exclude,
                     resolve: fsResolve,
                     readFile: read,
                 });
@@ -296,7 +343,7 @@ export function shaker(options = {}) {
                 escapedKey = [...result.escaped].sort().join('\n');
                 return result.escaped;
             };
-            devShaker = new DevShaker(entryComponents, fsResolve, read, devMode, getParse(), await currentEscaped());
+            devShaker = new DevShaker(entryComponents, fsResolve, read, devMode, getParse(false), await currentEscaped());
             shaken = await devShaker.init();
             const applyDelta = (result) => {
                 for (const [id, code] of Object.entries(result.changed))
@@ -380,7 +427,7 @@ export function shaker(options = {}) {
             const isDevOnly = compileDevOnly(root, options.devOnly);
             // The engine's entry components, collected from the entry DIRS: `entries`
             // names the roots to crawl from, these are the `.svelte` files under them.
-            const entryComponents = dirs.flatMap((d) => collectSvelteFiles(d, isDevOnly));
+            const entryComponents = dirs.flatMap((d) => collectSvelteFiles(d, isDevOnly, exclude));
             if (entryComponents.length === 0) {
                 shaken = {};
                 variantSources = new Map();
@@ -420,6 +467,7 @@ export function shaker(options = {}) {
                 preserve: options.preserve,
                 components: entryComponents,
                 devOnly: isDevOnly,
+                exclude,
                 resolve,
                 readFile: read,
             });
@@ -439,19 +487,26 @@ export function shaker(options = {}) {
                     throw new Error('[vite-plugin-svelte-shaker] engine: "rust" was requested but the WASM engine ' +
                         'could not be loaded. Remove the option (or use engine: "js") to use the JS engine.');
             }
-            else if (engineChoice === 'auto') {
+            else if (engineChoice === 'auto' && entryComponents.length <= RUST_ENGINE_MAX_COMPONENTS) {
+                // The native engine parses fast, but the whole-program AST must cross the
+                // JS<->WASM boundary as JSON, and past a few hundred components that AST is
+                // tens of MB (this app: ~600 components -> ~60 MB) — the round-trip then
+                // costs more than the faster parse saves, so `auto` keeps a large app on the
+                // boundary-free JS engine.  Speed-only: both engines emit byte-identical
+                // output, so a borderline misjudgment only affects build time, never what
+                // ships.  `engine: 'rust'` overrides this to force the native engine.
                 wasm = tryLoadWasmEngine();
             }
             if (wasm) {
                 // Native Rust engine — byte-identical to the JS engine, including
                 // monomorphization.
                 if (mono.enabled) {
-                    const result = await svelteShakerWasmWithMono(wasm, entryComponents, resolve, read, mono, getParse(), escaped);
+                    const result = await svelteShakerWasmWithMono(wasm, entryComponents, resolve, read, mono, getParse(true), escaped);
                     shaken = result.files;
                     variantSources = result.variants;
                 }
                 else {
-                    shaken = await svelteShakerWasm(wasm, entryComponents, resolve, read, getParse(), escaped);
+                    shaken = await svelteShakerWasm(wasm, entryComponents, resolve, read, getParse(true), escaped);
                     variantSources = new Map();
                 }
                 reportSizes(shaken, read, root, options.verbose === true, log);
@@ -460,12 +515,12 @@ export function shaker(options = {}) {
             if (!mono.enabled) {
                 // JS engine, monomorphization off: byte-for-byte the unused-prop fold /
                 // constant fold / value-set narrowing output.
-                shaken = await svelteShaker(entryComponents, resolve, read, getParse(), escaped);
+                shaken = await svelteShaker(entryComponents, resolve, read, getParse(false), escaped);
                 variantSources = new Map();
                 reportSizes(shaken, read, root, options.verbose === true, log);
                 return;
             }
-            const result = await svelteShakerWithMono(entryComponents, resolve, read, mono, variantSpecifier, getParse(), escaped);
+            const result = await svelteShakerWithMono(entryComponents, resolve, read, mono, variantSpecifier, getParse(false), escaped);
             shaken = result.files;
             variantSources = new Map();
             for (const v of result.mono.variants.values())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svelte-shaker",
-  "version": "0.15.2",
+  "version": "0.16.0",
   "description": "Tree shaking for Svelte components",
   "keywords": [
     "dead-code-elimination",