svelte-shaker 0.12.0 → 0.14.0

package/README.md

@@ -4,76 +4,60 @@
 
 <h1 align="center">svelte-shaker</h1>
 
-<p align="center">A <strong>sound, source-level tree-shaker for Svelte&nbsp;5 (runes) components.</strong></p>
-
-**▶ Try it in the browser: https://baseballyama.github.io/svelte-shaker/** — an
-interactive playground that runs the engine entirely client-side (and is itself
-built with rsvelte + dogfooded through svelte-shaker).
-
-It runs in your app's production build, _before_ the Svelte compiler, and slims
-each `.svelte` file by partially evaluating it against how the **whole app**
-actually uses it: props that are never passed (or always passed the same value)
-are folded to their constant, the dead `{#if}` arms behind them are deleted,
-those props are dropped from the `$props()` signature, and the now-pointless
-attributes are removed at every call site. The Svelte compiler then only sees the
-code your app can actually reach.
-
-It is **sound first**: it never changes what the user sees. When it cannot prove
-a transform is safe, it leaves the code untouched (bails).
-
-See [`docs/ARCHITECTURE.md`](https://github.com/baseballyama/svelte-shaker/blob/main/docs/ARCHITECTURE.md) for the full design.
-
-## Why this exists (and why a JS bundler can't do it)
-
-Design-system components carry lots of props (`Button` with
-`variant / size / loading / icon / iconPosition / fullWidth / rounded / href …`),
-but any one app uses only a few. The code behind the unused props — template
-branches, class computation, reactive statements, imports, CSS — is effectively
-dead for that app, yet it ships anyway.
-
-It cannot be removed _after_ Svelte compiles, because Svelte emits **one generic
-JS module per component**, shared by every caller. In that JS the prop values
-flow through the runtime (`$.prop(...)`), so `loading` / `variant` are not static
-JS constants — terser/esbuild/Rollup cannot fold `if (loading)` to `if (false)`,
-and the single module has no whole-program information to know which props this
-particular app never uses.
-
-svelte-shaker works **one step earlier**, on the pre-compile Svelte source, where
-the prop's value (its default, or the literal at the call site) is still visible
-and the template structure is intact. It is essentially a **whole-program partial
-evaluator + dead-code eliminator that understands Svelte**, driven by every call
-site in the app.
-
-### The CSS differentiator (what a bundler genuinely can't reach)
-
-Given `class="btn btn-{variant}"` where the app only ever passes
-`variant ∈ {primary, secondary}`, the class `btn-danger` can never exist at
-runtime. But the class only appears as a runtime string, so:
-
-- Svelte's own unused-CSS pruning keeps `.btn-danger` (it can't see inside the
-  interpolation), and
-- Rollup/terser can't touch it either (the class isn't in the JS at all).
-
-svelte-shaker computes the reachable value set of `variant`, proves the
-`.btn-danger` / `.btn-ghost` rules can never match any element this component
-renders, and **removes those `<style>` rules** — while keeping `.btn`,
-`.btn-primary`, `.btn-secondary`. This is verified end-to-end in
-`packages/svelte-shaker/tests/css.test.ts`.
+<p align="center">
+  <strong>A sound, source-level tree-shaker for Svelte&nbsp;5 (runes) components.</strong>
+</p>
+
+**▶ Try it in the browser: https://baseballyama.github.io/svelte-shaker/** — the
+playground runs the engine entirely client-side.
+
+svelte-shaker runs in your production build, **before** the Svelte compiler, and
+slims each `.svelte` file by partially evaluating it against how your **whole
+app** actually uses it: props no call site passes (or that always receive the
+same value) are folded to their constant, the dead `{#if}` arms behind them are
+deleted, the props are dropped from `$props()`, the attributes are removed at
+every call site, and `<style>` rules whose class can never be produced are
+stripped.
+
+It is **sound first**: it never changes what renders. When a transform can't be
+proven safe, the code is left untouched (bails).
+
+## Why a JS bundler can't do this
+
+Design-system components carry many props (`variant / size / loading / icon …`),
+but any one app uses only a few — yet the code behind the unused props still
+ships. A minifier _can_ fold a component-local constant (it compiles to plain
+JS). A prop is different: Svelte emits **one generic JS module per component**,
+shared by every caller, and the prop's value reaches it through runtime
+indirection (`$.prop(...)`), so turning `if (loading)` into `if (false)` would
+take constant propagation across component boundaries — something neither
+Rollup nor terser performs, even when every call site passes the same literal.
+svelte-shaker works one step earlier, on the pre-compile source, where
+call-site values and template structure are still visible.
+
+The clearest win is CSS: given `class="btn btn-{variant}"` where the app only
+ever passes `primary` / `secondary`, the class `btn-danger` can never exist at
+runtime — but it only appears as a runtime string, so neither Svelte's own
+unused-CSS pruning nor the bundler can prove that. svelte-shaker computes the
+reachable value set of `variant` and removes the `.btn-danger` rule.
 
 ## Install
 
 ```sh
-pnpm add -D svelte-shaker
-# or: npm i -D svelte-shaker / yarn add -D svelte-shaker
+npm i -D svelte-shaker   # requires svelte@^5
 ```
 
-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)).
 
 ## Usage (Vite)
 
-Add the plugin **before** `svelte()` so it hands already-slimmed source to the
-Svelte compiler. It is **build-only by design** — dev is a pass-through (see
-[Soundness](#soundness) / [Limitations](#limitations)).
+Add the plugin **before** `svelte()`. It runs only in `vite build` — dev/HMR is
+a pass-through by design. Out of the box it runs the native **Rust (WASM)
+engine** and parses with **rsvelte**; both fall back cleanly (see
+[Options](#options)).
 
 ```ts
 // vite.config.ts
@@ -83,161 +67,162 @@ 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(),
   ],
 });
 ```
 
-There is also a plain-Rollup plugin (`rollup-plugin-svelte-shaker`) for non-Vite
-pipelines; the Vite plugin is preferred for apps.
+For plain-Rollup pipelines, wire the shake up yourself with the public engine
+API (`svelte-shaker`) and the file-system helpers in `svelte-shaker/node`. Note
+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.
 
 ### Options
 
 ```ts
 shaker({
-  include: ['src'], // dirs (relative to root) holding every .svelte call site
-  level: 2, //  0 | 1 | 2 — default 2 (L0/L1/L1.5 always on; 2 also enables L2).
-  monomorphize: true, // L2 tuning; on by default — object overrides maxVariants/minSavings.
-  engine: 'auto', // 'auto' (default) | 'js' | 'rust' — see below.
-  parser: 'svelte', // 'svelte' (default) | 'rsvelte' — 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
+
+  // 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)
 });
-
-// L2 is ON by default (it is bail-safe and never bloats). Turn it OFF for faster
-// builds, or tune it:
-shaker({ include: ['src'], level: 1 }); // L2 off (L0/L1/L1.5 only)
-shaker({ include: ['src'], monomorphize: { maxVariants: 16 } }); // raise the variant cap
-
-// Engine: the native Rust (WASM) engine runs the whole shake INCLUDING L2 (it
-// calls back to JS only for the net-win gate's compiled-size proxy) and is
-// differentially tested to be byte-identical to the JS engine, so it only changes
-// speed. It is the default ('auto'); force it (or the JS engine) explicitly with:
-shaker({ include: ['src'], engine: 'rust' }); // or engine: 'js'
-
-// Opt into the faster rsvelte parser (~1.46x full build, ~2.2x parse).
-// Requires the optional peer `@rsvelte/vite-plugin-svelte-native` (install it
-// yourself). Soundness is unchanged — it only affects speed and, occasionally,
-// shakes a little more. If the native package can't load it THROWS (no silent
-// fallback) so the output stays the same on every machine.
-shaker({ include: ['src'], parser: 'rsvelte' });
-```
-
-### The rsvelte (Rust) parser
-
-By default the engine parses with `svelte/compiler`. Setting `parser: 'rsvelte'`
-swaps in [rsvelte](https://github.com/rsvelte/rsvelte)'s native (Rust) parser,
-which dominates the shake pipeline (~85% of the time is parsing): on a real
-474-component app the full build runs **~1.46x faster** (parse alone ~2.2x).
-
-```sh
-# rsvelte's native parser is an OPTIONAL peer — install it to opt in:
-pnpm add -D @rsvelte/vite-plugin-svelte-native
-```
-
-```ts
-// vite.config.ts
-shaker({ include: ['src'], parser: 'rsvelte' });
 ```
 
-- **Soundness is parser-independent.** The engine reads only UTF-16
-  `start`/`end` offsets, so the chosen parser never changes _what_ is folded —
-  only how fast. The few differences from the `svelte/compiler` path are cases
-  where rsvelte happens to shake a little _more_, each still behavior-preserving.
-- **No silent fallback.** If `parser: 'rsvelte'` is requested but the native
-  package can't be loaded (not installed, or no prebuilt binary for the
-  platform), the plugin **throws** rather than quietly using `svelte/compiler` —
-  a silent fallback would make the same source shake differently depending on
-  whether the optional binary is present, breaking build reproducibility.
-
-See [`docs/RUST-MIGRATION.md`](https://github.com/baseballyama/svelte-shaker/blob/main/docs/RUST-MIGRATION.md)
-for the design.
-
-## What it does
-
-| Level    | What it removes                                                                                                                              | Default    |
-| -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
-| **L0**   | Props no call site ever passes → fold to the default, drop from `$props()`, strip the attribute at call sites                                | on         |
-| **L1**   | Props that collapse to one constant app-wide → fold + drop + strip every call site's attribute                                               | on         |
-| **L1.5** | Value-set **narrowing**: with `variant ∈ {primary, secondary}`, delete provably-dead `{#if}`/`{:else if}` arms (prop stays in the signature) | on         |
-| **CSS**  | `<style>` rules whose class can never be produced given the value sets — the bundler-can't differentiator                                    | on         |
-| **L2**   | Per-call-site monomorphization: specialize a component per prop shape (deduped by residual, capped by `maxVariants`)                         | on (set `level: 1` to disable) |
+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
+  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.
+- **`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,
+  a build with `monomorphize` on is never larger, byte for byte, than the same
+  build with it off (the 3 always-on passes alone). The knobs only trade off how
+  much specialization is *attempted* against build time:
+  - `maxVariants` (default `8`) — cap on distinct residual variants per
+    component. A child whose call sites produce more distinct shapes than the
+    cap can't be specialized at every site, so it keeps its base entirely
+    (all-sites-or-nothing — no partial split). Raise it for a large
+    design-system component (e.g. a `Button` used with more than 8 prop shapes
+    app-wide) you know is worth specializing further.
+  - `minSavings` (default `0`, i.e. any strict net reduction) — the net-win
+    threshold: a specialization is applied only when it measures
+    `Σ_spec < Σ_base × (1 − minSavings)`. Raising it only makes the gate more
+    conservative (fewer, bigger wins, faster builds) — no value makes
+    monomorphization unsound.
+
+  ```ts
+  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'`.
+- **`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
+
+| Pass                    | What it removes                                                                                                                              | Default |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| **unused-prop fold**    | Props no call site ever passes → fold to the default, drop from `$props()`, strip the attribute at call sites                                | on      |
+| **constant fold**       | Props that collapse to one constant app-wide → fold + drop + strip every call site's attribute                                               | on      |
+| **value-set narrowing** | With `variant ∈ {primary, secondary}`, delete provably-dead `{#if}`/`{:else if}` arms (prop stays in the signature)                          | on      |
+| **CSS**                 | `<style>` rules whose class can never be produced given the value sets                                                                       | on      |
+| **monomorphization**    | Per-call-site: specialize a component per prop shape (deduped by residual, capped by `maxVariants`)                                          | on (`monomorphize: false` to disable) |
 
 Folding also reaches template ternaries (`{cond ? a : b}`) and class-string
-interpolation when the condition/parts are provable constants.
+interpolation when the parts are provable constants.
 
 ## Soundness
 
 The whole point is to **never change observable behavior**.
 
-- **Differential-SSR verified.** Tests server-render the original and the shaken
-  component (comments stripped, whitespace normalized) and assert the HTML is
-  identical for every value the app actually passes
-  (`packages/svelte-shaker/tests/diff.ts`).
-- **Conservative bail.** When a transform can't be _proven_ safe, the code is
-  left as-is. Whole-component bails: `<svelte:options accessors />` /
-  `customElement`, and any component that **escapes** as a value
-  (`<svelte:component this={X}>`, assigned/passed/stored), or is rendered through
-  a barrel/named import (its call sites aren't enumerable). Per-prop bails:
-  spread that could overwrite it, callee `...rest`, `bind:`, a name shadowed by
-  `{#each as}` / snippet params / `{#await then}` / `let:` / `{@const}`, or used
-  in `{@debug}`.
-- **Side effects preserved.** A call-site attribute is only stripped if its value
-  has no side effects; a value's code is removed only when it is provably pure
-  and unused.
-- **Whole-program fixpoint.** Call sites inside a folded-away `{#if}` don't count
-  toward a child's prop profile; analysis iterates to a fixpoint so cascades are
-  consistent with what the transform actually deletes.
+- **Differential-SSR verified** — tests server-render the original and the
+  shaken component and assert the HTML is identical for every value the app
+  actually passes.
+- **Conservative bail** — anything unprovable is left as-is. Whole-component:
+  `<svelte:options accessors />` / `customElement`, components that escape as a
+  value, or are imported through a barrel (call sites not enumerable). Per-prop:
+  spread, callee `...rest`, `bind:`, shadowing, `{@debug}`.
+- **Side effects preserved** — an attribute or value is only removed when it is
+  provably pure and unused.
+- **Whole-program fixpoint** — call sites inside deleted branches don't count
+  toward a child's prop profile.
 
 ## Limitations
 
-- **Svelte 5 runes only** (`$props()` / `$derived` / `$effect`). Svelte 4
-  (`export let` / `$:` / `$$props`) is out of scope.
-- **Needs `.svelte` source.** Libraries shipping compiled JS can't be shaken (the
-  source has to be visible — that's the whole premise). Distribute via
-  `svelte-package`. Anything it can't resolve is silently passed through.
-- **Build only.** It runs in `vite build`, not in dev/HMR — whole-program
-  analysis is fundamentally incompatible with HMR's locality, and L1.5/CSS depend
-  on negative information ("this value never occurs") that a lazily-loaded dev
-  server can't guarantee. Dev is always a pass-through (and is unoptimized but
-  always correct). A `dev: 'coarse'` mode is a future opt-in.
-- **`include` must cover the whole app.** A call site outside the scanned dirs is
-  invisible, so soundness requires every consumer of a prop to be in scope.
-- **Partial-bail boundaries.** Spread/rest/`bind:`/shadowing limit how much can be
-  folded (by design — the engine errs toward keeping code). L2's `minSavings`,
-  and `exclude` / `unsafe` / `report` options, are reserved but not yet
-  implemented.
-
-## Running the tests
-
-```sh
-pnpm --filter svelte-shaker test     # vitest: eval / basic / shadow / probes2 / css / vite / mono
-pnpm format:fix && pnpm all:check    # type-check + lint + format
-```
-
-### Bench
-
-`packages/svelte-shaker/tests/css.test.ts` builds a tiny app
-(`App` passes `variant="primary"` and `variant="secondary"` to `Btn`, whose
-`<style>` defines `.btn-{primary,secondary,danger,ghost}`) two ways:
-
-- **control** (Svelte + Rollup, no shaker): keeps `.btn-danger` and `.btn-ghost`
-  in the emitted CSS — the toolchain cannot prove them dead.
-- **shaken**: removes `.btn-danger` / `.btn-ghost`, keeps `.btn` /
-  `.btn-primary` / `.btn-secondary`, and the rendered HTML is identical for both
-  variants the app passes.
-
-That's the headline result: the same source produces strictly smaller CSS with no
-behavior change.
-
-## Architecture & status
-
-The engine is split into an environment-free **Engine** (Svelte-aware analysis +
-transform) behind a stable IR, and a thin **Shell** (the Vite/Rollup plugin) that
-owns file IO and module resolution — so the core can later be ported to Rust
-(rsvelte / OXC). The current implementation status (what's done vs. remaining) is
-tracked in [`docs/ARCHITECTURE.md` §11](https://github.com/baseballyama/svelte-shaker/blob/main/docs/ARCHITECTURE.md#11-実装状況implementation-status).
+- **Svelte 5 runes only** — Svelte 4 (`export let` / `$:` / `$$props`) is out of
+  scope.
+- **Needs `.svelte` source** — libraries shipping compiled JS pass through
+  unshaken; distribute via `svelte-package`.
+- **Build only** — whole-program analysis is incompatible with dev/HMR locality,
+  so dev is always a pass-through.
+- **`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.
 
 ## License
 

package/dist/analyze.d.ts

@@ -8,6 +8,25 @@ export type ReadFile = (id: ComponentId) => Promise<string> | string;
  * {@link buildAnalyzeInputSync}. */
 export type ResolveSync = (source: string, importer: ComponentId) => ComponentId | null;
 export type ReadFileSync = (id: ComponentId) => string;
+/**
+ * The set of input names a child component can ever OBSERVE at runtime (docs
+ * §PR4 reverse analysis).  In runes there is no `$$props`/`$$restProps`, so a
+ * component reads an input only through its `$props()` destructure:
+ *  - `{ kind: 'names' }` — a clean, rest-free ObjectPattern `$props()` (or no
+ *    `$props()` at all, giving the empty set): the child can observe EXACTLY
+ *    these declared external names, so a call-site input NOT in the set can
+ *    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.
+ */
+export type ReachableInputs = {
+    kind: 'all';
+} | {
+    kind: 'names';
+    names: Set<string>;
+};
 /** One declared prop in a `$props()` destructuring. */
 export interface PropDecl {
     /** The EXTERNAL prop name — the destructure KEY (`prop` in `prop: alias`).
@@ -47,6 +66,22 @@ export interface FileModel {
     propsDeclaration?: AnyNode | undefined;
     propsPattern?: AnyNode | undefined;
     hasRestProp: boolean;
+    /**
+     * The inputs this component can observe (docs §PR4).  Drives the reverse pass:
+     * a call site of THIS component may drop an input outside {@link
+     * ReachableInputs}.  Computed syntactically from the `$props()` shape.
+     */
+    reachableInputs: ReachableInputs;
+    /**
+     * EXTERNAL names of props this component DECLARES but never READS (docs §PR7):
+     * destructured out of a clean `$props()` yet with zero value-position reference
+     * to their local binding anywhere in the instance script or template.  Such a
+     * prop is invisible to the child, so its call-site attribute is dead and — when
+     * safe — the declaration can be dropped.  Source-only (independent of the call
+     * sites), so it is computed ONCE here, never inside the fixpoint; the transform
+     * gates its use on the component's plan not being bailed.
+     */
+    unreadDeclaredProps: Set<string>;
     /**
      * Every `<Child .../>` instance THIS component renders, with the child it
      * resolves to and the AST node (so the fixpoint can test whether the site
@@ -69,6 +104,27 @@ export interface FileModel {
      * dropping the prop dangles the reference — we never fold a prop named here.
      */
     debugNames: Set<string>;
+    /**
+     * Names the component WRITES TO — reassigns (`p = …`, `p += …`), mutates with
+     * `++`/`--`, destructure-assigns (`({ p } = obj)`), or two-way `bind:`s.  A
+     * written prop is not a constant even when every call site passes the same
+     * literal: the write changes it at runtime, so folding it would substitute the
+     * literal into the write's target (`"a" = …`, `0++`, `bind:value={"a"}`) —
+     * invalid Svelte — and, more importantly, silently change what renders after
+     * 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
@@ -100,6 +156,14 @@ export interface ExplicitProp {
     value: Literal;
     dynamic: boolean;
     afterLastSpread: boolean;
+    /**
+     * For a `dynamic` write whose value is a single expression (`prop={expr}`, or a
+     * known-spread key `{...{prop: expr}}`), the raw expression node — kept so the
+     * fixpoint can try to fold it against the OWNING component's constFold env
+     * (interprocedural pass-through, docs §13.1).  Absent for a literal write, a
+     * `bind:` (a two-way write that must never fold), or a multi-part value.
+     */
+    expr?: AnyNode | undefined;
 }
 /** How a child component is called at one `<Child .../>` site. */
 export interface CallSite {
@@ -112,6 +176,13 @@ export interface CallSite {
     hadSpread: boolean;
     /** Last-write-wins explicit props at this site, keyed by prop name. */
     explicit: Map<string, ExplicitProp>;
+    /**
+     * The component that OWNS this call site (renders the `<Child .../>`).  The
+     * fixpoint uses it to evaluate a forwarded expression (`prop={ownerProp}`)
+     * against the owner's fold env — interprocedural pass-through (docs §13.1).
+     * `undefined` for callers that read a site outside the graph fixpoint (mono).
+     */
+    owner?: ComponentId | undefined;
 }
 export interface AnalyzeResult {
     models: Map<ComponentId, FileModel>;
@@ -129,7 +200,7 @@ export interface AnalyzeResult {
  *   (b) recomputing plans (and hence dead spans) from that usage,
  * until the plans stop changing.
  */
-export declare function analyze(entries: ComponentId | ComponentId[], resolve: Resolve, readFile: ReadFile): Promise<AnalyzeResult>;
+export declare function analyze(entries: ComponentId | ComponentId[], resolve: Resolve, readFile: ReadFile, escaped?: ComponentId[]): Promise<AnalyzeResult>;
 /**
  * The pure, environment-free engine entry (docs/RUST-MIGRATION.md §2): given a
  * fully-resolved, batched {@link AnalyzeInput}, build every component's model and
@@ -139,6 +210,18 @@ export declare function analyze(entries: ComponentId | ComponentId[], resolve: R
  * one batched call in, plans out, no per-edge callback across the boundary.
  */
 export declare function analyzeInput(input: AnalyzeInput, parseCache?: ParseCache): AnalyzeResult;
+/**
+ * Compute every component's plan to a whole-program fixpoint (docs §2.1) from the
+ * models' current `bailReasons` (escape stamps, and — on a revert re-run — the
+ * cascade's force-bail stamps).  Extracted so the revert cascade can RECOMPUTE the
+ * whole fixpoint after force-bailing a component, not just patch that one plan:
+ * with interprocedural pass-through (docs §13.1) a child's fold can depend on an
+ * owner's fold, so force-bailing the owner must un-fold the child too — an
+ * in-place patch of only the owner's plan would leave the child's drop stale
+ * (unsound).  This mirrors the Rust engine, which re-runs `run_fixpoint` after
+ * stamping `forceBail` onto the models.
+ */
+export declare function planFixpoint(models: Map<ComponentId, FileModel>): Map<ComponentId, ComponentPlan>;
 /**
  * The Shell-side resolution + IO layer (docs/RUST-MIGRATION.md §2.1): BFS-crawl
  * the component graph from `entries`, resolving every import edge and reading
@@ -152,14 +235,14 @@ export declare function analyzeInput(input: AnalyzeInput, parseCache?: ParseCach
  * import is never crawled — its `<Comp/>` site cannot exist, so it cannot taint a
  * value set), keeping the produced model set — and thus the output — identical.
  */
-export declare function buildAnalyzeInput(entries: ComponentId | ComponentId[], resolve: Resolve, readFile: ReadFile, parseCache?: ParseCache, parse?: Parse): Promise<AnalyzeInput>;
+export declare function buildAnalyzeInput(entries: ComponentId | ComponentId[], resolve: Resolve, readFile: ReadFile, parseCache?: ParseCache, parse?: Parse, escaped?: ComponentId[]): Promise<AnalyzeInput>;
 /**
  * Synchronous twin of {@link buildAnalyzeInput} for callers that cannot await
  * (an ESLint rule runs synchronously). Byte-for-byte the same crawl with sync
  * `resolve`/`readFile`; the `tests/build-analyze-input-sync` differential test
  * pins it identical to the async path, so keep the two bodies in lockstep.
  */
-export declare function buildAnalyzeInputSync(entries: ComponentId | ComponentId[], resolve: ResolveSync, readFile: ReadFileSync, parseCache?: ParseCache, parse?: Parse): AnalyzeInput;
+export declare function buildAnalyzeInputSync(entries: ComponentId | ComponentId[], resolve: ResolveSync, readFile: ReadFileSync, parseCache?: ParseCache, parse?: Parse, escaped?: ComponentId[]): AnalyzeInput;
 /**
  * Dead `{#if}` spans per component implied by `plans`, via the SAME shared
  * predicate the transform uses ({@link computeDeadSpans}).  A bailed component
@@ -190,11 +273,16 @@ export interface UnpassedProp {
  *    `+page.svelte`'s `data`, a framework mount, a not-yet-rendered component);
  *  - a prop is reported only when EVERY call site neither names it nor carries a
  *    spread that could set it (`readCallSite` already folds `bind:`, known
- *    spreads, and `children`/snippet body into `explicit`/`hadSpread`).
+ *    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 `preserve`, docs
+ *    §4.2) — is skipped, because that consumer may pass a prop the crawl cannot see.
  *
- * Because missing an edge (e.g. an unfollowed barrel) only DROPS call sites, it
- * can only make this UNDER-report (the component looks unused and is skipped),
- * never over-report — so an incomplete crawl stays false-positive-free.
+ * 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
+ * one way it could OVER-report is a consumer the crawl cannot parse at all — a
+ * `.ts`/`.js` call site; `input.escaped` (the Shell's non-`.svelte` scan) closes
+ * exactly that hole, so with it supplied the result stays false-positive-free.
  */
 export declare function findNeverPassedProps(input: AnalyzeInput): Map<ComponentId, UnpassedProp[]>;
 /**
@@ -218,7 +306,7 @@ export declare function remapToLocalNames<V>(map: Map<string, V>, model: FileMod
  * both contributes those literals AND does not poison props it cannot set (docs
  * §4.1, "{...obj} が object literal ならキー展開").
  */
-export declare function readCallSite(component: AnyNode): CallSite;
+export declare function readCallSite(component: AnyNode, owner?: ComponentId): CallSite;
 /** Decide what to fold for one component from its global usage. */
 /**
  * Whether a declared prop name is unsafe to fold/narrow/drop because it is also
@@ -226,7 +314,9 @@ export declare function readCallSite(component: AnyNode): CallSite;
  * (`{#each as}`, snippet params, `{#await then}`, `let:`, `{@const}`), or used as
  * a `{@debug}` argument (Svelte forbids a literal there). In those scopes the
  * name is a different entity, so folding it would corrupt the binding (often
- * invalid Svelte). Both L1 planning ({@link buildPlan}) and L2 specialization
- * (mono.ts) must honor this identically.
+ * invalid Svelte) — or WRITTEN TO (reassigned / `++` / destructure-assigned /
+ * `bind:`), in which case it is not a constant and folding it changes what
+ * renders after the write. Both constant fold planning ({@link buildPlan}) and
+ * monomorphization specialization (mono.ts) must honor this identically.
  */
 export declare function isFoldBlockedName(model: FileModel, name: string): boolean;