@ic-reactor/vite-plugin 0.14.0 → 4.0.0-beta.1

package/src/index.ts

@@ -1,48 +1,91 @@
 /**
  * @ic-reactor/vite-plugin
  *
- * Vite plugin that:
- * 1. Generates hooks at build time (using @ic-reactor/codegen pipeline)
- * 2. Injects `ic_env` cookie for local development (via proxy)
- * 3. Hot-reloads when .did files change
+ * Vite plugin for an app built on a candid-core generated module.
+ *
+ * - Generation: at the start of a build or dev server, and when a `.did` file
+ *   changes, it runs `candid-core-cli gen` in a child process (see
+ *   generate.ts) and leaves candid-core's module as the generator wrote it. No
+ *   wrapper files, hooks or reactors are generated.
+ * - Environment: under `vite dev` and `vite preview` it sets the `ic_env`
+ *   cookie and proxies `/api` to the local IC network (see dev-environment.ts).
  */
 
-import type { Plugin, ResolvedConfig, UserConfig, ViteDevServer } from "vite"
+import fs from "node:fs"
 import path from "node:path"
+import type {
+  Logger,
+  Plugin,
+  ProxyOptions,
+  ResolvedConfig,
+  UserConfig,
+  ViteDevServer,
+} from "vite"
 import {
-  runCanisterPipeline,
-  type CanisterConfig,
-  type CodegenConfig,
-  type CodegenTarget,
-} from "@ic-reactor/codegen"
-import { getIcEnvironmentInfo, buildIcEnvCookie } from "./env.js"
+  createLocalEnvironment,
+  icEnvMiddleware,
+  type LocalEnvironment,
+  type LocalEnvironmentState,
+} from "./dev-environment.js"
+import { GENERATE_TIMEOUT_MS, generate, resolveCliBin } from "./generate.js"
 
 const PLUGIN_NAME = "ic-reactor-plugin"
-const DEFAULT_LOCAL_REPLICA = "http://127.0.0.1:4943"
 
+/** Where a canister's module goes when it sets no `outDir`. */
+const DEFAULT_OUT_DIR = "src/canisters"
+
+/** The first line the plugin logs: where an agent reads how to use the library. */
+const GUIDE_LINE =
+  "ic-reactor: agent guide at node_modules/@ic-reactor/core/llms.txt"
+
+/**
+ * The options of {@link icReactor}. Every one is optional: with none, the
+ * plugin generates nothing and, under `vite dev`, only injects the local IC
+ * environment, for no canister of the app's.
+ */
 export interface IcReactorPluginOptions {
   /**
-   * Canister configurations.
-   * `name` is required for each canister.
-   */
-  canisters: CanisterConfig[]
-  /**
-   * Default output directory (relative to the Vite project root).
-   * Default: "src/declarations"
-   */
-  outDir?: string
-  /**
-   * Default client manager import path.
-   * Default: "../../clients"
-   */
-  clientManagerPath?: string
-  /**
-   * Default generated runtime target.
-   * Default: "react"
+   * The app's canisters, by name: the canister's name in the `icp` project,
+   * which is also the name the `ic_env` cookie carries its ID under.
+   *
+   * - `didFile`: the canister's Candid interface, relative to the Vite root.
+   *   The plugin runs `candid-core-cli gen` on it at the start of a build or
+   *   dev server and again each time the file changes, regenerating only the
+   *   canisters that name the file that changed. The generator names its
+   *   output after the file, so `didFile: "../backend/ledger.did"` writes `ledger.ts` (the
+   *   module: it exports `actor` and the type `Actor`) and
+   *   `ledger.envelope.json` into `outDir`. Canisters that name the same
+   *   `didFile` and `outDir` share that one module, which is generated once.
+   *   Different `.did` files that would write the same module are refused:
+   *   give one an `outDir` of its own. A canister without a `didFile`
+   *   generates nothing and is only named in the cookie.
+   * - `outDir`: where the generator writes, relative to the Vite root.
+   *   Default: `"src/canisters"`.
+   * - `canisterId`: a fixed ID for the cookie, which wins over the ID `icp`
+   *   reports for the canister.
+   *
+   * The generator is the `@candid-core/cli` the app has installed, run as a
+   * child process so that a failure on one `.did` stops that process and not
+   * the dev server.
    */
-  target?: CodegenTarget
+  canisters?: Record<
+    string,
+    { didFile?: string; outDir?: string; canisterId?: string }
+  >
   /**
-   * Automatically inject `ic_env` cookie for local development?
+   * Inject the local IC environment under `vite dev` and `vite preview`: set
+   * the `ic_env` cookie on each response and proxy `/api` to the network the
+   * `icp` CLI reports.
+   *
+   * Until `icp` reports a network and every configured canister has an ID
+   * (a configured `canisterId` counts), each page load asks `icp` again, so a
+   * deploy after the server started needs only a reload. Once detection is
+   * complete, page loads run no `icp` command, and a redeploy into a fresh
+   * network needs a restart. An `/api` proxy that the Vite config or another
+   * plugin sets is left alone.
+   *
+   * Never injected in mode `"test"` (Vitest's), where `icp` is not run at all.
+   *
    * Default: true
    */
   injectEnvironment?: boolean
@@ -50,445 +93,569 @@ export interface IcReactorPluginOptions {
    * Abort the Vite run when a canister fails to generate.
    *
    * Default: `true` under `vite build`, `false` under `vite dev`. A build that
-   * silently ships the bindings left over from the last successful run is worse
-   * than no build at all, while a dev server has to survive the broken
-   * intermediate states of a `.did` file being edited — there the failure is
-   * reported to the terminal and the browser error overlay instead.
+   * silently ships the bindings left over from the last successful run is
+   * worse than no build at all, while a dev server has to survive the broken
+   * intermediate states of a `.did` file being edited: there the failure is
+   * logged and shown in the browser's error overlay, and the server keeps
+   * serving.
    */
   failOnError?: boolean
 }
 
-export function icReactor(options: IcReactorPluginOptions): Plugin {
-  const {
-    canisters,
-    outDir = "src/declarations",
-    clientManagerPath = "../../clients",
-    target = "react",
-    injectEnvironment = true,
-    failOnError,
-  } = options
-
-  // Construct a partial CodegenConfig to pass to the pipeline
-  const globalConfig: Pick<
-    CodegenConfig,
-    "outDir" | "clientManagerPath" | "target"
-  > = {
-    outDir,
-    clientManagerPath,
-    target,
-  }
+/** A canister with a `.did` to generate from. */
+interface Generated {
+  name: string
+  didFile: string
+  outDir: string
+}
+
+/** A canister that did not generate, and why. */
+interface Failure {
+  canister: Generated
+  message: string
+}
+
+type PluginLog = Pick<Logger, "info" | "warn" | "error">
+
+/** What the hooks log through before Vite hands over its logger. */
+const consoleLog: PluginLog = {
+  info: (message) => console.log(message),
+  warn: (message) => console.warn(message),
+  error: (message) => console.error(message),
+}
+
+/**
+ * The Vite plugin for an app built on a candid-core generated module.
+ *
+ * It does two things:
+ *
+ * - **Generates the module.** When a build or the dev server starts, and
+ *   when a configured `.did` changes, it runs the app's `candid-core-cli gen`
+ *   on each `didFile` and leaves the module as the generator wrote it: no
+ *   wrapper files, hooks or reactors. The generator is WebAssembly, so it runs
+ *   in a child process (the running Node binary on the CLI's bin script, never
+ *   through a shell, killed after 60 seconds). A trap, a crash or a hang on a
+ *   bad `.did` then ends that process and not the dev server: under
+ *   `vite build` it fails the build with the CLI's own message, and under
+ *   `vite dev` it is logged and shown in the error overlay while the server
+ *   keeps serving. See {@link IcReactorPluginOptions.failOnError}.
+ * - **Injects the local IC environment.** Under `vite dev` and `vite preview`
+ *   it sets the `ic_env` cookie, which carries the replica's root key and the
+ *   canister IDs, and proxies `/api` to the local replica, so the app needs no
+ *   configuration to find them. It asks the `icp` CLI for both, and is off in
+ *   mode `"test"` (Vitest's), where `icp` is never run.
+ *
+ * The first thing it logs names where an agent reads how to use the library:
+ * `ic-reactor: agent guide at node_modules/@ic-reactor/core/llms.txt`.
+ *
+ * The plugin needs `@candid-core/cli`, at the exact release that pairs with
+ * the `@candid-core/schema` the generated modules import, installed in the
+ * app. It imports neither, and no `@ic-reactor` runtime package.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * export default defineConfig({
+ *   plugins: [
+ *     icReactor({
+ *       canisters: { ledger: { didFile: "../backend/ledger.did" } },
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export function icReactor(options: IcReactorPluginOptions = {}): Plugin {
+  const { canisters = {}, injectEnvironment = true, failOnError } = options
+  const names = Object.keys(canisters)
+
+  const configuredCanisterIds = Object.fromEntries(
+    names.flatMap((name) => {
+      const { canisterId } = canisters[name]
+      return canisterId ? [[name, canisterId]] : []
+    })
+  )
+
+  /** The canisters that have a `.did` to generate from. */
+  const generated: Generated[] = names.flatMap((name) => {
+    const { didFile, outDir = DEFAULT_OUT_DIR } = canisters[name]
+    return didFile === undefined ? [] : [{ name, didFile, outDir }]
+  })
 
   // Vite resolves relative project paths against the resolved `config.root`,
   // which only equals the process cwd when vite happens to be started from the
-  // project directory — not for `root: "frontend"`, and not when the root is
-  // passed positionally (`vite build apps/web`). Note `--config` on its own does
-  // NOT move the root; it only selects the config file.
-  // `configResolved` overwrites this before any hook that resolves a path runs;
-  // the cwd is only the pre-resolution default, which is also Vite's own
+  // project directory, not for `root: "frontend"` and not when the root is
+  // passed positionally (`vite build apps/web`). `configResolved` overwrites
+  // this before any hook that resolves a path runs; the cwd is only Vite's own
   // default root.
   let projectRoot = process.cwd()
 
   // `vite build` and `vite dev` want opposite failure behaviour, so remember
-  // which one we are in. Both `config` and `configResolved` carry the command;
-  // build is the safer default for the case where neither has run.
+  // which one we are in. Build is the safer default for the case where neither
+  // `config` nor `configResolved` has run.
   let command: ResolvedConfig["command"] = "build"
 
-  // Set once the dev server exists, so a `buildStart` failure in dev can reach
-  // the browser overlay too — in dev, `configureServer` runs before Vite calls
-  // `buildStart` on the plugin container.
+  let log: PluginLog = consoleLog
+  let announced = false
+
+  /**
+   * The local IC environment `vite dev` and `vite preview` inject. The
+   * `config` hook creates it when `injectEnvironment` is on.
+   */
+  let localEnvironment: LocalEnvironment | undefined
+
+  /** The options of the plugin's `/api` proxy, as Vite hands them over. */
+  const apiProxyOptions = new Set<ProxyOptions>()
+
+  // Set once the dev server exists. In dev, `configureServer` runs before Vite
+  // calls `buildStart`, so a startup failure can reach the overlay too.
   let devServer: ViteDevServer | null = null
 
-  const resolveDidPath = (didFile: string) =>
-    path.normalize(
-      path.isAbsolute(didFile) ? didFile : path.resolve(projectRoot, didFile)
-    )
-  const configuredCanisterIds = Object.fromEntries(
-    canisters
-      .filter((canister) => !!canister.canisterId)
-      .map((canister) => [canister.name, canister.canisterId as string])
-  )
+  // ── Generation ──────────────────────────────────────────────────────────
+
+  const didPath = (canister: Generated) =>
+    path.resolve(projectRoot, canister.didFile)
+  const relativeToRoot = (file: string) =>
+    path.relative(projectRoot, file) || "."
 
   /**
-   * Report a generation failure everywhere a developer might be looking.
-   *
-   * Terminal output scrolls away behind request logs and HMR chatter, so in dev
-   * the browser error overlay is the signal that actually gets noticed.
+   * The `.did` text each canister last generated from. A rebuild that finds
+   * the text unchanged skips the canister, which is every rebuild of
+   * `vite build --watch` that was not caused by a `.did`, and the second
+   * `buildStart` Vite 6 and later run for another environment.
    */
+  const generatedFrom = new Map<string, string>()
+
   /**
-   * The failures that are still unfixed, one per canister, kept so a browser
-   * that was not connected when one happened still gets the overlay.
+   * The failures not yet fixed, by canister name. Vite awaits `buildStart`
+   * before the HTTP server listens, so a failure at startup is sent to no
+   * browser at all; each browser that connects later is handed these.
+   */
+  const unfixed = new Map<string, Failure>()
+
+  // Generation runs one job after another. Two `buildStart`s (one per Vite 6+
+  // environment) or a save during a run would otherwise start two generator
+  // processes that write the same files.
+  let tail: Promise<unknown> = Promise.resolve()
+  const serially = <T>(job: () => Promise<T>): Promise<T> => {
+    const result = tail.then(job)
+    tail = result.catch(() => undefined)
+    return result
+  }
+
+  /** The `.did` files waiting for a run that has not started. See `onDidSaved`. */
+  const queued = new Set<string>()
+
+  // Aborted when the build or dev server ends (`closeBundle`), which kills
+  // the generator processes then running and drops the runs still queued. A
+  // generator that outlived its server would keep Node alive for up to its
+  // timeout, and after a restart (a `vite.config` edit) it would write the
+  // same outDir as the new server's first run. A fresh controller follows each
+  // abort, since the same plugin object serves a server that is started again.
+  let stopper = new AbortController()
+
+  const readDid = (canister: Generated): string | undefined => {
+    try {
+      return fs.readFileSync(didPath(canister), "utf-8")
+    } catch {
+      return undefined
+    }
+  }
+
+  /**
+   * Generate `wanted`, in one generator process for each output directory, and
+   * report what the generator said. Never rejects: an unexpected error fails
+   * the canisters, since a rejection from a watcher callback could end the dev
+   * server.
    *
-   * Vite awaits the plugin container's `buildStart` before the HTTP server
-   * starts listening, so a generation failure during `vite dev` startup is
-   * broadcast when there are no WebSocket clients at all and the payload is
-   * simply dropped. The terminal shows it; the overlay never appears — for
-   * precisely the failures a developer is most likely to hit.
+   * Resolves `undefined` when `signal` was aborted before it finished: the
+   * server it belonged to is gone, so nothing is recorded, logged or shown.
    *
-   * A success only proves that the canister which regenerated is fixed. This
-   * used to be one slot that any success emptied, so a canister that was still
-   * broken vanished from the overlay as soon as another canister regenerated
-   * and its reload reconnected every tab.
+   * @param force - Generate even a canister whose `.did` text is unchanged.
+   * @param signal - The `stopper` signal current when the run was asked for.
    */
-  const pendingFailures = new Map<string, { message: string; stack: string }>()
-
-  const reportFailure = (
-    server: ViteDevServer | null,
-    message: string,
-    cause?: unknown
-  ) => {
-    console.error(`[ic-reactor] ${message}`)
-
-    const err = {
-      message: `[ic-reactor] ${message}`,
-      stack: cause instanceof Error && cause.stack ? cause.stack : "",
-      plugin: PLUGIN_NAME,
-    }
+  const generateNow = async (
+    wanted: Generated[],
+    force: boolean,
+    signal: AbortSignal
+  ): Promise<Failure[] | undefined> => {
+    if (signal.aborted) return undefined
+    try {
+      const sources = new Map(
+        wanted.map((canister) => [canister.name, readDid(canister)])
+      )
+      const stale = wanted.filter(
+        ({ name }) =>
+          force ||
+          sources.get(name) === undefined ||
+          generatedFrom.get(name) !== sources.get(name)
+      )
+      if (stale.length === 0) return []
 
-    server?.ws.send({ type: "error", err })
-    return { message: err.message, stack: err.stack }
-  }
+      let cli: string
+      try {
+        cli = resolveCliBin(projectRoot)
+      } catch (error) {
+        return stale.map((canister) => ({ canister, message: describe(error) }))
+      }
 
-  // Keep at most one regeneration per canister in flight and collapse every save
-  // that arrives meanwhile into a single trailing rerun, so the last saved
-  // `.did` still wins without piling up concurrent runs.
-  //
-  // Scope, precisely: this covers the watcher path only. `buildStart` calls the
-  // pipeline directly and does not register here, so a save landing during the
-  // initial generation can still run concurrently with it. That is deliberate
-  // rather than an oversight -- since @ic-reactor/codegen generates into a
-  // staging directory and swaps atomically, concurrent runs for one canister no
-  // longer interleave inside a delete-then-write sequence; the loser is simply
-  // overwritten. What this buys is ordering and wasted work, not integrity.
-  //
-  // Note the coalesced promise resolves when the RUNNING pass finishes, not the
-  // trailing rerun, so `handleHotUpdate` can return before the newest `.did` has
-  // been written. The trailing run sends its own full-reload, so the browser
-  // still converges.
-  const inFlight = new Map<string, Promise<void>>()
-  const rerunQueued = new Set<string>()
-
-  const regenerate = (
-    canisterConfig: CanisterConfig,
-    server: ViteDevServer
-  ): Promise<void> => {
-    const { name } = canisterConfig
-    const running = inFlight.get(name)
-
-    if (running) {
-      rerunQueued.add(name)
-      return running
-    }
+      const result = await generate({
+        cli,
+        root: projectRoot,
+        timeoutMs: GENERATE_TIMEOUT_MS,
+        signal,
+        // Shown as it arrives: a run that takes long, or is killed at the
+        // timeout, would otherwise say nothing until it is over.
+        onStderr: (line, didFiles) => {
+          if (signal.aborted) return
+          log.warn(
+            `ic-reactor: candid-core-cli (${didFiles.map((file) => relativeToRoot(file)).join(", ")}): ${line}`
+          )
+        },
+        canisters: stale.map((canister) => ({
+          name: canister.name,
+          didFile: didPath(canister),
+          outDir: path.resolve(projectRoot, canister.outDir),
+        })),
+      })
 
-    const run = runCanisterPipeline({
-      canisterConfig,
-      projectRoot,
-      globalConfig,
-    })
-      .then((result) => {
-        if (result.success) {
-          // A later connection must not be handed a failure that has since been
-          // fixed.
-          pendingFailures.delete(name)
-          // Reload page to reflect new types/hooks
-          server.ws.send({ type: "full-reload" })
-        } else {
-          pendingFailures.set(
-            name,
-            reportFailure(
-              server,
-              `Regeneration failed for ${name}: ${result.error ?? "unknown error"}`
-            )
+      if (signal.aborted) return undefined
+
+      const failures: Failure[] = []
+      for (const outcome of result.outcomes) {
+        // The names of one outcome share a `.did`, so they succeed or fail
+        // together and are reported once.
+        const members = stale.filter(({ name }) => outcome.names.includes(name))
+        const names = members.map(({ name }) => name).join(", ")
+        if (outcome.status === "failed") {
+          for (const canister of members) {
+            generatedFrom.delete(canister.name)
+            failures.push({ canister, message: outcome.failure ?? "" })
+          }
+          continue
+        }
+        for (const { name } of members) {
+          const source = sources.get(name)
+          if (source !== undefined) generatedFrom.set(name, source)
+        }
+        if (outcome.status === "written" && outcome.module) {
+          log.info(
+            `ic-reactor: generated ${names} into ${relativeToRoot(outcome.module)}`
           )
         }
-      })
-      // A throw from the pipeline (a malformed `.did` makes the parser throw
-      // rather than return a failed result) would otherwise be an unhandled
-      // rejection: invisible in the browser and, depending on the Node version,
-      // fatal to the dev server.
-      .catch((error: unknown) => {
-        pendingFailures.set(
-          name,
-          reportFailure(
-            server,
-            `Regeneration failed for ${name}: ${describeError(error)}`,
-            error
+        for (const { kind, name: what, reason, via } of outcome.omitted) {
+          log.warn(
+            `ic-reactor: ${names}: omitted ${kind} ${what} (${reason}${via ? ` via ${via}` : ""})`
           )
-        )
-      })
-      .finally(() => {
-        inFlight.delete(name)
-        if (rerunQueued.delete(name)) {
-          void regenerate(canisterConfig, server)
         }
-      })
-
-    inFlight.set(name, run)
-    return run
+      }
+      return failures
+    } catch (error) {
+      if (signal.aborted) return undefined
+      return wanted.map((canister) => ({ canister, message: describe(error) }))
+    }
   }
 
-  const plugin: Plugin = {
-    name: PLUGIN_NAME,
-    enforce: "pre", // Run before other plugins
+  /**
+   * The error text for failed canisters. Canisters that failed for the same
+   * reason (no CLI installed, one crash) are listed under it once.
+   */
+  const describeFailures = (failures: Failure[]): string => {
+    const byMessage = new Map<string, string[]>()
+    for (const { canister, message } of failures) {
+      const label = `${canister.name} (${relativeToRoot(didPath(canister))})`
+      byMessage.set(message, [...(byMessage.get(message) ?? []), label])
+    }
+    return (
+      `ic-reactor: could not generate ${failures.length} of ${generated.length} canisters:\n` +
+      [...byMessage]
+        .map(
+          ([message, labels]) =>
+            `  - ${labels.join(", ")}: ${message.replace(/\n/g, "\n    ")}`
+        )
+        .join("\n")
+    )
+  }
 
-    config(userConfig, { command: viteCommand }) {
-      command = viteCommand
+  /**
+   * Report the outcome of a run that does not end the Vite run (a save, or a
+   * build with `failOnError` off): log a failure and put every unfixed one in
+   * the browser's error overlay. When a canister is fixed, the overlay is
+   * replaced by one that lists only the canisters still failing, or cleared
+   * once there are none.
+   */
+  const publish = (attempted: Generated[], failures: Failure[]): void => {
+    // Every attempted canister leaves `unfixed`, not just the first one found
+    // there: a save regenerates all the canisters that name the `.did`, and
+    // `some` would stop at the first, leaving the others listed in an overlay
+    // nothing clears.
+    let wasFailing = false
+    for (const { name } of attempted) {
+      if (unfixed.delete(name)) wasFailing = true
+    }
+    for (const failure of failures) unfixed.set(failure.canister.name, failure)
+    if (failures.length > 0) {
+      log.error(describeFailures(failures))
+      showOverlay()
+    } else if (wasFailing && unfixed.size > 0) {
+      // The open overlay still lists the canister that was just fixed.
+      showOverlay()
+    } else if (wasFailing) {
+      // Nothing may have changed on disk when a canister is fixed back to what
+      // it generated before, so the page has nothing else to reload it.
+      devServer?.ws.send({ type: "full-reload" })
+    }
+  }
 
-      if (viteCommand !== "serve" || !injectEnvironment) {
-        return {}
+  /**
+   * Put the unfixed failures in the error overlay: of the browser that just
+   * connected when the WebSocket hands it over (`ws.on("connection")` does),
+   * and of every browser otherwise. Vite's client clears the overlay on every
+   * hot update it applies, and nothing here sends it again, so the overlay can
+   * go while a canister is still broken. The terminal log keeps the error, and
+   * the replay on connection shows it after the next full reload.
+   */
+  const showOverlay = (client?: { send?: (data: string) => void }): void => {
+    if (unfixed.size === 0) return
+    const payload = {
+      type: "error" as const,
+      err: {
+        message: describeFailures([...unfixed.values()]),
+        stack: "",
+        plugin: PLUGIN_NAME,
+      },
+    }
+    if (typeof client?.send === "function") {
+      try {
+        client.send(JSON.stringify(payload))
+      } catch {
+        // A browser that is already gone has no use for the overlay, and a
+        // listener must not throw into the WebSocket server.
       }
+      return
+    }
+    devServer?.ws.send(payload)
+  }
 
-      // ── Local Development Proxy & Cookies ────────────────────────────────
+  /**
+   * A `.did` file was saved: regenerate the canisters that name it, and only
+   * those. Canisters with one interface share its file and its run. Saves that
+   * arrive while it runs collapse into one run after it, so the last saved
+   * file wins without runs piling up.
+   */
+  const onDidSaved = (file: string): void => {
+    const saved = path.normalize(file)
+    const affected = generated.filter((canister) => didPath(canister) === saved)
+    if (affected.length === 0 || queued.has(saved)) return
+    queued.add(saved)
+    log.info(
+      `ic-reactor: ${relativeToRoot(saved)} changed, regenerating ${affected.map(({ name }) => name).join(", ")}`
+    )
+    const { signal } = stopper
+    void serially(async () => {
+      queued.delete(saved)
+      const failures = await generateNow(affected, true, signal)
+      if (failures) publish(affected, failures)
+    })
+  }
 
-      // Always include internet_identity if not present (common need)
-      const canisterNames = canisters
-        .map((c) => c.name)
-        .filter((n): n is string => !!n)
-      if (!canisterNames.includes("internet_identity")) {
-        canisterNames.push("internet_identity")
+  /**
+   * A `.did` file was deleted: fail the canisters that name it, in the log and
+   * the overlay, until it comes back (an `add` regenerates them). The module
+   * generated from it is still on disk and would otherwise go on looking
+   * current. No generator runs, since there is nothing to read.
+   *
+   * It waits behind the run in flight, so that run cannot report the file as
+   * generated after this has reported it gone.
+   */
+  const onDidRemoved = (file: string): void => {
+    const removed = path.normalize(file)
+    const affected = generated.filter(
+      (canister) => didPath(canister) === removed
+    )
+    if (affected.length === 0) return
+    const { signal } = stopper
+    void serially(async () => {
+      try {
+        // Back already, and the run its `add` queued regenerates it.
+        if (signal.aborted || fs.existsSync(removed)) return
+        for (const { name } of affected) generatedFrom.delete(name)
+        publish(
+          affected,
+          affected.map((canister) => ({
+            canister,
+            message:
+              "the .did file was deleted; its module is not regenerated until the file comes back",
+          }))
+        )
+      } catch (error) {
+        // A listener must not throw into the watcher.
+        log.error(`ic-reactor: ${describe(error)}`)
       }
+    })
+  }
 
-      // `configResolved` has not run yet, so resolve the root the way Vite
-      // will. icp finds the project from the directory it starts in, and with
-      // `vite apps/web` or a `root` option that is not the process cwd.
-      const { environment: icEnv, diagnostics } = getIcEnvironmentInfo(
-        canisterNames,
-        path.resolve(userConfig.root ?? process.cwd())
-      )
-
-      if (!icEnv) {
-        // Failing detection used to be indistinguishable from success: no
-        // cookie was set, no warning was printed, and the app only broke much
-        // later on an undefined canister id. Stay quiet in env-only mode
-        // (no canisters configured), where there is nothing to inject anyway.
-        if (canisters.length > 0) {
-          console.warn(
-            `[ic-reactor] Could not detect the local IC environment, falling back to ${DEFAULT_LOCAL_REPLICA}. ` +
-              `Canister IDs and the root key will not be injected — is the local replica running? ` +
-              `Re-run with DEBUG=ic-reactor to see the \`icp\` output.`
-          )
-        }
-
-        for (const diagnostic of diagnostics) {
-          debugLog(diagnostic)
-        }
+  /** Log the guide line once, before anything else the plugin says. */
+  const announceGuide = (userConfig: UserConfig): void => {
+    if (announced) return
+    announced = true
+    if (userConfig.customLogger) {
+      userConfig.customLogger.info(GUIDE_LINE)
+    } else if (
+      !["silent", "error", "warn"].includes(userConfig.logLevel ?? "")
+    ) {
+      console.log(GUIDE_LINE)
+    }
+  }
 
-        const envOnlyCookie =
-          canisters.length === 0
-            ? buildIcEnvCookie(
-                {},
-                undefined,
-                "http://id.ai.localhost:8000/authorize"
-              )
-            : undefined
-
-        // Fallback: proxy /api to default local replica. In env-only mode,
-        // still provide the standard ICP CLI built-in local II URL.
-        return {
-          server: {
-            headers: envOnlyCookie
-              ? {
-                  "Set-Cookie": `ic_env=${envOnlyCookie}; Path=/; SameSite=Lax;`,
-                }
-              : undefined,
-            proxy: apiProxy(userConfig, DEFAULT_LOCAL_REPLICA),
-          },
-        }
-      }
+  const plugin: Plugin = {
+    name: PLUGIN_NAME,
+    enforce: "pre", // Run before other plugins
 
-      // The replica can be UP -- `icp network status` succeeds, so icEnv is
-      // truthy and the check above never fires -- while a configured canister
-      // has never been deployed. Every `icp canister status <name>` then fails
-      // and that id is simply absent, so the cookie goes out carrying a root key
-      // and no PUBLIC_CANISTER_ID for it. That is the same "indistinguishable
-      // from success until the app breaks on an undefined canister id" failure
-      // the branch above exists to prevent, and it is the more common one.
-      //
-      // Only configured canisters are reported: `internet_identity` is appended
-      // to canisterNames for convenience and is routinely not deployed.
-      // An explicitly configured `canisterId` counts as resolved: the cookie
-      // below merges configuredCanisterIds over the detected ones, so the app
-      // does receive a valid PUBLIC_CANISTER_ID. Warning on those told the user
-      // to deploy a canister whose id they had already supplied.
-      const missingCanisterIds = canisters
-        .map((canister) => canister.name)
-        .filter((name): name is string => !!name)
-        .filter(
-          (name) => !icEnv.canisterIds[name] && !configuredCanisterIds[name]
-        )
+    async config(userConfig, { command: viteCommand, mode }) {
+      announceGuide(userConfig)
+      command = viteCommand
 
-      if (missingCanisterIds.length > 0) {
-        const names = missingCanisterIds.map((name) => `"${name}"`).join(", ")
-        const it = missingCanisterIds.length === 1 ? "it" : "them"
-        console.warn(
-          `[ic-reactor] The local replica is running, but no canister ID could be resolved for ${names}. ` +
-            `Deploy ${it} (\`icp deploy\`) — until then the injected ic_env carries no PUBLIC_CANISTER_ID ` +
-            `for ${it} and the app will see an undefined canister id. ` +
-            `Re-run with DEBUG=ic-reactor to see the \`icp\` output.`
-        )
+      // Vitest runs the plugin with the `serve` command and mode `test`, and
+      // a test run has no use for a cookie or a proxy, or for asking `icp`
+      // about a network.
+      if (viteCommand !== "serve" || mode === "test" || !injectEnvironment) {
+        return {}
       }
 
-      for (const diagnostic of diagnostics) {
-        debugLog(diagnostic)
-      }
+      // ── Local Development Proxy & Cookies ────────────────────────────────
 
-      const cookieValue = buildIcEnvCookie(
-        {
-          ...icEnv.canisterIds,
-          ...configuredCanisterIds,
+      // The plugin's own `/api` entry, unless the Vite config has one.
+      const ownsApiProxy = !userConfig.server?.proxy?.["/api"]
+
+      const environment = createLocalEnvironment({
+        canisterNames: names,
+        configuredCanisterIds,
+        // `configResolved` has not run yet, so resolve the root the way Vite
+        // will. icp finds the project from the directory it starts in, and
+        // with `vite apps/web` or a `root` option that is not the process cwd.
+        projectRoot: path.resolve(userConfig.root ?? process.cwd()),
+        onDiagnostic: debugLog,
+        onUpdate: (previous, next) => {
+          for (const proxyOptions of apiProxyOptions) {
+            proxyOptions.target = next.proxyTarget
+          }
+          if (previous) {
+            // Only a proxy the plugin kept following moves with detection.
+            reportDetectionProgress(previous, next, apiProxyOptions.size > 0)
+          }
         },
-        icEnv.rootKey,
-        icEnv.internetIdentityProvider
-      )
+      })
+      localEnvironment = environment
+
+      const state = await environment.detect()
+      warnAboutIncompleteDetection(state, names.length > 0, ownsApiProxy)
 
       return {
         server: {
-          headers: {
-            "Set-Cookie": `ic_env=${cookieValue}; Path=/; SameSite=Lax;`,
-          },
-          proxy: apiProxy(userConfig, icEnv.proxyTarget),
+          // The cookie is not a static `server.headers` entry: the middleware
+          // that configureServer adds sets it per response, from the latest
+          // detection. See dev-environment.ts.
+          proxy: apiProxy(userConfig, state.proxyTarget, (proxyOptions) => {
+            // A plugin whose config hook runs after this one can proxy /api
+            // as well. Vite merges its entry over the one returned here and
+            // keeps this `configure`, so a target other than the one returned
+            // here is that plugin's, and it stays where that plugin put it.
+            if (proxyOptions.target !== state.proxyTarget) {
+              debugLog(
+                "Another plugin changed the target of the /api proxy, so the plugin leaves that proxy alone."
+              )
+              return
+            }
+            // Vite hands the proxy these options on every request, so a new
+            // target set here takes effect on the next one.
+            apiProxyOptions.add(proxyOptions)
+            proxyOptions.target =
+              environment.state?.proxyTarget ?? state.proxyTarget
+          }),
         },
       }
     },
 
     configResolved(config) {
-      // Everything the plugin resolves — `didFile`, `outDir`,
-      // `clientManagerPath` — is documented as relative to the project root, so
-      // it has to be Vite's resolved root and not wherever the process started.
+      // Everything the plugin resolves, `didFile` and `outDir`, is documented
+      // as relative to the project root, so it has to be Vite's resolved root
+      // and not wherever the process started.
       projectRoot = config.root
       command = config.command
+      log = config.logger
     },
 
     configureServer(server) {
       devServer = server
 
-      // Replay the unfixed failures described at pendingFailures to each client
-      // that connects. A canister leaves the replay once it regenerates.
-      // Guarded: the peer range spans several Vite majors and `ws.on` is not
-      // present on every one of them. Losing the replay is acceptable; throwing
-      // out of configureServer is not.
-      server.ws.on?.("connection", () => {
-        if (pendingFailures.size === 0) return
-        const failures = [...pendingFailures.values()]
-        server.ws.send({
-          type: "error",
-          err: {
-            message: failures.map((failure) => failure.message).join("\n"),
-            stack: failures
-              .map((failure) => failure.stack)
-              .filter(Boolean)
-              .join("\n"),
-            plugin: PLUGIN_NAME,
-          },
-        })
-      })
-
-      // Explicitly watch configured DID files so HMR works even when they are not in the module graph.
-      const didFiles = canisters.map((c) => resolveDidPath(c.didFile))
-      server.watcher.add(didFiles)
-    },
-
-    async buildStart() {
-      // ── Code Generation ──────────────────────────────────────────────────
-
-      console.log(
-        `[ic-reactor] Generating canister bindings for ${canisters.length} canisters...`
-      )
-
-      const outcomes = await Promise.allSettled(
-        canisters.map((canisterConfig) =>
-          runCanisterPipeline({
-            canisterConfig,
-            projectRoot,
-            globalConfig,
-          })
-        )
-      )
-
-      // Collect every failure before reporting one: a canister failing must not
-      // hide what the others did, and the error should name all of them so a CI
-      // log shows the whole picture in one go.
-      const failures = outcomes.flatMap((outcome, index) => {
-        const name = canisters[index]?.name ?? `canister #${index}`
-
-        if (outcome.status === "rejected") {
-          return [{ name, detail: `${name}: ${describeError(outcome.reason)}` }]
-        }
-        if (!outcome.value.success) {
-          return [
-            {
-              name,
-              detail: `${name}: ${outcome.value.error ?? "unknown error"}`,
-            },
-          ]
-        }
-        return []
-      })
-
-      if (failures.length === 0) {
-        return
-      }
-
-      const message =
-        `Failed to generate ${failures.length} of ${canisters.length} canisters:\n` +
-        failures.map(({ detail }) => `  - ${detail}`).join("\n")
-
-      // Previously every failure here was a `console.error` and nothing more,
-      // so `vite build` exited 0 and CI shipped whatever stale bindings were
-      // still on disk — bindings that no longer match the deployed canister.
-      if (failOnError ?? command === "build") {
-        this.error(`[ic-reactor] ${message}`)
+      // Added here rather than returned as a post hook, so it runs before
+      // Vite's own middlewares, which serve the page.
+      if (localEnvironment) {
+        server.middlewares.use(icEnvMiddleware(localEnvironment))
       }
 
-      reportFailure(devServer, message)
-
-      // One entry per canister, so fixing one of them removes only its own line
-      // from the replay.
-      for (const { name, detail } of failures) {
-        pendingFailures.set(name, {
-          message: `[ic-reactor] Failed to generate ${detail}`,
-          stack: "",
-        })
-      }
+      if (generated.length === 0) return
+
+      // Hand each browser that connects the failures not yet fixed. Guarded:
+      // the peer range spans several Vite majors and `ws.on` is not present on
+      // every one of them. Losing the replay is acceptable; throwing out of
+      // configureServer is not.
+      server.ws.on?.("connection", showOverlay)
+
+      // `.did` files are not in the module graph, so the watcher is told about
+      // them. Regenerate from its own events and not from `handleHotUpdate`,
+      // which Vite calls only for a file changed in place and only while HMR
+      // is on: a `.did` created after startup, or written again by a build
+      // tool or `git checkout`, arrives as an `add` event, and a deleted one
+      // as `unlink`.
+      server.watcher.add(generated.map(didPath))
+      server.watcher.on("change", onDidSaved)
+      server.watcher.on("add", onDidSaved)
+      server.watcher.on("unlink", onDidRemoved)
     },
 
-    handleHotUpdate({ file, server }) {
-      // ── Hot Reload on .did changes ───────────────────────────────────────
-      if (!file.endsWith(".did")) {
-        return
+    // `vite preview` resolves the config with the `serve` command too, and
+    // used to inherit the cookie from `server.headers`.
+    configurePreviewServer(server) {
+      if (localEnvironment) {
+        server.middlewares.use(icEnvMiddleware(localEnvironment))
       }
+    },
 
-      const changedPath = path.normalize(file)
-      // Every canister, not only the first match. Deployed instances of one
-      // canister, such as two ledgers, share a .did file. Stopping at the first
-      // match left the others on stale bindings, and the full reload hid that.
-      const affectedCanisters = canisters.filter(
-        (canister) => resolveDidPath(canister.didFile) === changedPath
-      )
+    async buildStart() {
+      if (generated.length === 0) return
 
-      if (affectedCanisters.length === 0) {
-        return
-      }
+      // `vite build --watch` rebuilds when a file it watches changes, and a
+      // `.did` file is never part of the module graph. Registered here, a save
+      // starts a rebuild, and the rebuild's buildStart regenerates.
+      for (const canister of generated) this.addWatchFile(didPath(canister))
 
-      console.log(
-        `[ic-reactor] .did file changed: ${affectedCanisters
-          .map((canister) => canister.name)
-          .join(", ")}. Regenerating...`
+      const { signal } = stopper
+      const failures = await serially(() =>
+        generateNow(generated, false, signal)
       )
+      if (!failures) return
+      if (failures.length > 0 && (failOnError ?? command === "build")) {
+        // A build that exits 0 would ship whatever stale bindings are still on
+        // disk, which no longer match the canister.
+        this.error(describeFailures(failures))
+      }
+      publish(generated, failures)
+    },
 
-      // Returned so Vite waits for the write to finish before applying the
-      // update; it resolves to `undefined`, which leaves the affected module
-      // list untouched.
-      return Promise.all(
-        affectedCanisters.map((canister) => regenerate(canister, server))
-      ).then(() => undefined)
+    // The end of a build, and the close of a dev server, which Vite reports
+    // here once for each of its environments.
+    closeBundle() {
+      stopper.abort()
+      stopper = new AbortController()
     },
   }
 
   return plugin
 }
 
-/** One readable line for whatever the pipeline threw. */
-function describeError(error: unknown): string {
+/** One readable line for whatever was thrown. */
+function describe(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
@@ -501,8 +668,16 @@ function describeError(error: unknown): string {
  * pointed `/api` at icp-cli's port 8000 got 4943 instead, and nothing reported
  * the swap. Vite's merge skips an undefined value, so returning nothing leaves
  * the user's entry in place.
+ *
+ * `configure` receives the options object Vite builds the proxy from. Every
+ * supported Vite major copies it for each request, so the target can follow
+ * detection while the server runs.
  */
-function apiProxy(userConfig: UserConfig, target: string) {
+function apiProxy(
+  userConfig: UserConfig,
+  target: string,
+  configure: (options: ProxyOptions) => void
+): Record<string, ProxyOptions> | undefined {
   if (userConfig.server?.proxy?.["/api"]) {
     debugLog(
       `The Vite config already proxies /api, so the plugin keeps that proxy instead of sending /api to ${target}.`
@@ -510,7 +685,101 @@ function apiProxy(userConfig: UserConfig, target: string) {
     return undefined
   }
 
-  return { "/api": { target, changeOrigin: true } }
+  return {
+    "/api": {
+      target,
+      changeOrigin: true,
+      configure: (_proxy, options) => configure(options),
+    },
+  }
+}
+
+/** `"a"`, or `"a", "b"`: canister names as the warnings quote them. */
+function quoteNames(names: string[]): string {
+  return names.map((name) => `"${name}"`).join(", ")
+}
+
+/**
+ * Warn at startup when detection is incomplete, and say what the plugin does
+ * about it: it asks `icp` again on each page load until detection completes.
+ *
+ * Failing detection used to be indistinguishable from success: no cookie was
+ * set, no warning was printed, and the app only broke later on an undefined
+ * canister id.
+ */
+function warnAboutIncompleteDetection(
+  state: LocalEnvironmentState,
+  hasCanisters: boolean,
+  ownsApiProxy: boolean
+): void {
+  if (!state.environment) {
+    // Env-only mode (no canisters configured) has nothing to inject.
+    if (!hasCanisters) return
+    const proxyNote = ownsApiProxy
+      ? ` and /api goes to ${state.proxyTarget} for now`
+      : ""
+    console.warn(
+      `[ic-reactor] Could not detect the local IC environment, so no ic_env cookie is set${proxyNote}. ` +
+        `Is the local network running? The plugin asks \`icp\` again on each page load until it answers` +
+        `${ownsApiProxy ? ", then sends /api to the network it reports" : ""}: start the network ` +
+        `(\`icp network start\`) and reload the page. Re-run with DEBUG=ic-reactor to see the \`icp\` output.`
+    )
+    return
+  }
+
+  // The network can be up while a configured canister has never been
+  // deployed. Every `icp canister status <name>` then fails and that id is
+  // absent, so the cookie carries a root key and no PUBLIC_CANISTER_ID for it,
+  // which is the same silent failure. Only configured canisters count, and one
+  // with a configured `canisterId` is resolved.
+  const missing = state.missingCanisterIds
+  if (missing.length > 0) {
+    const it = missing.length === 1 ? "it" : "them"
+    console.warn(
+      `[ic-reactor] The local replica is running, but no canister ID could be resolved for ${quoteNames(missing)}. ` +
+        `Until one is, the ic_env cookie carries no PUBLIC_CANISTER_ID for ${it} and the app will see an ` +
+        `undefined canister id. Deploy ${it} (\`icp deploy\`) and reload the page: the plugin asks \`icp\` ` +
+        `again on each page load until every configured canister has an ID. ` +
+        `Re-run with DEBUG=ic-reactor to see the \`icp\` output.`
+    )
+  }
+}
+
+/**
+ * Report what a detection after startup found that the one before had not.
+ *
+ * @param followsApiProxy - Whether the `/api` proxy moves with detection. It
+ * does not when the Vite config or another plugin set its target.
+ */
+function reportDetectionProgress(
+  previous: LocalEnvironmentState,
+  next: LocalEnvironmentState,
+  followsApiProxy: boolean
+): void {
+  if (!previous.environment && next.environment) {
+    console.log(
+      `[ic-reactor] Detected the local IC network: the ic_env cookie now carries its root key` +
+        (followsApiProxy ? ` and /api goes to ${next.proxyTarget}.` : ".")
+    )
+  }
+
+  const resolved = previous.missingCanisterIds.filter(
+    (name) => !next.missingCanisterIds.includes(name)
+  )
+  if (next.environment && resolved.length > 0) {
+    console.log(
+      `[ic-reactor] The ic_env cookie now carries the canister ID${
+        resolved.length === 1 ? "" : "s"
+      } for ${quoteNames(resolved)}.`
+    )
+  }
+
+  if (next.complete && !previous.complete) {
+    console.log(
+      "[ic-reactor] Every configured canister has an ID, so page loads no longer run `icp`. " +
+        "Restart the dev server after redeploying into a fresh network."
+    )
+  }
 }
 
 /**