svelte-shaker 0.13.0 → 0.14.1

package/README.md

@@ -67,9 +67,10 @@ import { shaker } from 'svelte-shaker/vite';
 
 export default defineConfig({
   plugins: [
-    // `include` must cover EVERY call site in the app, or prop elimination
-    // would be unsound. Defaults to the Vite root.
-    shaker({ include: ['src'] }),
+    // `entries` is where the component crawl STARTS, not a file filter. It
+    // must cover EVERY call site in the app, or prop elimination would be
+    // unsound. Defaults to the Vite root.
+    shaker({ entries: ['src'] }),
     svelte(),
   ],
 });
@@ -88,8 +89,9 @@ module); the engine takes an optional `parse` argument if you want to swap it.
 
 ```ts
 shaker({
-  include: ['src'], // dirs (relative to root) holding every .svelte call site
-  external: [], // components to freeze — never fold their props (see below)
+  entries: ['src'], // dirs (relative to root) the crawl starts from; they must
+  // hold every .svelte call site in the app. Not a glob, not a filter.
+  preserve: [], // components whose props must never be folded (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
@@ -101,6 +103,10 @@ shaker({
 });
 ```
 
+That list is exhaustive: any other key **fails the build**, naming the key and the
+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
@@ -141,19 +147,30 @@ shaker({
   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'`.
-- **`external`** — freeze components a `.ts`/`.js` module uses in a way the shake
-  can't see, so their props are never folded. The plugin already scans your
-  non-`.svelte` modules and auto-freezes any component reached by a static import,
-  `export … from`, or a **literal** `import('./X.svelte')` — so a plain
-  `mount(Component, { props })` is handled for you. Use `external` for what the
-  scan can't follow: a **non-literal** dynamic `import(expr)`, or a call site in a
-  module outside `include`. Entries are root-relative or absolute paths naming a
-  component file (with its `.svelte` extension) or a directory of them (same basis
-  as `include`). It **freezes** the component — the file stays fully analyzed and
-  its own call sites still count; only its own prop folding is turned off. It is not
-  a scan-exclusion filter. The build **warns** (with the file path) about any module
-  the scan couldn't parse — so a mounted component isn't silently left unprotected —
-  and about `external` entries that matched no component.
+- **`preserve`** — keep a component's **prop interface** exactly as written, because
+  something the shake can't see passes props to it. What is preserved is the props,
+  **not** the file's presence in the bundle: this is unrelated to Rollup/Vite's
+  `external`, and it never keeps a file out of the bundle or out of the analysis.
+
+  You need it when the consumer lives outside the `.svelte` graph and the shaker
+  can't observe the call site — a `mount()` behind a **non-literal** dynamic
+  `import(expr)`, or a module outside the `entries` roots. Consumers reached by a
+  static import, `export … from`, or a **literal** `import('./X.svelte')` are found
+  by the plugin's own scan of your non-`.svelte` modules, so a plain
+  `mount(Component, { props })` is already handled for you.
+
+  Each entry is a root-relative or absolute path naming a component file (with its
+  `.svelte` extension) or a directory of them (same path-prefix basis as `entries`).
+  The file stays fully analyzed and its own call sites still count toward its
+  children — only that component's own prop folding is turned off. It is not a
+  scan-exclusion filter.
+
+  **When in doubt, list it.** Unlike `entries`, over-listing errs safe: a component
+  preserved without needing it is just shaken less, never wrongly.
+
+  The build **warns** (with the file path) about any module the scan couldn't
+  parse — so a mounted component isn't silently left unprotected — and about
+  `preserve` entries that matched no component.
 
 ## What it removes
 
@@ -192,14 +209,17 @@ The whole point is to **never change observable behavior**.
   unshaken; distribute via `svelte-package`.
 - **Build only** — whole-program analysis is incompatible with dev/HMR locality,
   so dev is always a pass-through.
-- **`include` must cover the whole app** — a call site outside the scanned dirs
-  is invisible, which would make prop elimination unsound. Call sites in
-  `.ts`/`.js` modules under `include` (e.g. `mount(Component, { props })`) are
-  scanned and the component is frozen automatically; a **non-literal** dynamic
-  `import(expr)` can't be followed, so reach for `external` there. The scan covers
-  modules **under `include`** — a library that mounts its own component from its own
-  bundled `.js`/`.ts` inside `node_modules` is not scanned, so freeze it via
-  `external` (with its resolved path) if you hit that.
+- **`entries` must cover the whole app** — the crawl starts there, and every
+  `.svelte` file it finds is a call-site source. A call site outside those roots
+  is invisible, so narrowing `entries` does not shake less, it shakes _wrongly_.
+  (Components reached _from_ the roots — including library ones in `node_modules`
+  — are crawled and shaken without being listed.) Call sites in `.ts`/`.js`
+  modules under the roots (e.g. `mount(Component, { props })`) are scanned and the
+  component's props are kept automatically; a **non-literal** dynamic `import(expr)`
+  can't be followed, so reach for `preserve` there. That scan covers modules
+  **under the `entries` roots only** — a library that mounts its own component
+  from its own bundled `.js`/`.ts` inside `node_modules` is not scanned, so list
+  it in `preserve` (with its resolved path) if you hit that.
 
 See [`docs/ARCHITECTURE.md`](https://github.com/baseballyama/svelte-shaker/blob/main/docs/ARCHITECTURE.md)
 for the full design and implementation status.

package/dist/analyze.d.ts

@@ -18,8 +18,10 @@ export type ReadFileSync = (id: ComponentId) => string;
  *    never be seen and is safe to drop;
  *  - `{ kind: 'all' }` — anything we cannot pin down: a `...rest` (captures
  *    undeclared inputs), an Identifier/Array binding (`let p = $props()`),
- *    more than one `$props()` call, or `$props()` outside a `let <pat> = …`
- *    declarator.  Then any input might be observed, so nothing is dropped.
+ *    more than one `$props()` call, `$props()` outside a `let <pat> = …`
+ *    declarator, or a component that observes slotted content outside `$props()`
+ *    — a legacy `<slot>` element or a `$$slots` read (both legal in runes mode).
+ *    Then any input might be observed, so nothing is dropped.
  */
 export type ReachableInputs = {
     kind: 'all';
@@ -114,6 +116,17 @@ export interface FileModel {
      * the write.  We never fold such a prop, exactly like a shadowed one.
      */
     writtenNames: Set<string>;
+    /**
+     * Owner-local bindings that are provably a single primitive CONSTANT, keyed by
+     * the LOCAL name a forwarded call-site expression references (docs §13.1
+     * interprocedural pass-through).  Merged into the owner's fold env so that
+     * `<Child {count}/>` — where `count` is an unmutated `let count = $state(0)` or
+     * a `const count = 0` — folds in the child exactly as a call-site literal would,
+     * feeding BOTH constant fold and value-set narrowing.  A static property of the
+     * source (independent of the fixpoint's plans), so it is computed ONCE here.
+     * See {@link computeScriptConstEnv} for the (conservative) admission rules.
+     */
+    scriptConstEnv: ReadonlyMap<string, Literal>;
     /**
      * Resolved ids of CHILD components this file leaks as a value (escape, docs
      * §4.1) — e.g. `<svelte:component this={Child}>`.  `analyze` unions these
@@ -264,8 +277,9 @@ export interface UnpassedProp {
  *    spread that could set it (`readCallSite` already folds `bind:`, known
  *    spreads, and `children`/snippet body into `explicit`/`hadSpread`);
  *  - a component in `input.escaped` — one the Shell knows has a consumer OUTSIDE
- *    the `.svelte` graph (a `.ts`/`.js` call site, or a user `external`, docs
- *    §4.2) — is skipped, because that consumer may pass a prop the crawl cannot see.
+ *    the `.svelte` graph (a call site in a non-`.svelte` module, or a user
+ *    `preserve`, docs §4.2) — is skipped, because that consumer may pass a prop
+ *    the crawl cannot see.
  *
  * Missing a `.svelte` EDGE (e.g. an unfollowed barrel) only DROPS call sites, so it
  * can only make this UNDER-report (the component looks unused and is skipped). The

package/dist/analyze.js

@@ -29,22 +29,22 @@ function fixpointIterationBound(componentCount) {
 /** Bail reason stamped on a component leaked as a value (docs §4.1 escape). */
 const ESCAPE_REASON = 'escapes as value (e.g. <svelte:component this={X}>)';
 /** Bail reason stamped on a component with a consumer OUTSIDE the analyzed
- * `.svelte` graph — a `.ts`/`.js` call site the crawl cannot parse, or a
- * user-declared `external` (docs §4.2, {@link AnalyzeInput.escaped}).  Kept
- * byte-identical to the Rust engine's constant so the two agree. */
-const EXTERNAL_ESCAPE_REASON = 'has a consumer outside the analyzed .svelte graph';
+ * `.svelte` graph — a call site in a non-`.svelte` module the crawl cannot
+ * parse, or a user-declared `preserve` (docs §4.2, {@link AnalyzeInput.escaped}).
+ * Kept byte-identical to the Rust engine's constant so the two agree. */
+const MODULE_ESCAPE_REASON = 'has a consumer outside the analyzed .svelte graph';
 /**
- * Stamp {@link EXTERNAL_ESCAPE_REASON} on every model in `escaped` that exists in
+ * Stamp {@link MODULE_ESCAPE_REASON} on every model in `escaped` that exists in
  * the program — the single injection point both the whole-program shake and
  * {@link findNeverPassedProps} share (docs §4.2).  Ids not in the program are
- * ignored (a stale `external` entry or a scanned `.ts` import to a component
- * outside the crawl is simply a no-op, never an error).
+ * ignored (a stale `preserve` entry or a scanned import to a component outside
+ * the crawl is simply a no-op, never an error).
  */
-function stampExternalEscapes(models, escaped) {
+function stampModuleEscapes(models, escaped) {
     for (const id of escaped ?? []) {
         const model = models.get(id);
-        if (model && !model.bailReasons.includes(EXTERNAL_ESCAPE_REASON))
-            model.bailReasons.push(EXTERNAL_ESCAPE_REASON);
+        if (model && !model.bailReasons.includes(MODULE_ESCAPE_REASON))
+            model.bailReasons.push(MODULE_ESCAPE_REASON);
     }
 }
 /**
@@ -86,9 +86,10 @@ export function analyzeInput(input, parseCache) {
         if (model && !model.bailReasons.includes(ESCAPE_REASON))
             model.bailReasons.push(ESCAPE_REASON);
     }
-    // Components with consumers outside the `.svelte` graph (a `.ts`/`.js` call site
-    // or a user `external`, docs §4.2) join the same whole-component escape bail.
-    stampExternalEscapes(models, input.escaped);
+    // Components with consumers outside the `.svelte` graph (a call site in a
+    // non-`.svelte` module or a user `preserve`, docs §4.2) join the same
+    // whole-component escape bail.
+    stampModuleEscapes(models, input.escaped);
     return { models, plans: planFixpoint(models) };
 }
 /**
@@ -348,6 +349,27 @@ const EMPTY_ENV = new Map();
 const EMPTY_SET_ENV = new Map();
 /** Shared empty {@link OwnerFoldEnv} (no owner, or an owner that folds nothing). */
 const EMPTY_OWNER_ENV = { fold: EMPTY_ENV, narrow: EMPTY_SET_ENV };
+/**
+ * Merge an owner's static script constants ({@link FileModel.scriptConstEnv})
+ * with its remapped folded props into a single fold env.  The two key spaces are
+ * DISJOINT by construction: a folded prop is keyed by the LOCAL binding name its
+ * `$props()` destructure introduces, and a script const by its top-level
+ * declarator name; a top-level `const`/`let` reusing a `$props()` local name is a
+ * JS redeclaration error, so no name can appear in both.  The merge is therefore
+ * order-independent — folded props are applied last purely to document that
+ * invariant — and either operand is returned as-is when the other is empty (the
+ * common case: no owner-forwarded expressions, or a prop-less component).
+ */
+function mergeScriptConsts(scriptConsts, foldedProps) {
+    if (scriptConsts.size === 0)
+        return foldedProps;
+    if (foldedProps.size === 0)
+        return scriptConsts;
+    const merged = new Map(scriptConsts);
+    for (const [name, value] of foldedProps)
+        merged.set(name, value);
+    return merged;
+}
 /**
  * Recompute every component's plan from the (cascade-filtered) usage, evaluating
  * forwarded call-site expressions against `prevPlans` — the PREVIOUS fixpoint
@@ -367,13 +389,21 @@ function buildPlans(models, usage, prevPlans) {
         if (cached)
             return cached;
         const model = models.get(owner);
-        const plan = prevPlans.get(owner);
         let env = EMPTY_OWNER_ENV;
-        if (model && plan && !plan.bail && (plan.constFold.size > 0 || plan.narrow.size > 0)) {
-            env = {
-                fold: plan.constFold.size > 0 ? remapToLocalNames(plan.constFold, model) : EMPTY_ENV,
-                narrow: plan.narrow.size > 0 ? remapToLocalNames(plan.narrow, model) : EMPTY_SET_ENV,
-            };
+        if (model) {
+            const plan = prevPlans.get(owner);
+            // A bailed owner still forwards its own SCRIPT CONSTANTS unchanged — its
+            // bail only makes ITS props unobservable, but it keeps rendering its call
+            // sites (docs §4.2 "自身のコールサイトは数える"), so `scriptConstEnv` (a
+            // static source fact) participates regardless of `plan.bail`.  Only the
+            // fold/narrow derived from the owner's OWN prop plan is gated on the plan
+            // being present and not bailed.
+            const foldable = plan !== undefined && !plan.bail;
+            const foldedProps = foldable && plan.constFold.size > 0 ? remapToLocalNames(plan.constFold, model) : EMPTY_ENV;
+            const narrow = foldable && plan.narrow.size > 0 ? remapToLocalNames(plan.narrow, model) : EMPTY_SET_ENV;
+            const fold = mergeScriptConsts(model.scriptConstEnv, foldedProps);
+            if (fold.size > 0 || narrow.size > 0)
+                env = { fold, narrow };
         }
         envCache.set(owner, env);
         return env;
@@ -470,8 +500,9 @@ export function deadSpansForPlans(models, plans) {
  *    spread that could set it (`readCallSite` already folds `bind:`, known
  *    spreads, and `children`/snippet body into `explicit`/`hadSpread`);
  *  - a component in `input.escaped` — one the Shell knows has a consumer OUTSIDE
- *    the `.svelte` graph (a `.ts`/`.js` call site, or a user `external`, docs
- *    §4.2) — is skipped, because that consumer may pass a prop the crawl cannot see.
+ *    the `.svelte` graph (a call site in a non-`.svelte` module, or a user
+ *    `preserve`, docs §4.2) — is skipped, because that consumer may pass a prop
+ *    the crawl cannot see.
  *
  * Missing a `.svelte` EDGE (e.g. an unfollowed barrel) only DROPS call sites, so it
  * can only make this UNDER-report (the component looks unused and is skipped). The
@@ -492,9 +523,10 @@ export function findNeverPassedProps(input) {
         if (model && !model.bailReasons.includes(ESCAPE_REASON))
             model.bailReasons.push(ESCAPE_REASON);
     }
-    // External consumers (`.ts`/`.js` call sites or `external`) escape too, so a prop
-    // they pass is never mis-reported as never-passed (docs §4.2).
-    stampExternalEscapes(models, input.escaped);
+    // Consumers outside the `.svelte` graph (non-`.svelte` module call sites or
+    // `preserve`) escape too, so a prop they pass is never mis-reported as
+    // never-passed (docs §4.2).
+    stampModuleEscapes(models, input.escaped);
     // Every textual call site counts (no cascade dead-span filtering): a prop passed
     // only at a folded-away site is still author-written, so we do not flag it.
     const usage = buildUsage(models, new Map());
@@ -637,10 +669,11 @@ function buildModelFromInput(file, edges, parseCache) {
             }
         }
     }
-    const reachableInputs = computeReachableInputs(instance, props, hasRestProp, propsPattern);
+    const reachableInputs = computeReachableInputs(instance, props, hasRestProp, propsPattern, usesLegacySlotInputs(ast));
     const childCalls = collectChildCalls(ast, imports);
     const { shadowedNames, debugNames, writtenNames } = collectTemplateBindings(ast, instance, propsDeclaration);
     const unreadDeclaredProps = computeUnreadDeclaredProps(ast, instance, props, propsPattern, shadowedNames, debugNames, writtenNames);
+    const scriptConstEnv = computeScriptConstEnv(ast, instance, ast.module, propsDeclaration, writtenNames);
     // Escape detection (docs §4.1): an imported component referenced as a *value*
     // (most notably `<svelte:component this={X}>`, but also assigned / passed /
     // stored) leaks to a use we cannot follow, so its prop profile is incomplete.
@@ -662,6 +695,7 @@ function buildModelFromInput(file, edges, parseCache) {
         shadowedNames,
         debugNames,
         writtenNames,
+        scriptConstEnv,
         escapedComponents,
         bailReasons,
     };
@@ -743,6 +777,195 @@ function computeUnreadDeclaredProps(ast, instance, props, propsPattern, shadowed
     }
     return unread;
 }
+/**
+ * Owner-local, provably-constant primitive bindings, keyed by the LOCAL name a
+ * forwarded call-site expression references (docs §13.1 interprocedural
+ * pass-through).  Walks the module then the instance `<script>`'s TOP-LEVEL
+ * declarations in order, extending the env sequentially so `const a = 1; const b
+ * = a + 1;` both resolve.  Every rule is conservative for soundness — a binding
+ * is admitted ONLY when its identifier definitely denotes one constant primitive
+ * at every call site:
+ *  - `const x = <expr>` / `let|var x = <expr>` whose `<expr>` constant-evaluates
+ *    against the env built so far;
+ *  - `$state(<arg>)` / `$state.raw(<arg>)` are unwrapped to `<arg>` (a bare
+ *    `$state()` is `undefined`): the reactive wrapper does not change the value a
+ *    never-written binding forwards.  `$derived` / `$props` / any OTHER rune is
+ *    not unwrapped, so its `CallExpression` never constant-evaluates and is
+ *    skipped (out of scope);
+ *  - primitives only — the `Literal` domain excludes object/array initializers,
+ *    so deep mutation through a `$state` proxy can never be folded away;
+ *  - the name is NEVER written (reassigned / `++` / destructure-assigned /
+ *    `bind:`), tested against {@link writtenNames} extended with module-internal
+ *    writes (docs §4.1: a written binding is not a constant);
+ *  - the name is bound EXACTLY ONCE across the whole file (its own top-level
+ *    declarator).  A name a template binder (`{#each as}`, snippet param, …) or a
+ *    nested/duplicate scope also binds is a DIFFERENT entity at some call site,
+ *    and call-site evaluation ({@link evaluate}) is scope-blind, so folding it
+ *    could read the wrong entity there (docs §4.1 shadowing; the same soundness
+ *    argument as {@link isFoldBlockedName}, but on the owner's OWN bindings — for
+ *    which the file-wide `shadowedNames` cannot be reused: it already contains
+ *    every top-level script declaration, so it would reject every candidate);
+ *  - exported bindings (`export const x`) are excluded — they are wrapped in an
+ *    `ExportNamedDeclaration`, not a bare `VariableDeclaration`, so the top-level
+ *    scan below skips them; like an escaped component they are reachable from
+ *    outside the analyzed graph.
+ */
+function computeScriptConstEnv(ast, instance, moduleScript, propsDeclaration, writtenNames) {
+    const env = new Map();
+    // A name is admissible only if bound EXACTLY ONCE anywhere in the file, so no
+    // template binder or nested scope can shadow it at a call site.
+    const bindingCounts = new Map();
+    countBindingNames(moduleScript?.content, bindingCounts);
+    countBindingNames(instance?.content, bindingCounts);
+    countBindingNames(ast.fragment, bindingCounts);
+    // `writtenNames` (from collectTemplateBindings) scans the instance script and
+    // the template but NOT the module script, so a module-internal write
+    // (`<script module>let n = 0; function inc(){ n++ }</script>`) would be missed.
+    // Close that gap here before admitting any module-level binding.
+    const written = new Set(writtenNames);
+    collectScriptWrites(moduleScript?.content, written);
+    // Module script runs before the instance and its bindings are visible to it,
+    // so extend module-first, then instance, each in declaration order.
+    for (const program of [moduleScript?.content, instance?.content]) {
+        for (const stmt of program?.body ?? []) {
+            // Only a bare `VariableDeclaration`; an `export const` is wrapped in an
+            // `ExportNamedDeclaration` and is deliberately excluded (see doc comment).
+            if (stmt.type !== 'VariableDeclaration' || stmt === propsDeclaration)
+                continue;
+            for (const decl of stmt.declarations ?? []) {
+                // A single-identifier binding only: a destructuring `const { a } = …`
+                // has no one primitive name to key, so it never folds.
+                if (decl.id?.type !== 'Identifier' || !decl.id.name)
+                    continue;
+                const name = decl.id.name;
+                if (written.has(name) || bindingCounts.get(name) !== 1)
+                    continue;
+                const value = evalDeclaratorValue(decl.init, env);
+                if (value.known)
+                    env.set(name, value.value);
+            }
+        }
+    }
+    return env;
+}
+/**
+ * Constant value of a declarator initializer for {@link computeScriptConstEnv},
+ * unwrapping the two runes whose argument IS the value a never-written binding
+ * holds: `$state(<arg>)` / `$state.raw(<arg>)` (a bare `$state()` /
+ * `$state.raw()` is `undefined`).  Any other initializer — including every other
+ * rune call — is evaluated verbatim, so a non-value rune simply falls to unknown.
+ */
+function evalDeclaratorValue(init, env) {
+    if (isStateRuneCall(init)) {
+        const arg = init?.arguments?.[0];
+        if (arg == null)
+            return { known: true, value: undefined }; // bare `$state()` -> undefined
+        return evaluate(arg, env);
+    }
+    return evaluate(init, env);
+}
+/**
+ * `$state(...)` or `$state.raw(...)` — the two runes whose sole argument is the
+ * plain value a never-written binding evaluates to.  `$state.snapshot`,
+ * `$derived`, `$props`, `$bindable`, etc. are intentionally NOT matched: they are
+ * not value-preserving wrappers, so they must stay unknown.
+ */
+function isStateRuneCall(node) {
+    if (node?.type !== 'CallExpression')
+        return false;
+    const callee = node.callee;
+    if (callee?.type === 'Identifier')
+        return callee.name === '$state';
+    return (callee?.type === 'MemberExpression' &&
+        callee.computed !== true &&
+        callee.object?.type === 'Identifier' &&
+        callee.object.name === '$state' &&
+        callee.property?.type === 'Identifier' &&
+        callee.property.name === 'raw');
+}
+/**
+ * Increment `counts` for every name a binding introduces in `root` (a `<script>`
+ * Program or the template fragment): variable declarators (including
+ * destructuring), function ids and parameters, and every template binder
+ * ({@link collectTemplateBindings} covers the same binders).  A name whose total
+ * count exceeds one is bound in more than one place — a nested/duplicate
+ * declaration or a template binder — so it is shadowed at some scope and is
+ * disqualified from {@link computeScriptConstEnv}.
+ */
+function countBindingNames(root, counts) {
+    if (!root)
+        return;
+    const bump = (name) => {
+        if (name)
+            counts.set(name, (counts.get(name) ?? 0) + 1);
+    };
+    const bumpPattern = (pattern) => {
+        const names = new Set();
+        addPatternNames(pattern, names);
+        for (const n of names)
+            bump(n);
+    };
+    // A `try {} catch (e) {}` param is intentionally NOT counted: a call-site
+    // expression only resolves against the TOP-LEVEL script scope, which a
+    // catch-block-scoped name can never enter, so it cannot shadow a fold there.
+    walk(root, null, {
+        _(node, { next }) {
+            switch (node.type) {
+                case 'VariableDeclarator':
+                    bumpPattern(node.id);
+                    break;
+                case 'FunctionDeclaration':
+                case 'FunctionExpression':
+                case 'ArrowFunctionExpression':
+                    if (node.id?.type === 'Identifier')
+                        bump(node.id.name);
+                    for (const p of node.params ?? [])
+                        bumpPattern(p);
+                    break;
+                case 'EachBlock':
+                    bumpPattern(node.context);
+                    if (typeof node.index === 'string')
+                        bump(node.index);
+                    break;
+                case 'SnippetBlock':
+                    if (node.expression?.type === 'Identifier')
+                        bump(node.expression.name);
+                    for (const p of node.parameters ?? [])
+                        bumpPattern(p);
+                    break;
+                case 'AwaitBlock':
+                    bumpPattern(node.value);
+                    bumpPattern(node.error);
+                    break;
+                case 'LetDirective':
+                    bump(node.name);
+                    break;
+                case 'ConstTag':
+                    for (const d of node.declaration?.declarations ?? [])
+                        bumpPattern(d.id);
+                    break;
+            }
+            next();
+        },
+    });
+}
+/** Add every name a `<script>` Program WRITES (bare-identifier assignment /
+ * update targets, at any nesting) to `out` — the module-script counterpart of
+ * the write collection {@link collectTemplateBindings} runs over the instance. */
+function collectScriptWrites(program, out) {
+    if (!program)
+        return;
+    walk(program, null, {
+        AssignmentExpression(node, { next }) {
+            collectWrittenNames(node, out);
+            next();
+        },
+        UpdateExpression(node, { next }) {
+            collectWrittenNames(node, out);
+            next();
+        },
+    });
+}
 /**
  * Collect every name bound by a TEMPLATE scope (so a same-named prop is a
  * different entity there) and every name used as a `{@debug}` argument.
@@ -1612,7 +1835,15 @@ function parseModuleBody(code, id) {
  * `$props.id()` (a member call) is NOT a `$props()` call — the props object never
  * leaks through it — so it does not count and does not affect the result.
  */
-function computeReachableInputs(instance, props, hasRestProp, propsPattern) {
+function computeReachableInputs(instance, props, hasRestProp, propsPattern, usesSlotInputs) {
+    // A legacy `<slot>` (or a bare `$$slots` read) observes slotted content —
+    // inputs that arrive OUTSIDE `$props()` (in Svelte 5 terms, the synthetic
+    // `children` input and named-slot / `let:` inputs a call site supplies as body
+    // content).  The `$props()` shape cannot model them, so the reverse pass must
+    // treat every input as observable, or it would delete the slot-carrying body at
+    // each call site.  This holds whether or not an instance script exists.
+    if (usesSlotInputs)
+        return { kind: 'all' };
     // No instance script -> no `$props()` -> the component reads no input at all.
     if (!instance)
         return { kind: 'names', names: new Set() };
@@ -1633,6 +1864,32 @@ function computeReachableInputs(instance, props, hasRestProp, propsPattern) {
         return { kind: 'all' };
     return { kind: 'names', names: new Set(props.map((p) => p.name)) };
 }
+/** True when the component observes slotted content outside `$props()`: a legacy
+ * `<slot>` element, or a read of the `$$slots` identifier (legal in runes mode,
+ * unlike `$$props`/`$$restProps`).  Either signal means {@link
+ * computeReachableInputs} cannot model the inputs and must fall back to ALL.
+ * `$$slots` can appear in the instance script OR a template expression
+ * (`{#if $$slots.default}`), so both trees are scanned; its `$$` prefix cannot be
+ * a user binding, so no shadowing check is needed. */
+function usesLegacySlotInputs(ast) {
+    return (nodeSignalsSlotInputs(ast.fragment) || (!!ast.instance && nodeSignalsSlotInputs(ast.instance)));
+}
+function nodeSignalsSlotInputs(root) {
+    let found = false;
+    walk(root, null, {
+        SlotElement(_node, { stop }) {
+            found = true;
+            stop();
+        },
+        Identifier(node, { stop }) {
+            if (node.name === '$$slots') {
+                found = true;
+                stop();
+            }
+        },
+    });
+    return found;
+}
 /** True when a `$props()` ObjectPattern binds a prop whose external name is not a
  * plain identifier (a string-literal or computed key), so {@link declared_props}
  * did not capture it. */

package/dist/engine.d.ts

@@ -47,13 +47,13 @@ export declare class DevShaker {
     /** Last-seen source per file, so an update re-reads only what changed. */
     private readonly codeCache;
     /** Components with a consumer outside the `.svelte` graph (docs §4.2): a
-     * `.ts`/`.js` call site or a user `external`.  The Shell recomputes and
+     * `.ts`/`.js` call site or a user `preserve`.  The Shell recomputes and
      * {@link setEscaped}s this whenever a non-`.svelte` module changes. */
     private escaped;
     /** Current slimmed output per `.svelte` id (the live shake result). */
     private output;
     constructor(files: ComponentId | ComponentId[], resolve: Resolve, readFile: ReadFile, mode?: DevMode, parse?: Parse, escaped?: ComponentId[]);
-    /** Replace the external-escape set (docs §4.2).  The Shell calls this before
+    /** Replace the module-escape set (docs §4.2).  The Shell calls this before
      * {@link update} when a non-`.svelte` module changed the set of components
      * reached from `.ts`/`.js`, so the next shake bails them. */
     setEscaped(escaped: ComponentId[]): void;

package/dist/engine.js

@@ -24,7 +24,7 @@ export class DevShaker {
     /** Last-seen source per file, so an update re-reads only what changed. */
     codeCache = new Map();
     /** Components with a consumer outside the `.svelte` graph (docs §4.2): a
-     * `.ts`/`.js` call site or a user `external`.  The Shell recomputes and
+     * `.ts`/`.js` call site or a user `preserve`.  The Shell recomputes and
      * {@link setEscaped}s this whenever a non-`.svelte` module changes. */
     escaped;
     /** Current slimmed output per `.svelte` id (the live shake result). */
@@ -38,7 +38,7 @@ export class DevShaker {
         this.parse = parse;
         this.escaped = escaped;
     }
-    /** Replace the external-escape set (docs §4.2).  The Shell calls this before
+    /** Replace the module-escape set (docs §4.2).  The Shell calls this before
      * {@link update} when a non-`.svelte` module changed the set of components
      * reached from `.ts`/`.js`, so the next shake bails them. */
     setEscaped(escaped) {

package/dist/escape-scan.d.ts

@@ -7,38 +7,43 @@ import type { Resolve, ReadFile } from './analyze.js';
  * uses this to decide whether a changed file can shift the escape set (docs §4.2).
  */
 export declare function isScannableModule(file: string): boolean;
-/** The components a set of `external` prefixes freezes (docs §4.2).  The
- * {@link partitionExternal} projection that drops the "matched nothing" diagnostic
+/** The components a set of `preserve` prefixes protects (docs §4.2).  The
+ * {@link partitionPreserve} projection that drops the "matched nothing" diagnostic
  * — kept for callers that only need the ids. */
-export declare function matchExternal(external: string[] | undefined, root: string, components: Iterable<ComponentId>): ComponentId[];
+export declare function matchPreserve(preserve: string[] | undefined, root: string, components: Iterable<ComponentId>): ComponentId[];
 /**
  * The whole escape set for a build (docs §4.2), plus the diagnostics a Shell must
  * surface.  `escaped` is the union of components a non-`.svelte` module imports
- * (found by scanning) and those the user named via `external`.  `unscannable` are
+ * (found by scanning) and those the user named via `preserve`.  `unscannable` are
  * modules the scan could not read/parse (a component mounted from one is NOT
- * escaped — the Shell warns and the user lists it in `external`); `unmatchedExternal`
- * are `external` entries that matched no component (a typo leaves the intended
- * component un-frozen).  Returning them as data lets each Shell — the Vite plugin,
+ * escaped — the Shell warns and the user lists it in `preserve`); `unmatchedPreserve`
+ * are `preserve` entries that matched no component (a typo leaves the intended
+ * component unpreserved).  Returning them as data lets each Shell — the Vite plugin,
  * or a future `eslint-plugin-svelte` rule — report in its own voice.
  */
 export interface EscapeScanResult {
     escaped: ComponentId[];
     unscannable: ComponentId[];
-    unmatchedExternal: string[];
+    unmatchedPreserve: string[];
 }
 /**
- * Compute the {@link EscapeScanResult} from "include roots + resolver + component
+ * Compute the {@link EscapeScanResult} from "entry roots + resolver + component
  * set".  The one helper a Shell calls (the only escape-scan symbol re-exported from
  * `svelte-shaker/node`).
  */
 export declare function computeEscapedComponents(opts: {
-    /** Absolute include roots (already resolved against the project root). */
-    includeDirs: string[];
-    /** Project root, for resolving relative `external` entries. */
+    /**
+     * Absolute crawl-entry roots (already resolved against the project root) — the
+     * Vite plugin's `entries`.  The SAME roots drive two different walks: collecting
+     * the `.svelte` crawl entries, and (here) collecting the non-`.svelte` modules to
+     * scan for call sites that escape the component graph.
+     */
+    entryDirs: string[];
+    /** Project root, for resolving relative `preserve` entries. */
     root: string;
-    /** User-declared `external` prefixes (root-relative or absolute), if any. */
-    external?: string[] | undefined;
-    /** The crawled `.svelte` component ids, for matching `external` prefixes. */
+    /** User-declared `preserve` prefixes (root-relative or absolute), if any. */
+    preserve?: string[] | undefined;
+    /** The crawled `.svelte` component ids, for matching `preserve` prefixes. */
     components: Iterable<ComponentId>;
     resolve: Resolve;
     readFile: ReadFile;

package/dist/escape-scan.js

@@ -1,7 +1,7 @@
 // ----------------------------------------------------------------------
 // Internal Shell helper (docs/ARCHITECTURE.md §4.2): find the components used from
 // OUTSIDE the analyzed `.svelte` graph — a `.ts`/`.js` call site the crawl cannot
-// parse, or a user-declared `external`.  NOT part of the `svelte-shaker/node` public
+// parse, or a user-declared `preserve`.  NOT part of the `svelte-shaker/node` public
 // surface: only `computeEscapedComponents` is re-exported there (`scan.ts`).  The
 // Vite Shell imports the rest of this module directly.
 // ----------------------------------------------------------------------
@@ -57,13 +57,13 @@ function collectNonSvelteModules(dir) {
  * Every module specifier a JS/TS module statically references: `import … from`,
  * `export … from` / `export *`, and a dynamic `import('…')` whose argument is a
  * STRING LITERAL.  A computed dynamic import (`import(expr)`) is unknowable here —
- * the `external` option (docs §4.2) is the sound fallback for it.  Parsed via the
+ * the `preserve` option (docs §4.2) is the sound fallback for it.  Parsed via the
  * Svelte parser's `<script module lang="ts">` wrapper (the same TS-capable parse
  * the engine's barrel-following uses).  Returns `null` when the module does NOT
  * parse — the wrapper handles TS but not JSX, and rejects some exotic syntax
  * (`.jsx`/`.tsx` bodies, bleeding-edge TS), and a parse failure hides any call site
  * inside, so the caller must surface it (a mounted component would go un-escaped);
- * `external` is the fix for that file.
+ * `preserve` is the fix for that file.
  */
 function moduleImportSpecifiers(code, id) {
     let module;
@@ -71,7 +71,7 @@ function moduleImportSpecifiers(code, id) {
         module = parseSvelte(`<script module lang="ts">\n${code}\n</script>`, id).module;
     }
     catch {
-        return null; // unparseable — the caller reports it (soundness hole, `external` fixes it)
+        return null; // unparseable — the caller reports it (soundness hole, `preserve` fixes it)
     }
     const program = module?.content;
     if (!program)
@@ -115,7 +115,7 @@ function moduleImportSpecifiers(code, id) {
  * A module that cannot be read or parsed is collected into `unscannable` (NOT
  * silently dropped): a call site inside it is invisible, so the caller must warn.
  */
-async function collectExternalEscapes(modules, resolve, readFile) {
+async function collectModuleEscapes(modules, resolve, readFile) {
     const escaped = new Set();
     const unscannable = new Set();
     for (const id of modules) {
@@ -141,22 +141,22 @@ async function collectExternalEscapes(modules, resolve, readFile) {
     return { escaped, unscannable };
 }
 /**
- * Partition user-declared `external` prefixes (docs §4.2) against a known component
- * set into the components they FREEZE and the entries that matched NOTHING.  Each
+ * Partition user-declared `preserve` prefixes (docs §4.2) against a known component
+ * set into the components they PRESERVE and the entries that matched NOTHING.  Each
  * entry is a Vite-root-relative or absolute path naming EITHER a component file
  * (exact match) OR a directory (every component under it) — the same "directory or
- * file prefix" basis as `include`, with no glob dependency.  An entry matching no
+ * file prefix" basis as `entries`, with no glob dependency.  An entry matching no
  * component is almost always a typo / wrong path (or a missing `.svelte`
  * extension), so it is returned in `unmatched` for the caller to surface rather
- * than being a silent no-op that leaves the intended component un-frozen.
+ * than being a silent no-op that leaves the intended component unpreserved.
  */
-function partitionExternal(external, root, components) {
+function partitionPreserve(preserve, root, components) {
     const matched = new Set();
     const unmatched = [];
-    if (!external || external.length === 0)
+    if (!preserve || preserve.length === 0)
         return { matched, unmatched };
     const ids = [...components];
-    for (const entry of external) {
+    for (const entry of preserve) {
         // `path.resolve` leaves an absolute entry as-is and resolves a relative one
         // against `root` — exactly "Vite-root-relative or absolute".
         const prefix = path.resolve(root, entry);
@@ -169,25 +169,25 @@ function partitionExternal(external, root, components) {
     }
     return { matched, unmatched };
 }
-/** The components a set of `external` prefixes freezes (docs §4.2).  The
- * {@link partitionExternal} projection that drops the "matched nothing" diagnostic
+/** The components a set of `preserve` prefixes protects (docs §4.2).  The
+ * {@link partitionPreserve} projection that drops the "matched nothing" diagnostic
  * — kept for callers that only need the ids. */
-export function matchExternal(external, root, components) {
-    return [...partitionExternal(external, root, components).matched];
+export function matchPreserve(preserve, root, components) {
+    return [...partitionPreserve(preserve, root, components).matched];
 }
 /**
- * Compute the {@link EscapeScanResult} from "include roots + resolver + component
+ * Compute the {@link EscapeScanResult} from "entry roots + resolver + component
  * set".  The one helper a Shell calls (the only escape-scan symbol re-exported from
  * `svelte-shaker/node`).
  */
 export async function computeEscapedComponents(opts) {
-    const { escaped, unscannable } = await collectExternalEscapes(opts.includeDirs.flatMap(collectNonSvelteModules), opts.resolve, opts.readFile);
-    const { matched, unmatched } = partitionExternal(opts.external, opts.root, opts.components);
+    const { escaped, unscannable } = await collectModuleEscapes(opts.entryDirs.flatMap(collectNonSvelteModules), opts.resolve, opts.readFile);
+    const { matched, unmatched } = partitionPreserve(opts.preserve, opts.root, opts.components);
     for (const id of matched)
         escaped.add(id);
     return {
         escaped: [...escaped],
         unscannable: [...unscannable].sort(),
-        unmatchedExternal: unmatched,
+        unmatchedPreserve: unmatched,
     };
 }

package/dist/ir.d.ts

@@ -39,12 +39,13 @@ export interface AnalyzeInput {
     /**
      * Components with at least one consumer OUTSIDE the analyzed `.svelte` graph —
      * a call site in a `.ts`/`.js` module (`mount(Comp, …)`, a lazy `import()`), or
-     * a user-declared `external` (docs/ARCHITECTURE.md §4.2).  The Shell computes
+     * a user-declared `preserve` (docs/ARCHITECTURE.md §4.2).  The Shell computes
      * this set (its FS scan cannot parse `.ts` call sites); the engine unions it
      * into the same whole-component escape bail auto-detected escapes use, so these
      * components are never folded and never reported as never-passed — while their
-     * OWN call sites still count toward their children.  Omitted/`[]` means "no
-     * external consumers", keeping the output byte-for-byte unchanged.
+     * OWN call sites still count toward their children.  Omitted/`[]` means every
+     * consumer is inside the crawled `.svelte` graph, keeping the output
+     * byte-for-byte unchanged.
      */
     escaped?: ComponentId[];
 }

package/dist/parse.d.ts

@@ -21,6 +21,8 @@ export interface AnyNode {
     init?: AnyNode | undefined;
     key?: AnyNode | undefined;
     property?: AnyNode | undefined;
+    /** MemberExpression object (`$state` in `$state.raw`). */
+    object?: AnyNode | undefined;
     source?: AnyNode | undefined;
     local?: AnyNode | undefined;
     /** ImportSpecifier / ExportSpecifier exported-name slot. */
@@ -46,6 +48,8 @@ export interface AnyNode {
     members?: AnyNode[] | undefined;
     body?: AnyNode[] | undefined;
     declarations?: AnyNode[] | undefined;
+    /** CallExpression / NewExpression arguments (`0` in `$state(0)`). */
+    arguments?: (AnyNode | null)[] | undefined;
     specifiers?: AnyNode[] | undefined;
     nodes?: AnyNode[] | undefined;
     /** SnippetBlock parameters; ArrayPattern elements; DebugTag identifiers. */

package/dist/transform.js

@@ -19,6 +19,21 @@ export function transformAll(models, plans) {
 }
 /** Shared empty local fold env for a bailed owner (nothing forwards a constant). */
 const EMPTY_LOCAL_ENV = new Map();
+/**
+ * Merge an owner's static script constants with its remapped folded props for the
+ * phase-2 side-effect check.  Both are keyed by LOCAL name and are disjoint (a
+ * `$props()` local and a top-level script const cannot share a name — JS
+ * redeclaration), so the merge is order-independent; either operand is returned
+ * as-is when the other is empty (the common case).  Mirrors analyze.ts's
+ * `mergeScriptConsts` (kept separate so neither module imports the other).
+ */
+function mergeLocalConstEnv(scriptConsts, foldedProps) {
+    if (scriptConsts.size === 0)
+        return foldedProps;
+    if (foldedProps.size === 0)
+        return scriptConsts;
+    return new Map([...scriptConsts, ...foldedProps]);
+}
 /**
  * Phases 1–2, shared by {@link transformAll} and {@link transformAllWithMono}:
  * fold each component body and drop its folded props (phase 1), then strip the
@@ -68,11 +83,13 @@ function runBasePhases(models, plans) {
     // skipping any call site phase 1 folded away (its attributes went with it).
     for (const model of models.values()) {
         const plan = plans.get(model.id);
-        // A forwarded expression (`<Child prop={ownerProp}/>`) was substituted to a
-        // literal in phase 1 when `ownerProp` is folded; its attribute is then just
-        // as removable as a written literal.  Give phase 2 the owner's fold env
-        // (local-keyed, as the expression references props) so it can recognize that.
-        const ownerEnv = plan.bail ? EMPTY_LOCAL_ENV : remapToLocalNames(plan.constFold, model);
+        // A forwarded expression (`<Child prop={ownerProp}/>`) that the owner proves
+        // constant — a folded prop OR an owner-local script constant (docs §13.1) — is
+        // side-effect-free, so once the child drops the prop its attribute is as
+        // removable as a written literal.  Give phase 2 the owner's fold env plus its
+        // `scriptConstEnv`, both local-keyed as the expression references props/locals.
+        const foldEnv = plan.bail ? EMPTY_LOCAL_ENV : remapToLocalNames(plan.constFold, model);
+        const ownerEnv = mergeLocalConstEnv(model.scriptConstEnv, foldEnv);
         removeCallSiteAttributes(model, dropped, strings.get(model.id), editedSpans.get(model.id) ?? [], ownerEnv);
     }
     // Phase 2.5 — reverse (docs §PR4) + unread declared (docs §PR7): delete the

package/dist/unread.js

@@ -81,7 +81,8 @@ export function collectUnread(models, plans) {
     // (b): a prop is droppable when it survived every site's veto (and had the
     // structural gates).  A child with NO call sites keeps every `true` here — safe,
     // since the child does not read the prop, so its own render is unchanged whether
-    // it is declared or not (and external consumers, if any, bail the child).
+    // it is declared or not (and a consumer outside the `.svelte` graph, if any,
+    // bails the child).
     for (const [id, perProp] of dropEligible) {
         const set = new Set();
         for (const [name, ok] of perProp)

package/dist/vite.d.ts

@@ -1,32 +1,57 @@
 import type { Plugin } from 'vite';
 import { type DevMode } from './engine.js';
 import { type MonomorphizeOptions } from './mono.js';
+/**
+ * Options for the {@link shaker} plugin.  The set below is exhaustive: any other
+ * key throws at build start rather than being ignored, because an option we never
+ * read is an option the user thinks is applied and is not.
+ */
 export interface ShakerOptions {
     /**
-     * Directories (relative to the Vite root) to scan for `.svelte` components.
-     * Defaults to the Vite root itself.  Every `.svelte` file found is treated as
-     * a call-site source, so the union of these dirs must contain the whole app
-     * for prop elimination to be sound (docs/ARCHITECTURE.md §4.2).
+     * Directories (relative to the Vite root) the component crawl STARTS from —
+     * the same semantics as SvelteKit's `config.kit.prerender.entries`: you list
+     * the roots, and everything reachable from them is pulled in by following the
+     * import graph.  Defaults to the Vite root itself.  No glob: each entry is a
+     * directory (or a single component file), matched on a plain path-prefix basis.
+     *
+     * This is NOT an include filter, and it does not bound what gets rewritten: a
+     * library component in `node_modules` is never under an entry root, yet it is
+     * still crawled and shaken, because a component that IS under one imports it.
+     *
+     * The soundness contract runs the other way.  Every `.svelte` file found is
+     * treated as a call-site source, so the union of these roots must cover EVERY
+     * call site in the app (docs/ARCHITECTURE.md §4.2).  Narrowing `entries` to a
+     * subset of the app does not shake less — it hides call sites, and a prop the
+     * shaker cannot see being passed is folded away.
      */
-    include?: string[];
+    entries?: string[];
     /**
-     * Components that have a consumer the shake cannot see, so they must never be
-     * folded or narrowed (docs/ARCHITECTURE.md §4.2).  Each entry is a Vite-root-
-     * relative or absolute path naming EITHER a component file or a directory of
-     * them — the same "directory or file prefix" basis as {@link include}, no glob.
+     * Components whose PROP INTERFACE must be left exactly as written, because they
+     * have a consumer the shake cannot see (docs/ARCHITECTURE.md §4.2).  Each entry
+     * is a Vite-root-relative or absolute path naming EITHER a component file or a
+     * directory of them — the same "directory or file prefix" basis as
+     * {@link entries}, no glob.
+     *
+     * What is preserved is the prop interface, NOT the component's presence in the
+     * bundle: this is unrelated to Rollup/Vite's `external`, and it never keeps a
+     * file out of the bundle or out of the analysis.
+     *
+     * Reach for it when a consumer lives outside the `.svelte` graph and the shaker
+     * cannot observe that call site: a `mount()` behind a NON-literal dynamic
+     * `import(expr)`, or a module outside the {@link entries} roots.  Consumers
+     * reached by a static `.ts`/`.js` import are already found by the non-`.svelte`
+     * module scan, so those need no entry here.
      *
-     * The non-`.svelte` module scan already escapes components reached by a static
-     * `.ts`/`.js` import; `external` is the sound fallback for what the scan cannot
-     * see — most importantly a NON-literal dynamic `import(expr)`, or a call site in
-     * a module outside the include roots.
+     * A-semantics — listing a component does NOT exclude it from the scan: the file
+     * stays fully in the analysis (its own `<Child/>` call sites keep counting toward
+     * its children's profiles), and only the component ITSELF has its prop folding /
+     * never-passed reporting turned off.  It is not a way to make the shaker ignore
+     * a file.
      *
-     * A-semantics — this FREEZES the named component, it does NOT exclude it from the
-     * scan: the file stays fully in the analysis (its own `<Child/>` call sites keep
-     * counting toward its children's profiles), and only the component ITSELF has its
-     * prop folding / never-passed reporting turned off.  It is not a way to make the
-     * shaker ignore a file.
+     * Over-listing errs SAFE, the opposite of {@link entries}: a component preserved
+     * without needing it is merely shaken less, never wrongly.
      */
-    external?: string[];
+    preserve?: 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

package/dist/vite.js

@@ -99,6 +99,62 @@ function resolveMono(options) {
     const overrides = typeof options.monomorphize === 'object' ? options.monomorphize : {};
     return { ...DEFAULT_MONO_OPTIONS, enabled: true, ...overrides };
 }
+/**
+ * Options renamed in the pre-1.0 cleanup: stale key -> what to write instead and
+ * why the old name described the wrong thing.  Both renames dropped a name the
+ * ecosystem had already spent on a DIFFERENT meaning, so the message has to say
+ * more than "renamed" — a user who reaches for the old key is usually carrying
+ * the old key's ecosystem meaning with it.
+ */
+const RENAMED_OPTIONS = {
+    include: 'the "include" option was renamed to "entries": rename `include:` to `entries:`. It was ' +
+        'never a file filter — it lists the directories the component crawl STARTS from, and ' +
+        'everything reachable from them (including library components under node_modules) is ' +
+        'shaken whether or not it sits under one.',
+    external: 'the "external" option was renamed to "preserve": rename `external:` to `preserve:`. It ' +
+        'has nothing to do with Rollup/Vite `external` — it never keeps a file out of the bundle. ' +
+        'It names components whose prop interface must be left as written because a consumer the ' +
+        'shaker cannot see (a non-literal dynamic `import(expr)`, a module outside `entries`) ' +
+        'passes props to them.',
+};
+/**
+ * Every key {@link ShakerOptions} accepts.  The `satisfies` is the point of the
+ * table: adding an option to the interface without listing it here fails
+ * `tsc --noEmit`, so the accept-list can never drift behind the type and start
+ * rejecting a valid config.
+ */
+const KNOWN_OPTIONS = {
+    entries: true,
+    preserve: true,
+    monomorphize: true,
+    engine: true,
+    dev: true,
+    parser: true,
+    verbose: true,
+};
+/**
+ * Reject anything that is not an option we act on.  A Vite config is external
+ * input, so this is a boundary check, not a courtesy: an ignored key still
+ * builds, but what the user configured quietly does not apply — `entries` falls
+ * back to the Vite root, `preserve` to an empty set, and that last one ships an
+ * over-shaken component.
+ *
+ * A typo (`preserv:`) fails in exactly that way, which is why unknown keys are
+ * rejected on the same footing as the pre-rename keys ({@link RENAMED_OPTIONS})
+ * rather than only the ones we happen to have a migration note for.  TypeScript's
+ * excess-property check only fires on an object literal written inline, so a
+ * config built up in a variable — or any JS config — reaches us unguarded.
+ */
+function assertValidOptions(options) {
+    for (const key of Object.keys(options)) {
+        if (Object.hasOwn(RENAMED_OPTIONS, key))
+            throw new Error(`[vite-plugin-svelte-shaker] ${RENAMED_OPTIONS[key]}`);
+        if (!Object.hasOwn(KNOWN_OPTIONS, key))
+            throw new Error(`[vite-plugin-svelte-shaker] unknown option "${key}". Valid options are: ` +
+                `${Object.keys(KNOWN_OPTIONS).join(', ')}. Check the spelling — an option we ` +
+                `do not read is an option that does not apply.`);
+    }
+}
 /**
  * Source-level Svelte tree-shaking as a Vite plugin (docs/ARCHITECTURE.md §6).
  *
@@ -119,6 +175,7 @@ function resolveMono(options) {
  * variant id (dedup), so they share one compiled module.
  */
 export function shaker(options = {}) {
+    assertValidOptions(options);
     const mono = resolveMono(options);
     let shaken = {};
     /** Variant request id (`<childPath>?shaker_variant=<n>`) -> residual source. */
@@ -129,22 +186,24 @@ export function shaker(options = {}) {
     let log = (msg) => console.info(`[svelte-shaker] ${msg}`);
     let warn = (msg) => console.warn(`[svelte-shaker] ${msg}`);
     // Surface the escape scan's diagnostics (docs §4.2) as build warnings: modules the
-    // scan could not parse (a component mounted from one is left un-frozen — a real
-    // soundness hole), and `external` entries that matched no component (a typo leaves
-    // the intended component un-frozen).  Both are actionable and name the offenders,
+    // scan could not parse (a component mounted from one is left unpreserved — a real
+    // soundness hole), and `preserve` entries that matched no component (a typo leaves
+    // the intended component unpreserved).  Both are actionable and name the offenders,
     // but never fail the build — the shake is still emitted.
     const reportEscapeDiagnostics = (result) => {
         if (result.unscannable.length > 0) {
-            warn(`external call-site scan could not parse ${result.unscannable.length} module(s), so a ` +
-                `.svelte component mounted from one of them is NOT protected and may be over-shaken. ` +
-                `If a component is mounted from any of these, add it to the \`external\` option:\n` +
+            warn(`could not parse ${result.unscannable.length} non-\`.svelte\` module(s), so any ` +
+                `component mounted from one of them is invisible to the shake and may be ` +
+                `over-shaken (props it is really passed folded away). If any of these mounts a ` +
+                `component, list that component in the \`preserve\` option to keep its props:\n` +
                 result.unscannable.map((f) => `  - ${path.relative(root, f) || f}`).join('\n'));
         }
-        if (result.unmatchedExternal.length > 0) {
-            warn(`\`external\` matched no component for ${result.unmatchedExternal.length} entr` +
-                `${result.unmatchedExternal.length === 1 ? 'y' : 'ies'} (check the path and that a ` +
-                `file entry keeps its \`.svelte\` extension); the intended component is NOT frozen:\n` +
-                result.unmatchedExternal.map((e) => `  - ${e}`).join('\n'));
+        if (result.unmatchedPreserve.length > 0) {
+            warn(`\`preserve\` matched no component for ${result.unmatchedPreserve.length} entr` +
+                `${result.unmatchedPreserve.length === 1 ? 'y' : 'ies'} (check the path, and that a ` +
+                `file entry keeps its \`.svelte\` extension); the intended component is NOT ` +
+                `preserved, so its props can still be folded:\n` +
+                result.unmatchedPreserve.map((e) => `  - ${e}`).join('\n'));
         }
     };
     // Dev (serve) shaking is opt-in (docs §6.2); `null` keeps dev a pass-through.
@@ -203,22 +262,24 @@ export function shaker(options = {}) {
         async configureServer(server) {
             if (!devMode)
                 return;
-            const dirs = (options.include ?? ['.']).map((p) => path.resolve(root, p));
-            const entries = dirs.flatMap(collectSvelteFiles);
+            const dirs = (options.entries ?? ['.']).map((p) => path.resolve(root, p));
+            // 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(collectSvelteFiles);
             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
-            // `external` (docs §4.2).  Dev uses the same relative-only `fsResolve` the dev
+            // `preserve` (docs §4.2).  Dev uses the same relative-only `fsResolve` the dev
             // crawl uses, so the escape scope matches the crawl scope — dev is never more
             // unsound than build.  The sorted-join key lets a change that does not move the
             // escape set skip the reload.
             let escapedKey = '';
             const currentEscaped = async () => {
                 const result = await computeEscapedComponents({
-                    includeDirs: dirs,
+                    entryDirs: dirs,
                     root,
-                    external: options.external,
-                    components: entries,
+                    preserve: options.preserve,
+                    components: entryComponents,
                     resolve: fsResolve,
                     readFile: read,
                 });
@@ -226,7 +287,7 @@ export function shaker(options = {}) {
                 escapedKey = [...result.escaped].sort().join('\n');
                 return result.escaped;
             };
-            devShaker = new DevShaker(entries, fsResolve, read, devMode, getParse(), await currentEscaped());
+            devShaker = new DevShaker(entryComponents, fsResolve, read, devMode, getParse(), await currentEscaped());
             shaken = await devShaker.init();
             const applyDelta = (result) => {
                 for (const [id, code] of Object.entries(result.changed))
@@ -301,9 +362,11 @@ export function shaker(options = {}) {
         async buildStart() {
             if (devShaker)
                 return;
-            const dirs = (options.include ?? ['.']).map((p) => path.resolve(root, p));
-            const entries = dirs.flatMap(collectSvelteFiles);
-            if (entries.length === 0) {
+            const dirs = (options.entries ?? ['.']).map((p) => path.resolve(root, p));
+            // 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(collectSvelteFiles);
+            if (entryComponents.length === 0) {
                 shaken = {};
                 variantSources = new Map();
                 return;
@@ -334,13 +397,13 @@ export function shaker(options = {}) {
             };
             // Components used from OUTSIDE the `.svelte` graph must not be folded (docs
             // §4.2): those a non-`.svelte` module imports (found by the scan) plus any the
-            // user froze via `external`.  Hand the engine that escape set, and surface the
-            // scan's diagnostics (unparseable modules / unmatched `external`) as warnings.
+            // user pinned via `preserve`.  Hand the engine that escape set, and surface the
+            // scan's diagnostics (unparseable modules / unmatched `preserve`) as warnings.
             const escapeScan = await computeEscapedComponents({
-                includeDirs: dirs,
+                entryDirs: dirs,
                 root,
-                external: options.external,
-                components: entries,
+                preserve: options.preserve,
+                components: entryComponents,
                 resolve,
                 readFile: read,
             });
@@ -367,12 +430,12 @@ export function shaker(options = {}) {
                 // Native Rust engine — byte-identical to the JS engine, including
                 // monomorphization.
                 if (mono.enabled) {
-                    const result = await svelteShakerWasmWithMono(wasm, entries, resolve, read, mono, getParse(), escaped);
+                    const result = await svelteShakerWasmWithMono(wasm, entryComponents, resolve, read, mono, getParse(), escaped);
                     shaken = result.files;
                     variantSources = result.variants;
                 }
                 else {
-                    shaken = await svelteShakerWasm(wasm, entries, resolve, read, getParse(), escaped);
+                    shaken = await svelteShakerWasm(wasm, entryComponents, resolve, read, getParse(), escaped);
                     variantSources = new Map();
                 }
                 reportSizes(shaken, read, root, options.verbose === true, log);
@@ -381,12 +444,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(entries, resolve, read, getParse(), escaped);
+                shaken = await svelteShaker(entryComponents, resolve, read, getParse(), escaped);
                 variantSources = new Map();
                 reportSizes(shaken, read, root, options.verbose === true, log);
                 return;
             }
-            const result = await svelteShakerWithMono(entries, resolve, read, mono, variantSpecifier, getParse(), escaped);
+            const result = await svelteShakerWithMono(entryComponents, resolve, read, mono, variantSpecifier, getParse(), 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.13.0",
+  "version": "0.14.1",
   "description": "Tree shaking for Svelte components",
   "keywords": [
     "dead-code-elimination",